第23篇：看板（Kanban）——多 AI 协作白板

第23篇：看板（Kanban）——多 AI 协作白板

想象一下，你不再需要把一个任务拆成无数个“小纸条”塞给同一个助手，而是把任务贴在一面公共白板上，让不同的 AI 助手（甚至你自己）像同事一样，各自认领、更新、交接。这就是 Hermes 的看板（Kanban）功能。

第1步：理解看板是什么

看板是一个持久化的任务板，所有任务都存成数据库里的“一行”。它和 delegate_task（一次性的子任务调用）完全不同：delegate_task 像“打电话问个问题”，问完就挂；看板则像“微信群里的协作”，任务、进度、评论都留在那里，谁都能看、谁都能改，即使程序重启也不会丢。

第2步：两种操作入口

AI 助手：通过内置的 kanban_* 工具直接读写看板（比如 kanban_create 创建任务、kanban_complete 完成任务）。注意：助手是“调用工具”，不是“敲命令行”。
你（人类）：通过命令行 hermes kanban …、斜杠命令 /kanban … 或可视化看板来操作。

两种方式最终都访问同一个数据库，所以数据永远一致。

第3步：核心概念

看板（Board）：一个独立的任务队列。默认有一个 default 看板，你也可以为不同项目创建多个看板。
任务（Task）：看板上的每一行，包含标题、正文、负责人、状态等。
依赖链接（Link）：记录“父任务 → 子任务”的依赖关系。所有父任务都 done 之后，调度器才会把子任务从 todo 提升为 ready。已经跑起来的子任务不能再加链接（它已经被认领了，加链接也拦不住），唯一例外是正在运行的 worker 在交接前给自己的卡片加链接。

第4步：看板适合什么场景？

官方文档列举了 5 个典型场景：

研究分诊：多个研究员并行收集资料，分析师汇总，写手成稿，中间随时可以插入人工审核。
定时运维：每天自动生成简报，长期积累成一本“日志”。
数字孪生：给每个固定角色（如“收件箱助手”）分配一个持久身份，让它积累长期记忆。
工程流水线：拆解任务 → 并行开发 → 审查 → 迭代 → 合并代码。
批量管理：一个专家助手管理 N 个对象（比如 50 个社交媒体账号）。

第5步：什么时候用看板，什么时候用 delegate_task？

简单记：需要短平快的回答，用 delegate_task；需要跨角色协作、长期跟踪、人工介入、或者任务要能恢复，用看板。

两者也可以在同一个 run 里嵌套：看板任务在 profile 网关下以隔离的托管 worker 执行，它的 delegate_task 子任务由该网关在这个 worker 的执行下预留：每个子任务有自己的会话（在卡片会话里列为 subagent），计入 delegation.max_concurrent_children 和 delegation.max_spawn_depth，在卡片的这一轮里返回结果，并随 worker 一起结束。如果网关在子任务中途挂掉，子任务会被回收，不会恢复。需要比网关活得更久、或者需要自己的审查者的工作，仍然应该用子卡片（kanban_create 带 parents）。

第6步：两个新能力值得留意

迭代预算检查点：由调度器派发的 worker 会在用掉约 90% 迭代预算时收到一次检查点提醒（可用 agent.budget_warning_ratio 调早阈值）。提醒只是“报告机会”，不保证模型一定照做；硬上限、无工具最终总结、连续失败熔断这些机制都没变。普通对话和被委派的子任务不会自动继承这个检查点，需要手动开启。
PR 完成契约：创建任务时可以用 --completion-contract OWNER/REPO（或一个具体的 PR URL）声明这是一个 PR 任务；纯本地工作则用 local-only。发布 PR 后，完成时要把 metadata.published_pr 传进去，第一个匹配的 URL 会永久绑定这张卡片。完成时会校验分支保护、必需检查等证据，缺失、待定、失败、超时、跳过或中性的必需证据都无法完成任务；被拒绝时卡片和工作区都会保留，方便修复后重试。仓库没有必需检查时，请改用 local-only 契约。

第7步：别把“支援卡”挂到它要解救的那张卡下面

这是个很容易踩的坑：worker 卡在 t_parent 上，于是新建一张支援卡去补缺失的那块——这时候千万别 kanban_link(t_parent, t_support)。因为链接会让支援卡变成 t_parent 的子任务，于是它被自己本来要解救的父任务挡住，两张卡永远都跑不起来。正确做法是在支援卡的正文里写上父任务的 id 作为引用。

