ultrapilot

Ultrapilot Skill

并行自动驾驶，通过文件所有权分区生成多个 worker，以实现最大速度。

概述

Ultrapilot 是 autopilot 的并行演进版本。它将你的任务分解为可独立并行处理的子任务，为每个 worker 分配不重叠的文件集，并同时运行它们。

关键能力：

1. 分解任务为可并行安全处理的组件
2. 分区文件并赋予独占所有权（无冲突）
3. 生成最多 20 个并行 worker
4. 通过 TaskOutput 协调进度
5. 集成变更，并对共享文件进行顺序处理
6. 验证整个系统的完整性

速度倍增： 对于适合的任务，比顺序 autopilot 最多快 5 倍。

用法

/oh-my-claudecode:ultrapilot <your task>
/oh-my-claudecode:up "Build a full-stack todo app"
/oh-my-claudecode:ultrapilot Refactor the entire backend

魔法关键词

以下短语会自动激活 ultrapilot：

• "ultrapilot"、"ultra pilot"
• "parallel build"、"parallel autopilot"
• "swarm build"、"swarm mode"
• "fast parallel"、"ultra fast"

何时使用

Ultrapilot 擅长的场景：

• 多组件系统（前端 + 后端 + 数据库）
• 跨不同模块的独立功能添加
• 具有清晰模块边界的大规模重构
• 并行测试文件生成
• 多服务架构

Autopilot 更适合：

• 单线程顺序任务
• 组件之间存在重度相互依赖
• 需要持续集成检查的任务
• 单个模块中的小型聚焦功能

架构

User Input: "Build a full-stack todo app"
           |
           v
  [ULTRAPILOT COORDINATOR]
           |
   Decomposition + File Partitioning
           |
   +-------+-------+-------+-------+
   |       |       |       |       |
   v       v       v       v       v
[W-1]   [W-2]   [W-3]   [W-4]   [W-5]
backend frontend database api-docs tests
(src/  (src/   (src/    (docs/)  (tests/)
 api/)  ui/)    db/)
   |       |       |       |       |
   +---+---+---+---+---+---+---+---+
       |
       v
  [INTEGRATION PHASE]
  (shared files: package.json, tsconfig.json, etc.)
       |
       v
  [VALIDATION PHASE]
  (full system test)

阶段

阶段 0：任务分析

目标： 确定任务是否可并行化

检查项：

• 任务能否拆分为 2 个以上独立子任务？
• 文件边界是否清晰？
• 依赖是否最少？

输出： Go/No-Go 决策（如果不适合，则回退到 autopilot）

阶段 1：分解

目标： 将任务拆分为可并行安全处理的子任务

Agent： Architect（Opus）

方法： AI 驱动的任务分解

Ultrapilot 使用 decomposer 模块生成智能任务拆分：

import {
  generateDecompositionPrompt,
  parseDecompositionResult,
  validateFileOwnership,
  extractSharedFiles
} from 'src/hooks/ultrapilot/decomposer';

// 1. Generate prompt for Architect
const prompt = generateDecompositionPrompt(task, codebaseContext, {
  maxSubtasks: 5,
  preferredModel: 'sonnet'
});

// 2. Call Architect agent
const response = await Task({
  subagent_type: 'oh-my-claudecode:architect',
  model: 'opus',
  prompt
});

// 3. Parse structured result
const result = parseDecompositionResult(response);

// 4. Validate no file conflicts
const { isValid, conflicts } = validateFileOwnership(result.subtasks);

// 5. Extract shared files from subtasks
const finalResult = extractSharedFiles(result);

流程：

1. 通过 Architect agent 分析任务需求
2. 识别具有文件边界的独立组件
3. 按复杂度分配 agent 类型（executor-low/executor/executor-high）
4. 映射子任务之间的依赖关系（blockedBy）
5. 生成并行执行分组
6. 识别共享文件（由 coordinator 处理）

输出： 结构化的 DecompositionResult：

