Multi Agent Orchestration

Multi-Agent Orchestration

本 Skill 是 AgentDock Orchestrator 的轻量客户端。它不再在本地维护第二套 Git/Record/HTML 控制面；Project、Work Item、Assignment、Execution、Gate、Record 与 Outcome 的唯一事实源都在 Orchestrator 服务端。

适合的运行方式是：1~5 号各自有固定定时任务 → 定时唤醒 AgentDock → 调用本 Skill → 按 slot 原子领取一个服务端 Assignment → 执行 → 回报。

1. 固定 Slot

Slot 只是定时任务的固定入口，不是权限声明。 真正的协议角色、任务归属、Work Item 状态和可执行动作都由服务端当前 Assignment/Execution 决定。不要在 prompt、payload 或 Record 中伪造 from / role。

2. 每次定时唤醒

定时任务只需要告诉模型自己的编号，例如：

使用 multi-agent-orchestration Skill。你是 3 号，领取并推进当前正式任务；如果 idle 或 busy 就结束本轮。

模型调用：

printf '%s' '{"skill_action":"claim","slot":3}' | python3 run.py

脚本从 Skill 根目录以相对路径执行；URL、Token、节点标识等环境由运行宿主注入，不读取 AgentDock 私有目录或环境文件。

claim 是推荐入口。它在服务端一次完成“选择下一项 + 创建 Execution + 标记 running”，模型不需要再手动 start，也不需要保存 execution_id。

返回状态：

• claimed：本轮拿到新的正式 Assignment，Execution 已经是 running，直接开始实际工作。
• resume：上一轮 Execution 已成功结束，但仍有一个协议后续动作；读取 next_action 并继续，不要领取别的 Work Item。
• idle：当前没有属于该 Slot 的待办，正常结束。
• busy：该 Slot 已有 queued/running Execution，通常说明另一个定时触发仍在工作；新的定时触发不要重复执行。

同一 Slot 一次只运行一个 Execution。服务端会优先恢复 resume 上下文，再按 FIFO 从所有活动 Project/Work Item 中选择 READY Assignment，避免在 dispatch / Gate / close 尚未完成时跳去其他任务。

3. claimed / resume 后的统一流程

收到 claimed 后先阅读返回的：

• project
• work_item
• assignment
• execution
• recent_records

只执行 assignment 明确要求的工作，不自行改变正式任务归属。claim 已经自动写入 started；不要再调用 start。

后续所有写动作都只传自己的 slot，Skill 会从 Orchestrator 当前上下文解析 Execution；模型不要抄写、缓存或传递 execution_id。

执行时间较长时可以按 slot 报告关键进展；不要高频刷 progress：

{"skill_action":"progress","slot":3,"summary":"已筛出 12 个候选，正在核对真实使用量"}

有真实成果时及时上报 Artifact：

{
  "skill_action": "artifact",
  "slot": 3,
  "artifact": {
    "title": "实现结果",
    "type": "text",
    "value": "真实路径、URL、commit、报告或可验证结果",
    "description": "这份成果如何核验"
  }
}

普通 Worker 完成后：

{"skill_action":"finish","slot":3,"status":"succeeded","summary":"完成了什么，以及关键证据"}

如果本轮明确失败，应使用 failed 或 interrupted，让 Assignment 回到 READY 供后续定时任务重试；不要把失败包装成成功。

4. 1 号的 Assignment kind

1 号必须先看 assignment.kind，不同 kind 的后续动作不同。

plan

1. 理解 Work Item 目标、验收条件和已有 Record。
2. 拆成 1~3 个真正需要的 Worker Assignment；不用为了凑满 3/4/5 全开。
3. 用 finish slot=1 status=succeeded 结束当前 plan Execution。
4. 服务端会返回可恢复的 resume / next_action=dispatch 上下文；再用 dispatch slot=1 形成正式 Worker Assignment。

{
  "skill_action": "dispatch",
  "slot": 1,
  "assignments": [
    {
      "seat": 3,
      "role": "backend",
      "title": "实现后端",
      "goal": "完成可验证后端增量",
      "acceptance": ["测试通过"],
      "required": true
    }
  ]
}

