版本：2.88.0

name: orchestrator description: “完整的编排工作流程，包含蜂群模式：评估 -> 澄清 -> 分类 -> 持久化 -> 计划模式 -> 产生队友 -> 执行 -> 验证 -> 回顾。使用场景：(1) 实施功能，(2) 复杂重构，(3) 多文件更改，(4) 需要协调的任务。触发词：/orchestrator, /orch, ‘orchestrate’, ‘full workflow’, ‘implement feature’.” argument-hint: “<任务描述>” user-invocable: true context: fork agent: orchestrator allowed-tools:

LSP
Task
AskUserQuestion
EnterPlanMode
ExitPlanMode
TodoWrite
Read
Edit
Write
Bash
Glob
Grep
mcp__plugin_claude-mem_* hooks: PreToolUse:
- path: .claude/hooks/validate-lsp-servers.sh match_tool: LSP

编排器 - 多代理 Ralph v2.88

智能记忆驱动编排，包含蜂群模式、并行记忆搜索、RLM启发式路由和质量优先验证。

基于 @PerceptualPeak 智能分叉概念：

“为什么不利用你从数百/数千其他 Claude 代码会话中获得的知识呢？不要让这些宝贵的上下文浪费！！”

快速开始

# 通过技能调用
/orchestrator 实现与 Google 的 OAuth2 认证

# 通过 CLI
ralph orch "从 MySQL 迁移数据库到 PostgreSQL"

# 与特定队友
/orchestrator "重构数据库层" --teammates coder,reviewer

v2.88 主要变更 (MODEL-AGNOSTIC)

模型不可知：使用 ~/.claude/settings.json 或 CLI/env vars 配置的模型
无需标志：所有队友使用配置的默认模型
灵活：适用于 GLM-5、Claude、Minimax 或任何配置的模型
设置驱动：通过 ANTHROPIC_DEFAULT_*_MODEL env vars 选择模型

v2.87 主要变更 (UNIFIED SKILLS MODEL)

技能/命令统一：所有命令现在使用 SKILL.md 格式
单一真实来源：技能在 repo 中，全局链接
版本对齐：所有技能更新至 v2.87.0
文档整合：架构文档在 docs/architecture/

v2.81 主要变更 (SWARM MODE)

蜂群模式现在默认启用，使用原生 Claude Code 多代理功能：

团队创建：编排器创建团队 “orchestration-team” 与身份
队友产生：ExitPlanMode 产生 3 个队友 (code-reviewer, test-architect, security-auditor)
共享任务列表：所有队友通过 TeammateTool 看到相同任务
代理间通信：队友可以通过 mailbox 通信
计划批准：领导可以批准/拒绝队友计划

核心工作流程 (10 步)

0. 评估 -> 快速复杂度评估（简单 vs 非简单）
1. 澄清 -> 密集 AskUserQuestion（MUST_HAVE + NICE_TO_HAVE）
2. 分类 -> 复杂度 1-10，模型路由
2b. 工作树 -> 询问工作树隔离
3. 计划 -> 设计详细计划（编排器分析）
3b. 持久化 -> 写入 .claude/orchestrator-analysis.md
4. 计划模式 -> EnterPlanMode（读取分析作为基础）
5. 分配 -> 路由到适当的模型/代理
6. 执行 -> 并行子代理
7. 验证 -> 质量门 + 对抗性
8. 回顾 -> 分析和改进

步骤 0：评估 (3 维分类)

分类 (RLM 启发式)：

维度	值	目的
复杂度	1-10	范围，风险，模糊性
信息密度	常数 / 线性 / 二次	答案如何扩展
上下文需求	适合 / 分块 / 递归	分解需求

工作流路由：

密度	上下文	复杂度	路由
常数	适合	1-3	FAST_PATH (3 步)
常数	适合	4-10	标准
线性	分块	任何	PARALLEL_CHUNKS
二次	任何	任何	RECURSIVE_DECOMPOSE

步骤 1：澄清 (记忆增强)

MUST_HAVE 问题（阻塞）：

