dsh-lcx-codex 0.3.3 → 0.4.0-rc.13

package/README.md

@@ -1,162 +1,270 @@
-# dsh-lcx-codex
+<div align="center">
 
-**简体中文** | [English](README_EN.md)
+<img src="https://raw.githubusercontent.com/kk3ya03-star/dsh-lcx-codex/main/assets/dsh-lcx-codex-banner.jpg" alt="DSH-LCX-CODEX" width="100%" />
 
-[![npm version](https://img.shields.io/npm/v/dsh-lcx-codex.svg)](https://www.npmjs.com/package/dsh-lcx-codex)
-[![license](https://img.shields.io/npm/l/dsh-lcx-codex.svg)](LICENSE)
+# DSH-LCX-CODEX
 
-社区维护的 DSH 插件，为兼容 OpenAI Responses/Codex 协议的 GPT 模型增加 Hosted Web Search、Alpha Search 和 Native V2 远程压缩。
+**给 DeepSeek Harness 补上 GPT Responses / Codex 原生能力。**
 
-> [!IMPORTANT]
-> Alpha Search 有 5 种可用部署路径：Sub2API 直连，以及经 NewAPI 的 4 种渠道类型：`Sub2API`、`New API`、`ChatGPT Subscription (Codex)`、`Advanced Custom`。普通 `OpenAI` 渠道不支持 `/v1/alpha/search`，会在 NewAPI 内被拒绝。
+[![npm](https://img.shields.io/npm/v/dsh-lcx-codex?color=1677ff&label=npm)](https://www.npmjs.com/package/dsh-lcx-codex)
+![Node](https://img.shields.io/badge/Node-%3E%3D20-1677ff)
+![DSH](https://img.shields.io/badge/DSH-0.1.1--rc.2-4ea8ff)
+![License](https://img.shields.io/badge/license-MIT-1677ff)
 
-这份名单来自 NewAPI 当前主分支的 [`AlphaSearchHelper`](https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relay/alpha_search_handler.go)。不同版本的 NewAPI 可能有差异，最终以实际 capability probe 为准。
+**简体中文** · [English](README_EN.md)
 
-`LCX` 只是插件名称，不是服务商或协议。本插件支持：
+</div>
 
-- 直接使用 Sub2API 反代的 GPT 模型。
-- 使用 NewAPI 中转的 GPT 模型（也就是第三方中转）；NewAPI 的上游渠道连接 Sub2API。
+---
 
-```mermaid
-flowchart LR
-    accTitle: dsh-lcx-codex 技术路线
-    accDescr: 插件复用当前 DSH openai-responses 模型的路由和凭据，将 Hosted Search、capability-gated Alpha Search 与 Native V2 Compact 请求经受控传输发送到 Sub2API 直连或 NewAPI 中转部署。
+`dsh-lcx-codex` 是一个社区维护的 DSH 插件，面向已经通过 `llm-pi-ai / openai-responses` 接入的 GPT 路由。它尽量复用 DSH 自己的 Agent、Web、Session 和 Compaction 架构，只在缺少 OpenAI/Codex 原生语义的地方补能力。
 
-    dsh_session([DSH GPT 会话]) --> resolve_route[复用 provider、model、baseURL 和凭据]
+> `LCX` 只是项目名称。本项目不隶属于 OpenAI、DeepSeek、Sub2API 或 NewAPI。
 
-    subgraph plugin_capabilities ["dsh-lcx-codex"]
-        hosted_search[Hosted Search<br/>POST /responses + web_search]
-        alpha_gate{Alpha capability 匹配?}
-        alpha_search[Alpha Search<br/>POST /alpha/search]
-        alpha_disabled([Alpha 不注册])
-        native_compact[Native V2 Compact<br/>stream + compaction_trigger]
-    end
+- **最新版 DSH 图片管线**：Native V2 直接复用 `readImageRequest()` 和当前路由图片预算，避免压缩请求与普通 GPT 请求使用不同的图片版本。
 
-    resolve_route --> hosted_search
-    resolve_route --> alpha_gate
-    resolve_route --> native_compact
-    alpha_gate -->|是| alpha_search
-    alpha_gate -->|否| alpha_disabled
+## 核心能力
 
-    hosted_search --> transport[受控鉴权、超时、重试和响应大小]
-    alpha_search --> transport
-    native_compact --> transport
+| 能力 | 说明 | 默认 |
+|---|---|---:|
+| **DSH 原生 `web_search` → GPT Hosted Search** | 不新增重复的普通搜索工具；rc.7+ 自动跟随当前 Agent 的 GPT Responses 模型 | 可开启 |
+| **Advanced Hosted Search** | 域名过滤、location、search context、图片搜索等 OpenAI Hosted 参数 | 关闭 |
+| **Alpha Search** | `search/open/find/click/screenshot` 等 Codex/Alpha 风格命令；能力探针通过后才注册 | 关闭 |
+| **Native Remote Compaction V2** | 通过 Responses `compaction_trigger` 获取 provider-native opaque checkpoint | 可开启 |
+| **Conversation fidelity retention** | 显式保留 bounded user / assistant 可见事实，避免只记得“问过什么”却忘记“答了什么” | 内置 |
+| **Session-native checkpoint** | checkpoint 存在 DSH append-only session log，不再以 sidecar 作为新会话真相源 | 内置 |
+| **Native-first 自动压缩** | 90% 主动 Native V2，95% emergency 才允许 DSH prune；阈值可调 | 可开启 |
+| **长搜索超时** | DSH `web_search` 外层 timeout 默认提升到 240 秒，可调 30–600 秒 | 内置 |
 
-    transport --> deployment{部署路径}
-    deployment -->|直连| sub2api[Sub2API]
-    deployment -->|中转| newapi[NewAPI 兼容渠道]
-    sub2api --> upstream([OpenAI Responses/Codex-compatible upstream])
-    newapi --> upstream
+## rc.8：面向 DSH 0.1.1-rc.2
 
-    upstream -.->|compaction output| checkpoint[(Checkpoint v3)]
-    checkpoint -->|同路由| opaque_replay[Opaque native replay]
-    checkpoint -->|路由或模型变化| portable_migration[Portable migration]
-    opaque_replay --> transport
-    portable_migration --> transport
+rc.8 直接面向 **DSH 0.1.1-rc.2**。普通 `web_search` 继续跟随当前 Agent 模型，同时 Native V2 的图片输入改用新版 DSH `readImageRequest()` 管线，不再直接读取 attachment master bytes。
+
+搜索路由仍通过 **DSH `tools/execute` → SearchProvider** 运行时上下文传递：
+
+```text
+Agent: lcx / gpt-5.6-luna
+        │
+        └─ DSH web_search
+             │
+             └─ Hosted Search: lcx / gpt-5.6-luna
+
+Agent: lcx / gpt-5.6-sol
+        │
+        └─ DSH web_search
+             │
+             └─ Hosted Search: lcx / gpt-5.6-sol
 ```
 
-本项目不隶属于 OpenAI，也不是 OpenAI 官方发布的插件或 OAuth 客户端。
+这不会修改模型看到的 `web_search` schema。
 
-## 功能
+没有 Agent 上下文时，才使用设置页里的 **回退 Responses 地址 / 回退 GPT 模型**。
 
-| 功能 | 工具或协议 | 说明 |
-|---|---|---|
-| Hosted Web Search | `websearch_gpt` | `/responses` + `web_search`，返回正文、来源和 citations |
-| Alpha Search | `websearch_alpha` | `/alpha/search`，支持 search、open/find/click、PDF screenshot、image、finance、weather、sports 和 time |
-| Native V2 Compact | `/responses` + `compaction_trigger` | 保存 checkpoint v3，支持同路由回放、模型迁移、fork/tree、重启和图片 attachment |
+### Search 与会话缓存隔离
 
-Alpha 只有在 capability 记录与当前 endpoint、provider、model 和 schema 匹配时才会启用。Hosted 与 Alpha 是两条独立协议，不会互相静默降级。
+Hosted Search 是一笔独立 Responses 请求，不等于主会话推理。rc.8 继续给搜索使用独立 cache namespace：
 
-## 安装
+```text
+主会话 replay:  dsh-lcx:<route hash>
+Hosted Search: dsh-lcx-search:<route hash>
+```
 
-推荐从 npm 安装：
+因此搜索不会故意与 Native replay 共用同一个 `prompt_cache_key`。NewAPI 后台仍可能看到搜索请求夹在主会话请求之间；它们是不同请求，搜索行本身 cache 较低并不代表 DSH session 被截断。
 
-```powershell
-dsh plugin --profile web add dsh-lcx-codex
+## Native V2 Compaction
+
+DSH 本身已经负责：
+
+- token pressure；
+- compactable range selection；
+- tool-result pruning；
+- durable session transaction；
+- `/compact`；
+- context-overflow recovery。
+
+本插件不再造第二套 compaction engine，而是在 DSH 的 `purpose: 'compaction'` LLM seam 上执行 Native V2：
+
+```text
+DSH compaction transaction
+        │
+        └─ purpose=compaction
+              │
+              └─ POST /responses
+                   x-codex-beta-features: remote_compaction_v2
+                   input: [...history, { type: "compaction_trigger" }]
 ```
 
-也可以下载 GitHub Release 中的 `.tgz` 安装指定版本：
+Native 成功：不再额外运行 basic summary。
 
-```powershell
-dsh plugin --profile web add .\dsh-lcx-codex-0.3.2.tgz
+Native 失败且开启 fallback：才回到 DSH basic compaction。
+
+## 为什么压缩后还能记住模型自己说过的话
+
+单纯依赖 provider-native opaque compaction 是有损的。真实长会话测试发现，低显著性的 assistant-only 事实可能被压掉，例如：
+
+- 模型随机生成的项目代号；
+- 搜索后模型给出的具体姓名；
+- 只在 assistant 最终回答里出现的数字。
+
+因此当前 checkpoint 使用：
+
+```text
+bounded client-visible history
++ bounded assistant-visible answers
++ opaque Native V2 compaction item
 ```
 
-安装后启动 DSH：
+默认总 explicit retention 预算约 `64k` estimated tokens，其中 assistant-visible answer 最多预留约 `24k`，单条默认最多约 `3k`。不把 reasoning、巨大 tool result、完整搜索正文和运行 telemetry 全塞回来。
 
-```powershell
-dsh web
+目标不是“逐字无损”，而是：**删过程，保事实。**
+
+## 自动压缩策略
+
+rc.8 延续 rc.6 的 Native-first pressure policy：
+
+```text
+0% ─────────────────── 90% ───── 95% ───── 100%
+       正常使用          Native     emergency    hard cap
+                         V2         DSH prune
+```
+
+默认：
+
+- `< 90%`：不让 DSH 原来的 80% pressure prune 提前改写历史；
+- `90%–95%`：优先 Native V2；
+- `>= 95%`：允许 DSH replay-safe tool-result pruner 救场；
+- provider 明确返回 context overflow：仍保留 DSH 原生 recovery；
+- 手动 `/compact`：不受阈值影响。
+
+阈值可在插件设置页调整。
+
+## 关于“缓存突然断了”
+
+需要区分两件事：
+
+```text
+cacheRead = 0
+≠
+会话历史被删除
 ```
 
-打开 `设置 -> 插件 -> LCX / Codex 能力`，按需启用 Hosted、Alpha 或 Native Compact。插件默认关闭。
+在真实 NewAPI 日志里，出现过：
 
-## 要求
+```text
+某轮：155k uncached / cacheRead 0
+下一轮：~1k new input / ~155k cacheRead
+```
+
+这说明上一轮只是 provider prompt-cache miss / eviction，完整上下文仍被重新发送，并没有发生 session compaction 或 surface replacement。
+
+真正会主动改变历史前缀的主要情况是：
+
+1. `/compact` / 自动 Native compaction；
+2. emergency tool-result pruning；
+3. 换模型 / provider / baseURL；
+4. DSH 自己发生其他 surface replacement。
+
+DSH 重启、长时间 idle、上游 cache TTL/eviction 也可能造成某一轮重新建 cache；插件无法保证第三方网关永不 evict KV cache。
+
+## 搜索分层
+
+### 1. 普通搜索：`web_search`
+
+推荐默认使用。rc.8 会跟随当前 Agent 的 GPT Responses route。
 
-- Node.js 20 或更高版本
-- DSH `0.1.0-rc.8` 或兼容版本
-- 已在 DSH 中添加并能正常对话的 GPT 模型
-- 模型使用 `llm-pi-ai` 的 `openai-responses` provider
+### 2. 高级 Hosted：`websearch_gpt_advanced`
 
-插件复用当前 DSH 模型的 provider、model、Responses 地址、凭据引用、headers 和 retry policy，并通过 DSH credentials service 取凭据。正常运行不需要再给插件配置一份 `LCX_API_KEY`。
+仅在需要这些参数时开启：
 
-界面中的 endpoint 和 model 字段用于没有活动会话路由时的默认选择，以及旧版直连配置兼容；同名 DSH provider 已存在时，以 DSH provider 配置为准。
+- allowed / blocked domains；
+- approximate user location；
+- `search_context_size`；
+- image search；
+- external web access；
+- return token budget。
 
-## Alpha probe
+开启/关闭额外工具会改变 tool catalog，因此默认关闭以保持主会话 request schema 稳定。
 
-Alpha 能力按部署记录为 `native`、`command-capable`、`emulated-search-only`、`unsupported` 或 `unknown`。HTTP 200 本身不能证明 action 是原生能力。
+### 3. Alpha：`websearch_alpha`
 
-探针是 DSH runtime 外的独立 Node.js 脚本，不能调用 DSH credentials service，因此探针需要本机 key 文件；插件运行时不需要重复配置。
+面向 stateful Codex/Alpha 风格搜索：`search/open/find/click/screenshot` 等。只有 capability probe 与当前 endpoint/provider/model/schema 匹配后才注册。
+
+## 安装
+
+### npm
+
+稳定版：
 
 ```powershell
-$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $env:USERPROFILE '.dsh' }
-$env:LCX_API_KEY_FILE = 'C:\path\to\local-key.txt'
-$env:LCX_MODEL = '实际模型名'
-node (Join-Path $dshHome 'profiles\web\node_modules\dsh-lcx-codex\scripts\probe-alpha.mjs')
+dsh plugin --profile web add dsh-lcx-codex
 ```
 
-要同时探测 image、finance、weather、sports 和 time：
+预发布版（当前 rc.8）：
 
 ```powershell
-$env:LCX_ALPHA_PROBE_STRUCTURED = '1'
-node (Join-Path $dshHome 'profiles\web\node_modules\dsh-lcx-codex\scripts\probe-alpha.mjs')
+dsh plugin --profile web add dsh-lcx-codex@next
 ```
 
-探针不会输出 key 或完整响应正文。完成后重启 DSH，或关闭再开启 Alpha 设置。
+### 本地 RC
 
-## 数据与限制
+```powershell
+dsh plugin --profile web remove dsh-lcx-codex
+dsh plugin --profile web add .\dsh-lcx-codex-0.4.0-rc.13.tgz
+dsh web
+```
 
-- 网络目标由当前活动 DSH `openai-responses` provider 的 `baseURL` 决定，不固定到 LCX 或其他域名；插件只在该地址下调用 `/responses` 和 `/alpha/search`
-- 凭据名称取自同一 provider 的 `apiKeyEnv`，并由 DSH credentials service 解析；插件不会自行保存 API key
-- Checkpoint：`$DSH_HOME/storages/lcx-codex/checkpoints-v3.json`
-- Alpha capability：`$DSH_HOME/storages/lcx-codex/web-alpha-capabilities.json`
-- Alpha refs：`$DSH_HOME/storages/lcx-codex/web-alpha-refs.json`
-- 只支持 Native remote-compaction V2，不调用 `/responses/compact`
-- 同路由 replay 会复用 DSH session 的 `prompt_cache_key` 并保持已有请求前缀稳定；短期缓存过期后仍可能出现单次冷请求，不能用会话累计命中率判断插件是否破坏缓存
-- Sub2API 的 Codex OAuth 转换层会删除上游不支持的 `prompt_cache_retention`，因此经该路径设置 `24h` 不会延长缓存；以实际连续请求的 `cached_tokens` 为准
-- Checkpoint 不保存图片原始字节或 data URL
-- Opaque checkpoint 不跨不兼容 provider、model、base URL、session 或 lineage 回放
-- 不包含图片生成功能
+不要为了升级删除 `$DSH_HOME/storages/lcx-codex/` 或旧 session。v3 sidecar 仍作为只读旧会话兼容层。
 
-不要把 API key、OAuth token、Authorization header、账户 ID、session cookie 或运行时 sidecar 提交到 GitHub。
+## 推荐设置
 
-## 更新与卸载
+```text
+Enable plugin                         ✅
+Use GPT Hosted Search                ✅
+Advanced Hosted Search               ❌
+Alpha Search                         ❌
 
-```powershell
-dsh plugin --profile web update dsh-lcx-codex
-dsh plugin --profile web remove dsh-lcx-codex
+Native V2 remote compaction          ✅
+Native-first auto compaction         ✅
+Native threshold                     90%
+Emergency DSH prune                  95%
+web_search timeout                   240s
+```
+
+调试 Native 时可以先关闭 fallback；稳定使用时是否开启 fallback 由你决定。
+
+## 部署要求
+
+- Node.js `>=20`
+- DSH `0.1.1-rc.2`
+- DSH 中已经能正常使用的 GPT `openai-responses` route
+- upstream 实际支持你启用的 Hosted Search / Native V2 / Alpha 能力
+
+典型路径：
+
+```text
+DSH → llm-pi-ai/openai-responses → Sub2API
+DSH → llm-pi-ai/openai-responses → NewAPI → upstream
 ```
 
-卸载不会删除 `$DSH_HOME/storages/lcx-codex/`。如果会话仍引用 checkpoint marker，不要单独删除对应 sidecar。
+插件优先复用 DSH route 的 `baseURL`、credential reference、headers 和 retry policy。
+
+## 发布通道
+
+- npm stable：正式稳定版本
+- npm `next`：`0.4.0-rc.*` 预发布测试版本
+
+GitHub tag 与 `package.json` version 必须一致；Trusted Publishing workflow 会先跑测试再发布。
 
 ## 开发
 
-```powershell
-npm install
+```bash
 npm test
 npm run test:schema
+npm pack --ignore-scripts
 ```
 
-真实 E2E 和 Alpha probe 只应读取本机忽略文件或环境变量中的测试凭据。
+关键设计说明见 [ARCHITECTURE.md](ARCHITECTURE.md)，完整版本记录见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## License
 
-[MIT](LICENSE)
+MIT