Orchestrator V4#

智能任务编排系统，为主会话提供自动规划和批量派发能力。

核心能力#

规划引擎（纯计算，无外部依赖）#

• scan_task_scope()：扫描文件系统，统计文件数/行数/体积，识别顶层功能模块
• plan_complex_task()：自动拆分子任务，计算超时，生成含文件读取约束的 prompt
• scan_and_plan.py CLI：命令行入口，输出 JSON 供主会话读取和派发
• 任务类型自动识别：analysis > code > debug > research > general 优先级链

大项目智能拆分#

• 大项目检测：超过 1000 文件或 10 万行代码时自动切换大项目模式
• 按模块拆分：按顶层目录识别功能模块，不按文件数机械切片
• 小模块智能合并：文件数 ≤20 且行数 ≤2000 的模块视为小模块，按负载贪心装箱合并（单批上限 60 文件 / 5000 行），减少子代理数量和批次
• 自适应超时：小模块（<20 文件）5min、中模块（20-50 文件）8min、大模块（>50 文件）10min
• 文件读取约束注入：每个子任务 prompt 自动注入"最多读 N 个文件"

派发与执行（主会话通过 sessions_spawn 执行）#

• 滚动派发：按 max_parallel 分批，前一批完成后立即派发下一批
• 超时重试：超时的子任务缩小范围重跑，不原样重试
• 进度追踪：实时进度表格，每个子代理完成时输出关键发现

用户交互控制（主会话原生支持）#

• 用户随时打断：子代理运行期间主会话保持可交互，用户随时可以发消息
• 暂停派发：用户说"暂停"时，主会话停止派发新的子代理（已派发的继续运行至完成或超时）
• 改思路：用户说"改方向"时，主会话调整后续子任务的 prompt 或取消剩余派发
• 恢复：用户说"继续"时，主会话按新的或原有规划继续派发

---

标准执行流程#

Step 1：规划#

bash

cd <skill_dir>/scripts
python scan_and_plan.py \
  --task "用户的任务描述" \
  --target-dir "/path/to/project" \
  --output plan.json \
  --max-parallel 5

输出摘要后告知用户规划结果。

Step 2：读取规划结果#

用 read 工具读取 plan.json，提取 subtasks 列表。每个 subtask 包含：

• description：子任务 prompt（已含文件读取约束）
• estimated_time_sec：超时时间
• module_key：模块名
• module_file_count：模块文件数
• file_read_cap：文件读取上限

Step 3：批量派发#

按 max_parallel（默认 5）取前 N 个 subtasks，逐个调用 sessions_spawn：

text

sessions_spawn(
  agentId: "main",
  label: "orch-{module_key}",
  mode: "run",
  task: subtask.description,
  timeoutSeconds: subtask.estimated_time_sec,
  runTimeoutSeconds: subtask.estimated_time_sec,
)

派发时必须输出任务表格：

text

第 N 批 M 个子代理已派发：

| # | 模块 | 文件数 | 超时 | Label |
|---|------|--------|------|-------|
| 1 | tools | 184 | 600s | orch-tools |
| 2 | services | 136 | 600s | orch-services |
| 3 | hooks | 104 | 600s | orch-hooks |

Step 4：等待完成#

调用 sessions_yield 等待子代理完成推送。不主动轮询。

用户可随时发消息打断：

• "暂停" → 停止派发新的子代理
• "改思路：xxx" → 调整后续子任务 prompt
• "继续" → 恢复派发

Step 5：进度更新 + 滚动派发#

每个子代理完成时：

1. 告知用户关键发现（一句话概括 + 2-3 个 [重要] 标记）
2. 更新进度：N/总数 完成
3. 前一批全部完成后，立即派发下一批（重复 Step 3-4）
4. 小模块可合并派发：一个子代理负责 3-5 个小模块

Step 6：汇总报告#

所有子代理完成后，汇总全部结果写入报告文件。

---

关键配置#

配置默认说明max_files_per_subtask2每子任务最多读文件数（代码生成类）analysis_max_files_per_subtask8分析类每子任务最多读文件数large_project_file_threshold1000大项目文件数阈值large_project_line_threshold100000大项目行数阈值analysis_small_module_timeout300小模块超时（秒）analysis_medium_module_timeout480中模块超时（秒）analysis_large_module_timeout600大模块超时（秒）max_parallel_subagents3同时运行的子代理数

---

与 OpenClaw 原生 subagent 的区别#

能力OpenClaw 原生Orchestrator派发方式手动调用 sessions_spawn，逐个派发自动扫描 → 规划 → 批量派发任务拆分手动编写 prompt 拆分自动按模块/功能域拆分超时控制固定超时（手动传参）自适应超时（小模块 5min、大模块 10min）文件读取约束无约束自动注入"最多读 N 个文件"限制并发控制无限制max_parallel 限流，超出排队失败重试无缩小范围重跑进度追踪手动记录 session_key实时进度表格滚动派发无前一批完成后自动派发下一批用户打断需手动管理随时打断，暂停/改思路/恢复