AskUserQuestion:
  questions:
    - question: "主要目标是什么？"
      header: "目标"
      options:
        - label: "新功能"
        - label: "错误修复"
        - label: "重构"
        - label: "性能"

步骤 2：分类 (模型路由)

分数	复杂度	模型	对抗性
1-2	简单	GLM-4.7 / glm-5	否
3-4	简单	GLM-4.7 / glm-5	否
5-6	中等	Sonnet	可选
7-8	复杂	Opus	是
9-10	临界	Opus (思考)	是

步骤 3：计划 + 持久化

将计划写入 .claude/orchestrator-analysis.md，包含：

摘要（由记忆信息提供）
需要修改/创建的文件
依赖关系
测试策略
风险（包括记忆中的已知问题）

步骤 4：计划模式

EnterPlanMode: {}  # Claude Code 读取 orchestrator-analysis.md

批准后用 ExitPlanMode 退出。

步骤 5：分配（并行优先与蜂群）

优先级：并行执行

# 带有蜂群模式（v2.81+）
Task:
  subagent_type: "orchestrator"
  description: "完整的蜂群编排"
  prompt: "$ARGUMENTS"
  model: "sonnet"
  team_name: "orchestration-team"
  name: "orchestrator-lead"
  mode: "delegate"

# ExitPlanMode 带有蜂群启动：
ExitPlanMode:
  launchSwarm: true
  teammateCount: 3

步骤 6：执行-同步

嵌套循环与并行子步骤：

EXTERNAL RALPH LOOP (max 25)
└── For EACH step:
    ├── LSA-VERIFY (架构检查)
    ├── IMPLEMENT (如果独立则并行)
    ├── PLAN-SYNC (漂移检测)
    └── MICRO-GATE (最多 3 次重试)

关键：所有子代理使用模型：“sonnet”

步骤 7：验证（质量优先）

阶段 1：正确性（阻塞）

是否满足要求？
边缘情况处理？

阶段 2：质量（阻塞）

安全验证？（semgrep + gitleaks）
性能 OK？
测试足够？

阶段 3：一致性（咨询 - 不阻塞）

是否遵循模式？
风格匹配？

阶段 4：对抗性（如果复杂度 >= 7）

ralph adversarial "设计审查"

步骤 8：回顾（强制）

ralph retrospective

保存学习到记忆：

ralph memvid save "成功实现 OAuth2：[模式细节]"
ralph memvid save "AVOID: [错误模式] 导致 [问题]"

-> VERIFIED_DONE

模型路由

路由	主要	次要	最大迭代
FAST_PATH	sonnet	-	3
STANDARD (1-4)	glm-5	sonnet	25
STANDARD (5-6)	sonnet	opus	25
STANDARD (7-10)	opus	sonnet	25
PARALLEL_CHUNKS	sonnet (块)	opus (聚合)	15/块
RECURSIVE	opus (根)	sonnet (子)	15/子

GLM-5 团队集成 (–with-glm5)

当 $ARGUMENTS 包含 --with-glm5：

步骤 1：解析参数

TASK=<everything before --with-glm5>
USE_GLM5=true

步骤 2：产生 GLM-5 队友

# GLM-5 编码者
.claude/scripts/glm5-teammate.sh "glm5-coder" "$CODER_TASK" "$TASK_ID-coder"

# GLM-5 审查者
.claude/scripts/glm5-teammate.sh "glm5-reviewer" "$REVIEW_TASK" "$TASK_ID-reviewer"

# GLM-5 测试者
.claude/scripts/glm5-teammate.sh "glm5-tester" "$TEST_TASK" "$TASK_ID-tester"

步骤 3：等待完成

cat .ralph/teammates/$TASK_ID-*/status.json

步骤 4：聚合结果

从 .ralph/reasoning/ 收集输出
显示思考过程以提高透明度
应用质量门

可用队友

队友	角色	最适合
`coder`	实现	编写代码，修复错误
`reviewer`	代码审查	质量检查，安全
`tester`	测试生成	单元测试，覆盖率
`orchestrator`	协调	复杂多步骤任务

