@jasper_zheng/ewi-zentao-cli

v0.5.0

Published

a month ago

EWI 增强版禅道命令行工具，支持产品模块、产品分支、研发看板与 AI Agent 协作。

0High
0Medium
0Low

jasper_zheng

zentao 禅道 cli project-management

EWI Zentao CLI

EWI 增强版禅道命令行工具，支持在终端和 AI Agents 中访问、组织与操作禅道数据。

本项目基于 MIT 许可的 easysoft/zentao-cli 持续开发，保留原作者署名；npm 独立发布名为 @jasper_zheng/ewi-zentao-cli，终端命令仍为 zentao。

主要特性

✅ 基于最新的禅道 RESTful API 2.0 实现
✅ 使用便捷，可通过 npx @jasper_zheng/ewi-zentao-cli 立即运行
✅ 安全的用户认证管理，支持多用户切换
✅ 支持对数据进行摘取、过滤、排序等处理，并自动将 HTML 转换为 Markdown
✅ 对 AI Agents 友好，帮助信息完善，支持输出 Markdown
✅ 支持以 AI 技能的方式使用，支持通过 zentao add-skill 一键安装技能到 AI Agent
✅ 支持 MCP 服务，使用 npx @jasper_zheng/ewi-zentao-cli mcp 启动 MCP 服务
✅ 支持读取研发看板，并修改泳道名称、列名称和 WIP 上限
✅ 使用现代的 bun 与 TypeScript 开发，具备类型安全
✅ 提供完善的测试覆盖，保障代码质量

待实现特性：

[ ] 支持工作区管理，支持记住用户上次访问的产品、项目和执行信息
[ ] 支持批量创建和更新操作
[ ] 对象预设 pick 列表
[ ] Markdown 输出渲染，提供适合人阅读的终端渲染模式，为 Markdown 内容应用多彩格式，代码块支持高亮
[ ] 支持适合开发者手动使用的极客版，有友好的 TUI 界面，支持在一个界面提供交互式操作
[ ] 一键安装脚本，支持自动根据用户环境选择安装方式
[ ] 国际化支持，支持多语言
[ ] 多级别日志功能

快速使用

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

# 其他安装与运行方式
# bun install -g @jasper_zheng/ewi-zentao-cli  # ← 使用 bun 安装
# npx @jasper_zheng/ewi-zentao-cli             # ← 通过 npx 免安装运行
# pnpm dlx @jasper_zheng/ewi-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

核心命令

@jasper_zheng/ewi-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

# 在禅道 22.3 的产品分支创建并指派 Bug
zentao bug create --productID=2 --branch=1 --title='登录异常' \
  --openedBuild=34 --assignedTo=he_kai_jie \
  --steps='1. 登录系统' --actual='停留在登录页' --expect='进入首页'

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

0.3.3 起，Bug 创建会把 productID 同时放入 REST 查询参数和正文；创建/更新在有账号密码登录产生的网页会话时优先使用禅道原生表单，并在成功响应后强制回读核验。这样可避开禅道 22.3 REST 更新 steps 返回成功却未落库的问题。完整说明见禅道 22.3 Bug 兼容写入。

需求与任务

0.4.0 起，story、epic、requirement 的创建会把 productID 同时放入查询参数和正文，修复禅道 22.3 误报 Missing required parameter: productID；研发需求创建后会自动补写 module，并新增 zentao story review 评审动作和 zentao story link 关联动作。完整说明见禅道 22.3 需求兼容写入与评审。

# 查看需求列表
zentao story

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

管理产品需求模块

# 查看产品 #2 的需求模块树
zentao productmodule --product=2

# 创建顶级模块或子模块
zentao productmodule create --product=2 --name=产品定义 --parentID=0
zentao productmodule create --product=2 --name=核心功能 --parentID=42

# 修改模块；--product 用于读取当前值和执行安全检查
zentao productmodule update 42 --product=2 --name=核心能力

# 声明式同步默认只做 dry-run；确认差异后才显式执行
zentao productmodule sync --product=2 --file=product-modules.json
zentao productmodule sync --product=2 --file=product-modules.json --apply --yes

删除产品模块还必须通过 --yes 明确确认，并且 CLI 会拒绝删除仍有子模块或关联需求的模块。完整说明见产品需求模块管理。

产品需求模块只属于产品：productmodule 传入 --execution 或 --project 会直接报错，不会静默落到别的集合上。

管理执行任务模块

# 查看执行 #34 的任务模块树（含所关联产品的需求模块，只读）
zentao taskmodule --execution=34
zentao taskmodule --execution=34 --filter=type:task

# 创建顶级模块或子模块；--parentID 也可以填关联产品的需求模块 ID
zentao taskmodule create --execution=34 --name=后端服务 --parentID=0
zentao taskmodule create --execution=34 --name=鉴权 --parentID=436

# 改名或移动父级；未传入的字段保持原值
zentao taskmodule update 436 --execution=34 --name=后端

