@mars-sea/dsh-commandcode-provider 0.12.9 → 0.12.10

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.10] - 2026-10-10
+
+### Changed
+
+- **引擎兼容范围增加 `0.2.1-alpha.2`，业务代码零改动。** 15 个 `@deepseek-ai/dsh-*` peer 的析取由 `0.2.0-rc.2 || 0.2.1-alpha.1` 扩为 `0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2`，`dsh.compatibility.dsh`、`engines.dsh`、`devDependencies`、`package-lock.json` 与 `dsh.compatibility.dshReleases` 同批同步；既有两个分支保留，`@deepseek-ai/cordis`（`~4.0.4 || ~4.0.5-alpha.1`）与 `@deepseek-ai/schemastery`（`~3.18.4 || ~3.18.5-alpha.1`）不用改——alpha.2 与 alpha.1 同批发布的正是这两个版本。逐文件对比 alpha.1 → alpha.2 的公开源码后确认无需改代码：`RequestMessage`／`GenerateOptions`／`ContentBlock`／`LlmError` 结构未变，Agent 事件、设置、凭据、附件与 Typert 严格描述符未变，五个客户端插槽的声明与 Web 预置模块表也未变。
+- alpha.2 有三处宿主内部行为变化，插件按现有接口继续工作，边界已记入参考文档：模型调用准备新增可选回调 `prepareCall(config, signal?, configure?)`（普通适配器不必调用）、请求准备完成后会刷新运行时上下文、代理卸载改为先停流再排空事件。上游 `idleWatchdog` 那处「挂起读取也能按期结束」的修复**不覆盖**插件自己的读流实现，因此本轮按同一目标单独补齐（见下方 Fixed）。
+- `npm run test:install` 改为**逐引擎矩阵**：每个已声明兼容版本各建一个全新的 pnpm 10.34.5 generation，安装时把该版本的必需 Harness peer 一起钉死，再断言锁文件解析出的 `@deepseek-ai/dsh-llm` 恰好是目标版本。此前单次安装只会命中范围里最新的那个分支，全绿并不能证明另外两个引擎装得上。
+
+### Fixed
+
+- **读取卡住的响应不再拖住收束。** 读循环每次读取改用一个「唤醒闸门」：空闲期限到期与调用者取消都先解开闸门，再尽力取消底层读取。此前只有 `reader.cancel()` 能把挂起的 `read()` 唤醒，遇到被包装或被垫片替换、既不结算读取也不响应取消的响应体时，空闲期限、调用者取消和消费方 `return()` 三条路径会一起卡死——期限到了不报错，取消也不返回。现在闸门自己结束等待：调用者取消原样传播（归类 `aborted`），否则以既有 `TIMEOUT` 失败；被放弃的读取结果丢弃，其迟到拒绝就地吞掉（真实读取器在释放锁时会以 `Invalid state: Releasing reader` 拒绝挂起的读取），读取锁仍只释放一次。`tests/adapter.test.ts` 新增三个用例固定这三种收束。
+
+### 已知边界
+
+- 真实引擎检查通过的是发布入口加载、静态具名导入、客户端 `require()` 种子、易变设置契约与 22 个流终态场景；浏览器实际渲染、真实账号请求、卸载期间最终事件排空与长期运行仍需实际环境验收。
+
+### 刻意未采纳
+
+- `systemPromptUpdate: 'in-history'`（历史内系统提示替换）与原生工具延迟激活语义：插件继续用前导系统提示与 `addition-only`（仅新增）工具声明，每次请求发送完整活跃工具列表。能力标记与实际 wire 行为必须一致，未实现前不宣告。
+- 新版 `prepareCall` 的可选准备回调：它是给需要注入辅助调用元数据的场景用的，本适配器不使用第三参数即可保持既有行为。
+
 ## [0.12.9] - 2026-10-09
 
 ### Changed

package/README.md

