Pi Durabletask MCP

已从 pi-durabletask-mcp 更名为 pi-durateam：请安装 pi-durateam。旧命令仍可使用；配置、PI_DELEGATE_* 变量、已存储状态和工具名称均未更改。

主 Agent 负责规划、选择模型并评估结果。阅读、搜索和交叉核查任务交由 Pi 代理执行——可使用 Gemini、Grok、GPT、DeepSeek 或 Pi 支持的其他提供商——消耗这些提供商的配额，而不是 Claude Code 或 Codex 的配额；返回内容是简明状态和最终报告，或者仅提供文件路径。在我们的发布前评审中，4 个 Agent 使用 Gemini、Grok 和 GPT 模型阅读了约 200 万个 token 的代码库，而 Claude 会话收到的报告约为 7 KB。

• team — 执行一个或多个并行任务，将同一问题交给多个模型，分叉后只读一次并回答多个问题，选择启用协调器，以及按代理授予 MCP 服务（只读 GitHub、浏览器）。
• dura — 每次运行都设有轮次、时间和工具调用预算，并预留最后一轮用于作答且不调用工具。还可选择启用软截止时间、提供商出错时的模型回退，以及在服务重启后仍可保留的会话。

例如，可以向 Agent 提出：“使用 Pi 并行调用 Gemini、Grok 和 GPT 审查附带的 diff。不要编辑文件。仅报告确实存在的缺陷，并注明 file:line。” 它会使用一个共享的 prompt 和 3 个模型调用 spawn_batch，再通过 wait 收集结果，并得到 3 份独立报告，其中包含 token 用量和费用。

快速开始

需要 macOS 或 Linux、Node.js 22.19+ 和 Pi。 CI 使用 Node.js 22 和 24，针对 Pi 1.0.0、1.0.4、1.1.0 和 1.3.0 运行测试。模型调用使用你自己的提供商凭据。

1 · 安装 Pi（如果已安装可跳过），并登录提供商：

curl -fsSL https://pi.dev/install.sh | sh
pi  # then /login, or configure a provider

2 · 安装 pi-durateam：

npm install -g pi-durateam@latest

git clone https://github.com/Nyarlathoteppppp/pi-durateam.git
cd pi-durateam && npm ci && npm run build
# below, use `node /absolute/path/pi-durateam/dist/index.js` instead of `pi-durateam`

3 · 连接。 Claude Code：

claude mcp add --scope user pi -- pi-durateam

Codex（~/.codex/config.toml）：

[mcp_servers.pi]
command = "pi-durateam"

Codex 桌面应用使用精简的 PATH 启动 MCP 服务（不包含 Homebrew 或 nvm 目录），因此可能既找不到 pi-durateam，也找不到用于运行它的 node。这样服务就无法启动，会话中也不会出现 Pi 工具。请在此处使用绝对路径：

[mcp_servers.pi]
command = "/opt/homebrew/bin/node" # output of `which node`
args = ["/opt/homebrew/lib/node_modules/pi-durateam/dist/index.js"] # under `npm root -g`
[mcp_servers.pi.env]
PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" # inherited by what the server starts

更新 pi-durateam 或 Pi 后，请重新连接 MCP 服务。其他客户端 →

4 · 试试看：“使用 Pi 检查 auth 模块是否缺少权限检查。只读。” init 会显示模型、提供商凭据和设置；models 会列出代理可以使用的模型。

dir="$HOME/.claude/skills/pi-durateam" # Claude Code
# dir="$HOME/.agents/skills/pi-durateam" # Codex: use instead
mkdir -p "$dir"
curl -fsSL https://raw.githubusercontent.com/Nyarlathoteppppp/pi-durateam/main/skills/pi-durateam/SKILL.md \
  -o "$dir/SKILL.md"

• 委派。 spawn 会在后台启动一项任务，并立即返回 sessionId。spawn_batch 默认每次最多启动 4 项任务（PI_DELEGATE_BATCH_MAX），并会先检查每项任务，因此只要有一项无效，就不会启动任何任务。run 会阻塞，适合快速提问。使用 wait 和 until: "settled" 收集结果。
• 一个问题，多个模型。 批次级别的 prompt 会发送给每项任务；每项任务指定自己的 model，并附加各自的 prompt。不同的模型系列会忽略不同的内容，但意见一致并不代表正确：采取行动前请核实发现。
• 读取一次，多方提问。 forkFrom 会根据已完成会话的记录启动新任务，包括该会话已读取的文件；每个分支都会获得全新的预算。
• 引导并继续。 可对正在运行的委派任务使用 steer，回答其问题；对已完成的任务使用 follow_up（会保留它读取的内容）；必要时使用 abort。status 会报告 idleMs 和 phase，用于区分缓慢推理和请求卡住。
• 输入材料，输出报告。 attachments 会通过绝对路径传递差异或笔记；saveTo / saveDir 会将长报告写入文件并返回路径；usage 会提供令牌用量和费用。
• 协调器（可选启用）。 向 spawn 传递 coordinator 计划：Pi 协调器会调度团队成员、向其中一位提出有针对性的后续问题，并撰写一份引用原始报告的综合报告。需要在 PI_DELEGATE_ALLOW_TOOLS 中启用 codemode。大多数任务用 spawn_batch 并自行判断会更简单。工作流 →

每个委派任务可用的 MCP 工具

