# Canban CLI、Agent 优化与 --human

> `canban` 命令行工具（`crates/cli/src/main.rs`）与原生桌面端调用同一套 `AppServer` JSON-RPC 接口。它默认面向 Agent 进行 Token 与一致性优化，同时通过全局 `--human` 参数为人类提供清晰易读的输出。

## 核心 CLI 命令一览

全局参数 `--home <PATH>`（`CANBAN_HOME`）、`--endpoint <PATH>`（`CANBAN_ENDPOINT`）、`--human`、`--fields <COLS>` 与 `--full` 适用于所有子命令：

| 命令 | 用途 |
| --- | --- |
| `canban snapshot`、`canban status` | 获取完整 `app.snapshot` 快照或 `herdr.status` 运行状态。 |
| `canban call <METHOD> '<JSON>'` | 调用任意公开 `AppServer` JSON-RPC 方法（支持 `@/path/to/params.json` 读取文件参数）。 |
| `canban card show`、`card update`、`card adopt` | 查看卡片、更新 `--title` / `--file`，或在不重启重复 Agent 的前提下将当前活终端接管为 `--stage develop`。 |
| `canban report` | 上报执行结果（`--state`：`completed`、`backlog`、`blocked`、`failed`、`working`；`--message`、`--file`），支持卡片或 `--schedule-run-id`。 |
| `canban reply` | 在不结束当前主任务的情况下回复追问（`--to <QUESTION_ID> --file <PATH>`）。 |
| `canban bind-session` | 将提供商会话 ID（`--session-id`）绑定到当前卡片、定时任务、合入批次或配置会话。 |
| `canban review draft`、`review clear` | 暂存或清除本地未发布的 Diff 审查草稿 JSON（`{ summary, verdict, comments }`）。 |
| `canban workflow sources`、`export`、`submit`、`set-default` | 管理 SQLite 中的 `workflow_sources`（支持 `--project-id` 或 `--global`、`--check` 预校验与全局默认模板设置）。 |
| `canban schedule` | `list`、`runs`、`create`、`trigger`、`toggle`（`--on` / `--off`）、`delete` 与 `artifact`，管理全局或项目定时任务。 |
| `canban worktree gc` | 清理已合入的干净 Worktree（`--merged-before 7d`、`--dry-run`、`--env-dirty`、`--fail-on-dirty`）。 |
| `canban batch report` | 在 `_merge_queue` `@merger` 会话中上报批次解决结果（支持可重复 `--evict <CARD_NUMBER>`）。 |
| `canban serve`、`pair`、`service` | 启动无界面 `AppServer`（`--tailscale`、`--port 7680`、`--listen`）、打印 `canban://` 配对链接或管理 `systemd` / `launchd` 服务。 |
| `canban skill`、`--skill`、`build-info` | 打印当前二进制内置的 `SKILL.md` 或不可变构建版本信息，无需打开应用数据库。 |

## Agent 优先优化设计

Canban 在 CLI 与 RPC 层（`crates/app-server/src/representation.rs`）针对 AI Coding Agent 的上下文成本与并发可靠性做了专门设计：

