hermes教程-标题：看板工作通道

看板工作通道

工作通道是一类进程，看板调度器可以将任务路由到这些进程。每个通道都有一个身份（负责人字符串）、一个生成机制，以及一个关于生成后必须对任务执行什么操作的契约。

本页面就是该契约。它面向两类读者：

• 操作员：选择将哪些通道接入看板（创建哪些配置文件，使用哪些负责人）。
• 插件/集成作者：希望添加新的通道形态（包装 Codex / Claude Code / OpenCode 的 CLI 工作器、容器化审查工作器、通过 API 拉取任务的非 Hermes 服务）。

如果你正在编写工作器代码本身——即在通道内部运行的代理——kanban-worker 技能提供了更详细的过程细节。

层次结构

Hermes Kanban  =  规范的任务生命周期 + 审计追踪
工作通道       =  针对一个已分配卡片的实现执行器
审查者         =  人类或人类代理，用于把关“完成”
GitHub PR      =  可上游化的产物（可选，用于代码通道）

Hermes Kanban 拥有生命周期真相——ready → running → blocked / done / archived。工作通道执行工作，但从不拥有该真相；它们所做的一切都通过 kanban_* 工具（或者对于非 Hermes 外部工作器，通过 API）流回看板内核。审查者把关从“代码变更已编写”到“任务完成”的转换。

通道提供的内容

要成为一个看板工作通道，集成必须提供三样东西：

1. 负责人字符串

调度器将 task.assignee 与 Hermes 配置文件名称（默认通道形态）或已注册的不可生成标识符（插件通道形态——参见下文添加外部 CLI 工作器通道）进行匹配。如果任务的负责人无法解析，则任务会保持在 ready 状态，并附带一个 skipped_nonspawnable 事件，以便看板操作员可以修复它们；它们不会被静默丢弃或由任意回退执行。

2. 生成机制

对于 Hermes 配置文件通道，调度器的 _default_spawn 会在任务的固定工作区内运行 hermes -p <assignee> chat -q <prompt>（或者当 hermes 垫片不在 $PATH 中时，使用等效的模块形式），并设置以下环境变量：

对于非 Hermes 通道（通过插件注册），插件提供自己的 spawn_fn 可调用对象，该对象接收 task、workspace 和 board，并返回一个可选的 PID 用于崩溃检测。

3. 生命周期终结器

每个声明必须恰好以以下之一结束：

• kanban_complete(summary=..., metadata=...) —— 任务成功，状态翻转为 done。
• kanban_block(reason=...) —— 任务等待人工输入，状态翻转为 blocked。当 kanban_unblock 运行时，调度器会重新生成。
• 工作器进程退出且未调用任何工具。内核会回收它并发出 crashed（PID 死亡）、gave_up（连续失败断路器触发）或 timed_out（超过最大运行时间）。这是失败路径；健康的工作器不会在此结束。

看板内核强制要求每个运行恰好以其中之一结束。一个既不调用两者又正常退出的工作器将被视为崩溃。

输出与需要审查的约定

对于大多数更改代码的任务，工作器完成时工作并非真正完成——它需要人工审查。看板内核不强制执行这种区分（“更改代码的任务”是模糊的，如果对每个代码工作器都强制阻塞而非完成，会破坏那些不需要审查的流程）。这是一个叠加在之上的约定：

• 阻塞而非完成，reason 前缀为 review-required: ，以便仪表板 / hermes kanban show 将该行显示为等待审查。
• 首先将结构化元数据放入 kanban_comment，因为 kanban_block 只携带人类可读的 reason。评论是持久的注释渠道——所有与审计相关的字段（changed_files、tests_run、diff_path 或 PR url、决策）都应放在那里。
• 审查者要么批准并解除阻塞，这会重新生成工作器并附带评论线程以供后续跟进；要么通过另一条评论要求修改，下一个工作器运行会在 kanban_show 的上下文中看到这些修改。

kanban-worker 技能提供了 kanban_complete（真正终结的任务——拼写修正、文档更改、研究写作）和 review-required 阻塞模式的工作示例。

日志与审计追踪

调度器将每个任务的工作器标准输出/标准错误写入 <board-root>/logs/<task_id>.log。日志可从看板元数据中审计：

