Long task orchestrator

长任务编排

本技能把长任务拆成“主线程编排 + 独立执行单元 + 机器回执 + 闸门放行”的可验证闭环。它适合需要多个代理、多个窗口、命令任务或人工执行共同完成的任务。

核心角色

• 主线程：只做目标拆解、状态包维护、任务包下发、监控读取、闸门判断和最终放行。
• 独立执行单元：执行边界明确的任务，可以是 Codex 新线程、子代理、命令任务或人工复制任务包。
• 质检执行单元：独立检查证据、回执和产物，不直接替代主线程放行。

恢复前五字段

长任务恢复、上下文压缩后继续、重大返工或高风险产物放行前，主线程必须先检查 状态包/当前状态.json 里的 恢复前检查：

• 原始目标：最终要交付什么。
• 禁止路径：哪些文件、目录或动作不能碰。
• 失败记录：哪些方案试过，为什么失败。
• 待核事实：哪些判断还没有证据。
• 下一步闸门：继续前要看哪份回执、跑哪个校验、等谁确认。

任一字段为空时，先补状态包，不继续下发任务包。

线程监控硬锁

使用 独立线程 时，主线程只能在创建后约 10 秒做一次拉起确认。拉起确认只确认线程存在、状态可读、可重命名或可登记，不检查产物，不判断执行进度。

正式监控必须满足：

• 固定心跳周期为 15 分钟。
• 心跳自动化或等价监控创建失败时暂停调度。
• manual_short_poll_thread_output 必须作为永久阻断动作登记。
• 禁止用短等待、文件存在性检查、线程预览或人工轮询判断产物进度。
• 进度判定只能来自心跳、执行单元主动回执、回执监控文件或用户明确要求的人工介入。

触发条件

命中任一条件时使用本技能：

• 任务预计超过 2 小时。
• 需要读取 3 个以上长文件或跨多个阶段推进。
• 涉及高风险产物，例如代码入口、渲染产物、发布配置、迁移脚本或对外可见交付物。
• 用户要求调用子代理、新窗口、后台任务、长任务机制或交接文件。
• 主线程上下文已经接近拥挤，继续执行会增加漂移或遗忘风险。
• 同类错误复发，需要隔离执行和独立质检回执。

第一步：分派判定

先判断任务属于哪类执行单元：

类型	适合任务	禁止事项
subagent	读材料、证据采集、复核、挑刺、非高风险分析	不写高风险产物，不作为阶段放行依据
独立线程	正式产物、高风险产物、重大返工、正式质检、渲染或发布前验收	不能脱管执行，必须有任务包和回执
命令任务	可重复的本地脚本、测试、构建、静态检查	不能替代需要判断的质检
人工执行	登录、扫码、人工试听、人工审美确认、不可自动化审核	必须写确认记录，不能只口头通过

允许不分派的例外：

• 用户只要求解释、只读复核或极小修改。
• 当前工具不可用，且记录了不可用原因。
• 已有同阶段执行单元正在运行，主线程正在等待回执。
• 用户明确禁止分派。

任何不分派都要写入调度记录。

分派前还要检查恢复前五字段是否存在。恢复状态不完整时，当前任务不是“继续执行”，而是“补齐交接单”。

第二步：创建任务包

每个执行单元都必须拿到任务包。复制 templates/任务包.template.json，至少填写：

• 任务包ID
• 阶段
• 任务目标
• 执行单元类型
• 上游状态版本
• 必读文件
• 允许写入路径
• 授权产物路径
• 禁止触碰路径
• 回执监控路径
• 监控器状态路径
• 动作策略
• 验收标准
• 回传格式

高风险产物只能授权给 独立线程。同一文件同一时间只允许一个执行单元写入。

第三步：下发执行

下发任务时只给执行单元必要上下文：

1. 任务包完整内容。
2. 必读文件清单。
3. 允许写入和禁止触碰边界。
4. 必须产出的回执路径。
5. 创建后拉起确认边界：只确认线程状态，不判断产物进度。
6. 完成后必须停止，不自行开新任务。

不要把主线程全部上下文塞给执行单元。执行单元需要更多上下文时，由主线程补发具体文件或片段。

第四步：读取回执和监控状态

执行单元完成后，只接受机器可读回执。复制 templates/回执.template.json，至少包含：

• 任务包ID
• 执行单元类型
• 输入版本
• 结果
• 读取文件清单
• 产物路径
• 闸门结果
• 失败项
• 阻塞问题
• 下一步建议

主线程先检查监控状态，再检查回执：

1. 监控状态 必须是 已收到回执。
2. 回执 任务包ID 必须匹配任务包。
3. 回执产物必须落在授权路径内。
4. 禁止触碰路径不得被修改。
5. 失败项和阻塞问题为空时，才允许进入闸门判断。
6. 心跳周期分钟 必须为 15。
7. 心跳创建状态 必须为 已创建。
8. 短轮询禁止 必须为 true。
9. 进度判定来源 不得是 manual_short_poll_thread_output、短等待文件检查或线程预览检查。

自然语言“已完成”“已经通过”不能作为放行依据。

第五步：闸门放行

主线程汇总状态包、任务包、回执、监控状态和必要脚本结果后，再决定是否推进阶段。

放行前运行最小校验：

python3 long-task-orchestrator/scripts/validate_orchestrator.py --project <项目目录>

校验通过只代表证据结构合格，不代表业务自动通过。主线程仍要根据验收标准做最终判断。

阻塞处理

• 回执缺失：保持阶段未放行，继续等待或重新下发任务。
• 监控状态未更新：先更新监控状态，再复跑校验。
• 任务包不匹配：驳回回执，不允许用错任务包放行。
• 执行单元越权写入：驳回产物，重新创建受控任务包。
• 高风险产物由 subagent 写入：流程失败，必须改用 独立线程。
• 执行单元被上下文压缩、超时或连续返工超过一次：停止复用，新建执行单元。
• 心跳创建失败：暂停调度，不用短轮询补救。
• 主线程短轮询产物：流程失败，重新登记监控状态并等待心跳或回执。

参考文件

• 协议细则：references/协议说明.md
• Codex 适配：references/Codex适配.md
• Claude Code 适配：references/Claude-Code适配.md
• 脱敏规则：references/脱敏规则.md
• 相邻项目边界：references/相邻项目边界.md
• 模板目录：templates/
• 最小示例：examples/最小闭环示例/