使用说明
🔄 代理池
claude mcp add agent-pool -- npx -y github:Sceat/agent-pool
⚠️ 安全警告
生成的代理在绕过所有权限的情况下运行
代理是通过以下方式生成的 --dangerously-skip-permissions，这意味着他们可以：
- 执行 任何shell命令 未经批准
- 读/写 任何文件 在您的系统上
- 访问 网络资源 自由地
- 继承你的 全环境 （环境变量、凭据、SSH密钥）
这是有意为之的——编排要求代理自主工作。然而：
- ✅ 仅使用受信任的代理定义 来自您控制的来源
- ✅ 审查代理提示 在
agents/*.md跑步前 - ❌ 从不运行不受信任的代理 或来自未知来源的代理定义
你对你的代理人所做的事情负责。
为什么存在
Claude Code的母语 Task 工具有 关键内存泄漏问题 这会导致进程从数百MB增长到数十GB，最终崩溃：
| 问题 | 描述 |
|---|---|
| #7020 | 子代理编排：450MB→ 30GB，然后崩溃 |
| #4953 | 进程增长到120GB+RAM，OOM被杀死 |
| #11315 | 129GB虚拟内存消耗 |
| #11155 | Bash输出永久存储在内存中，使用量90GB+ |
| #8382 | v2.0.0：每个进程26GB |
根本原因： 每 Task 工具调用会生成一个新的子流程。记忆会累积，永远不会释放。
代理池的解决方案： 保持Claude CLI子流程的活动状态并使用 /clear 在保留热提示缓存的同时重置上下文。无新进程=无内存泄漏。
运作原理
Native Task Tool (leaky): agent-pool (stable):
────────────────────────── ──────────────────────
Task 1 → spawn → 450MB Warmup → spawn → 450MB
Task 2 → spawn → 900MB ↑ Task 1 → /clear → 450MB (cached)
Task 3 → spawn → 1.3GB ↑ Task 2 → /clear → 450MB (cached)
Task 4 → spawn → 1.7GB ↑ Task 3 → /clear → 450MB (cached)
... ...
Task N → OOM KILLED 💀 Task N → still 450MB ✓
奖金： 相同的进程=相同的系统提示=提示缓存命中率= 约90%的代币节省.
快速开始
claude mcp add agent-pool -- npx -y github:Sceat/agent-pool
// Warm up agent (optional, creates prompt cache)
mcp__agent-pool__warmup({ agent: "code-reviewer" })
// Send tasks - all reuse the same process
mcp__agent-pool__invoke({ agent: "code-reviewer", task: "Review src/auth.js" })
mcp__agent-pool__invoke({ agent: "code-reviewer", task: "Review src/api.ts" })
mcp__agent-pool__invoke({ agent: "code-reviewer", task: "Review src/db.js" })
// Check active agents
mcp__agent-pool__list()
api参考
| 工具 | 说明 |
|---|---|
invoke(agent, task) |
将任务发送给代理，获取结果，自动重置上下文 /clear |
warmup(agent) |
预生成代理用于预热提示缓存（可选） |
list() |
显示带有PID的活动代理 |
reset(agent) |
终止代理进程（下次调用时重新启动） |
代币节省
| 任务 | 本机任务 | 代理池 | 节省 |
|---|---|---|---|
| 1 | 2,000 | 2,000 | 0% |
| 3 | 6,000 | 2,600 | 57% |
| 5 | 10,000 | 3,200 | 68% |
| 10 | 20,000 | 4,700 | 76% |
系统提示（约1500个令牌）在第一次调用后缓存。后续通话仅按任务内容付费。
建筑
┌─────────────────────────────────────────────────────────────┐
│ Claude Code │
└──────────────────────────┬──────────────────────────────────┘
│ MCP Protocol
┌──────────────────────────┴──────────────────────────────────┐
│ agent-pool MCP Server (Node.js) │
│ invoke() │ warmup() │ list() │ reset() │
└─────┬───────────┬───────────┬───────────┬───────────────────┘
│ │ │ │
┌──┴──┐ ┌──┴──┐ ┌──┴──┐ ┌──┴──┐
│Agent│ │Agent│ │Agent│ │Agent│ ← Persistent processes
│ PID │ │ PID │ │ PID │ │ PID │ (not respawned)
└─────┘ └─────┘ └─────┘ └─────┘
↑ ↑ ↑ ↑
/clear /clear /clear /clear ← Context reset
(cache) (cache) (cache) (cache) (cache preserved)
创建自定义代理
创建 agents/my-agent.md 使用YAML frontmatter：
---
name: my-agent
description: What this agent does
skills:
- skill-name
expertise:
- expertise-name
---
Frontmatter标题
| 标题 | 描述 |
|---|---|
name |
代理标识符（用于 invoke({ agent: "name" })) |
description |
代理的作用（如所示 list() 输出） |
skills |
要注入的技能模块列表（从加载 SKILLS_DIR) |
expertise |
要注入的专业知识模块列表（从加载 EXPERTISE_DIR) |
技能和专业知识注入： 引用的技能/专业知识文件中的内容在生成时被注入到代理的系统提示符中。这允许代理功能的模块化组合。
然后调用： mcp__agent-pool__invoke({ agent: "my-agent", task: "..." })
💡 专业提示
禁用主编排器的MCP服务器，仅对子代理启用
使用编排器模式时，主Claude实例不需要直接访问工具——它应该只委托给专门的代理。
为什么这很重要：
- 减少上下文污染 -主实例侧重于编排，而不是工具输出
- 强制执行模式 -防止意外直接使用工具
- 更清洁的分离 -编排者思考，下属行动
工具访问模式：
| 实例 | 工具 |
|---|---|
| 主编排器 | mcp__agent-pool__invoke, Task, AskUserQuestion, TodoWrite |
| 子代理 | 完全MCP访问（Bash、读取、写入、Grep等） |
如何配置：
-
CLAUDE.md方法 -禁止在编排器的说明中直接使用工具：
# Orchestrator Rules - NEVER use Bash, Read, Write, Edit, or Grep directly - ALWAYS delegate work to specialized agents via mcp__agent-pool__invoke - Only use AskUserQuestion for user clarification -
选择性MCP注册 -仅注册主实例的代理池，不注册文件/外壳MCP
-
钩子 -使用Claude Code钩子阻止主实例的某些工具
这种模式使您的编排器保持干净，并强制进行适当的授权。
故障排除
| 问题 | 解决方案 |
|---|---|
| 找不到代理 | 检查 agents/name.md 存在和 name: 在前场比赛中 |
| 任务超时 | 运行 reset({ agent: "name" }) 杀死卡住的进程 |
| 插件未加载 | 验证 plugin.json 已存在，请完全重新启动Claude Code |
| 内存使用率高 | 请检查您使用的是代理池，而不是本机任务工具 |
完整指南： docs/TROUBLESHOOTING.md
文档
需求
- Claude CLI 2.0+带
--input-format stream-json支持 - Node.js 18+
许可证
专为Claude Code开发人员设计，厌倦了OOM的杀戮
