control-session-orchestrator

控制会话编排器

将当前会话用作控制平面，处理范围过广、风险过高或状态过于复杂、不适合在一次对话中完成的项目工作。控制会话负责意图、拆解、路由、状态、验证和汇总。工作会话负责范围明确的执行。工作子 Agent 是各工作会话中的本地实现、研究和审计助手。

心智模型

User
  -> Control session (strategy, dispatch, tracking, integration)
       -> Worker project session A (persistent branch/workstream)
            -> Subagents for research, implementation, review, tests
       -> Worker project session B (persistent branch/workstream)
            -> Subagents for local fan-out
       -> Verifier/reviewer session (optional independent gate)

这类似于动态工作流，但编排过程对人类可读，并且原生于会话，而不是运行时脚本。当持久性、分支、PR、人类引导或跨会话连续性比完全自动化的任务分发更重要时，请使用这种方式。

代码运行时可以免费提供可靠性保障（验证结果、屏障、预算、去重、恢复）。提示驱动的控制平面只有在状态可供机器检查时才能获得这些保障。无需运行时也能做到这一点的有两份契约：必需的工作者结果块和持久的控制状态清单（见可供机器检查的契约）。此技能中的其他所有内容都依赖这两项产物——没有它们，“这个工作者是否已完成并通过验证？”就只能靠猜，而不能直接读取字段。

支持的控制应用

此技能与应用无关。首先发现当前会话中有哪些编排工具可用，然后根据对应界面采用相同的控制工作流。

能力	Codex 应用	GitHub Copilot 应用	后备方案
查找工作会话	列出或搜索项目线程	列出或搜索应用会话	请用户提供目标会话链接或 ID
创建持久工作流	在可用时创建或复用 Codex 线程/工作树	在可用时创建或复用 Copilot 应用会话/工作区	仅使用本地子 Agent
引导现有工作流	向线程发送后续提示词	向会话发送后续提示词	请用户将提示词粘贴到工作者会话中
本地任务分发	从本会话启动子 Agent，或请工作者自行启动	使用 Copilot 提供的 Agent/会话工具	在本地完成工作
跟踪	线程标题、置顶项、分支、PR、画布节点、精简状态表	会话名称、分支、PR、议题、画布节点、精简状态表	Markdown 状态表

不要假设 GitHub Copilot 或 Codex 工具的名称。请使用当前环境中提供的工具，并在分派工作者之前说明当前启用的控制界面。

何时使用

以下情况请使用此技能：

• 全代码库审计、迁移或一致性检查
• 跨模块、服务、功能或 PR 的并行调查
• 适合由独立的实现者和验证者会话协作完成的工作
• 需要拆分设计、实现、测试和评审的大型功能
• 类似“协调 Agent”“启动会话”“运行工作流”“让工作者处理此事”“监控其他会话”或“充当控制方”的项目控制提示
• 工作会话本身可能使用子 Agent 进行本地研究、编码或评审的情况

简单的单文件修复、快速解答，或只需一个本地子 Agent 就能完成的任务，不要使用此技能。编排需要额外开销；只有在协调能够降低风险或提高吞吐量时才使用。

可供机器检查的契约

这些契约相当于运行时中的类型化结果和持久运行状态。它们对人类可读，但必须遵守，并非仅供参考——控制会话会解析这些内容以更新状态、去重和决定路由，而不是重新阅读叙述性文字。

工作者结果块

