pi-openai-toolkit 0.14.2 → 0.14.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +251 -246
- package/README.zh.md +251 -246
- package/package.json +1 -1
- package/src/context-management/window-manager.ts +479 -421
package/README.zh.md
CHANGED
|
@@ -1,246 +1,251 @@
|
|
|
1
|
-
# pi-openai-toolkit
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
4
|
-
[](./LICENSE)
|
|
5
|
-
|
|
6
|
-
面向 Pi 的 OpenAI 工具包：Codex 远端上下文窗口、远端无损压缩 v2、托管联网搜索、图像生成与 Auto 模式。
|
|
7
|
-
|
|
8
|
-
[English](./README.md)
|
|
9
|
-
|
|
10
|
-
`pi-openai-toolkit` 为 OpenAI Responses 协议族（`openai-responses` 与 `openai-codex-responses`）集成五个 Pi 扩展：
|
|
11
|
-
|
|
12
|
-
1. **压缩与远端上下文管理**（`extensions/compaction.ts`）：两套长上下文策略。[Codex 远端上下文管理](#codex-远端上下文管理)把 Codex 原生窗口体系移植到 Pi——无摘要 `new_context` 换窗（附成功的 notes checkpoint 硬门禁）、跨窗口 `history` / `notes` 工具（加密参数传输）、按预算触发的 checkpoint 提醒。关闭它时，本扩展走 **Remote Compaction v2**：服务端密文压缩，绝不做有损文本重摘要。
|
|
13
|
-
2. **联网搜索**（`extensions/web-search.ts`）：为 `provider/model-id` 精确白名单注入托管 `web_search`，复用当前模型连接。
|
|
14
|
-
3. **图像生成**（`extensions/image-generation.ts`）：由托管 `image_generation` 工具驱动的本地 `openai_generate_image`，支持文生图与显式本地参考图编辑，图像字节不进会话历史。
|
|
15
|
-
4. **Auto 模式**（`extensions/auto-mode.ts`）：为改变状态的工具调用增设审批模型门禁，Agent 不必停下来等你确认。
|
|
16
|
-
5. **Codex Astra**（`extensions/codex-astra.ts`）：为 `gpt-6-astra` 补发 Codex 后端版本门禁头，并用 `configuration_update` 会话项保住提示缓存。按模型名静默启用，无配置段。
|
|
17
|
-
|
|
18
|
-
本包是 Pi 扩展集而非可导入库：一切通过一个 JSON 配置文件驱动，在 Pi 内自动生效。
|
|
19
|
-
|
|
20
|
-
## 目录
|
|
21
|
-
- [安全](#安全)
|
|
22
|
-
- [背景](#背景)
|
|
23
|
-
- [安装](#安装)
|
|
24
|
-
- [使用](#使用)
|
|
25
|
-
- [配置](#配置)
|
|
26
|
-
- [功能指南](#功能指南)
|
|
27
|
-
- [开发](#开发)
|
|
28
|
-
- [API](#api)
|
|
29
|
-
- [Remote Context 工具](#remote-context-工具)
|
|
30
|
-
- [HTTP 协议参考](#http-协议参考)
|
|
31
|
-
- [维护者](#维护者)
|
|
32
|
-
- [贡献](#贡献)
|
|
33
|
-
- [许可证](#许可证)
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
"
|
|
87
|
-
"
|
|
88
|
-
"
|
|
89
|
-
"
|
|
90
|
-
"
|
|
91
|
-
"
|
|
92
|
-
"
|
|
93
|
-
"
|
|
94
|
-
"
|
|
95
|
-
"
|
|
96
|
-
"
|
|
97
|
-
"
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
|
|
103
|
-
"
|
|
104
|
-
"
|
|
105
|
-
"
|
|
106
|
-
|
|
107
|
-
}
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `nativeFallback.
|
|
131
|
-
| `nativeFallback.
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
| `
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
-
|
|
182
|
-
-
|
|
183
|
-
-
|
|
184
|
-
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
npm
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
POST {base}/alpha/
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
1
|
+
# pi-openai-toolkit
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
|
|
6
|
+
面向 Pi 的 OpenAI 工具包：Codex 远端上下文窗口、远端无损压缩 v2、托管联网搜索、图像生成与 Auto 模式。
|
|
7
|
+
|
|
8
|
+
[English](./README.md)
|
|
9
|
+
|
|
10
|
+
`pi-openai-toolkit` 为 OpenAI Responses 协议族（`openai-responses` 与 `openai-codex-responses`）集成五个 Pi 扩展：
|
|
11
|
+
|
|
12
|
+
1. **压缩与远端上下文管理**（`extensions/compaction.ts`）：两套长上下文策略。[Codex 远端上下文管理](#codex-远端上下文管理)把 Codex 原生窗口体系移植到 Pi——无摘要 `new_context` 换窗（附成功的 notes checkpoint 硬门禁）、跨窗口 `history` / `notes` 工具（加密参数传输）、按预算触发的 checkpoint 提醒。关闭它时，本扩展走 **Remote Compaction v2**：服务端密文压缩，绝不做有损文本重摘要。
|
|
13
|
+
2. **联网搜索**（`extensions/web-search.ts`）：为 `provider/model-id` 精确白名单注入托管 `web_search`，复用当前模型连接。
|
|
14
|
+
3. **图像生成**（`extensions/image-generation.ts`）：由托管 `image_generation` 工具驱动的本地 `openai_generate_image`，支持文生图与显式本地参考图编辑，图像字节不进会话历史。
|
|
15
|
+
4. **Auto 模式**（`extensions/auto-mode.ts`）：为改变状态的工具调用增设审批模型门禁，Agent 不必停下来等你确认。
|
|
16
|
+
5. **Codex Astra**（`extensions/codex-astra.ts`）：为 `gpt-6-astra` 补发 Codex 后端版本门禁头，并用 `configuration_update` 会话项保住提示缓存。按模型名静默启用，无配置段。
|
|
17
|
+
|
|
18
|
+
本包是 Pi 扩展集而非可导入库：一切通过一个 JSON 配置文件驱动，在 Pi 内自动生效。
|
|
19
|
+
|
|
20
|
+
## 目录
|
|
21
|
+
- [安全](#安全)
|
|
22
|
+
- [背景](#背景)
|
|
23
|
+
- [安装](#安装)
|
|
24
|
+
- [使用](#使用)
|
|
25
|
+
- [配置](#配置)
|
|
26
|
+
- [功能指南](#功能指南)
|
|
27
|
+
- [开发](#开发)
|
|
28
|
+
- [API](#api)
|
|
29
|
+
- [Remote Context 工具](#remote-context-工具)
|
|
30
|
+
- [HTTP 协议参考](#http-协议参考)
|
|
31
|
+
- [维护者](#维护者)
|
|
32
|
+
- [贡献](#贡献)
|
|
33
|
+
- [许可证](#许可证)
|
|
34
|
+
- [致谢](#致谢)
|
|
35
|
+
|
|
36
|
+
## 安全
|
|
37
|
+
|
|
38
|
+
- **覆盖模型不会有静默的有损摘要。** `contextManagement: "remote"` 覆盖某模型期间，Pi 原生压缩在阈值、手动 `/compact`、溢出全部路径上被取消，v2 也不发送。若想再加宿主级保险，在 Pi `settings.json` 设 `"compaction": { "enabled": false }`；覆盖范围外的模型照常走 Pi 自己的策略。
|
|
39
|
+
- **网关隔离。** 网关模式只转发配置的数据面 key；OAuth 令牌、account cookie、account ID 一律剥离；artifact 中凭据与不透明密文永远脱敏。
|
|
40
|
+
- **Checkpoint 门禁。** `new_context` 无法在没有本窗口成功 notes 写入、也没有用户显式 `force` 授权时丢弃未保存工作状态——Codex 官方实验特性上出现过的"后端故障 + 换窗丢状态"在此被硬拦。
|
|
41
|
+
- **计费与审批边界。** 图像生成显式开启且可能产生费用；审批请求禁用提示缓存、只授予只读工具，无 UI 会话 fail-closed。
|
|
42
|
+
|
|
43
|
+
## 背景
|
|
44
|
+
|
|
45
|
+
Pi 内置压缩会把旧轮次摘要成文本，细节随之丢失；OpenAI Codex 后端其实提供两种无损机制，普通客户端拿不到：**`remote_compaction_v2` SSE 协议**（用加密密文项替换被摘要的前缀）与实验性**上下文窗口体系**（`new_context` / `history` / `notes`，完全不做摘要地换窗）。本工具包对着真实后端实现了两者，并已在 Codex OAuth 与 Codex 兼容网关中继（NEWapi + CLIProxyAPI）上端到端验证。
|
|
46
|
+
|
|
47
|
+
来源说明：Remote Context 协议逆向自 `@howaboua/pi-codex-conversion@3.0.29`（source commit `7021ae48e8efe36a3becc5830d529696ff798e5e`）；Astra 适配层移植自 Oh My Pi 18.1.8（MIT）；联网搜索行为改编自 [`pi-openai-web-search`](https://github.com/code-yeongyu/pi-openai-web-search)（commit `3964338`）。完整归属见 [NOTICE](./NOTICE)。alpha 的 `history`/`notes` 端点可能随时变更，本仓库的端点与 header fixture 必须同步更新。
|
|
48
|
+
|
|
49
|
+
要求 **Pi >= 0.85.1**、**Node.js >= 22.19.0**。模型目录与 Codex/API Key 登录由 Pi 提供；本包不实现独立登录流程，也绝不直接触碰凭据存储。
|
|
50
|
+
|
|
51
|
+
## 安装
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pi install npm:pi-openai-toolkit
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
写入 Pi 全局配置，用 `pi list` 验证。只装到当前项目：
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pi install npm:pi-openai-toolkit --local
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
从 git 安装（开发或锁版本）：
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pi install git:github.com/awoaCrim/pi-openai-toolkit
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 更新
|
|
70
|
+
|
|
71
|
+
`pi update --extensions` 会连同本工具包一起更新 Pi 包。已发布版本见 [npm](https://www.npmjs.com/package/pi-openai-toolkit)。
|
|
72
|
+
|
|
73
|
+
### 冲突警告
|
|
74
|
+
|
|
75
|
+
不要将 `pi-remote-compact`、`@lll9p/pi-better-compaction` 或独立的 `pi-openai-web-search` 与本包同时运行：重复 hook 会造成竞态和系统提示词重复。
|
|
76
|
+
|
|
77
|
+
## 使用
|
|
78
|
+
|
|
79
|
+
所有功能由一个配置文件加会话内命令控制。无配置文件时：压缩按默认值运行；联网搜索、图像生成、Auto 模式、Remote Context 均需显式开启。Astra 兼容层与网关 Remote Context 按内置的 `gpt-6-astra` 模型名匹配启用，不走任何白名单。
|
|
80
|
+
|
|
81
|
+
创建 `~/.pi/agent/extensions/pi-openai-toolkit/config.json`（Windows：`C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json`）：
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"compaction": {
|
|
86
|
+
"enabled": true,
|
|
87
|
+
"contextManagement": "remote",
|
|
88
|
+
"contextReminderThresholdPercent": 10,
|
|
89
|
+
"allowCompactionContinuityBreak": false,
|
|
90
|
+
"remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
|
|
91
|
+
"nativeFallback": { "enabled": true, "model": null, "thinkingLevel": "off" },
|
|
92
|
+
"responsesApis": ["openai-responses", "openai-codex-responses"],
|
|
93
|
+
"notifyOnLoad": false,
|
|
94
|
+
"debug": false,
|
|
95
|
+
"logProviderPayloads": false,
|
|
96
|
+
"logCompactResponses": false,
|
|
97
|
+
"redactSensitiveData": true,
|
|
98
|
+
"artifactRoot": "~/.pi/agent/artifacts/pi-openai-toolkit/compaction"
|
|
99
|
+
},
|
|
100
|
+
"webSearch": { "enabled": true, "models": ["uwoacrimson/gpt-5.6-luna"] },
|
|
101
|
+
"imageGeneration": { "enabled": false },
|
|
102
|
+
"autoMode": {
|
|
103
|
+
"enabled": true,
|
|
104
|
+
"models": ["uwoacrimson/gpt-5.6-luna"],
|
|
105
|
+
"reviewerModel": "uwoacrimson/gpt-5.6-luna",
|
|
106
|
+
"gate": "side-effect"
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
之后正常启动 Pi，工具包自动加载并接管每个会话：
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pi --model uwoacrimson/gpt-6-astra "继续部署任务"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### 配置
|
|
118
|
+
|
|
119
|
+
所有键都可选；未知键只告警忽略，不会回写你的文件。`models` 类键是精确 `provider/model-id` 白名单——只做 trim，不做通配——所以每个功能在你列入模型前都是关的。
|
|
120
|
+
|
|
121
|
+
#### `compaction`
|
|
122
|
+
|
|
123
|
+
| 键 | 类型 / 默认 | 说明 |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| `enabled` | *boolean*, `true` | 压缩扩展 hook 总开关。 |
|
|
126
|
+
| `contextManagement` | `"off"` \| `"remote"`, `"off"` | 启用 Codex 远端上下文管理。覆盖模型为原生 Codex 模型，加上在 Codex 兼容网关（`openai-responses`）上的 `gpt-6-astra`；匹配规则内置，无白名单。覆盖模型由其独占：不发送 `remote_compaction_v2`，且取消 Pi 原生压缩（见[安全](#安全)）。设回 `"off"` 即回滚。 |
|
|
127
|
+
| `contextReminderThresholdPercent` | *integer* `0`-`100`, `5` | 仅 Remote Context：当前窗口剩余 token 低于窗口该百分比时，每窗口注入一次 checkpoint 提醒；`0` 关闭提醒（窗口耗尽兜底仍生效）。建议明显高于 Pi 原生 reserve 余量（默认 16384 token，约为 272k 窗口的 6%），让模型在撞阈值前有机会主动换窗。 |
|
|
128
|
+
| `allowCompactionContinuityBreak` | *boolean*, `false` | v2 路径：最近一次压缩由其他方式（如文本摘要）生成时，允许从当前文本上下文重建密文链。 |
|
|
129
|
+
| `remoteCompactModel` | *string \| null*, `null` | v2 路径：仅用于 synthetic `remote_compaction_v2` 请求的模型，会话模型不切换；必须与当前模型解析出相同生效 Base URL。 |
|
|
130
|
+
| `nativeFallback.enabled` | *boolean*, `true` | 远端请求已尝试但失败时，用显式摘要模型跑 Pi 原生压缩；成功远端链路不受影响。 |
|
|
131
|
+
| `nativeFallback.model` | *string \| null*, `null` | 仅用于完全无法走 v2 的模型（非 Responses API 或被 `responsesApis` 排除）；`null` 用当前模型。 |
|
|
132
|
+
| `nativeFallback.thinkingLevel` | *string*, `"off"` | 本扩展指定模型时传给 Pi `compact()` 的思考级别。 |
|
|
133
|
+
| `responsesApis` | *string[]*, 两个 API | 限定可尝试远端压缩的 API 标识符子集；仅 `contextManagement` 为 `"off"` 时生效。 |
|
|
134
|
+
| `notifyOnLoad` | *boolean*, `false` | 启动横幅通知。 |
|
|
135
|
+
| `debug` | *boolean*, `false` | 在 `artifactRoot` 下写 lifecycle 与压缩 artifact，含每次 `session_start` 的 Remote Context 激活结果与原因。 |
|
|
136
|
+
| `logProviderPayloads` / `logCompactResponses` | *boolean*, `false` | 额外把原始 provider 请求体与压缩 SSE 事件写入 artifact。除非排查特定请求，保持关闭。 |
|
|
137
|
+
| `redactSensitiveData` | *boolean*, `true` | artifact 全量脱敏；即使设为 `false`，Authorization 凭据、API Key/Token、Codex account ID 与 `encrypted_content` / `encrypted_output` 也始终脱敏。 |
|
|
138
|
+
| `artifactRoot` | *string*, `~/.pi/agent/artifacts/pi-openai-toolkit/compaction` | artifact 根目录；相对路径基于配置目录解析。 |
|
|
139
|
+
|
|
140
|
+
#### `webSearch`
|
|
141
|
+
|
|
142
|
+
| 键 | 类型 / 默认 | 说明 |
|
|
143
|
+
| --- | --- | --- |
|
|
144
|
+
| `enabled` | *boolean*, `true` | 总开关。 |
|
|
145
|
+
| `models` | *string[]*, `[]` | 接收托管 `web_search` 注入的精确白名单（限 Responses 系 API）。名单内模型的上行载荷会移除本地 `web_search` 函数工具，原生搜索成为唯一路径；切到名单外模型即恢复。 |
|
|
146
|
+
|
|
147
|
+
#### `imageGeneration`
|
|
148
|
+
|
|
149
|
+
| 键 | 类型 / 默认 | 说明 |
|
|
150
|
+
| --- | --- | --- |
|
|
151
|
+
| `enabled` | *boolean*, `false` | `openai_generate_image` 的唯一开关。默认关闭，因为每次成功请求都可能产生费用。无模型白名单：托管图像工具是 Responses API 能力，对所有 Responses 系模型暴露、其余隐藏。 |
|
|
152
|
+
|
|
153
|
+
#### `autoMode`
|
|
154
|
+
|
|
155
|
+
| 键 | 类型 / 默认 | 说明 |
|
|
156
|
+
| --- | --- | --- |
|
|
157
|
+
| `enabled` | *boolean*, `true` | 总开关；未列入白名单或未设 `reviewerModel` 前依然无法启用。 |
|
|
158
|
+
| `models` | *string[]*, `[]` | 允许进入 auto 模式的当前会话模型白名单。 |
|
|
159
|
+
| `reviewerModel` | *string \| null*, `null` | 审批模型（`provider/model-id`，经 Pi 注册表解析）。只用于单次审批请求，绝不成为会话模型。 |
|
|
160
|
+
| `gate` | `"side-effect"` \| `"all"`, `"side-effect"` | 审批范围；`/auto all` 把当次会话扩到全部工具。 |
|
|
161
|
+
| `extraTools` | *string[]*, `[]` | 在副作用集（`bash`、`write`、`edit`）之外追加审批的工具名。 |
|
|
162
|
+
| `timeoutMs` | *integer* 1000-120000, `30000` | 审批模型全部轮次的总时限；超时绝不视为通过。 |
|
|
163
|
+
| `transcript` | *boolean*, `true` | 给审批模型有界的会话视图，使其能判断"用户是否授权"而非只看命令危险度。 |
|
|
164
|
+
| `evidenceTools` | *boolean*, `true` | 允许审批模型先用 Pi 只读工具（`read`/`grep`/`find`/`ls`）查证；它永远拿不到 `bash`、写工具或网络。 |
|
|
165
|
+
| `maxEvidenceRounds` | *integer* 0-8, `3` | 调查轮数上限；`0` 为单次补全。 |
|
|
166
|
+
| `classifier.*` | 见码内说明 | 可选非阻塞低风险预打分（`enabled` `false`、`model`、`timeoutMs` `15000`、`maxLag` `2`），只能给普通调用开快车道，绝不否决。 |
|
|
167
|
+
| `circuitBreaker.*` | — | 否决熔断（连续 `consecutiveDenials` `3` 或窗口 `windowSize` `50` 内 `recentDenials` `10` 结束回合；`0` 关闭）。 |
|
|
168
|
+
|
|
169
|
+
#### `codexAstra`
|
|
170
|
+
|
|
171
|
+
已移除。Astra 兼容层（对所有 `openai-codex-responses` 请求的版本门禁头，以及保缓存的 `configuration_update` 档位改写）现按模型名 `gpt-6-astra` 静默启用（限 Responses 系 API），无需任何配置；旧配置里的 `codexAstra` 段会按未知字段告警并忽略。唯一保留的注意事项：宿主（如 Oh My Pi）已实现同款改写时只开一边，避免双重插入。
|
|
172
|
+
|
|
173
|
+
模型目录说明：Pi 内置 `openai-codex` 列表可能还没有 `gpt-6-astra`。在 `~/.pi/agent/models.json` 的内置 provider 下登记（`api: "openai-codex-responses"`、`baseUrl: "https://chatgpt.com/backend-api"`、`contextWindow: 272000`、`maxTokens: 128000`、`thinkingLevelMap` `low`…`max`）；令牌由 Pi 的 Codex OAuth 提供。
|
|
174
|
+
|
|
175
|
+
### 功能指南
|
|
176
|
+
|
|
177
|
+
#### Codex 远端上下文管理
|
|
178
|
+
|
|
179
|
+
`contextManagement` 为 `"remote"` 且会话模型被覆盖（原生 `openai-codex`，或 API 为 `openai-responses` 的 `gpt-6-astra`；模型匹配内置）时，会话进入 Codex 窗口生命周期：
|
|
180
|
+
|
|
181
|
+
- **窗口身份。** `session_start` 初始化窗口（first/current/previous id、窗口编号），以 `codex-context-window` 自定义消息持久化进 Pi 会话；resume 回放、fork 后重建。实时请求携带 `x-codex-window-id` 与 `x-codex-turn-metadata`。
|
|
182
|
+
- **无摘要换窗。** `new_context` 安装新窗口并把旧窗口从模型上下文裁剪，不做任何再摘要；旧轮次仍可通过服务端 `history` 取回。
|
|
183
|
+
- **Checkpoint 门禁。** 换窗前必须存在当前窗口内*成功的* `notes` `append_to_file` / `write_file`，校验基于持久化会话分支重建（重启后依然有效）；不满足时 `new_context` 拒绝。`force: true` 是用户明确授权丢弃的唯一逃生口；Toolkit 自己的窗口耗尽兜底会在要求最后一次 notes 写入后自动绕过门禁。
|
|
184
|
+
- **预算。** `get_context_remaining` 报告实时窗口预算；`contextReminderThresholdPercent` 控制每窗口一次的 checkpoint 提醒。
|
|
185
|
+
- **压缩独占。** 覆盖模型的全部压缩事件由本包接管：不发送 v2；即使 Remote 运行时暂时未激活也取消 Pi 原生压缩（阈值、手动 `/compact`、溢出三条路径全拦），不会有有损摘要背地里插入。未激活原因以通知呈现（`debug` 开启时同时写入 `session_start` lifecycle artifact 的 `activation` 字段），请修复该原因而非期待压缩。
|
|
186
|
+
|
|
187
|
+
原生路线经 `ModelRegistry` 复用 Pi 的 Codex OAuth；网关路线只用配置的数据面 API key——本地 OAuth 凭据、account cookie、account ID 绝不转发给网关。
|
|
188
|
+
|
|
189
|
+
**验证是否激活。** `/reload` 或新开会话后：会话里应出现 `codex-context-window` 边界消息，`new_context` / `get_context_remaining` / `history` / `notes` 工具可用。`debug: true` 时每次 `session_start` 在 `artifactRoot` 下写 lifecycle artifact，`activation` 字段记录 `active` 或未激活的确切原因（如 `tool-name-conflict`、`missing-api-key`、`auth-resolution-failed`）。
|
|
190
|
+
|
|
191
|
+
#### Remote Compaction v2
|
|
192
|
+
|
|
193
|
+
`contextManagement` 关闭时，符合条件的 Responses 会话走 v2：在实时流式请求尾部追加 `compaction_trigger`，响应需返回恰好一个带非空 `encrypted_content` 的 `type: "compaction"` 输出项，密文存入 `CompactionEntry.details.compactedWindow`；后续请求把密文项前置回放——零丢失、无文本摘要。回放有 fail-closed 保护：找不到摘要锚点即中止请求并通知、写无内容失败 artifact，绝不发送 sentinel 裸载荷。降级层：远端尝试失败可交给 Pi 原生压缩（`remoteCompactModel`/当前模型）；完全不能用 v2 的模型走 `nativeFallback`。Pi 0.85.1+ 自己驱动自动压缩，本包不再另起驱动器。
|
|
194
|
+
|
|
195
|
+
#### Auto 模式
|
|
196
|
+
|
|
197
|
+
会话内用 `pi --auto` 或 `/auto on` 启用（页脚显示状态；启用动作本身不发起任何请求）。被门禁的每个调用由 `reviewerModel` 审批：分开评估行为固有风险与对话授权程度，按固定表得出 `allow`/`deny`；审批模型可先跑只读工具取证；否决会把理由与禁止绕条款返回给请求模型；未完成的审批（超时/取消/报错）按故障上报，绝不伪装成安全结论。所有决策以非上下文会话条目持久化备审计。无 UI（`-p`/JSON）时无人可升级确认，审批不可用即拦截。
|
|
198
|
+
|
|
199
|
+
## 开发
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
npm run typecheck # tsc 项目检查
|
|
203
|
+
bun test # 全量单元测试
|
|
204
|
+
npm run test:pi # Pi 集成冒烟测试
|
|
205
|
+
npm pack --dry-run # 检查发布包内容
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Remote Context 协议 fixture（`src/context-management/`）必须与上游 alpha 端点变更同步更新。
|
|
209
|
+
|
|
210
|
+
## API
|
|
211
|
+
|
|
212
|
+
### Remote Context 工具
|
|
213
|
+
|
|
214
|
+
Remote Context 激活时注册的四个工具：
|
|
215
|
+
|
|
216
|
+
| 工具 | 参数 | 结果 / 错误 |
|
|
217
|
+
| --- | --- | --- |
|
|
218
|
+
| `new_context` | `{ force?: boolean }` | 换到下一窗口，不摘要。当前窗口没有成功的 notes checkpoint 时拒绝（`force` 可越过）；已有换窗排队时报告 "already scheduled"。 |
|
|
219
|
+
| `get_context_remaining` | 无 | 当前窗口剩余 token 与窗口身份；尚无任何用量来源时返回 unknown。 |
|
|
220
|
+
| `history` | `{ action: "list_windows" \| "list_items" \| "read_item" \| "search_contents", ... }` | 读取既往窗口。返回的 `item_id`/窗口 ID 必须原样传递；搜索词按加密参数策略发送。 |
|
|
221
|
+
| `notes` | `{ action: "list_files_by_prefix" \| "read_file" \| "search_contents" \| "append_to_file" \| "write_file", path, text, ... }` | 跨窗口工作记忆。路径解析到会话 agent 目录下（如 `/root/notes/<file>` 或相对路径）；非法路径由后端拒绝。成功的 append/write 就是满足 `new_context` 门禁的凭证。 |
|
|
222
|
+
|
|
223
|
+
四个工具在超时、取消、非 2xx、非法 JSON、认证、协议故障时都抛出明确工具错误，绝不静默降级。
|
|
224
|
+
|
|
225
|
+
### HTTP 协议参考
|
|
226
|
+
|
|
227
|
+
内部 alpha 端点，改编自 `@howaboua/pi-codex-conversion`（见[背景](#背景)）：
|
|
228
|
+
|
|
229
|
+
```text
|
|
230
|
+
POST {base}/alpha/history/v2/list_windows | list_items | read_item | search_contents
|
|
231
|
+
POST {base}/alpha/notes/v2/list_files_by_prefix | read_file | search_contents | append_to_file | write_file
|
|
232
|
+
GET {base}/alpha/notes/v2/thread_hint
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
原生路线 `{base} = <backend-api>/codex`，携带 `Authorization: Bearer <oauth token>`、`ChatGPT-Account-ID` 与 Codex CLI 头。网关路线用配置的 `/v1` base + 数据面 API key，携带 `originator: codex_cli_rs`、`X-Codex-Affinity-Scope`、`X-Codex-Model`（裸模型 ID）——绝不含本地凭据。两条路线都设置 `Session-Id` / `X-Client-Request-Id`（有界的 Pi 会话 ID）、`x-openai-tool-output-truncation-policy`，加密参数端点另带 `x-openai-encrypted-tool-arguments`；加密结果以 `encrypted_output` 返回并重新编码进后续请求。这些是 alpha 契约，上游可能随时变更。
|
|
236
|
+
|
|
237
|
+
## 维护者
|
|
238
|
+
|
|
239
|
+
[awoaCrim](https://github.com/awoaCrim)
|
|
240
|
+
|
|
241
|
+
## 贡献
|
|
242
|
+
|
|
243
|
+
欢迎在 [issue 区](https://github.com/awoaCrim/pi-openai-toolkit/issues)提问和提交 PR。涉及行为变更请先开 issue 讨论（尤其是 alpha `history`/`notes` 协议假设）。提交前跑 `bun test` 与 `npm run typecheck`；新的线路协议行为需要 fixture 测试。
|
|
244
|
+
|
|
245
|
+
## 许可证
|
|
246
|
+
|
|
247
|
+
MIT © awoaCrim and contributors。见 [LICENSE](./LICENSE)，第三方归属见 [NOTICE](./NOTICE)。
|
|
248
|
+
|
|
249
|
+
## 致谢
|
|
250
|
+
|
|
251
|
+
感谢 [Linux.do](https://linux.do/) 社区的支持与讨论。
|