overvy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overvy

Manage issues on a kanban board. Issues are sourced from connected GitHub repositories.

在看板上管理任务，任务来源于已关联的GitHub仓库。

API Configuration

API配置

Base URL:

https://app.overvy.com/api/v1

(override with

OVERVY_API_URL

env var)

Auth:
```
Authorization: Bearer $OVERVY_API_KEY
```

At the start of any workflow, verify the API key is set:

bash

test -n "$OVERVY_API_KEY" || echo "ERROR: OVERVY_API_KEY is not set"

OVERVY_API_KEY

is not set, stop and tell the user to set it.

基础URL：
```
https://app.overvy.com/api/v1
```
（可通过
```
OVERVY_API_URL
```
环境变量覆盖）
认证方式：
```
Authorization: Bearer $OVERVY_API_KEY
```

在任何工作流开始前，需验证API密钥已配置：

bash

test -n "$OVERVY_API_KEY" || echo "ERROR: OVERVY_API_KEY is not set"

如果未配置

OVERVY_API_KEY

，请停止操作并告知用户进行配置。

Key Details

关键说明

Only board issues are accessible. Backlog issues are not exposed.
Lane types:
```
ready
```
(to do),
```
progress
```
(active),
```
review
```
(in review),
```
done
```
(complete).
Each issue has
```
projectRef
```
(
```
owner/repo
```
) and
```
externalNumber
```
(GitHub issue number).

仅可访问看板中的任务，待办任务不对外暴露。
泳道类型：
```
ready
```
（待处理）、
```
progress
```
（处理中）、
```
review
```
（审核中）、
```
done
```
（已完成）。
每个任务包含
```
projectRef
```
（
```
所有者/仓库名
```
）和
```
externalNumber
```
（GitHub任务编号）。

API Operations

API操作

List Workspaces

列出工作区

bash

curl -s -f "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/workspaces" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json"

Returns: JSON array of workspaces, each with

id

name

, and

lanes

