Pi Codex Toolkit

English

Pi Codex Toolkit 在不替代 Pi agent loop 的前提下，增加少量、边界明确的 OpenAI/Codex 能力。 本文描述 0.2.0 版本：在原有五项能力之上，增加 Shell Sessions、Code Mode、 Tool Discovery 和按模型匹配的执行规则。相对 0.1.0 的变化见版本历史。

八项能力全部默认关闭：

能力	增加的功能	主要条件
Web Search	Native hosted search 或 openai_web_search Sidecar 工具	官方兼容 Responses route；Sidecar 还需要选定 OpenAI API-key 或 Codex OAuth executor
Remote Compaction v2	在 Pi 压缩边界创建并 replay Codex checkpoint	官方 openai-codex OAuth route
Image Generation	openai_generate_image 工具和持久化 PNG artifact	可用 OpenAI API-key 或 Codex OAuth image route
Apply Patch	provider-neutral 的 apply_patch 工具和 Codex 兼容 patch 语法	任意能调用普通 Pi 工具的主模型；Pi 在支持时使用 grammar sampling，否则使用 JSON
Computer Use	六个实验性、顺序执行的桌面工具	macOS、交互式 UI、支持 image input 的模型及成套 ChatGPT/Codex 组件
Shell Sessions	默认关闭的 exec_command / write_stdin，共用一个本地 executor	任意能调用普通 Pi 工具的主模型
Code Mode	默认关闭的 exec / wait：以当前用户权限运行可信 JavaScript，每次调用使用全新 worker，不是安全沙箱	任意能调用普通 Pi 工具的主模型；支持时由 Pi 以 grammar sampling 发送原始 JavaScript，否则使用 JSON；confirm 模式下嵌套 apply_patch 需要确认
Tool Discovery	默认关闭的 find_tools：显式 deferred 的 Toolkit 工具在被发现并加载前保持隐藏	任意能调用普通 Pi 工具的主模型；只管理 Toolkit 自有工具

环境要求

• Node.js 22.19.0 或更新版本。
• 需要 Pi 0.87 系列（^0.87.0）。不声明更早的 host 或 0.88 及之后的版本。带日期的 host 验证与限制见 架构验证。
• Provider 认证始终由 Pi 管理；Toolkit 配置不保存 API key 或 OAuth token。
• Computer Use 依赖另行安装的 ChatGPT/Codex 组件。本包不会安装或分发 ChatGPT.app、Codex、@oai/sky 或 Computer Use helper。

安装

0.2.0 版本

以下命令在对应 npm 版本或 Git tag 可用后安装 0.2.0。版本元数据和本地打包 本身不代表已经发布。

通过 Pi 的包管理器安装确定版本的 npm 包：

pi install npm:pi-codex-toolkit@0.2.0
pi list

也可以安装对应的不可变 Git tag：

pi install https://github.com/duo/pi-codex-toolkit@v0.2.0

固定版本的 npm 与 Git 安装不会自动更新。升级时请显式安装新版本或新 tag。 移除时，从 pi list 复制完整 source 并执行 pi remove <source>。

从 0.1.0 升级

先将 Pi 升级到 0.87 系列；0.1.0 验证时使用的是 Pi 0.84.4。 安装上方一种固定版本来源，然后重启 Pi。只保留一个 Toolkit 安装来源，避免 重复注册工具。

现有有效配置保留原设置，新能力在显式启用前仍然关闭。不含 execution 节时， 旧 enabled 开关继续使用累加语义，不隐藏原生工具。在 /pct config → Execution rules 中，先检查迁移预览再保存：初始 catch-all 规则对应旧开关（全关时生成空规则 列表），保存后规则取代这些开关。生效的 Shell 或 Code route 隐藏原生 bash； 生效的 Patch route 隐藏 edit 和 write。仅打开编辑器不会保存或迁移文件。选择迁移前先备份 配置，尤其是以后可能退回不认识执行规则的 0.1.0 时。见 配置文档。

本地开发源码

在包含目标源码修订、且已备好开发依赖的 checkout 中，可单次加载而不写入 Pi settings：

pi -e .

需要固定版本时使用版本 tag。源码本地验证不代表已发布到 npm，也不代表 已经从 registry 安装验证。

首次使用

启动 Pi 后使用：

/pct status
/pct config
/pct reload

/pct config 用于显式开启能力，并可选择 Sidecar Search 的 executor model 与独立 effort；/pct status 说明配置状态、实际状态及 原因；手工修改 Toolkit 配置后用 /pct reload 重载。所有开关关闭时， 启动不会发出 Toolkit 网络请求、生成图片、执行 Remote Compaction、启动 GUI、启动 shell 进程、启动 Code Mode worker、启动 Computer Use 进程，也不会 暴露 Toolkit patch 写入路径。

配置文件通常位于：

~/.pi/agent/extensions/pi-codex-toolkit.json

设置 PI_CODING_AGENT_DIR 时使用 Pi 解析后的 agent dir。完整 schema 与 资格条件见配置文档。

数据、费用与桌面边界

