Zentao Api

禅道 API v2.0

配置

优先级从高到低：

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

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

认证流程

所有业务 API 需在 Header 携带 token。运行 scripts/get-token.sh 自动获取：

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

脚本依赖：curl、node

后续所有请求 Header 携带：token: $ZENTAO_TOKEN

执行 API 调用的步骤

1. 运行 eval "$(bash scripts/get-token.sh)" 获取凭证（自动处理缓存；仍缺失时提示用户） 2. 根据用户意图选择正确的 API 端点（参见 api-reference.md） 3. 若为 PUT 编辑操作且用户未提供全部必填字段，先调用对应 GET 详情接口取回当前数据，再将用户指定的字段覆盖进去 4. 构造请求（方法、URL、Header、Body）并向用户确认写操作内容 5. 执行请求，解析响应 6. 以清晰易读的格式向用户展示结果

模块总览

API 基础路径：$ZENTAO_URL/api.php/v2

CRUD = 创建(POST) + 读取(GET) + 更新(PUT) + 删除(DELETE)；CUD = 无独立全局列表接口

分页与筛选

所有列表接口支持统一的查询参数：

筛选参数名不一致：Program 列表、Execution 全局列表、Task 列表用 status，其余用 browseType。

常用操作示例

获取进行中的项目及其执行

curl -s "$ZENTAO_URL/api.php/v2/projects?browseType=doing&recPerPage=100" -H "token: $ZENTAO_TOKEN"
curl -s "$ZENTAO_URL/api.php/v2/projects/{projectID}/executions?browseType=doing" -H "token: $ZENTAO_TOKEN"

创建需求（必填：productID, title）

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

创建业务需求（Epic）

curl -s -X POST "$ZENTAO_URL/api.php/v2/epics" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "业务需求标题", "grade": 1, "pri": 3, "reviewer": ["admin"]}'

创建用户需求（Requirement）

curl -s -X POST "$ZENTAO_URL/api.php/v2/requirements" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "用户需求标题", "parent": 1001, "grade": 1, "pri": 3, "reviewer": ["admin"]}'

创建 Bug（必填：productID, title, openedBuild）

curl -s -X POST "$ZENTAO_URL/api.php/v2/bugs" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "Bug标题", "openedBuild": ["trunk"], "severity": 2, "type": "codeerror"}'

解决 Bug（必填：resolution）

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

创建任务（必填：name, executionID）

curl -s -X POST "$ZENTAO_URL/api.php/v2/tasks" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"executionID": 1, "name": "任务名", "type": "devel", "assignedTo": "admin", "estimate": 4}'

完成任务（必填：currentConsumed, realStarted, finishedDate）

curl -s -X PUT "$ZENTAO_URL/api.php/v2/tasks/{taskID}/finish" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"currentConsumed": 4, "realStarted": "2026-03-25", "finishedDate": "2026-03-25"}'

关闭需求（必填：closedReason）

curl -s -X PUT "$ZENTAO_URL/api.php/v2/stories/{storyID}/close" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"closedReason": "done"}'

常用枚举值速查

意图识别规则

注意事项

• URL 中的 {id} 需替换为实际 ID；不知道 ID 时先调列表接口获取
• 创建 Epic / Requirement / Story 时，建议始终显式传 `grade`，不要依赖接口默认值。 已有用户反馈某些禅道实例在未传 grade 时会把需求层级写成 0，导致界面中 BR / UR / SR 标签显示异常。
• PUT 编辑接口：先 GET 详情获取当前完整数据，再将用户修改的字段覆盖进去一并提交
• 状态流转操作 (resolve/close/activate/start/finish/change) 通常有独立的必填字段，不需要先 GET 详情
• 写操作前向用户确认，用户明确要求不确认则直接执行
• 401 响应表示 token 已失效，执行 rm ~/.zentao-token.json 清除缓存后重新运行
• 字段名不一致注意：POST builds 用 executionID，PUT builds 用 execution；PUT testcases 的模块字段为 moudule（规范中的拼写）

完整 API 参考

详细的端点列表、必填/可选字段、枚举值和查询参数见 api-reference.md。

备用资源

• 禅道 API 2.0 官方文档：https://www.zentao.net/book/api/2309.html
• 1.0 API 文档（备用）：https://www.zentao.net/book/api/1397.html

禅道 API v2.0 端点参考

基础路径：{ZENTAO_URL}/api.php/v2 认证方式：所有接口（除登录外）需在 Header 携带 token: <token值> 写操作需额外携带 Content-Type: application/json

字段标注说明：粗体 = 必填，普通 = 可选

---

认证（Token）

