Pi Bridge

将 Codex 的有边界任务交给已安装的 Pi执行，并返回独立验收证据。提供 Skill、命令行和 stdio MCP 三种入口，使用同一套运行时。

• Windows、macOS、Linux 使用相同的 Node 程序，无需 PowerShell。

• 自动查找所选后端，支持 Pi 的 npm 全局安装、JS 入口和原生可执行程序。

• Pi 默认继承自己的模型、认证、代理和插件，也可指定 provider/model。

• 每个 Codex 聊天使用独立实例，保存任务、日志和恢复状态。

• 常驻 daemon 复用空闲 Pi worker；取消、超时、独立验收和失败恢复保持统一。

安装

前提：Node.js >=22.19（推荐 24 LTS）、npm、Git、Codex，以及已配置可用模型的 Pi。先确认Pi 的 pi --help 与 codex --help 正常。

三平台均可安装预构建包：

npm install -g https://github.com/UWPK/pi-bridge/releases/download/v0.4.4/uwpk-pi-bridge-0.4.4.tgz
pi-bridge check-local

该命令下载本仓库的构建包；npm 安装所需依赖需要网络。无需编译 TypeScript。使用自定义 npm 前缀时，确认全局 bin 目录已加入 PATH。

从源码开发：

git clone https://github.com/UWPK/pi-bridge.git
cd pi-bridge
npm ci
npm run build
node bin/pi-bridge.mjs check-local

Related MCP server: pi-agent-mcp

首次安装与验收

v0.4.4 提供分阶段安装诊断与可选模型验收。安装后运行：

pi-bridge setup --apply
pi-bridge setup --apply --verify

第一步检查 Git、Pi 入口、启动与工作进程参数，安装 skill 并输出完整 MCP 配置，不调用模型。默认沿用 Pi 的模型与认证；--pi-cli PATH、--profile inherit|minimal、--destination PATH 可指定入口、工作进程和共享技能目录。重复运行会复用一致的 skill；发现本机修改时停止并保留文件。

第二步需明确选择 --verify：会连接模型（可能计费），在专用临时 Git 工作区让 Pi 创建一个小文件，并由独立命令核对内容。通过后停止测试实例、删除测试文件；失败保留诊断目录与任务 ID，不自动重试，也不会影响日常实例。重新验证会创建新测试任务，先检查上一轮结果，避免重复费用。

结果区分 installed（依赖与安装检查通过）、verified（CLI 模型任务和独立验收通过）、blocked（安装检查未通过）、verification-failed（模型或验收失败）。只有真实验收通过才返回 modelVerified: true；这仍不代表 Codex 的 MCP 连接或未来任务的权限已经验证。

权限由宿主应用控制。Pi 首次启动可能写入自己的状态目录；Bridge 也需要保存运行状态。输出中的 permissions 列出预期路径与进程，用户可在宿主支持时选择保留所需授权。程序不会修改宿主权限配置、关闭审核或扩大整个用户目录的访问范围。如果宿主在命令运行前拦截，程序无法捕获该拒绝，应查看宿主给出的具体理由。自动审核拒绝后停止，用户通过正式权限入口解决后再手动重试。

复制输出中的完整 MCP 配置，接入宿主并检查连接。以后复用已选择的入口和模型；只有工作区、模型或权限范围变化时才确认新选择。

接入 Skill

pi-bridge install-skill --apply

默认安装至当前用户的 ~/.agents/skills/pi-bridge。已有同名目录会停止；使用 --destination <技能目录> 安装到独立的代理配置环境。重启或新建 Codex 聊天，然后明确调用 $pi-bridge。

技能运行时需要全局命令 pi-bridge，或由代理使用已安装包中 bin/pi-bridge.mjs 的绝对路径。程序保持安装后才可使用技能。

首次配置时选择模型

安装或重装时，skill 会先询问缺失的服务商、模型选择；当前聊天已给出的选择会直接沿用。复用后端现有认证，凭据在本机处理。Pi 模型选择保存到 Bridge 专用配置，日常 PiDeck 默认模型保持原样。配置完成后，以实际安装包执行一次有独立验收的小任务。详见 首次配置说明。

接入 MCP

推荐运行：

pi-bridge mcp-config

将输出的配置片段加入目标 Codex 配置，或在界面中添加等效的 stdio 服务。输出自动使用本机 Node 和 MCP 程序的绝对路径，并包含所选后端入口和工作进程配置的环境段，适合桌面应用 PATH 与终端不同的情况。请复制包含 [mcp_servers.pi_bridge.env] 的完整片段。程序只显示配置，不重写当前设置。

也可使用 Codex CLI 注册：

codex mcp add pi_bridge -- pi-bridge-mcp

