skill-parallel-agents

宿主：Codex CLI — 此技能最初为 Claude Code 设计，后适配为 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前 Codex Shell 和子 Agent 工具。除非当前会话已提供相应功能，否则不要声称某个提供商、模型或宿主子 Agent 可用。 有关宿主工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

Claude Octopus - 多触手编排器

必须遵守 — 切勿跳过

调用此技能时，你必须并行调度多个提供商来处理工作。严禁：

• 只使用一个模型依次执行任务，而不是并行调度多个提供商
• 跳过 orchestrate.sh，直接完成工作
• 认定任务“简单到”只需一个提供商
• 以仅使用 Claude 的串行执行取代多 LLM 并行执行

此技能专为多提供商并行工作而设。如果你发现自己在想“我直接自己做就行”——立即停下。

面向 Claude Code 的多触手编排器——采用 Double Diamond 方法，全面探索问题、达成共识并交付经过验证的成果。

    DISCOVER          DEFINE           DEVELOP          DELIVER
      (probe)         (grasp)          (tangle)          (ink)

    \         /     \         /     \         /     \         /
     \   *   /       \   *   /       \   *   /       \   *   /
      \ * * /         \     /         \ * * /         \     /
       \   /           \   /           \   /           \   /
        \ /             \ /             \ /             \ /

   Diverge then      Converge to      Diverge with     Converge to
    converge          problem          solutions        delivery

快速开始

Claude Code 用户须知： 无需运行这些命令！直接用自然语言告诉 Claude 即可：

• “研究 OAuth 身份验证模式”
• “构建用户身份验证系统”
• “检查这段代码是否存在安全问题”

以下命令适用于直接使用 CLI 或自动化操作。

# Full Double Diamond workflow (all 4 phases)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Build a user authentication system"

# Individual phases
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "Research authentication best practices"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "Define auth requirements"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement auth feature"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Validate and deliver auth implementation"

# Crossfire: Adversarial cross-model review
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple "implement password reset API"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement JWT auth"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "review auth.ts for vulnerabilities"

# Smart auto-routing (detects intent automatically)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "research OAuth patterns"           # -> probe
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build user login"                  # -> tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "review the auth code"              # -> ink

重要：何时不应使用此技能

如果用户请求涉及以下任一内容，请勿使用此技能：

1. Claude Code 内置命令——以 / 开头且属于 Claude Code 本身的命令：

   • /plugin - 插件管理（添加、移除、更新、列出）
   • /init - 项目初始化
   • /help - 帮助文档
   • /clear - 清除对话
   • /commit - Git 提交操作
   • /remember - 记忆管理
   • 其他任何不属于 /parallel-agents 或 /octo:* 的 / 命令

2. 直接使用工具——简单的文件操作、Git 命令或终端任务

   • 读取/写入文件
   • 运行 Git 命令
   • 基本 Bash 操作
   • 这些任务应直接使用内置工具完成

3. Claude Code 配置——管理 Claude Code 本身

   • 更改设置
   • 管理插件
   • 更新 Claude Code

如果用户请求符合以上任一情况，请勿启用此技能。请改用标准 Claude Code 工具和功能处理请求。

可视化指示标记 - 了解当前运行内容

Claude Octopus 使用可视化指示标记，让你随时了解哪个 AI 正在响应：

指示标记	含义	用途
🐙	并行模式	通过 orchestrate.sh 编排多个 CLI
🔴	Codex CLI	OpenAI Codex（使用你的 OPENAI_API_KEY）
🧭	Antigravity CLI	Google Antigravity（使用你已认证的席位）
🔵	Claude 子 Agent	Claude Code 宿主子 Agent 工具（内置）

哪些操作会触发外部 CLI，哪些会触发子 Agent

以下情况会执行外部 CLI：

• 显式使用 /parallel-agents 命令
• 使用 /octo:debate 命令（AI Debate Hub）
• 运行 orchestrate.sh 工作流（probe、grasp、tangle、ink、embrace、grapple、squeeze）
• 知识模式下的讨论（知识模式已开启时）
• 触发此技能的自然语言请求（研究、构建、审查类任务）

