# Zentao CLI

> 通过 zentao 命令行工具查询和操作禅道（ZenTao）数据，覆盖项目集、产品、项目、执行、需求、Bug、任务、测试用例、测试单、产品计划、版本、发布、反馈、工单、应用、用户、附件、文档、待办、地盘、问题、风险、会议、工作流等模块的增删改查及状态流转。当用户提到禅道、zentao、查询项目进展、获取 Bug 列表、创建任务、更新需求状态等项目管理操作时使用本技能。

- Skill: `easysoft/zentao-cli-2` (Agent Skill)
- Install (CLI): `npx get-skill add easysoft/zentao-cli-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/easysoft/zentao-cli-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: easysoft (https://skillmd.com/u/easysoft)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/easysoft/zentao-cli-2

---


# 禅道 CLI

通过 `zentao` 命令行工具查询和操作禅道数据。CLI 自动处理认证，支持分页、数据过滤和排序。

## 前置准备

### 安装

```bash
npm install -g zentao-cli
# 或 bun install -g zentao-cli
# 或 pnpm install -g zentao-cli
# 或免安装运行：npx zentao-cli
```

如果用户没有安装，引导用户进行全局安装使用，如果系统存在 bun 或 pnpm 则优先使用 bun 或 pnpm 进行全局安装。

### 认证

首次执行任意 `zentao` 命令会自动提示登录。也可显式登录：

```bash
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。

```bash
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
```

### 列表范围参数

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

```bash
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` 跳过确认提示：

```bash
zentao bug delete 1 --yes
```

### 不知道 ID 时

先查列表获取 ID，再操作具体对象：

```bash
zentao product --pick=id,name           # 查看产品列表
zentao bug --product=1 --pick=id,title  # 查看 Bug 列表
zentao bug 42                           # 查看具体 Bug
```

### 不确定字段时

查询返回对象可能包含哪些字段时用 `props`；查看创建、更新或状态流转能传哪些参数时，以该操作的 `--help` 为准。`props` 不是写入参数清单。

```bash
zentao bug props --format=json
zentao bug create --help
```

### 写操作前确认

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

### 更新操作自动补全

执行 `update` 时，CLI 会先 GET 当前对象，把用户未显式传入的字段用现值填充后再 PUT，避免禅道 PUT 覆盖未提交字段导致清空。因此只需传想改的字段即可，无需手动先查再传完整参数。

## 数据处理

### 摘取字段

```bash
zentao product --pick=id,name,status
```

### 过滤

```bash
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
```

支持的运算符：`=` 等于（推荐）、`:` 等于（兼容）、`!=` 不等于、`>` `<` `>=` `<=`、`~` 包含、`!~` 不包含。

### 模糊搜索

```bash
zentao bug --product=1 --search=登录 --search-fields=title,steps
zentao bug --product=1 --search=登录,失败 --search=注册,超时  # 组内 AND，组间 OR
```

### 排序

```bash
zentao bug --product=1 --sort=pri:asc,severity:asc
```

### 分页

```bash
zentao bug --product=1 --page=1 --recPerPage=50
zentao bug --product=1 --limit=10       # 只取当前返回页的前 10 条
```

CLI 不会自动翻页。仅当该列表操作的 `--help` 显示 `--page` / `--recPerPage` 时才可使用这两个参数；部分列表接口不支持服务端分页参数。需要全量数据且返回了 pager 时，重复调整 `--page`，直到已读取条数覆盖总数。`--limit` 只在当前返回页上截取。

## 常用操作示例

### 查看进行中的项目和执行

```bash
zentao project --browseType=doing --pick=id,name,status
zentao execution projectExecutions --projectID=5 --browseType=all --pick=id,name,status
```

### 创建需求并关联计划

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

### 创建并解决 Bug

```bash
zentao bug create --productID=1 --title="Bug标题" --severity=2 --pri=2 --type=codeerror --openedBuild=trunk
zentao bug resolve 42 --resolution=fixed
```

### 创建、启动并完成任务

```bash
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>"
```

### 查看帮助

```bash
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` 查看和切换账号