至少一个 Worker 必须 required=true。

rework

读取最新 Gate/Record 中的失败或 STALE 证据，重新形成必要 Worker Assignment。顺序同 plan：先 finish slot=1，再在 resume / next_action=dispatch 时调用 dispatch slot=1。

integrate

1. 汇总 Worker Artifact 和真实业务结果。
2. 对代码交付项目，确保服务端配置的 Business Git 工作区已经形成 clean 最终候选。
3. 先 finish slot=1 status=succeeded。
4. resume / next_action=request_gate 后再请求 Gate：

{"skill_action":"request_gate","slot":1}

服务端会锁定最终候选，并创建 2 号正式 Gate Assignment。

close

只有正式 Gate PASS 后才会出现。先 finish slot=1 status=succeeded；看到 resume / next_action=complete 后再：

{"skill_action":"complete","slot":1}

如果历史 PASS 已因 Business Git HEAD/clean 状态变化而 STALE，服务端会拒绝完成并自动进入 rework；不要绕过。

5. 2 号 Gate

2 号只处理服务端给它的 kind=gate Assignment。

流程：

1. claim slot=2；返回 claimed 时 Execution 已自动 running。
2. 独立检查最终候选，不接受 1/3/4/5 号“代验收”。
3. 用 finish slot=2 status=succeeded 表示 Gate 执行过程本身完成。
4. 看到 resume / next_action=submit_gate 后，再 submit_gate slot=2 写正式结论。

{
  "skill_action": "submit_gate",
  "slot": 2,
  "gate": {
    "profile": "software",
    "verdict": "PASS",
    "business_head_sha": "服务端要求时填写当前候选 commit",
    "checks": [
      {"id": "tests", "result": "PASS", "evidence": "真实测试证据"}
    ],
    "evidence": "独立 Gate 总结"
  }
}

Gate verdict 与 check 只能基于真实证据。Business Git 项目由服务端校验候选 SHA、clean 状态和 STALE 语义。

6. 可用 action

脚本从 stdin 接收单个 JSON 对象，并只输出结构化 JSON。失败返回：

{"ok":false,"error":{"code":"...","message":"..."}}

7. 环境配置

MULTI_AGENT_ORCHESTRATOR_TOKEN 应通过 AgentDock Skill 隔离环境配置。脚本不会输出 Token。

8. 失败与恢复

• idle：不是错误，结束本轮。
• busy：不是错误；新的定时触发不要抢占或重复执行。
• resume：不是新的 Assignment；继续 next_action 指定的协议动作，完成后再领取其他任务。
• HTTP 401：Token 未配置或不匹配。
• HTTP 409：服务端状态已经变化，重新 next/claim，不要根据旧上下文强推。
• Skill 写动作不接受模型手动管理 Execution 生命周期；统一通过 slot 解析当前 Execution。
• finish: failed/interrupted：服务端会把当前 Assignment 重新变为 READY，后续定时任务可重试。
• 控制面重启时会把遗留 queued/running Execution 标记 interrupted 并释放 Assignment。
• 当前 V1.1 不做时间型 lease 自动抢占：如果 Agent 进程被硬杀而 Orchestrator 本身未重启，Slot 会保持 busy，避免误判另一个仍在工作的 Agent。出现持续 busy 时应先确认原执行是否真的死亡，再处理恢复，不要让定时任务自动并发接管。

9. 核心约束

1. Orchestrator 数据库与 Record 是唯一事实源；不要再创建本地编排 Git/Markdown 状态仓库。
2. 角色与权限来自服务端 Assignment/Execution；Skill 不提供 from / role 冒充入口。
3. 2 号 Gate 独立于 1/3/4/5 的执行结果声明。
4. Worker 只做当前 Assignment；不自己派工、不自己改变 Work Item 生命周期。
5. Artifact 必须是真实可访问、可核验的成果，不制造占位卡片。
6. 对代码交付，业务 Git 的 clean HEAD / Gate / STALE 约束由服务端统一执行，不在 Skill 复制第二套状态机。