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

package/ARCHITECTURE.md

@@ -9,7 +9,7 @@ DSH 0.1.1-rc.2 `compaction-basic` defaults to a `0.8` pressure threshold and, on
 - provider-confirmed context overflow continues to use DSH's original `context-overflow` recovery unchanged;
 - manual `/compact` remains unchanged.
 
-The pressure wrapper is installed on the actual agent-scoped compaction instance when an agent enters `running`, because DSH's own pre-step listener dynamically dispatches `this.compactIfNeeded()` at event time. The wrapper is restored on plugin cleanup.
+Agent presets may isolate `compaction` and `toolResultPruner` inside entry-local Cordis realms. DSH 0.1.1-rc.2 explicitly documents that these preset services are invisible to both the host and ordinary `agent.ctx`; host-side code must address them through `agentPresets.serviceFor(agent, name)`. LCX therefore observes agent lifecycle events globally, resolves each Agent's real preset-local compaction/pruner through that public resolver, and patches the concrete compaction instance. A root `ctx.inject(['compaction'], ...)` hook remains only for non-preset/non-isolated deployments. Concrete Cordis service identity is used for de-duplication. DSH's own pre-step listener dynamically dispatches `this.compactIfNeeded()` at event time, and the wrapper is restored on plugin cleanup.
 
 ## rc.6 search timeout coordination
 
@@ -17,12 +17,16 @@ The pressure wrapper is installed on the actual agent-scoped compaction instance
 
 # Architecture Notes — 0.4 Native Session Refactor / rc.6 Pressure Coordination
 
+## rc.11 Native cache identity
+
+Native compaction and same-route replay reuse the active DSH/Pi conversation cache identity: the clamped session id is the `prompt_cache_key`, provider `cacheRetention` is respected, and `long` may emit `prompt_cache_retention: 24h` when supported. `cacheRetention: none` omits Native prompt-cache/session affinity. Ordinary Hosted Search remains intentionally isolated under `dsh-lcx-search:<route hash>` so search traffic cannot share the main conversation request/cache namespace.
+
 ## Design invariants
 
 1. **DSH owns compaction policy.** LCX never independently decides threshold, compact range, pruning, transaction boundaries or overflow retries.
 2. **Native success performs one compaction model request.** Basic summary is a failure fallback, not a parallel portable-copy generator.
 3. **DSH session log is the new checkpoint source of truth.** Opaque Native V2 state lives in `compaction/summary.rawOutput`; v3 sidecar access is legacy read-only.
