mesh

mesh

意图

$mesh 是 Codex 的高扇出批量执行路径，适用于重复的叶级工作已整理成形之后。

它用于已整理成形的叶级工作，不用于规划或分解。

在以下情况下使用：

• 用户明确要求使用 $mesh，或者重复的叶级工作已经清晰地按行组织
• 工作负载按行组织且具有同质性
• 每一行都可以独立处理
• 每一行都代表一个实质性单元，且有唯一的范围和验收目标
• 你希望将每行的结构化结果导出到 CSV
• 规划已完成，剩下的工作是叶级执行

在以下情况下不要使用：

• 工作属于研究、审查、辩论或设计
• 任务仍需要分解或共享判断
• 任务共享上下文或相互依赖
• 多个工作者会修改同一个可变范围
• 直接通过 spawn_agent 委派或在本地执行更清晰

与原生架构的契合

• $mesh 对应 spawn_agents_on_csv，而非独立的运行时协议。
• 批处理作业会为每一行 CSV 启动一个工作者子 Agent。
• 主调用会一直阻塞，直至批处理完成。
• 每个工作者都必须恰好调用一次 report_agent_job_result。
• 结果会导出到 output_csv_path 指定的位置，或默认的输出 CSV 文件。
• 规划在批处理开始前完成；$mesh 执行的是已整理成形的行。

推荐用途

• 每行审计一个文件
• 每行分类一张工单、一段日志或一份文档
• 从大量输入中提取结构化字段
• 对文件列表执行相同的有限转换，且输出互不重叠
• 在 $select 或 $teams 已整理好执行批次后，每行执行一个互不重叠的实现单元

如果工作内容异质，请改用 $teams 或直接使用 spawn_agent。

复合任务与叶级任务的契合度

仅当每一行都是叶级任务时才使用 $mesh：

• 输入来自 CSV 列，且清晰明确
• 所有行共用一个指令模板
• 行与行之间无需协调
• 每行产生一个结构化结果

如果你仍需要确定行的结构、质疑方案或比较策略，请在使用 $mesh 之前完成这些工作，通常可使用 $teams 或在本地完成。

实质性单元规则

• 一行应代表一个独特的工作单元，具有唯一的读写范围和一个验收目标。
• 不要仅为了增加通道、证据或并发数，就在同一范围上重复创建多行。
• 将一条干净的主行视为该单元的充分证据。
• 仅当先前的行报告了具体阻碍、证明失败或需要再次处理的非平凡差异时，才添加次级审查、编码、修复、证明或集成行。
• 已弃用的垫片（reducer、mentor、locksmith、applier）绝不能作为新建行。

推荐流程

1. 确认规划已完成，且各行确实同质、相互独立。
2. 使用稳定的表头构建 CSV；必要时设置稳定的 id_column，并确保每个实质性单元各占一行。
   • 如果批次来自 OrchPlan 或 $st 声明集，优先使用 task_id 作为稳定的行 ID。
3. 编写一个使用 {column} 占位符的指令模板，并为每行指定一个主要交付物。
4. 只选择所需的控制项：output_schema、output_csv_path、max_concurrency、max_runtime_seconds；将 max_concurrency 设为安全的行数，除非需要设置更低的上限。
5. 运行 spawn_agents_on_csv。
6. 仅为报告了具体阻碍、证明失败或需要再次处理的非平凡差异的单元排入次级行。
7. 审查导出的 CSV，并在本地或使用 $teams 完成集成或后续工作。
   • 如果执行状态由 $st 管理，请在关闭批次前使用 st import-mesh-results --input <output.csv> 同步导出结果。

具体示例

示例 1：每行审查一个文件

目标：

检查每个 Markdown 文件是否包含必需的 frontmatter 键，并为每个文件导出一行结果。

示例 CSV：

id,path
1,docs/intro.md
2,docs/setup.md

示例指令模板：

Inspect {path}. Report whether the required frontmatter keys exist and list any missing keys.

为什么使用 $mesh：

• 每一行使用相同的模板
• 每一行都是独立的
• 可以将结果捕获为每个文件对应的一个结构化对象

示例 2：对支持工单分类

目标：

按产品领域和紧急程度对 2,000 个支持工单进行分类，然后将标签导出为 CSV。

示例 CSV：