---

前端输出规范#

派发时#

text

第 N 批 M 个子代理已派发：

| # | 模块 | 文件数 | 超时 | Label |
|---|------|--------|------|-------|
| 1 | xxx | 184 | 600s | orch-xxx |
...

子代理完成时#

text

{模块名} 完成（N/总数）。

**{模块名} 模块关键发现：**
- [重要] 发现 1
- [重要] 发现 2
- [重要] 发现 3

进度：N/总数 完成。

全部完成时#

text

全部 N 个模块分析完成。M 个子代理，零超时。

报告已写入 reports/xxx.md

---

文件说明#

文件说明状态scripts/scan_and_plan.py扫描规划 CLI（Step 1 入口，支持 analyze/fix 模式）已验证scripts/orchestrator_v4_acp.py核心引擎（扫描+规划+上下文管理+并发控制）已验证

---

注意事项#

1. 派子代理时必须输出任务表格

2. 子代理完成时立即通知用户进度和关键发现

3. 执行过程中主会话保持可交互，用户随时可打断

4. 分析类任务的子代理 prompt 必须包含文件读取约束

5. 超时的子任务缩小范围重跑，不原样重试

6. 小模块合并到一个子代理时，prompt 里列出所有模块的目录

7. 用户说"暂停"时停止派发新子代理，说"继续"时恢复

8. 空结果检测与处理：子代理返回结果后，检查内容是否有效：

   • 空结果判定条件（满足任一即视为空结果）：
     • 结果长度 < 100 字符
     • 结果只包含"let me check"、"now let me"、"I have all the context"等中间过程文本
     • output tokens < 200（子代理统计信息中可见）
   • 空结果不一定意味着任务失败：子代理可能已通过工具调用完成了文件写入，只是总结文本被截断
   • 处理流程：
     1. 先检查磁盘：确认子代理是否已创建/修改了目标文件（检查文件是否存在且非空）
     2. 如果文件已创建且内容完整 → 任务实际完成，无需重跑，标记为"文件已就位，总结被截断"
     3. 如果文件不存在或为空 → 真正的空结果，缩小范围重跑
   • 预防措施：
     • 子代理 prompt 中要求"先写文件，最后再输出总结"，确保即使被截断文件也已落盘
     • 单个子代理不要同时读太多文件 + 创建多个文件 + 修改现有文件，容易超 token 限制
     • 如果任务涉及 >3 个文件的创建/修改，考虑拆成更小的子任务
     • 对于纯创建文件的任务，可以在 prompt 中直接给出完整代码，让子代理只负责写入

9. 默认排除目录：扫描器自动排除 .next、node_modules、.git、dist、build、out、.turbo、coverage 等构建产物和依赖目录，无需手动跳过

---

修复模式（v2.2 新增）#

当分析完成后需要批量修复问题时，使用修复模式：

Step 1：准备问题列表#

将审计发现的问题整理为 issues.json：

json

[
  {
    "id": "fix-1",
    "title": "密码改用 bcrypt",
    "priority": "P0",
    "files": ["lib/auth.ts", "app/api/auth/login/route.ts"],
    "description": "将明文密码验证改为 bcrypt.compare()...",
    "depends_on": []
  },
  {
    "id": "fix-2",
    "title": "middleware 添加 role 校验",
    "priority": "P0",
    "files": ["middleware.ts"],
    "description": "JWT 验证后检查 payload.role === 'admin'...",
    "depends_on": ["fix-1"]
  }
]

Step 2：生成修复计划#

bash

cd <skill_dir>/scripts
python scan_and_plan.py \
  --mode fix \
  --issues issues.json \
  --target-dir "/path/to/project" \
  --output fix-plan.json

脚本会自动：

• 按优先级排序（P0 > P1 > P2）
• 操作相同文件的问题合并到一个子任务
• 处理依赖关系（depends_on）
• 计算每个子任务的超时时间

Step 3：按 plan 派发（同分析模式的 Step 3-6）#

也可以跳过 issues.json，直接根据审计报告手动规划修复子任务（适合问题清单已经很清晰的情况）。

---

Python API（需注入 spawn_func）#

以下功能在 orchestrator_v4_acp.py 中完整实现，当前在标准流程中由主会话的 sessions_spawn 替代。将来 OpenClaw 支持 Python SDK 后可直接启用：

• handle()：端到端执行（扫描→规划→派发→收集→汇总）
• 三级 Worker 路由：Fast（本地秒回）、Slow（子代理）、Long（v3_bridge 子进程+心跳）
• 审计质检： enable_audit=True 时代码任务自动过审计官，REJECT 自动重做
• pause_all() / redirect() / resume_with_redirect()：Orchestrator 内部子代理的暂停/改思路控制
• get_progress_report()：Orchestrator 内部的任务统计
• 并发限流： _spawn_semaphore 控制最大并行 subagent 数