禅道 API v2.0

配置

优先级从高到低：

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 一次性设置所有变量：

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）
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"}'

意图识别规则

注意事项

• 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