禅道 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 自动获取：
eval "$(bash scripts/get-token.sh)"
# 执行后可直接使用 $ZENTAO_URL、$ZENTAO_TOKEN、$ZENTAO_ACCOUNT
脚本依赖：curl、node
后续所有请求 Header 携带：token: $ZENTAO_TOKEN
执行 API 调用的步骤
- 运行
eval "$(bash scripts/get-token.sh)"获取凭证（自动处理缓存；仍缺失时提示用户） - 根据用户意图选择正确的 API 端点（参见 api-reference.md）
- 若为 PUT 编辑操作且用户未提供全部必填字段，先调用对应 GET 详情接口取回当前数据，再将用户指定的字段覆盖进去
- 构造请求（方法、URL、Header、Body）并向用户确认写操作内容
- 执行请求，解析响应
- 以清晰易读的格式向用户展示结果
模块总览
API 基础路径：$ZENTAO_URL/api.php/v2
| 模块 | 资源路径 | 支持操作 |
|---|---|---|
| 项目集 Program | /programs | CRUD + 关联产品/项目列表 |
| 产品 Product | /products | CRUD + 关联需求/Bug/用例/计划/发布/反馈/工单/测试单/应用 |
| 项目 Project | /projects | CUD + 关联执行/需求/Bug/用例/版本/测试单 |
| 执行 Execution | /executions | CRUD + 关联需求/任务/Bug/用例/版本/测试单 |
| 需求 Story | /stories | CRUD + change/close/activate |
| 业务需求 Epic | /epics | CRUD + change/close/activate |
| 用户需求 Requirement | /requirements | CRUD + change/close/activate |
| Bug | /bugs | CRUD + resolve/close/activate |
| 任务 Task | /tasks | CRUD + start/finish/close/activate |
| 测试用例 Testcase | /testcases | CRUD |
| 产品计划 Productplan | /productplans | CUD + 按产品查列表 |
| 版本 Build | /builds | CUD + 按项目/执行查列表 |
| 发布 Release | /releases | CUD + 按产品查列表 |
| 测试单 Testtask | /testtasks | CUD + 按产品/项目/执行查列表 |
| 反馈 Feedback | /feedbacks | CRUD + close/activate |
| 工单 Ticket | /tickets | CRUD + close/activate |
| 应用 System | /systems | CU + 按产品查列表 |
| 用户 User | /users | CRUD |
| 文件 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 | 每页数量，最大 1000 |
pageID | 页码，从 1 开始 |
筛选参数名不一致：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"}'
常用枚举值速查
| 字段 | 可选值 |
|---|---|
项目模式 model | scrum, waterfall, kanban, agileplus, waterfallplus |
Bug 类型 type | codeerror, config, install, security, performance, standard, automation, designdefect, others |
Bug 解决方案 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 |
意图识别规则
| 用户意图关键词 | 对应操作 |
|---|---|
| 进行中的执行/迭代/Sprint | GET /projects?browseType=doing → GET /projects/{id}/executions |
| 获取所有产品/项目/项目集 | GET /products, /projects, /programs |
| 某产品/项目/执行的 Bug | GET /products/{id}/bugs, /projects/{id}/bugs, /executions/{id}/bugs |
| 创建/新增 Bug | POST /bugs（必填：productID, title, openedBuild） |
| 更新/修改 Bug | PUT /bugs/{id} |
| 解决 Bug | PUT /bugs/{id}/resolve（必填：resolution） |
| 关闭 Bug | PUT /bugs/{id}/close |
| 激活 Bug | PUT /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