(array of

id

label

sortOrder

type

bash

curl -s -f "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/workspaces" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json"

返回结果：工作区的JSON数组，每个工作区包含

id

、

name

和

lanes

（包含

id

、

label

、

sortOrder

、

type

的数组）。

List Issues

列出任务

bash

curl -s -f "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues?lane=LANE&ai=AI" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json"

Query parameters (all optional):

```
workspace
```
-- workspace UUID, defaults to first workspace
```
lane
```
-- filter by lane:
```
ready
```
,
```
progress
```
,
```
review
```
,
```
done
```
```
ai
```
-- filter by AI-created issues:
```
true
```
or
```
false
```

Omit query parameters you don't need. Returns: JSON array of issues, each with

id

title

state

ai

provider

projectRef

externalNumber

assignees

lane

(

id

label

type

sortOrder

bash

curl -s -f "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues?lane=LANE&ai=AI" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json"

查询参数（均为可选）：

```
workspace
```
-- 工作区UUID，默认使用第一个工作区
```
lane
```
-- 按泳道过滤：
```
ready
```
、
```
progress
```
、
```
review
```
、
```
done
```
```
ai
```
-- 按AI生成的任务过滤：
```
true
```
或
```
false
```

可省略不需要的查询参数。返回结果：任务的JSON数组，每个任务包含

id

、

title

、

state

、

ai

、

provider

、

projectRef

、

externalNumber

、

assignees

、

lane

（包含

id

、

label

、

type

）、

sortOrder

。

Move Issue

移动任务

bash

curl -s -f -X PATCH "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues/ISSUE_ID/move" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lane": "TARGET_LANE"}'

Replace

ISSUE_ID

with the issue UUID and

TARGET_LANE

with one of:

ready

progress

review

done

bash

curl -s -f -X PATCH "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues/ISSUE_ID/move" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lane": "TARGET_LANE"}'

将

ISSUE_ID

替换为任务的UUID，

TARGET_LANE

替换为以下值之一：

ready

、

progress

、

review

、

done

。

Error Handling

错误处理

All curl commands use
```
-f
```
to fail on HTTP errors.
If a command fails, check the HTTP status by running without
```
-f
```
and adding
```
-w "\n%{http_code}"
```
.
Common errors: 401 (bad API key), 404 (invalid issue ID or workspace), 422 (invalid lane).

所有curl命令使用
```
-f
```
参数，在HTTP错误时终止。
如果命令执行失败，可去掉
```
-f
```
参数并添加
```
-w "\n%{http_code}"
```
来查看HTTP状态码。
常见错误：401（API密钥无效）、404（任务ID或工作区无效）、422（泳道参数无效）。

Workflow: List AI Tickets

工作流：列出AI工单

List AI-created tickets in the "ready" lane so the user can pick one to work on.

Run:

bash

curl -s -f "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues?lane=ready&ai=true" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json"

If the response is an empty array, tell the user there are no AI-ready tickets.
Present results as a numbered list in this format:

AI-ready tickets:

1. <title> (<projectRef>#<externalNumber>) -- id: <id>
2. <title> (<projectRef>#<externalNumber>) -- id: <id>
...

Say "work on ticket <number>" to start, or "work on any ticket" to pick the first one.

列出“ready”泳道中AI生成的工单，供用户选择处理。

执行以下命令：

bash

curl -s -f "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues?lane=ready&ai=true" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json"

如果响应为空数组，告知用户暂无AI待处理工单。
按以下编号列表格式展示结果：

AI待处理工单：

1. <标题> (<projectRef>#<externalNumber>) -- ID: <id>
2. <标题> (<projectRef>#<externalNumber>) -- ID: <id>
...

请说“处理工单 <编号>”来开始，或“处理任意工单”选择第一个工单。

Workflow: Work on Ticket

工作流：处理工单

End-to-end flow: pick a ticket, implement it, create a PR, update the board.

Prerequisites:

gh

CLI authenticated with GitHub. Working directory is the repo matching the ticket's

projectRef

端到端流程：选择工单、开发实现、创建PR、更新看板。

前提条件：

gh

CLI已通过GitHub认证，工作目录与工单的

projectRef

匹配。

1. Select the ticket

1. 选择工单

User gave a number from the list output -- use that ticket's
```
id
```
,
```
projectRef
```
,
```
externalNumber
```
.
User said "work on any ticket" -- list issues with
```
lane=ready&ai=true
```
and pick the first result.
No tickets available -- tell the user and stop.

Store:

issueId

projectRef

externalNumber

title

用户提供了列表中的编号 -- 使用对应工单的
```
id
```
、
```
projectRef
```
、
```
externalNumber
```
。
用户说“处理任意工单” -- 列出
```
lane=ready&ai=true
```
的任务，选择第一个结果。
无可用工单 -- 告知用户并终止流程。

存储以下信息：

issueId

、

projectRef

、

externalNumber

、

title

。

2. Move to in progress

2. 移动到“处理中”泳道

bash

curl -s -f -X PATCH "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues/$ISSUE_ID/move" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lane": "progress"}'

This is mandatory -- always move before starting work.

bash

curl -s -f -X PATCH "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues/$ISSUE_ID/move" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lane": "progress"}'

此步骤为必填项 -- 开始工作前必须移动工单。

3. Research the issue

3. 调研任务详情

bash

gh issue view <externalNumber> --repo <projectRef>

Read the full issue body, comments, and labels. Understand what needs to be done before writing code.

bash

gh issue view <externalNumber> --repo <projectRef>

阅读完整的任务描述、评论和标签，在编写代码前明确需求。

4. Create a working branch

4. 创建工作分支

bash

git checkout -b <prefix>/<externalNumber>-<short-description>

Use

fix/

for bugs,

feat/

for features,

chore/

for maintenance. Example:

fix/42-handle-null-response

bash

git checkout -b <前缀>/<externalNumber>-<简短描述>

修复Bug使用

fix/

，新增功能使用

feat/

，维护任务使用

chore/

。示例：

fix/42-handle-null-response

。

5. Implement the changes

5. 开发实现变更

Follow existing codebase patterns. Run tests if available.

遵循现有代码库的规范，如有测试请运行测试用例。

6. Create a pull request

6. 创建Pull Request

bash

git push -u origin HEAD
gh pr create --title "<title>" --body "$(cat <<'EOF'

bash

git push -u origin HEAD
gh pr create --title "<title>" --body "$(cat <<'EOF'

Summary

摘要

<1-3 bullet points explaining what changed and why>

Closes <projectRef>#<externalNumber> EOF )"


- PR title should match or closely reflect the issue title.
- PR body must include `Closes <projectRef>#<externalNumber>` (full `owner/repo#N` format).

<1-3个要点说明变更内容及原因>

Closes <projectRef>#<externalNumber> EOF )"


- PR标题应与工单标题一致或高度关联。
- PR描述中必须包含`Closes <projectRef>#<externalNumber>`（完整格式为`所有者/仓库名#编号`）。

7. Move to in review

7. 移动到“审核中”泳道

bash

curl -s -f -X PATCH "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues/$ISSUE_ID/move" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lane": "review"}'

This is mandatory -- always move after the PR is created.

bash

curl -s -f -X PATCH "${OVERVY_API_URL:-https://app.overvy.com/api/v1}/issues/$ISSUE_ID/move" \
  -H "Authorization: Bearer $OVERVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lane": "review"}'

此步骤为必填项 -- 创建PR后必须移动工单。

8. Report

8. 结果反馈

Done. Worked on: <title> (<projectRef>#<externalNumber>)
PR: <pr-url>
Board: moved to "In Review"

已完成。处理任务：<title> (<projectRef>#<externalNumber>)
PR地址：<pr-url>
看板状态：已移动至“审核中”