AgentPool

AgentPool

你订阅了多个编码 Agent 服务——Codex、Claude Code、Cursor、 Copilot、Devin、Droid——但每次只使用其中一个。其余订阅会一直闲置，直到 当前使用的服务达到 5 小时或每周限额，然后你就只能停下来。

AgentPool 是一个本地 Python CLI 和 MCP 服务，可读取你所有编码 Agent 订阅的实时使用限额， 并让你或你的主 Agent 将工作交给仍有余量的服务。充分利用你已付费购买的容量， 达到限额时也能继续推进工作，而不是被迫停下。

它是控制平面，而不是自动路由器。AgentPool 会公开实时的服务商、 模型、会话、制品、租约，以及尽力而为的使用量和容量状态，并将你交付的工作作为明确的工作会话运行。你或你的 Agent 仍需选择服务商和模型——AgentPool 会让限额一目了然，帮助你做出明智选择，但绝不会自动选择。

v0.1 alpha 的设计较为保守：

• tmux 是默认运行时；配置后也可选用 Terminal Control。
• 必须明确选择服务商；不接受 provider=auto。
• 使用量和容量摘要会标注可信度，并以服务商 ID 为键。
• 安装或配置后，可选用 CodexBar 和 ccusage 作为使用量辅助工具。
• AgentPool 不会存储服务商凭据、抓取浏览器中的使用量页面、对模型进行排名、合并代码或推送代码。

要求

• Python 3.11 或更高版本。
• PATH 中需有 tmux。
• 可选：使用 Terminal Control 运行时需在 PATH 中配置 termctrl。
• 使用 worktree 隔离和收集差异需安装 Git。
• 实时运行时支持 macOS 或 Linux。除 WSL 类 shell 环境外，Windows 不是 v0.1 的目标平台。

安装

AgentPool 以 agentpool-cli 的名称发布到 PyPI；安装后的命令为 agentpool。

uv tool install agentpool-cli      # recommended
pipx install agentpool-cli         # fallback
uvx agentpool-cli --help           # zero-install try

然后：

agentpool setup codex
agentpool doctor --deep --privacy

agentpool-cli 软件包可安装在 macOS、Linux 和 Windows 上，但实时终端运行时仅支持 macOS 或 Linux（Windows 需通过 WSL）。

可选的 Terminal Control 配置：

runtime:
  default: tmux
  terminal_control:
    enabled: true
    binary: termctrl
    session_prefix: agentpool
    cols: 120
    rows: 36

从源代码安装：

git clone https://github.com/sidduHERE/agentpool.git
cd agentpool
uv tool install --force .

或者从开发检出目录运行：

uv venv
uv pip install -e ".[dev]"

也支持通过 GitHub release 安装（wheel 固定到指定标签，无需使用 PyPI）：

scripts/install.sh latest

首次运行、升级和 MCP 配置说明，请参阅 docs/install.md。

快速入门

对于 AI Agent，请先加载随附且版本匹配的技能：

agentpool skills get agentpool
agentpool skills get core --full

agentpool init
agentpool setup cursor
agentpool config validate
agentpool doctor --deep --privacy
agentpool setup all
agentpool smoke --provider fake-question --repo . --json
agentpool inventory --json
agentpool usage-summary --refresh --json

你最常运行的就是最后一条命令：它会显示每个已配置订阅的剩余限额、重置时间和 usable 标志，让你一眼看出下一个任务适合交给哪个服务商。

启动一个明确指定且只读的工作进程：

agentpool spawn \
  --provider <provider-id> \
  --repo . \
  --task "Inspect the project and ask one clarifying question." \
  --isolation read_only

agentpool observe <session-id> --wait-for completed,error,question,approval_prompt --timeout 60 --json
agentpool send <session-id> "Continue with the smallest useful check."
agentpool artifacts <session-id> --json
agentpool transcript <session-id> --tail-lines 80 --json
agentpool session show <session-id> --json
agentpool sessions --recent 10 --json
agentpool collect <session-id> --json
agentpool terminate <session-id> --dry-run --json
agentpool terminate <session-id> --json

spawn 的 --initial-prompt-mode 默认值为 provider_default。对于 Codex CLI，该值会解析为 arg，将第一个任务作为 Codex 提示词参数传入，而不是依赖启动后粘贴并提交的流程。支持推理控制的服务商也接受进程级覆盖选项，例如 --reasoning-effort high；Codex 还接受 --service-tier priority。 AgentPool 不会修改你的服务商配置。

如需使用 AgentPool 创建编辑隔离，请明确选择 worktree：

agentpool spawn \
  --provider <provider-id> \
  --repo . \
  --task "Make the small patch." \
  --role implementer \
  --isolation worktree

agentpool worktrees list --repo .
agentpool worktrees cleanup --session-id <session-id> --dry-run --json
agentpool worktrees cleanup --session-id <session-id>

默认不会强制启用 worktree 隔离。用户通常有自己的 worktree 设置和清理规则，因此 AgentPool 仅会在通过 --isolation worktree 或策略配置提出请求时创建 worktree。

用量与容量

agentpool usage-summary --refresh --json
agentpool usage-summary --refresh --no-interactive --json
agentpool stats --since 7d --json
agentpool usage-summary --refresh --backend codexbar --json
agentpool usage-summary --refresh --backend ccusage --provider claude-code --json

usage-summary 会返回一个以提供商 ID 为键的 providers 对象。它没有排序，也不是推荐列表。每一行都包含 usable、unusable_reason、配额窗口、可信度、时效性以及提供商提供的重置时间。旧版 CLI capacity-summary 命令仍作为便于人工使用的别名保留；MCP 也将 get_capacity_summary 作为 get_usage_summary 的兼容别名公开。

