zentao-api
by catouse
调用禅道（ZenTao）RESTful API v2.0 完成用户请求，包括查询项目、执行、需求、Bug、任务、测试用例等数据，以及创建、编辑、删除等写操作。当用户提到禅道、zentao、查询项目进展、获取Bug列表、更新需求状态、创建任务等项目管理相关操作时使用本技能。
安装
claude skill add --url github.com/openclaw/skills/tree/main/skills/catouse/zentao-api文档
禅道 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）
脚本行为：
- 若缓存文件存在，自动补全缺失的
ZENTAO_URL、ZENTAO_TOKEN和ZENTAO_ACCOUNT - 缓存中 URL 与账号均匹配时直接复用 token（token 永久有效，无需密码）
- URL 或账号变更、缓存不存在时，调用登录 API 获取新 token，并将
token、url、account写入缓存
脚本输出三行 KEY=VALUE，使用 eval 一次性设置所有变量：
bash
eval "$(bash scripts/get-token.sh)"
# 执行后可直接使用 $ZENTAO_URL、$ZENTAO_TOKEN、$ZENTAO_ACCOUNT
后续所有请求的 Header 中携带：
code
token: $ZENTAO_TOKEN
执行 API 调用的步骤
- 运行
eval "$(bash scripts/get-token.sh)"获取ZENTAO_URL、ZENTAO_TOKEN、ZENTAO_ACCOUNT（自动处理缓存，无需每次登录；仍缺失时提示用户） - 根据用户意图选择正确的 API 端点（参见 api-reference.md）
- 若为 PUT 操作且用户未提供全部字段，先调用对应 GET 详情接口取回当前数据，再将用户指定的字段覆盖进去
- 构造请求（方法、URL、Header、Body）并向用户确认写操作内容
- 执行请求，解析响应
- 以清晰易读的格式向用户展示结果
常用操作示例
获取所有正在进行的执行（迭代/Sprint）
执行（execution）属于某个项目，需先确定项目 ID，或遍历所有项目：
bash
# 先获取进行中的项目
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 列表
bash
curl -s "$ZENTAO_URL/api.php/v2/products/{productID}/bugs" -H "token: $ZENTAO_TOKEN"
修改 Bug
bash
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
bash
curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}/resolve" \
-H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" -d '{}'
创建需求
bash
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"}'
完成任务
bash
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 |
注意事项
- URL 中的数字 ID（如
/bugs/1）需替换为实际 ID - 若不知道 ID，先调用列表接口获取，再操作具体条目
- PUT 接口需提供所有相关字段：禅道的 PUT API 通常要求请求体包含该资源的所有必填字段，而不仅仅是要修改的字段。若用户只指定了部分字段，必须先调用对应的 GET 详情接口获取当前完整数据，再将用户修改的字段覆盖进去，最后一并提交
- 为避免误操作，写操作前向用户确认操作内容，如果用户明确要求不用确认则直接执行
- 响应为 401 表示 token 已被手动吊销，执行
rm ~/.zentao-token.json清除缓存后重新运行 browseType常用值：all（全部）、doing（进行中）、closed（已关闭）
完整 API 参考
详细的端点列表和请求参数见 api-reference.md。
备用资源
- 禅道 API 2.0 官方文档： https://www.zentao.net/book/api/2309.html
- 如果 2.0 的 API 无法满足要求可以参考 1.0 的 API 文档： https://www.zentao.net/book/api/1397.html