Agent Pool

🔄 代理池

Claude Code内存泄漏问题的解决方法。生成代理一次，无限期重复使用。

claude mcp add agent-pool -- npx -y github:Sceat/agent-pool

______________________________________________________________________

⚠️ 安全警告

生成的代理在绕过所有权限的情况下运行

代理是通过以下方式生成的 --dangerously-skip-permissions，这意味着他们可以：

• 执行 任何shell命令 未经批准
• 读/写 任何文件 在您的系统上
• 访问 网络资源 自由地
• 继承你的 全环境 （环境变量、凭据、SSH密钥）

这是有意为之的——编排要求代理自主工作。然而：

• ✅ 仅使用受信任的代理定义 来自您控制的来源
• ✅ 审查代理提示 在 agents/*.md 跑步前
• ❌ 从不运行不受信任的代理 或来自未知来源的代理定义

你对你的代理人所做的事情负责。

______________________________________________________________________

为什么存在

Claude Code的母语 Task 工具有 关键内存泄漏问题 这会导致进程从数百MB增长到数十GB，最终崩溃：

根本原因： 每 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参考

______________________________________________________________________

代币节省

*系统提示（约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标题

技能和专业知识注入： 引用的技能/专业知识文件中的内容在生成时被注入到代理的系统提示符中。这允许代理功能的模块化组合。

然后调用： mcp__agent-pool__invoke({ agent: "my-agent", task: "..." })

______________________________________________________________________

💡 专业提示

禁用主编排器的MCP服务器，仅对子代理启用

使用编排器模式时，主Claude实例不需要直接访问工具——它应该只委托给专门的代理。

为什么这很重要：

• 减少上下文污染 -主实例侧重于编排，而不是工具输出
• 强制执行模式 -防止意外直接使用工具
• 更清洁的分离 -编排者思考，下属行动

工具访问模式：

如何配置：

1. 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

1. 选择性MCP注册 -仅注册主实例的代理池，不注册文件/外壳MCP

1. 钩子 -使用Claude Code钩子阻止主实例的某些工具

这种模式使您的编排器保持干净，并强制进行适当的授权。

______________________________________________________________________

故障排除

完整指南： docs/TROUBLESHOOTING.md

______________________________________________________________________

文档

• 安装指南 -先决条件和设置
• 用法和API -API完整参考和示例
• 建筑 -它在内部是如何工作的
• 故障排除 -常见问题和修复
• 贡献 -如何做出贡献

______________________________________________________________________

需求

• Claude CLI 2.0+带 --input-format stream-json 支持
• Node.js 18+

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

专为Claude Code开发人员设计，厌倦了OOM的杀戮