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

package/ARCHITECTURE.md

@@ -0,0 +1,89 @@
+
+## rc.6 pressure coordination
+
+DSH 0.1.1-rc.2 `compaction-basic` defaults to a `0.8` pressure threshold and, once pressure qualifies, runs `toolResultPruner` before summary compaction. Real long-session traces showed that a large prune can reduce the measured surface below 80%, preventing the Native summarizer from running while still rewriting an old request prefix and invalidating cache. rc.6 coordinates the existing engine instead of replacing it:
+
+- for a compatible GPT Responses route with Native auto-compaction enabled, `compactIfNeeded(..., "pressure")` returns `null` below the configured Native threshold (default 90%), so the stock 80% path does not mutate history;
+- from 90% up to the emergency threshold, the existing engine still owns range selection and the durable transaction, but `toolResultPruner.pruneSession()` is temporarily suppressed for that call; the engine's summary transport therefore reaches the existing `purpose=compaction` Native V2 override first;
+- at the emergency threshold (default 95%) or above, the pruner is no longer suppressed and DSH may shrink oversized tool results before attempting summary compaction;
+- 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.
+
+## rc.6 search timeout coordination
+
+`dsh-tool-web` stores the cooperative search deadline only in `ToolDefinition.timeoutMs`; timeout metadata is explicitly not sent to the model. rc.6 adjusts the visible `web_search` definition's timeout to 240 seconds by default and restores the original value on cleanup. This avoids the observed 60-second false timeout while leaving the model-visible tool schema byte-stable.
+
+# Architecture Notes — 0.4 Native Session Refactor / rc.6 Pressure Coordination
+
+## 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.
+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.
+
+## Why not subclass `BasicCompactionEngine`
+
+`BasicCompactionEngine.summarize()` is the intended subclass customization hook, but a subclass is a new `ctx.compaction` service provider. The shipped DSH profile already mounts `dsh-compaction-basic`; mounting a second engine would duplicate service ownership/listeners unless the profile explicitly replaces the existing row.
+
+The stock summarizer already routes through `ctx.llm.stream({ purpose: 'compaction' })`. For an out-of-tree optional plugin that must install without rewriting the base profile, narrowly intercepting that purpose is the less invasive integration.
+
+If DSH later adds a public **summarizer provider registry** (distinct from the compaction engine service), LCX should migrate to it.
+
+## Why not inline opaque JSON in checkpoint text
+
+Inlining `encrypted_content` makes the session self-contained, but also exposes a large opaque string to DSH's visible surface/token accounting. Using a non-text block in `compaction/summary.rawOutput` keeps the session self-contained without turning provider state into prompt text.
+
+## Remaining deliberate low-level seams
+
+### Native Responses replay
+
+Generic DSH/Pi messages do not expose an input type for OpenAI `compaction` items. Same-route resume therefore builds the Responses request directly. This is a bounded compatibility adapter, not a second general LLM stack.
+
+### Runtime Web SearchProvider selection
+
+DSH 0.1.1-rc.2 pins `deepseek-official` and has no public live setter. LCX uses an isolated compatibility write to the 0.1.1-rc.2 runtime field so the settings toggle works without restart. A future DSH public setter/configuration hook should replace this shim.
+
+## Cache expectations
+
+- Stable ordinary tool schema improves prefix stability versus exposing two ordinary search tools.
+- Enabling/disabling Advanced or Alpha changes tools and may reset provider prefix cache.
+- Compaction necessarily changes visible history and therefore starts a new post-checkpoint prefix.
+- `prompt_cache_key` remains stable per exact route/session across Native compaction and native replay.
+- Remote-first avoids an otherwise redundant large-prefix local summary call.
+
+## Native V2 retained-history invariant
+
+Current Codex V2 retains selected client messages and appends the opaque compaction item. Real DSH testing showed an additional product-level fidelity problem: a low-salience fact that existed only in an assistant answer can be omitted by the opaque state. LCX rc.5 therefore keeps the Native ordering but adds a bounded assistant-visible protection layer:
+
+```text
+selected user/developer/system message items
++ selected assistant visible output_text items
+→ opaque compaction item
+→ later DSH-retained / post-compaction messages
+```
+
+The fidelity prefix is capped at an estimated 64k tokens total. Up to 24k is reserved for assistant-visible answers; each retained assistant answer is capped at about 3k tokens. Assistant copies deliberately exclude reasoning, response IDs, tool calls, tool outputs, and provider-private state. The opaque item remains the only durable representation of those process details.
+
+The DSH surface still stores only the short checkpoint marker. The retained wire items and opaque compaction state remain log-only in `compaction/summary.rawOutput`, so they do not inflate DSH's visible token-meter surface. They do, intentionally, increase the post-compaction provider request relative to an opaque-only checkpoint; the total explicit retention ceiling prevents this protection from defeating compaction.
+
+Compatibility:
+
+- `0.4.0-rc.3`: v4 checkpoint could contain only the opaque item.
+- `0.4.0-rc.4`: v4 checkpoint retained client messages but not assistant-visible answers.
+- `0.4.0-rc.5`: writes `lcx-native-compaction-v5`; when replaying a v4 checkpoint it reconstructs the shadowed DSH transcript and derives the v5 fidelity prefix before reusing the original opaque state.
+
+
+
+## rc.7 active-Agent Hosted Search routing
+
+DSH intentionally keeps `SearchProvider.search()` small: the provider receives the normalized search request and cancellation signal, not the calling Agent. Ordinary Hosted Search still needs the exact active GPT Responses route, especially when a user switches between Sol/Luna or multiple proxy routes.
+
+rc.7 therefore captures route identity at the model-facing `tools/execute` boundary for `web_search` and propagates it through Node `AsyncLocalStorage` only for the lifetime of that tool execution. `LcxResponsesSearchProvider.search()` resolves the route from that async context and falls back to the plugin-configured route only when no compatible active Agent route exists. No fields are added to the DSH `web_search` schema.
+
+Hosted Search uses a dedicated stable cache namespace (`dsh-lcx-search:<route fingerprint>`) rather than the Native replay namespace (`dsh-lcx:<route fingerprint>`). The two requests have different prefixes and should not be intentionally co-routed under one prompt-cache key.

