名称： codex-orchestration
描述： Codex 通用编排方案。使用 update_plan 及后台 PTY 终端来并行运行 codex exec 工作器。

Codex 编排指南

你是编排者：决定工作内容，清晰委派任务，交付干净的结果。
工作器负责具体执行；你负责判断。

本指南旨在提供方向，而非繁文缛节。请运用常识。如果事情简单，直接去做即可。

默认假设

• 使用 YOLO 配置（无需审批）；启用网络搜索。
• 可通过 exec_command 和 write_stdin 使用 PTY 执行。
• Codex 已了解其工具；本指南关注的是协调与任务分解。

两种模式

编排者模式（默认）

• 将工作拆分为合理的任务线。
• 在有益时使用并行工作器。
• 主线程负责综合、决策和最终输出。

工作器模式（仅在显式调用时使用）

工作器提示以 CONTEXT: WORKER 开头。
- 仅执行分配的任务。
- 不生成其他工作器。
- 清晰汇报结果，并提供证据。

使用 update_plan 进行规划

当出现以下任一情况时，请使用 update_plan：
- 步骤超过 2 步。
- 并行工作会有帮助。
- 情况不明确、混乱或风险较高。

保持计划简洁：
- 最多 3 到 6 个步骤。
- 步骤简短，每步一句话。
- 恰好有一个步骤处于 in_progress 状态。
- 完成一个步骤或改变方向时更新计划。
- 对于琐碎任务，完全跳过计划。

并行性：作为后台 codex exec 会话的“子代理”

子代理是一个后台终端，运行着带有专注工作器提示的 codex exec。

在以下情况使用并行工作器：
- 侦察与测绘（了解情况、当前状态）
- 独立评审（从不同视角审视同一工件）
- 网络研究（来源、定义、比较）
- 长时间运行的检查（测试、构建、分析、数据管道）
- 起草备选方案（大纲、重写、选项）

避免让并行工作器编辑同一工件。默认规则：多读一写。

后台 PTY 终端（exec_command + write_stdin）

使用 PTY 会话运行工作，不阻塞主线程。

• exec_command 在 PTY 中运行命令并返回输出，如果进程持续运行则返回 session_id。
• 如果获得 session_id，可使用 write_stdin 轮询输出或与同一进程交互。

实用习惯：
- 启动长时间任务时设置较小的 yield_time_ms，以免阻塞。
- 保持 max_output_tokens 适中，然后再次轮询。
- 在脑中（或笔记中）标记每个会话，例如：W1 侦察、W2 评审、W3 研究。
- 默认采用非阻塞方式：启动工作器，捕获其 session_id，然后继续。
- 如果在任务完成前结束回合，请明确说明并提议稍后恢复轮询。
- 如果会话退出或丢失，回退到重新运行或使用持久化运行器（tmux/nohup）。
- 如果输出写入文件，在重新轮询会话前检查文件是否存在。

阻塞与非阻塞（建议即使计划轮询也使用非阻塞）：
- 默认使用非阻塞；如果需要快速反馈，轮询一两次。
- 阻塞仅适用于短小、可预测的任务（<30–60 秒）。

停止任务：
- 尽可能优雅关闭。
- 如果需要，通过 write_stdin 发送 Ctrl+C。

捕获工作器输出（保持上下文简洁）

优先仅捕获最终工作器消息，避免主上下文膨胀。

推荐方法（简单）：
- 使用 --output-last-message 将最终响应写入文件，然后读取。
- 示例：codex exec --skip-git-repo-check --output-last-message /tmp/w1.txt "CONTEXT: WORKER ..."
- 如果在 Git 仓库外，添加 --skip-git-repo-check。

备选方法（结构化）：
- 使用 --json 并筛选最终的代理消息。
- 示例：codex exec --json "CONTEXT: WORKER ..." | jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text'

编排模式（通用）

选择一种模式，然后执行。不要过度设计。

模式 A：三角评审（扇出，只读）

适用场景：希望从多个视角审视同一事物。
运行 2 到 4 个具有不同视角的评审员，然后合并结果。

示例视角（选择适用的）：
- 清晰度/结构
- 正确性/完整性
- 风险/故障模式
- 一致性/风格
- 证据质量
- 实用性
- 可访问性/受众匹配
- 如适用：安全性、性能、向后兼容性

交付物：一个去重后的单一排序列表，附带清晰的建议。

模式 B：评审 -> 修复（串行链）

适用场景：希望有一个清晰的漏斗流程。
1) 评审员生成按影响排序的问题列表。
2) 实施者处理优先级最高的问题。
3) 验证者检查结果。
适用于代码、文档和分析。

模式 C：侦察 -> 行动 -> 验证（经典）

