[English](README.md) | 简体中文

# pi-gpt-enhance

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

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

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

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

## 安装

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

```bash
pi install npm:pi-gpt-enhance
```

从本仓库临时运行：

```bash
pi -e ./packages/gpt-enhance
```

启动后可运行：

```text
/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` 开关控制。

## 配置

全局配置文件：

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

项目配置文件：

```text
.pi/gpt-enhance.json
```

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

完整示例：

```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           |
| `/gpt-enhance update`  | 清除当前模型的能力缓存，使下一次请求重新探测               |
| `/gpt-enhance compact` | 在会话空闲时手动调用 Provider 的 `POST /responses/compact` |

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

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

```text
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                     |

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

```text
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](https://github.com/peach0x33a/pi-extensions/issues)。

## 请求处理顺序

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

1. 将首个可提升的 system/developer 字符串提示移动到 `instructions`
2. 应用 Fast mode 的 `service_tier: "priority"`
3. 应用服务端压缩或 Responses continuation
4. 调用最终 Provider `onPayload` hook

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

## 服务端压缩

正常 Responses 请求仍由 Pi 内置实现发送。扩展只在请求边界补充 [OpenAI Compaction](https://developers.openai.com/api/docs/guides/compaction) 所需行为：

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

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

> [!WARNING]
> 服务端压缩仍处于实验阶段，目前仍然存在已知问题。请勿将其作为防止上下文溢出的唯一保障；请保留 Pi 原生本地压缩回退，并在 [Issues](https://github.com/peach0x33a/pi-extensions/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` 按以下模型身份保存偏好：

```text
provider + api + model id + baseUrl
```

启用后，最终 OpenAI Responses 请求携带：

```json
{
  "service_tier": "priority"
}
```

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

偏好保存在：

```text
~/.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`：

```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`](../autofill-model-metadata)：为自定义 Provider 注册并填充模型元数据的 Pi 扩展
- [`pi-codex-gpt-metadata`](../codex-gpt-metadata)：由 autofill 使用的独立 Codex 目录；它没有 Pi 扩展入口，也不依赖 `pi-gpt-enhance`

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

```jsonc
{
  "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、请求内容或响应内容。

## 开发验证

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

仓库级验证：

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

## 来源与许可

服务端能力探测使用 OpenAI Responses 的 `context_management` 参数。Codex 模型目录由独立的 [`pi-codex-gpt-metadata`](../codex-gpt-metadata) 维护，并由 [`pi-autofill-model-metadata`](../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 背书。