请求体：account(string), password(string) 响应：{"status":"success","token":"..."}

---

用户（User）

POST 创建：account(string), realname(string), password(string)

PUT 修改：realname, dept(int), join(date), group(string[]), email, visions(string[] rnd|lite), mobile, weixin, password

GET 列表参数：browseType(inside|outside), orderBy(id|realname|account+_asc/_desc), recPerPage, pageID

---

项目集（Program）

POST/PUT：name(string), begin(date), end(date), PM(string), desc(string)

GET 列表参数：status(all|unclosed|wait|doing|suspended|delayed|closed), orderBy(id|name|begin|end+_asc/_desc), recPerPage, pageID

---

产品（Product）

产品关联资源列表：

POST/PUT：name(string), program(int), line(int), type(normal|branch|platform), PO(string), reviewer(string[]), desc(string[]), QD(string), RD(string), acl(open|private)

GET 列表参数：browseType(all|noclosed|closed), orderBy(id|title|begin|end+_asc/_desc), recPerPage, pageID

---

项目（Project）

项目关联资源列表：

POST/PUT：name(string), model(scrum|waterfall|kanban|agileplus|waterfallplus), begin(date), end(date), workflowGroup(int, 付费版功能开源版可不填), products(string[]), parent(int), PM(string)

GET /projects 参数：browseType(all|undone|wait|doing，默认undone), orderBy(id|name|begin|end+_asc/_desc), recPerPage, pageID

GET /programs/{id}/projects 参数：同上

GET /projects/{id}/executions 参数：browseType(all|undone|wait|doing，默认undone), orderBy(rawID|nameCol|begin|end+_asc/_desc), recPerPage, pageID

---

执行（Execution / Sprint）

执行关联资源列表：

POST 创建：project(int), name(string), begin(date), end(date), lifetime(short|long|ops), days(int), products(string[]), plans(string[]), PO(string), QD(string), PM(string), RD(string), acl(open|private)

PUT 修改：同上但 project 变为可选

GET /executions 参数：status(all|undone|wait|doing，默认undone), orderBy(rawID|nameCol|begin|end+_asc/_desc), recPerPage, pageID

---

需求（Story）

列表通过父资源获取：/products/{id}/stories, /projects/{id}/stories, /executions/{id}/stories

POST 创建：productID(int), title(string), grade(int 需求层级，建议显式传入), pri(int, 默认3), module(int), parent(int), estimate(float), spec(string 需求描述), category(feature|interface|performance|safe|experience|improve|other), source(customer|user|po|market|service|operation|support|competitor|partner|dev|tester|bug|forum|other), verify(string 验收标准), assignedTo(string), reviewer(string[]), project(int), execution(int)

PUT 修改：title(string)，其余字段可选

PUT change 变更：reviewer(string[]), title(string), spec(string), verify(string)

PUT close 关闭：closedReason(done|subdivided|duplicate|postponed|willnotdo|cancel|bydesign), comment(string)

PUT activate 激活：assignedTo(string), comment(string)

GET 列表参数：browseType(allstory|assignedtome|openedbyme|reviewbyme|draftstory，默认unclosed), orderBy(id|title|status+_asc/_desc), recPerPage, pageID

建议：创建 Story / Epic / Requirement 时显式传 grade，不要依赖接口默认值；在某些禅道实例中，不传 grade 可能会把需求层级写成 0。

---

业务需求（Epic）

列表：/products/{id}/epics

字段结构同 Story，差异：无 project/execution 字段，parent 指父业务需求。

POST 创建建议：沿用 Story 的字段结构，并显式传 grade。典型 BR 场景可传 grade: 1。

GET 列表参数：同 Story

---

用户需求（Requirement）

列表：/products/{id}/requirements

字段结构同 Story，差异：无 project/execution 字段，change 操作中 reviewer 为可选（非必填）。

POST 创建建议：沿用 Story 的字段结构，并显式传 grade。典型 UR 场景可传 grade: 1。

GET 列表参数：同 Story

---

Bug

列表通过父资源获取：/products/{id}/bugs, /projects/{id}/bugs, /executions/{id}/bugs

POST 创建：productID(int), title(string), openedBuild(string[], 如["trunk"]), project(int), execution(int), severity(int, 默认3), pri(int, 默认3), type(codeerror|config|install|security|performance|standard|automation|designdefect|others), steps(string), story(int)

PUT 修改：所有字段均为可选

PUT resolve 解决：resolution(fixed|notrepro|bydesign|duplicate|external|postponed|willnotfix|tostory), resolvedDate(string), resolvedBuild(string), assignedTo(string), comment(string)

PUT close 关闭：comment(string)

