dsh-connect-workbuddy 4.6.1 → 4.6.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 4.6.2 (2026-10-16)
+
+> 版本号是 **patch**：修的是一个启动期缺陷，没有接口、配置或界面变更。
+
+### Fixes
+
+- **shim 启动时会避开「HTTP 客户端自己拒绝」的端口**
+  - **症状**：某个区域（`cn` 或 `global`）的模型请求**全部失败**，报错只有一句 `Connection error.`，而 shim 本身完全健康 —— `curl`、`node:http`、裸 TCP 连上去都是 200。重启后可能好、可能照样坏。
+  - **根因**：`server.listen(0)` 让内核挑端口，而 Fetch 规范定义了一张**必须拒绝**的端口清单（`fetch.spec.whatwg.org#block-bad-port`，undici 实现为 `badPorts`，当前最大到 `10080`）。`fetch` 在**开 socket 之前**就拒绝这些端口，所以请求根本没上过网线。pi-ai 驱动官方 `openai` SDK，而它的 `getDefaultFetch()` 返回 `globalThis.fetch` —— **生产路径走的就是这一层**，不是只有测试才会中招（已实测 `openai@6.40.0`：坏端口报 `Connection error. → fetch failed → bad port`，正常端口正常返回）。端口只在启动时 bind 一次，不会自己重掷，所以一旦抽中就是**该区域持续失败直到插件重新加载**。
+  - **只在特定机器上发生**：`listen(0)` 的抽取范围是系统的动态端口范围，三平台默认值（Windows/macOS `49152-65535`、Linux `32768-60999`）**整体高于**清单最大值 `10080`，交集为空 —— 默认机器**结构上不可能中招**。只有当范围被下调到触及 `10080` 以下才会发生，例如本机的遗留注册表值 `MaxUserPort = 15000`（实测 `netsh` 报 `1024-15000`，范围内有 **19 个**被禁端口，约 `0.136%`／次绑定；每次插件加载建 2 个 shim，约 `0.27%`／次加载）。这一条**已按三方独立实测核对**：`0.105%`（60000 次采样）、`0.115%`（20000 次采样）、理论值 `0.136%`。
+  - **为什么难自查**：错误链上真正的 `cause`（`bad port`）被 SDK 归一化时丢弃，界面和日志都只剩 `Connection error.`，读不出是端口问题；用户唯一能做的「换个账号」恰好**救不了**（与账号无关）。顺带确认：这个拒绝与代理无关（把 `HTTP_PROXY` 指向死端口、清空 `NO_PROXY`，回环好端口仍返回 200 —— 说明回环流量根本不经过代理），也不是 `ECONNREFUSED`（后者带 `code`，而它是 `cause.message === 'bad port'`、无 `code`）。
+  - **改了什么**：新增 `clientRefusesPort()`（绑定后用自己的 `fetch` 打 `/healthz` 探测：**返回任何 HTTP 码都算客户端接受**，含 401；只有抛异常才算被拒）与 `listenOnClientReachablePort()`（有界重掷，上限 `PORT_ROLL_LIMIT = 5`）。用客户端自身探测而**不是**比对一张抄来的端口表：清单是规范的一部分，抄本会随规范漂移，而这里要满足的规则**本身就是客户端的**。绑定方式仍是 `listen(0)` + 仅回环（随机性不变），端口在 `ready` 之前定格，因此 `baseUrl()` 的消费方一行未改。
+  - **顺带修掉一个自己引入的缺陷**：`close()` 落在 `listen()` 未完成期间时，Node **既不触发 `listening` 也不触发 `error`，只触发 `close`**（实测确认）——最初的 `listenOnce` 只监听前两者，会让 `ready` 永久 pending、卡住插件卸载。已补 `close` 监听。
+  - **守卫**：`tests/shim.spec.ts` 新增 6 例（真实客户端识别被禁端口、健康端口不误判、拒绝与真实传输错误可区分、重掷后确实服务、上界生效不空转、首抽即通过时不重掷），外加 2 例生命周期守卫（启动期被处置不得挂起、并发 `close()` 安全）。**变异验证（4 个变异全部转红，且各自只打中应打中的用例）**：① 探测恒真（永不重绑，等价修复前）→ 红 3 例；② 探测恒假 → 红 1 例；③ 移除 `close` 监听 → 红 1 例（30s 超时，正是挂起）；④ 上界失效 → 红 1 例。
+  - **端到端验证（跑在真实 `createWorkBuddyShim` 上，非 mock）**：启动 **500 个**真实 shim，落在被禁端口的 **0 个**、客户端不可达的 **0 个**（修复前期望约 0.68 个）；劫持 `fetch` 让首次探测抛出与真实 `bad port` **同形状**的错误后，真实对象从 `4512` 重掷到 `4513` 并在新端口正常服务。全量 `79` 文件／`1308` 用例通过，与改动前的 `1300` 相比净增 `8` 例。
+
 ## 4.6.1 (2026-10-16)
 
 > 版本号是 **patch**：只加了一行提示文案，没有行为、接口或配置变更。

