dsh-lcx-codex 0.4.3-pre.3 → 0.4.3

package/README.md

@@ -4,156 +4,125 @@
 
 # LCX Codex
 
-**为 DeepSeek Harness 中的 GPT 提供 Responses 生命周期能力，并为 Grok 接入原生 Web / X Search。**
+**让 DeepSeek Harness 里的 GPT 与 Grok 更适合长任务、联网搜索和连续工作。**
 
-[![npm prerelease](https://img.shields.io/npm/v/dsh-lcx-codex/prelatest?label=prelatest)](https://www.npmjs.com/package/dsh-lcx-codex)
-[![DSH](https://img.shields.io/badge/DSH-0.1.3--alpha.2-16803c)](#安装)
+[![npm](https://img.shields.io/npm/v/dsh-lcx-codex?label=latest)](https://www.npmjs.com/package/dsh-lcx-codex)
+[![DSH](https://img.shields.io/badge/DSH-0.1.5--rc.1-16803c)](#安装)
 [![License](https://img.shields.io/badge/license-MIT-555)](LICENSE)
 
 **简体中文** · [English](README_EN.md) · [更新日志](CHANGELOG.md) · [问题反馈](https://github.com/kk3ya03-star/dsh-lcx-codex/issues)
 
 </div>
 
-LCX Codex 是 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness)（DSH）的社区插件。它按当前模型启用对应能力：GPT 可使用远程原生压缩、Hosted / Alpha Search；Grok 可直接使用 xAI Responses 的原生 `web_search` 与 `x_search`。其他模型继续走 DSH 原生路径。
+LCX Codex 是 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness)（DSH）的社区插件。
 
-模型、接口、API Key / credential、会话和工具仍由 DSH 管理，不需要在插件里再配置一遍。GPT 与 Grok 的功能开关彼此独立；当前 Grok 原生搜索支持 API Key / API 网关调用，不包含 xAI OAuth / SuperGrok 登录。
+它不会替代 DSH，也不需要你重新配置模型、接口或 API Key。模型、凭据、会话和工具仍由 DSH 管理；LCX 只在需要时为 GPT 和 Grok 增加额外能力。
 
-## 安装
-
-本页对应 **`0.4.3-pre.3` 预发布版**，适配 **DSH `0.1.3-alpha.2`**。稳定版仍为 `0.4.2`，使用旧版 DSH `0.1.1-rc.2` 的用户请看[稳定版说明](https://github.com/kk3ya03-star/dsh-lcx-codex/blob/v0.4.2/README.md)。
-
-安装前，请确认 DSH Web 能正常启动，并已配置需要使用的 GPT Responses 或 Grok Responses API 路由。Node.js 要求 `^22.19.0 || >=24.0.0`；Windows 启动出现 `fs-ext` 报错时，先看下方[故障排查](#故障排查)。
-
-```sh
-dsh plugin --profile web add dsh-lcx-codex@0.4.3-pre.3
-dsh web
-```
+## 你可以用它做什么
 
-以后升级预发布版，可执行 `dsh plugin --profile web add dsh-lcx-codex@prelatest`。不带版本或标签安装会得到稳定版，**不是本页介绍的新版本**。
-
-**从 `0.4.2` 升级：** 旧插件配置和 v3/v4 压缩检查点不再兼容，请重新配置插件并新建会话。新版 v5 GPT 检查点仍支持重启续聊。
-
-## 启用
-
-打开 DSH Web 的插件设置，展开 **Responses / Codex 能力**，按需打开开关并保存：
-
-| 开关 | 什么时候开 |
+| 能力 | 适合场景 |
 | --- | --- |
-| 启用 LCX | 使用 GPT Responses 生命周期、Native V2 压缩及 GPT 搜索能力时。 |
-| GPT Hosted Search | 当前模型是 GPT，且需要普通联网查询时。 |
-| 高级 Hosted 工具 | GPT 需要搜图、限定网站或使用其他 Hosted 搜索条件时。 |
-| Alpha | GPT 需要连续 `open / find / click / screenshot` 网页操作时，属于实验功能。 |
-| Grok 原生 Web Search | 当前模型是 Grok，并希望使用 xAI 服务端原生网页搜索时。 |
-| Grok 原生 X Search | 当前模型是 Grok，并希望直接搜索 X 内容时。 |
-
-**六个开关默认均关闭。** GPT 四项由“启用 LCX”控制；Grok 两项独立，不要求打开 GPT 的 LCX 主开关。模型、推理等级、图片输入、endpoint 与 credential 都继续在 DSH 的模型/provider 配置中管理。
-
-模型切换不需要重启插件：
+| GPT 联网搜索 | 让 GPT 直接通过 DSH 的 `web_search` 查询网页。 |
+| GPT 高级搜索 | 搜图片、限定网站、加入位置等额外搜索条件。 |
+| Grok 原生 Web / X Search | 直接使用 xAI Responses 的 Web Search 和 X Search。 |
+| 长对话压缩 | GPT 长任务接近上下文上限时自动尝试远程压缩，并继续当前会话。 |
+| 搜索媒体预览 | 在回答下方直接预览可用的图片和视频链接。 |
+| Alpha 网页操作 | 实验性连续网页阅读能力，适合需要进一步打开、查找页面内容的任务。 |
 
-- GPT → 只启用已打开的 GPT / LCX 能力；
-- Grok → 只启用已打开的原生 Web / X Search；开启任意 Grok 原生搜索时，该请求不会同时暴露 DSH `web_search`，但 `web_fetch` 和其他 DSH/MCP 工具仍可用；
-- Claude、Gemini、DeepSeek 等其他模型 → 保持 DSH 原生会话、搜索、工具和压缩行为。
+其他模型继续使用 DSH 原生路径，不会因为安装 LCX 而被接管。
 
-## 搜索与搜图
-
-### GPT 联网查询
-
-GPT 普通查询沿用 DSH 的单一 `web_search` 工具入口；开启 **GPT Hosted Search** 后，LCX 按当前 GPT Responses route 执行 Hosted Search。需要域名、位置、search context 或图片等额外参数时，可启用 `websearch_gpt_advanced`。
+## 安装
 
-例如：
+当前稳定版：**`dsh-lcx-codex@0.4.3`**
 
-> 只搜索 Python 官方文档，查找 asyncio.TaskGroup 的用法。
+兼容环境：
 
-### Grok 原生 Web / X Search
+- DSH `0.1.5-rc.1` 起的 `0.1.5` 系列（当前完整验证基线：`0.1.5-rc.1`）
+- Node.js `^22.19.0 || >=24.0.0`
 
-Grok 使用 xAI Responses 的服务端工具，而不是把搜索包装成 DSH function tool：
+安装：
 
-```text
-{ type: "web_search" }
-{ type: "x_search" }
+```sh
+dsh plugin --profile web add dsh-lcx-codex@0.4.3
+dsh web
 ```
 
-开启任意 Grok 原生搜索后，Grok 请求会移除 DSH `web_search`，避免重复搜索语义；`web_fetch`、`read` 及其他 DSH/MCP function tools 仍保持可用。原生搜索结果可以继续进入本地工具调用，再回到同一 Grok agentic workflow；插件会保存 xAI 必需的 provider-native replay state，但不会把服务端搜索伪装成 DSH 本地工具调用。
-
-当前支持 **API Key / API Gateway** 路由；OAuth / SuperGrok / X Premium 订阅登录不在本版范围内。搜索来源 URL 会尽量保留，但具体 citation 展示形式仍受上游兼容网关返回格式影响。
+后续稳定版更新可以使用：
 
-### GPT 搜索图片并显示
-
-开启高级 Hosted 工具后，可以这样说：
+```sh
+dsh plugin --profile web add dsh-lcx-codex@latest
+```
 
-> 搜索金门大桥的照片，选一张直接显示在回复里，并附上来源网页。
+不指定版本或使用 `@latest` 都会安装当前稳定版。需要预发布版本时可使用 `@prelatest`；`0.4.3-pre.13` 作为本次正式版之前的已验证预发布历史继续保留。
 
-**不需要自己填写 JSON 参数。** 模型负责选择图片搜索参数；如果只返回文字，可以补充“请使用高级 Hosted 的图片搜索，并把图片显示出来”。
+本版已在官方 DSH `0.1.5-rc.1` 完整验证。后续同一 `0.1.5` 系列版本可以直接安装并进行兼容评估，不再需要仅因为 RC 版本号变化而发布新的 LCX 版本。
 
-搜索工具提供图片链接与来源，DSH 用现有的 Markdown 渲染器显示图片。这是**搜索已有图片，不是生成图片**，也不代表模型已经读取了图片像素。图片能否显示还取决于原站链接是否可访问。
+## 启用功能
 
-### Alpha 网页操作
+打开 DSH Web 的插件设置，找到 **Responses / Codex 能力**。
 
-`websearch_alpha` 支持 `search / open / find / click / screenshot` 等动作，用于 GPT 连续查阅网页。它操作的是**上游搜索服务中的网页内容**，不会操作你的本机浏览器或 DSH 界面。
+### 使用 GPT
 
-Alpha 需要单独开启，且接口通过能力探测后才会出现。目前网页引用仍可能偶发失效，`screenshot` 尚未验证能返回可显示的图片。**日常 GPT 搜索/搜图和 Grok 原生搜索都不需要开启 Alpha。**
+通常打开：
 
-## 长对话与压缩
+1. **启用 LCX**
+2. **GPT Hosted Search**（需要联网时）
 
-开启 LCX 后，插件将 DSH 的压缩请求交给上游 GPT 接口执行 **Native V2 远程原生压缩**，再将结果接回当前会话。会话保存、工具执行和压缩事务仍由 DSH 负责。
+按需再打开：
 
-| 上下文占用 | 处理方式 |
-| --- | --- |
-| 低于 `90%` | 正常对话，不提前裁剪工具结果。 |
-| `90%` 至 `95%` | 优先尝试远程原生压缩。 |
-| 达到 `95%` | 允许 DSH 紧急裁剪工具结果，再按流程压缩。 |
+- **高级 Hosted 工具**：需要图片搜索、限定域名、位置等高级搜索条件时使用；它依赖 GPT Hosted Search。
+- **Alpha**：实验性网页连续操作。日常联网搜索不需要开启。
 
-也可以输入 `/compact` 手动压缩。这些阈值是固定策略，不需要额外设置；实际能否压缩取决于是否有可压缩的历史以及接口支持情况。
+### 使用 Grok
 
-压缩后可以继续对话、重启恢复或切换 GPT 模型。遇到不兼容的模型或接口配置时，插件改用可迁移的历史，不会强行复用原生状态。首次建立检查点时，部分可恢复失败可以回退到 DSH 基础压缩；并非所有失败都会回退。
+Grok 原生搜索与 GPT 的 LCX 主开关相互独立：
 
-## 缓存
+- **Grok 原生 Web Search**：搜索网页。
+- **Grok 原生 X Search**：搜索 X 内容。
 
-缓存由上游服务实现，插件只负责保持与当前 provider 兼容的缓存/session identity。
+开启 Grok 原生搜索后，LCX 会使用 xAI 的服务端搜索能力，同时保留页面读取和其他 DSH / MCP 工具。
 
-- **GPT**：延续 LCX 既有策略；前台会话与其子代理可共享父会话的 prompt-cache identity，以复用公共请求前缀。真正的 DSH Session、工具执行与私有历史仍各自独立。
-- **Grok**：严格跟随 DSH/Pi 原生语义；每个前台/子代理使用自己的 DSH Session ID 作为 prompt cache / session affinity identity，sibling 子代理不会共享 opaque replay state。
+### 搜索媒体预览
 
-Pi `0.85.1` 的显式缓存模式支持 `30m` 长保留参数；`cacheRetention=none` 时不发送 prompt cache key。压缩、切换模型或改变工具列表后，缓存可能需要重新建立。
+**搜索媒体预览**可以独立开启。它只改变回答的显示方式，不会修改模型提示词、搜索请求、聊天历史或缓存。
 
-## 故障排查
+可识别的图片会显示缩略图并支持放大；直接视频链接可以点击播放。媒体加载失败时，原来的文字和链接仍会保留。
 
-**DSH 在 Windows 启动时报 `fs-ext` 错误？**
+## 常见用法
 
-DSH `0.1.3-alpha.2` 会在启动时加载 `fs-ext`，即使 Windows 实际不使用它。当它的原生模块不可用时，DSH 会在启动阶段退出。这是 **DSH 的依赖加载问题，不是插件压缩或会话锁损坏**。
+直接像平时一样和模型说话，不需要手写工具参数。例如：
 
-本版 Windows 实测使用了一个最小 DSH 修正：仅在非 Windows 平台加载 `fs-ext`，保留原有 Win32 会话锁。插件不会自动修改 DSH；未经该修正的 Windows 环境不保证能启动。不要用关闭会话锁来绕过问题。
+> 搜索 Python 官方文档，告诉我 `asyncio.TaskGroup` 应该怎么用。
 
-**安装后没有变化？**
+> 搜索几张金门大桥的照片，显示一张，并给我来源网页。
 
-检查安装和启动是否使用同一个 `web` 配置，并确认对应模型的开关已保存。GPT 主开关与 Grok Web/X 开关彼此独立。
+> 用 Grok 搜一下 X 上最近关于这个项目的讨论。
 
-**对话正常，但搜索或压缩失败？**
+长任务也不需要自己盯着上下文。启用 LCX 后，兼容的 GPT 路由会在对话变得很长时自动尝试远程压缩并继续工作；你也可以使用 `/compact` 手动压缩。
 
-普通 Responses 对话可用，不代表接口同时支持 Native V2、Hosted/Alpha 或 Grok 原生 Web/X Search。请确认当前通道提供对应服务端能力；Sub2API、NewAPI 或其他网关名称本身不是能力保证。
+## 兼容性与已知限制
 
-## 版本与验证范围
+- `0.4.3` 的当前完整验证基线是 DSH `0.1.5-rc.1`。同一 `0.1.5` 系列后续版本处于可安装、可评估范围，但仍会单独记录兼容验证结果；`0.1.6` 及更高版本不会自动视为兼容。
+- 从较旧的 LCX / DSH 版本升级时，建议新建会话；旧版保存的压缩状态不保证兼容。
+- Grok 原生搜索支持 API Key / API 网关路由；xAI OAuth / SuperGrok 登录不在当前范围。
+- Alpha 仍是实验功能。搜索可以正常使用，但连续 `open / find` 等操作在部分路由上仍可能失败；截图也不保证能作为可显示图片返回。
+- 修改 DSH profile 中的插件启用状态后，已经打开的浏览器页面可能需要刷新。
+- 不同 API 网关支持的能力可能不同。普通聊天可用，不代表搜索、长对话压缩或 Alpha 等功能也一定可用。
 
-本版使用 DSH `0.1.3-alpha.2`、DSH host Pi `0.85.1` 和插件 Pi `0.85.1`。插件单独声明 Pi 依赖，不替换 DSH 的依赖。
+## 遇到问题
 
-发布前完整测试为 **237/237 PASS**，strict host/client typecheck 与 4 个 DSH schema 均通过。真实运行覆盖 GPT Hosted/Native V2 回归、DeepSeek 原生 DSH 搜索回归，以及 Grok 4.5/4.6 原生 Web/X Search、Web/X → 本地 `read` → continuation、provider-native replay、完整 DSH 重启后的续聊、Grok 父/子代理 session/cache 隔离。GPT 已验证的父 cache-sharing 策略保持不变。
+**安装后看不到变化**：确认安装和启动使用的是同一个 `web` profile，并检查对应功能开关是否已经保存。
 
-仍需保留的预发布限制：Windows DSH `0.1.3-alpha.2` 的 `fs-ext` 启动问题需要文档中的最小 host loading 修正；Alpha 引用及 screenshot 展示、代理/NO_PROXY、更广的并发/取消和后台 continuable subagent 矩阵仍未全面覆盖；Grok OAuth 不支持，citation 渲染仍可能受上游网关格式影响。详细变更见 [v0.4.3-pre.3 发布说明](https://github.com/kk3ya03-star/dsh-lcx-codex/releases/tag/v0.4.3-pre.3)。
+**对话正常，但搜索或压缩失败**：先确认当前 GPT / Grok Responses 路由确实提供对应服务端能力。网关名称本身不代表一定支持所有功能。
 
-## 开发与反馈
+提交 [Issue](https://github.com/kk3ya03-star/dsh-lcx-codex/issues) 时，请附上插件版本、DSH 版本、Node.js 版本和复现步骤。不要上传 API Key、完整请求或未脱敏的会话日志。
 
-```sh
-npm ci --ignore-scripts
-npm ci --prefix scripts/runtime-alpha2 --ignore-scripts
-node scripts/link-dsh-runtime.mjs scripts/runtime-alpha2
-node scripts/check-generated.mjs
-npm run typecheck
-npm test
-npm run test:schema
-```
+## 更多信息
 
-实现细节见[架构说明](ARCHITECTURE.md)。提交 [Issue](https://github.com/kk3ya03-star/dsh-lcx-codex/issues) 时，请附上插件、DSH、Node.js 版本及复现步骤，不要上传 API Key、完整请求或未脱敏的会话日志。
+- [更新日志](CHANGELOG.md)
+- [架构说明](ARCHITECTURE.md)
+- [第三方许可](THIRD_PARTY_NOTICES.md)
 
 ## 许可证
 
-[MIT](LICENSE)。独立社区插件，与 OpenAI、DeepSeek、Sub2API、NewAPI 无隶属或官方背书关系。DeepSeek 名称及标识归其权利人所有。
+[MIT](LICENSE)。独立社区插件，与 OpenAI、DeepSeek、Sub2API、NewAPI 无隶属或官方背书关系。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,64 @@
+# Third-party notices
+
+`lib/pi-responses-runtime.js` is generated from public exports of the packages below. The build recipe in `scripts/build-pi-runtime.mjs` verifies that no other third-party package contributes output bytes.
+
+## @earendil-works/pi-ai 0.85.1
+
+Upstream source: https://github.com/earendil-works/pi/tree/v0.85.1/packages/ai
+
+Included public Responses helpers and model catalogs:
+
+- `api/openai-responses-shared`
+- `api/constrained-sampling`
+- `api/openai-prompt-cache`
+- `utils/event-stream`
+- model helpers from the package root
+- Responses-bearing catalogs for `cloudflare-ai-gateway`, `github-copilot`, `openai`, `opencode`, `opencode-go`, and `xai`
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## partial-json 0.1.7
+
+Upstream source: https://github.com/promplate/partial-json-parser-js
+
+MIT License
+
+Copyright (c) 2023 Promplate Dev Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/auxiliary-usage.js

@@ -0,0 +1,63 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const calls = new AsyncLocalStorage();
+const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+/** Collect only authoritative Responses billing, independently of context size. */
+export function recordHostedUsage(response, requestId, provider, model) {
+    const store = calls.getStore();
+    if (!store || !object(response) || !object(response.usage))
+        return;
+    const u = response.usage;
+    const input = u.input_tokens, output = u.output_tokens, total = u.total_tokens;
+    const cached = object(u.input_tokens_details) ? u.input_tokens_details.cached_tokens : undefined;
+    if (!count(input) || !count(output) || !count(total) || !count(cached)
+        || cached > input || input + output !== total)
+        return;
+    store.push({ requestId, provider, model, usage: {
+            inputTokens: input - cached, outputTokens: output, totalTokens: total,
+            cacheReadTokens: cached, cacheWriteTokens: 0,
+        } });
+}
+/** Extend only LCX-owned search output; rendering and request schemas stay intact. */
+export function withAuxiliaryUsage(tool) {
+    const schema = tool.output.schema;
+    if (schema.type !== "object")
+        throw new Error("Search accounting requires an object output");
+    return {
+        ...tool,
+        output: {
+            ...tool.output,
+            schema: { ...schema, properties: { ...schema.properties, auxiliaryUsage: {
+                        type: "array", items: { type: "object", additionalProperties: true },
+                    } } },
+            render(args, value) {
+                if (!object(value))
+                    return tool.output.render(args, value);
+                const { auxiliaryUsage: _billing, ...original } = value;
+                return tool.output.render(args, original);
+            },
+            presentationMeta(args, value) {
+                if (!object(value))
+                    return tool.output.presentationMeta?.(args, value) ?? {};
+                const { auxiliaryUsage, ...original } = value;
+                const meta = tool.output.presentationMeta?.(args, original) ?? {};
+                if (!Array.isArray(auxiliaryUsage) || auxiliaryUsage.length === 0)
+                    return meta;
+                if (!object(meta))
+                    throw new Error("Search accounting requires object presentation metadata");
+                return { ...meta, auxiliaryUsage };
+            },
+        },
+        async execute(args, exec) {
+            const records = [];
+            return calls.run(records, async () => {
+                const value = await tool.execute(args, exec);
+                if (records.length === 0)
+                    return value;
+                if (!object(value))
+                    throw new Error("Search accounting requires an object result");
+                return { ...value, auxiliaryUsage: records };
+            });
+        },
+    };
+}