orchestrator-v4

智能任务编排系统。自动扫描项目规模、规划子任务、动态派发多个 AI Worker 并行执行，支持大项目按模块拆分、自适应超时、滚动派发、用户随时打断改思路。触发条件：用户需要处理复杂任务、多步骤分析、代码生成、调试分析、研究调查或需要智能调度 AI Worker 时。

Audits

Pass

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalstale

Multi-engine malware detections and file reputation.

Install

openclaw skills install orchestrator-v4

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：规划

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：

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

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

第 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：进度更新 + 滚动派发

每个子代理完成时：

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

Step 6：汇总报告

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

关键配置

配置	默认	说明
`max_files_per_subtask`	2	每子任务最多读文件数（代码生成类）
`analysis_max_files_per_subtask`	8	分析类每子任务最多读文件数
`large_project_file_threshold`	1000	大项目文件数阈值
`large_project_line_threshold`	100000	大项目行数阈值
`analysis_small_module_timeout`	300	小模块超时（秒）
`analysis_medium_module_timeout`	480	中模块超时（秒）
`analysis_large_module_timeout`	600	大模块超时（秒）
`max_parallel_subagents`	3	同时运行的子代理数

与 OpenClaw 原生 subagent 的区别

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

前端输出规范

派发时

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

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

子代理完成时

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

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

进度：N/总数 完成。

全部完成时

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

报告已写入 reports/xxx.md

文件说明

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

注意事项

派子代理时必须输出任务表格
子代理完成时立即通知用户进度和关键发现
执行过程中主会话保持可交互，用户随时可打断
分析类任务的子代理 prompt 必须包含文件读取约束
超时的子任务缩小范围重跑，不原样重试
小模块合并到一个子代理时，prompt 里列出所有模块的目录
用户说"暂停"时停止派发新子代理，说"继续"时恢复
空结果检测与处理：子代理返回结果后，检查内容是否有效：
- 空结果判定条件（满足任一即视为空结果）：
  - 结果长度 < 100 字符
  - 结果只包含"let me check"、"now let me"、"I have all the context"等中间过程文本
  - output tokens < 200（子代理统计信息中可见）
- 空结果不一定意味着任务失败：子代理可能已通过工具调用完成了文件写入，只是总结文本被截断
- 处理流程：
  1. 先检查磁盘：确认子代理是否已创建/修改了目标文件（检查文件是否存在且非空）
  2. 如果文件已创建且内容完整 → 任务实际完成，无需重跑，标记为"文件已就位，总结被截断"
  3. 如果文件不存在或为空 → 真正的空结果，缩小范围重跑
- 预防措施：
  - 子代理 prompt 中要求"先写文件，最后再输出总结"，确保即使被截断文件也已落盘
  - 单个子代理不要同时读太多文件 + 创建多个文件 + 修改现有文件，容易超 token 限制
  - 如果任务涉及 >3 个文件的创建/修改，考虑拆成更小的子任务
  - 对于纯创建文件的任务，可以在 prompt 中直接给出完整代码，让子代理只负责写入
默认排除目录：扫描器自动排除 .next、node_modules、.git、dist、build、out、.turbo、coverage 等构建产物和依赖目录，无需手动跳过

修复模式（v2.2 新增）

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

Step 1：准备问题列表

将审计发现的问题整理为 issues.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：生成修复计划

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 数