English | 简体中文

pi-gpt-enhance

为 Pi 中使用 OpenAI Responses 协议的 GPT 模型提供一组窄范围 Codex 请求增强：服务端上下文压缩、Responses instructions 提升、Fast mode，以及可选的 apply_patch custom tool。模型元数据有意交由 pi-autofill-model-metadata 和独立的 pi-codex-gpt-metadata 目录提供，而不是由本扩展提供。

扩展只处理同时满足以下条件的模型：

• api 为 openai-responses
• 模型 ID 以 gpt- 或 openai/gpt- 开头

其他 API、Provider 和模型不会被修改。

安装

从 npm 安装到 Pi 的用户配置：

pi install npm:pi-gpt-enhance

从本仓库临时运行：

pi -e ./packages/gpt-enhance

启动后可运行：

/gpt-enhance

查看当前模型和所有增强功能的状态。

功能与默认值

| 功能 | 配置 | 默认值 | | ----------------------------------------------- | ----------------------------------- | ---------- | | 扩展总开关 | enabled | 开启 | | 自动服务端压缩与 Responses continuation | compression | 开启 | | 首个 system/developer 提示提升到 instructions | promoteSystemPromptToInstructions | 开启 | | Footer 状态栏 | statusBar | 开启 | | 服务端压缩通知 | notify | 开启 | | Codex-compatible apply_patch | applyPatch | 关闭 | | Fast mode | /gpt-enhance fast | 按模型关闭 |

applyPatch、promoteSystemPromptToInstructions、compression 和 Fast mode 相互独立，但都受全局 enabled 开关控制。

配置

全局配置文件：

~/.pi/agent/gpt-enhance.json

项目配置文件：

.pi/gpt-enhance.json

优先级从高到低为：环境变量、项目配置、全局配置、内置默认值。项目配置只覆盖同名字段。

完整示例：

{
  "enabled": true,
  "compression": true,
  "applyPatch": false,
  "promoteSystemPromptToInstructions": true,
  "thresholdRatio": 0.9,
  "notify": true,
  "statusBar": true
}

配置字段

| 字段 | 类型 | 说明 | | ----------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- | | enabled | boolean | 完全启用或禁用扩展 | | compression | boolean | 启用自动服务端上下文压缩和 Responses continuation；关闭后仍可显式运行 /gpt-enhance compact 并使用其他增强 | | applyPatch | boolean | 注册 Codex-compatible apply_patch；只对 eligible GPT 模型生效 | | promoteSystemPromptToInstructions | boolean | 将首个可提升的 system/developer 字符串提示移动到顶层 instructions | | compactThreshold | number | 直接指定服务端压缩 token 阈值；优先于 thresholdRatio | | thresholdRatio | number | 按模型上下文窗口计算压缩阈值；默认 0.9，最大按 0.95 处理 | | notify | boolean | 显示服务端压缩相关 TUI 通知 | | statusBar | boolean | 在 Pi footer 显示服务端压缩与 Fast 状态；关闭时清除两个状态 |

promoteSystemPromptToInstructions 和 statusBar 都可以直接写在 JSON 配置文件中。环境变量只用于覆盖：

| 配置字段 | 环境变量 | | ----------------------------------- | ------------------------------------------------------ | | enabled | PI_GPT_ENHANCE_ENABLED | | compression | PI_GPT_ENHANCE_COMPRESSION | | applyPatch | PI_GPT_ENHANCE_APPLY_PATCH | | promoteSystemPromptToInstructions | PI_GPT_ENHANCE_PROMOTE_SYSTEM_PROMPT_TO_INSTRUCTIONS | | compactThreshold | PI_GPT_ENHANCE_COMPACT_THRESHOLD | | thresholdRatio | PI_GPT_ENHANCE_THRESHOLD_RATIO | | notify | PI_GPT_ENHANCE_NOTIFY | | statusBar | PI_GPT_ENHANCE_STATUS_BAR |

布尔环境变量接受 true/false、1/0、yes/no 和 on/off。

命令

| 命令 | 作用 | | ---------------------- | -------------------------------------------------------------------------------------- | | /gpt-enhance | /gpt-enhance status 的别名 | | /gpt-enhance status | 显示当前模型和所有增强功能的状态 | | /gpt-enhance fast | 为当前 Provider/API/模型/base URL 循环切换 Fast mode：off → priority → ultrafast → off | | /gpt-enhance update | 清除当前模型的能力缓存，使下一次请求重新探测 | | /gpt-enhance compact | 在会话空闲时手动调用 Provider 的 POST /responses/compact |

在 /gpt-enhance 后输入空格即可获得带说明的子命令补全；继续输入前缀会过滤候选项。

状态命令使用当前 Pi 主题输出对齐面板，例如：

