禅道 API v2.0

---

name: zentao-api

description: 调用禅道（ZenTao）RESTful API v2.0 完成用户请求，包括查询项目、执行、需求、Bug、任务、测试用例等数据，以及创建、编辑、删除等写操作。当用户提到禅道、zentao、查询项目进展、获取Bug列表、更新需求状态、创建任务等项目管理相关操作时使用本技能。

---

# 禅道 API v2.0

配置

优先级从高到低：

| 变量 | 说明 |

|------|------|

| `ZENTAO_URL` | 服务器地址，如 `http://zentao.example.com` |

| `ZENTAO_TOKEN` | 直接指定 token，跳过登录和缓存（最高优先级），仍然需要提供禅道服务器地址 |

| `ZENTAO_ACCOUNT` | 登录账号，当有 ZENTAO_TOKEN 时，账号是可选的，但如果提供账号可以更好的回答与当前用户相关的问题。 |

| `ZENTAO_PASSWORD` | 登录密码，当有 ZENTAO_TOKEN 时，无需提供密码 |

**`ZENTAO_URL`、`ZENTAO_TOKEN` 和 `ZENTAO_ACCOUNT` 会在首次登录后写入 `~/.zentao-token.json`，后续调用无需重复设置**。

若必要变量缺失，提示用户并给出 `export` 命令。如果用户直接提供了服务器、账号和密码，则直接使用，但同时告知用户尽量设置为环境变量。

认证流程

所有业务 API 均需在 Header 携带 `token`。通过运行脚本 `scripts/get-token.sh` 自动获取禅道 URL、token 和用户名，避免每次重复登录。

脚本依赖：`curl`、`node`（Node.js）

脚本行为：

脚本输出三行 `KEY=VALUE`，使用 `eval` 一次性设置所有变量：

eval "$(bash scripts/get-token.sh)"
# 执行后可直接使用 $ZENTAO_URL、$ZENTAO_TOKEN、$ZENTAO_ACCOUNT

后续所有请求的 Header 中携带：

token: $ZENTAO_TOKEN

执行 API 调用的步骤

1. 运行 `eval "$(bash scripts/get-token.sh)"` 获取 `ZENTAO_URL`、`ZENTAO_TOKEN`、`ZENTAO_ACCOUNT`（自动处理缓存，无需每次登录；仍缺失时提示用户）

2. 根据用户意图选择正确的 API 端点（参见 [api-reference.md](api-reference.md)）

3. 若为 PUT 操作且用户未提供全部字段，先调用对应 GET 详情接口取回当前数据，再将用户指定的字段覆盖进去

4. 构造请求（方法、URL、Header、Body）并向用户确认写操作内容

5. 执行请求，解析响应

6. 以清晰易读的格式向用户展示结果

常用操作示例

获取所有正在进行的执行（迭代/Sprint）

执行（execution）属于某个项目，需先确定项目 ID，或遍历所有项目：

# 先获取进行中的项目
curl -s "$ZENTAO_URL/api.php/v2/projects?browseType=doing" -H "token: $ZENTAO_TOKEN"

# 再获取该项目的执行列表（将 {projectID} 替换为实际ID）
curl -s "$ZENTAO_URL/api.php/v2/projects/{projectID}/executions" -H "token: $ZENTAO_TOKEN"

获取产品的 Bug 列表

curl -s "$ZENTAO_URL/api.php/v2/products/{productID}/bugs" -H "token: $ZENTAO_TOKEN"

修改 Bug

curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}" \
  -H "token: $ZENTAO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "新标题", "severity": 2, "pri": 2}'

解决 Bug

curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}/resolve" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" -d '{}'

创建需求

curl -s -X POST "$ZENTAO_URL/api.php/v2/stories" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "需求标题", "assignedTo": "admin"}'

完成任务

curl -s -X PUT "$ZENTAO_URL/api.php/v2/tasks/{taskID}/finish" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"consumed": 2, "assignedTo": "admin", "finishedDate": "2026-03-18"}'

意图识别规则

| 用户意图关键词 | 对应操作 |

|--------------|---------|

| 正在进行的执行/迭代/Sprint | GET projects?browseType=doing + GET projects/{id}/executions |

| 获取所有产品/项目 | GET /products 或 GET /projects |

| 某产品/项目的 Bug | GET /products/{id}/bugs 或 /projects/{id}/bugs |

| 更新/修改 Bug | PUT /bugs/{id} |

| 解决 Bug | PUT /bugs/{id}/resolve |

| 关闭需求 | PUT /stories/{id}/close |

| 创建任务 | POST /tasks |

| 完成任务 | PUT /tasks/{id}/finish |

| 获取用户列表 | GET /users |

注意事项

完整 API 参考

详细的端点列表和请求参数见 [api-reference.md](api-reference.md)。

备用资源