好在系统会把这个死锁暴露出来：link / kanban_link 在把一张 ready 的子卡降级时会报告 gated: true 并记录一条 dependency_wait 事件（用 parents 创建卡片时同理），你在看板上就能看到。想解开，用 hermes kanban unlink <parent> <child> 就行。

第8步：看板列的顺序和事件流

看板的每一列都有自己的排序逻辑：普通列按派发顺序排列卡片（先看优先级，同优先级则最早创建的排最前，最上面那张就是下一个要被派发的）；done 列是历史记录，按完成时间倒序排，最新完成的在最上面。命令行里 hermes kanban list --status done --sort completed-desc 得到的就是同样的顺序，--sort 还支持 completed-desc、created、created-desc、priority、priority-desc、status、assignee、title、updated 等取值。

另外，看板还提供了一条实时事件流：通过 WebSocket 访问 /events?since=<event_id>，就能持续收到 task_events 表的新行。不带 since 参数时，流从看板当前的“尾巴”开始（因为 /board 快照里已经包含了历史）；想从某个位置补看，就传 since=<latest_event_id>；想从头回放全部历史，传 since=0 即可。

第9步：两个小细节

日志保留：hermes kanban 支持 --log-retention-days N 参数来控制日志保留天数。负数会被拒绝，传 0 则表示关闭这项清理（即关闭这一项清扫）。
worker 自报家门：如果调度器在启动 worker 之后、还没来得及记录它的 pid 就挂了，worker 会在第一次调用模型之前自己把 worker_registered 事件（包含 {pid, started_at}）写进去。这样存活检查就能看到它，过期的认领会被延长而不是再启动第二个 worker；如果 worker 的运行在它走到这一步之前就被回收了，它会直接退出，不会去动那张卡片。

第10步：验收读的是“负责人自己的 gh 账号”

这一条对多账号、多组织的机器特别重要。看板做验收（acceptance）时，用的是负责人（assignee）这个 profile 自己的 gh 登录——也就是它自己 .env 里的 GH_TOKEN / GH_CONFIG_DIR，不是当前执行这张卡片的进程的“环境登录”。

一台机器上挂多个 profile（比如每个组织一个 GitHub 身份）时，要按 profile 分别登录 gh：在那个 profile 的 .env 里设置 GH_CONFIG_DIR。
token 必须放在 profile 的 .env（或配置好的密钥来源）里。只是在 shell 里 export GH_TOKEN、或者写在 systemd unit 里的 token，会被从 gh 子进程里清掉，而且不会再加回来。
如果负责人 profile 自己没有 gh 登录，或者这个 profile 已经不存在了，会直接报 not logged in 拒绝执行，不会退回去用 ~/.config/gh。没分配负责人的卡片仍然用环境里的登录。
登录了但看不到这个仓库，会被判为 classification=auth 并报出 profile 名和仓库名，而不是当成可重试的基础设施故障。

第11步：调度器拒绝派发和熔断时的两种状态

看板的 show / tail 里会看到两个值得认识的状态：

状态	附带信息	含义
`skipped_nonspawnable`	`{assignee}`	调度器拒绝派发，因为负责人的 profile 在这个 home 里不存在（或者不在 `kanban.dispatch_profiles` 里）。每张卡片只写一次（除非中间又落了别的事件），所以 `show` / `tail` 能直接点出缺失的 profile，而不会每个 tick 刷一行。卡片仍留在 `ready`，重新分配或装上那个 profile 即可。
`gave_up`	`{failures, effective_limit, limit_source, error, terminal_provider?}`	连续 N 次不成功之后熔断器触发，任务自动阻塞并带上最后一次错误。有效上限的解析顺序是：任务自己的 `max_retries` → 调度器的 `failure_limit` / `kanban.failure_limit` → 内置默认值。`terminal_provider: true` 表示 worker 因 provider 错误退出码 `78`（重试也修不好，比如凭据被吊销、模型下线），其中包含启动阶段就明确要求重新登录的凭据失败（需要 `hermes auth` / `setup`，会在第一轮之前就退 `78`；其他启动失败退 `1`）——这种情况下熔断器会在第一次尝试就触发，并且是“粘性”的，不受上限约束。

总结：看板是 Hermes 让多个 AI 助手像真人团队一样协作的“公共白板”。它把任务变成持久化的数据行，支持人工介入、失败重试、审计追踪，特别适合研究、运维、工程流水线等复杂工作流。

下一篇预告：第24篇将带你手把手搭建第一个看板任务，从创建到分配、完成，走一遍完整流程。别错过！