Agent Switchboard 运维手册

本 Skill 是使用 agent-switchboard MCP（本地跨 agent 协作桥）的操作契约，全部经验来自真实生产使用的事故与验收记录。只负责编排规则；任务本身的修改纪律交给 minimal-implementation，范围澄清交给 clarify-before-change。

适用范围与触发边界

触发边界：存在任一可用委派通道即可触发；随后按任务类型进入相应路由：

1. 存在任一可用委派通道：mcp__agent-switchboard__* 工具，或宿主原生委派机制（如后台 subagent）；
2. 任务属于以下之一：跨模型委派（审查/实现/辩论）、受管长任务执行、监督或收取其他 agent 会话的成果、多窗口并行编排。

不适用场景

• 单会话可直接完成的小型或中型修改：不要为普通任务起 supervisor。
• 环境未安装 agent-switchboard 且也无原生委派通道：不要猜测工具名或要求用户临时安装，安装属于高风险操作，需用户明确授权。
• 纯只读问答：直接回答，不经 broker 绕道。

核心模式：管理者—执行者边界

• 会话管理者（你自己）只负责：定目标与阶段顺序、写完整派工提示词、审阅执行者证据、下返修指令、判定阶段是否通过、向用户汇报。
• 任务规模一律由 task-mode-router 判级，不由"我已经在做了"反推：判为中型及以上的动手操作（调查、读大量文件、编码、改配置、跑构建/测试/数据扫描、Git 提交）委派给受管执行者；判为小型的单会话修改可直接最小修改并验证。执行前记录所选路由与理由（写入派工单或 broker 记录）。
• 管理者允许做有界、只读的独立验收：复跑只读校验脚本、git show/git diff --check、读文件核对哈希/行号/输出。禁止实现、提交、扩大调查范围。
• 执行者自报的 PASS 不是验收依据；验收以独立证据为准（上述只读核验的结果）。
• 互不冲突的任务应主动并行多个受管窗口，无需用户提醒；存在同一文件或同一数据冲突风险的任务在同一窗口排队。
• 执行者窗口验收完成或确认不再需要后立即 close_supervisor / stop_managed_claude_supervisor，不得长期悬挂闲置窗口。

路由规则：确定性选择委派通道

按以下顺序判定，命中即停；执行前记录所选路由与理由：

1. 小型任务直接执行：经 task-mode-router 判级为小型的单会话修改，不走任何委派，直接最小修改并验证。
2. 同厂劳动 native subagent 优先：与当前会话同厂（同厂商/同宿主）的执行类劳动，优先使用宿主原生委派机制（如后台 subagent）。这不是"switchboard 失败后的降级"，而是 broker 自身要求的默认路由。
3. 异厂咨询/审查走 switchboard：跨厂商模型的审查、评审、辩论、咨询，经 route_agent_task / consult_* / queue_*_request 走 broker。
4. 受管 Claude 长任务走 supervisor：需要跨多轮、可归档续接的 Claude 长任务，用 start_managed_claude_supervisor 受管执行。
5. 逐级降级：所需路由的真实调用失败时，才降级到下一可用通道（switchboard → 原生 subagent → 直接执行），并记录降级原因。可用性以真实调用为准：工具未出现在会话声明目录里不等于不可用（热重载可能迟注册），禁止凭目录清单下"无法使用"的结论。
6. 无可用执行者报 BLOCKED：所有通道均不可用时，在验收报告中报 BLOCKED，说明已试通道与失败原因，不硬撑执行。

用户成本偏好：计费 token 与订阅额度并存时，在任务适配、真实可用性和授权边界均满足的前提下优先 MCP 路由（省钱）；不得以此绕过最小权限、认证失败停机或破坏性操作上报规则。

降级通道的能力差异要如实告知用户：宿主 subagent 没有 broker 的事件流、归档和跨会话续接能力；长任务可建议用户安装 agent-switchboard（安装属高风险操作，需明确授权）。

统一监督协议（2026-08-26 沉淀，业界对照联网验证）