默认缓冲值为 policy.min_remaining_percent = 10。如果报告中的任何配额窗口低于该缓冲值，摘要中该提供商行就会标记为不可用。过时情况仅以时长信息报告；这本身不会导致提供商不可用。如果希望缓存的摘要读取在达到阈值后自动刷新，请在 ~/.agentpool/config.yaml 中设置 policy.usage_auto_refresh_after_seconds。 AgentPool 仍不会替你选择其他提供商。 MCP 用量刷新有意设定了上限，可能会返回 partial=true；当具备 shell 能力的 Agent 需要完整的实时刷新时，请使用上述 CLI 命令。如果 shell 脚本必须避免回退探测提供商 TUI，请使用 --no-interactive 或 AGENTPOOL_NO_INTERACTIVE_USAGE=1。

提供商矩阵

提供商 ID	命令	v0.1 中的用量状态	模型固定
codex-cli	codex	原生本地 app-server 速率限制探测；CodexBar 可选	--model + 配置范围内的推理/服务层级
cursor-cli	agent 或 cursor-agent	可选的 CodexBar Cursor 用量；原生 CLI 用量仅支持交互式 /usage	--model + 只读 --mode ask
claude-code	claude	临时 /usage 探测；ccusage 遥测可选	--model + --effort
devin-cli	devin	使用现有 CLI 身份验证调用 Devin/Windsurf 计划状态 API，失败时回退到 /usage	--model
copilot-cli	gh copilot	从环境变量或 gh auth token 获取 GitHub Copilot 用量 API	转发 --model
droid-cli	droid	除非未来通过安全探测获取，否则状态未知	进程本地设置文件 + --reasoning-effort
opencode	opencode	已配置适配器；此 alpha 版本中用量未知	使用提供商/模型 ID 的 --model

兼容性说明：PRD 将 Factory 的编码产品称为 factory-droid，但 AgentPool 将其公开为 droid-cli，因为已安装的命令是 droid。除非出现不同的运行框架，否则不要添加重复的 factory-droid 清单行。

隐私立场

AgentPool 优先采用本地处理，但用量探测仍可能涉及敏感信息，因为它会读取现有 CLI 身份验证状态，并可能在明确刷新时调用提供商 API。

AgentPool 不会：

• 存储提供商凭据；
• 默认读取浏览器 Cookie；
• 抓取浏览器控制面板；
• 触发登录流程；
• 静默接受付费超额用量。

AgentPool 会存储：

• SQLite 会话、事件、用量快照、工件和租约元数据；
• 默认存放在 ~/.agentpool/artifacts 下的转录和工件文件；
• 非凭据类的生成运行时设置。

运行：

agentpool doctor --privacy --json

请参阅 SECURITY.md 和 docs/usage-detection.md。

MCP

启动 MCP 服务：

agentpool mcp
agentpool mcp --toolsets default,stats
AGENTPOOL_MCP_LOCKDOWN=1 agentpool mcp

主机配置示例：

agentpool mcp-config --client generic

{
  "mcpServers": {
    "agentpool": {
      "command": "agentpool",
      "args": ["mcp"]
    }
  }
}

已验证的安装助手（深层链接或单行 Shell 命令）：

agentpool mcp-config --client cursor --absolute-command --install
agentpool mcp-config --client claude-code --absolute-command --install
agentpool mcp-config --client codex --absolute-command --install
agentpool mcp-config --client copilot-cli --absolute-command --install

原始配置生成器：

agentpool mcp-config --client claude-code --json
agentpool mcp-config --client codex
agentpool mcp-config --client cursor
agentpool mcp-config --client claude-desktop --json

如果 MCP 主机无法继承你的 Shell PATH，请使用 --absolute-command。 各主机经过验证的操作步骤见 docs/mcp-clients.md。 团队模板：.cursor/mcp.json.example、 .mcp.json.example 和 docs/examples/README.md。 MCP Registry 元数据：server.json。其中列出了 agentpool-cli PyPI 软件包，并应在每次发布时更新。发布 检查清单：docs/release.md。 提供方设置指南： Cursor、 Cursor Agent CLI、 Codex、 Claude Code、 Copilot、 Droid 和 Devin。

已连接 MCP 的 Agent 应在连接时读取以下内容：

• agentpool://onboarding
• agentpool://skill.md
• agentpool://preferences.md

然后使用工具执行实时操作。用户拥有的偏好文件也可通过 agentpool preferences 和 get_delegation_preferences() 查看。该文件可能会指示你在某些任务中使用原生子 Agent 系统，而不是 AgentPool。默认 MCP 工具集有意保持精简：清单、用量快照、用量摘要、提供方模型、偏好设置、生成、观察、轮询、发送、中断、收集、构件清单、转录分页和终止。使用 agentpool mcp --toolsets default,stats,sessions,leases,worktrees 添加可选工具集。

具备 Shell 能力的 Agent 可以使用 agentpool skills get agentpool，通过已安装的 CLI 加载相同的核心用法指南，以替代 MCP 资源。

可访问 Shell 的编码 Agent 应优先使用 CLI 路径。这样更节省 token，因为大型工作器输出会保留在构件文件中，而 observe/collect 默认返回精简清单。对于原生支持 MCP 的主机和无 Shell 环境，MCP 仍是首选方案。参见 docs/agent-cli-and-mcp.md。

开发检查

开发和 CI 检查已记录在 CONTRIBUTING.md 中。