@kerin/zentao-cli

禅道命令行工具，支持在你喜爱的终端里访问和操作禅道数据，对 AI Agents 友好。本包位于 zentao monorepo 的 packages/zentao-cli，底层依赖同仓的 @kerin/zentao-api。

主要特性

• ✅ 基于禅道 RESTful API 2.0（经 @kerin/zentao-api SDK）
• ✅ 使用便捷，可通过 npx @kerin/zentao-cli 立即运行
• ✅ 安全的用户认证管理，支持多 profile / 多用户切换
• ✅ 支持对数据进行摘取、过滤、排序等处理，并自动将 HTML 转换为 Markdown
• ✅ 对 AI Agents 友好，帮助信息完善，支持输出 Markdown
• ✅ 支持以 AI 技能的方式使用，zentao add-skill 一键安装到 AI Agent
• ✅ 支持 MCP 服务，zentao mcp 启动；zentao add-mcp 一键写入 Agent 配置（复用本地 login 凭证）
• ✅ 工作区管理：ls / set（ID 或名称切换、就地改范围）/ add（按对象建区）/ rm；命令自动注入范围并提示；可选 autoSetWorkspace
• ✅ Shell 自动补全脚本：zentao autocomplete bash|zsh|fish
• ✅ 富文本图床上传：zentao upload <image>
• ✅ zentao upgrade 检查新版本并自动升级 CLI
• ✅ zentao uninstall 一键清理 Agent skill/MCP、补全脚本，并 npm 全局卸载 CLI（--purge 可删本地配置）
• ✅ 使用 Bun + TypeScript 开发，具备类型安全与测试覆盖

待实现 / 待完善特性：

• [ ] 支持批量创建和更新操作
• [ ] 对象预设 pick 列表
• [ ] Markdown 输出渲染，提供适合人阅读的终端渲染模式，为 Markdown 内容应用多彩格式，代码块支持高亮
• [ ] 支持适合开发者手动使用的极客版，有友好的 TUI 界面，支持在一个界面提供交互式操作
• [ ] 国际化支持，支持多语言
• [ ] 多级别日志功能

快速使用

一键安装（推荐）

自动检测 Node.js、包管理器，并引导完成登录与 AI 技能安装。已是最新版时跳过安装直接进入配置；仅当本地与远程版本不一致时询问跳过/覆盖/退出。

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Kerinlin/zentao/main/packages/zentao-cli/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/Kerinlin/zentao/main/packages/zentao-cli/scripts/install.ps1 | iex

若未检测到 Node.js 18+，脚本会询问并自动安装 Node 22 LTS（macOS 走 brew 或官方 .pkg；Windows 走 winget/choco 或官方 MSI；Linux 走 apt/dnf/yum/apk 或官方 tar）。

手动安装

# 全局安装 zentao-cli 工具
npm install -g @kerin/zentao-cli

# 其他安装与运行方式
# bun install -g @kerin/zentao-cli  # ← 使用 bun 安装
# npx @kerin/zentao-cli             # ← 通过 npx 免安装运行
# pnpm dlx @kerin/zentao-cli        # ← 通过 pnpm 免安装运行

# 首次使用需要进行登录
zentao login -s https://zentao.example.com -u admin -p 123456

# 直接执行获取可用命令帮助
zentao

# 查看禅道产品
zentao product

# 查看指定 ID 的产品
zentao product 1

# 更新禅道产品 #1
zentao product update --id=1 --name=产品1

# 更多功能可通过 help 查看
zentao help

# 查看禅道产品帮助
zentao product help

# 安装 zentao-cli 技能
zentao add-skill

# 检查并升级 CLI 到最新版本
zentao upgrade
# zentao upgrade --yes   # 跳过确认，直接升级

核心命令

zentao-cli 的命令格式简单直观：zentao <模块名> [操作] [参数]。下面通过常见场景快速上手。

查看与管理产品

# 查看产品列表
zentao product

# 查看产品详情
zentao product 1

# 创建产品
zentao product create --name=新产品

# 更新产品名称
zentao product update 1 --name=产品新名称

# 删除产品
zentao product delete 1

查看与处理 Bug

# 查看 Bug 列表
zentao bug

# 查看 Bug 详情
zentao bug 329

# 解决 Bug（执行操作）
zentao bug resolve 329 --resolution=fixed

需求与任务

# 查看需求列表
zentao story

# 创建任务
zentao task create --name=实现登录功能 --execution=10

数据筛选与搜索

# 只显示指定字段
zentao product --pick=id,name

# 按条件过滤
zentao bug --filter 'status:active'

# 模糊搜索
zentao story --search=登录 --search-fields=title

# 按字段排序
zentao bug --sort=id_desc

# JSON 格式输出（适合程序处理）
zentao product --format=json

查看帮助

# 查看所有命令
zentao help

# 查看指定模块的帮助（可用操作与参数）
zentao bug help

更多功能（环境变量、账户切换、批量操作、管道输入、分页控制等）请参考 CLI 核心功能详解。

按角色上手（小白向）：开发 & 测试使用指南 — 内网一键安装后二选一：zentao add-skill（技能）或 zentao add-mcp（MCP，日常提单修单推荐）。

在 AI Agents 中使用