package/CHANGELOG.md

@@ -1,65 +1,106 @@
 # Changelog
 
-本项目遵循语义化版本。未通过真实验收的能力只记录在Unreleased，不作为已发布功能。
+## 0.4.0-rc.8
 
-## Unreleased
+- Rebase the plugin on DSH `0.1.1-rc.2`; older DSH releases are no longer a supported runtime target.
+- Native V2 compaction image replay now uses DSH `attachments.readImageRequest()` with the active `llm-pi-ai` route's request-image pixel/byte policy instead of reading normalized master bytes directly.
+- Native image requests use DSH's deterministic `offloadRequestImagesWithPolicy()` projection before serialization, matching the current request-size behavior for long image-heavy sessions.
+- Keep rc.7 active-Agent Hosted Search routing, isolated search cache namespace, 240s search timeout, rc.5 conversation-fidelity checkpointing, and rc.6 90% Native-first / 95% emergency pressure policy unchanged.
+- CI installs against current declared DSH packages instead of enforcing the stale rc.8 lockfile.
 
-## 0.3.3 - 2026-08-21
+## 0.4.0-rc.7 - 2026-08-22
 
 ### Fixed
 
-- Native V2 checkpoint 现在由客户端按 64K token 预算保留最近真实 user messages，再追加 exactly-one compaction item；不再错误假设上游 `response.output` 会返回 retained messages。旧的 compaction-only v3 checkpoint 会从 portable history 安全补全，运行时上下文注入不会进入 replacement history。
+- Ordinary DSH `web_search` now follows the active Agent `provider/model` instead of always using the plugin fallback GPT model. A Luna conversation now searches with Luna; a Sol conversation searches with Sol.
+- Added an AsyncLocalStorage route bridge at the DSH `tools/execute` boundary so the provider-only `ctx.web.search()` seam can receive Agent route context without changing the model-visible `web_search` schema.
+- Hosted Search now uses a separate stable `dsh-lcx-search:<route hash>` `prompt_cache_key`, avoiding intentional cache-key sharing with Native conversation replay.
+- The settings UI now labels the configured Responses endpoint/model as **fallback** values, matching their actual rc.7 role.
 
-### Documentation
+### Kept from rc.6
 
-- 记录 installed `0.3.2` 的 compact + 三次 replay 缓存实测，并说明 Sub2API Codex OAuth 路径会删除上游不支持的 `prompt_cache_retention`；短缓存过期后的单次冷请求不等于插件改变了稳定前缀。
-- 增加连续 replay 的前缀稳定性回归断言，区分缓存生命周期与 replacement-history 保真问题。
+- 240-second default DSH `web_search` deadline.
+- Native-first automatic pressure policy: 90% Native V2, 95% emergency DSH prune.
+- rc.5 conversation-fidelity checkpoints and restart-safe DSH session-log persistence.
 
-## 0.3.2 - 2026-08-21
+### Docs / release
 
-### Fixed
+- Reworked the README around the current architecture and real cache observations.
+- Added a blue/white DSH-LCX-CODEX hero banner for GitHub/npm.
+- GitHub trusted publishing is wired through `.github/workflows/publish.yml`: pre-release tags publish to npm dist-tag `next`; stable tags publish to `latest`.
 