委派任务可以使用 Pi 的 mcp.json 中配置的 MCP 服务——例如只读的 GitHub、Serena、浏览器和网页搜索——并按任务选择；默认不启用任何服务。将服务添加到 ~/.pi/agent/mcp.json，在 pi-durateam 的环境中允许其确切工具名称（PI_DELEGATE_ALLOW_TOOLS="mcp__github__get_file_contents,mcp__github__search_code"），然后重新连接。随后在每次调用中选择要使用的服务：

{
  "cwd": "/absolute/repo",
  "nativeMcp": true,
  "mcpServers": ["github"],
  "tools": ["mcp__github__get_file_contents"],
  "prompt": "Read package.json of OWNER/REPO with GitHub MCP and report its version."
}

• 只有 mcpServers 中的服务会连接。对于这些服务，委派任务只能使用 tools 中列出的 mcp__<server>__<tool> 名称，且这些名称必须获得 PI_DELEGATE_ALLOW_TOOLS 许可；选择某个服务并不会授予其全部工具。
• 如果调用选择了服务，但未授予这些服务的任何工具，则会在启动前被拒绝——例如省略 tools（只读默认设置），或只指定 codemode 或 tool_search（它们只能访问 tools 中列出的工具）。tools: [] 仍会运行不带任何工具的任务。
• 对于委派任务，mcp.json 中服务的 exposure 设置无关紧要：tools 中列出的每个工具都会直接声明给委派任务，因此你可以在交互式 Pi 中将服务设为 deferred 或 codemode。设为 hidden 的工具仍无法访问。只有在脚本化循环中才将 codemode 添加到 tools；脚本也只能访问同样列出的工具。
• extensions 可以保持为 false。批次任务会继承 nativeMcp 和 mcpServers；协调器成员会自行选择。
• 获准使用的 MCP 工具可能会在 cwd 之外写入或执行操作，而且秘密路径防护不涵盖外部服务。请谨慎授予能力。

GitHub、Serena 和 agent-browser 的设置方法：可选工具。网页搜索：研究。详情和恢复方法：原生 MCP。

Dura：为顺利完成而运行

始终启用

• 轮次、时间和工具调用预算。spawn 和 spawn_batch 默认最多运行 30 轮、10 分钟；run 默认最多运行 12 轮、5 分钟；上限由 PI_DELEGATE_MAX_TURNS（默认值为 50）和 PI_DELEGATE_MAX_DURATION_MS（默认值为 15 分钟）设定。maxToolCalls 限制委派任务自身的调用次数。
• 当轮次或工具调用预算达到 75%，或已用时达到总时长的 2/3 时，委派任务会收到收尾提示；最后一轮不可使用工具，专用于给出答案。
• answerState 用于标记答案为空（missing）或被截断（partial）。运行结束时若没有答案（aborted、error），则会将最近一段有实质内容的文本作为 salvagedText 返回。已完成的结果会标明作答所用的模型。

选择启用

• 软截止时间（PI_DELEGATE_DEADLINE_GRACE_MS）：到达截止时间后，工具调用会被禁用，且不会启动新的工具调用；委派任务会在这段宽限时间内作答，只有仍未给出答案的运行才会中止。
• 模型回退（PI_DELEGATE_FALLBACK_MODELS，或按调用设置的 fallbackModels）：如果供应商错误在 Pi 重试后仍未解决，运行会在同一会话中继续使用下一个列出的模型，例如 "xai/*:high,antigravity/gemini-*"。在我们的使用场景中，Codex 配额错误现在会在几秒内切换到 Grok 继续运行。
• 对于持续调用工具的模型：PI_DELEGATE_ANSWER_GRACE=1 会额外提供一轮不可使用工具的机会；PI_DELEGATE_TOOL_CHOICE_NONE 会在该轮发送 toolChoice: "none"；运行即将结束时，PI_DELEGATE_FINISH_THINKING 会降低思考级别。
• 持久会话（durable: true）：使用 SQLite 检查点；服务器重启后，会话会使用原有 ID、历史记录和预算恢复；结果未知的工具调用绝不会盲目重放。默认保留已完成的会话 7 天（retentionDays、PI_DELEGATE_RETENTION_DAYS）。
• handoff：在一个 Claude/Codex 窗口中用 save 保存备注，再在另一个窗口中用 read 读取，以继续同一个持久会话。

安全默认设置

• 未提供 tools 的调用会获得只读工具集（read、grep、find、ls 或你设置的 PI_DELEGATE_DEFAULT_TOOLS）；其他工具必须通过 PI_DELEGATE_ALLOW_TOOLS 授权。这并非沙箱：如果委派任务获得了 bash，它就能执行你能执行的任何操作。
• 附件、读取和搜索均会拒绝访问机密路径（.env、~/.ssh、凭据）；将 PI_DELEGATE_SECRET_GUARD=0 设为 0 可关闭此保护。
• 会话保存在内存中，并在 MCP 进程结束时终止。除非手动启用，否则持久化存储、模型回退、软截止时间、答案宽限轮次、原生 MCP 和协调器均处于关闭状态。
• 默认情况下，每个服务进程最多同时运行 4 个委派任务（PI_DELEGATE_MAX_CONCURRENT）。无法解析的模型名称会被拒绝，不会替换为默认模型。

文档

• 参考文档：工具、配置、身份验证、原生 MCP
• 可选 MCP 工具 · 网络研究 · 审查与综合 · 协调器
• 开发 · 更新日志 · 问题反馈

MIT · 基于 howznguyen/pi-delegate-mcp 和 Pi Durable 构建。