禅道 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": "需求标题", "pri": 3, "assignedTo": "admin", "spec": "需求描述"}'

zentao-api

Install via CLI (Recommended)