-- Native V2 compact 与同路由 replay 现在和 DSH/Pi 普通 Responses 请求复用相同的 session `prompt_cache_key`、缓存 retention 与会话 header，避免压缩边界额外切换 NewAPI/Sub2API 的缓存和账号粘性域；`cacheRetention: none` 时同时省略这些缓存信号。
-- 移除未被插件直接导入或注入的 `@deepseek-ai/dsh-compaction-basic` peer 声明，避免 DSH/pnpm 安装时出现误导性的宿主依赖警告；Basic fallback 继续通过 DSH `llm/stream` 的 `next()` 链调用宿主实现。
+## 0.4.0-rc.6
 
-## 0.3.1 - 2026-08-21
+- Added Native-first automatic pressure coordination for GPT Responses sessions: below the configured Native threshold the plugin suppresses DSH's stock 80% pressure compaction/prune path; at the default 90% threshold it lets compaction proceed while temporarily suppressing tool-result pruning so Native V2 runs first.
+- Added a separate emergency prune threshold (default 95%). At or above this zone, DSH's replay-safe tool-result pruner is allowed to run before compaction as overflow protection.
+- Added adjustable `web_search` tool deadline, default 240 seconds (30–600s). This mutates only DSH's non-model-visible `ToolDefinition.timeoutMs`, so the model tool schema and prompt-cache prefix do not change.
+- Added Settings UI controls for automatic compaction, Native threshold, emergency prune threshold, and web search timeout.
+- Kept the rc.5 checkpoint/fidelity format unchanged (`lcx-native-compaction-v5`); rc.6 is a pressure/timeout coordination release, not another checkpoint migration.
 
-### Fixed
+## 0.4.0-rc.5
 
-- 删除未被 DSH 官方识别、且错误写死旧域名与 `LCX_API_KEY` 的 `dshhub` 权限块；README 改为声明网络目标和凭据由当前 `openai-responses` provider 动态决定。
-- 添加 npm 与 DSH 社区检索使用的标准关键词，其中包括 `dsh-plugin` GitHub topic 对应关键词。
-- 新增独立英文用户文档 `README_EN.md`，并与中文 README 互相链接。
+- Adds a bounded conversation-fidelity layer after real DSH testing showed assistant-only facts could be lost by opaque Native V2 compaction.
+- New `lcx-native-compaction-v5` checkpoints retain selected user/developer/system messages plus user-visible assistant final answers before the opaque compaction item.
+- Keeps explicit retained history within an estimated 64k-token ceiling; defaults reserve at most 24k for assistant answers and cap one retained answer at about 3k tokens.
+- Does not copy reasoning, tool calls/results, raw search payloads, or telemetry into the fidelity prefix.
+- Repairs rc.3/rc.4 v4 checkpoints from append-only `shadowedSeqs`, including assistant-visible answers when the original DSH events still exist.
+- Stores only the single opaque compaction output item, ignoring unrelated terminal output items from nonstandard proxies.
+- Route compatibility now accepts both native checkpoint versions 4 and 5.
+- Adds regression coverage for the exact assistant-only anchor failure (`Cobalt-Sparrow-604` / `81736`) and the 64k retention ceiling.
 
-## 0.3.0 - 2026-08-21
+## 0.4.0-rc.4
 
-### Changed
+- Fixes a Native V2 replay fidelity bug found by real DSH session-log testing.
+- Native checkpoints now persist the retained client-authored Responses messages before the opaque `compaction` item, matching current OpenAI Codex remote-compaction V2 replacement-history semantics.
+- Existing rc.3 opaque-only v4 checkpoints are repaired on replay by reconstructing the missing shadowed user history from the DSH append-only session log.
+- Adds replay/retention regression coverage and an explicit Native success diagnostic.
+- Keeps the rc.3 search-provider, remote-first fallback, and session-log-native checkpoint architecture unchanged.
 
-- 收紧 npm/DSH 安装包，只保留运行时代码、Alpha 运维探针、许可证和用户文档；开发测试与 schema 校验脚本继续保留在源码仓库。
-- README 和包元数据明确 `LCX` 只是插件名称；支持 Sub2API 反代或 NewAPI 中转的 GPT 模型，不隶属于 OpenAI；Alpha 能力继续按部署 fingerprint 与可信 provenance 分类，不作全局 native 承诺。
-- 明确 Alpha 经过 NewAPI 时渠道类型必须为 `Sub2API`，不能使用普通 `OpenAI` 渠道。
-- README 改为面向用户的中文文档，提供经 DSH/pnpm 帮助核对的 GitHub URL、Release 包、更新和卸载命令；本地 `link:` 安装明确归入源码开发流程。
+## 0.4.0-rc.3
 