gpt-enhance
  model           misaka-responses/gpt-5.6-sol
  server compact  not probed
  fast mode       off
  instructions    on
  apply_patch     active
  status bar      on

Footer 状态栏

statusBar 默认开启。扩展使用 Pi 的 ctx.ui.setStatus()，不会替换默认 footer：

| 显示 | 含义 | | ------------- | -------------------------------------------- | | COMPACT:? | 服务端压缩能力尚未探测 | | COMPACT:ON | Provider 已确认支持服务端压缩 | | COMPACT:OFF | 配置已关闭服务端压缩，或 Provider 明确不支持 | | FAST | 当前模型已启用 Fast mode（priority 档） | | ULTRAFAST | 当前模型已启用 Fast mode（ultrafast 档） |

Pi 会按状态 key 排序，因此 Fast 开启时通常显示为：

COMPACT:ON FAST

当前模型不符合 gating，或 statusBar 为 false 时，扩展会清除 gpt-enhance.compression 和 gpt-enhance.fast 两个 footer 状态。/gpt-enhance status 命令仍然可用，并会显示 status bar off。

自定义 footer 只要继续读取 footerData.getExtensionStatuses()，就能保留这些状态。

[!TIP] 我们正在寻找一款美观的 Pi status bar，以及让第三方 footer 一键兼容 gpt-enhance 状态的集成方案。如果你正在维护或愿意推荐合适的状态栏，欢迎打开 Issue。

请求处理顺序

对于 eligible 模型，每个实际发往 Provider 的请求按以下顺序处理：

1. 将首个可提升的 system/developer 字符串提示移动到 instructions
2. 应用 Fast mode 的 service_tier（priority，选择 ultrafast 时为 ultrafast）
3. 应用服务端压缩或 Responses continuation
4. 调用最终 Provider onPayload hook

最终 hook 对初始请求、fallback 和 continuation retry 都拥有最终决定权。只有返回 undefined 才表示保留当前 payload；null 等其他返回值均被视为有效替换。

服务端压缩

正常 Responses 请求仍由 Pi 内置实现发送。扩展只在请求边界补充 OpenAI Compaction 所需行为：

1. 首个 eligible 请求加入 store: true 和 context_management，压缩阈值默认为上下文窗口的 90%。
2. Provider 接受增强请求后，扩展缓存服务端压缩支持状态；后续请求在可用时使用 previous_response_id 和增量 input。
3. Provider 明确拒绝 previous_response_id 时，当前请求改用完整本地 input 和 context_management 重试，并缓存续接不支持，防止后续重复发送已知会失败的参数。
4. previous_response_id 不支持不会关闭服务端压缩；只有 Provider 拒绝压缩增强参数或增强请求无法恢复时，才恢复 Pi 原生请求和本地压缩。
5. Provider 拒绝增强参数或发生可恢复网络错误时，扩展维持内部响应链不变量，再使用无增强 payload 重试。
6. 模型、会话或分支发生变化时清理响应链状态，避免跨 Provider 污染；恢复会话时跳过 error 和 aborted 响应。

当服务端实际返回 compaction 或 compaction_summary 时，扩展只针对该 item 显示一次通知，并在下一次 Pi 压缩生命周期写入服务端压缩标记，避免旧 token 估算反复触发本地压缩。

[!WARNING] 服务端压缩仍处于实验阶段，目前仍然存在已知问题。请勿将其作为防止上下文溢出的唯一保障；请保留 Pi 原生本地压缩回退，并在 Issues 中报告可复现的问题。

服务端压缩会设置 store: true。请求内容将遵循 OpenAI Responses 的存储策略；代理 Provider 是否遵循相同策略取决于该 Provider。

手动压缩

/gpt-enhance compact 只在会话空闲且模型 eligible 时运行。它会：

• 优先使用已有 Responses responseId 和 previous_response_id
• 在 Provider 明确拒绝 continuation 时，以 Pi 当前有效会话 input 重试
• 遵守最近的 Pi compaction 边界，不重新发送已压缩的旧历史
• 使用与正常请求相同的 instructions 提升逻辑

命令成功后不会创建 Pi 本地 [compaction] 会话条目。失败时只显示错误，不会隐式执行 Pi 本地压缩，也不会破坏当前服务端响应链。

/gpt-enhance update 只清除能力缓存，不发送模型请求，也不会触发压缩。

Fast mode

/gpt-enhance fast 按以下模型身份保存偏好：

provider + api + model id + baseUrl

/gpt-enhance fast 在三个状态间循环：off → priority → ultrafast → off。只有当 pi-codex-gpt-metadata 目录的 serviceTiers 中列出了 ultrafast 档的模型才会进入 ultrafast；其他模型按 off → priority → off 循环。启用后，最终 OpenAI Responses 请求携带所选的服务档位：

{
  "service_tier": "priority"
}