@@ -35,11 +35,13 @@ See [Screenshots](#screenshots) below for what the UI looks like.
 
 ## Install
 
-This release supports **dsh 0.2.0-rc.2 and dsh 0.2.1-alpha.1, and nothing else** —
-the plugin's peer range is exactly those two verified versions, and its
+This release supports **dsh 0.2.0-rc.2, dsh 0.2.1-alpha.1 and dsh 0.2.1-alpha.2, and nothing else** —
+the plugin's peer range is exactly those three verified versions, and its
 compatibility records name them alone. `0.2.0-rc.2` is what
 `npm i -g @deepseek-ai/dsh@latest` and the official desktop build ship, so it is
-the version most users are on; `0.2.1-alpha.1` is the upstream `alpha` channel:
+the version most users are on; `0.2.1-alpha.2` is the upstream `alpha` channel
+today, and `0.2.1-alpha.1` stays in the range because it was already verified, so
+a profile pinned to it keeps working:
 
 ```sh
 dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@latest
@@ -66,14 +68,14 @@ dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@0.11.15
 
 The same applies to every profile you install into, including the terminal UI below.
 
-Fresh pnpm 10 marketplace generations are supported directly. Every Harness package — including `@deepseek-ai/cordis` and `@deepseek-ai/schemastery` — is declared by the plugin over the same two-version range as its `@deepseek-ai/dsh-*` peers as a Host peer, so the active dsh profile remains their owner; do not add a separate dependency for any of them. Upstream removed the `@deepseek-ai/dsh-invariants` package in `0.2.1-alpha.1`, so the plugin no longer declares it.
+Fresh pnpm 10 marketplace generations are supported directly. Every Harness package is declared by the plugin as a Host peer, so the active dsh profile remains their owner; do not add a separate dependency for any of them. The `@deepseek-ai/dsh-*` packages share one exact-version disjunction; `@deepseek-ai/cordis` and `@deepseek-ai/schemastery` carry the paired ranges `~4.0.4 || ~4.0.5-alpha.1` and `~3.18.4 || ~3.18.5-alpha.1` instead, because publishing an engine rewrites both to the version that shipped alongside it. Upstream removed the `@deepseek-ai/dsh-invariants` package in `0.2.1-alpha.1`, so the plugin no longer declares it.
 
 ## Updating
 
 Update with the same tag you installed with:
 
 ```sh
-dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.0-rc.2 or 0.2.1-alpha.1
+dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.0-rc.2, 0.2.1-alpha.1 or 0.2.1-alpha.2
 dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@0.9.1      # older dsh (0.5.0 line, unmaintained)
 ```
 
@@ -147,7 +149,7 @@ cmd login                               # writes ~/.commandcode/auth.json
         cwd: !!js process.cwd()
 ```
 
-**Engine version.** The plugin is maintained against exactly two engines: **dsh 0.2.0-rc.2** and **dsh 0.2.1-alpha.1**. Its `@deepseek-ai/dsh-*` peers use the disjunction `0.2.0-rc.2 || 0.2.1-alpha.1`, `@deepseek-ai/cordis` is pinned to `~4.0.4 || ~4.0.5-alpha.1` and `@deepseek-ai/schemastery` to `~3.18.4 || ~3.18.5-alpha.1` (each branch shipped with its engine), and `dsh.compatibility.dshReleases` records exactly those two releases. That disjunction is deliberate and load-bearing: unlike a caret or a `>=` range it admits **no** adjacent prerelease, release candidate, or stable patch version, every branch is a bare version, and `npm run test:engine` runs the whole suite against **both** engines before a release. DSH itself refuses to load a plugin whose `@deepseek-ai/dsh*` peers do not admit the running engine, so a range that silently admitted an unverified neighbour would be worse than no range at all. On any other engine the settings page, the message envelope, or the request-image budget may not line up — install the last release that supported your engine (see [Install](#install)) instead of forcing this one.
+**Engine version.** The plugin is maintained against exactly three engines: **dsh 0.2.0-rc.2**, **dsh 0.2.1-alpha.1** and **dsh 0.2.1-alpha.2**. Its `@deepseek-ai/dsh-*` peers use the disjunction `0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2`, `@deepseek-ai/cordis` is pinned to `~4.0.4 || ~4.0.5-alpha.1` and `@deepseek-ai/schemastery` to `~3.18.4 || ~3.18.5-alpha.1` (each branch shipped with its engine), and `dsh.compatibility.dshReleases` records exactly those three releases. That disjunction is deliberate and load-bearing: unlike a caret or a `>=` range it admits **no** adjacent prerelease, release candidate, or stable patch version, every branch is a bare version, and `npm run test:engine` runs the whole suite against **all three** engines before a release. DSH itself refuses to load a plugin whose `@deepseek-ai/dsh*` peers do not admit the running engine, so a range that silently admitted an unverified neighbour would be worse than no range at all. On any other engine the settings page, the message envelope, or the request-image budget may not line up — install the last release that supported your engine (see [Install](#install)) instead of forcing this one.
 
 ## Usage dashboard
 

package/README.zh-CN.md

@@ -33,7 +33,7 @@
 
 ## 安装
 
-本版本**只支持 dsh 0.2.0-rc.2 与 dsh 0.2.1-alpha.1 这两个版本**：插件的 peer 范围就是这两个已验证版本的析取，兼容性记录里也只列它们。`0.2.0-rc.2` 正是 `npm i -g @deepseek-ai/dsh@latest` 与官方桌面端放出的版本，多数用户都在它上面；`0.2.1-alpha.1` 是上游的 `alpha` 通道：
+本版本**只支持 dsh 0.2.0-rc.2、dsh 0.2.1-alpha.1 与 dsh 0.2.1-alpha.2 这三个版本**：插件的 peer 范围就是这三个已验证版本的析取，兼容性记录里也只列它们。`0.2.0-rc.2` 正是 `npm i -g @deepseek-ai/dsh@latest` 与官方桌面端放出的版本，多数用户都在它上面；`0.2.1-alpha.2` 是上游 `alpha` 通道当前提供的版本，`0.2.1-alpha.1` 因为已经验证过而保留在范围内，钉在它上面的 profile 可以继续使用：
 
 ```sh
 dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@latest
@@ -55,14 +55,14 @@ dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@0.11.15
 
 这一点对每个 profile 都成立，包括下面的终端界面。
 
-插件可直接在 pnpm 10 的全新插件市场 generation 中安装。所有 Harness 包（含 `@deepseek-ai/cordis`、`@deepseek-ai/schemastery`）都由插件按与 `@deepseek-ai/dsh-*` 相同的双版本范围声明为 Host peer，由当前 dsh profile 统一管理，不要另行添加 dependency。上游曾在 `0.2.1-alpha.1` 删除 `@deepseek-ai/dsh-invariants` 这个包，因此插件不再声明它。
+插件可直接在 pnpm 10 的全新插件市场 generation 中安装。所有 Harness 包都由插件声明为 Host peer，由当前 dsh profile 统一管理，不要另行添加 dependency。其中 `@deepseek-ai/dsh-*` 共用同一个精确版本析取；`@deepseek-ai/cordis` 与 `@deepseek-ai/schemastery` 则分别写成配对范围 `~4.0.4 || ~4.0.5-alpha.1` 与 `~3.18.4 || ~3.18.5-alpha.1`——上游每次发引擎都会把这两个包重写成随引擎发布的版本。上游曾在 `0.2.1-alpha.1` 删除 `@deepseek-ai/dsh-invariants` 这个包，因此插件不再声明它。
 
 ## 更新
 
 用与安装时相同的 tag 更新：
 
 ```sh
-dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.0-rc.2 或 0.2.1-alpha.1
+dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.0-rc.2、0.2.1-alpha.1 或 0.2.1-alpha.2
 dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@0.9.1      # 更早的 dsh（0.5.0 线，不再维护）
 ```
 
@@ -136,7 +136,7 @@ cmd login                               # 写入 ~/.commandcode/auth.json
         cwd: !!js process.cwd()
 ```
 
-**引擎版本要求。** 插件针对两个引擎维护：**dsh 0.2.0-rc.2** 与 **dsh 0.2.1-alpha.1**。它的 `@deepseek-ai/dsh-*` 对等依赖写成两者的析取 `0.2.0-rc.2 || 0.2.1-alpha.1`，`@deepseek-ai/cordis` 固定为 `~4.0.4 || ~4.0.5-alpha.1`、`@deepseek-ai/schemastery` 固定为 `~3.18.4 || ~3.18.5-alpha.1`（每个分支都与对应引擎同批发布），`dsh.compatibility.dshReleases` 也只记录这两个版本。这个析取写法是刻意的、且是承重的：它不像 `^` 或 `>=` 那样放行任何相邻的预发布版、候选发布或稳定补丁版，每个分支都是一个裸版本号，且发版前 `npm run test:engine` 会对**两个引擎各跑一遍**完整套件。DSH 本身会拒绝加载 `@deepseek-ai/dsh*` peer 不接纳当前引擎的插件——所以一个静默放行未验证邻居的范围，比没有范围更糟。在其它引擎上，设置页、消息封装或请求图片预算总有一处对不上——请改装支持你所用引擎的最后一个版本，而不是硬装这一个。
+**引擎版本要求。** 插件针对三个引擎维护：**dsh 0.2.0-rc.2**、**dsh 0.2.1-alpha.1** 与 **dsh 0.2.1-alpha.2**。它的 `@deepseek-ai/dsh-*` 对等依赖写成三者的析取 `0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2`，`@deepseek-ai/cordis` 固定为 `~4.0.4 || ~4.0.5-alpha.1`、`@deepseek-ai/schemastery` 固定为 `~3.18.4 || ~3.18.5-alpha.1`（每个分支都与对应引擎同批发布），`dsh.compatibility.dshReleases` 也只记录这三个版本。这个析取写法是刻意的、且是承重的：它不像 `^` 或 `>=` 那样放行任何相邻的预发布版、候选发布或稳定补丁版，每个分支都是一个裸版本号，且发版前 `npm run test:engine` 会对**三个引擎各跑一遍**完整套件。DSH 本身会拒绝加载 `@deepseek-ai/dsh*` peer 不接纳当前引擎的插件——所以一个静默放行未验证邻居的范围，比没有范围更糟。在其它引擎上，设置页、消息封装或请求图片预算总有一处对不上——请改装支持你所用引擎的最后一个版本，而不是硬装这一个。
 
 ## 用量面板
 

package/lib/client.js

@@ -3273,7 +3273,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region package.json
-		var version = "0.12.9";
+		var version = "0.12.10";
 		var repository = {
 			"type": "git",
 			"url": "git+https://github.com/Mars-Sea/dsh-commandcode-provider.git"

package/lib/index.js

@@ -3970,6 +3970,11 @@ function openStreamTrace(scope, options = {}) {
 /** 仅供本次消费生命周期使用，不作为服务商错误或用户取消向外传播。 */
 var ConsumerStreamClosed = class extends Error {};
 /**
+* 读循环唤醒闸门的标记值：底层 read() 既不结算、取消也叫不醒时，由闸门结束这次等待。
+* 它不是错误，只在读循环内部出现，用来把「读取完成」与「读取卡住」区分开。
+*/
+const READ_STALLED = Symbol("readStalled");
+/**
 * 异步生成器的 return 会排在正在等待的 next 后面，因此必须先通过独立信号
 * 唤醒当前读取，再让生成器执行 finally。消费方已结束时不再交付用量或错误。
 */
@@ -4031,7 +4036,12 @@ async function* readResponse(response, context) {
 			reader.cancel().catch(() => void 0);
 		} catch {}
 	};
-	const onAbort = () => cancelReader();
+	let openGate;
+	const wakeRead = () => openGate?.();
+	const onAbort = () => {
+		wakeRead();
+		cancelReader();
+	};
 	const decoder = new TextDecoder();
 	let buffer = "";
 	const streamStartedAt = Date.now();
@@ -4044,6 +4054,7 @@ async function* readResponse(response, context) {
 		if (idleTimer !== void 0) clearTimeout(idleTimer);
 		idleTimer = setTimeout(() => {
 			idleFired = true;
+			wakeRead();
 			cancelReader();
 		}, streamIdleTimeoutMs);
 	};
@@ -4053,12 +4064,24 @@ async function* readResponse(response, context) {
 			idleTimer = void 0;
 		}
 	};
+	/** 空闲期限结束读循环时的唯一错误文本；读取结算与读取卡住两条路径共用。 */
+	const idleTimeoutError = () => bilingual("TIMEOUT", `Command Code API stream from ${apiBase} was idle for ${streamIdleTimeoutMs}ms (no events) and was treated as a dead connection`, `Command Code API 流式响应已 ${streamIdleTimeoutMs} 毫秒无任何事件，被判定为死连接——长思考模型可在设置中调大流空闲超时`);
 	const asm = createBlockAssembler();
 	let finish;
 	let usage;
 	let usageEmitted = false;
 	let endRecorded = false;
 	let protocolStopped = false;
+	/** 读循环收束（读到 EOF 或读取卡住）共用的诊断事实，两处记录字段保持一致。 */
+	const eofFacts = () => ({
+		chunks: chunkCount,
+		bytes: totalBytes,
+		silentMs: Date.now() - lastChunkAt,
+		totalMs: Date.now() - streamStartedAt,
+		finishSeen: finish !== void 0,
+		idleFired,
+		buffered: buffer.length
+	});
 	function* handle(event) {
 		captureResponseIdentifiers(responseMetadata, event);
 		if (isRecord(event) && (protocol === "messages" && event.type === "message_stop" || protocol === "cli" && event.type === "finish")) protocolStopped = true;
@@ -4084,9 +4107,14 @@ async function* readResponse(response, context) {
 		for (;;) {
 			signal?.throwIfAborted();
 			let read;
+			const gate = new Promise((resolve) => {
+				openGate = () => resolve(READ_STALLED);
+			});
 			armIdle();
 			try {
-				read = await reader.read();
+				const pending = reader.read();
+				pending.catch(() => void 0);
+				read = await Promise.race([pending, gate]);
 			} catch (error) {
 				signal?.throwIfAborted();
 				trace.record("read-error", {
@@ -4098,20 +4126,21 @@ async function* readResponse(response, context) {
 				throw bilingual("TRANSPORT", `Command Code API stream from ${apiBase} failed while reading: ${errorChain(error)}`, "Command Code API 流式响应中途断开——网络波动所致，重试通常可恢复", { cause: error });
 			} finally {
 				clearIdle();
+				openGate = void 0;
+			}
+			if (read === READ_STALLED) {
+				trace.record("eof", {
+					...eofFacts(),
+					readStalled: true
+				});
+				signal?.throwIfAborted();
+				throw idleTimeoutError();
 			}
 			signal?.throwIfAborted();
 			const { done, value } = read;
 			if (done) {
-				trace.record("eof", {
-					chunks: chunkCount,
-					bytes: totalBytes,
-					silentMs: Date.now() - lastChunkAt,
-					totalMs: Date.now() - streamStartedAt,
-					finishSeen: finish !== void 0,
-					idleFired,
-					buffered: buffer.length
-				});
-				if (idleFired) throw bilingual("TIMEOUT", `Command Code API stream from ${apiBase} was idle for ${streamIdleTimeoutMs}ms (no events) and was treated as a dead connection`, `Command Code API 流式响应已 ${streamIdleTimeoutMs} 毫秒无任何事件，被判定为死连接——长思考模型可在设置中调大流空闲超时`);
+				trace.record("eof", eofFacts());
+				if (idleFired) throw idleTimeoutError();
 				if (buffer.trim()) yield* handleLine(buffer);
 				break;
 			}
@@ -9922,8 +9951,8 @@ function transportBudgetMessage(failureMessage, maxRetries) {
 /**
 * Mark one schema field volatile.
 *
-* `.volatile()` is unconditional: it is a schemastery 3.18.3 feature and the
-* only supported engine (`dsh 0.2.1-alpha.1`) pins `~3.18.5-alpha.1`, so the
+* `.volatile()` is unconditional: it is a schemastery 3.18.3 feature and every
+* supported engine ships `~3.18.4` or `~3.18.5-alpha.1`, so the
 * method is always present. It is reached through a structural member so the caller's
 * declared field type survives — the mark changes what the schema PARSES to (a
 * live reference), not the plugin-facing `Config` shape.