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 背书。