package/lib/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as defaultDesktopAuthDirs, F as WorkBuddyUpstreamClient, K as WORKBUDDY_APP_EXECUTABLE_ENV, O as legacyWorkbuddyOwnAuthPath, Q as findWorkbuddyAppExecutableWithSource, S as defaultDesktopAuthCandidates, a as readHostHeartbeat, c as WORKBUDDY_CONNECT_VERSION, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, j as workbuddyOwnAuthPath, l as piAiRuntimeInfo, o as workbuddyHostHeartbeatPath, ot as hostPeersInfo, r as isHeartbeatProcessAlive, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, y as WorkBuddyCredentialStore } from "./host-heartbeat-BI7_lfoi.js";
+import { C as defaultDesktopAuthDirs, F as WorkBuddyUpstreamClient, K as WORKBUDDY_APP_EXECUTABLE_ENV, O as legacyWorkbuddyOwnAuthPath, Q as findWorkbuddyAppExecutableWithSource, S as defaultDesktopAuthCandidates, a as readHostHeartbeat, c as WORKBUDDY_CONNECT_VERSION, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, j as workbuddyOwnAuthPath, l as piAiRuntimeInfo, o as workbuddyHostHeartbeatPath, ot as hostPeersInfo, r as isHeartbeatProcessAlive, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, y as WorkBuddyCredentialStore } from "./host-heartbeat-De95rlXS.js";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/bin.ts

package/lib/{host-heartbeat-BI7_lfoi.js → host-heartbeat-De95rlXS.js}

