@zentao-agent/cli

English | 简体中文

不是禅道官方的 zentao-cli。 本包是面向 AI 编码代理的禅道工具链 CLI：提供基于 @zentao-agent/sdk 的 zt api ... 命令直接调用禅道 REST API，安装 agent 集成（commands / prompts / skills、hook、协作规则文件），并内置供桌面客户端使用的 stdio MCP server。请和官方独立 CLI 区分使用。

它做的事情：

• 把 zt-fix-bug、zt-bug-analyze、zt-auto-fix-bug、zt-review-bug 装到目标 agent 的 workflow 入口（统一 zentao-agent- 前缀，标记为本 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 的配置里注册内置的 zt mcp server——默认只为桌面客户端注册（claude-desktop、codex-desktop、copilot-local）；编码代理直接用 zt api ...。可用 --mcp / --no-mcp 覆盖。
• 把 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_AGENT_HOME 或 ~/zentao-agent>/<profile>/
• 为每个 bug 生成一个 .code-workspace，让 VS Code 一次打开 bug 上下文和它的 worktree
• 维护每个 profile workspace 里的 repos.yaml 注册表（productId → 多个代码库）
• 通过 zt api <resource> <operation> 直接调用 SDK 的禅道 API 操作；通过 zt api request 调用未显式包装的 REST 端点。
• 一键卸载：不带 --agent 时清扫全部受支持 agent 的 user+workspace 两个 scope（MCP 注册含旧名、工作流含旧前缀、指令文件、hook）；可用 --agent <id> 或 target 收窄。

api 命令可直接 CRUD 禅道对象；但 CLI 不替 agent 跑修 bug 工作流。读截图、调研代码、审查决策这些仍然走 slash command，因为它们属于 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-agent/cli

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

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

用法

zt <group> <command> [options]

  login / logout        登录 / 删除已保存凭据（成对）
  profile whoami|list|use
                        查看已保存的 profile 并设置默认
  install / uninstall   安装 / 移除 agent 集成（成对；uninstall 默认清扫所有 agent）
  update / migrate      升级当前 CLI / 从 zentao-hub 时代的安装迁移
  workspace init|show|path|bug|config
                        管理当前 profile 的 hub workspace
  repo register|list    维护当前 profile 的 repos.yaml 注册表
  api                   直接调用 SDK 的禅道 API（与 REST 端点 1:1）；
                        见 `zt api help [resource]`
  bug list-my|history|download-attachments
                        基于 API 组合的 bug 复合操作
  task list-my          任务复合操作
  mcp                   启动内置 stdio MCP server（桌面客户端用）
  help <group>          打印某个分组的帮助

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

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

禅道 API 命令（api）

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

常用格式：

zt api products list --query limit=20
zt api bugs get 123
zt api bugs create 27 --field title='登录崩溃' --field severity=2
zt api tasks finish 456 --data '{"consumed":1,"left":0}'
zt 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 内 zt api help 默认打印紧凑资源摘要；zt api help <resource> 展开单个资源；zt 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：

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

复合命令（bug、task）

api 分组保持与禅道 REST 端点的干净 1:1 映射；由多次 API 调用或本地 I/O 组合出来的业务逻辑放在独立的顶层分组里：

# 某个产品下指派给我的 bug（逐页拉取后本地过滤，
# 因为禅道 v1 的 assignedTo/status 查询参数在部分版本上不可靠）。
zt bug list-my <productId> [--status active|resolved|closed|all] [--limit <n>] [--max-scan <n>]

# 带端点回退的操作/备注历史（/actions → /history → 内嵌字段）。
zt bug history <bugId>

# 下载 bug.files 及重现步骤里的内联 <img>。
zt bug download-attachments <bugId> --dest <dir> [--no-inline]

# 某个执行下指派给我的任务。
zt task list-my <executionId> [--status ...] [--limit <n>] [--max-scan <n>]

它们接受与 api 命令相同的 --profile / --credentials / --compact 选项，结果以 JSON 输出到 stdout。

典型一次性安装流程

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

# 1. 装 CLI + 登录。桌面客户端用的 MCP server 内置在同一个二进制里
#    （`zt mcp`），只需要装这一个包。
npm install -g @zentao-agent/cli
zt login

# 2. 安装 agent 集成。若当前目录不是 git repo，只安装 user/global 部分
#    （commands/prompts/skills；桌面 agent 额外注册 MCP），repo 文件会跳过。
zt install --agent claude-code

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

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

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

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

一键卸载

zt uninstall                  # 全卸：所有 agent 的 MCP 注册 + 工作流文件 + 当前仓库的协作规则文件与 hook
zt uninstall --repo ~/projects/foo
zt uninstall --keep-hooks-path

需要更细粒度：

zt uninstall commands
zt uninstall hooks --repo .
zt uninstall claude-md --repo .
zt uninstall mcp --agent claude-code

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

Workspace 目录结构

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

$ZENTAO_AGENT_HOME/
├── 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  ← `zt workspace bug <bugId>` 生成
│           ├── attachments/
│           │   ├── <id>-<title>.<ext>
│           │   └── inline/
│           │       └── inline-N-<basename>
│           ├── status               ← pending-review / skipped / failed / merged / rejected
│           ├── auto-fix-report.md   ← 无人值守修复报告，供 /zt-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（CLI 和内置 MCP server 鉴权也用这个）来挑 workspace。zt 在 $PATH 上时，会跑 zt workspace path --profile $ZENTAO_PROFILE 拿到目录。

持久化 hub root 和 workspace（config）

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

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

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

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

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

升级 CLI（update）

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

zt update            # 升级到最新发布版本
zt update --check    # 只检查有没有新版本，不安装
zt 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 直接写在根目录下。如果升级后这些文件还在那儿，zt workspace init --migrate-legacy 会把它们搬到 default/ profile workspace。

注册表 repos.yaml

一个 productId 可以对应多个代码库（前端 / 后端 / 数据库迁移 / …）。/zt-fix-bug 在 Phase 2 支持多选，跨库 bug 时按仓库循环 worktree + commit + squash。/zt-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]

可以手工编辑，也可以用 zt repo register 追加。

流程概览（slash command 跑的事）

/zt-fix-bug 四阶段：

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

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

/zt-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。

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

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

设计取舍

• API 操作和 LLM 流程分开：zt 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