{
  "subtasks": [
    {
      "id": "1",
      "description": "Backend API routes",
      "files": ["src/api/routes.ts", "src/api/handlers.ts"],
      "blockedBy": [],
      "agentType": "executor",
      "model": "sonnet"
    },
    {
      "id": "2",
      "description": "Frontend components",
      "files": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
      "blockedBy": [],
      "agentType": "executor",
      "model": "sonnet"
    },
    {
      "id": "3",
      "description": "Wire frontend to backend",
      "files": ["src/client/api.ts"],
      "blockedBy": ["1", "2"],
      "agentType": "executor-low",
      "model": "haiku"
    }
  ],
  "sharedFiles": [
    "package.json",
    "tsconfig.json",
    "README.md"
  ],
  "parallelGroups": [["1", "2"], ["3"]]
}

分解类型：

类型	描述	使用场景
DecomposedTask	带有 id、files、blockedBy、agentType、model 的完整任务	智能 worker 生成
DecompositionResult	带有 subtasks、sharedFiles、parallelGroups 的完整结果	完整分解输出
toSimpleSubtasks()	转换为 string[] 以兼容旧版	简单任务列表

阶段 2：文件所有权分区

目标： 为 worker 分配独占文件集

规则：

1. 独占所有权 - 任何文件都不能出现在多个 worker 集合中
2. 共享文件延后处理 - 在集成阶段顺序处理
3. 追踪边界文件 - 跨边界导入的文件

数据结构： .omc/state/ultrapilot-ownership.json

{
  "sessionId": "ultrapilot-20260123-1234",
  "workers": {
    "worker-1": {
      "ownedFiles": ["src/api/routes.ts", "src/api/handlers.ts"],
      "ownedGlobs": ["src/api/**"],
      "boundaryImports": ["src/types.ts"]
    },
    "worker-2": {
      "ownedFiles": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
      "ownedGlobs": ["src/ui/**"],
      "boundaryImports": ["src/types.ts"]
    }
  },
  "sharedFiles": ["package.json", "tsconfig.json", "src/types.ts"],
  "conflictPolicy": "coordinator-handles"
}

阶段 3：并行执行

目标： 同时运行所有 worker

生成 Worker：

// Pseudocode
workers = [];
for (subtask in decomposition.subtasks) {
  workers.push(
    Task(
      subagent_type: "oh-my-claudecode:executor",
      model: "sonnet",
      prompt: `ULTRAPILOT WORKER ${subtask.id}

Your exclusive file ownership: ${subtask.files}

Task: ${subtask.description}

CRITICAL RULES:
1. ONLY modify files in your ownership set
2. If you need to modify a shared file, document the change in your output
3. Do NOT create new files outside your ownership
4. Track all imports from boundary files

Deliver: Code changes + list of boundary dependencies`,
      run_in_background: true
    )
  );
}

监控：

• 轮询每个 worker 的 TaskOutput
• 跟踪完成状态
• 及早检测冲突
• 累积边界依赖

最大 Worker 数： 5（Claude Code 限制）

阶段 4：集成

目标： 合并所有 worker 的变更并处理共享文件

流程：

1. 收集输出 - 汇总所有 worker 的交付物
2. 检测冲突 - 检查意外的重叠
3. 处理共享文件 - 对 package.json 等文件进行顺序更新
4. 集成边界文件 - 合并类型定义、共享工具函数
5. 解析导入 - 确保跨边界导入有效

Agent： Executor（Sonnet）- 顺序处理

冲突解决：

• 如果 worker 意外修改了同一文件 → 手动合并
• 如果共享文件需要多次修改 → 顺序应用
• 如果边界文件发生变更 → 验证所有依赖的 worker

阶段 5：验证

目标： 验证集成后的系统可正常工作

检查（并行）：

1. 构建 - 运行项目的构建命令
2. Lint - 运行项目的 lint 命令
3. 类型检查 - 运行项目的类型检查命令
4. 单元测试 - 所有测试通过
5. 集成测试 - 跨组件测试

Agent（并行）：

• Build-fixer（Sonnet）- 修复构建错误
• Architect（Opus）- 功能完整性
• Security-reviewer（Opus）- 跨组件漏洞

重试策略： 最多 3 轮验证。如果仍失败，向用户提供详细的错误报告。

状态管理

会话状态

位置： .omc/ultrapilot-state.json