@@ -3825,7 +3825,7 @@ function generationOf(version) {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "4.6.1";
+const WORKBUDDY_CONNECT_VERSION = "4.6.2";
 //#endregion
 //#region src/host-heartbeat.ts
 /**

package/lib/index.js

@@ -1,4 +1,4 @@
-import { $ as isEncryptedFieldWrapper, A as workbuddyAccountId, B as modelIdOfBody, C as defaultDesktopAuthDirs, D as isVaultAccountId, E as isEncryptedCredentialError, F as WorkBuddyUpstreamClient, G as regionOf, H as parseReasoning, I as classifyUpstreamError, J as deriveAtRestKey, K as WORKBUDDY_APP_EXECUTABLE_ENV, L as declaredTools, M as CREDENTIAL_REJECTED_CODE, N as WORKBUDDY_FALLBACK_SYSTEM_PROMPT, O as legacyWorkbuddyOwnAuthPath, P as WorkBuddyCredentialRejectedError, R as isCredentialRejectedError, S as defaultDesktopAuthCandidates, T as hasEncryptedCredentialFields, U as parseUpstreamModel, V as parseCreditMultiplier, W as prepareChatBody, X as fetchAtRestKeyPayload, Y as deriveAtRestKeyId, Z as findWorkbuddyAppExecutable, _ as WORKBUDDY_AUTH_FILENAME, a as readHostHeartbeat, at as workbuddyAppExecutableCandidates, b as WorkBuddyEncryptedCredentialError, c as WORKBUDDY_CONNECT_VERSION, ct as withFileLock, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, et as isWorkbuddyBundle, f as WorkBuddyCatalog, g as ENCRYPTED_CREDENTIAL_CODE, h as fallbackModelsFor, i as processStartTimeMs, it as readAtRestKey, j as workbuddyOwnAuthPath, k as parseWorkBuddyAuth, l as piAiRuntimeInfo, lt as writeFileAtomic, m as deriveCatalog, n as clearHostHeartbeat, nt as macosNestedAppBundles, o as workbuddyHostHeartbeatPath, p as applyContextBudgets, q as clearAtRestKeyCache, r as isHeartbeatProcessAlive, rt as openEncryptedField, s as writeHostHeartbeat, st as resolveDshHome, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, tt as macosBundleExecutable, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, w as defaultDesktopAuthPath, x as authFileName, y as WorkBuddyCredentialStore, z as knownRegionOf } from "./host-heartbeat-BI7_lfoi.js";
+import { $ as isEncryptedFieldWrapper, A as workbuddyAccountId, B as modelIdOfBody, C as defaultDesktopAuthDirs, D as isVaultAccountId, E as isEncryptedCredentialError, F as WorkBuddyUpstreamClient, G as regionOf, H as parseReasoning, I as classifyUpstreamError, J as deriveAtRestKey, K as WORKBUDDY_APP_EXECUTABLE_ENV, L as declaredTools, M as CREDENTIAL_REJECTED_CODE, N as WORKBUDDY_FALLBACK_SYSTEM_PROMPT, O as legacyWorkbuddyOwnAuthPath, P as WorkBuddyCredentialRejectedError, R as isCredentialRejectedError, S as defaultDesktopAuthCandidates, T as hasEncryptedCredentialFields, U as parseUpstreamModel, V as parseCreditMultiplier, W as prepareChatBody, X as fetchAtRestKeyPayload, Y as deriveAtRestKeyId, Z as findWorkbuddyAppExecutable, _ as WORKBUDDY_AUTH_FILENAME, a as readHostHeartbeat, at as workbuddyAppExecutableCandidates, b as WorkBuddyEncryptedCredentialError, c as WORKBUDDY_CONNECT_VERSION, ct as withFileLock, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, et as isWorkbuddyBundle, f as WorkBuddyCatalog, g as ENCRYPTED_CREDENTIAL_CODE, h as fallbackModelsFor, i as processStartTimeMs, it as readAtRestKey, j as workbuddyOwnAuthPath, k as parseWorkBuddyAuth, l as piAiRuntimeInfo, lt as writeFileAtomic, m as deriveCatalog, n as clearHostHeartbeat, nt as macosNestedAppBundles, o as workbuddyHostHeartbeatPath, p as applyContextBudgets, q as clearAtRestKeyCache, r as isHeartbeatProcessAlive, rt as openEncryptedField, s as writeHostHeartbeat, st as resolveDshHome, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, tt as macosBundleExecutable, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, w as defaultDesktopAuthPath, x as authFileName, y as WorkBuddyCredentialStore, z as knownRegionOf } from "./host-heartbeat-De95rlXS.js";
 import z from "@deepseek-ai/schemastery";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
@@ -1111,8 +1111,12 @@ function finish(parts, calls) {
 *     JSON、bearer 必须匹配进程内随机 secret）、常量时间比对、
 *     随机端口绑定、body 上限、上游错误分类到 HTTP 状态码的映射，
 *     均由该项目设计并验证。
-* 改动：无。安全相关代码不做「改善」，原样沿用。
-
+* 改动：随机端口绑定加了「先确认客户端能用」一步（`listenOnClientReachablePort`）。
+*   绑定方式仍是 `listen(0)` + 仅回环，随机性不变；改的只是抽到 HTTP 客户端
+*   禁用端口（fetch 规范的 block-bad-port 清单）时重抽，而不是带着一个自己
+*   客户端连不上的端口启动。四重校验、常量时间比对、body 上限、
+*   错误分类均未改动。
+*
 * @module dsh-connect-workbuddy/shim
 */
 const REQUEST_BODY_LIMIT = 67108864;
@@ -1776,6 +1780,147 @@ function contentFrame(chunk, choice, content) {
 	return `data: ${JSON.stringify(next)}\n\n`;
 }
 /**
+* Whether this runtime's `fetch` refuses `port` WITHOUT ever connecting.
+*
+* `server.listen(0)` lets the kernel pick the port, and the Fetch standard bans
+* a list of ports that `fetch` must reject before opening a socket
+* (`fetch.spec.whatwg.org#block-bad-port`, implemented as undici's `badPorts`).
+* Every client of this shim goes through that same `fetch`: pi-ai drives the
+* OpenAI SDK, whose `getDefaultFetch()` returns `globalThis.fetch`. So a shim
+* that lands on a banned port is unreachable to its own client while being
+* perfectly healthy on the wire — measured on port 6000: `fetch` refuses,
+* while `node:http`, a raw TCP socket and `curl` all connect and get 200.
+*
+* That combination is what makes it worth preventing rather than diagnosing: it
+* is silent (the SDK surfaces only `Connection error.`, with the `bad port`
+* cause dropped), total (every request in the region fails), and it does not
+* re-roll on its own.
+*
+* Whether it can happen at all depends on the machine's dynamic port range,
+* because that is the set `listen(0)` draws from:
+*
+*   Windows default 49152-65535, Linux default 32768-60999, macOS 49152-65535
+*     — every banned port is <= 10080 (the current list ends there), so the
+*       intersection is EMPTY and these machines cannot be affected.
+*   A range lowered to reach below 10080 — e.g. the legacy `MaxUserPort`
+*     registry value pinned to 15000, which yields 1024-15000 — draws from a
+*     set that CONTAINS banned ports. Measured there: 19 of 13977 ports are
+*     banned, i.e. ~0.14% per bind and ~0.27% per plugin load (two regions,
+*     one bind each).
+*
+* Probing with the client itself, rather than comparing against a copy of the
+* banned list, is deliberate: a hard-coded list drifts the moment the standard
+* gains a port, whereas the rule being satisfied here IS the client's own, so
+* asking the client cannot disagree with it. `tests/shim.spec.ts` pins the
+* error shape this relies on, so a Node change that renames it fails loudly
+* instead of silently disabling the guard.
+*/
+async function clientRefusesPort(port) {
+	try {
+		await fetch(`http://127.0.0.1:${port}/healthz`);
+		return false;
+	} catch (error) {
+		return isBadPortRefusal(error);
+	}
+}
+/**
+* Whether `error` is the client's PORT REFUSAL rather than a real transport
+* failure.
+*
+* The two must never be conflated: a refused port is worth re-rolling, while
+* `ECONNREFUSED`/`ECONNRESET` are ordinary transport errors that re-rolling
+* would only paper over. Measured shapes on Node 24:
+*
+*   refused port : TypeError('fetch failed') -> cause Error('bad port')        (no `code`)
+*   closed  port : TypeError('fetch failed') -> cause Error('connect ECONNREFUSED …') (code `ECONNREFUSED`)
+*
+* The cause chain is walked, with a bound, rather than read one level deep:
+* the OpenAI SDK wraps this same refusal in its own `APIConnectionError`, and a
+* caller should not have to know how deep the active client happens to nest it.
+*/
+function isBadPortRefusal(error) {
+	let current = error;
+	for (let depth = 0; depth < 4; depth++) {
+		if (!(current instanceof Error)) return false;
+		if (current.message === "bad port") return true;
+		current = current.cause;
+	}
+	return false;
+}
+/**
+* Listen on an ephemeral loopback port, rejecting on failure.
+*
+* Also settles on `close`, which is NOT redundant: measured on Node 24, a
+* `close()` that lands while `listen()` is still pending fires neither
+* `listening` nor `error` — only `close`. Without that third listener a dispose
+* during startup would leave this promise (and therefore the shim's `ready`)
+* pending forever, wedging plugin unload. Resolving there is deliberate:
+* disposal is a satisfied end state, not a startup failure.
+*/
+function listenOnce(server) {
+	return new Promise((resolve, reject) => {
+		const settle = () => {
+			server.off("listening", onListening);
+			server.off("error", onError);
+			server.off("close", onClose);
+		};
+		const onListening = () => {
+			settle();
+			resolve();
+		};
+		const onError = (error) => {
+			settle();
+			reject(error);
+		};
+		const onClose = () => {
+			settle();
+			resolve();
+		};
+		server.once("listening", onListening);
+		server.once("error", onError);
+		server.once("close", onClose);
+		server.listen(0, "127.0.0.1");
+	});
+}
+/** Stop listening, resolving once the listener is down. */
+function closeOnce(server) {
+	return new Promise((resolve) => server.close(() => resolve()));
+}
+/**
+* Bind an ephemeral loopback port that the CLIENT can actually reach.
+*
+* `listen(0)` stays the right way to get a port — the kernel picks a free one
+* instead of this plugin guessing a number — but the first pick is not always
+* usable, so the roll repeats while the client refuses it. See
+* {@link clientRefusesPort} for why the client's own answer is the criterion,
+* and {@link PORT_ROLL_LIMIT} for why the loop is bounded.
+*
+* The probe is injected rather than imported so the re-roll path can be driven
+* deterministically: no test can make `listen(0)` return a banned port on
+* demand, so this seam is the only way to pin the behaviour that actually
+* matters.
+*
+* `ready` (the returned promise) therefore resolves only once a port is
+* settled, which is what lets every consumer keep reading `baseUrl()` as it
+* always has.
+*/
+async function listenOnClientReachablePort(options) {
+	const { server, clientRefuses, logger, cancelled } = options;
+	for (let attempt = 1;; attempt++) {
+		if (cancelled?.() === true) return;
+		await listenOnce(server);
+		const address = server.address();
+		const port = address === null || typeof address === "string" ? void 0 : address.port;
+		if (port === void 0 || !await clientRefuses(port)) return;
+		if (attempt >= 5) {
+			logger?.warn(`dsh-connect-workbuddy: port ${port} is on the HTTP client's refused list and 5 rolls did not avoid one; serving on it anyway`);
+			return;
+		}
+		logger?.warn(`dsh-connect-workbuddy: port ${port} is refused by the HTTP client; re-rolling (attempt ${attempt})`);
+		await closeOnce(server);
+	}
+}
+/**
 * Start the loopback endpoint. Requests must carry the shim's shared secret;
 * the loopback bind alone is not a trust boundary.
 */
@@ -1804,11 +1949,27 @@ function createWorkBuddyShim(options) {
 	const server = createServer((req, res) => {
 		handle(req, res);
 	});
-	const ready = new Promise((resolve, reject) => {
-		server.once("listening", () => resolve());
-		server.once("error", reject);
+	let disposed = false;
+	server.on("error", (error) => {
+		if (server.listening) logger?.error("dsh-connect-workbuddy: loopback listener error", error);
+	});
+	/**
+	* Resolves once the listener is up on a port the client can actually reach.
+	*
+	* The port is settled HERE — `listenOnClientReachablePort` re-rolls while the
+	* client refuses the assigned one — so every consumer can keep resolving
+	* `baseUrl()` exactly as before, with no invalidation or rebuild step. A
+	* genuine bind failure still rejects, the one behaviour the caller relies on.
+	*/
+	const ready = listenOnClientReachablePort({
+		server,
+		clientRefuses: clientRefusesPort,
+		logger,
+		cancelled: () => disposed
+	}).catch((error) => {
+		logger?.error("dsh-connect-workbuddy: loopback listener failed to start", error);
+		throw error;
 	});
-	server.listen(0, "127.0.0.1");
 	const baseUrl = () => {
 		const address = server.address();
 		if (address === null || typeof address === "string") throw new Error("workbuddy shim has no listening address");
@@ -2054,10 +2215,10 @@ function createWorkBuddyShim(options) {
 		ready,
 		baseUrl,
 		token: () => SHARED_SECRET,
-		close: () => new Promise((resolve, reject) => {
+		close: () => new Promise((resolve) => {
+			disposed = true;
 			server.close(() => resolve());
 			server.closeAllConnections();
-			server.once("error", reject);
 		})
 	};
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-workbuddy",
   "displayName": "DSH Connect WorkBuddy",
   "description": "把本机登录的 WorkBuddy 模型接入 DeepSeek Harness，并提供只读的积分概览与模型管理。",
-  "version": "4.6.1",
+  "version": "4.6.2",
   "author": "dingminhua",
   "copyright": "Copyright (c) 2026 LaoDing",
   "license": "MIT",