kanban-orchestrator

看板协调者——任务拆解手册

核心工作者生命周期（包括 kanban_create 扇出模式和“拆解，而非执行”规则）会通过 KANBAN_GUIDANCE 系统提示词块自动注入每个看板流程。当你是职责全在路由任务的协调者配置时，本技能是更深入的操作手册。

配置由用户决定，并非固定名单

Hermes 的配置差异很大。有些用户使用一个配置处理所有工作；有些用户运行一小组配置（docker-worker、cron-worker）；还有些用户组建了由自己命名的精选专家团队。没有默认的专家名单——协调者技能并不知道这台机器上有哪些配置。

扇出任务前，必须根据实际存在的配置来拆解任务。调度器遇到未知的负责人名称时会静默地无法启动任务——它不会自动更正、不会提出建议，也不会回退。因此，在只有 docker-worker 的配置中，分配给 researcher 的卡片只会永远停留在 ready 状态。

步骤 0：规划前先查找可用配置。

任选以下一种方式：

• hermes profile list——显示这台机器上已配置的配置列表。若有终端工具，就通过它运行；否则询问用户。
• kanban_list(assignee="<some-name>")——确认某个名称是否有效。对于未知负责人，它会返回空列表而非错误，因此只能用于确认你已经考虑中的名称。
• 直接询问用户。 当目标需要不止一位专家时，第一轮询问“你配置了哪些配置？”完全没问题。

将结果保存在工作记忆中，供本次对话后续使用。每轮都重新询问会浪费工具调用。

何时使用看板（而不是直接完成工作）

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

1. 需要多位专家。 研究 + 分析 + 写作需要三个配置。
2. 工作需要在崩溃或重启后继续。 任务耗时长、会重复执行或很重要。
3. 用户可能需要介入。 在任意步骤都需要人在环。
4. 多个子任务可以并行执行。 扇出任务以提高速度。
5. 预计需要审核 / 迭代。 审核者配置会针对撰写者的输出进行迭代。
6. 需要保留审计记录。 看板中的行会永久保存在 SQLite 中。

如果以上情况都不适用——这只是一个简单的一次性推理任务——就使用 delegate_task，或者直接回答用户。

抵制诱惑的规则

你的职责说明是“负责路由，不负责执行”。以下规则有助于确保这一点：

• 不要亲自执行工作。 你的受限工具集通常甚至不包含用于实现任务的终端 / 文件 / 代码 / Web 工具。如果你发现自己在想“我就快速修一下”——停下来，为合适的专家创建任务。
• 任何具体任务都要创建看板任务并分配。 每次都要这样做。
• 创建卡片前拆分多条工作线的请求。 用户提示可能包含几条相互独立的工作流。先提取这些工作线，再为每条工作线创建一张卡片，而不是把互不相关的工作打包进一张交给实施者的卡片。
• 并行运行相互独立的工作线。 如果两张卡片不需要对方的输出，就不要相互关联，让调度器可以扇出执行。只有存在真正的数据依赖时才建立关联。
• 不要把有依赖关系的工作创建为彼此独立的 ready 卡片。 如果一张卡片必须等待另一张卡片，就在原始的 kanban_create 调用中传入 parents=[...]。不要先创建再关联，也不要只在正文中写“等待 T1”。
• 如果现有配置中没有合适的专家，就询问用户要创建哪个配置，或使用哪个现有配置。 不要编造配置名称；调度器会静默丢弃未知负责人。
• 拆解、路由并总结——这就是全部工作。

任务拆解手册

步骤 1——理解目标

如果目标含糊不清，就提出澄清问题。提问成本低；派出错误的团队代价高昂。

Step 2 — 绘制任务图

创建任何内容之前，先在回复用户时口头拟定任务图。将每个具体工作流视为一张候选任务卡：

1. 从请求中提取各个工作流。
2. 将每个工作流对应到 Step 0 中发现的某个配置档。如果某个工作流不适合任何现有配置档，请询问用户要使用哪个配置档，或是否创建一个。
3. 判断各个工作流是否独立，还是依赖其他工作流。
4. 将独立工作流创建为并行任务卡，不设置父级链接。
5. 为综合、审查或集成任务创建任务卡，并链接到其依赖的工作流。使用尚未完成的父级任务创建的子任务会处于 todo 状态；只有所有父级任务都完成后，调度器才会将其提升为 ready。

应拆分为多个任务的提示示例（使用配置档名称占位符，请替换为用户环境中的实际名称）：