反模式

绝不在没有智能记忆搜索的情况下开始
绝不跳过澄清
绝不对子代理使用模型：“haiku”
绝不跳过回顾
绝不尝试超过 3 次修复（3-Fix 规则）
绝不因一致性问题而阻塞（质量优于一致性）
绝不忽略记忆上下文（从历史中学习）

完成标准

VERIFIED_DONE 需要全部：

智能记忆搜索完成
任务分类（3 维）
MUST_HAVE 问题回答
计划批准
实施完成
正确性通过（阻塞）
质量通过（阻塞）
对抗性通过（如果复杂度 >= 7）
回顾完成 + 学习保存到记忆

CLI 命令

# 标准编排
ralph orch "任务描述"

# 与 GLM-5 队友
ralph orch "任务描述" --with-glm5
ralph orch "复杂功能" --with-glm5 --teammates coder,reviewer,tester

# 质量门
ralph gates
ralph adversarial "规格"

# 记忆
ralph memory-search "查询"
ralph fork-suggest "添加认证"

代理团队集成 (v2.88)

最佳场景：集成（代理团队 + 自定义子代理）

这个技能使用集成方法，结合代理团队协调和自定义子代理专业化。

为什么这个技能选择场景 C

多阶段编排需要在评估、澄清、计划、执行、验证阶段进行紧密协调
**质量门（TeammateIdle, TaskCompleted）**对 VERIFIED_DONE 保证至关重要
专门的 ralph- 代理*用于不同任务类型（coder, reviewer, tester, researcher）
共享任务列表用于进度跟踪和依赖关系管理
10 步工作流从团队协调和代理专业化中受益

配置

TeamCreate：在技能调用时创建团队 “orchestration-team-{timestamp}”
TaskCreate：为每个编排阶段创建任务（评估，澄清，计划，执行，验证）
产生：根据需要使用 ralph-coder, ralph-reviewer, ralph-tester, ralph-researcher
钩子：TeammateIdle + TaskCompleted 保证 VERIFIED_DONE
协调：共享任务列表在 ~/.claude/tasks/{team}/

工作流模式

TeamCreate(team_name, description)
  → TaskCreate(evaluate, clarify, classify, persist)
  → TaskCreate(plan-mode tasks)
  → Task(subagent_type="ralph-*", team_name) for execute phase
  → TaskUpdate(status="completed") as phases finish
  → Hooks validate quality at each stage
  → VERIFIED_DONE after retrospective

Ralph 代理类型 (v2.88)

代理	角色	工具	模型
`ralph-coder`	代码实现	Read, Edit, Write, Bash	从 settings.json 继承
`ralph-reviewer`	代码审查（安全，质量）	Read, Grep, Glob	从 settings.json 继承
`ralph-tester`	测试 & QA	Read, Edit, Write, Bash(test)	从 settings.json 继承
`ralph-researcher`	研究 & 探索	Read, Grep, Glob, WebSearch	从 settings.json 继承

注意：所有代理从 ~/.claude/settings.json 通过 ANTHROPIC_DEFAULT_*_MODEL 环境变量继承其模型（v2.88 模型不可知架构）。

VERIFIED_DONE 模式与钩子

编排器通过这些关键钩子确保 VERIFIED_DONE：

钩子	事件	目的	退出 2 行为
`teammate-idle-quality-gate.sh`	TeammateIdle	空闲前的质量检查	继续工作 + 反馈
`task-completed-quality-gate.sh`	TaskCompleted	任务完成前的质量	防止完成 + 反馈
`ralph-subagent-stop.sh`	SubagentStop	ralph-* 代理的质量门	如果不完整则阻塞

退出 2 行为：当钩子返回退出代码 2 时，代理继续工作而不是完成/空闲，确保连续执行直到 VERIFIED_DONE。

团队协调示例

# 1. 创建团队（技能调用时自动）
TeamCreate:
  team_name: "orchestration-team-20250214"
  description: "编排功能实现"

