pi-apply-patch-plus

English | 简体中文

给 pi 带来 Codex 风格补丁式编辑：用一份结构化补丁（apply_patch）一次完成多个文件的增、改、删、移，配合本地格式校验与彩色 diff 预览。智能识别 GPT 系列模型，自动启用补丁式编辑并接管 edit / write，无需维护模型清单。

特性

• 补丁式多文件编辑 —— 一个补丁信封描述所有改动，改动一目了然：

  *** Begin Patch
  *** Add File: src/new.ts
  +export const value = 1;
  
  *** Update File: src/app.ts
  @@
  -const oldValue = 0;
  +const newValue = 1;
  
  *** Delete File: src/obsolete.ts
  *** End Patch

• 本地校验先行 —— 解析并验证补丁格式（信封、操作头、上下文匹配、+ 前缀），不合法则拒绝执行，绝不静默产生错误结果。

• 智能 GPT 识别 —— 任何 gpt-* 模型自动获得该工具（gpt-5.6-sol / gpt-5.6-luna / gpt-5.6-terra / gpt-4o 及未来的 GPT 模型），无需硬编码清单；非 GPT 模型自动隐藏。

• Codex 远程约束 —— 在 gpt-5.2/5.3-codex 模型上，补丁以 CFG 约束的 freeform 工具发送到 OpenAI Codex API，语法层即受限。

• Diff UI 与实时计数 —— pi 原生 diff 渲染器显示彩色差异，逐文件展示 +X -Y 与操作进度。

• 中断恢复 —— 被打断的孤儿工具调用自动补上合成取消输出，后续提问不会因缺失 custom_tool_call_output 而失败。

• 工具接管策略 —— 启用后禁用 edit / write，统一走 apply_patch，避免并行工具同改一文件互相覆盖；切回非 GPT 模型时自动恢复。

安装

需要先安装 pi。从 npm 安装：

pi install npm:pi-apply-patch-plus

然后在 pi 中输入 /reload，让扩展加载进当前会话。

后续更新：

pi update npm:pi-apply-patch-plus

其他方式 —— 从源码仓库安装：

pi install git:github.com/matsuzaka-yuki/pi-apply-patch-plus

本地开发：

pi install ./

工作原理

1. 在 pi 中注册 apply_patch 工具；
2. 按模型执行工具策略：GPT 模型启用 apply_patch 并移除 edit / write，非 GPT 模型恢复内置编辑工具；
3. 在 gpt-5.2/5.3-codex 上，工具以 type: "custom" + syntax: "lark" 的 freeform 形式发送到 Codex API，并解析 custom_tool_call 事件映射回 pi 工具调用；
4. 本地解析补丁 → 校验 → 应用文件改动 → 以 custom_tool_call_output 回传结果；
5. 全程渲染逐文件 +X -Y 计数与彩色 diff（展开工具输出查看完整补丁）。

补丁格式

信封结构：

*** Begin Patch
*** Add File: hello.txt
+Hello
*** End Patch

支持操作：

• *** Add File: <path> —— 新建文件（内容逐行以 + 开头）
• *** Delete File: <path> —— 删除文件
• *** Update File: <path>（可选 *** Move to: <path>）—— 原地修改 / 改名
• hunk：@@ 起始，行为 （上下文）、+（新增）、-（删除）

路径行为与 pi 的 write 语义一致：相对路径基于当前工作目录解析。

模型支持

| 模型 | 行为 | |------|------| | 任意 gpt-*（如 gpt-5.6-sol、gpt-5.6-luna、gpt-5.6-terra） | 本地支持：普通 JSON 工具，补丁放在 input 字段 | | gpt-5.2-codex* / gpt-5.3-codex* | 完整支持：额外以 CFG/freeform 形式走 Codex API | | 非 GPT 模型（claude-*、deepseek-*、glm-* 等） | 工具隐藏并拦截 |

开发

pnpm install
pnpm typecheck
pnpm test

致谢

本项目在功能设计与交互思路上参考了 MIT 协议开源的 pi-extension-codex-apply-patch 项目，感谢原作者的贡献。在此基础之上，本项目重写了模型识别逻辑（智能 GPT 识别替代硬编码清单）、文档与项目包装，使其更贴合个人使用场景。