# 24 种内置 Agent CLI、Herdr PTY 与 CLI 参考

> Canban 通过 `herdr-core` 持久 PTY 与 `libghostty-vt` 直接运行原生编程 Agent CLI，完整保留各工具原有的交互式 TUI、MCP、Skills、权限提示与会话恢复能力。

## 无干扰保留原生 TUI、MCP 与 Skills

Canban 不会用简陋聊天框替换你的编程工具，也不依赖脆弱的 `Stop` Hook，而是通过 `herdr-core`（`hc`）托管真实 PTY：

- **原生 TUI 与终端渲染**：由 `libghostty-vt` 负责 VT 解析与增量状态同步，macOS 通过 AppKit/CoreText 原生绘制，Linux 通过 GTK4 绘制，支持 SGR/像素鼠标上报、OSC 8 超链接与 Monokai 等 17 套深色配色。
- **完整保留 MCP、Skills 与权限控制**：CLI 进程直接在卡片对应 Worktree 中以你的本机环境启动，既有的 MCP Server、自定义 Skill、沙箱规则与登录态无需重新配置。
- **重启不丢会话与精确恢复**：关闭 Canban 窗口、重启 `canband` 或应用在线升级时，`herdr-core` 中的 Agent 进程依然保持运行；已结束的会话也支持按精确会话 ID（`--resume` / `--session` / `--conversation`）恢复上下文。
- **全局并发预算**：自动工作流步骤共享全局并发上限（`scheduler.max_agents`，默认 `8`），手动 Shell 与 `script` 步骤不占用 Agent 槽位。

![Canban Card #2 在持久 Herdr PTY 终端中运行原生 @developer CLI 会话，并与卡片讨论、Hold auto-merge 和工作流进度条并排显示。](https://canban.dev/screenshots/board-terminal.png)

*@developer 在 Card #2 的独立 Worktree（acme-api-f4c9/2）中通过 Herdr PTY 运行 cargo test，并等待显式调用 canban report 推进流程。*

## 全部 24 种内置 CLI Agent

`crates/profiles/src/catalog.rs` 内置了与 Herdr 终端识别及恢复引擎对齐的 24 种官方交互式 CLI，同时支持在 `config/agents.json` 自定义命令或使用动态 `herdr:<template>` 模板：

| ID | Agent | 可执行文件 | 精确会话恢复 | 模型 / 推理强度参数 |
| --- | --- | --- | --- | --- |
| `codex` | Codex | `codex` | 支持 (`resume`) | `-m`, 推理强度 |
| `claude` | Claude Code | `claude` | 支持 (`--resume`) | `--model`, `--effort` |
| `agy` | Antigravity | `agy` | 支持 (`--conversation`) | `--model`, `--effort` |
| `gemini` | Gemini CLI | `gemini` | 支持 (`--resume`) | `-m` |
| `opencode` | OpenCode | `opencode` | 支持 (`--session`) | `-m`, `--variant` |
| `cursor` | Cursor Agent | `cursor-agent` | 支持 (`--resume`) | `--model` |
| `pi` | Pi | `pi` | 支持 (`--session`) | `--model`, `--thinking` |
| `omp` | Omp | `omp` | 支持 (`--resume=`) | `--model` |
| `copilot` | GitHub Copilot | `copilot` | 支持 (`--resume=`) | `--model` |
| `droid` | Droid | `droid` | 支持 (`--resume`) | `-m` |
| `amp` | Amp | `amp` | 新建会话 | — |
| `kimi` | Kimi | `kimi` | 支持 (`--session`) | `--model` |
| `kiro` | Kiro | `kiro-cli` | 新建会话 | `--model` |
| `qwen` | Qwen Code | `qwen` | 支持 (`--resume`) | `-m` |
| `devin` | Devin | `devin` | 支持 (`--resume`) | — |
| `cline` | Cline | `cline` | 新建会话 | — |
| `grok` | Grok | `grok` | 支持 (`--resume`) | `-m` |
| `hermes` | Hermes | `hermes` | 支持 (`--resume`) | `-m` |
| `kilo` | Kilo | `kilo` | 支持 (`--session`) | `-m` |
| `qodercli` | Qoder | `qodercli` | 支持 (`--resume`) | `--model` |
| `letta` | Letta | `letta` | 支持 (`--conversation`) | `-m` |
| `mastracode` | Mastra Code | `mastracode` | 支持 (`--thread`) | `--model` |
| `maki` | Maki | `maki` | 新建会话 | — |
| `muse` | Muse | `muse` | 新建会话 | — |

## 使用 canban card adopt 无缝接管工作流阶段

当你在 `Backlog` 卡片的交互式终端中与 Agent 讨论需求，确认方案后希望直接在该会话中开始编码时，无需重新启动新 Agent：

```sh
"$CANBAN_CLI" card update --file "$CANBAN_RUN_DIR/card.md"
"$CANBAN_CLI" card adopt --stage develop
```

- `card adopt` 会自动携带继承的 `HC_TERMINAL_ID` 与 `HC_SESSION` 运行时上下文。
- `AppServer` 校验所属 Core、主机、活跃 PTY、Profile 与工作区后，将卡片移入 `develop`（`reason: "agent_adopted_stage"`）且不触发重复调度，并把当前活终端直接绑定到 `WorkflowRun`。
- 后续 Agent 调用 `canban report --state completed` 时，卡片会自动顺滑推进至 `Review` 与 `Queue Merge`。

## 注入的 canban CLI 常用命令

Canban 会为每个启动的 Agent 与卡片终端自动注入 `CANBAN_CLI`、`CANBAN_ENDPOINT`、`CANBAN_HOME`、`CANBAN_CARD`、`CARD_ID`、`CANBAN_PROJECT`、`CANBAN_PROFILE_ID` 和 `CANBAN_RUN_DIR`：

```sh
# 查看或更新当前卡片
"$CANBAN_CLI" card show --fields number,title,body,stage,revision
"$CANBAN_CLI" card update [--title '新标题'] --file "$CANBAN_RUN_DIR/card.md"

# 上报执行结果（completed | backlog | blocked | failed | working）
"$CANBAN_CLI" report --state completed --message '摘要' --file "$CANBAN_RUN_DIR/report.md"

# 回复运行中的追问，而不结束当前主任务
"$CANBAN_CLI" reply --to <QUESTION_ID> --file "$CANBAN_RUN_DIR/reply.md"

# 暂存本地 Diff 审查草稿（不直接发往 GitHub）
"$CANBAN_CLI" review draft --file "$CANBAN_RUN_DIR/review_draft.json"

# 调用任意 AppServer JSON-RPC 方法
"$CANBAN_CLI" call card.list '{"project_id":"<PROJECT_ID>","stage":"develop","limit":50}'
```

完整命令清单、Agent 裁剪契约与 `--human` 示例见 [Canban CLI、Agent 优化与 --human](/zh/docs/cli/)。