# 2. 为队友创建任务
TaskCreate:
  subject: "实现 OAuth2 流程"
  description: "添加与 Google 提供商的 OAuth2 认证"
  metadata:
    assigned_to: "ralph-coder"
    priority: "high"

TaskCreate:
  subject: "审查 OAuth2 实现"
  description: "审查 OAuth2 代码的安全性和质量"
  metadata:
    assigned_to: "ralph-reviewer"
    depends_on: ["implement-oauth2-flow"]

TaskCreate:
  subject: "测试 OAuth2 认证"
  description: "OAuth2 的单元和集成测试"
  metadata:
    assigned_to: "ralph-tester"
    depends_on: ["implement-oauth2-flow"]

# 3. 产生队友以并行执行
Task:
  subagent_type: "ralph-coder"
  team_name: "orchestration-team-20250214"

Task:
  subagent_type: "ralph-reviewer"
  team_name: "orchestration-team-20250214"

Task:
  subagent_type: "ralph-tester"
  team_name: "orchestration-team-20250214"

# 4. 监控进度并聚合结果
TaskList:
  status: "in_progress"

# 5. 标记任务完成
TaskUpdate:
  taskId: "1"
  status: "completed"

# 6. VERIFIED_DONE 后删除团队
TeamDelete:
  team_name: "orchestration-team-20250214"

质量标准（所有 Ralph 代理）

正确性：语法必须有效，逻辑必须合理
质量：无 console.log，无 TODO/FIXME，适当的类型
安全：无硬编码秘密，适当的输入验证
一致性：遵循项目风格指南

通信模式

队友通过共享任务列表和 SendMessage 工具通信：

SendMessage:
  type: "message"
  recipient: "ralph-reviewer"
  content: "OAuth2 实现完成，准备审查"
  summary: "实现准备审查"

行动报告 (v2.93.0)

编排器生成完整的自动报告 以保证可追溯性：

自动报告

当 /orchestrator 完成时，自动生成：

在 Claude 对话中：可见报告，包含所有细节
在仓库中：docs/actions/orchestrator/{timestamp}.md
元数据 JSON：.claude/metadata/actions/orchestrator/{timestamp}.json

报告内容

每个报告包括：

✅ 摘要：执行的任务描述
✅ 执行细节：持续时间，迭代次数，修改的文件
✅ Git 状态：分支，提交，更改的文件
✅ 错误：发现的错误（如果适用）
✅ 建议：建议的下一步

手动生成（可选）

如果需要手动控制报告：

# 开始时
source .claude/lib/action-report-lib.sh
start_action_report "orchestrator" "实现与 Google 的 OAuth2"

# 执行期间
mark_iteration  # 每次循环迭代
mark_file_modified "src/auth/oauth.ts"  # 每次修改文件
record_error "类型不匹配在配置中"  # 如果有错误

# 完成后
complete_action_report \
    "success" \
    "OAuth2 实现完成" \
    "1. 运行测试：npm test
     2. 安全审计：/security src/
     3. 创建 PR：gh pr create"

查看先前报告

# 列出所有编排器报告
ls -lt docs/actions/orchestrator/

# 查看最近的报告
cat $(ls -t docs/actions/orchestrator/*.md | head -1)

# 搜索失败报告
grep -l "Status: FAILED" docs/actions/orchestrator/*.md

统计

source .claude/lib/action-report-generator.sh
get_skill_stats "orchestrator"

# 输出：
# 技能：编排器
# 总报告：45
# 完成：42
# 失败：3
# 成功率：93%

与钩子集成

编排器的报告系统与以下集成：

钩子	目的	位置
`action-report-tracker.sh`	自动生成报告	`.claude/hooks/`
`orchestrator-report.sh`	会话报告	`~/.ralph/reports/`
`progress-tracker.sh`	实时跟踪	`.claude/progress.md`

注意：行动报告（docs/actions/）是会话报告（~/.ralph/reports/）的补充。

报告系统参考

行动报告系统 - 完整文档
action-report-lib.sh - 辅助库
action-report-generator.sh - 生成器