以下情况会执行 Claude 子 Agent：

• 简单的文件操作（读取、写入、编辑）
• Git 命令和 Bash 操作
• 代码阅读和导航
• 不需要多方视角的任务
• Claude Code 内置功能已足够处理的任务

此区分的重要性： 外部 CLI 会使用你的 OpenAI/Google API 配额并产生费用。Claude 子 Agent 已包含在 Claude Code 中，不会额外收费。

当你看到 🐙 CLAUDE OCTOPUS 已激活时，将会调用 Codex、Antigravity 等外部 CLI 提供商进行多角度分析。

强制多提供商模式

有时，即使是通常不会触发工作流的简单任务，你也希望进行多提供商分析。如果你需要从多个角度全面审视决策、比较不同模型的思考方式，或者自动路由低估了任务复杂度，这会很有用。

显式命令

使用 /octo:multi 命令强制执行多提供商模式：

/octo:multi "Explain how Redis works"
/octo:multi "What is OAuth?"
/octo:multi "Review this simple function"
/octo:multi "Should we use TypeScript?"

自然语言触发

你也可以通过自然语言强制启用多提供商模式：

"Run this with all providers: What is JWT?"
"I want multiple AI models to look at our architecture"
"Get multiple perspectives on this design decision"
"Use all providers for explaining caching strategies"
"Force multi-provider analysis of our API design"

何时强制启用并行模式

在以下情况下使用强制并行模式：

• 重大决策需要多个模型进行全面分析
• 比较不同观点——想了解不同模型如何处理同一个问题
• 需要深入分析的简单问题——看似简单，但值得进行彻底的多模型分析
• 了解不同方法——探索每个模型如何思考某个主题
• 自动路由低估了复杂度——任务看似简单，但其实有细微之处

在以下情况下不要强制启用并行模式：

• 任务已经会自动触发工作流（octo research、octo build、octo review）
• Claude 能够可靠回答的简单事实性问题
• 注重成本效益（参见下文的成本注意事项）
• 文件操作或代码导航（使用内置工具）

成本注意事项

强制启用并行模式会为每项任务调用外部 CLI，因此会产生 API 费用：

提供商	每次查询的费用	使用的凭据
🔴 Codex CLI	~0.01-0.05 USD	你的 OPENAI_API_KEY
🧭 Antigravity CLI	已包含在访问权限/订阅中	Antigravity CLI auth
🔵 Claude	已包含	Claude Code 订阅

每次强制查询的总费用：~0.02-0.08 USD

请谨慎使用强制并行模式，仅用于多个观点确实能带来价值的任务。对于日常工作，让自动路由决定何时适合进行多提供商分析。

视觉指示器

强制启用并行模式时，你会看到以下横幅：

🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider mode
Force parallel execution

Providers:
🔴 Codex CLI - [Role in this task]
🧭 Antigravity CLI - [Role in this task]
🔵 Claude - [Role in this task]

随后会显示各提供商的结果，并附上对应指示器（例如 🔴 🟡 🧭 🔵）。

前置条件检查

此技能激活后，运行本地提供商检查：

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}"
"$OCTO_ROOT/scripts/orchestrate.sh" detect-providers

此检查会读取本地命令、凭据和一小时缓存，不会调用提供商 API。当前输出包含 Claude Code 版本要求，以及每个提供商的状态：

Detecting Claude Code version...

CLAUDE_CODE_VERSION=2.1.219
CLAUDE_CODE_STATUS=ok
CLAUDE_CODE_MINIMUM=2.1.14

CODEX_STATUS=ok
AGY_STATUS=unauthenticated

提供商状态值为 ok、unauthenticated、quota、not-installed，或 model-invalid 等具体原因。

根据结果选择路由

如果 Claude Code 版本过旧，请停止并显示命令报告的版本和更新说明：

CLAUDE_CODE_VERSION=2.1.13
CLAUDE_CODE_STATUS=outdated
CLAUDE_CODE_MINIMUM=2.1.14