ticket_id,text
T-1001,"Billing page shows a 500 error"
T-1002,"How do I rotate an API key?"

示例输出架构：

{
  "type": "object",
  "properties": {
    "area": { "type": "string" },
    "urgency": { "type": "string" },
    "needs_human": { "type": "boolean" }
  },
  "required": ["area", "urgency", "needs_human"]
}

为什么使用 $mesh：

• 这是重复的只读分类工作
• 架构让每行输出易于比较和后处理

示例 3：对互不重叠的文件进行转换

目标：

重写大量生成的摘要，每个输入文件对应一个输出文件，且输出位置互不重叠。

合适的 $mesh 设置：

• CSV 列如 id,input_path,output_path
• 一个读取 {input_path} 且只写入 {output_path} 的指令模板
• 一个 JSON 结果，用于确认该行是否成功

为什么使用 $mesh：

• 写入范围互不重叠
• 对每一行重复执行相同的、有明确边界的转换

示例 4：互不重叠的实现单元

目标：

执行 OrchPlan 中第一批安全的实现任务，其中每项任务都有各自互不重叠的范围。

合适的 $mesh 设置：

• CSV 列如 id,objective,write_scope,proof_command
• 每个实现单元对应一行主任务，而不是每个审查通道对应一行
• 将 max_concurrency 设为安全且互不重叠的单元数量
• 仅为验证失败或报告阻塞问题的单元添加后续验证者或修复者任务行

为什么使用 $mesh：

• 规划完成后，工作就是重复执行叶级任务
• 每一行都有唯一范围和明确的验收目标
• 批处理可以真正并行扩展，无需虚构合成的证据通道

反例：跨共享代码实现单一功能

不要将 $mesh 用于：

添加一项会修改共享解析器逻辑、服务端行为和 UI 的功能。

原因：

• 工作仍需拆解和协调
• 各行并不独立
• 存在共享可变文件时，使用 $teams 或本地执行更安全

行设计规则

• 每行的目标都应具体且有明确边界。
• 每行应构成一个实质性单元，具有唯一范围和验收目标。
• 让 write_scope 遵循 codex/skills/select/references/lock-roots.md 中的规范锁定根目录约定。
• 优先选择只读工作或互不重叠的写入范围。
• 让结果对象保持结构化，并确保各行之间可比较。
• 如果之后需要汇总输出，请使用稳定的行 ID。
• 除非阻塞问题或验证失败足以证明需要后续处理，否则不要针对同一范围按角色或通道增加任务行。
• 如果需要归约思路，请在 coder 中通过设置 approach=reduce 来实现；不要将 reducer 重新作为一种新的行类型。
• 如果各行需要共享可变状态，请停止并改用非 $mesh 方案。
• 如果某一行仍需规划，请停止并在运行批处理前完成拆解。

结果约定

• 每个工作者都必须通过 report_agent_job_result 恰好报告一个 JSON 结果。
• 缺少报告即视为失败。
• 叙述性文本不具权威性；结构化结果才是判断依据。
• 如果提供 output_schema，请保持其精简，并与实际所需字段一致。

请参阅 references/output-contract.md。

反模式

• 将 $mesh 用作 $teams 的通用替代方案
• 在批处理工作者中进行递归规划或辩论
• 将一个紧密耦合的实现拆分到相互依赖的行中
• 各行的写入范围相互重叠
• 实质性工作已完成后，再启动一轮合成证据收集
• 在同一范围内无正当理由地增加 coder/fixer/prover/integrator 行；正当理由应由阻塞项触发
• 将新工作交给已弃用的兼容层，而不是当前的核心角色
• 依赖自由格式文本，而不是结构化结果字段
• 为 csv_path 和 output_csv_path 使用相同路径

参见 references/orchestration-anti-patterns.md。

最终回复

实际运行 mesh 时，请在正文中简要列出 Orchestration Ledger。

适用的字段：

• Skills used
• Subagents
• Artifacts produced
• Cleanup status

如果没有运行编排，则完全省略此部分。

从 $teams 移交

如果 $teams 将工作移交给 $mesh，移交内容应包括：

• 确认规划已完成，仅剩叶子节点执行
• CSV 或行架构
• 指令模板
• 预期输出字段
• 并发或超时假设

除非运行时实际提供额外的泳道、法定人数或状态机协议，否则不要添加这些协议。