dsh-lcx-codex 0.4.3 → 0.5.0-pre.1

package/README.md

@@ -4,120 +4,155 @@
 
 # LCX Codex
 
-**让 DeepSeek Harness 里的 GPT 与 Grok 更适合长任务、联网搜索和连续工作。**
+**给 DeepSeek Harness 里的 GPT 和 Grok 加上联网搜索和长对话自动压缩。**
 
-[![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)](#安装)
+[![npm latest](https://img.shields.io/npm/v/dsh-lcx-codex/latest?label=latest)](https://www.npmjs.com/package/dsh-lcx-codex)
+[![npm prelatest](https://img.shields.io/npm/v/dsh-lcx-codex/prelatest?label=prelatest&color=orange)](https://www.npmjs.com/package/dsh-lcx-codex?activeTab=versions)
 [![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）的社区插件。
+LCX Codex 是 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness)（DSH）的社区插件。装上之后，你在 DSH 里用的 GPT 和 Grok 可以：
 
-它不会替代 DSH，也不需要你重新配置模型、接口或 API Key。模型、凭据、会话和工具仍由 DSH 管理；LCX 只在需要时为 GPT 和 Grok 增加额外能力。
+- **联网搜索**：GPT 使用 Responses 服务端搜索（Hosted Search），Grok 使用 xAI 原生 Web Search 和 X Search；
+- **长任务不中断**：对话接近上下文上限时自动压缩并继续，不用手动开新会话；
+- **直接看到图片和视频**：搜索返回的图片、回答里的图片直链排成一行显示在回答下方，点击用 DSH 自带的看图器放大；视频直链显示为卡片，点击后在回答里直接播放。
 
-## 你可以用它做什么
+模型、API Key、会话和其他工具仍由 DSH 管理，不需要额外配置。其他模型（如 DeepSeek）照常走 DSH 自己的逻辑，不受影响。
 
-| 能力 | 适合场景 |
-| --- | --- |
-| GPT 联网搜索 | 让 GPT 直接通过 DSH 的 `web_search` 查询网页。 |
-| GPT 高级搜索 | 搜图片、限定网站、加入位置等额外搜索条件。 |
-| Grok 原生 Web / X Search | 直接使用 xAI Responses 的 Web Search 和 X Search。 |
-| 长对话压缩 | GPT 长任务接近上下文上限时自动尝试远程压缩，并继续当前会话。 |
-| 搜索媒体预览 | 在回答下方直接预览可用的图片和视频链接。 |
-| Alpha 网页操作 | 实验性连续网页阅读能力，适合需要进一步打开、查找页面内容的任务。 |
+## 使用前提
+
+- 已安装 DSH，并在 DSH 中配置好 **GPT 或 Grok 的 Responses API 路由**（官方 API 或兼容网关均可）。
+- Node.js `^22.19.0` 或 `>=24.0.0`。
 
-其他模型继续使用 DSH 原生路径，不会因为安装 LCX 而被接管。
+> 搜索和压缩依赖服务端能力。你的网关能正常聊天，不代表它一定支持这些功能，详见[已知限制](#已知限制)。
 
 ## 安装
 
-当前稳定版：**`dsh-lcx-codex@0.4.3`**
+### 1. 按 DSH 版本选择插件版本
+
+先运行 `dsh --version` 查看 DSH 版本，再按下表选择：
+
+| 你的 DSH 版本 | 安装的 LCX 版本 | 安装命令中的标签 |
+| --- | --- | --- |
+| `0.2.0` 系列（`0.2.0-rc.2` 及以后，低于 `0.2.1`） | `0.5.0-pre.1`（预发布版） | `@prelatest` |
+| `0.1.6` 系列（`0.1.6-alpha.2` 及以后） | `0.4.4-pre.1`（旧预发布版） | `@0.4.4-pre.1` |
+| `0.1.5` 系列（`0.1.5-rc.1` 及以后） | `0.4.3`（稳定版） | `@latest` |
+
+请务必按表格选择：三个版本互不兼容，装错版本时安装命令可能只给出依赖警告，但插件可能无法正常工作。`0.5.0-pre.1` 是预发布版，本次预发布的验收基线为 DSH `0.2.0-rc.2`（host / plugin Pi `0.87.1`）。
 
-兼容环境：
+### 2. 安装并启动
 
-- DSH `0.1.5-rc.1` 起的 `0.1.5` 系列（当前完整验证基线：`0.1.5-rc.1`）
-- Node.js `^22.19.0 || >=24.0.0`
+DSH `0.2.0` 系列：
+
+```sh
+dsh plugin --profile web add dsh-lcx-codex@prelatest
+dsh web
+```
 
-安装：
+DSH `0.1.6` 系列：
 
 ```sh
-dsh plugin --profile web add dsh-lcx-codex@0.4.3
+dsh plugin --profile web add dsh-lcx-codex@0.4.4-pre.1
 dsh web
 ```
 
-后续稳定版更新可以使用：
+DSH `0.1.5` 系列：
 
 ```sh
 dsh plugin --profile web add dsh-lcx-codex@latest
+dsh web
 ```
 
-不指定版本或使用 `@latest` 都会安装当前稳定版。需要预发布版本时可使用 `@prelatest`；`0.4.3-pre.13` 作为本次正式版之前的已验证预发布历史继续保留。
+以后更新插件，重新运行同一条 `add` 命令即可。
+
+### 3. 打开功能开关
+
+打开 DSH Web 的插件页面，在 LCX 的配置卡片 **Responses / Codex 能力** 中按需打开下列开关，然后点击 **保存**。
+
+<img src="https://raw.githubusercontent.com/kk3ya03-star/dsh-lcx-codex/main/assets/settings-card.png" alt="LCX 插件配置卡片" width="720" />
 
-本版已在官方 DSH `0.1.5-rc.1` 完整验证。后续同一 `0.1.5` 系列版本可以直接安装并进行兼容评估，不再需要仅因为 RC 版本号变化而发布新的 LCX 版本。
+**GPT**
 
-## 启用功能
+| 开关 | 作用 | 建议 |
+| --- | --- | --- |
+| **启用 LCX** | GPT 功能的总开关，包括长对话自动压缩 | 用 GPT 时打开 |
+| **使用 GPT Hosted Search 作为 DSH web_search 后端** | GPT 联网搜索 | 需要联网时打开 |
+| **启用高级 Hosted 工具** | 图片搜索、限定网站、指定位置等（需先打开上一项） | 按需 |
+| **启用 Alpha command** | 实验功能：让 GPT 继续打开、查找搜索结果中的页面 | 日常不需要 |
 
-打开 DSH Web 的插件设置，找到 **Responses / Codex 能力**。
+**Grok 原生搜索**（与“启用 LCX”相互独立）
 
-### 使用 GPT
+| 开关 | 作用 |
+| --- | --- |
+| **启用原生 Web Search** | Grok 搜索网页 |
+| **启用原生 X Search** | Grok 搜索 X 内容 |
 
-通常打开：
+开启任一项后，Grok 改用 xAI 原生搜索；网页读取和其他 DSH / MCP 工具仍可正常使用。
 
-1. **启用 LCX**
-2. **GPT Hosted Search**（需要联网时）
+**显示**
 
-按需再打开：
+| 开关 | 作用 |
+| --- | --- |
+| **搜索媒体预览** | 在回答下方显示搜索返回的图片、回答里的图片直链和可直接播放的视频直链；图片横排显示、点击放大，视频点击后在回答里播放。回答里用 Markdown 写的图片由 DSH 原生显示，不会重复；普通网页链接保持为链接。只改变界面显示，不影响发给模型的内容 |
 
-- **高级 Hosted 工具**：需要图片搜索、限定域名、位置等高级搜索条件时使用；它依赖 GPT Hosted Search。
-- **Alpha**：实验性网页连续操作。日常联网搜索不需要开启。
+## 怎么用
 
-### 使用 Grok
+像平时一样和模型说话即可，不需要写任何工具参数：
 
-Grok 原生搜索与 GPT 的 LCX 主开关相互独立：
+> 搜索 Python 官方文档，告诉我 `asyncio.TaskGroup` 应该怎么用。
 
-- **Grok 原生 Web Search**：搜索网页。
-- **Grok 原生 X Search**：搜索 X 内容。
+> 搜几张金门大桥的照片，显示一张，并附上来源网页。
 
-开启 Grok 原生搜索后，LCX 会使用 xAI 的服务端搜索能力，同时保留页面读取和其他 DSH / MCP 工具。
+> 用 Grok 看看 X 上最近关于这个项目的讨论。
 
-### 搜索媒体预览
+长对话会在接近上限时自动压缩；你也可以随时输入 `/compact` 手动压缩。
 
-**搜索媒体预览**可以独立开启。它只改变回答的显示方式，不会修改模型提示词、搜索请求、聊天历史或缓存。
+## 从旧版本升级
 
-可识别的图片会显示缩略图并支持放大；直接视频链接可以点击播放。媒体加载失败时，原来的文字和链接仍会保留。
+- **DSH 升级到 `0.2.0` 系列**：把插件换成 `@prelatest`（`0.5.0-pre.1`），旧版 `0.4.x` 不支持 DSH `0.2`。
+- **DSH `0.1.6` 系列**：继续使用 `@0.4.4-pre.1`；`@prelatest` 现在指向支持 DSH `0.2` 的 `0.5.0-pre.1`。
+- **升级后建议新建会话**：旧版本保存的压缩状态不保证兼容。DSH `0.2` 迁移过的旧长会话如果带有旧版 LCX 压缩检查点，LCX 会提示 `LCX_CHECKPOINT_UNSUPPORTED`，新建会话即可；其他模型不受影响。
 
-## 常见用法
+## 停用与卸载
 
-直接像平时一样和模型说话，不需要手写工具参数。例如：
+- **临时停用**：在配置卡片中关闭 **启用 LCX** 和 Grok 原生搜索开关并保存，GPT 和 Grok 即恢复 DSH 原生行为。
+- **卸载**：
 
-> 搜索 Python 官方文档，告诉我 `asyncio.TaskGroup` 应该怎么用。
+  ```sh
+  dsh plugin --profile web remove dsh-lcx-codex
+  ```
 
-> 搜索几张金门大桥的照片，显示一张，并给我来源网页。
+## 已知限制
 
-> 用 Grok 搜一下 X 上最近关于这个项目的讨论。
+- **网关能力因人而异**：搜索、压缩、Alpha 都依赖对应的服务端能力，不同网关支持程度不同。
+- **Grok**：支持 API Key / API 网关路由，不支持 xAI OAuth / SuperGrok 登录。原生 X Search 目前只在 `grok-4.6` 上验证过。
+- **Grok 长对话压力**：xAI 的智能体调用会把多次内部请求的用量累加计费。`0.5.0-pre.1` 在服务端返回完整的实时上下文数据时，用它来判断何时压缩，缺失时退回估算；计费数字本身保持不变。
+- **Alpha 仍是实验功能**：连续打开/查找页面在已测试的 OAuth 类上游上可用；API Key 类上游账号不在支持范围内。目标页面抓取失败时会提示 `LCX_ALPHA_PAGE_FETCH_FAILED`，模型可以换一个结果继续。
+- **Markdown 图片换行**：为避免 DSH `0.2` 中图片后的文字挤到图片右侧，LCX 会让回答里的 Markdown 图片单独占一行，这一点与“搜索媒体预览”开关无关；句中的小图也会因此换行。
+- **DSH `0.1.5` + LCX `0.4.3`**：在插件设置中启用或停用 LCX 后，已打开的浏览器页面可能需要刷新。
+- **验证范围**：`0.5.0-pre.1` 的验收基线为 DSH `0.2.0-rc.2`（预发布）；`0.4.4-pre.1` 在 DSH `0.1.6-alpha.2` 上完整验证；`0.4.3` 的稳定发布基线是 DSH `0.1.5-rc.1`，并已另外验证 DSH `0.1.5-rc.2`。同一安装范围内其他后续版本仍需单独评估，遇到问题欢迎反馈。
 
-长任务也不需要自己盯着上下文。启用 LCX 后，兼容的 GPT 路由会在对话变得很长时自动尝试远程压缩并继续工作；你也可以使用 `/compact` 手动压缩。
+## 常见问题
 
-## 兼容性与已知限制
+**装完没有变化？**
+确认安装命令和启动命令用的是同一个 profile（上面的示例都是 `web`），并检查插件设置里的开关已经保存。
 
-- `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 等功能也一定可用。
+**能正常聊天，但搜索或压缩失败？**
+大概率是当前 GPT / Grok 路由没有提供对应的服务端能力。可以换官方 API 或其他网关对比一下。
 
-## 遇到问题
+**安装时出现依赖版本警告，或插件加载失败？**
+通常是 DSH 版本和插件版本不匹配，按[上面的表格](#1-按-dsh-版本选择插件版本)重新选择。
 
-**安装后看不到变化**：确认安装和启动使用的是同一个 `web` profile，并检查对应功能开关是否已经保存。
+## 反馈问题
 
-**对话正常，但搜索或压缩失败**：先确认当前 GPT / Grok Responses 路由确实提供对应服务端能力。网关名称本身不代表一定支持所有功能。
+请在 [Issues](https://github.com/kk3ya03-star/dsh-lcx-codex/issues) 中附上：插件版本、DSH 版本、Node.js 版本、使用的模型/网关类型和复现步骤。
 
-提交 [Issue](https://github.com/kk3ya03-star/dsh-lcx-codex/issues) 时，请附上插件版本、DSH 版本、Node.js 版本和复现步骤。不要上传 API Key、完整请求或未脱敏的会话日志。
+**请不要上传 API Key、完整请求内容或未脱敏的会话日志。**
 
-## 更多信息
+## 更多
 
 - [更新日志](CHANGELOG.md)
 - [架构说明](ARCHITECTURE.md)
@@ -125,4 +160,4 @@ Grok 原生搜索与 GPT 的 LCX 主开关相互独立：
 
 ## 许可证
 
-[MIT](LICENSE)。独立社区插件，与 OpenAI、DeepSeek、Sub2API、NewAPI 无隶属或官方背书关系。
+[MIT](LICENSE)。独立社区插件，与 OpenAI、xAI、DeepSeek、Sub2API、NewAPI 无隶属关系，也未获得其官方背书。

package/lib/abort-error.js

@@ -0,0 +1,47 @@
+// @ts-check
+const ABORT_MESSAGE = "The operation was aborted";
+function abortInstance() {
+    if (typeof DOMException === "function")
+        return new DOMException(ABORT_MESSAGE, "AbortError");
+    const error = new Error(ABORT_MESSAGE);
+    error.name = "AbortError";
+    return error;
+}
+// `DOMException.prototype.code` is a getter-only accessor, so own properties are
+// defined rather than assigned. Both stay non-enumerable, like a native `cause`.
+function define(target, key, value) {
+    try {
+        Object.defineProperty(target, key, {
+            value,
+            configurable: true,
+            writable: true,
+            enumerable: false,
+        });
+    }
+    catch { }
+}
+function synthesize(reason) {
+    const error = abortInstance();
+    define(error, "code", "LCX_ABORTED");
+    if (reason !== undefined && reason !== null)
+        define(error, "cause", reason);
+    return error;
+}
+/**
+ * Normalize an abort reason into something safe to throw. `fallback` is used only when
+ * the reason is absent, preserving the older `signal.reason ?? error` behaviour.
+ */
+export function normalizeAbortReason(reason, fallback) {
+    if (reason instanceof Error)
+        return reason;
+    if (reason === undefined || reason === null) {
+        if (fallback instanceof Error)
+            return fallback;
+        return synthesize(undefined);
+    }
+    return synthesize(reason);
+}
+/** The error to throw for `signal`'s cancellation. */
+export function abortError(signal, fallback) {
+    return normalizeAbortReason(signal?.reason, fallback);
+}