如果某个非 Claude 提供商报告 ok，则使用该提供商。并行执行至少需要一个就绪的非 Claude 提供商，但即使没有就绪的非 Claude 提供商，普通的仅使用 Claude 的命令仍可正常运行。如果没有提供商报告 ok，请停止并行工作流，引导用户使用 /octo:setup，不要通过反复运行单个提供商来模拟提供商间的一致意见。一个就绪的提供商可以提供额外视角，但这不代表多提供商共识。

该命令会写入 ~/.claude-octopus/.provider-cache。缓存最长可复用一小时；超过一小时后，请重新运行检测。

双钻石工作流

阶段 1：探查（发现）

先发散，再收敛，建立理解

从 4 个角度并行研究：

• 问题空间分析（约束、要求、需求）
• 现有解决方案研究（哪些有效，哪些无效）
• 边缘情况探索（潜在挑战）
• 技术可行性（前置条件、依赖项）

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "What are the best approaches for real-time notifications?"

阶段 2：把握（定义）

围绕问题建立共识

多触角的问题定义：

• 核心问题陈述
• 成功标准
• 约束和边界

# Optional second argument: no phase sets this variable; copy the path the probe
# phase printed after "Probe synthesis saved to:"
PROBE_SYNTHESIS="<printed probe-synthesis-*.md path>"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "Define requirements for notification system" "$PROBE_SYNTHESIS"

Phase 3：TANGLE（开发）

通过多种解决方案发散探索

增强型 Map-Reduce，并带有验证机制：

• 通过 LLM 分解任务
• 在多个 Agent 间并行执行
• 质量关卡（75% 成功率阈值）

# Optional second argument: no phase sets this variable; copy the path the grasp
# phase printed after "Problem definition saved to:"
GRASP_CONSENSUS="<printed grasp-consensus-*.md path>"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement notification service" "$GRASP_CONSENSUS"

Phase 4：INK（交付）

收敛为经过验证的交付成果

交付前验证：

• 质量关卡验证
• 结果综合
• 生成最终交付成果

# Optional second argument: no phase sets this variable; copy the path the tangle
# phase printed after "Validation complete:"
TANGLE_VALIDATION="<printed tangle-validation-*.md path>"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Deliver notification system" "$TANGLE_VALIDATION"

完整工作流：EMBRACE

按顺序运行全部 4 个阶段，并自动传递上下文：

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Create a complete user dashboard feature"

Crossfire：对抗式跨模型评审

不同模型各有盲点。Crossfire 命令会让模型相互评议对方的成果，比单模型评审发现更多问题。

GRAPPLE——对抗式辩论

两条触手相互角力，直至达成共识

各个可用提供方会分别提出解决方案，然后相互评议对方的成果。综合分析后确定胜出方案。

┌─────────────┐     ┌─────────────┐
│   Codex     │     │ Antigravity │
│ (Proposer)  │     │ (Proposer)  │
└──────┬──────┘     └──────┬──────┘
       │                   │
       ▼                   ▼
┌─────────────┐     ┌─────────────┐
│ PROPOSAL A  │ ←─→ │ PROPOSAL B  │
└──────┬──────┘     └──────┬──────┘
       │                   │
       ▼                   ▼
┌─────────────┐     ┌─────────────┐
│ Antigravity │     │   Codex     │
│ (Critic)    │     │  (Critic)   │
└──────┬──────┘     └──────┬──────┘
       │                   │
       └─────────┬─────────┘
                 ▼
       ┌─────────────────┐
       │   SYNTHESIS     │
       │ (Winner + Fix)  │
       └─────────────────┘

# Basic grapple
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple "implement password reset API"

# Grapple with security principles
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement JWT authentication"

# Grapple with performance principles
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles performance "optimize database queries"

SQUEEZE——红队安全评审

章鱼挤压猎物，以测试其弱点

蓝队（Codex）编写安全代码。红队（Antigravity）发起攻击以查找漏洞。随后进行修复和验证。

Phase 1: Blue Team implements secure solution
Phase 2: Red Team finds vulnerabilities
Phase 3: Remediation fixes all issues
Phase 4: Validation verifies all fixed

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "implement user login form"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "review auth.ts for vulnerabilities"

宪法原则