PUT activate 激活：openedBuild(string[]), assignedTo(string), comment(string)

GET /products/{id}/bugs 参数：browseType(all|unclosed|assignedtome|openedbyme|assignedbyme，默认unclosed), orderBy(id|title|status+_asc/_desc), recPerPage, pageID

GET /projects/{id}/bugs 和 /executions/{id}/bugs 参数：browseType(all|unresolved，默认all), orderBy 同上

---

任务（Task）

列表：/executions/{id}/tasks

POST 创建：name(string), executionID(int), type(string), assignedTo(string), estStarted(date), deadline(date), pri(int), estimate(float), module(int), story(int), desc(string)

PUT 修改：所有字段可选

PUT start 启动：realStarted(date), assignedTo(string), consumed(float), left(float), comment(string)

PUT finish 完成：currentConsumed(float), realStarted(date), finishedDate(date), assignedTo(string), consumed(float), comment(string)

PUT close 关闭：comment(string)

PUT activate 激活：left(float), assignedTo(string), comment(string)

GET 列表参数：status(all|unclosed|assignedtome|myinvolved|assignedbyme，默认unclosed), orderBy(id|name|status+_asc/_desc), recPerPage, pageID

---

测试用例（Testcase）

列表通过父资源获取：/products/{id}/testcases, /projects/{id}/testcases, /executions/{id}/testcases

POST 创建：productID(int), title(string), module(int), story(int), pri(int), type(unit|interface|feature|install|config|performance|security|other), precondition(string), steps(string[]), expects(string[]), stepType(string[] step|group), project(int), execution(int)

PUT 修改：title(string)，其余可选（注意：模块字段名为 moudule）

GET 列表参数：browseType(all|wait|needconfirm，默认all), orderBy(id|title|status或pri+_asc/_desc), recPerPage, pageID

---

产品计划（Productplan）

列表：/products/{id}/productplans

POST 创建：productID(int), title(string), parent(int), begin(date), end(date), branchID(int), desc(string)

PUT 修改：title(string)，productID 不再必填，其余可选

GET 列表参数：browseType(all|undone|wait|doing，默认undone), orderBy(id|title|begin|end|status+_asc/_desc), recPerPage, pageID

---

版本（Build）

列表：/projects/{id}/builds, /executions/{id}/builds（无查询参数）

POST 创建：executionID(int), product(int), name(string), system(int), builder(string), date(date), scmPath(string), filePath(string), desc(string)

PUT 修改：同上但字段名为 execution(int)（非 executionID）

---

发布（Release）

列表：/products/{id}/releases（无查询参数）

POST 创建：productID(int), system(int), name(string), build(string[]), date(date), status(wait|normal|fail|terminate), desc(string)

PUT 修改：productID 不再必填，其余同上

路径参数名为 releasID（非 releaseID）

---

测试单（Testtask）

列表：/products/{id}/testtasks, /projects/{id}/testtasks, /executions/{id}/testtasks（无查询参数）

POST 创建：productID(int), name(string), build(int), begin(date), end(date), execution(int), type(string[] integrate|system|acceptance|performance|safety), owner(string), status(wait|doing|done|blocked), desc(string)

PUT 修改：productID 不再必填，其余同上

---

反馈（Feedback）

列表：/products/{id}/feedbacks

POST/PUT：product(int), title(string), module(int), type(story|task|bug|todo|advice|issue|risk|opportunity), desc(string), feedbackBy(string), source(string)

PUT close 关闭：closedReason(commented|repeat|refuse), comment(string)

PUT activate 激活：assignedTo(string), comment(string)

GET 列表参数：browseType(all|wait|doing|toclosed|review|assigntome|openedbyme，默认wait), orderBy(id|title|status+_asc/_desc), recPerPage, pageID

---

工单（Ticket）

列表：/products/{id}/tickets

POST 创建：product(int), title(string), module(int), type(code|data|stuck|security|affair), desc(string), assignedTo(string), deadline(date), openedBuild(string[])

PUT 修改：所有字段可选

PUT close 关闭：closedReason(commented|repeat|refuse), comment(string)

PUT activate 激活：assignedTo(string), comment(string)

GET 列表参数：browseType(all|unclosed|wait|doing|done|finishedbyme|assigntome|openedbyme，默认wait), orderBy(id|title|status+_asc/_desc), recPerPage, pageID

---

应用（System）

列表：/products/{id}/systems（无查询参数）

POST 创建：productID(int), integrated(int, 0=否 1=是), children(string[], 非集成传[]), name(string), desc(string)

PUT 修改：name(string), children(string[]), desc(string)

---

文件（File）

POST：fileName(string)