# 安全删除
zentao taskmodule delete 436 --execution=34 --yes

任务模块挂在执行下，禅道没有项目级或产品级任务模块，因此 taskmodule 只接受 --execution。写入走网页兼容会话并在写入后回读核验，绝不返回「成功但没落库」。完整说明见执行任务模块管理。

管理产品分支与需求归属

# 读取产品真实分支 ID
zentao productbranch --product=2

# 按分支读取、创建或调整需求
zentao requirement --product=2 --branch=2
zentao requirement create --productID=2 --title='Model CT 需求' --branch=2
zentao requirement update 11 --branch=2

业务需求、用户需求和研发需求均支持 branch 字段；0 表示主干或共享需求。跨分支移动后应回读确认模块是否保持，完整说明见产品分支与需求归属。

管理研发看板

# 展开执行中的区域、泳道和列
zentao kanban --execution=16

# 修改泳道和列；写入后 CLI 会自动回读核验
zentao kanban rename-lane 44 --execution=16 --name='机会验证'
zentao kanban rename-column 298 --execution=16 --name='机会池'

# 设置或取消 WIP 上限
zentao kanban set-wip 300 --execution=16 --wip=3
zentao kanban set-wip 300 --execution=16 --wip=unlimited

禅道 22.x 的看板写入仍使用原生控制器。0.3.0 起，账号密码登录会通过独立 classic 登录同时缓存 API Token 和绑定账号的网页会话，但不会保存密码；旧 Profile 升级后需重新执行一次 zentao login。仅使用 Token 登录会主动清除旧网页会话，避免读写身份不一致。完整说明见研发看板管理。

数据筛选与搜索

# 只显示指定字段
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 核心功能详解。

在 AI Agents 中使用

通过 Zentao CLI 技能使用

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

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

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

请选择要安装的 AI Agent:
  1) Claude Code
  2) Cursor
  3) Cherry Studio
  4) Codex
  5) OpenCode
  6) VS Code
  7) Antigravity
  8) Gemini
  9) 全部安装
请输入编号 (1-9):9

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

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

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

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

禅道中有哪些产品？

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

需求 xxx 有哪些风险？

通过 MCP 服务使用

Zentao CLI 支持一键配置 MCP 服务，只需要执行 zentao add-mcp 命令，然后按照提示输入禅道 URL、用户名和密码即可。

# 一键配置 MCP 服务
$ zentao add-mcp

请输入禅道 URL: https://zentao.example.com
请输入用户名: admin
请输入密码: 123456

请选择要配置的 AI Agent:
   1) Cursor
   2) Claude Desktop
   3) Claude Code
   4) Windsurf
   5) Cline
   6) Trae
   7) VS Code
   8) Cherry Studio
   9) OpenCode
  10) Codex
  11) 全部配置
请输入编号 (1-11): 7

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

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

统一支持通过 npx -y @jasper_zheng/ewi-zentao-cli mcp 手动启动 MCP 服务，然后通过 MCP 客户端访问和操作禅道数据。目前各大 Agents 工具无需提前安装 @jasper_zheng/ewi-zentao-cli 本身，只需要在 MCP 服务配置中增加如下配置即可：

{
  "mcpServers": {
    "ewi-zentao-cli": {
      "command": "npx",
      "args": ["-y", "@jasper_zheng/ewi-zentao-cli", "mcp"],
      "env": {
        "ZENTAO_URL": "https://zentao.example.com",
        "ZENTAO_ACCOUNT": "admin",
        "ZENTAO_PASSWORD": "123456"
      }
    }
  }
}

文档

| 文档 | 说明 | | --- | --- | | CLI 核心功能详解 | 用户验证、数据访问与操作、数据处理、输出格式、配置管理等 | | 产品分支与需求归属 | 分支查询，以及业务／用户／研发需求的分支读写与迁移核验 | | 产品需求模块管理 | 产品模块 CRUD、声明式同步、dry-run 与删除保护 | | 执行任务模块管理 | 执行任务模块 CRUD、与产品需求模块的区别、写后回读核验 | | 禅道 22.3 Bug 兼容写入 | productID、分支、负责人、三段式重现步骤与写后语义核验 | | 禅道 22.3 需求兼容写入与评审 | 需求创建的 productID／模块归属、评审通过与删除兼容 | | 执行创建与产品关联 | 执行 products 传参写法、多分支产品与关联排查 | | 列表的范围与分页 | 三类列表端点的范围差异、分页截断判断与 --pick 作用范围 | | 研发看板管理 | 看板结构读取、泳道／列重命名、WIP 与登录态安全 | | 在 Agents 中使用禅道 | 通过技能或 MCP 在 AI Agents 中使用禅道 | | 开发指引 | 技术栈、项目结构、测试 | | 技术方案与实现细节 | 内部接口调用规则、验证机制与持久化配置 | | 常见错误排查与参考手册 | 错误代码（Exxxx）查阅 | | 后续计划 | 待实现的功能和改进计划 | | 更新日志 | 每个版本的变更内容 |