• “构建一个应用” → 为产品/UI 方向创建一张任务卡，分配给偏设计的配置档；为实现创建一到两张任务卡，分配给工程配置档；如果用户有审查者配置档，还可创建一张后续集成/审查任务卡。
• “修复阻塞问题并检查模型变体” → 为阻塞问题修复创建一张实现任务卡；为配置/源验证创建一张探索/研究任务卡。最终审查任务卡可依赖这两项任务。
• “研究文档并实现” → 文档研究任务卡可以与代码库探索任务卡并行；只有在实现确实需要这些发现时，才让实现任务等待。
• “分析这张截图并查找相关代码” → 为具备视觉能力的配置档创建一张视觉分析任务卡，同时由另一张任务卡搜索代码库。

“另外”、“最后”或“以及”之类的词并不自动意味着存在依赖关系。它们通常只是表示“确保在汇报前涵盖这些事项”。只有当某张任务卡必须等待另一张任务卡的输出才能开始时，才建立链接。

创建任务卡之前，先向用户展示任务图。让用户有机会提出修改，包括指定负责各个工作流的实际配置档名称。

Step 3 — 创建任务并建立链接

使用 Step 0 中的配置档名称。以下示例使用占位符 <profile-A>、<profile-B>、<profile-C>——请替换为用户实际拥有的配置档名称。