-4. **Opaque state never crosses an incompatible route.** Provider, model, base URL and session ancestry gate native replay.
+4. **Opaque state is same-session only.** Provider, model, base URL and exact `sourceSessionId === currentSessionId` gate Native opaque replay. Verified parent/child ancestry authorizes portable migration only; a fork never sends the parent's opaque checkpoint state.
 5. **Route migration is transparent and transient.** Reconstruct shadowed DSH messages and hand them to the normal adapter; do not persist a second portable history copy.
 6. **Ordinary search has one model tool.** `web_search` is ordinary search; `websearch_gpt_advanced` exists only for parameters absent from `WebSearchRequest`; Alpha remains its own stateful protocol.
 7. **Provider-native wire code is isolated.** Direct `/responses` SSE code is limited to Native V2 compaction/replay and Hosted Search protocol calls.

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # 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
+
+- Promote the fully validated `0.4.0-rc.13` runtime to the stable `0.4.0` line with no functional/runtime code changes.
+- Make the rc.13 Native V2 hardening, canonical Responses replay/serialization fixes, session isolation, cache continuity, and concurrency/lifecycle fixes the recommended stable release.
+- Preserve `0.3.4` only as historical stable state; `0.4.0` becomes the default npm `latest` after publication.
+
+### Validation
+
+- Runtime-sensitive source is required to remain content-identical to the already live-tested rc.13 release.
+- Full suite: 58/58 passed; DSH schema validation: 4/4 passed.
+- Real rc.13 DSH acceptance already covers automatic Native pressure Compact, replay/cache re-warm, restart/resume, real GUI `/compact`, parent/child opaque isolation, and dual-session same-preset ServiceMutex failure cleanup.
+- Stable promotion adds no new runtime behavior; publication is a version/documentation promotion only.
+
+## 0.4.0-rc.13 - 2026-08-23
+
+### Fixed
+
+- Restrict opaque Native checkpoint replay to the exact source DSH session. Parent/child ancestry remains valid only for portable migration, so a fork never sends the parent session's opaque Native state.
+- Reconcile Responses replay deltas and terminal output by stable item/call identity instead of `output_index` alone, preventing changed-index duplicate/empty text blocks and keeping terminal-only function calls balanced.
+- Replace the simplified Native message/tool serializer with the public `@earendil-works/pi-ai@0.82.1` OpenAI Responses converters, preserving reasoning/message identities, tool linkage, constrained-tool semantics, deferred-tool transcript semantics, and DSH image boundaries.
+- Match ordinary Pi `openai-responses` system-prompt placement: Native compact/replay now carries the developer/system prelude inside the canonical input prefix rather than introducing a separate top-level `instructions` prefix difference.
+- Restore strict validation of DSH Pi replay-state envelopes before reusing native signatures; mismatched replay metadata degrades to a portable foreign-assistant projection instead of injecting stale provider-native identity.
+- Treat Pi canonical role-only developer/user items as durable retained history and keep image persistence on `dsh_image_attachment` references rather than request image payloads.
+- Use Pi/model or explicitly configured DSH Responses compatibility only; unknown custom routes no longer assume strict tools, grammar tools, or tool-search support.
+- Mirror DSH/OpenAI Responses generation controls into Native compact/replay (`reasoning` + encrypted-reasoning include, temperature, and max output tokens), preventing the real Terra `xhigh` compact path from dropping the envelope used by ordinary Pi requests.
+- Source automatic-compaction generation controls from the matching session request header rather than the Basic compaction summarizer request, so the selected conversation effort (for example Terra `xhigh`) reaches the Native provider request.
+- Declare the DSH `sessions` service as an explicit Cordis runtime injection because checkpoint/replay and automatic-compaction generation parity read the live session/request header.
+- Maintain a deterministic per-session request-header cache from DSH `session/event`; `compaction/start` synchronously refreshes it from the live Session before the Native request, avoiding reliance on async-context propagation for generation parity.
+- Register that cross-session `session/event` observer with Cordis `{ global: true }`, matching DSH system-wide observers so Agent-carrier session events reach the standing plugin scope.
+- Snapshot the exact `agentArg.session.requestHeader()` inside the Native-first pressure wrapper immediately before delegating to Basic compaction; this is the deterministic pressure-path source of generation controls, with the global session-event cache retained only as a secondary path.
+- Seed the request-header cache from already-live sessions at plugin installation, seed newly announced resume/fork sessions, and evict disposed session entries so manual/non-pressure compaction remains restart-safe without retaining stale headers.
+- Match the explicit Remote V2 tool-control contract used by current Codex and mature Responses compaction implementations: Native compact/replay send `tool_choice: "auto"` and `parallel_tool_calls: true` on the plain `openai-responses` route.
+- Preserve only bounded provider machine diagnostics (`code`, `type`, `param`) from `response.failed`; the safe identifiers are included in the generic failure message/log so DSH compaction history can diagnose failures, while provider messages/bodies remain excluded.
+- Persist Pi replay envelope v2 on successful Native replay finish so DSH retains response id/stop reason plus text/reasoning native metadata across post-compact turns.
+- Preserve normal Pi OpenAI function-call identity as `call_id|item_id` for replay deltas and completed tool-call blocks, preventing loss of the provider `fc_*` item id on the next canonical request.
+- Treat the session header `config` as the effective ordinary-request envelope even when DSH marks a value in `adapterDefaults`; those materialized defaults (for example Terra `xhigh` and `maxTokens`) are still sent by normal Pi and therefore must be mirrored by Native compact/replay.
+
+### Validation
+
+- `tests/rc13-regressions.test.mjs`: 15/15 passed.
+- Full local suite: 58/58 passed; DSH schema validation: 4/4 passed; `git diff --check` passed.
+- Installed DSH/NewAPI acceptance passed on Terra xhigh: automatic 90% Native V2 compact, continuous replay/cache re-warm, DSH Web restart/resume, real GUI `/compact` plus continuation, and parent→child fork portable isolation all completed without pre-Native stock prune or cross-session opaque replay.
+- This remains a local release candidate only; no npm/GitHub publication or tag is implied.
+
+## 0.4.0-rc.12 - 2026-08-22
+
+### Fixed
+
+- Serialize every `compactIfNeeded()` call per concrete preset compaction service so same-generation sessions cannot observe each other’s temporary Native-first pruner/config state; queued calls are abortable and plugin cleanup drains active owners before restoring the original method.
+- Align Native `openai-responses` session affinity with the active Pi adapter: default OpenAI-format routes use `session_id` plus `x-client-request-id`, while OpenRouter-format routes use `x-session-id`; explicit affinity headers remain authoritative.
+- Restrict Basic fallback to allowlisted retryable first-checkpoint failures and fail closed once a Native/legacy checkpoint already exists.
+- Require a real `response.completed` terminal event with `status=completed` for Native compaction/replay and reject orphan `function_call_output` items.
+- Set credential-bearing fetches to `redirect: error` and keep provider response bodies/messages out of surfaced/logged transport errors.
+
+## 0.4.0-rc.11 - 2026-08-22
+
+### Fixed
+
+- Restore ERR-051 cache/session affinity semantics that regressed in the rc.8 refactor: Native V2 compaction and same-route replay now use the DSH/Pi conversation session id as the clamped `prompt_cache_key` instead of a route fingerprint, inherit the active provider `cacheRetention`, emit `prompt_cache_retention: 24h` only for supported `long` retention, and omit Native cache affinity when retention is `none`.
+- Keep ordinary Hosted Search on its intentionally separate `dsh-lcx-search:<route hash>` namespace.
+
+## 0.4.0-rc.10 - 2026-08-22
+
+### Fixed
+
+- Fix Native-first pressure coordination for DSH 0.1.1-rc.2 Agent presets by using the public `agentPresets.serviceFor(agent, name)` resolver for preset-local `compaction` and `toolResultPruner` instances. This replaces the rc.9 assumption that ordinary `agent.ctx` lookup could see entry-local isolated services.
+
+## 0.4.0-rc.9 - 2026-08-22
+
+### Fixed
+
+- Restore the Alpha capability/ref-store interfaces consumed by `lib/index.js`; the rc.8 release package could pass its unit tests but fail immediately at module import with missing `AlphaCapabilityStore` / `AlphaRefStore` exports.
+- Add package-entry import regression coverage so CI fails when the server entry point and internal module exports drift out of sync.
+- Restore Native-first pressure coordination for isolated agent presets using DSH 0.1.1-rc.2's public `agentPresets.serviceFor(agent, name)` resolver. Preset-local `compaction` / `toolResultPruner` services are not visible through ordinary host or `agent.ctx` lookup; the plugin now addresses the actual per-Agent instances before applying the 90% Native / 95% emergency policy. A root service-lifecycle hook remains for non-preset deployments.
 ## 0.4.0-rc.8
 
 - Rebase the plugin on DSH `0.1.1-rc.2`; older DSH releases are no longer a supported runtime target.

package/README.md

@@ -1,261 +1,197 @@
 <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
-dsh plugin --profile web add .\dsh-lcx-codex-0.4.0-rc.8.tgz
+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。