CANBAN // 文档 // CLI
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(limit1..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,不会偷偷多拉取字段或改变请求语义:
# 以可读缩进格式查看完整看板快照
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目录:
# 从 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。