如果模型目录条目不再列出 ultrafast 档，已保存的 ultrafast 偏好会回退到 priority。

Fast mode 与 compression 独立。关闭 Fast 时，扩展不会移除调用方已经设置的 service_tier。

偏好保存在：

~/.pi/agent/gpt-enhance-preferences.json

写入过程使用跨进程锁和原子 rename。文件缺失或无效时按 Fast 关闭处理。测试可通过 PI_GPT_ENHANCE_PREFERENCES_FILE 指定隔离路径。

第三方 Provider 若在响应中省略 service_tier，Pi 可能无法计算 priority multiplier；请求仍会携带 priority。

instructions 提升

默认情况下，扩展会检查 Responses payload 的第一个 input 项：

• role 必须为 developer 或 system
• content 必须为非空字符串
• 顶层不能已有非空 instructions

满足条件时，该项会从 input 中移除，并将原字符串移动到顶层 instructions。扩展不会复制提示，也不会扫描后续项。

以下情况保持原样：

• 顶层已有非空 instructions
• 第一项不是 system/developer
• content 为结构化数组或其他非字符串值
• promoteSystemPromptToInstructions 为 false

该规则覆盖正常请求、手动压缩、continuation fallback 和公开的 compactResponseChain() API。

可选 apply_patch

将以下配置写入全局或项目 gpt-enhance.json：

{
  "applyPatch": true
}

启用后，扩展只在 eligible 模型下注册 Codex-compatible apply_patch custom tool。它支持：

• Add、Delete、Update 和 Move
• 多文件与多 chunk patch
• @@ context anchor 和 *** End of File
• Codex 风格的 exact、尾部空白、trim 和 Unicode 匹配回退
• 写入前的完整确定性预检
• Pi 文件 mutation queue 下的多路径稳定加锁

相对路径从当前请求的 ctx.cwd 解析。已有其他扩展提供同名工具时，外部工具始终优先；本扩展不会覆盖、停用或管理它。模型切换或其他扩展改写 active tools 后，本扩展也只管理自己注册的工具实例。

此功能只实现文件 patch，不包含 Codex runtime 的 shell、exec_command、PTY、sandbox、审批、MCP、远程执行或进度协议。工具使用当前 Pi 进程的文件权限。

模型元数据由独立组件提供

pi-gpt-enhance 不会注册、填充或持有模型元数据。元数据功能有意拆分为：

• pi-autofill-model-metadata：为自定义 Provider 注册并填充模型元数据的 Pi 扩展
• pi-codex-gpt-metadata：由 autofill 使用的独立 Codex 目录；它没有 Pi 扩展入口，也不依赖 pi-gpt-enhance

通过 autofill 的 codex/<model-id> 来源配置 Codex 元数据：

{
  "mapping": {
    "my-responses-provider": {
      "gpt-5.6-sol[1m]": "codex/gpt-5.6-sol[1m]",
    },
  },
}

两个 Pi 扩展没有加载顺序依赖：autofill 注册模型元数据，gpt-enhance 只注册增强后的 Responses 请求流，Pi 会合并两部分 Provider 注册。~/.pi/agent/models.json 中显式设置的模型字段仍具有最高优先级。

本扩展按 API 和模型 ID 前缀判断是否启用请求增强，而不是依赖模型目录成员关系，因此元数据目录可以独立于 pi-gpt-enhance 发布更新。

本地状态文件

| 文件 | 内容 | | ------------------------------------------- | -------------------------------------------- | | ~/.pi/agent/gpt-enhance.json | 用户级配置 | | .pi/gpt-enhance.json | 项目级配置 | | ~/.pi/agent/gpt-enhance-capabilities.json | 按 Provider/API/模型/base URL 隔离的能力缓存 | | ~/.pi/agent/gpt-enhance-preferences.json | 按模型隔离的 Fast 偏好 |

能力缓存不包含 API key、请求内容或响应内容。

开发验证

bun run --filter pi-gpt-enhance typecheck
bun run --filter pi-gpt-enhance test
pi -e ./packages/gpt-enhance

仓库级验证：

bun run check
npm pack --dry-run --json --workspace pi-gpt-enhance

来源与许可

服务端能力探测使用 OpenAI Responses 的 context_management 参数。Codex 模型目录由独立的 pi-codex-gpt-metadata 维护，并由 pi-autofill-model-metadata 注册。

src/apply-patch.ts 和 src/apply-patch-tool.ts 中包含经修改的 Codex 派生实现，按 Apache-2.0 提供并保留 Copyright 2025 OpenAI 归属。其余本包原创代码按 MIT 提供。包级许可证声明为 (MIT AND Apache-2.0)。

发布包包含：

• LICENSE
• LICENSES/Apache-2.0.txt
• NOTICE

本扩展不是 OpenAI Codex 官方产品，也不代表 OpenAI 背书。