dsh-lcx-codex 0.4.0 → 0.4.1-pre.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.1-pre.1 - Candidate QA pending / not published
+
+- Integrates the accepted Alpha stateful continuation and fail-closed capability work from #20, #21, and #22.
+- Includes accepted compatibility seam isolation (#24), typed protocol-core hardening (#25), unified conservative token budgeting (#26), and the installed-plugin settings lifecycle fix (#36).
+- This is an unpublished candidate for #19 installed-candidate and cross-feature QA; no npm publication, tag, or release is implied.
+
 ## 0.4.0 - 2026-08-23
 
 ### Stable promotion

package/README.md

@@ -1,211 +1,170 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/kk3ya03-star/dsh-lcx-codex/main/assets/dsh-lcx-codex-banner.jpg" alt="DSH-LCX-CODEX" width="100%" />
-
-# DSH-LCX-CODEX
-
-**给 DeepSeek Harness 补上 GPT Responses / Codex 原生能力。**
+<img src="assets/dsh-lcx-codex-banner.png" alt="dsh-lcx-codex — 为 DSH 增加 GPT Hosted Search、Codex 风格网页操作与 Native V2 Compaction" width="100%" />
 
 [![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)
+[![CI](https://github.com/kk3ya03-star/dsh-lcx-codex/actions/workflows/publish.yml/badge.svg)](https://github.com/kk3ya03-star/dsh-lcx-codex/actions/workflows/publish.yml)
 ![DSH](https://img.shields.io/badge/DSH-0.1.1--rc.2-4ea8ff)
-![License](https://img.shields.io/badge/license-MIT-1677ff)
+![Node](https://img.shields.io/badge/Node-%3E%3D20-2f855a)
+![License](https://img.shields.io/badge/license-MIT-6b7280)
 
-**简体中文** · [English](README_EN.md)
+**简体中文** · [English](README_EN.md) · [Architecture](ARCHITECTURE.md) · [Changelog](CHANGELOG.md)
 
 </div>
 
----
-
-`dsh-lcx-codex` 是一个社区维护的 DSH 插件，面向已经通过 `llm-pi-ai / openai-responses` 接入的 GPT 路由。它尽量复用 DSH 自己的 Agent、Web、Session 和 Compaction 架构，只在缺少 OpenAI/Codex 原生语义的地方补能力。
+> **DSH 仍然是 host。LCX 只补齐 GPT Responses 路径缺失的原生能力，不修改 DSH 核心，也不替换 Agent / Session / Web / Compaction。**
 
-> `LCX` 只是项目名称。本项目不隶属于 OpenAI、DeepSeek、Sub2API 或 NewAPI。
+## 它解决什么
 
-- **最新版 DSH 图片管线**：Native V2 直接复用 `readImageRequest()` 和当前路由图片预算，避免压缩请求与普通 GPT 请求使用不同的图片版本。
+如果你的 DSH 已经有一个可工作的 GPT `openai-responses` route，`dsh-lcx-codex` 让这条 route 更完整地使用 GPT Responses 原生能力，同时尽量保持 DSH 原有入口和生命周期不变。
 
-## 核心能力
+| 场景 | DSH 原有入口 | LCX 增强后 |
+|---|---|---|
+| 普通联网搜索 | DSH `web_search` | **仍然使用同一个 `web_search`**，由 LCX SearchProvider 映射到当前 GPT Hosted Search |
+| Hosted Search 高级参数 | 普通搜索入口保持简洁 | 按需增加 `websearch_gpt_advanced`，提供域名过滤、近似位置、search context、图片搜索等 |
+| 连续网页 / PDF 浏览 | DSH 继续拥有 Web 生命周期 | 按需增加 Codex / Alpha Web Actions：`search → open → find/click → screenshot` |
+| 长会话压缩 | DSH 继续负责 pressure、事务与 recovery | 在现有 compaction seam 上优先请求 Responses Native V2 checkpoint |
 
-| 能力 | 说明 | 默认 |
-|---|---|---:|
-| **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 秒 | 内置 |
+**目标不是再造一套 Agent，而是让 DSH 的 GPT route 用上它本来就应该拥有的原生能力。**
 
-## rc.8：面向 DSH 0.1.1-rc.2
+## 三大能力
 
-rc.8 直接面向 **DSH 0.1.1-rc.2**。普通 `web_search` 继续跟随当前 Agent 模型，同时 Native V2 的图片输入改用新版 DSH `readImageRequest()` 管线，不再直接读取 attachment master bytes。
+### 1. GPT Hosted Search：普通搜索不换入口
 
-搜索路由仍通过 **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
-```
+启用后，模型看到的普通搜索工具依然是 DSH 原生 `web_search`。LCX 替换的是 SearchProvider 路径，而不是再注册一个重复的“普通搜索”工具。
 
-这不会修改模型看到的 `web_search` schema。
+需要更细控制时，再单独启用 `websearch_gpt_advanced`。
 
-没有 Agent 上下文时，才使用设置页里的 **回退 Responses 地址 / 回退 GPT 模型**。
+### 2. Codex 风格 Web Actions：需要时再打开
 
-### Search 与会话缓存隔离
-
-Hosted Search 是一笔独立 Responses 请求，不等于主会话推理。rc.8 继续给搜索使用独立 cache namespace：
+`websearch_alpha` 面向连续浏览和结构化 Web action：
 
 ```text
-主会话 replay:  dsh-lcx:<route hash>
-Hosted Search: dsh-lcx-search:<route hash>
+search → open → find / click → screenshot
 ```
 
-因此搜索不会故意与 Native replay 共用同一个 `prompt_cache_key`。NewAPI 后台仍可能看到搜索请求夹在主会话请求之间；它们是不同请求，搜索行本身 cache 较低并不代表 DSH session 被截断。
-
-## Native V2 Compaction
+它默认关闭，并且只有当前 endpoint / provider / model / schema 通过 capability probe 后才注册。未知部署采用 **fail-closed**，不会被误报成“支持 Alpha”。
 
-DSH 本身已经负责：
+### 3. Native V2 Compaction：保留 DSH 会话语义
 
-- token pressure；
-- compactable range selection；
-- tool-result pruning；
-- durable session transaction；
-- `/compact`；
-- context-overflow recovery。
+LCX 不创建第二套 compaction engine。DSH 仍然拥有 pressure、compactable range、`/compact`、durable session transaction、tool-result pruning 与 overflow recovery；LCX 只在已有 compaction LLM seam 上请求 Responses Native V2。
 
-本插件不再造第二套 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" }]
+0% ─────────────────── 90% ───── 95% ───── 100%
+       normal            Native      emergency   hard cap
+                         V2          DSH prune
 ```
 
-Native 成功：不再额外运行 basic summary。
-
-Native 失败且开启 fallback：才回到 DSH basic compaction。
-
-## 为什么压缩后还能记住模型自己说过的话
+- **90%**：优先尝试 Native V2。
+- **95%**：才允许 emergency DSH prune。
+- provider-confirmed context overflow：继续使用 DSH 原有恢复逻辑。
+- 手动 `/compact`：继续使用 DSH 原生会话事务。
 
-单纯依赖 provider-native opaque compaction 是有损的。真实长会话测试发现，低显著性的 assistant-only 事实可能被压掉，例如：
+同一 source session 可以继续复用自己的 Native checkpoint；fork 或模型迁移不会跨 session 发送 parent 的 opaque state，而是走 portable migration；重启后从 DSH session log 恢复。
 
-- 模型随机生成的项目代号；
-- 搜索后模型给出的具体姓名；
-- 只在 assistant 最终回答里出现的数字。
+## 30 秒开始使用
 
-因此当前 checkpoint 使用：
+### 1. 安装
 
-```text
-bounded client-visible history
-+ bounded assistant-visible answers
-+ opaque Native V2 compaction item
+```powershell
+dsh plugin --profile web add dsh-lcx-codex
+dsh web
 ```
 
-默认总 explicit retention 预算约 `64k` estimated tokens，其中 assistant-visible answer 最多预留约 `24k`，单条默认最多约 `3k`。不把 reasoning、巨大 tool result、完整搜索正文和运行 telemetry 全塞回来。
+### 2. 在 DSH Settings 启用
 
-目标不是“逐字无损”，而是：**删过程，保事实。**
+第一次使用建议从最小配置开始：
 
-## 自动压缩策略
+| 设置 | 建议 |
+|---|---:|
+| Enable plugin | **On** |
+| Use GPT Hosted Search | 需要 GPT Hosted Search 时 **On** |
+| Advanced Hosted Search | **Off**，需要高级参数再开 |
+| Alpha Search | **Off**，确认当前 route 支持后再开 |
+| Native V2 remote compaction | 上游实际支持 Native V2 时 **On** |
+| Native-first auto compaction | 使用 Native V2 时 **On** |
 
-rc.8 延续 rc.6 的 Native-first pressure policy：
+**前提条件**
 
-```text
-0% ─────────────────── 90% ───── 95% ───── 100%
-       正常使用          Native     emergency    hard cap
-                         V2         DSH prune
-```
+- Node.js `>=20`
+- DSH 中已有可工作的 GPT `openai-responses` route
+- 上游 endpoint 实际支持你准备启用的 Hosted Search / Native V2 / Alpha 能力
 
-默认：
+### 3. 确认它真的生效
 
-- `< 90%`：不让 DSH 原来的 80% pressure prune 提前改写历史；
-- `90%–95%`：优先 Native V2；
-- `>= 95%`：允许 DSH replay-safe tool-result pruner 救场；
-- provider 明确返回 context overflow：仍保留 DSH 原生 recovery；
-- 手动 `/compact`：不受阈值影响。
+不要只看开关是否打开，按能力检查实际行为：
 
-阈值可在插件设置页调整。
+| 能力 | 应看到什么 |
+|---|---|
+| GPT Hosted Search | 普通工具入口仍是 DSH `web_search`，实际请求走当前 GPT Responses route |
+| Advanced Hosted | 启用后出现 `websearch_gpt_advanced`，高级参数可以单独控制 |
+| Alpha Web Actions | 只有 capability probe 通过时才出现 `websearch_alpha` |
+| Native V2 | compact 时出现 provider-native checkpoint 路径；普通 Basic Compaction 不会被伪装成 Native V2 成功 |
 
-## 关于“缓存突然断了”
+## 搜索工具怎么选
 
-需要区分两件事：
+三个入口用途不同，**不需要全部开启**：
 
-```text
-cacheRead = 0
-≠
-会话历史被删除
-```
+| 你要做什么 | 使用入口 | 适合场景 |
+|---|---|---|
+| 普通联网搜索 | DSH `web_search` | 找资料、查网页、一般检索 |
+| 控制 Hosted Search 参数 | `websearch_gpt_advanced` | 域名 allow/block、近似位置、search context、图片搜索等 |
+| 连续浏览网页或 PDF | `websearch_alpha` | `search/open/find/click/screenshot` 与结构化 Web actions |
 
-在真实 NewAPI 日志里，出现过：
+## 它如何接入 DSH
 
 ```text
-某轮：155k uncached / cacheRead 0
-下一轮：~1k new input / ~155k cacheRead
+DSH Agent / Session / Web
+├─ web_search ──────────> LCX SearchProvider ──> GPT Hosted Search
+├─ Advanced / Alpha ────> LCX Web tools ───────> GPT Web actions
+└─ compact / replay ────> LCX Native bridge ───> Responses Native V2
 ```
 
-这说明上一轮只是 provider prompt-cache miss / eviction，完整上下文仍被重新发送，并没有发生 session compaction 或 surface replacement。
+**DSH 是 host，LCX 是兼容扩展层。** 插件优先复用当前 DSH route 的 `baseURL`、credential reference、headers、模型与 retry policy，而不是维护第二套账号配置。
 
-真正会主动改变历史前缀的主要情况是：
+checkpoint、canonical replay、Pi serializer、cache identity、fork safety 与 pressure coordination 等实现细节见 [ARCHITECTURE.md](ARCHITECTURE.md)。
 
-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。
+当前正式验证组合：
 
-## 搜索分层
+| Plugin | DSH | DSH host Pi | Plugin Pi | 状态 |
+|---|---|---|---|---|
+| `0.4.0` | `0.1.1-rc.2` | `0.82.1` | `0.82.1` | **VERIFIED** |
 
-### 1. 普通搜索：`web_search`
+新的 DSH 版本**不会自动视为兼容**。项目会先检查受影响的 DSH / Pi seam，再按风险运行对应测试；Pi registry 单独出现新版本也不会自动升级插件依赖。
 
-推荐默认使用。rc.8 会跟随当前 Agent 的 GPT Responses route。
+<details>
+<summary><strong>完整推荐设置</strong></summary>
 
-### 2. 高级 Hosted：`websearch_gpt_advanced`
+| 设置 | 推荐值 | 说明 |
+|---|---:|---|
+| Enable plugin | On | 启用插件 |
+| Use GPT Hosted Search | 按需 | 让 DSH `web_search` 走 GPT Hosted Search |
+| Advanced Hosted Search | Off | 需要高级 Hosted 参数时再开 |
+| Alpha Search | Off | capability 验证后再开 |
+| Native V2 remote compaction | On* | *上游 route 实际支持 Native V2 时 |
+| Native-first auto compaction | On | 启用自动 pressure 策略 |
+| Native threshold | 90% | 90% 开始优先 Native V2 |
+| Emergency DSH prune | 95% | 95% 才允许 emergency prune |
+| `web_search` timeout | 240 s | 避免长搜索被过早终止 |
 
-仅在需要这些参数时开启：
+主要配置字段：`remoteCompaction`、`autoCompaction`、`fallbackToBasicCompaction`、`autoCompactionThresholdPercent`、`emergencyPruneThresholdPercent`、`webSearchTimeoutSeconds`、`advancedHostedSearch`、`alphaSearch`。
 
-- allowed / blocked domains；
-- approximate user location；
-- `search_context_size`；
-- image search；
-- external web access；
-- return token budget。
+</details>
 
-开启/关闭额外工具会改变 tool catalog，因此默认关闭以保持主会话 request schema 稳定。
+<details>
+<summary><strong>其他安装方式</strong></summary>
 
-### 3. Alpha：`websearch_alpha`
-
-面向 stateful Codex/Alpha 风格搜索：`search/open/find/click/screenshot` 等。只有 capability probe 与当前 endpoint/provider/model/schema 匹配后才注册。
-
-## 安装
-
-### npm
-
-稳定版：
-
-```powershell
-dsh plugin --profile web add dsh-lcx-codex
-```
-
-预发布版（当前 rc.8）：
+**预发布版**
 
 ```powershell
 dsh plugin --profile web add dsh-lcx-codex@next
 ```
 
-### 本地 RC
+**本地 tarball**
 
 ```powershell
 dsh plugin --profile web remove dsh-lcx-codex
@@ -213,49 +172,26 @@ dsh plugin --profile web add .\dsh-lcx-codex-0.4.0.tgz
 dsh web
 ```
 
-不要为了升级删除 `$DSH_HOME/storages/lcx-codex/` 或旧 session。v3 sidecar 仍作为只读旧会话兼容层。
+升级插件时，不要为了“清理”删除 DSH session 或 `$DSH_HOME/storages/lcx-codex/`。旧会话可能仍引用历史兼容数据。
 
-## 推荐设置
+</details>
 
-```text
-Enable plugin                         ✅
-Use GPT Hosted Search                ✅
-Advanced Hosted Search               ❌
-Alpha Search                         ❌
-
-Native V2 remote compaction          ✅
-Native-first auto compaction         ✅
-Native threshold                     90%
-Emergency DSH prune                  95%
-web_search timeout                   240s
-```
+<details>
+<summary><strong>常见情况</strong></summary>
 
-调试 Native 时可以先关闭 fallback；稳定使用时是否开启 fallback 由你决定。
+**`web_search` 没走 GPT Hosted Search**  
+确认插件和 Hosted Search 已启用，并且当前 Agent 能解析到兼容的 GPT `openai-responses` route。
 
-## 部署要求
+**`websearch_alpha` 没出现**  
+这是预期的 fail-closed 行为。Alpha 必须对当前 route/schema 完成可信 capability probe 后才注册。
 
-- 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
-```
+**Native V2 没有生效**  
+确认当前 GPT Responses endpoint 实际支持 `remote_compaction_v2`。插件不会把普通 Basic Compaction 假装成 Native V2 成功。
 
-插件优先复用 DSH route 的 `baseURL`、credential reference、headers 和 retry policy。
+</details>
 
-## 发布通道
-
-- npm stable：正式稳定版本
-- npm `next`：`0.4.0-rc.*` 预发布测试版本
-
-GitHub tag 与 `package.json` version 必须一致；Trusted Publishing workflow 会先跑测试再发布。
-
-## 开发
+<details>
+<summary><strong>开发</strong></summary>
 
 ```bash
 npm test
@@ -263,8 +199,14 @@ npm run test:schema
 npm pack --ignore-scripts
 ```
 
-关键设计说明见 [ARCHITECTURE.md](ARCHITECTURE.md)，完整版本记录见 [CHANGELOG.md](CHANGELOG.md)。
+- 设计与协议细节：[ARCHITECTURE.md](ARCHITECTURE.md)
+- 版本变化：[CHANGELOG.md](CHANGELOG.md)
+- npm：[`dsh-lcx-codex`](https://www.npmjs.com/package/dsh-lcx-codex)
+
+</details>
 
 ## License
 
 MIT
+
+> `LCX` 只是项目名称。本项目是社区项目，不隶属于 OpenAI、DeepSeek、Sub2API 或 NewAPI。