禅道 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

环境变量（优先级低于命令行参数）：

登录成功后凭证缓存在 ~/.config/zentao/zentao.json，后续无需重复登录。

凭证安全

• 用户尚未登录时，不要在对话里收集账号密码。让用户直接在终端执行 zentao login，或执行任意 zentao 命令触发首次自动登录提示，由用户自行输入凭证。
• 严禁读取本地凭证：ZENTAO_PASSWORD / ZENTAO_TOKEN 环境变量、~/.config/zentao/zentao.json 配置文件。所有禅道数据均通过 zentao 命令获取，凭证由 CLI 内部处理。

命令格式

使用简写方式（推荐）：

也支持 --data='JSON' 传入 JSON 数据。

模块与操作速查

> CRUD = 列表 + 详情 + 创建 + 更新 + 删除；CUD = 无独立列表接口，需指定所属范围

列表范围参数

部分模块的列表需要指定所属范围：

zentao story --product=1                # 产品 #1 的需求
zentao bug --product=1                  # 产品 #1 的 Bug
zentao task --execution=1               # 执行 #1 的任务
zentao execution --project=5            # 项目 #5 的执行
zentao build --project=5                # 项目 #5 的版本
zentao testtask --product=1             # 产品 #1 的测试单
zentao release --product=1              # 产品 #1 的发布
zentao productplan --product=1          # 产品 #1 的计划
zentao feedback --product=1             # 产品 #1 的反馈
zentao ticket --product=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

写操作前确认

执行创建、更新、删除等写操作前，先向用户确认操作内容。用户明确要求不确认时可跳过。

更新操作自动补全

执行 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 --sort=pri_asc,severity_asc

分页

zentao bug --product=1 --page=1 --recPerPage=50
zentao bug --product=1 --all            # 获取全部
zentao bug --product=1 --limit=10       # 只取前 10 条

常用操作示例

查看进行中的项目和执行

zentao project --filter='status:doing' --pick=id,name,status
zentao execution --project=5 --pick=id,name,status

创建需求并关联计划

zentao story create --product=1 --title="需求标题" --assignedTo=admin --pri=3
zentao story update 11 --title="需求标题" --plan=1

创建并解决 Bug

zentao bug create --product=1 --title="Bug标题" --severity=2 --pri=2 --type=codeerror --openedBuild=trunk
zentao bug resolve 42

创建、启动并完成任务

zentao task create --execution=1 --name="任务名" --type=devel --assignedTo=admin --estimate=4
zentao task start 100
zentao task finish 100 --consumed=4

查看帮助

zentao bug help          # 查看 Bug 模块的参数和操作
zentao story update help # 查看需求更新操作的参数和操作
zentao help              # 查看所有命令

意图识别

错误处理

注意事项

• 不确定模块参数时，先执行 zentao help 查看帮助，不确定操作参数时，先执行 zentao help 查看帮助
• browseType 常用值：all（全部）、doing（进行中）、closed（已关闭）
• 多账号切换：zentao profile 查看和切换账号