• Native Search 只修改当前兼容的 Responses 请求。
• Sidecar Search 会把生成的 query 原样放进一次独立 OpenAI Responses 请求，增加延迟与费用。它不会自动附带完整 Pi 对话，但 query 可能概括 对话内容。结果最多保留 20 条去重后的可点击 sources；这是 Toolkit 的 输出预算，不是上游返回数量保证。
• Image Generation 每次发送一个独立请求，并把返回的 PNG 保存到 Pi agent dir；dispatch 后不重试，也不切换账户。
• Remote Compaction 把有界的 provider-visible 历史发送到官方 Codex route， 并在 Pi session 中保存可读 fallback 和一个 opaque checkpoint。
• Apply Patch 的 grammar 与 JSON function 调用共用一个本地 executor。现有源文件 （包括 Delete File 目标）必须是有效 UTF-8 文本，换行须统一为 LF 或 CRLF； 非 UTF-8、裸 CR 和混合换行会在 mutation 前被拒绝。不支持二进制文件删除。 Update File hunk 中的裸空行按空 context 行读取，context 以空行结尾的 hunk 去掉该空行后同样可以匹配；Add File hunk 仍然严格，其中的裸空行会被拒绝。 它拒绝可见 symlink 组件，并在逐文件原子提交前完成 staging；多文件 patch 不是 transaction，静态 containment 也不防御恶意并发路径替换。它不是 Responses 一等 apply_patch_call 协议。
• Computer Use 只在显式 status probe 或工具调用时启动隔离 bridge；不会安装 组件、启动 GUI 或授予 macOS 权限。Confirm 在当前 Pi session 内按 app 记住 Yes，No 后下次仍会询问；Always 只跳过 Toolkit confirmation，不绕过 macOS 权限。不新增人工审批期限：经校验的异步审批等待不消耗剩余执行预算， 可持续到答复、取消或失败。
• Shell Sessions 使用用户的本地进程权限，不是 sandbox 或 TTY。使用旧 enabled 开关时原生 bash 仍可用；execution 规则选中直调 Shell 或 Code 时，会在该 route 生效期间隐藏它，route 结束后恢复。短命令不一定需要轮询。命令只启动一次；leader 退出后，普通同进程组 后代仍被管理。stop 有界升级并报告无法确认的清理。stdin 准入有上限；transport 确认不证明应用已执行，delivery unknown 时不可自动重发。
• Code Mode 每次 exec 都在独立 worker thread 中以全新状态运行一段短 JavaScript，不是安全沙箱；只应运行可信代码，使用当前用户的权限。uses 声明并校验受支持的 tools.<name> adapter dispatch，不防御恶意 JavaScript， 也不限制宿主环境权限。已声明的嵌套调用经过各工具现有 executor 自身的校验、 禁用状态、顺序与文件 mutation queue。Pi 原生 tool_call / tool_result hook 以及第三方权限拦截器只能看到外层 exec / wait 调用（含完整 code 与 uses），看不到嵌套调用； 但有界的嵌套进度记录会随外层调用的 update 一起返回。 confirm 的额外 Toolkit 确认只适用于 apply_patch，并且发生在嵌套调用 真正执行时：headless 下只声明 Patch 的 cell 照常运行，只有真正的嵌套 apply_patch 会在任何改动之前失败。shell 同样能修改文件，但保持直接 shell 的权限语义。参数先校验再确认，等待后复查实时权限。 完成会等待被跟踪的传递调用，包括结果序列化引入的工作；失败会封禁未 dispatch 调用并协作 abort 未 settle 工作，不回滚。worker 终止支持 CPU-bound 取消， 不保证强制终止所有 host effect；V8 limit 不限制 total RSS 或外部分配。 独立 shell 控制信息不因 JS 返回值被省略/截断而丢失；Code Mode 清理不会停止 已 yield 的独立 shell。
• Shell/Code 在 preview 丢失前保留解码 stream 或已发出/序列化的选定表示。 私有文件惰性创建，handle 释放或功能禁用后仍可读，直到实际 Pi session_shutdown。已完整交付的小结果无需文件。通过可用的原生 read 或 获授权 shell 读取返回路径，不可为恢复证据重跑副作用。capture 快照不是最终 outcome receipt；partial、missing、unavailable 不代表完整证据。文件可能含 密钥；没有聚合磁盘 quota，也不保证重启恢复。
• 禁用/冲突会请求清理，而非保证所有工作已消失。尝试 session switch/fork 会先 清理执行；清理不完整则否决替换。即使操作被取消，部分工作也可能已停止，不会 回滚；文件保留到实际 shutdown。未变更 /pct reload 和 model change 保留 执行。Pi resource /reload、quit、紧急 teardown 在这里不可否决：可能残留 工作/文件，报错也不保证替换后旧 handle 可用。
• Tool Discovery 是本地且默认关闭的。find_tools 在文件级 toolDiscovery.deferred 显式列表中搜索，并只增量激活 Toolkit 自有且当前 具资格的名字。它绝不执行工具、不授予权限、不复活被禁用或被用户过滤的能力、 不替换冲突注册、也不启用第三方工具；new/resume/fork 后遗忘已加载名字，且 不重放任何调用。

完整协议与失败边界见架构文档。

验证状态

统一的验证与限制摘要区分历史 能力/模型探针（含 2026 年 9 月 10 日）、9 月 13 日修复测试与确定性公开 host 运行，以及后续源码级检查。它们均不代表新的安装或 GitHub Actions 结果。 历史 live 探针没有在修复后源码重跑；未测试的 API-key route、平台与 UI 路径 仍未获验证。不声明 Code Mode 或 Tool Discovery 的普适 token/延迟收益。

开发

这些命令作用于选定 checkout。公开文档仅限 docs/en/、 docs/zh/ 和 docs/third-party/；私有研究同时排除在公开 Git 导出和 npm 之外。 本地打包不等于选定新版本。

npm ci --ignore-scripts
npm test
npm run test:coverage
npm run test:coverage:project
npm run typecheck
npm run lint
npm run format:check
npm pack --dry-run --ignore-scripts

详细文档：

• 架构
• 配置
• English architecture
• English configuration

版本说明维护在 CHANGELOG.md；缺陷请通过 GitHub Issues 反馈。

许可证

Pi Codex Toolkit 采用 Apache License 2.0。项目包含 OpenAI Codex Apply Patch 实现的修改部分；归属与许可证详情见 NOTICE 和 docs/third-party。