禅道 API v2.0#

配置#

优先级从高到低：

变量说明ZENTAO_URL服务器地址，如 http://zentao.example.com``ZENTAO_TOKEN直接指定 token，跳过登录和缓存（最高优先级），仍需提供服务器地址ZENTAO_ACCOUNT登录账号，有 token 时可选，但提供可更好回答与当前用户相关的问题ZENTAO_PASSWORD登录密码，有 token 时无需提供

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

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

认证流程#

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

bash

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

模块资源路径支持操作项目集 Program/programsCRUD + 关联产品/项目列表产品 Product/productsCRUD + 关联需求/Bug/用例/计划/发布/反馈/工单/测试单/应用项目 Project/projectsCUD + 关联执行/需求/Bug/用例/版本/测试单执行 Execution/executionsCRUD + 关联需求/任务/Bug/用例/版本/测试单需求 Story/storiesCRUD + change/close/activate业务需求 Epic/epicsCRUD + change/close/activate用户需求 Requirement/requirementsCRUD + change/close/activateBug/bugsCRUD + resolve/close/activate任务 Task/tasksCRUD + start/finish/close/activate测试用例 Testcase/testcasesCRUD产品计划 Productplan/productplansCUD + 按产品查列表版本 Build/buildsCUD + 按项目/执行查列表发布 Release/releasesCUD + 按产品查列表测试单 Testtask/testtasksCUD + 按产品/项目/执行查列表反馈 Feedback/feedbacksCRUD + close/activate工单 Ticket/ticketsCRUD + close/activate应用 System/systemsCU + 按产品查列表用户 User/usersCRUD文件 File/files编辑名称 + 删除

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

分页与筛选#

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

参数说明browseType 或 status筛选状态，如 all, doing, unclosed, undone 等（不同模块参数名和可选值不同，详见 api-reference.md）orderBy排序，格式 字段_asc 或 字段_desc，如 id_desc, title_asc``recPerPage每页数量，最大 1000pageID页码，从 1 开始

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

常用操作示例#

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

bash

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）#

bash

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）#

bash

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）#

bash

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）#

bash

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）#

bash

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）#

bash

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）#

bash

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）#

bash

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

常用枚举值速查#

字段可选值项目模式 model``scrum, waterfall, kanban, agileplus, waterfallplusBug 类型 type``codeerror, config, install, security, performance, standard, automation, designdefect, othersBug 解决方案 resolution``fixed, notrepro, bydesign, duplicate, external, postponed, willnotfix, tostory需求关闭原因 closedReason``done, subdivided, duplicate, postponed, willnotdo, cancel, bydesign需求来源 source``customer, user, po, market, service, operation, support, competitor, partner, dev, tester, bug, forum, other需求类别 category``feature, interface, performance, safe, experience, improve, other用例类型 type``unit, interface, feature, install, config, performance, security, other测试单类型 type``integrate, system, acceptance, performance, safety发布状态 status``wait, normal, fail, terminate反馈关闭原因 closedReason``commented, repeat, refuse工单类型 type``code, data, stuck, security, affair产品类型 type``normal, branch, platform产品访问控制 acl``open, private执行类型 lifetime``short, long, ops

意图识别规则#

用户意图关键词对应操作进行中的执行/迭代/SprintGET /projects?browseType=doing → GET /projects/{id}/executions获取所有产品/项目/项目集GET /products, /projects, /programs某产品/项目/执行的 BugGET /products/{id}/bugs, /projects/{id}/bugs, /executions/{id}/bugs创建/新增 BugPOST /bugs（必填：productID, title, openedBuild）更新/修改 BugPUT /bugs/{id}解决 BugPUT /bugs/{id}/resolve（必填：resolution）关闭 BugPUT /bugs/{id}/close激活 BugPUT /bugs/{id}/activate创建需求POST /stories（必填：productID, title）关闭/激活/变更需求PUT /stories/{id}/close, /activate, /change业务需求/epics（同 stories 结构）用户需求/requirements（同 stories 结构）创建任务POST /tasks（必填：name, executionID）启动任务PUT /tasks/{id}/start（必填：realStarted）完成任务PUT /tasks/{id}/finish（必填：currentConsumed, realStarted, finishedDate）关闭任务PUT /tasks/{id}/close测试用例/testcases（CRUD）测试单/testtasks（CUD + 按产品/项目/执行查列表）产品计划/productplans（CUD + 按产品查列表）版本/Build/builds（CUD + 按项目/执行查列表）发布/releases（CUD + 按产品查列表）反馈/feedbacks（CRUD + close/activate）工单/tickets（CRUD + close/activate）应用/系统/systems（CU + 按产品查列表）获取用户列表GET /users

注意事项#

• 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