# Canban 文档中心

> Canban（canban.dev）将用于维护 Human Context 的 Kanban 卡片、声明式 schema 10 Workflow 引擎、Agent 优先的 `canban` CLI，以及基于 Herdr 的持久 PTY 原生 Agent CLI 终端整合在同一个原生工作台中。

- [Workflow YAML 与执行语义](https://canban.dev/zh/docs/workflows/): 基于源码校验的 schema 10 Document/Step 语法、全部 9 种 uses: 步骤类型、condition 指针、admit 准入、返工失败处理与 FIFO Queue Merge。
- [Canban CLI 与 --human](https://canban.dev/zh/docs/cli/): 核心 CLI 子命令、紧凑 JSON 默认输出与服务端 --fields 裁剪、零配置环境变量注入、request_key 幂等以及 --human 人类可读用法。
- [24 种 Agent CLI 与 Herdr PTY](https://canban.dev/zh/docs/agents/): 全部 24 个内置 CLI Agent、libghostty-vt 终端保活、canban card adopt 接管以及零干扰原生 TUI / MCP / Skills。
- [远程 Linux 主机 (canband)](https://canban.dev/zh/docs/remote-hosts/): Headless Linux canband 守护进程、Tailscale TCP 直连与 Bearer 鉴权、SSH 引导/回退、离线快照缓存与诊断中心。
- [安装与常见问题](https://canban.dev/zh/install/): macOS / Linux 桌面版与 Headless 服务器安装命令、GTK4/GStreamer 运行库依赖及常见问题解答。
- [版本更新](https://canban.dev/zh/changelog/): 按版本倒序展示已发布的 Canban Release 与原始更新日志。

## 系统架构

Canban 使用 Rust 构建，采用原生界面框架（`longbridge/nsh` — macOS 13.0+ Apple Silicon 使用 AppKit/Metal，Linux `x86_64` / `arm64` 使用 GTK4）以及 `libghostty-vt` 终端渲染引擎。

- **Canban 桌面客户端 (`canban-ui`)**：通过本地 Unix Socket（`~/.canban/app.sock`）连接本机 `AppServer`，同时通过 Tailscale TCP 或 SSH 隧道直连多台远程 `canband` 主机。
- **AppServer (`canban serve` / `canband`)**：负责 SQLite WAL 存储、卡片、工作流引擎、调度器、Git Worktree 隔离与合并队列。关闭桌面窗口不会中断后台调度。
- **Herdr Core (`hc`)**：持久化 PTY 会话守护进程，直接运行原生 Agent CLI（`claude`、`codex`、`agy`、`gemini`、`opencode`、`cursor-agent` 等），在应用重启或升级时保持 Agent 进程不中断。

## 为什么是 Canban = Kanban + Workflow + Herdr

1. **Kanban 维护 Human Context**：需求说明、粘贴的截图、`#Card` 与 GitHub Issue/PR 引用、`@Agent` 讨论、结构化报告和代码 Diff 都保存在同一张卡片上。
2. **Workflow 自动调度 Worktree 与交付**：将卡片拖入 `Develop` 自动创建独立 Git Worktree（`<dir>-<proj4>/<card-number>`）并推进工作流图；进入 `Review` 后通过串行 FIFO Queue Merge 完成变基合并。
3. **Herdr 无干扰运行原生 Agent CLI**：完整保留原生 CLI 的 TUI 交互、MCP Server、Skills、权限确认与精确会话恢复能力。

![Canban Card #1 工作树 Git Diff 审查视图，展示提交列表、变更 Rust 文件、行内 Diff、Copy Markdown 以及 Review & Send to @Agent 按钮。](https://canban.dev/screenshots/review-diff.png)

*Canban 内置 Worktree Diff 审查：查看提交与行内代码变更、添加行级批注，并通过 Review & Send to @Agent 直接交给 Agent 处理。*

## 核心 CLI 速览

在 Canban 启动的终端或定时 Agent 会话中，进程会自动注入 `CANBAN_CLI`、`CANBAN_ENDPOINT`、`CANBAN_CARD`、`CANBAN_PROJECT` 与 `CANBAN_RUN_DIR`。人类终端操作可加上 `--human` 格式化输出而不额外拉取字段：

```sh
"$CANBAN_CLI" card show --fields number,title,body,stage,revision
"$CANBAN_CLI" card adopt --stage develop
"$CANBAN_CLI" report --state completed --message '已完成实现并验证测试' --file "$CANBAN_RUN_DIR/report.md"
canban --human --fields number,title,stage card show
```

完整命令与优化契约见 [Canban CLI、Agent 优化与 --human](/zh/docs/cli/)。
