Power Spawn

PowerSpawn-通用多代理MCP服务器

直播： powerspawn.com | 版本1.6.2

Spawn Claude、Codex和Copilot来自一位协调员。你的特工会留下书面记录。

用于跨模型AI代理编排的轻量级MCP服务器。适用于Claude Code、GitHub Copilot和任何兼容MCP的客户端。通过CLI和API提供商支持GPT、Claude、Gemini、Grok和Mistral模型。

______________________________________________________________________

两种操作模式

PowerSpawn提供了两种不同的方法来生成代理，每种方法都有不同的功能：

CLI代理（完全自主）

将CLI代理用于：

• 跨多个文件的代码重构
• 运行测试套件并修复故障
• 通过文件创建创建新功能
• Git操作和提交
• 任何需要文件系统访问的任务

API代理（仅限文本响应）

将API代理用于：

• 研究和总结（协调员应用结果）
• 从不同的模型中获得“第二意见”
• 起草文本（求职信、文件）
• 代码审查分析（协调员应用修复程序）
• 翻译、头脑风暴、构思
• 对多个模型的并行查询

主要区别

CLI Agent:   Coordinator → Agent → [MODIFIES FILES] → Result
API Agent:   Coordinator → Agent → [TEXT RESPONSE] → Coordinator applies changes

API代理的示例工作流：

Coordinator: "Ask Gemini and Grok to review this function"
→ spawn_gemini("Review this code: ...")
→ spawn_grok("Review this code: ...")
→ Both return analysis text
→ Coordinator synthesizes feedback and applies fixes

为什么选择PowerSpawn？

1.使用您现有的CLI订阅

PowerSpawn产卵 真正的CLI代理 （Claude Code、GitHub Copilot、Codex），你已经安装了。无需单独管理API密钥，只需使用现有订阅即可。

2.确定性，不抱希望

MCP服务器 包裹 子代理并确定地处理所有日志记录。我们不依赖代理“按照指示”更新文件——编排器会自动捕获输入/输出。

3.在订阅之间分配负载

达到克劳德的利率上限？代之以培养一名食品法典委员会的特工。PowerSpawn让你 平衡多个AI订阅的工作，最大限度地提高您的吞吐量。

4.对用户和协调员的全面监督

• IAC.md -代理间上下文：顶部的活动代理表+所有输入和输出的完整审计跟踪（最新的第一个，最后15个条目）

5.跨会话的持久内存

基于文件的状态意味着 会话可以恢复 即使在：

• 协调器代理在上下文窗口外运行
• 进程重新启动或崩溃
• 工作会议之间的时间或天数

6.同一项目中的并行工作

多个代理可以同时处理不同的任务。基于文件的架构可以防止冲突，并提供清晰的分离。

7.扩展上下文窗口

子代理执行繁重的工作——读取文件、搜索代码、运行测试——并返回 简明摘要 而不是原始数据。您的协调员的上下文保持精简，从而能够：

• 更长的会议 在达到上下文限制之前
• 更复杂的任务 在模型约束范围内
• 更专注 关于编排，而不是文件内容

______________________________________________________________________

与其他框架的比较

IAC模式（代理间上下文）

传统的多智能体系统使用内存消息传递或数据库。PowerSpawn使用单个 markdown文件 （IAC.md）作为状态跟踪器和通信信道：

┌─────────────────────────────────────────────────────────────────┐
│                    COORDINATOR (Claude/Copilot)                 │
│                    Reads IAC.md, writes tasks                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
              ┌─────────────────────────────┐
              │         IAC.md              │
              │  • Task assignments         │
              │  • Agent results            │
              │  • Human-readable log       │
              │  • Git-trackable            │
              └─────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CODEX SUB-AGENT │ │ CLAUDE SUB-AGENT│ │COPILOT SUB-AGENT│
│ • GPT-5.1       │ │ • Claude models │ │ • GPT/Claude/   │
│ • Reads AGENTS  │ │ • Reads CLAUDE  │ │   Gemini models │
│ • Writes IAC.md │ │ • Writes IAC.md │ │ • Reads AGENTS  │
└─────────────────┘ └─────────────────┘ └─────────────────┘

为什么这很重要：

• 可审计的：每个代理交互都记录在简单的markdown中
• 可调试：阅读IAC.md，看看到底发生了什么
• 持久：进程重启、会话超时后仍能生存
• 版本可控：Git跟踪您的代理历史记录

新颖性研究（2025年12月）

我们分析了900多个MCP存储库和主要框架。调查结果：

最接近的竞争对手: claude-flow （1k星）-但只有Claude，不支持跨型号。

安装

PowerSpawn作为 git子模块 -不需要包管理器。

添加到您的项目

