禅道 CLI
通过 zentao 命令行工具查询和操作禅道数据。CLI 自动处理认证,支持分页、数据过滤和排序。
前置准备
安装
npm install -g zentao-cli
# 或 bun install -g zentao-cli
# 或 pnpm install -g zentao-cli
# 或免安装运行:npx zentao-cli
如果用户没有安装,引导用户进行全局安装使用,如果系统存在 bun 或 pnpm 则优先使用 bun 或 pnpm 进行全局安装。
认证
首次执行任意 zentao 命令会自动提示登录。也可显式登录:
zentao login -s https://zentao.example.com -u admin -p 123456
环境变量(优先级低于命令行参数):
| 变量 | 说明 |
|---|---|
ZENTAO_URL |
禅道服务地址 |
ZENTAO_ACCOUNT |
用户账号 |
ZENTAO_PASSWORD |
密码 |
ZENTAO_TOKEN |
直接指定 Token(有此变量可省略密码) |
登录成功后凭证缓存在 ~/.config/zentao/zentao.json,后续无需重复登录。
凭证安全
- 用户尚未登录时,不要在对话里收集账号密码。让用户直接在终端执行
zentao login,或执行任意zentao命令触发首次自动登录提示,由用户自行输入凭证。 - 严禁读取本地凭证:
ZENTAO_PASSWORD/ZENTAO_TOKEN环境变量、~/.config/zentao/zentao.json配置文件。所有禅道数据均通过zentao命令获取,凭证由 CLI 内部处理。
命令格式
使用简写方式(推荐):
| 操作 | 命令 |
|---|---|
| 列表 | zentao <module> |
| 详情 | zentao <module> <id> |
| 属性定义 | zentao <module> props |
| 创建 | zentao <module> create --field=value |
| 更新 | zentao <module> update <id> --field=value |
| 删除 | zentao <module> delete <id> |
| 命名操作 | zentao <module> <action> [参数](是否需要 ID 以操作帮助为准) |
| 帮助 | zentao <module> --help / zentao <module> <action> --help |
也支持 --data='JSON' 传入 JSON 数据。
模块与操作速查
| 模块名 | 中文 | 支持的操作 |
|---|---|---|
| program | 项目集 | CRUD |
| product | 产品 | CRUD |
| project | 项目 | 列表 + CUD(无详情接口) |
| execution | 执行/迭代 | CRUD |
| story | 需求 | CRUD + activate / change / close |
| epic | 业务需求 | CRUD + activate / change / close |
| requirement | 用户需求 | CRUD + activate / change / close |
| bug | Bug | CRUD + activate / close / resolve |
| task | 任务 | CRUD + activate / close / finish / start |
| testcase | 测试用例 | CRUD |
| testtask | 测试单 | CUD(按产品/项目/执行查列表) |
| productplan | 产品计划 | CRUD(按产品查列表) |
| build | 版本 | CUD(按项目/执行查列表) |
| release | 发布 | CUD(按产品查列表) |
| feedback | 反馈 | CRUD + activate / close |
| ticket | 工单 | CRUD + activate / close |
| system | 应用 | CU(按产品查列表) |
| user | 用户 | CRUD |
| file | 附件 | 上传 + 编辑名称 + 删除 |
| issue | 问题 | 列表、详情、创建及项目/执行内列表 |
| risk | 风险 | 列表、详情、创建及项目/执行内列表 |
| meeting | 会议 | 列表、详情、创建及项目/执行内列表 |
| workflow | 工作流 | 工作流列表及示例合同详情 |
| doc | 文档 | 空间、文档库、目录、文档的命名查询和写入操作 |
| todo | 待办 | 创建、更新、删除;列表通过 my todos 获取 |
| my | 地盘 | todos、tasks、bugs、stories、projects 等个人列表 |
CRUD = 列表 + 详情 + 创建 + 更新 + 删除;CUD = 创建 + 更新 + 删除。“按范围查列表”表示列表命令必须携带所属范围。
最低版本要求
先通过 zentao <module> <action> --help 查看参数和最低禅道版本。原有操作基线为 22.0 / biz13.0 / max8.0 / ipd5.0,新增操作一般为 22.5 / biz13.5 / max8.5 / ipd5.5,按同一系列比较。CLI 在请求前检查实际服务器版本;遇到 E2010 时报告兼容性限制,不反复重试同一操作。帮助离线列出完整操作,不代表当前服务器全部支持。
doc 和 my 没有默认列表,需要明确操作名称;多个路径参数需分别传入,--id 只代表首个路径 ID。
zentao story getGrades
zentao my tasks --pick=id,name,status
zentao doc myDocs --spaceID=1 --libID=2
zentao doc createMyDoc --spaceID=1 --libID=2 --data '{"title":"开发说明","content":"# 正文","contentType":"doc"}'
zentao file create --file=/path/to/screenshot.png --objectType=bug --objectID=1
列表范围参数
部分模块的列表需要指定所属范围:
zentao story --product=1 # 产品 #1 的需求
zentao bug --product=1 # 产品 #1 的 Bug
zentao task --executionID=1 # 执行 #1 的任务
zentao execution projectExecutions --projectID=5 --browseType=all # 项目 #5 的执行,需满足新增操作的最低版本
zentao build --project=5 # 项目 #5 的版本
zentao testtask --product=1 # 产品 #1 的测试单
zentao release --productID=1 # 产品 #1 的发布
zentao productplan --productID=1 # 产品 #1 的计划
zentao feedback --productID=1 # 产品 #1 的反馈
zentao ticket --productID=1 # 产品 #1 的工单
zentao system --productID=1 # 产品 #1 的应用
AI 使用策略
输出格式
- 展示给用户:不加
--format参数,默认输出 Markdown 表格(列表)或列表(单个对象) - 需要程序化处理:加
--format=json,返回结构化 JSON
交互确认
AI 场景下执行删除操作时加 --yes 跳过确认提示:
zentao bug delete 1 --yes
不知道 ID 时
先查列表获取 ID,再操作具体对象:
zentao product --pick=id,name # 查看产品列表
zentao bug --product=1 --pick=id,title # 查看 Bug 列表
zentao bug 42 # 查看具体 Bug
不确定字段时
查询返回对象可能包含哪些字段时用 props;查看创建、更新或状态流转能传哪些参数时,以该操作的 --help 为准。props 不是写入参数清单。
zentao bug props --format=json
zentao bug create --help
写操作前确认
执行创建、更新、删除等写操作前,先向用户确认操作内容。用户明确要求不确认时可跳过。
更新操作自动补全
执行 update 时,CLI 会先 GET 当前对象,把用户未显式传入的字段用现值填充后再 PUT,避免禅道 PUT 覆盖未提交字段导致清空。因此只需传想改的字段即可,无需手动先查再传完整参数。
数据处理
摘取字段
zentao product --pick=id,name,status
过滤
zentao bug --product=1 --filter='status=active'
zentao bug --product=1 --filter='severity<=2,pri<=2' # AND
zentao bug --product=1 --filter='status=active' --filter='status=resolved' # OR
支持的运算符:= 等于(推荐)、: 等于(兼容)、!= 不等于、> < >= <=、~ 包含、!~ 不包含。
模糊搜索
zentao bug --product=1 --search=登录 --search-fields=title,steps
zentao bug --product=1 --search=登录,失败 --search=注册,超时 # 组内 AND,组间 OR
排序
zentao bug --product=1 --sort=pri:asc,severity:asc
分页
zentao bug --product=1 --page=1 --recPerPage=50
zentao bug --product=1 --limit=10 # 只取当前返回页的前 10 条
CLI 不会自动翻页。仅当该列表操作的 --help 显示 --page / --recPerPage 时才可使用这两个参数;部分列表接口不支持服务端分页参数。需要全量数据且返回了 pager 时,重复调整 --page,直到已读取条数覆盖总数。--limit 只在当前返回页上截取。
常用操作示例
查看进行中的项目和执行
zentao project --browseType=doing --pick=id,name,status
zentao execution projectExecutions --projectID=5 --browseType=all --pick=id,name,status
创建需求并关联计划
zentao story create --productID=1 --title="需求标题" --assignedTo=admin --pri=3
zentao story update 11 --title="需求标题" --plan=1
创建并解决 Bug
zentao bug create --productID=1 --title="Bug标题" --severity=2 --pri=2 --type=codeerror --openedBuild=trunk
zentao bug resolve 42 --resolution=fixed
创建、启动并完成任务
zentao task create --executionID=1 --name="任务名" --type=devel --assignedTo=admin --estimate=4
zentao task start 100 --realStarted="<YYYY-MM-DD HH:mm:ss>"
zentao task finish 100 --currentConsumed=4 --realStarted="<YYYY-MM-DD HH:mm:ss>" --finishedDate="<YYYY-MM-DD HH:mm:ss>"
查看帮助
zentao bug --help # 查看 Bug 模块的参数和操作
zentao story update --help # 查看需求更新操作的参数和操作
zentao help # 查看所有命令
意图识别
| 用户意图 | CLI 命令 |
|---|---|
| 所有产品/项目/项目集 | zentao product / zentao project --browseType=all / zentao program,全量结果按 pager 逐页读取 |
| 进行中的项目 | zentao project --browseType=doing |
| 某产品的 Bug | zentao bug --product=<id> |
| 某执行的任务 | zentao task --executionID=<id> |
| 创建/新增 Bug | zentao bug create ... |
| 解决 Bug | zentao bug resolve <id> --resolution=<解决方案> |
| 关闭 Bug | zentao bug close <id> |
| 激活 Bug | zentao bug activate <id> |
| 创建需求 | zentao story create ... |
| 变更需求 | zentao story change <id> --reviewer=<审评账号> |
| 关闭需求 | zentao story close <id> --closedReason=<关闭原因> |
| 激活需求 | zentao story activate <id> |
| 业务需求 | zentao epic ...,操作参数以 zentao epic <action> --help 为准 |
| 用户需求 | zentao requirement ...,操作参数以 zentao requirement <action> --help 为准 |
| 创建/启动/完成/关闭任务 | zentao task create/start/finish/close ... |
| 测试用例 | zentao testcase ... |
| 测试单 | zentao testtask ... |
| 产品计划 | zentao productplan ... |
| 版本/Build | zentao build ... |
| 发布 | zentao release ... |
| 反馈 | zentao feedback ... |
| 工单 | zentao ticket ... |
| 用户列表 | zentao user |
| 当前用户信息 | zentao profile |
错误处理
| 错误码 | 含义 | 处理方式 |
|---|---|---|
| E1001 | 未登录/凭证缺失 | 执行 zentao login |
| E1004 | Token 失效 | 执行 zentao login 重新登录 |
| E2001 | 模块不存在 | 执行 zentao help 查看可用模块 |
| E2002 | 对象不存在 | 检查 ID 是否正确 |
| E2003 | 缺少必要参数 | 执行 zentao <module> --help 或 zentao <module> <action> --help 查看操作参数 |
| E2006 | 无权限 | 提示用户检查权限 |
| E2010 | 禅道版本不支持该操作 | 按错误提示确认对应系列的最低版本 |
| E2011 | 版本格式无法识别 | 检查是否为受支持的正式版本 |
| E2012 | 无法识别服务器配置 | 检查站点根地址的 ?mode=getconfig 响应 |
| E5001 | 请求超时 | 检查网络或禅道服务状态 |
注意事项
- 不确定模块参数时,先执行
zentao <module> --help查看帮助,不确定操作参数时,先执行zentao <module> <action> --help查看帮助 browseType常用值:all(全部)、doing(进行中)、closed(已关闭)- 多账号切换:
zentao profile查看和切换账号