受管 supervisor 与 DSH 会话（goal 模式）是两套执行引擎，但应共用一套监督协议—— 业界共识（Langfuse/LangSmith/OTel/Temporal）：观测平台只负责记录，"每个执行器都必须 适配同一组事件与状态字段"，而不是为每个执行器发明一套监督方式。 来源：https://langfuse.com/docs/observability/data-model、 https://docs.langchain.com/langsmith/annotate-code、 https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md、 https://github.com/temporalio/documentation/blob/main/docs/develop/go/activities/timeouts.mdx

三要素监督协议（对任何执行者都检查这三项，不区分 executor_type）：

执行规则：

• 监督任何执行者时，按 ①②③ 三项核对，缺哪项用对应机制补（supervisor 缺摘要→查 agent_events；DSH 会话缺超时→看门狗警告）；
• 事件统一落点：broker agent_events 表（executor_type 列：cli/supervisor/session/subagent）；
• 任务路由（execution 引擎二选一）：交互式/需要思考可见 → DSH 会话；重后台/需要独立进程硬兜底 → 受管 supervisor；监督接口两者一致。

工作流程：受管执行者生命周期

1. 启动：start_managed_claude_supervisor，提供具体 objective、明确 policy（里程碑、安全红线、验收规则）、稳定 supervisor_id。默认 decision_mode=record_only，除非用户要求 Codex 决策。
2. 派工：send_to_managed_claude_session 发送有界任务切片（一次一个可验收的增量），不发开放式大目标。
   • 验收口径开工前回显（2026-08-26 沉淀）：凡任务涉及外部对照目标（如"对照某基准榜/公认值/参考实现"），派工提示词必须写明该目标允许怎么用（仅验收对照 vs 可作调参目标；可调参时注明约束：不要求一一对应、偏差上限、禁止照抄）并要求执行者在步骤 0 回显口径；先开工后改口径 = 返工。来源实证：2026-08-26 论文会话国际公认榜口径 16:14"仅验收"→16:18"可调参"翻转，中间按旧口径下发的任务需返工。
3. 追踪：用 wait_supervisor_event 长轮询等待材料事件；进度可见性来自 wait 本身。禁止自建 cron 或轮询循环做监控。
4. 验收：对照 objective 与 policy 独立核验证据，不接受执行者自述。
5. 关闭归档：close_supervisor 写入归档摘要（做了什么、证据、风险、下一步），供跨会话续接。

生命周期强制收尾（看门狗兜底）

根因：2026-08-24 会话 9 个 supervisor 在验收完成后仍悬挂（leaderboard-reground、impact-gold-rootcause-audit、taskflow-dashboard-update 等全部 attention_required、daemon+claude 存活）。"及时关闭"规则早已存在，缺的是执行拦截——人工"记得 close"不可靠。

收尾不是靠记忆，是靠看门狗兜底：

• 验收后立即 close：验收通过或确认不再需要 → close_supervisor 归档摘要，这是验收流程第 5 步的自然延续。
• 启动时设 stall 兜底：start_managed_claude_supervisor 必填 stall_timeout_seconds（300~600），超时无 token 自动产出 stall 事件供处置。
• 看门狗必须对用户可见：启动长监督/跨轮等待时，必须在回复中报告「下一次检查触发时间」（精确到时分秒，含时区），不能黑箱等待；超时无事件则由 stall 事件接管，管理者不得静默循环。
• 回合结束自查一次：每个 goal round / 长等待结束时，list_managed_claude_supervisors 检查本项目存活 supervisor；任务已完成但仍存活的立即 close；attention_required 的先收集最终结果再关闭。
• stale 记录识别：daemon_alive=false 但状态非终态（stopped/failed）的 supervisor 会带 stale_uncollected: true——daemon 已死无法回收，状态残留；出现时在 checkpoint 登记后清理状态记录，不让它永久残留。
• 返修轮次预算（防套娃，broker 强制）：同一 artifact 的 review→repair 循环最多 2 轮（第 3 轮起被 broker 拒绝）。实现方式：每次 route_agent_task / queue_cli_request 派发同一 artifact 的返修时，必须传 chain_key=<artifact 稳定 id>（同一链同 key）；broker 对同一 chain_key 计数 ≥3 时直接拒绝（chain_budget_exceeded）。若收到该错误：停止该链，重新设计合同（或升级决策），并在验收报告记录 repair_rounds。参照 GitLab retry:max/Jenkins retry(N) 的收敛上限思想。
• 悬挂即处置，不留过夜：任何 supervisor 若已无待处理命令且事件流停滞，即使本回合没有它的结果，也 stop_managed_claude_supervisor 并在 checkpoint 记录，由下一会话续接，而不是长期悬挂。