每位工作者的报告都必须以一个带有 control-result 标签的围栏代码块 ```json 结束。控制会话会读取此代码块（绝不读取其周围的叙述性文字），以更新状态、去重并决定路由。

{
  "worker_id": "auth-api",
  "wave_id": "w1",
  "unit_key": "service/auth",
  "scope": "src/auth/** — refresh-token rotation",
  "status": "complete",
  "files_changed": ["src/auth/rotate.ts"],
  "verification": { "command": "pnpm test auth", "result": "pass", "evidence": "42 passed" },
  "subagents_used": "2 — one research, one test author",
  "risks": ["rotation interacts with logout; covered by test"],
  "next_step": "ready for review session",
  "report_ref": "thread/PR/path to the full report"
}

代码块必须是严格 JSON（不得包含注释或尾随逗号），以便解析。status 的值必须是 complete | blocked | needs-decision | failed 之一；verification.result 的值必须是 pass | fail | not-run 之一。

控制状态清单

一份持久化的工件，即任务的事实来源——置顶的控制线程、跟踪 issue 正文、画布节点，或已提交的 control/state.json。每轮都重新读取并更新它；对话用于决策，而非记录状态。每个单元占一行（以单元为键，因此同一单元绝不会被派发两次——这是去重台账）。

{
  "mission": "MCP tool parity audit",
  "non_goals": ["no behavior changes"],
  "success_criteria": ["every tool present in server, HTTP, SDK, docs or flagged"],
  "budget": { "max_concurrent_workers": 5, "max_total_workers": 25, "spawned": 0, "in_flight": 0 },
  "convergence": { "rule": "single-pass", "k_empty": 2, "empty_streak": 0, "target": null, "current": 0 },
  "worker_contract": { "schema_name": "control-result/v1", "required_output_schema": null },
  "batch_guard": {
    "service_key": null,
    "pilot_unit_key": null,
    "pilot_status": "not-required",
    "pause_after_same_signature": 2,
    "paused": false,
    "failure_signatures": {}
  },
  "workers": [
    {
      "unit_key": "surface/http",
      "worker_id": "http-audit",
      "session_ref": "thread-or-session id/link",
      "scope": "HTTP API surface",
      "branch_or_pr": "—",
      "status": "pending",
      "wave_id": "w1",
      "last_update": "ISO-8601",
      "evidence_ref": "report_ref from the result block",
      "verification": "not-run",
      "blocker": null
    }
  ],
  "decisions": [],
  "open_followups": []
}

规则：

• 工作者状态（工作者在其结果块中自我报告的状态）：complete | blocked | needs-decision | failed。
• 清单单元状态（控制会话维护的超集）：pending | dispatched | needs-decision | blocked | stalled | complete | failed | dropped。工作者报告的值是其中的子集，因此根据工作者结果块设置单元状态（步骤 5）始终有效。
• 终止状态——单元已关闭——包括 complete | failed | dropped。其他状态均为非终止状态，必须在任务关闭前解决，或明确转换为 dropped 并说明原因（步骤 8）。
• budget.in_flight 是当前状态为 dispatched 的行数。派发时递增 spawned 和 in_flight；单元离开 dispatched 状态时递减 in_flight；重新载入时，根据各行重新计算该值。
• convergence.rule 的取值为 single-pass | loop-until-dry | loop-until-budget | accumulate-to-target。k_empty/empty_streak 仅用于 loop-until-dry；target/current 仅用于 accumulate-to-target（target = 数量或覆盖率目标，current = 当前进度）。
• worker_contract.required_output_schema 在调用方提供了结构化输出架构时，保存其原文。默认契约为 control-result/v1；绝不可改述或悄然替换外部架构。
• batch_guard 记录同质外部服务批次的试运行结果和规范化故障特征。service_key 标识共享依赖，而非单个项目。
• 被丢弃/失败的单元必须在 open_followups 中附带原因。

新的控制会话将根据此清单重新载入状态（步骤 0）。

控制工作流

0. 重新载入状态（恢复进行中的任务）

会话开始时，查找此任务是否已有控制状态清单。如果有：

• 加载清单；将其视为事实来源。
• 通过 session_ref 重新连接工作者，并在任何新派发之前，核对每个工作者的实际状态（读取线程/PR）。
• 根据仍标记为 dispatched 的行重新计算 budget.in_flight。
• 不要重新派发状态为 dispatched 或 complete 的单元——改为安排后续工作。

如果没有清单，则这是一个新任务——在步骤 1 中创建清单。

1. 界定任务

在启动任何工作者之前，记录以下内容（并写入清单）：

• 目标和非目标
• 涉及的仓库、分支、PR 或 issue
• 每个工作流的文件或子系统边界
• 成功标准和验证关卡
• 合并/集成预期
• 任何“不得触碰”的限制
• 调用方或执行环境要求指定时，工作者输出架构的原文
• 多项目批次使用的任何共享外部服务

同时预先设定明确限制（清单中的 budget 和 convergence）：

• max_concurrent_workers（默认约为 4–6）——同时进行的工作者数量不得超过此值
• max_total_workers——整个任务的生命周期上限（例如 25）
• 可选的 token / 成本 / 时间上限
• 收敛规则：有界任务使用 single-pass；开放式审计/迁移/一致性扫描使用 loop-until-dry、loop-until-budget 或 accumulate-to-target

如果任何边界含糊不清，且可能导致编辑冲突，请在派发前询问。

2. 检测控制界面

分派前，识别可用的应用工具：

• Codex 应用：线程/会话工具，例如列出、创建/读取、发送消息、重命名、置顶/归档，以及 可选的本地子 Agent 工具。
• GitHub Copilot 应用：应用连接器提供的会话或工作区工具，以及可用的 GitHub issue/PR/分支控制工具。
• 通用 Agent 应用：会话、任务、子 Agent、分支、issue、PR 或自动化工具的任意组合。

如果没有可用的持久会话工具，则降级为本地多 Agent 方案，并说明此限制。不要虚构后端。

3. 选择拓扑

选择最精简且实用的拓扑：

• 单个工作者：应在独立项目会话中完成的隔离实现或错误修复
• 并行工作者：相互独立的模块、软件包、端点、测试或文档
• 先研究再实现：先由探索会话报告发现，再开始编码
• 实现者 + 验证者：一个会话修改代码，另一个独立审查或验证
• 仅控制：暂不启动工作者；只检查状态、列出会话或规划分派

如果工作者可能编辑重叠的历史记录、需要不同分支，或需要长期上下文，优先使用独立会话。如果任务是探索性的，且不需要持久分支状态，则优先在单个会话中使用本地子 Agent。

4. 使用完整提示词分派工作者

遵守预算：当 in_flight >= max_concurrent_workers 时，绝不分派——将工作单元排队（status: pending）并记录。达到 max_total_workers 或 token/成本上限时，停止分派并提出需要决策，不得继续启动工作者。分派是一次原子清单更新：将工作单元的行设为 status: dispatched（填写 session_ref、worker_id、wave_id、last_update），并同时递增 spawned 和 in_flight；如果分派未能启动，则将该行保留为 pending，且两个计数器都不递增。工作单元离开 dispatched 状态时（进入终止状态，或返回 needs-decision/blocked/stalled），递减 in_flight，以便启动排队的工作单元。这样可确保 in_flight 等于 Step 0 重新计算的 dispatched 行数。

每个工作者提示词都应自包含。内容包括：

• 任务和确切范围（以及其 unit_key）
• 文件、子系统、issue/PR 链接和分支要求
• 工作者可以和不可以修改的内容
• 验证命令或验收标准
• 是否可以创建提交、PR，还是只能汇报
• 所需的输出约定

工作者提示词模板：

You are worker <name> for <project>.

Mission: <specific outcome>
unit_key / wave_id: <key> / <wave>
Scope: <files/subsystems/issue/PR>
Do not touch: <boundaries>
Approach: <expected plan or constraints>
Verification: <commands/checks/evidence>
Required output schema: <exact JSON schema, or "control-result/v1">
Submission format: <default control-result block, or exact external-schema instruction>

You MAY use your own subagents for local research, implementation, and review, but you remain
accountable for this scope and the final report. Do NOT create or steer further persistent project
sessions — if the work needs another full workstream, say so in next_step.

Follow the submission format exactly and validate the payload against the required output schema
before submission. The control session reads only that payload.

对于 control-result/v1，将提交格式设为带围栏的 json control-result 代码块，并填写所有字段，包括 subagents_used。当调用方要求使用不同的 schema 时，应原样存储并包含该 schema，包括所有必需的根键和类型，并告知工作者必须严格按该 schema 返回，不得使用 control-result 包装。如果执行界面提供结构化输出验证，则使用相同的 schema 进行配置；对于不提供此功能的界面，不要虚构参数。分派前，定义并测试一个从外部 schema 到控制清单的无损适配器。若没有这样的适配器，则返回 needs-decision，而不是近似处理任一约定。

使用 Codex 应用控制工具时，优先重命名并置顶重要的工作者/控制线程，以便清晰查看会话关系图。使用 GitHub Copilot 应用控制工具时，如果提供相应的会话或工作区标签，则使用它们。

试运行共享服务批次

在通过同一外部服务派发大型同质批次之前：

1. 设置 batch_guard.service_key，并选择一个代表性的 pilot_unit_key。
2. 仅派发试运行单元；其余单元保持 pending。
3. 只有试运行单元返回符合架构的结果并通过验收检查后，才放行整个批次。

不同的项目 ID 并不意味着故障彼此独立。如果两个不同单元出现相同的规范化故障签名，请设置 batch_guard.paused: true，停止通过该服务启动排队中的任务，并报告阻塞原因。只有在诊断或输入发生实质性变化，或明确决定接受风险后，才能恢复。

5. 集中跟踪状态

控制状态清单是唯一事实来源——每轮都更新清单，而不是对话。从每个已接受的工作线程结果中（必要时先应用经过测试的适配器），设置单元的 status、evidence_ref、verification；当 status 为 blocked 或 needs-decision 时，还要设置 blocker（否则设为 null）。对于 control-result/v1，这些字段分别映射自 report_ref、verification.result 和阻塞原因。控制会话自行记录其余字段：使用自身时钟填写 last_update，并在已知时根据工作线程的会话／PR 元数据设置 branch_or_pr。控制会话的上下文应聚焦于摘要和决策，而非完整对话记录；完整报告保存在 evidence_ref 中。

每个单元至少跟踪以下信息：unit_key、worker_id、session_ref、范围、状态、分支／PR、最后更新时间、阻塞原因和验证状态——与上述行架构一致。如果应用提供画布节点或 SQL／待办事项表，可将其用作清单的后端。

6. 路由后续处理（结果门控）

工作线程报告结果后，先运行结果门控：

• 解析 worker_contract 要求的载荷：默认契约要求 fenced control-result 块，否则要求完全匹配的外部载荷。如果缺少必需字段或格式错误，请勿接受——只发送一次标准化的重新提示，仅要求提供更正后的载荷。最多重试 2 次，然后升级给用户。
• 对于外部架构，在应用经过测试的适配器之前，验证每个必需的根键、类型和枚举值。即使默认 control-result 有效，但不符合调用方的精确架构，也仍然无效。
• 验证和应用适配器后，如果完成状态与证据冲突，则拒绝该结果。status: complete 通常要求 verification.result: pass。
• 只有当清单范围和成功标准明确说明运行时验证不在范围内、files_changed 为空，且证据引用了已检查的来源并满足这些标准，同时未声称未经测试的运行时行为时，已完成且基于来源的只读研究单元才可以使用 verification.result: not-run。在清单中如实记录 not-run。工具不可用、遗漏检查，或任何实现／配置变更，都不属于此例外；此类工作必须作为未经验证的工作予以拒绝。
• 只有在结果块通过验证且满足成功标准后，才接受已完成的工作。

然后进行路由：

• 对缺失的验证、范围偏移或阻塞原因，发送有针对性的后续请求。
• 避免重复工作线程已开展的调查，除非其结果不完整或可疑（先检查单元台账）。
• 如果两个或更多工作线程的结果相互冲突，请暂停集成，并在进行更多编辑之前厘清责任归属。
• 通过移除易变的项目 ID、请求 ID 和时间戳，规范化重复的外部服务故障。在 batch_guard.failure_signatures 中记录签名和受影响的单元键；达到配置的阈值时，暂停使用该服务的排队单元。瞬时重试可以采用有界退避，但对于已出现相同故障的服务，绝不能同时发起大量重试。

7. 迭代各轮，直至收敛

对于多轮任务，在分派一轮的后续工作后，先应用声明的 convergence.rule，再进行汇总：

• single-pass — 仅执行一轮；跳到汇总。
• loop-until-dry — 持续开启工作单元，直到连续 k_empty 轮都没有产生新的（去重后）工作单元；在清单中维护 empty_streak。
• loop-until-budget — 达到预算上限时停止。
• accumulate-to-target — 达到目标数量/覆盖范围时停止。

“新”和“无新增”以清单中的 unit_key 集合为准，而非依靠记忆。不得悄然停止——应在 open_followups / decisions 中说明迭代结束的原因。

8. 验证并汇总

宣布任务完成前：

• 运行或委派双方约定的验证关卡。
• 检查差异，或请独立审查会话提供高价值发现。
• 确保工作线程的输出已整合到正确的分支/会话中。

轮次汇合/完整性关卡： 只有当清单中的每一行工作线程记录都处于终止状态——complete、failed 或 dropped——任务才算完成。非终止状态（pending、dispatched、needs-decision、blocked、stalled）必须先解决；无法解决的工作单元——例如，工作线程到检查点时仍未报告，因而被标记为 stalled——必须明确转换为 dropped 并说明原因。此后才能将任务声明为 “已完成，另有 N 项已丢弃：<ID + 原因>”。不得以非终止状态的记录结束任务，也不得静默丢弃。最终摘要中应列出每个已分派的工作单元。

拉取节奏（无推送信号时）： 基于会话的控制平面没有“工作线程已完成”事件来唤醒它。分派一轮后，应定义下一个检查点触发方式——后续轮次、状态表轮询或用户提醒——并确保每一轮都完成汇合。

对于与 PR 相关的工作，由控制会话负责最终 PR 就绪情况和审查安排。

安全规则

• 不要为琐碎任务启动工作线程。
• 除非明确协调，否则不要让多个工作线程编辑同一文件。
• 不要假设存在指定的应用连接器；应先发现它，并如实使用备用方案。
• 不要擅自创建分支、提交、推送或 PR；遵循用户授权和仓库规则。
• 不要要求工作线程跨会话分享机密或敏感数据。
• 工作线程子 Agent 是叶节点助手——严禁创建或引导更多持久会话。层级严格为两层（控制会话 -> 工作线程 -> 子 Agent）；如果工作线程需要另一个完整工作流，应向控制会话报告这一需求。
• 严格遵守并发和总分派量上限；绝不可悄然超出。已丢弃、跳过或失败的工作单元都必须记录原因（不得静默截断）。
• 对大型、同质的外部服务批次先进行试运行；若反复出现相同的故障特征，应暂停。
• 如果使用原位检出，请格外谨慎：其中可能已有其他用户的改动。
• 如果计划发生实质性变化，请在继续前告知用户和工作线程。

建议的报告格式

使用简洁的控制平面更新（根据清单生成各行）：

**Status:** <on track | blocked | needs decision | complete>
**Budget:** in-flight <X/Y> · spawned <A/B> · wave <N> (empty-streak <E>)

| Workstream | Session | Scope | State | Evidence |
|---|---|---|---|---|
| <name> | <id/name> | <scope> | <state> | <test/report/PR> |

**Decision needed:** <only if blocked>

面向用户的更新应简洁。控制会话应清楚呈现协调情况，不要用每个工作线程的完整对话记录淹没用户。