Kanban 看板

看板编排器（Kanban Orchestrator）—— 分解操作手册

核心工作者生命周期（包括 `kanban_create` 扇出（fan-out）模式和"分解，勿执行"（decompose, don't execute）规则）会通过 `KANBAN_GUIDANCE` 系统提示词块自动注入到每个看板流程中。当你是职责仅为任务路由的编排器（orchestrator）角色时，本技能是更深入的操作手册。

何时使用看板（而不是直接干活）

满足以下任一条件时，创建看板（Kanban）任务：

1. 需要多个专家。 研究 + 分析 + 写作就是三个不同的角色。
2. 工作应能承受崩溃或重启。 长期运行、周期性或重要的工作。
3. 用户可能想要插话。 任何步骤都需要人在回路（human-in-the-loop）。
4. 多个子任务可以并行。 为提速进行扇出。
5. 预期需要评审/迭代。 评审角色在起草者的输出上循环迭代。
6. 审计轨迹很重要。 看板行会永久保存在 SQLite 中。

如果以上情况都不适用——只是一次性的小型推理任务——请改用 delegate_task，或者直接回答用户。

抵制诱惑的规则

你的职责描述是"路由，不要执行"。以下是确保这一点的规则：

• 不要亲自执行工作。 你的受限工具集通常甚至不包含用于实现的 terminal/file/code/web。如果你发现自己想"快速修一下"——停下来，为合适的专家创建任务。
• 对于任何具体任务，创建看板任务并分配出去。 每次都如此。
• 如果没有合适的专家，询问用户要创建哪个角色。 不要以"差不多就行"为借口默认自己做。
• 分解、路由、总结——这就是全部工作。

标准专家名册（惯例）

除非用户的配置自定义了角色，否则默认以下角色存在。根据用户实际拥有的角色调整——不确定就问。

| 角色 | 职责 | 典型工作区 |

|---|---|---|

| researcher | 阅读资料、收集事实、撰写发现 | scratch |

| analyst | 综合、排序、去重。消费多个 researcher 的输出 | scratch |

| writer | 以用户的语气撰写文稿 | scratch 或 dir: 指向用户的 Obsidian 笔记库 |

| reviewer | 阅读输出、留下评审意见、把关批准 | scratch |

| backend-eng | 编写服务端代码 | worktree |

| frontend-eng | 编写客户端代码 | worktree |

| ops | 运行脚本、管理服务、处理部署 | dir: 指向运维脚本仓库 |

| pm | 编写规格说明、验收标准 | scratch |

分解操作手册

第 1 步 —— 理解目标

如果目标不明确，先提出澄清性问题。提问成本很低；启动错误的子任务群代价高昂。

第 2 步 —— 草拟任务图谱

在创建任何内容之前，先在（你给用户的回复中）把图谱草拟出来。例如"分析我们是否应该迁移到 Postgres"：

T1  researcher        research: Postgres cost vs current
T2  researcher        research: Postgres performance vs current
T3  analyst           synthesize migration recommendation       parents: T1, T2
T4  writer            draft decision memo                       parents: T3

把它展示给用户。在创建任何内容之前，让用户修正它。

第 3 步 —— 创建任务并建立关联

t1 = kanban_create(
    title="research: Postgres cost vs current",
    assignee="researcher",
    body="Compare estimated infrastructure costs, migration costs, and ongoing ops costs over a 3-year window. Sources: AWS/GCP pricing, team time estimates, current Postgres bills from peers.",
    tenant=os.environ.get("HERMES_TENANT"),
)["task_id"]

t2 = kanban_create(
    title="research: Postgres performance vs current",
    assignee="researcher",
    body="Compare query latency, throughput, and scaling characteristics at our expected data volume (~500GB, 10k QPS peak). Sources: benchmark papers, public case studies, pgbench results if easy.",
)["task_id"]

t3 = kanban_create(
    title="synthesize migration recommendation",
    assignee="analyst",
    body="Read the findings from T1 (cost) and T2 (performance). Produce a 1-page recommendation with explicit trade-offs and a go/no-go call.",
    parents=[t1, t2],
)["task_id"]

t4 = kanban_create(
    title="draft decision memo",
    assignee="writer",
    body="Turn the analyst's recommendation into a 2-page memo for the CTO. Match the tone of previous decision memos in the team's knowledge base.",
    parents=[t3],
)["task_id"]