Grapple 支持特定领域的评议原则：

原则	关注重点	使用场景
general	整体质量	大多数评审的默认选项
security	OWASP Top 10、安全编码	身份验证、支付、用户数据
performance	N+1 查询、缓存、异步	数据库、API 优化
maintainability	整洁代码、可测试性	重构、代码评审

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement password reset"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles performance "optimize search API"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles maintainability "refactor user service"

智能自动路由

auto 命令会检测意图关键词，并路由到相应的工作流：

关键词	路由至	阶段
research、explore、investigate、analyze	probe	发现
develop、dev、build、implement、create	tangle + ink	开发 + 交付
qa、test、review、validate、check	ink	交付（侧重质量）
security audit、red team、pentest	squeeze	红队
adversarial、cross-model、debate	grapple	辩论
（其他编码关键词）	codex Agent	单个 Agent
（其他设计关键词）	agy Agent	单个 Agent

示例：

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "research best practices for caching"     # -> probe
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build the caching layer"                 # -> tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "review the cache implementation"         # -> ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "security audit the auth module"          # -> squeeze
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "have both models debate the API design"  # -> grapple
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "fix the cache invalidation bug"          # -> codex

质量关卡

tangle 阶段会执行质量关卡：

分数	状态	行为
>= 90%	PASSED	继续进入 ink 阶段
75-89%	WARNING	谨慎继续
< 75%	FAILED	ink 阶段标记为待评审

命令参考

Double Diamond 命令

命令	阶段	说明
probe <prompt>	发现	并行研究并由 AI 综合结果
grasp <prompt>	定义	围绕问题定义达成共识
tangle <prompt>	开发	带质量关卡的增强型 Map-Reduce
ink <prompt>	交付	验证并最终交付
embrace <prompt>	全部 4 个阶段	完整的 Double Diamond 工作流
preflight	-	验证所有依赖项

Crossfire 命令（对抗式评审）

命令	说明
grapple <prompt>	Codex 与 Antigravity 辩论，直至达成共识
grapple --principles TYPE <prompt>	根据领域原则进行辩论（安全、性能、可维护性）
squeeze <prompt>	红队安全评审（蓝队与红队对抗）

经典编排命令

命令	说明
init	初始化工作区
spawn <agent> <prompt>	启动单个 Agent
auto <prompt>	智能路由（Double Diamond 或 Agent）
fan-out <prompt>	发送给多个 Agent
map-reduce <prompt>	分解任务并并行执行
parallel [tasks.json]	执行任务文件
status	显示正在运行的 Agent
kill [id|all]	终止 Agent
clean	重置工作区
aggregate [filter]	汇总结果

选项

选项	默认值	描述
-p, --parallel	3	并发 Agent 数量上限
-t, --timeout	600	每项任务的超时时间（秒）；同时替代 grasp 等命令固定的单次调用时限（如 300s）。可通过 OCTOPUS_AGENT_TIMEOUT 覆盖
-v, --verbose	false	输出详细日志
-n, --dry-run	false	显示但不执行

Agent 选择（高级版默认项）

Agent	模型	最适合
codex	gpt-5.6-sol	前沿实现和独立审查
codex-standard	gpt-5.6-terra	均衡的实现和审查
codex-mini	gpt-5.6-luna	快速修复、简单任务
agy	服务选择的默认项	深度分析和外部审查
agy-research	服务选择的默认项	专注研究的 Antigravity 账号
codex-review	gpt-5.6-sol	代码审查模式
openrouter	多种	通用备用方案（400+ 个模型）
orcarouter	多种	通过 OrcaRouter 网关提供的通用备用方案

基于提供商的智能路由（v4.8）

Claude Octopus 现在会根据你的订阅层级和费用智能地路由任务。

提供商订阅层级

提供商	层级	月费	能力
Codex/OpenAI	Free、Plus、Pro、API	0-200 USD	代码、聊天、审查
Antigravity	Google 访问权限/订阅	访问权限内含	代码、分析、外部审查
Claude	Pro、Max 5x、Max 20x、API	20-200 USD	代码、聊天、分析、长上下文
OpenRouter	按使用付费	不固定	400+ 个模型、路由变体
OrcaRouter	按使用付费	不固定	单一网关、带命名空间的模型 ID