通过 Zentao CLI 技能使用

支持通过 zentao-cli 技能访问和操作禅道数据。安装技能可以通过 zentao add-skill 一键安装到 AI Agent，目前支持 Claude Code、Cursor、Cherry Studio、Codex、OpenCode、VS Code、Antigravity、Gemini、WorkBuddy。

详细使用可以参考：在 Agents 中使用禅道，下面简单介绍。

# 安装 zentao-cli 技能（交互：↑↓ 移动，空格勾选，a 全选，回车确认）
$ zentao add-skill

请选择要安装的 AI Agent（可多选）:
❯ [x] Claude Code
  [x] Cursor
  [ ] Cherry Studio
  ...
↑↓ 移动  空格 勾选  a 全选  回车 确认  Ctrl+C 取消

# 安装技能到 Claude Code
$ zentao add-skill claude-code

如果还未安装 zentao-cli，可以通过下面的命令，一键安装、登录和配置 Skill：

# 一键安装、登录和配置 Skill
$ pnpm install -g @kerin/zentao-cli && zentao login && zentao add-skill all

安装技能后即可在对应 Agent 工具中使用禅道 CLI 技能。

禅道中有哪些产品？

产品 xxx 有哪些研发中的需求？

需求 xxx 有哪些风险？

通过 MCP 服务使用

先 zentao login 登录，再执行 zentao add-mcp 一键写入 Agent 配置。MCP 进程复用本地 profile / 工作区，不在 Agent 配置里写密码。

# 需已登录
$ zentao login
$ zentao add-mcp
# 或指定 Agent，例如 Claude Code → 写入 ~/.claude.json
$ zentao add-mcp claude-code

请选择要配置的 AI Agent（可多选）:
❯ [x] Claude Code
  [ ] Cursor
  [ ] VS Code
  ...
# ↑↓ 移动，空格勾选，a 全选，回车确认

如果还未安装 zentao-cli，可以通过下面的命令，一键安装、登录和配置 MCP 服务：

# 一键安装、登录和配置 MCP 服务
$ pnpm install -g @kerin/zentao-cli && zentao login && zentao add-mcp

也可手动在 Agent 的 MCP 配置中加入（需本机已安装 zentao 且已 login）：

{
  "mcpServers": {
    "zentao-cli": {
      "command": "zentao",
      "args": ["mcp"]
    }
  }
}

Claude Code 全局 MCP 写在 ~/.claude.json 顶层 mcpServers（不是 ~/.claude/settings.json）。
鉴权：zentao login 缓存的 token；范围：当前 workspace（product/project/execution）。环境变量 ZENTAO_* 仅为无 profile 时的后备，日常 MCP 不需要。 MCP 仅暴露 19 个语义化 tool（Bug 工作流 + 枚举产品/项目/版本/用户）（不再按模块全量注册 zentao_bug / zentao_task 等）：

| Tool | 说明 | | --- | --- | | list_bugs | Bug 列表（scope 或工作区；默认 browseType=all、orderBy=id_desc、recPerPage=1000；filter 客户端本页筛选；默认省略 steps） | | get_bug | Bug 详情（含 steps） | | create_bug | 创建 Bug | | update_bug | 修改 Bug 字段 | | delete_bug | 删除 Bug | | resolve_bug / close_bug / activate_bug | 状态流转 | | get_current_user | 当前账号 | | list_profiles | 本地已登录账号（无密码） | | switch_user | 切换账号 | | list_workspaces | 工作区列表 | | create_workspace | 按产品/项目/执行建区（对齐 workspace add，并设为当前） | | switch_workspace | 切换工作区（ID 或名称） | | upload_image | 上传本地图片到图床 | | list_products | 产品列表（拿 productId） | | list_projects | 项目列表（拿 projectId） | | list_builds | 版本列表（openedBuild / resolvedBuild） | | list_users | 用户列表（assignedTo 账号） |

迁移（硬切）：旧 zentao_bug + action、zentao_profile、zentao_switch_profile 及全部其它模块 tool 已移除；请改用上表。其它模块操作请继续使用 CLI 或 skill。

卸载

# 预览将清理的 skill / MCP / 补全，并卸载 npm 全局包（默认保留 ~/.config/zentao 登录配置）
zentao uninstall

# 跳过确认
zentao uninstall -y

# 同时删除当前生效的本地配置文件（含 token / 工作区）
zentao uninstall -y --purge

顺序：skill → MCP 键（zentao-cli / zentao）→ 补全脚本 →（可选 purge）→ npm uninstall -g @kerin/zentao-cli。
非交互环境必须带 -y，否则只打印计划并以退出码 2 退出。

文档

| 文档 | 说明 | | --- | --- | | CLI 核心功能详解 | 用户验证、数据访问与操作、数据处理、输出格式、配置管理等 | | 在 Agents 中使用禅道 | 通过技能或 MCP 在 AI Agents 中使用禅道 | | 开发指引 | 技术栈、项目结构、测试 | | 技术方案与实现细节 | 内部接口调用规则、验证机制与持久化配置 | | 常见错误排查与参考手册 | 错误代码（Exxxx）查阅 | | 后续计划 | 待实现的功能和改进计划 | | 更新日志 | 每个版本的变更内容 |