{
  "sessionId": "ultrapilot-20260123-1234",
  "taskDescription": "Build a full-stack todo app",
  "phase": "execution",
  "startTime": "2026-01-23T10:30:00Z",
  "decomposition": { /* from Phase 1 */ },
  "workers": {
    "worker-1": {
      "status": "running",
      "taskId": "task-abc123",
      "startTime": "2026-01-23T10:31:00Z",
      "estimatedDuration": "5m"
    }
  },
  "conflicts": [],
  "validationAttempts": 0
}

文件归属映射

位置： .omc/state/ultrapilot-ownership.json

记录哪个 worker 拥有哪些文件（参见上方阶段 2 的示例）。

进度跟踪

位置： .omc/ultrapilot/progress.json

{
  "totalWorkers": 5,
  "completedWorkers": 3,
  "activeWorkers": 2,
  "failedWorkers": 0,
  "estimatedTimeRemaining": "2m30s"
}

配置

.claude/settings.json 中的可选设置：

{
  "omc": {
    "ultrapilot": {
      "maxWorkers": 5,
      "maxValidationRounds": 3,
      "conflictPolicy": "coordinator-handles",
      "fallbackToAutopilot": true,
      "parallelThreshold": 2,
      "pauseAfterDecomposition": false,
      "verboseProgress": true
    }
  }
}

设置说明：

• maxWorkers - 最大并行 worker 数（5 是 Claude Code 的限制）
• maxValidationRounds - 验证重试次数
• conflictPolicy - "coordinator-handles" 或 "abort-on-conflict"
• fallbackToAutopilot - 如果任务无法并行化则自动切换
• parallelThreshold - 使用 ultrapilot 的最小子任务数（否则回退）
• pauseAfterDecomposition - 执行前与用户确认
• verboseProgress - 显示详细的 worker 进度

取消

/oh-my-claudecode:cancel

或者说："stop"、"cancel ultrapilot"、"abort"

行为：

• 所有活跃 worker 优雅终止
• 部分进度保存到状态文件
• 会话可以恢复

恢复

如果 ultrapilot 被取消或有 worker 失败：

/oh-my-claudecode:ultrapilot resume

恢复逻辑：

• 仅重启失败的 worker
• 复用已完成 worker 的输出
• 从上一个阶段继续

示例

示例 1：全栈应用

/oh-my-claudecode:ultrapilot Build a todo app with React frontend, Express backend, and PostgreSQL database

Worker：

1. 前端（src/client/）
2. 后端（src/server/）
3. 数据库（src/db/）
4. 测试（tests/）
5. 文档（docs/）

共享文件： package.json、docker-compose.yml、README.md

耗时： 约 15 分钟（对比顺序执行的约 75 分钟）

示例 2：多服务重构

/oh-my-claudecode:up Refactor all services to use dependency injection

Worker：

1. Auth 服务
2. User 服务
3. Payment 服务
4. Notification 服务

共享文件： src/types/services.ts、tsconfig.json

耗时： 约 8 分钟（对比顺序执行的约 32 分钟）

示例 3：测试覆盖率

/oh-my-claudecode:ultrapilot Generate tests for all untested modules

Worker：

1. API 测试
2. UI 组件测试
3. 数据库测试
4. 工具函数测试
5. 集成测试

共享文件： jest.config.js、test-utils.ts

耗时： 约 10 分钟（对比顺序执行的约 50 分钟）

最佳实践

1. 清晰的模块边界 - 在代码分离良好的情况下效果最佳
2. 最小化共享状态 - 降低集成复杂度
3. 信任分解结果 - Architect 知道哪些是并行安全的
4. 监控进度 - 检查 .omc/ultrapilot/progress.json
5. 尽早审查冲突 - 不要等到集成阶段

文件归属策略

所有权类型

独占所有权：

• Worker 拥有唯一写入权限
• 其他 Worker 无法触碰这些文件
• Worker 可以在其拥有的目录中创建新文件

共享文件：

• 没有 Worker 拥有独占访问权
• 在集成阶段按顺序处理
• 包括：package.json、tsconfig.json、配置文件、根 README

边界文件：