- **默认单行紧凑 JSON**：无论标准输出是否为 TTY，所有查询与变更均输出单行紧凑 JSON，节省上下文 Token；失败时向 stderr 输出结构化 `{"error":{"message":...}}` 并返回非零退出码。
- **服务端响应裁剪（`--fields` 与 `--full`）**：`card.show`、`card.get` 与 `card.list` 列表项默认仅返回精简字段（`id`、`number`、`title`、`stage`、`revision`），写入操作默认仅返回 `accepted` 回执而不重复回传正文。需要正文或特定字段时传入 `--fields number,title,body,stage,revision`（对应 `CARD_FIELDS` / `EVENT_FIELDS`），或使用与 `--fields` 互斥的 `--full`（`view: "full"`）。非法字段名会在分发与落库前直接拦截。
- **有界 Keyset 分页**：`card.list`（`limit` `1..500`，默认 `50`）使用不透明 `cursor` 并校验 `cursor_stale` / `cursor_scope_mismatch`；`timeline.list` 在 SQL 层过滤 `kinds`、将评论文本统一折叠到 `body`，并返回 `next_cursor`、`last_sequence` 与 `highwater`。
- **零配置环境变量注入**：Canban 为启动的会话自动注入 `CANBAN_CLI`、`CANBAN_ENDPOINT`、`CANBAN_HOME`、`CANBAN_CARD`、`CARD_ID`、`CANBAN_PROJECT`、`CANBAN_PROFILE_ID` 与 `CANBAN_RUN_DIR`（定时与合入批次会话还会注入 `CANBAN_SCHEDULE_RUN_ID`、`CANBAN_SCHEDULE_ID` 与 `CANBAN_BATCH_ID`），且省略 `--project` 时可由当前工作目录自动推断。
- **`request_key` 幂等与更新期排队**：变更命令默认附带（或通过 `--request-key` 复用）去重键，改变 `--fields`/`--full` 不会影响写入幂等指纹；遇到守护进程在线升级重启时，`report`、`batch report` 与 `reply` 会通过 `canban_updater::handoff` 持久排队并返回 `{"queued":true,"request_key":...}`。
- **显式 `report --state` 完成门禁**：进程退出或空闲绝不会隐式推进工作流，必须显式申报 `completed`、`blocked`、`failed`、`backlog` 或 `working`。
- **内置 `canban skill`（`SKILL.md`）**：`canban skill` / `canban --skill` 直接输出与当前二进制版本锁定的 `skills/canban/SKILL.md`，`AppServer::open` 也会同步落盘到 `<CANBAN_HOME>/skills/canban/SKILL.md`。
- **本地未发布 `review draft`**：`canban review draft --file "$CANBAN_RUN_DIR/review_draft.json"` 仅将行级批注暂存在本地 SQLite 供桌面 Diff UI 审阅和决定是否发往 GitHub。

## 人类使用方式（--human）

人类开发者使用同一个 `canban` 二进制排查状态或编写脚本时，只需加上全局参数 `--human`。如 `crates/cli/src/main.rs`（`Output::encode`）所示，`--human` **仅负责缩进美化（pretty-print）** 当前服务端返回的 JSON，不会偷偷多拉取字段或改变请求语义：

```sh
# 以可读缩进格式查看完整看板快照
canban --human snapshot

# 只拉取指定卡片字段并格式化打印（兼顾精简与可读性）
canban --human --fields number,title,stage card show

# 以可读格式调用任意 JSON-RPC 方法
canban --human call project.list '{}'

# 配合 --card / --full 使用，或将默认紧凑 JSON 管道传给 jq
canban --human --full card show --card 42
canban call card.list '{"stage":"develop","limit":20}' | jq '.items[] | [.number, .title]'
```

提示：排查隔离开发环境或远程主机 Socket 时，可将 `--home <PATH>` 或 `--endpoint <PATH>` 与 `--human` 组合使用。

## 内置 Canban Skill（canban skill）

Canban 将与当前构建版本锁定的 Agent Skill（`skills/canban/SKILL.md`，在 `crates/context/src/lib.rs` 编译为 `canban_context::SKILL_MD`）直接嵌入二进制，既能让 Agent 准确掌握 CLI 契约，又不会擅自改动用户全局 Agent 配置目录：

- **无副作用输出与 Home 落盘**：执行 `canban skill` 或 `canban --skill`（`crates/cli/src/main.rs`）可直接向 stdout 打印内嵌 `SKILL.md`，无需打开数据库或 Socket；`AppServer::open` 启动（以及 `stage_remote` 同步远程执行机）时，会通过 `materialize_skill` 原子落盘到 `<CANBAN_HOME>/skills/canban/SKILL.md`，但不会自动修改全局 Agent 目录。
- **安装或更新到你的 Agent**：桌面端 **Agent Setup** 与 **Settings → Agents & Identities**（`crates/ui/src/agents_setup.rs`）提供了一键复制的 `npx skills add` 安装命令；也可以将 `canban skill` 的输出直接写入任意 Agent 的 `canban/SKILL.md` 目录：

```sh
# 从 Canban Home 目录安装或更新全局 Skill
npx skills add ~/.canban/skills --skill canban -g

# 或直接将二进制内置 Skill 写入指定 Agent 的 skills 目录
canban skill > ~/.agents/skills/canban/SKILL.md
```

- **Skill 教授给 Agent 的核心规范**：会话前置检查（校验 `CANBAN_CLI` 与 `CANBAN_ENDPOINT`）、将临时正文保存在工作树外的 `$CANBAN_RUN_DIR`、精简 `card show` 与 `card adopt` 接管、显式 `report --state` 完成门禁、`reply --to` 回复追问、本地未发布 `review draft`、`workflow submit --check` 与 `worktree gc`。