-### Added
+- Fix Cordis external-package loading: all `ctx.web`/`ctx.llm` service access now occurs inside an explicit `ctx.inject(['llm', 'web'], ...)` scope.
+- This fixes `cannot get property "web" without inject` when DSH loads the plugin from a profile-installed `.tgz`.
+- No protocol or checkpoint-format changes from rc.2.
 
-- Hosted Search 完整结构化参数与 citation/source/image 输出。
-- 独立 `websearch_alpha`，支持 search、image、open/find/click、PDF screenshot、finance、weather、sports 和 time；capability/ref sidecar 按 route 与 session 隔离。
-- Native V2 checkpoint v3、同路由 replay、Sol/Luna portable migration、fork/tree/restart generation lease 与 durable-image migration。
+## 0.4.0-rc.2 - 2026-08-21
 
-### Fixed
+- Packaging-only fix over rc.1: remove unnecessary `@deepseek-ai/dsh-compaction-basic` and `@deepseek-ai/dsh-web` peer declarations.
+- The plugin consumes DSH runtime services through injected `ctx.*` seams and does not import or mount either package directly.
+- Avoids misleading pnpm "missing peer" warnings and, importantly, avoids encouraging users to install a second compaction backend.
+
+## 0.4.0-rc.1 - 2026-08-21
+
+### Architecture
+
+- Keep DSH `compaction-basic` as the sole compaction service owner; use only its documented/interceptable `purpose=compaction` `llm/stream` summarizer seam.
+- Replace parallel local+remote compaction with remote-first fallback.
+- Persist new Native V2 opaque state in DSH `compaction/summary.rawOutput` using `lcx-native-compaction-v4`; the model-visible replacement stays short.
+- Remove new-checkpoint writes to the v3 JSON sidecar. The v3 sidecar is now read-only compatibility for old sessions.
+- Reconstruct portable history for route migration from DSH append-only `shadowedSeqs` instead of duplicating every checkpoint's portable history.
+- Preserve same-route fork replay through DSH session ancestry.
+- Centralize the remaining direct Responses-native transport in `compact-v2.js` and `responses-replay.js`.
+
+### Search
+
+- Make `ctx.web` / DSH `web_search` the ordinary Hosted Search entry point.
+- Remove the ambiguous ordinary `websearch_gpt` tool.
+- Add opt-in `websearch_gpt_advanced` for Hosted-only controls that DSH `WebSearchRequest` cannot express.
+- Keep `websearch_alpha` independent and capability-gated.
+- Isolate the DSH rc.8 runtime SearchProvider-selection compatibility shim.
+
+### Reliability
+
+- Rehydrate DSH image attachment references when replaying legacy v3 checkpoints.
+- Resolve startup settings into runtime route config immediately instead of waiting for the first settings change.
+- Do not assume `events[seq]` is always the event whose `event.seq === seq`; use a safe fallback lookup.
+- Add protocol, session persistence, migration and architecture regression tests.
+
+### Compatibility
+
+- Node.js >= 20.
+- Target DSH `0.1.1-rc.2` only.
+- Existing 0.3.x v3 marker sessions remain best-effort readable through the old sidecar.
+
+## 0.3.1
 
-- Hosted Search 与 Alpha Search 现在和 Native V2 Compact 一样，复用 DSH 已添加的 `openai-responses` provider 路由、凭据引用、headers 与 retry policy；不再要求用户为插件重复配置 `LCX_API_KEY`。
-- README 将插件运行时凭据与运行在 DSH 外的 Alpha 探针/E2E 测试凭据明确分开。
-- README 改为简短的用户手册，以 npm 安装为主；Alpha 提示前置，并按 NewAPI 当前源码区分 4 种中转渠道类型与 Sub2API 直连，共 5 种部署路径。
-- Native replay and portable migration no longer depend on the nonexistent `GenerateOptions.branchId`; fork safety uses public session ancestry and derived marker history while preserving existing v3 fingerprint compatibility.
-- README 的本地 link 安装示例不再包含开发机绝对路径。
-- Alpha 从 rc.8 公共 `session.requestContext()` 读取 active route，避免模型切换后的 capability 误判。
-- Alpha 对 HTTP 200 内的函数调用语义错误 fail closed，并修正 sports action 的 wire 字段。
-- Responses SSE 去重、usage、工具配对、并发 sidecar、Windows ACL、图片 offload/hydrate 和 remote/local summary 边界。
-
-## 0.2.0
-
-- Hosted Responses query-only Web Search。
-- Native Remote Compaction V2，拒绝legacy transport。
-- checkpoint v3、同route replay和第一批portable model migration。
-- 图片同route attachment hydrate，portable image migration保持fail closed。
-- 协议、大小、超时、重试、redirect和日志脱敏基础测试。
+- Previous Hosted/Alpha Search and Native V2 checkpoint-v3 implementation.

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.8.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