等待纪律：WAIT 与 GET 不得夹用（防轮询变体）

反模式：2026-08-24 会话 wait_supervisor_event（180s）每次超时返回后立即夹一次 get_managed_claude_supervisor，形成 WAIT→GET 轮询循环，连续 44 分钟无看门狗、无用户可见检查时间。

• wait_supervisor_event 超时返回 ≠ 有事件：直接再次 wait（since_seq 推进到最新已知 seq），禁止在两次 wait 之间夹 get_managed_claude_supervisor / list_managed_claude_supervisors 查询；
• 只有 wait 返回了 material 事件（turn_completed / stall / failed / exited），才去 GET 详情或收结果；
• 长等待依赖 stall_timeout_seconds 的事件驱动兜底，而不是人工每 3 分钟查一次。

跨通道等待纪律总纲（防轻量状态查询轮询）

反模式：2026-08-22 监督会话 pollCount=305（request_status×96、list_agents×265、job_list×15、get_goal×25）——监督者反复调用轻量状态查询工具"看进度"，而非转入单次长轮询。AGENTS.md 模块七/八已确立纪律，这是规则确立后的执行回归（见 evolution-inbox 提案 #1）。业界共识（AWS SQS Long Polling / LangGraph event streaming / Claude SDK streaming 等）：等待应靠"任务句柄 + 单次阻塞等待/事件流 + 超时恢复"，polling 仅限调试。

• 等待阶段唯一合法动作是单次长轮询：派发 subagent / CLI 请求 / supervisor 后，等待结果只能用 wait_supervisor_event / request_result(wait_seconds=60~120) / job_output(wait=true) 单次挂起；
• 轻量状态查询仅限"首次确认请求存在"调用一次：request_status / job_list / list_agents / get_goal / get_topic_status / get_cli_requests / get_codex_requests 等，仅在派发后第一次确认"请求已入队/已存在"时可调用一次；确认后必须转入对应的长轮询工具；
• 禁止把反复无 wait 状态查询当作等待策略：连续 ≥2 次无 wait 的轻量查询即构成轮询反模式，会被 scripts/evolution_scan.js 检测并写入 evolution-inbox；
• 超时接管而非重查：长轮询超时返回 ≠ 通道死亡——直接再次长轮询（推进 since_seq / 同一 request_id），或先查一次在途队列确认存在后继续长轮询；禁止切回短周期查询循环。

跨模型委派规则

• 模型档位与执行层解耦（统一 Provider 优先）：
  • 禁止死板按厂商猜工具：不要将 Gemini 绑定到 Antigravity，也不要将 OpenAI 模型绑定到 Codex CLI。任何注册在 Provider（如 CPA）或 CLI 中的模型均可通过 route_agent_task(target_model=...) 直接分发。
  • 执行层默认使用廉价工作马：默认首选廉价档（如 gpt-5.6-luna、gemini-3.7-flash），两者互为热备；除非用户显式要求前沿档（sol/fable），否则禁止使用昂贵模型。
  • 网络检索/开放调研委托执行层：凡需最新资料、论文检索或外网调研，禁止主会话直接调用 web_search 灌入脏网页，优先委托带搜索能力的执行层 Worker（如 gemini-3.7-flash via CPA）处理并回收提炼摘要。
  • web_search 不可用时的标准通道（CLI worker 搜索）：内置 web_search 工具（web-search-deepseek provider）需要 DeepSeek 官方 API key；未配置或调用失败时不阻塞，改用已登录的 CLI worker 联网搜索：queue_cli_request(backend=codex_cli, target_model=gpt-5.6-luna, effort=medium, prompt="联网搜索…返回URL") → 单次 request_result(wait_seconds=120) 回收。零新增成本、复用已有订阅额度；代价是 1~3 分钟延迟与结构化提示词约束。完整可复制模板见 examples/web-search-via-cli-worker.md。