需要 Codex 进程可以找到 pi-bridge-mcp；否则使用上面的绝对路径配置。Codex MCP 配置方式见 官方文档。

MCP 工具

每次调用填写同一聊天专属的 instance，例如 chat-<Codex聊天ID>。状态变更还需 apply:true。不同聊天使用不同实例；MCP 服务进程被复用时，调用仍按实例隔离。提交后持续查询 status，直到任务终止并审查验收结果。MCP 重连后使用原实例即可访问原状态。

如果只安装 MCP，在 Codex 项目说明中写明：委派给 Pi 时使用 pi_bridge_* 工具，每个聊天使用独立 instance，提交后轮询状态并验收 diff 和验证命令。

配置

Windows 默认状态位于 LOCALAPPDATA/pi-bridge，macOS 为 ~/Library/Application Support/pi-bridge，Linux 为 XDG_STATE_HOME/pi-bridge 或 ~/.local/state/pi-bridge。与本机旧版 Bridge 使用独立目录。自定义 Pi 安装可通过环境变量指定入口；已有正确的 Pi 配置保持原样。

完整 CLI、任务 JSON 与恢复流程见 技能运行说明。

插件较多时的精简工作进程

工作进程可独立配置：默认 inherit 完整继承 Pi；设置 PI_BRIDGE_WORKER_PROFILE=minimal 后，Bridge 工作进程关闭自动扩展、MCP、技能和提示模板加载。模型、认证和日常 PiDeck 配置保持原样。

通过 PI_BRIDGE_PI_ARGS 的 JSON 数组显式加回必要项，例如 --extension 加机器规则插件的绝对路径。也可在当前实例 bridge.config.json 的 pi.profile / pi.args 中配置。首次启动会检查所选 Pi 是否支持所需参数；缺少必要文件或不支持的参数会明确报错。不会硬编码某台 Mac 的路径，也不需要额外 Python 包装器。

在相同环境生成 pi-bridge mcp-config，CLI 与 MCP 即使用相同配置。doctor 显示加载配置和 Pi 报告的模型、thinking level。已有 daemon 需在任务结束后只重启对应实例。

更新验收默认采用可配置的 300 秒测试期限，生产任务的期限保持原设置。agent_end 后继续等待 agent_settled，再运行独立验收；超时和插件报错会保留为失败。具体配置、机器规则保留和更新步骤见 工作进程配置。

执行边界

运行环境使用 Pi 的现有主机权限。目录授权用于任务路由；更严格的文件和网络隔离需要运行环境提供。当前执行器接受显式 allowWrite:true、allowNetwork:true 的可信 host 整工作区任务；无法实施的只读、断网和子目录隔离要求会被拒绝。任务 constraints 表达用户的修改范围，Codex 仍需检查实际 diff。

只有独立验收命令通过才能给出 passed；worker 仅声明完成最多得到 partial。真实模型调用依赖用户所选后端的服务访问和额度。本项目不修改认证或声明未经测量的额度节省。

验证

npm test
npm run test:smoke

默认测试使用模拟 Pi，不请求模型。smoke 默认明确跳过真实服务；需要显式设置 BRIDGE_LIVE_TEST=1 才会尝试真实模型请求。

来源

由已有的本地 codex-pi-bridge 运行时整理并改进。Pi 与 MCP SDK 使用各自许可，本包未包含模型凭据、私人运行数据或 Pi 本体。

Windows/macOS 安装验收入口

npm 安装发布 tarball 后运行：

pi-bridge setup --apply

该命令检查 Git、实际 Pi --help 和选定 worker 参数，安装技能并返回完整 MCP 配置。相同技能可重复执行；已有不同内容不会覆盖。可用 --destination PATH 安装 到共享技能库，--pi-cli PATH 指定已有 Pi 入口。插件较多时显式选用 --profile minimal，并通过 PI_BRIDGE_PI_ARGS 保留任务需要的机器策略扩展。 默认保持 inherit，避免静默移除用户插件。命令不修改 Pi 认证或 Codex MCP 配置， 不请求模型；将输出的完整 MCP 配置注册后，再做真实任务验收。

GitHub Actions 在 Windows x64、Mac Apple Silicon 和 Intel Mac 执行源码测试， 再将 npm tarball 装入全新前缀，验证实际安装包的 setup、CLI、MCP 与独立验收。 这些使用模拟 Pi，不能替代目标电脑自身的模型认证和在线任务测试。

文档与许可证

• Skill 入口：任务委派与结果审阅。

• 首次配置：模型选择、认证和安装处理。

• 运行契约：CLI、MCP、任务格式与恢复。

• 验证范围：自动化测试与真实模型验收的区别。

本项目采用 MIT License。Pi、模型服务及其商标属于各自权利人，使用时遵循对应项目和服务条款。本项目不分发模型凭据。