@zentao-hub/cli

English | 简体中文

不是禅道官方的 zentao-cli。 本包是 @zentao-hub/mcp 的配套 CLI，同时提供基于 @zentao-hub/sdk 的 zentao-hub api ... 命令，可在终端直接调用禅道 REST API。请和官方独立 CLI 区分使用。

@zentao-hub/mcp 的配套 CLI。MCP server 本身不需要它 —— 它把原本要靠手抄/复制脚本完成的事情包成几个子命令，并提供一层直接操作禅道的 API 命令：

• 把 zentao-hub-fix-bug、zentao-hub-bug-analyze、zentao-hub-auto-fix-bug、zentao-hub-review-bug 装到目标 agent 的 workflow 入口（统一 zentao-hub- 前缀，标记为本 CLI 所属入口，避免与用户/团队自定义的同名入口冲突）
  • --agent claude-code → ~/.claude/commands/*.md
  • --agent codex-desktop / codex-cli → $HOME/.agents/skills/<name>/SKILL.md
  • --agent copilot-local → <repo>/.github/prompts/*.prompt.md
  • --agent copilot-cli → ~/.copilot/skills/<name>/SKILL.md
  • --agent claude-desktop → 没有 command/prompt 等价物，只装 MCP
• 在目标 agent 的配置里注册 zentao-hub MCP server。
• 把 commit-msg hook（拦 AI 署名 + 校 Conventional Commits）装到目标代码库
• 按 agent 复制协作规则文件：CLAUDE.md（Claude Code）/ AGENTS.md（Codex / Copilot CLI）/ .github/copilot-instructions.md（Copilot in VS Code）
• 初始化 / 查看 bug-context workspace —— 每个 profile 一个 workspace，在 <$ZENTAO_HUB 或 ~/zentao-hub>/<profile>/
• 为每个 bug 生成一个 .code-workspace，让 VS Code 一次打开 bug 上下文和它的 worktree
• 维护每个 profile workspace 里的 repos.yaml 注册表（productId → 多个代码库）
• 通过 zentao-hub api <resource> <operation> 直接调用 SDK 的禅道 API 操作；通过 zentao-hub api request 调用未显式包装的 REST 端点。

api 命令可直接 CRUD 禅道对象；但 CLI 不替 agent 跑修 bug 工作流。读截图、调研代码、审查决策这些仍然走 slash command + MCP，因为它们属于 LLM workflow。

支持的 agent

| Agent ID | 说明 | Workflow 入口 | MCP 配置文件 | 协作规则文件 | | ----------------- | ----------------------- | ------------------------------------------ | -------------------------------------------------------- | --------------------------------- | | claude-desktop | Claude Desktop | 无 | claude_desktop_config.json | 无 | | claude-code | Claude Code CLI | ~/.claude/commands/*.md | ~/.claude.json 或 <repo>/.mcp.json | CLAUDE.md | | codex-desktop | Codex Desktop | $HOME/.agents/skills/<name>/SKILL.md | ~/.codex/config.toml 或 <repo>/.codex/config.toml | AGENTS.md | | codex-cli | Codex CLI | $HOME/.agents/skills/<name>/SKILL.md | ~/.codex/config.toml 或 <repo>/.codex/config.toml | AGENTS.md | | copilot-local | GitHub Copilot Local | <repo>/.github/prompts/*.prompt.md | 用户 User/mcp.json 或 <repo>/.vscode/mcp.json | .github/copilot-instructions.md | | copilot-cli | GitHub Copilot CLI | ~/.copilot/skills/<name>/SKILL.md | ~/.copilot/mcp-config.json 或 <repo>/.mcp.json | AGENTS.md |

兼容旧 ID：claude → claude-code，codex → codex-cli，copilot → copilot-local。

安装

npm install -g @zentao-hub/cli

或本 monorepo 内开发（使用 pnpm）：

corepack enable
pnpm install
pnpm run build
node packages/cli/dist/index.js help

用法

zentao-hub <group> <command> [options]

  profile login|logout|whoami|list|use
                        管理凭据和默认 profile
  setup install|uninstall|update
                        安装/卸载 agent 集成，或升级当前 CLI
  workspace init|show|path|bug|config
                        管理当前 profile 的 hub workspace
  repo register|list    维护当前 profile 的 repos.yaml 注册表
  api                   直接调用 SDK 的禅道 API；
                        见 `zentao-hub api help [resource]`
  help <group>          打印某个分组的帮助

全局选项:
  --lang <en|zh|auto>   输出语言；默认根据环境自动判断

跑 zentao-hub help 看完整选项，或用 zentao-hub help profile|setup|workspace|repo 查看某个分组。help 语言会读取 ZENTAO_HUB_LANG、LANGUAGE、LC_ALL、LC_MESSAGES、LANG；单次命令可用 --lang <en|zh|auto> 覆盖。

禅道 API 命令（api）

API 命令统一放在 zentao-hub api ... 命名空间下，避免和 setup、profile、repo、workspace 这些 Hub 本地命令分组混淆。认证沿用 zentao-hub profile login 写入的 profile，也支持 ZENTAO_URL / ZENTAO_TOKEN / ZENTAO_USERNAME / ZENTAO_PASSWORD 环境变量。

常用格式：

zentao-hub api products list --query limit=20
zentao-hub api bugs get 123
zentao-hub api bugs create 27 --field title='登录崩溃' --field severity=2
zentao-hub api tasks finish 456 --data '{"consumed":1,"left":0}'
zentao-hub api request GET /products/27/bugs --query status=active

通用 API 参数：

• --profile <name> / --credentials <path>：选择认证来源。
• --query <key=value>：查询参数，可重复，用于 list/raw request。
• --data <json> / --data-file <path|->：JSON 对象请求体。
• --field <key=value>：请求体字段，可重复；值会尽量按 JSON 解析，例如 2、true、["a"]。
• --compact：输出压缩 JSON；默认输出格式化 JSON。

完整 typed API 命令面如下。CLI 内 zentao-hub api help 默认打印紧凑资源摘要；zentao-hub api help <resource> 展开单个资源；zentao-hub api help all 打印全部操作。

| API 资源 | 操作 | | --- | --- | | bugs | list-by-product <productId>, list-by-execution <executionId>, get <bugId>, create <productId>, update <bugId>, resolve <bugId>, close <bugId>, confirm <bugId>, activate <bugId>, assign-to <bugId>, delete <bugId>, get-actions <bugId>, get-history <bugId> | | builds | list-by-product <productId>, list-by-execution <executionId>, get <buildId>, create <executionId>, delete <buildId> | | cases | list-by-product <productId>, get <caseId>, create <productId>, update <caseId>, delete <caseId>, create-result <caseId>, list-results <caseId> | | docs | list-libs, list-by-lib <doclibId>, get <docId>, create <doclibId>, update <docId>, delete <docId> | | efforts | create, list, update <effortId>, delete <effortId> | | executions | list, get <executionId>, create, update <executionId>, start <executionId>, close <executionId>, delete <executionId>, list-tasks <executionId>, list-stories <executionId>, list-team <executionId> | | issues | list-by-project <projectId>, get <issueId>, create <projectId>, update <issueId>, resolve <issueId>, close <issueId>, delete <issueId> | | products | list, get <productId>, create, update <productId>, delete <productId>, list-branches <productId>, list-modules <productId>, list-plans <productId>, list-executions <productId>, list-testsuites <productId>, list-testtasks <productId> | | programs | list, get <programId>, create, delete <programId> | | projects | list, get <projectId>, create, update <projectId>, delete <projectId>, list-executions <projectId>, list-products <projectId> | | releases | list-by-product <productId>, get <releaseId>, create <productId>, delete <releaseId> | | repos | list, get <repoId>, list-branches <repoId>, list-commits <repoId> | | risks | list-by-project <projectId>, get <riskId>, create <projectId>, update <riskId>, delete <riskId> | | stories | list-by-product <productId>, get <storyId>, create <productId>, update <storyId>, change <storyId>, review <storyId>, close <storyId>, activate <storyId>, assign-to <storyId>, delete <storyId> | | tasks | get <taskId>, list-by-execution <executionId>, create <executionId>, update <taskId>, start <taskId>, finish <taskId>, pause <taskId>, activate <taskId>, close <taskId>, cancel <taskId>, assign-to <taskId>, delete <taskId> | | testreports | list-by-product <productId>, get <testreportId>, create <productId>, delete <testreportId> | | todos | list, get <todoId>, create, update <todoId>, finish <todoId>, delete <todoId> | | users | list, get <account>, list-departments, list-by-department <departmentId> |

未覆盖的端点使用 raw request：

zentao-hub api request GET /user
zentao-hub api request POST /some/path --data '{"name":"demo"}'

典型一次性安装流程

下面以 Claude Code 为例（--agent claude-code）。把 --agent 换成其他支持的 agent 即可；凭据、workspace、注册表跨 agent 共用。

# 1. 装 CLI + 登录。MCP server 由 `npx -y @zentao-hub/mcp` 按需启动，不必预装。
#    想启动更快，把 @zentao-hub/mcp 也加到下面这行。
npm install -g @zentao-hub/cli
zentao-hub profile login

# 2. 安装 agent 集成。若当前目录不是 git repo，只安装 user/global 部分
#    （MCP + commands/prompts/skills），repo 文件会跳过。
zentao-hub setup install --agent claude-code

# 3. 初始化 bug-context workspace（与具体 agent 无关）
zentao-hub workspace init
echo 'export ZENTAO_HUB=$HOME/zentao-hub' >> ~/.zshrc

# 4. 每个目标代码库：安装 repo 文件/hook + 登记 productId
#    如果 global 部分已经装过，可加 --no-mcp --no-workflows。
cd ~/projects/venus-fe
zentao-hub setup install --agent claude-code --no-mcp --no-workflows
zentao-hub repo register 2 . --name venus-frontend --tag 前端 --tag electron

之后在所选 agent 里（Claude Code / Copilot Chat / Copilot CLI / Codex CLI）启动并输入：

/zentao-hub-bug-analyze 9634   # 只分析
/zentao-hub-fix-bug 27         # 列产品 27 你名下 active bug 让你挑
/zentao-hub-fix-bug 27 9634    # 直接修
/zentao-hub-auto-fix-bug 27 3  # 无人值守：最多提交 3 个 fix branch，不 merge/push/resolve
/zentao-hub-review-bug 9634    # 审查无人值守修复，然后合并或拒绝

一键卸载

zentao-hub setup uninstall                  # 全卸：slash command + 当前仓库的 hook + 当前仓库的 CLAUDE.md
zentao-hub setup uninstall --repo ~/projects/foo
zentao-hub setup uninstall --keep-hooks-path

需要更细粒度：

zentao-hub setup uninstall commands
zentao-hub setup uninstall hooks --repo .
zentao-hub setup uninstall claude-md --repo .
zentao-hub setup uninstall mcp --agent claude-code

凭据和 workspace 不会被动 —— 那是用户数据，用 zentao-hub profile logout --all 删凭据，rm -rf <hub-root>/<profile> 删 workspace。

Workspace 目录结构

$ZENTAO_HUB（默认 ~/zentao-hub；老版本默认是 ~/.zentao-hub，存在时会自动沿用，升级不会丢数据，迁移命令：mv ~/.zentao-hub ~/zentao-hub）是 hub root，每个 profile 一个 workspace：<root>/<profile>/。这样多个禅道实例（比如不同客户）的 bug 上下文、注册表、附件天然隔离。zentao-hub workspace init --profile <name> 之后：

$ZENTAO_HUB/
├── credentials.json                 ← 跨 profile 共用
├── default/                         ← profile workspace
│   ├── repos.yaml                   ← 注册表：productId → 代码库列表
│   ├── repos.yaml.example           ← 模板
│   └── bugs/                        ← 每个 bug 一个子目录，由 slash command 写入
│       └── <bugId>/
│           ├── raw.json
│           ├── description.md
│           ├── history.md
│           ├── analysis.md
│           ├── bug-<bugId>.code-workspace  ← `zentao-hub workspace bug <bugId>` 生成
│           ├── attachments/
│           │   ├── <id>-<title>.<ext>
│           │   └── inline/
│           │       └── inline-N-<basename>
│           ├── status               ← pending-review / skipped / failed / merged / rejected
│           ├── auto-fix-report.md   ← 无人值守修复报告，供 /zentao-hub-review-bug 读取
│           └── worktrees/           ← fix commands 把每个仓库的 git worktree 放这里
│               ├── <repo-a>/        ← 分支 fix/bug-<bugId>，从 main 切出
│               └── <repo-b>/
└── client-foo/                      ← 第二个 profile，完全隔离
    ├── repos.yaml
    └── bugs/

slash command / prompt 通过当前的 $ZENTAO_PROFILE（MCP server 鉴权也用这个）来挑 workspace。zentao-hub 在 $PATH 上时，会跑 zentao-hub workspace path --profile $ZENTAO_PROFILE 拿到目录。

持久化 hub root 和 workspace（config）

与其在每个 shell 里 export $ZENTAO_HUB、或在每条命令上带 --workspace，不如把偏好一次性持久化：

zentao-hub workspace config hub-root ~/work/zentao-hub         # 给所有 profile 换 hub root
zentao-hub workspace config workspace ~/work/foo --profile foo # 给某个 profile 指定完全自定义的 workspace
zentao-hub workspace config                                    # 查看生效值，以及各自来源
zentao-hub workspace config hub-root --unset                   # 还原成默认
zentao-hub workspace config workspace --unset --profile foo

这些写到 ~/.config/zentao-hub/settings.json（或 $XDG_CONFIG_HOME/zentao-hub/settings.json；设 $ZENTAO_HUB_SETTINGS 可让所有命令都指向同一个文件）—— 刻意放在 hub root 之外，因为 hub root 本身就存在这里。该文件不含任何密钥（不同于 credentials.json）。

解析优先级，从高到低：--workspace/--flag → 环境变量（$ZENTAO_HUB）→ settings.json → 内置默认。所以临时的环境变量或命令行参数永远压过持久化配置。

一旦某个 bug 已经拉到本地，zentao-hub workspace bug <bugId> 会在该 bug 目录里刷新一个 VS Code multi-root workspace 文件。它会把 bug 目录本身和所有 worktrees/* 子目录都放进顶层 folder，同时把 bug 根目录下的 worktrees/ 隐藏掉，避免 Explorer 和搜索里重复看到同一份代码。

升级 CLI（update）

不用再记全局安装那串命令，直接跑：

zentao-hub setup update            # 升级到最新发布版本
zentao-hub setup update --check    # 只检查有没有新版本，不安装
zentao-hub setup update 0.3.2      # 锁定 / 降级到指定版本或 dist-tag

update 会读取当前版本，到 registry 查目标版本（沿用你配置的 registry，所以镜像也能用）， 然后用安装它的包管理器重新执行全局安装——npm、pnpm、yarn、bun 会按安装路径自动识别。 用 --pm <npm|pnpm|yarn|bun> 可覆盖识别结果，--registry <url> 可指定查询用的 registry， --force 在已是最新时也强制重装。如果 CLI 是通过 npx（临时缓存，而非全局安装）运行的， 那就没什么可升级的——npx 每次本来就拉最新版本。

从老的扁平结构迁移

更早的版本把 bugs/ 和 repos.yaml 直接写在根目录下。如果升级后这些文件还在那儿，zentao-hub workspace init --migrate-legacy 会把它们搬到 default/ profile workspace。

注册表 repos.yaml

一个 productId 可以对应多个代码库（前端 / 后端 / 数据库迁移 / …）。/zentao-hub-fix-bug 在 Phase 2 支持多选，跨库 bug 时按仓库循环 worktree + commit + squash。/zentao-hub-auto-fix-bug 只使用这里已经登记的仓库；无法高置信度匹配仓库时会跳过该 bug。

结构：

products:
  27:
    - name: eda-schematic
      path: /Users/you/projects/eda-studio/eda-schematic
      tags: [前端]
    - name: eda-interop
      path: /Users/you/projects/eda-studio/eda-interop
      tags: [api]

可以手工编辑，也可以用 zentao-hub repo register 追加。

流程概览（slash command 跑的事）

/zentao-hub-fix-bug 四阶段：

Phase 1 — Bug 上下文（不依赖任何代码库）
Phase 2 — 选代码库（多选；新输入的写回 repos.yaml）
Phase 3 — 按每个选中的库循环：worktree → 改 → 测 → squash merge
Phase 4 — 收尾建议（push / resolve_bug / 删 worktree）

/zentao-hub-bug-analyze 只跑 Phase 1。之后想真修，直接 /zentao-hub-fix-bug <productId> <bugId>，已下载的 context 会复用。

/zentao-hub-auto-fix-bug <productId> [maxBugs] 是给定时任务用的无人值守版本。它会选择 active bug，写 analysis.md，创建 worktree，提交 fix branch，写 auto-fix-report.md，然后停在 pending-review / skipped: <reason> / failed: <reason>。它不会 merge、push、resolve 禅道 bug、更新 repos.yaml，也不会删除已有 branch/worktree。

/zentao-hub-review-bug <bugId> 读取无人值守报告，展示每个 worktree 的 git log 和 diff stat，然后询问合并、修改后合并或拒绝。通过审查的修复沿用 /zentao-hub-fix-bug 的 squash merge 流程；拒绝则把 status 写为 rejected。

之后如果想把同一个 bug 重新在 VS Code 里打开，跑 zentao-hub workspace bug <bugId> --open。不带 --open 也会刷新 .code-workspace 文件；带 --print-path 时则只输出它的路径。

设计取舍

• API 操作和 LLM 流程分开：zentao-hub api ... 直接调用禅道 API；slash command / prompt 负责 LLM-in-the-loop 的分析、修复、审查流程。
• 集中 workspace 而非仓库内：bug 分析阶段不知道改哪个库；多库场景下放任何一个库都尴尬。
• workspace 按 profile 隔离：多 ZenTao 实例（不同客户/环境）的 bug 上下文与注册表互不污染。
• worktree 而非 checkout：主仓库不动，多库场景天然并行。
• worktree 收纳在 bug 目录下，而不是放在源仓库旁边。一次 cd <bugId>/（或 IDE 以它为根开一个窗口）就能同时看到分析和所有仓库的修复改动。代价：源仓库的 git worktree list 会指向 workspace 树里 —— git worktree remove 照常能用，但别在 worktree 还在时直接 rm -rf <bugId>/。
• squash 而非 fast-forward：主分支只想看一个干净的「fix: #N」commit。
• 不主动 push / resolve / 删分支：副作用 / 跨边界操作留给用户显式触发。
• uninstall 不动用户数据：凭据、workspace 不会被 uninstall 删，避免误伤。

License

MIT © Deven Liu