# Add as submodule
git submodule add https://github.com/CynaCons/PowerSpawn.git powerspawn

# Install Python dependencies
pip install mcp

Windows:安装PowerShell核心（Copilot shell命令需要）

Copilot CLI使用PowerShell核心(pwsh)用于Windows上的shell命令。没有它，文件操作（创建、编辑、读取）可以工作，但shell命令会失败。

# Install via winget
winget install Microsoft.PowerShell

# Verify installation
pwsh --version  # Should show PowerShell 7.x

注： 安装后，重新启动终端以使PATH更改生效。

配置您的MCP客户端

克劳德代码（需要两个文件）

步骤1：定义MCP服务器 (.mcp.json 在项目根目录中）：

{
  "$schema": "https://raw.githubusercontent.com/anthropics/mcp/main/schema/mcp.json",
  "mcpServers": {
    "agents": {
      "command": "python",
      "args": ["powerspawn/mcp_server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

步骤2：启用MCP服务器 (.claude/settings.local.json):

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": []
  },
  "enabledMcpjsonServers": [
    "agents"
  ],
  "enableAllProjectMcpServers": true
}

步骤3：重新启动Claude代码 加载MCP服务器。

注： 这 .claude/ 如果目录不存在，则会自动创建。这两个文件都是必需的- .mcp.json 定义服务器，以及 settings.local.json 使之成为可能。

GitHub副本（单个文件）

.vscode/mcp.json:

{
  "servers": {
    "powerspawn": {
      "command": "python",
      "args": ["powerspawn/mcp_server.py"],
      "cwd": "${workspaceFolder}"
    }
  }
}

更新到最新版本

git submodule update --remote powerspawn

快速开始

使用克劳德代码

配置后，这些MCP工具可用：

mcp__agents__spawn_claude   - Spawn Claude sub-agent (haiku/sonnet/opus)
mcp__agents__spawn_codex    - Spawn Codex sub-agent (GPT-5.1)
mcp__agents__spawn_copilot  - Spawn Copilot sub-agent (GPT/Claude/Gemini)
mcp__agents__list           - List running/completed agents
mcp__agents__result         - Get agent result by ID
mcp__agents__wait_for_agents - Wait for all agents to complete

示例提示：

“你能在审查代码时为Codex生成一个powerspawn来运行测试套件吗？”

独立Python

from spawner import spawn_claude, spawn_codex, spawn_copilot

# Spawn Claude for code review
result = spawn_claude("Review src/App.tsx for security issues")

# Spawn Codex for testing (preserves Claude rate limit)
result = spawn_codex("Run npm test and report failures")

# Spawn Copilot with any model (GPT, Claude, or Gemini)
result = spawn_copilot("Analyze this codebase structure", model="gpt-5.1")
result = spawn_copilot("Write documentation", model="gemini")

建筑

powerspawn/
├── mcp_server.py      # MCP server entry point (~500 lines)
├── spawner.py         # Core spawn logic for Claude/Codex
├── api_providers.py   # API provider implementations (Grok, Gemini, Mistral)
├── logger.py          # IAC.md logging with file locking
├── context_loader.py  # Example: future role-based context (not currently used)
├── parser.py          # Response parsing (JSON, JSONL)
├── __init__.py        # Package exports
├── requirements.txt   # Python dependencies (just 'mcp')
├── schemas/           # JSON output schemas
├── examples/          # Usage examples
├── site/              # Landing page (powerspawn.com)
├── README.md          # This file
├── MCP_DESIGN.md      # Detailed architecture docs
└── DESIGN.md          # Original design document

自动生成的文件（gitignored）：

• IAC.md -代理间上下文（活动代理+交互历史）

关键文件

上下文文件（由CLI自动加载）

PowerSpawn依赖于CLI工具的内置上下文加载：

这些文件应包含：

• 项目结构概述
• 关键文件位置
• 当前冲刺/迭代目标
• 角色指南（注意事项）

IAC.md-代理间上下文

顶部包含活动代理状态，后面是交互历史记录。协调员在此处编写任务分配。代理阅读说明并附加结果。格式：

## Task: Run Production Tests
**Assigned to:** Codex
**Status:** In Progress
**Timestamp:** 2025-12-01T20:30:00

### Instructions
Run `npm run test:production` and report any failures...

### Result
[Agent appends result here when complete]

AGENTS.md-食品法典委员会代理说明

由Codex CLI自动加载。定义：

• 可用工具和限制
• 输出格式期望
• 项目惯例
• 行为准则

MCP工具参考

spawn_claude

{
  "prompt": "Your task description",
  "model": "sonnet",        // haiku | sonnet | opus
  "timeout": 600            // seconds (default: 600)
}

spawn_codex

{
  "prompt": "Your task description"
}

spawn_copilot

{
  "prompt": "Your task description",
  "model": "gpt-5.1"  // gpt-5.1 | gpt-5 | gpt-5.1-codex | gpt-5-mini |
                       // claude-sonnet | claude-haiku | claude-opus | gemini
}

可用型号：

spawn_grok

通过X.ai API生成Grok子代理（仅限文本响应）。

{
  "prompt": "Your task description",
  "model": "grok-3",           // grok-3 | grok-3-fast
  "system_prompt": "Optional role context"
}

注： API代理-仅返回文本，不能修改文件。

spawn_gemini

通过Google API生成Gemini子代理（仅限文本响应）。

{
  "prompt": "Your task description",
  "model": "gemini-2.0-flash"  // gemini-2.0-flash | gemini-1.5-pro | gemini-1.5-flash
}

注： API代理-仅返回文本，不能修改文件。

spawn_mistral

通过Mistral API生成Mistral子代理（仅限文本响应）。

{
  "prompt": "Your task description",
  "model": "mistral-large"     // mistral-large | mistral-small | codestral | devstral
}

注： API代理-仅返回文本，不能修改文件。

列表

返回正在运行和已完成的代理ID。

结果

{
  "agent_id": "abc123"
}

返回代理的输出、成本和状态。

服务员

阻塞，直到所有正在运行的代理完成。返回所有结果。

用例

1.平行测试+审查

Coordinator: "Spawn Codex to run tests while I review the PR"
→ Codex runs tests (doesn't consume Claude rate limit)
→ Claude reviews code
→ Both results collected

2.研究任务

Coordinator: "Powerspawn an Opus agent to research multi-agent patterns"
→ Opus agent does deep research with web search
→ Results written to IAC.md
→ Coordinator summarizes findings

3.大规模重构

Coordinator: "Spawn 4 agents to migrate different test file groups"
→ Agent 1: tests/editor/01-10
→ Agent 2: tests/editor/11-20
→ Agent 3: tests/editor/21-30
→ Agent 4: tests/editor/31-40
→ All run in parallel, results collected

配置

环境变量：

• ANTHROPIC_API_KEY -对于克劳德的经纪人
• OPENAI_API_KEY -食品法典委员会代理

代理默认值位于MCP服务器中。通过工具参数进行覆盖。

API提供程序密钥

对于API代理（Grok、Gemini、Mistral），通过以下方式配置密钥：

1. 本地文件 （优先）：创建 api_keys.json:

   {
     "XAI_API_KEY": "your-grok-key",
     "GEMINI_API_KEY": "your-gemini-key",
     "MISTRAL_API_KEY": "your-mistral-key"
   }

1. 环境变量：设置 XAI_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY

支持的别名： GROK_API_KEY, GOOGLE_API_KEY 也工作。

从以下位置获取密钥：

• Grok：https://console.x.ai
• 双子座：https://aistudio.google.com/apikey
• 米斯特拉尔：https://console.mistral.ai

深潜：设计哲学

要全面了解PowerSpawn的架构和我们设计决策背后的推理，请阅读 设计.md.

主要亮点：

• 为什么要进行确定性日志记录？ 代理人在自我报告方面95%不可靠（第6.1节）
• 分层监管模式 -用户→ 协调员→ python→ 次级代理人（第2.3节）
• 决定论原理 -所有可以确定地完成的事情都应该是（第2.1节）
• 代理能力矩阵 -何时使用Claude vs Codex（第11节）

故障排除

文件写入的副本“权限被拒绝”

症状： 复制代理在尝试创建或编辑文件时报告“权限被拒绝，无法向用户请求权限”。

原因： 这 --allow-tool Copilot CLI中的标志 可变参数列表，这意味着必须将多个工具作为参数传递给单个标志。

错误：

copilot --allow-tool shell --allow-tool write  # Each flag only gets one arg

对的：

copilot --allow-tool shell write  # Both tools as args to one flag

在代码中修复：

# Wrong - separate flags
cmd = ["--allow-tool", "shell", "--allow-tool", "write"]

# Correct - single flag with multiple args
cmd = ["--allow-tool", "shell", "write"]

这在PowerSpawn v1.6.2（spawner.py:611）中得到了修复。

______________________________________________________________________

路线图

• \[x\] 登陆页面powerspawn.com
• \[x\] GitHub Copilot集成（spawn_Copilot）
• \[x\] API代理商：Grok、Gemini、Mistral
• \[\]MCP注册表提交
• \[\]单元和集成测试套件

许可证

麻省理工学院-使用它，分叉它，改进它。

______________________________________________________________________

使用AI构建，用于AI编排。

*部分 电源时间线 项目。*