t1 = kanban_create(
    title="research: Postgres cost vs current",
    assignee="<profile-A>",  # whichever profile handles research on this setup
    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="<profile-A>",  # same profile, run in parallel
    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="<profile-B>",  # whichever profile does synthesis/analysis
    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="<profile-C>",  # whichever profile drafts user-facing prose
    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。无需手动协调；调度器和依赖引擎会处理这一切。

如果任务图中存在依赖关系，请先创建父级任务卡并记录其返回的 id，然后在调用子任务的 kanban_create 时将这些 id 加入子任务的 parents 列表。不要并行创建所有任务卡，再事后建立链接；这样会造成一个时间窗口，让调度器可能在子任务的输入尚未就绪时就领取它。

Step 4 — 完成你自己的任务

如果你自己也是作为一项任务被启动的（例如，规划配置档被分配了任务 T0: "investigate Postgres migration"），请用你创建内容的摘要将任务标记为完成：

kanban_complete(
    summary="decomposed into T1-T4: 2 research lanes in parallel, 1 synthesis on their outputs, 1 prose draft on the recommendation",
    metadata={
        "task_graph": {
            "T1": {"assignee": "<profile-A>", "parents": []},
            "T2": {"assignee": "<profile-A>", "parents": []},
            "T3": {"assignee": "<profile-B>", "parents": ["T1", "T2"]},
            "T4": {"assignee": "<profile-C>", "parents": ["T3"]},
        },
    },
)

Step 5 — 向用户汇报

用通俗的文字告知用户你创建了哪些任务，并注明所使用的实际配置档：

我已排入 4 项任务：

• T1（<profile-A>）：成本比较
• T2（<profile-A>）：性能比较，与 T1 并行
• T3（<profile-B>）：综合 T1 和 T2，形成建议
• T4（<profile-C>）：将 T3 整理成 CTO 备忘录

调度器现在会领取 T1 和 T2。两项任务都完成后，T3 才会开始。T4 完成时，你会收到网关通知。使用仪表板或 hermes kanban tail <id> 跟踪进度。

常见模式

扇出 + 扇入（研究 → 综合）： 创建 N 张没有父任务的研究类任务卡，再创建一张以这些任务卡为所有父任务的综合任务卡。

并行实现 + 验证： 一张实现者任务卡负责进行更改，同时一张探索者／研究者任务卡负责核验配置、文档或源代码映射。审核者任务卡可以依赖这两张卡。不要仅仅因为用户在一句话中提到了两件事，就让实现者负责不相关的验证工作。

带关卡的流水线： planner → implementer → reviewer。每个阶段都将 parents=[previous_task]。审核者负责阻止或完成任务；如果审核者阻止了任务，操作人员会提供反馈并重新生成任务。

同一配置文件队列： 创建 N 个任务，全部分配给同一配置文件，任务之间没有依赖关系。调度器会串行处理——该配置文件按优先级顺序处理任务，并在自己的记忆中积累经验。

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

注意事项

编造不存在的配置文件名称。 调度器会静默地无法生成未知受派人的任务卡——该卡会永远停留在 ready 状态。始终从 Step 0 的发现结果中选择配置文件进行分配；不确定时，请询问用户。

将独立的工作线捆绑到一张任务卡中。 如果用户要求两个互相独立的结果，就创建两张任务卡。例如：“修复阻碍问题并检查模型变体”并不是一项修复任务；应为修复工作创建一张修复者／工程师任务卡，为变体检查创建一张探索者／研究者任务卡，然后可以将审核关卡设为依赖这两张卡。

因措辞而过度关联。 “最后检查 X”仍可能与实现并行，前提是 X 属于静态配置、文档或源代码发现。只有当检查依赖实现结果时，才将其链接到实现之后。

忘记添加依赖链接。 如果任务图是 research -> implement -> review，不要将所有任务都创建为互相独立的 ready 任务卡。使用父任务链接，确保实现／审核任务不会在其输入就绪前运行。

重新分配与新建任务。 如果审核者以“需要修改”为由阻止了任务，应创建一个链接自审核者任务的新任务——不要用严厉的语气重新运行同一个任务。新任务应分配给原实现者所用的配置文件。

链接的参数顺序。 kanban_link(parent_id=..., child_id=...)——父任务在前。顺序弄反会将错误的任务降级为 todo。

如果任务图的结构取决于中间发现，不要预先创建整个任务图。 如果 T3 的结构取决于 T1 和 T2 的发现，就让 T3 作为一项“综合发现”任务存在，并将阅读父任务交接内容、规划后续步骤作为它自己的第一步。编排器可以生成编排器。

租户继承。 如果你的环境中设置了 HERMES_TENANT，请在每次调用 kanban_create 时传入 tenant=os.environ.get("HERMES_TENANT")，确保子任务位于相同的命名空间中。

目标模式卡片（持久工作者）

默认情况下，派发的工作者对其卡片只有一次机会：完成工作后，调用 kanban_complete/kanban_block，然后退出。对于开放式卡片，一轮通常无法完成任务，此时传入 goal_mode=True，即可将该工作者置于 Ralph 风格的目标循环中——这与 /goal 斜杠命令使用的是同一套引擎：

kanban_create(
    title="Translate the full docs site to French",
    body="Acceptance: every page translated, no English left, links intact.",
    assignee="<translator-profile>",
    goal_mode=True,        # judge re-checks the card after each turn
    goal_max_turns=15,     # optional budget (default 20)
)["task_id"]

运作方式：

• 每轮工作者执行完毕后，辅助评审器会根据卡片的标题 + 正文（视为验收标准）评估工作者的响应。
• 未完成且仍有预算 → 工作者会在同一会话中继续工作（保留完整上下文，不会重新启动新工作者）。
• 工作者自行调用 kanban_complete/kanban_block → 循环停止，进入正常生命周期。
• 预算耗尽但仍未完成 → 卡片会被阻塞，等待人工审核（状态会保留），绝不会悄然退出。

适用场景：耗时较长、涉及多个步骤，或“持续执行直到 X 成立”的卡片。不适用场景：成本低、一次即可完成的卡片（翻译单个字符串、快速查询）——评审器的开销不值得，而且派发器现有的重试和断路器机制已经能够处理工作者的暂时性故障。

请将正文写成明确的验收标准——评审器的效果取决于目标文本的质量。“翻译 README”不如“将 README 的每个部分都翻译成法语；不保留任何英文句子”明确。

恢复卡住的工作者

当某个工作者配置持续崩溃、产生幻觉，或因自身错误而被阻塞时（通常是因为模型错误、缺少技能或凭据失效），看板会为任务标上 ⚠ 标记，并在抽屉中打开一个恢复区域。主要操作有三种：

1. 回收（或运行 hermes kanban reclaim <task_id>）——立即中止正在运行的工作者，并将任务重置为 ready。现有的认领 TTL 约为 15 分钟；这是快速脱困的方式。
2. 重新分配（或运行 hermes kanban reassign <task_id> <new-profile> --reclaim）——将任务切换到另一个配置文件（该配置文件必须存在于当前设置中），然后由派发器使用新的工作者接手。
3. 更改配置文件模型——看板会打印一条可复制粘贴的 hermes -p <profile> model 命令提示，因为配置文件设置保存在磁盘上；请在终端中编辑，然后回收任务，以使用新模型重试。

当工作者调用 kanban_complete(created_cards=[...])，并声称创建了不存在的卡片 ID 或并非由该工作者配置文件创建的卡片 ID 时（门控机制会阻止完成操作），相关任务会显示幻觉警告。若自由文本摘要中引用了无法解析的 t_<hex> ID（这是非阻塞的提示性文本扫描），也会显示此警告。这两种情况都会生成审计事件，即使执行恢复操作后也会保留，以便追踪调试。