• task_runs 行携带 log_path、退出码（如果可用）、摘要和元数据。
• task_events 行携带每个状态转换（promoted、claimed、heartbeat、completed、blocked、gave_up、crashed、timed_out、reclaimed、claim_extended）。
• kanban_show 返回两者，因此阅读任务的审查者（或后续工作器）无需仪表板访问权限即可获得完整历史记录。

仪表板以摘要、元数据块和退出状态徽章的形式呈现运行历史。CLI 用户可以运行 hermes kanban tail <task_id> 实时跟踪，或运行 hermes kanban runs <task_id> 查看历史尝试列表。

现有通道形态

Hermes 配置文件通道（默认）

这是当前每个看板工作器采用的形态：负责人是一个配置文件名称，调度器生成 hermes -p <profile>，工作器自动加载 kanban-worker 技能以及 KANBAN_GUIDANCE 系统提示块，并使用 kanban_* 工具终止运行。除了定义配置文件外，无需额外设置。

当你为你的工作器群创建配置文件时，选择与编排器要路由到的角色相匹配的名称。编排器（如果有的话）通过 hermes profile list 发现你的配置文件名称——系统没有假设固定的名册（有关编排器方面的契约，请参见 kanban-orchestrator 技能）。

编排器配置文件通道

配置文件通道的一个特化：编排器是一个 Hermes 配置文件，其工具集包含 kanban，但排除 terminal / file / code / web 用于实现。它的工作是将高级目标分解为子任务（通过 kanban_create + kanban_link），然后退后一步。编排器技能编码了反诱惑规则。

添加外部 CLI 工作器通道

将非 Hermes CLI 工具（Codex CLI、Claude Code CLI、OpenCode CLI、本地编码模型运行器等）作为看板工作器通道接入目前还不是一条铺好的路。调度器的生成函数是可插拔的（spawn_fn 是 dispatch_once 上的一个参数），插件可以为非 Hermes 负责人注册自己的 spawn_fn，但周围的集成工作——将 CLI 的退出码包装到 kanban_complete / kanban_block 调用中，将 CLI 的工作区/沙箱约定映射到调度器的 HERMES_KANBAN_WORKSPACE 环境变量，处理认证和每个 CLI 的策略——仍然是每个集成单独的设计工作。

如果你正在考虑添加一个 CLI 通道，请提交一个 issue，描述具体的 CLI 以及你想要启用的工作流。上面的契约是任何此类通道必须满足的约束；实现形态（每个 CLI 一个插件 vs 一个由配置参数化的通用 CLI 运行器插件）是开放的。

与此相关的历史 issue 是 #19931，以及已关闭但未合并的 Codex 特定 PR #19924——它们描述了最初的架构提案，但并未落地一个运行器。

调度器处理的故障模式

这样通道作者就不必重新实现这些：

• 过期的声明 TTL —— 一个声明了但从未心跳/完成/阻塞的工作器会在 DEFAULT_CLAIM_TTL_SECONDS（默认 15 分钟）后被回收——但仅当工作器进程实际已死亡时。一个活跃的工作器（慢速模型在一次无工具的 LLM 调用中花费 20 分钟以上）会获得声明的延长而非被杀死；只有死亡的 PID 才会被回收。
• 崩溃的工作器 —— 一个主机本地 PID 已消失的工作器会被 detect_crashed_workers 检测到并回收；任务会递增 consecutive_failures，并在断路器触发时可能自动阻塞。
• 运行级重试 —— 当任务被重试时（阻塞后、崩溃后、回收后），工作器可以使用终止工具上的 expected_run_id 参数，在其自身运行已被取代时快速失败。
• 每个任务的最大运行时间 —— task.max_runtime_seconds 硬性限制每次运行的挂钟时间，无论 PID 是否存活。这可以捕获那些活跃 PID 扩展本会让其继续运行的真正死锁工作器。
• 滞留任务检测 —— 一个 ready 状态的任务，其负责人在 kanban.stranded_threshold_seconds（默认 30 分钟）内从未产生声明，会在 hermes kanban diagnostics 中显示为 stranded_in_ready 警告。严重性在阈值 2 倍时升级为错误，6 倍时升级为严重。这可以在一个信号中捕获拼写错误的负责人、已删除的配置文件和下线的外部工作器池——与身份无关，无需维护每个看板的允许列表。

相关

• 看板概述 —— 面向用户的介绍。
• 看板教程 —— 配合仪表板打开的演练。
• kanban-worker —— 工作器进程加载的技能。
• kanban-orchestrator —— 编排器方面。