成本优化策略

策略	描述
balanced（默认）	智能平衡成本和质量
cost-first	优先选择能力足够且费用最低的提供商
quality-first	优先选择层级最高的提供商

示例： 如果你的 Google 账号包含 Antigravity 访问权限，系统可以优先使用 AGY 进行分析，而不调用已弃用的 Gemini CLI。

路由 CLI 标志

# Force a specific provider
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --provider agy auto "analyze code structure"

# Prefer cheapest option
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --cost-first auto "research best practices"

# Prefer highest quality
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --quality-first auto "complex refactoring task"

# OpenRouter routing variants
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --openrouter-nitro auto "quick task"  # Fastest
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --openrouter-floor auto "bulk task"   # Cheapest

配置

可在 setup 期间或通过 providers 配置文件配置提供商层级：

# Run setup wizard (includes provider tier steps)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup

# View current provider status
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh status

配置文件：~/.claude-octopus/.providers-config

version: "2.0"
providers:
  codex:
    installed: true
    auth_method: "oauth"
    subscription_tier: "plus"    # free|plus|pro|api-only
    cost_tier: "low"             # free|low|medium|high|bundled|pay-per-use

  agy:
    installed: true
    auth_method: "oauth"
    subscription_tier: "google"     # service-managed Google access
    cost_tier: "bundled"

  openrouter:
    enabled: false
    routing_preference: "default"   # default|nitro|floor

  orcarouter:
    enabled: false

cost_optimization:
  strategy: "balanced"  # cost-first|quality-first|balanced

OpenRouter 备用方案

当无法使用直接外部 CLI 时，OpenRouter 提供 400+ 个模型作为通用备用方案：

# Set up OpenRouter API key
export OPENROUTER_API_KEY="sk-or-..."

# Re-run setup to configure
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup

OrcaRouter 备用方案

当无法使用直接外部 CLI 时，OrcaRouter 通过单一网关提供多种模型，作为通用备用方案：

# Set up OrcaRouter API key
export ORCAROUTER_API_KEY="sk-orca-..."

# Re-run setup to configure
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup

工作区结构

~/.claude-octopus/
├── results/
│   ├── probe-synthesis-*.md      # Research findings
│   ├── grasp-consensus-*.md      # Problem definitions
│   ├── tangle-validation-*.md    # Quality gate reports
│   └── delivery-*.md             # Final deliverables
├── logs/                         # Execution logs
├── plans/                        # Execution plan history
└── .gitignore

工作流示例

研究优先的开发

# 1. Explore the problem space
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "Authentication patterns for microservices"

# 2. Define the approach (with the path step 1 printed after "Probe synthesis saved to:")
PROBE_SYNTHESIS="<printed probe-synthesis-*.md path>"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "OAuth2 with JWT for our API" \
  "$PROBE_SYNTHESIS"

# 3. Implement with validation
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement OAuth2 authentication"

# 4. Deliver with quality checks
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Finalize auth implementation"

快速构建（自动路由）

# Auto-detects "build" intent -> runs tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build a rate limiting middleware"

完整功能开发

# All 4 phases in one command
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Create a user notification system with email and push support"

最佳实践

1. 为需要探索的新功能从 embrace 开始
2. 在确定方案前进行研究时，单独使用 probe
3. 根据意图进行智能路由时使用 auto
4. 通过将上一阶段的结果文件作为第二个参数传入，串联各阶段以实现渐进式工作流
5. 运行 preflight，在启动长工作流前验证依赖项
6. 在继续执行 ink 前，检查 tangle 输出中的质量门槛

故障排除

预检失败

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh preflight
# Verify: codex CLI, agy CLI, and task-relevant provider credentials

质量门槛未通过

Tangle 阶段要求成功率达到 75%。如果未达到：

• 将任务拆分为更小的子任务
• 使用 -t 600 增加超时时间
• 检查 ~/.claude-octopus/logs/ 中各 Agent 的日志

重置工作区

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh clean
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh init