kanban-code-orchestrator用 Hermes Kanban 构建可恢复的编程工作流摘要Hermes Kanban 是什么为什么不能只写一句“Coder 完成后交给 Tester”Skill 的整体工作流1. 首次运行配置控制面与三个执行面2. 正常运行当前 session 成为唯一 Orchestrator3. 状态机工作流实现原理原理一Chat session 是控制平面不再创建 Orchestrator Worker原理二唯一写入者与显式所有权原理三通过 kanban_create 建立 creator-session subscription原理四Terminal event 只是中断信号metadata.result 才是业务输入原理五Task body 是可恢复日志不依赖模型短期记忆原理六业务重试与基础设施重试分离关键不变量安装与调用边界与结论参考资料项目地址lichenrobo/kanban-code-orchestrator核心入口SKILL.md完整协议workflow-protocol.md同步发布在个人笔记kanban-code-orchestrator用 Hermes Kanban 构建可恢复的编程工作流摘要kanban-code-orchestrator是一个运行在 Hermes Agent 上的软件开发编排 Skill。它把调用 Skill 的持久 TUI/Gateway chat session 直接作为 Orchestrator只创建三个执行型 Profilekanban-code-coder实现需求并修复缺陷kanban-code-tester独立验证并输出 QA 结论kanban-code-reviewer在 QA 通过后执行最终工程审查。工作流不是把三个 Agent 一次性并发启动也不是依赖自然语言“约定俗成”地交接而是在 Hermes Kanban 的持久 Task、run、parent link 和 terminal event 之上实现一台显式状态机。Orchestrator 只接受 Worker 最新 completed run 的metadata.result作为状态转换输入网络中断、Worker 崩溃和通知丢失都不会隐式转移工作流所有权。这套设计要解决的不是“让三个模型互相聊天”而是四个更具体的工程问题谁拥有创建下一张 Task 的唯一权限如何区分 Task 生命周期结束与业务验收通过如何在会话恢复后重建状态并避免重复建卡如何把业务重试与基础设施重试拆成两个独立熔断域。Hermes Kanban 是什么Hermes Kanban 是 Hermes Agent 内置的多 Profile 持久任务板。它不是一次性的 subagent 调用而是一个由 SQLite 持久化的任务队列与状态系统Task、run、依赖关系、评论和事件都写入 Kanban 数据层Worker 则以具有独立 Profile 身份的 OS 进程运行。Hermes 官方文档将它与delegate_task的差别概括为两类计算模型后者接近同步 RPC父 Agent 发起调用并等待返回Kanban 更接近 durable work queue任务可以跨会话、跨进程、跨人工干预继续存在。Kanban 的关键组件包括组件技术职责Board隔离任务、事件、Workspace 和日志的持久队列默认 Board 使用~/.hermes/kanban.dbTask带 assignee、body、status、Workspace 和依赖关系的工作单元RunWorker 对 Task 的一次执行尝试保存 outcome、summary 和 metadataProfile独立的 Hermes Home拥有自己的模型配置、.env、SOUL.md、memory 和 sessionDispatcher周期性提升、原子认领 Task并拉起对应 Profile 的 Worker 进程Terminal eventcompleted、blocked、gave_up、crashed、timed_out等终态事件模型通过kanban_create、kanban_show、kanban_complete等结构化工具访问任务板而不是在 shell 中执行hermes kanban ...。CLI 面向人类和脚本kanban_*toolset 面向正在推理的 Agent。两条入口最终访问同一数据层但工具调用避免了 shell quoting、远程终端中找不到 Hermes CLI以及从 stderr 反解析状态等问题。Profile 与 Workspace 也必须区分。按照 Hermes Profiles 文档Profile 是 Agent 的配置与状态边界并不等价于文件系统沙箱Workspace 才是本次 Task 实际操作的目录。kanban-code-orchestrator因此不会把某个项目路径永久写入 Worker 的terminal.cwd而是在每张 Task 上显式传递绝对dir:pathWorkspace。为什么不能只写一句“Coder 完成后交给 Tester”自然语言角色提示可以约束单个 Agent却不能自动提供分布式工作流需要的控制语义。例如Coder 说“完成了”但没有调用kanban_completeTask 仍未形成持久交接Task 进入done只说明某次执行结束不代表 Tester 返回了QA_PASSReviewer 拒绝后直接重新审查跳过 Tester会让修复代码绕过回归测试Orchestrator 断线后其他 session 若擅自补建 Task可能产生两个并行状态分支QA_FAIL与模型 API 崩溃都表现为“没成功”但它们需要完全不同的重试预算。因此本项目把角色提示、Task 数据契约和 Orchestrator 状态机同时纳入协议。SOUL 负责约束 Worker 能做什么Task body 负责携带不可丢失的上下文metadata.result负责机器可判定的交接当前 chat session 负责唯一的状态转换。Skill 的整体工作流1. 首次运行配置控制面与三个执行面第一次调用/kanban-code-orchestrator时Skill 先做只读 readiness 检测。只有发现缺项时才加载first-run-setup.md并与用户交互确认同名 Worker Profile 是复用、备份后更新还是重建三个 Worker 继承现有模型/API 配置还是分别手动配置当前 Profile 是否具有 Kanban 编排工具三个 Worker 是否启用 coding toolsetauto_decomposefalse与auto_subscribe_on_createtrue是否成立哪个 Gateway 是唯一 Dispatcher owner是否允许执行可能产生模型费用的 smoke test。首次配置只创建三个 Worker Profile不创建kanban-code-orchestratorProfile。Worker SOUL 来自仓库中的固定模板API Key、OAuth token 和 bot token 不进入聊天或仓库只在本地 setup、环境变量或 Profile.env中配置。2. 正常运行当前 session 成为唯一 Orchestrator后续调用若 readiness 已满足当前 TUI/Gateway chat session 直接成为 workflow 的 initiator、owner 与 OrchestratorCurrent persistent chat session (Orchestrator) │ ▼ kanban-code-coder │ IMPLEMENTATION_COMPLETE ▼ kanban-code-tester ┌──────┴──────┐ QA_FAIL QA_PASS │ │ ▼ ▼ Coder Fix kanban-code-reviewer │ ┌────┴─────────┐ └─Tester │ │ REVIEW_REJECT REVIEW_APPROVE │ │ ▼ ▼ Coder Fix → Tester WORKFLOW_DONE启动新 workflow 前必须确定稳定的workflow_id、绝对 Workspace、完整需求、acceptance criteria以及业务重试和 Worker 基础设施重试上限。3. 状态机定义阶段集合S {CODER, TESTER, REVIEWER, DONE, ESCALATION, ERROR}Worker 允许输出的业务结果集合R_coder {IMPLEMENTATION_COMPLETE} R_tester {QA_PASS, QA_FAIL} R_reviewer {REVIEW_APPROVE, REVIEW_REJECT}状态转换函数可以写成δ(CODER, IMPLEMENTATION_COMPLETE) create(TESTER) δ(TESTER, QA_PASS) create(REVIEWER) δ(TESTER, QA_FAIL) tester_retry ; create(CODER_FIX) δ(REVIEWER, REVIEW_REJECT) reviewer_retry ; create(CODER_FIX) δ(REVIEWER, REVIEW_APPROVE) DONE δ(any, unknown_or_missing_result) ERROR其中两个回路存在严格约束QA_FAIL → Coder Fix → Tester REVIEW_REJECT → Coder Fix → Tester → Reviewer任何 Coder 修改都必须重新经过 Tester。Reviewer 拒绝后的修复不能直接回到 Reviewer这是协议最重要的回归测试不变量之一。工作流实现原理原理一Chat session 是控制平面不再创建 Orchestrator Worker早期常见设计会创建一个独立 Orchestrator Profile再由它的无头 Worker 派发任务。问题在于无头进程未必携带正确的平台 session identity如果它错误继承其他进程的 session key自动订阅可能绑定到错误会话。Orchestrator 一旦断线外层 chat 又可能误以为自己需要“接管”最终形成双写控制面。本项目直接让发起 Skill 的持久 TUI/Gateway chat 成为 Orchestrator。这样创建者身份、事件订阅目标和用户可见会话天然重合workflow_owner_kind: chat_session workflow_owner_profile: current profile workflow_owner_session_id: current session identity when available它只编排不直接编码、测试或审查。Dispatcher 只负责拉起 Worker也不拥有业务分支决策权。原理二唯一写入者与显式所有权每条 workflow 只有 owner session 可以执行以下 mutation创建 Coder、Tester、Reviewer 和 Fix Task增加业务重试计数器选择下一状态建立 parent chain。Worker 只能 complete 或 block 自己当前的 Task不能创建下一阶段。网络中断、Gateway 重启、通知失败、Workercrashed或timed_out都不是 ownership transfer event。owner 不可用时系统 fail closed进入WORKFLOW_ORCHESTRATOR_UNAVAILABLE而不是让任意 Profile 猜测并补写任务图。新的 session 只有在用户明确授权后才能接管并且必须先读取完整 Task、run、parent 与 event 链找到最后一个合法 completed run再检查下一阶段 Task 是否已经存在。原理三通过kanban_create建立 creator-session subscriptionOwner chat 必须直接调用kanban_create不能退化为 shell、subprocess 或hermes kanban create。这不仅是接口风格问题还关系到订阅来源auto_subscribe_on_createtrue会把 terminal event 绑定到发起创建的持久 session。创建后必须保存并验证task_id new task id subscribed true subscription target owner session delivery_mode notify | notifywakeHermes 官方订阅语义 中notify只投递被动消息notifywake还会触发目标 Agent 的新推理轮次。因此本 Skill 接受两者但不会把notify宣称为完全无人值守若只有被动通知用户可能需要在同一 session 中执行/kanban-code-orchestrator continue workflow_id工作流不使用sleep或轮询保活。事件到达后才读取 Task用户主动查询状态时也只执行只读检查。原理四Terminal event 只是中断信号metadata.result才是业务输入completedevent 只意味着 Worker run 到达终态可能只携带截断摘要。Orchestrator 收到事件后的读取路径固定为event.task_id → kanban_show(task_id) → latest run where outcomecompleted → run.summary run.metadata → branch on run.metadata.result only它不会依据 Task 标题、顶层statusdone、通知文本、summary 首行或顶层 result 推进。缺少或出现未知metadata.result时进入WORKFLOW_PROTOCOL_ERROR。这是典型的控制面/数据面分离terminal event 类似中断只负责通知“有状态变化”completed run metadata 才是状态机读取并验证的持久数据。Worker 的结构化交接示例{result:QA_FAIL,tests_executed:[pytest tests/test_auth.py],tests_passed:17,tests_failed:1,failing_tests:[test_expired_refresh_token],reproduction_steps:[issue an expired refresh token,POST /token/refresh],expected_result:401 with token_expired,actual_result:500 Internal Server Error,suspected_location:[src/auth/refresh.py],severity:high}代码缺陷是正常业务结果所以QA_FAIL和REVIEW_REJECT仍通过kanban_complete形成成功交接只有缺少权限、外部服务不可达、测试环境缺失或需要用户决策等真正外部阻塞才调用kanban_block。原理五Task body 是可恢复日志不依赖模型短期记忆每张 Task 都重复携带恢复所需的最小完整状态workflow_id: login-api-001 workflow_owner_kind: chat_session workflow_owner_profile: default workflow_owner_session_id: session id workspace: dir:/workspace/myproject tester_retry: 0 tester_retry_limit: 5 reviewer_retry: 0 reviewer_retry_limit: 3同时保留原始需求和 acceptance criteria并尽可能把直接上游 completed Task 设为 parent。parent chain 提供因果关系但不是唯一状态源关键字段仍显式写入每张 Task避免 parent 数据缺失或上下文压缩导致不可恢复。恢复算法是确定性的枚举 workflow 的 Task、run、parent 和 terminal event找到最后一个协议合法的 completed run从 Task body 恢复 Workspace 与计数器根据metadata.result计算应有的下一阶段检查该 Task 是否已经存在只有不存在时才创建。第 5 步是恢复路径上的幂等性闸门可避免 session 在“Task 已创建、回复尚未送达”之间断线后重复建卡。原理六业务重试与基础设施重试分离默认业务预算tester_retry_limit 5 reviewer_retry_limit 3tester_retry只在QA_FAIL时增加reviewer_retry只在REVIEW_REJECT时增加。计数器在后续通过时也不清零因为它们描述的是整条 workflow 已消耗的业务迭代预算。Worker 的max_retries3则用于 spawn failure、模型 API 异常、crash 或 protocol failure 等基础设施问题。把两者分开可以避免两个错误代码持续不满足验收却被基础设施重试无限掩盖或者一次临时 API 故障错误消耗 QA 修复额度。关键不变量这套工作流的正确性依赖以下不变量而不是依赖 Agent “大致理解流程”当前持久 chat 是唯一 Orchestrator不存在 Orchestrator Profile 或 Task所有 Worker/Fix Task 只能由 owner chat 直接调用kanban_create创建Worker 只能结束或阻塞自己的当前 Taskdone不等于业务通过只读取最新 completed run 的metadata.resultQA_FAIL必须返回 Coder所有 Coder 修改后必须重新 TesterREVIEW_REJECT后固定执行 Coder → Tester → Reviewer只有REVIEW_APPROVE可以产生WORKFLOW_DONE每张 Task 显式携带绝对 Workspace不永久修改 Workerterminal.cwdownership 不因断网、通知失败或 Worker 故障自动转移。安装与调用直接从 GitHub 安装hermes skillsinstalllichenrobo/kanban-code-orchestrator/skills/kanban-code-orchestrator或者将仓库添加为 Skill Taphermes skills tapaddlichenrobo/kanban-code-orchestrator hermes skillsinstalllichenrobo/kanban-code-orchestrator/kanban-code-orchestrator必须在持续运行的 TUI 或 Gateway chat 中调用/kanban-code-orchestrator 在 C:\projects\example 中实现登录 API验收条件是……不要从chat -q、cron、一次性 CLI 或 Dispatcher worker 启动。那些无头上下文无法可靠提供 owner chat 所需的持续 session identity 和通知路由。边界与结论kanban-code-orchestrator不是通用 CI/CD 替代品也不提供容器级安全隔离。它解决的是 Agent 编码工作流中的控制一致性用持久 Task 保存交接用结构化结果驱动状态机用唯一 owner 防止多写者竞争用 terminal event 代替轮询并在失败恢复时从 Task 图而不是聊天记忆重建状态。其核心判断可以浓缩成一句话LLM 可以负责实现和判断但工作流推进必须由持久协议约束而不能依赖自然语言暗示。参考资料项目 GitHub 仓库项目工作流协议项目首次配置协议Hermes Kanban 官方文档Hermes Profiles 官方文档Hermes Skills 官方文档