• 所有 Worker 均可读取
• 写入权限由使用情况分析决定
• 通常为：类型定义、共享工具、接口

所有权检测算法

For each file in codebase:
  If file in shared_patterns (package.json, *.config.js):
    → sharedFiles

  Else if file imported by 2+ subtask modules:
    → boundaryFiles
    → Assign to most relevant worker OR defer to shared

  Else if file in subtask directory:
    → Assign to subtask worker

  Else:
    → sharedFiles (safe default)

共享文件模式

自动归类为共享：

• package.json、package-lock.json
• tsconfig.json、*.config.js、*.config.ts
• .eslintrc.*、.prettierrc.*
• README.md、CONTRIBUTING.md、LICENSE
• Docker 文件：Dockerfile、docker-compose.yml
• CI 文件：.github/**、.gitlab-ci.yml

冲突处理

冲突类型

意外重叠：

• 两个 Worker 修改了同一个文件
• 解决方案： 协调器在人工确认后合并

共享文件争用：

• 多个 Worker 需要更新 package.json
• 解决方案： 在集成阶段按顺序应用

边界文件冲突：

• 多个 Worker 需要同一类型定义
• 解决方案： 由第一个 Worker 创建，其他 Worker 导入

冲突策略

coordinator-handles（默认）：

• 协调器尝试自动合并
• 情况复杂时回退给用户

abort-on-conflict：

• 任何冲突都会立即取消 ultrapilot
• 用户查看冲突报告
• 手动修复后可恢复

故障排查

分解失败？

• 任务可能耦合度过高
• 自动触发回退到 autopilot
• 查看 .omc/ultrapilot/decomposition.json 了解详情

Worker 卡住？

• 检查 .omc/logs/ultrapilot-worker-N.log 中的 Worker 日志
• 取消并重启该 Worker
• 可能表明存在文件所有权问题

集成冲突？

• 查看 .omc/ultrapilot-state.json 的 conflicts 数组
• 检查共享文件是否被意外修改
• 如有需要，调整所有权规则

验证循环？

• 跨组件集成问题
• 检查边界导入
• 可能需要带完整上下文进行顺序重试

太慢？

• 检查 Worker 是否真正独立
• 检查分解质量
• 考虑 autopilot 是否更快（高度相互依赖时）

与 Autopilot 的区别

特性	Autopilot	Ultrapilot
执行方式	顺序	并行（最高 5 倍）
最适合	单线程任务	多组件系统
复杂度	较低	较高
速度	标准	快 3-5 倍（适用任务）
文件冲突	不适用	所有权分区
回退	不适用	可回退到 autopilot
设置	即时	分解阶段（约 1-2 分钟）

经验法则： 如果任务有 3 个以上独立组件，使用 ultrapilot。否则，使用 autopilot。

高级：自定义分解

你可以提供自定义分解文件以跳过第 1 阶段：

位置： .omc/ultrapilot/custom-decomposition.json

{
  "subtasks": [
    {
      "id": "worker-auth",
      "description": "Add OAuth2 authentication",
      "files": ["src/auth/**", "src/middleware/auth.ts"],
      "dependencies": ["src/types/user.ts"]
    },
    {
      "id": "worker-db",
      "description": "Add user table and migrations",
      "files": ["src/db/migrations/**", "src/db/models/user.ts"],
      "dependencies": []
    }
  ],
  "sharedFiles": ["package.json", "src/types/user.ts"]
}

然后运行：

/oh-my-claudecode:ultrapilot --custom-decomposition

完成时清理状态

重要：完成时删除状态文件 - 不要只是设置 active: false

当所有 Worker 成功完成时：

# Delete ultrapilot state files
rm -f .omc/state/ultrapilot-state.json
rm -f .omc/state/ultrapilot-ownership.json

未来增强

v4.1 计划：

• 动态 Worker 扩缩（从 2 个开始，如需要则增加）
• 预测性冲突检测（集成前分析）
• Worker 间通信（用于罕见依赖）
• 推测性执行（乐观并行）
• 从集成阶段恢复（如果验证失败）

v4.2 计划：

• 多机器分发（如果 Claude Code 支持）
• 实时进度仪表盘
• Worker 性能分析
• 自动调整分解策略