• 审查/评审/辩论类任务优先派给当前最强模型（如 Codex 的 gpt-5.6-sol max 档），mode=read-only；评审意见作为返修指令来源。
• Gemini 路由：经 consult_gemini / route_agent_task(target_agent="gemini") 走 Gemini CLI 或 Gemini API；适用咨询类任务，与 Codex/Claude 同属异厂咨询通道。
• 权限默认最小：broker 默认的受管权限模式是 acceptEdits，实现类委派先以默认最小权限启动；bypassPermissions 仅在用户明确授权且目标范围受控（有界目录、红线已写入 policy）时才升级使用。
• worker 拒绝执行有两类成因，分别处理：会话模式受限（落在"仅提供建议"的只读会话）→ 检查权限模式与路由，不要盲目升级权限；提示词缺少授权声明 → 在派工提示词开头补显式授权声明，模板见 examples/delegate-implementation.md。
• 遇到认证失败（凭据缺失/过期/配额鉴权错误）或被要求执行破坏性操作（删除数据、重置历史、覆盖未知产物）时，必须停止并上报用户，不得自行升级权限或重试绕过。
• 调研派工必须极窄探针切片：严禁向外部委派“大而全的宏大文献综述课题”；必须切片为 23 个生成耗时 <10 秒的极窄探针（单次 <100 字，结构化事实），510 秒极速回收。
• 多路结果共识直接锁定（Diff-Only）：回收多路结果时，重合度 ≥80% 的共识事实直接采纳入库；严禁因次要格式差异全量重新调研，仅对单一实质冲突点发起微探针核查。
• 大证据用 store_shared_context 压缩传递，接收方按需 retrieve_shared_context，不要把完整转录粘贴进提示词。
• 排队类请求（queue_codex_request 等）用 request_result 长轮询收取，并在汇报中区分"请求的模型"与"实际应答的模型"。

已知陷阱与对策

输出契约

派工时输出派工单；验收时输出验收报告：

派工单：目标 / 边界与红线 / 授权范围 / 所选路由与理由 / 产物落点 / 验收标准 / 回报方式
验收报告：结论（PASS | PARTIAL | BLOCKED）/ 执行机制 / 收据 / 状态 / 独立核验证据 / 偏差与风险 / 下一步

• 执行机制：实际使用的路由（switchboard supervisor / switchboard 队列 / 原生 subagent / 直接执行）。
• 收据：该路由的产物标识——supervisor 为 supervisor_id 与归档摘要；队列为 request_id 与终态；原生 subagent 为其返回的最终报告；直接执行为改动文件清单。
• 状态：该路由的终态（closed/stopped、completed/error/cancelled、子代理已结算、验证已通过）。

向用户汇报时按路由分支给出状态，不凭空估计进度：

• switchboard supervisor 路径：活跃 supervisor 列表及其状态（来自 list_managed_claude_supervisors 或 wait 返回）。
• switchboard 队列路径：排队请求终态（request_result 收取结果）。
• 原生 subagent / 直接执行路径：supervisor=N/A、队列=N/A，汇报子代理结算结果或直接执行的验证输出，不要编造 broker 侧对象。

安全边界与非目标

• 不修改用户级或全局 MCP/模型配置，除非用户明确要求。
• 不使用 send_to_claude_session 前台控制他人终端，除非用户明确要求驱动人工会话。
• 不抓取私人会话内容；快照走 request_context_snapshot 的本地授权通道。
• 不代替执行者写项目代码；管理者的写入仅限 broker 记录（record_work_memory / record_agent_event）。

验证方式

交接或收尾前完成以下可观察检查，按实际路由选择适用项：

通用（所有路由）：

1. 验收报告中的每条证据都可复核（路径、行号、哈希、命令输出）。
2. 所选路由与理由已记录；发生降级时降级原因已记录。
3. 无悬挂执行者、无未收取的结果、无管理者越权写入项目文件。

switchboard supervisor 路径：

4. initialize + tools/list 能连上 broker（新环境先冒烟）。
5. 每个启动过的 supervisor 都有终态：closed / stopped，且有归档摘要。

switchboard 队列路径：

6. 每个排队请求都有终态：completed / error / cancelled，结果已用 request_result 收取。

原生 subagent / 直接执行路径：

7. supervisor=N/A、队列=N/A；核验子代理最终报告或直接执行的测试/校验输出，不要求 broker 侧对象。

相关示例见 examples/。