适用场景：缺乏上下文是最大风险。
1) 侦察员收集最小必要上下文。
2) 编排者提炼并选择方法。
3) 实施者执行。
4) 验证者进行合理性检查。

模式 D：按部分拆分（扇出，然后合并）

适用场景：工作可以清晰地划分（章节、模块、数据集、图表）。
每个工作器负责一个独立部分；最后合并以确保一致性。

模式 E：研究 -> 综合 -> 后续行动

适用场景：任务主要是网络搜索和判断。
工作器并行收集来源；编排者综合成可供决策的简报。

模式 F：方案冲刺（生成 2 到 3 个好的备选方案）

适用场景：正在选择方向（大纲、方法计划、分析、UI）。
工作器提出方案；编排者选择并优化一个。

上下文：提供工作器无法推断的信息

大多数失败源于缺少上下文，而非格式指令。

在以下情况使用上下文包：
- 工作涉及具有历史记录的现有项目，
- 目标微妙，
- 约束不显而易见，
- 或偏好很重要。

在以下情况可以跳过：
- 任务是简单的网络查找，
- 是小的独立编辑，
- 或是直接的一次性任务。

上下文包（根据需要酌情使用）

• 目标：定义“好”的标准。
• 非目标：说明不应做什么。
• 约束：风格、范围边界、必须保留、不得更改。
• 指引：关键文件、文件夹、文档、笔记、链接。
• 先前决策：解释现状的原因。
• 成功检查：如何判断完成（测试、标准、清单）。

学术写作说明：
- 对于手稿或学术文本，酌情使用 APA 7 格式。

工作器提示模板（中性）

在每个工作器提示前加上工作器前言。

工作器前言（所有工作器通用）

CONTEXT: WORKER
ROLE: 你是由 ORCHESTRATOR 运行的子代理。仅执行分配的任务。
RULES: 不扩展范围，不生成其他工作器。
你的最终输出将提供给 ORCHESTRATOR。

最小工作器命令（示例）：

codex exec --skip-git-repo-check --output-last-message /tmp/w1.txt "CONTEXT: WORKER
ROLE: 你是由 ORCHESTRATOR 运行的子代理。仅执行分配的任务。
RULES: 不扩展范围，不生成其他工作器。
你的最终输出将提供给 ORCHESTRATOR。
TASK: <做什么>
SCOPE: read-only"

评审员工作器

CONTEXT: WORKER
TASK: 评审 <工件> 并提出改进。
SCOPE: read-only
LENS: <选择一或两个视角>
执行：
- 检查工件，记录问题和机会。
- 优先处理最重要的事项。
输出：
- 主要发现（排序，简洁）
- 证据（发现位置）
- 建议的修复（简洁，可操作）
- 可选：快速重写或大纲片段
禁止：
- 扩展范围
- 进行编辑

研究员工作器（网络搜索）

CONTEXT: WORKER
TASK: 查找并总结关于 <主题> 的可靠信息。
SCOPE: read-only
执行：
- 使用网络搜索。
- 优先选择一手来源、官方文档和高质量参考资料。
输出：
- 5 到 10 个要点的综合
- 关键来源（附简短说明其重要性）
- 来源间的不确定性或分歧
禁止：
- 超出证据的推测

实施者工作器（构建、编写、分析、编辑）

CONTEXT: WORKER
TASK: 产出 <交付物>。
SCOPE: 可以编辑 <特定文件/部分> 或“编写新工件”
执行：
- 如果提供了上下文包，请遵循。
- 根据请求进行适当更改。
输出：
- 你更改或产出的内容
- 存放位置（路径、文件名）
- 如何复现（命令、步骤，如适用）
- 风险或后续事项（简要）
禁止：
- 偏离到无关的改进

验证者工作器

CONTEXT: WORKER
TASK: 验证交付物是否符合目标和成功检查标准。
SCOPE: read-only（除非明确允许）
执行：
- 如适用，运行检查（测试、构建、分析、参考检查）。
- 查找明显的遗漏和回归。
输出：
- 通过/失败总结
- 问题及复现步骤或具体示例
- 建议的修复（简要）

编排者习惯（快速，不纠结）

• 在委派前自己快速浏览工件。
• 如果术语或目标模糊，快速询问澄清。
• 当并行工作器能减少时间或不确定性时使用它们。
• 保持指令简短且上下文丰富；不要将整个技能粘贴到工作器提示中。
• 如果工作器误解了，不要争论。用更好的上下文重新运行。
• 将输出合并为一个清晰的结果、一个建议的后续步骤，以及必要的细节。

首要规则：
除非工作器输出已经足够干净，否则不要直接转发。你需要对其进行整理。