parents=[...] 控制任务晋级——子任务保持在 todo 状态，直到所有父任务都达到 done，然后自动晋级为 ready。无需手动协调；调度器和依赖引擎会处理。

第 4 步 —— 完成你自己的任务

如果你自己是作为任务被派生的（例如 planner 角色被分配了 T0: "investigate Postgres migration"），请附上你所创建内容的摘要并标记完成：

kanban_complete(
    summary="decomposed into T1-T4: 2 researchers parallel, 1 analyst on their outputs, 1 writer on the recommendation",
    metadata={
        "task_graph": {
            "T1": {"assignee": "researcher", "parents": []},
            "T2": {"assignee": "researcher", "parents": []},
            "T3": {"assignee": "analyst", "parents": ["T1", "T2"]},
            "T4": {"assignee": "writer", "parents": ["T3"]},
        },
    },
)

第 5 步 —— 向用户汇报

用平实的语言告诉他们你创建了什么：

我已排队 4 个任务：

- T1（researcher）：成本对比

- T2（researcher）：性能对比，与 T1 并行

- T3（analyst）：将 T1 + T2 综合为一条建议

- T4（writer）：把 T3 转化为给 CTO 的备忘录

调度器现在会接手 T1 和 T2。两者都完成后 T3 开始。T4 完成时你会收到网关（gateway）通知。使用看板面板或 `hermes kanban tail ` 跟进进度。

常见模式

扇出 + 扇入（研究 → 综合）： N 个无父任务的 researcher 任务，一个以所有这些任务为父任务的 analyst 任务。

带门控的流水线： pm → backend-eng → reviewer。每个阶段的 parents=[previous_task]。评审者可以阻塞或完成；如果评审者阻塞，操作者用反馈解除阻塞并重新生成任务。

同角色队列： 50 个任务全部分配给 translator，彼此之间没有依赖。调度器串行化处理——翻译者按优先级顺序处理，并在自己的记忆中积累经验。

人在回路： 任何任务都可以调用 kanban_block() 等待输入。调度器在 /unblock 后重新生成任务。评论线程承载完整上下文。

陷阱

重新分配 vs. 新建任务。 如果评审者以"需要修改"阻塞任务，从评审者的任务创建一个新任务并建立关联——不要板着脸重跑同一个任务。新任务分配给最初的实现者角色。

关联时的参数顺序。 kanban_link(parent_id=..., child_id=...)——父任务在前。搞混会把错误的任务降级到 todo。

如果任务图谱的形状取决于中间发现，不要预先创建整个图谱。 如果 T3 的结构取决于 T1 和 T2 的发现，就让 T3 以"综合发现"任务的形式存在，其自身的第一步是读取父任务的交接结果并规划后续。编排器可以派生编排器。

租户继承。 如果你的环境中设置了 HERMES_TENANT，把 tenant=os.environ.get("HERMES_TENANT") 传给每次 kanban_create 调用，这样子任务会保持在同一个命名空间中。

恢复卡住的工作者

当某个工作者角色持续崩溃、产生幻觉（hallucinating）或被困在自己的错误中（通常是：模型选错、缺少技能、凭据损坏），看板面板会为该任务标记 ⚠ 徽标，并在抽屉中打开恢复（Recovery）板块。三个主要操作：

1. 回收（Reclaim）（或 hermes kanban reclaim ）——立即中止正在运行的工作者，并将任务重置为 ready。现有的认领 TTL 约为 15 分钟；这是最快的脱身路径。
2. 重新分配（Reassign）（或 hermes kanban reassign --reclaim）——将任务切换到不同的角色，让调度器用新工作者接手。
3. 更换角色模型——面板会打印 hermes -p model 的复制粘贴提示，因为角色配置保存在磁盘上；在终端中编辑它，然后回收（Reclaim）以用新模型重试。

以下情况会出现幻觉（hallucination）警告：工作者的 kanban_complete(created_cards=[...]) 声明中包含不存在或非该角色创建的卡片 ID（门控会阻止完成），或自由文本摘要引用了无法解析的 t_ ID（建议性文本扫描，不阻塞）。两种情况都会产生审计事件，即使在执行恢复操作后仍会保留——追踪记录始终留存以供调试。