@having5548/dsh-downloader 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -9,6 +9,61 @@
 
 ## [未发布]
 
+## [0.6.0] - 2026-10-17
+
+### 新增
+
+- **`harnessProxy`：让 harness 自身的出网也走内核**（原先只有 `dsh_download` 与 `dsh_run_proxied` 走）。
+  做法是把内核绑到**固定端口**、额外接受一个**持久化令牌**，再把
+  `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` 写进 `$DSH_HOME/.env`（写前备份）。
+  DSH 启动时据此装全局 dispatcher 并把变量传给子进程，因此**这些会跟着走**：
+  `web_fetch`、shell 子进程里的 `curl`/`git`/`npm`、MCP 的 HTTP 传输、jobs/workflow/subagent 派生的进程。
+  **覆盖不到** Electron 渲染进程与内嵌 webview —— Chromium 读的是**系统代理**，不读环境变量。
+- 新工具 `dsh_harness_proxy`（`status` / `apply` / `remove`），新配置项
+  `harnessProxy`（开关）与 `harnessProxyPort`（默认 `17890`）。
+- 新模块 `lib/core/harness-proxy.js`：令牌持久化、URL 拼装、`.env` 的增/删/查、备份。
+
+### 设计要点
+
+- **令牌必须持久化**：`.env` 里要写死它，随机令牌每次重启都会 407。存在
+  `<数据目录>/harness-token.txt`（`mode 0o600`）。
+- **端口必须固定**：`.env` 指不到随机端口。被占用时自动退回随机端口并 warn —— 此时开放实际不生效（`status` 会报「与配置不一致」）。
+- **`NO_PROXY` 自动补上回环 + 国内 AI 平台域名**：前者避免「代理指向自己」的循环，后者保证代理抖动时不打断模型长连接。
+- **不会有自指环**：内核与订阅自己拉的流量走 `httpFlow`（Node `http/https` 模块），**不受全局 dispatcher 影响** —— 这是刻意确认过的，插件里没有用 `fetch()` 的核心代码。
+- 内核原先只接受一个令牌，现改为**令牌集合**（本进程令牌 + 持久化令牌），unknown 令牌照旧 407。
+
+### 兼容
+
+`harnessProxy` 默认**关闭**，行为与 0.5.3 完全一致；不开时内核仍是随机端口 + 随机令牌，只服务本插件自己的下载。
+
+> 测试 368 → 406 项：令牌持久化与只读模式、URL 校验、6 个 `*_PROXY` 键的增删幂等、
+> 备份与还原、`NO_PROXY` 合并、不一致检测，以及**内核同时接受两个令牌 / 未知令牌仍被拒**的运行时断言。
+
+## [0.5.3] - 2026-10-11
+
+### 修复
+
+- **上游断管会把整个 DSH 宿主崩掉**（严重，宿主连续崩了两次）。
+  现象：`crash-2026-10-11T03-46-46-081Z-host.log` 与 `03-48-03-999Z-host.log` 的栈指向同一处：
+  ```
+  dsh: fatal uncaught exception: Error: write EPIPE
+      at Writable.write (node:internal/streams/writable:508:10)
+      at Object.write (.../@having5548/dsh-downloader/lib/core/transports.js:598:28)
+      at Socket.<anonymous> (.../@having5548/dsh-downloader/lib/core/proxy-server.js:154:9)
+  ```
+  根因：`nativeConnect()` 用 `stdio: ["pipe","pipe","pipe"]` 起 Go 连接器，但**三根管道一个 `error` 监听都没挂**。
+  连接器进程一死（连接失败 / 超时 / 被 kill），管道随即断裂，之后任何一次写入都会让 `child.stdin` 抛出
+  `EPIPE` —— 而在 Node 里**没有监听者的 `error` 事件就是未捕获异常**，直接把宿主带走。
+  原有的 `ended` 标志挡不住这个竞态：写入可能排在一个已经断掉的管道上，而 `exit` 事件还没派发。
+  修法（三层）：
+  1. 新增 `stdioFace(child)`：给 `stdin` / `stdout` / `stderr` 与子进程本身都挂 `error` 监听，
+     写入再包一层 try/catch（防同步抛出），并保留连接器最后的 stderr 供排查；
+  2. `ProxyServer.#relay()` 里的 `face.write(chunk)` 包 try/catch，失败即关闭上游并销毁客户端连接；
+  3. 新增**独立子进程**回归测试：让子进程关掉 stdin 但继续活着（于是 `ended` 不会置位、管道却已断），
+     再灌 1.25 MB 数据。旧写法在该探针下必崩（实测 `exit=1`、`code: 'EOF'`），修复后存活。
+
+> 测试 366 → 368 项。
+
 ## [0.5.2] - 2026-10-10
 
 两处都是把 `dsh_run_proxied` 真正用起来时才暴露的：`git push` 打插件内核**必定**失败。

package/README.en.md

@@ -6,10 +6,11 @@
 
 [简体中文](README.md) | English
 
-![Version](https://img.shields.io/badge/version-0.5.2-4c7ef3?style=flat-square)
+![Version](https://img.shields.io/badge/version-0.6.0-4c7ef3?style=flat-square)
+![npm](https://img.shields.io/npm/v/@having5548/dsh-downloader?style=flat-square&label=npm)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0078d6?style=flat-square)
 ![Protocols](https://img.shields.io/badge/nodes-ss%20%7C%20trojan%20%7C%20vless%20%7C%20vmess%20%7C%20socks5%20%7C%20http-2b6cb0?style=flat-square)
-![Tests](https://img.shields.io/badge/tests-366%20passed-2fa95e?style=flat-square)
+![Tests](https://img.shields.io/badge/tests-406%20passed-2fa95e?style=flat-square)
 ![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)
 
 </div>
@@ -50,20 +51,27 @@ The two can be used together; they do not interfere. This plugin **never mutates
 
 ## 📦 Install
 
+From npm (published to the official registry):
+
+```bash
+dsh plugin --profile desktop add @having5548/dsh-downloader
+```
+
 From the GitHub release:
 
 ```bash
-dsh plugin --profile desktop add https://github.com/having5548/dsh-downloader/releases/latest/download/having5548-dsh-downloader-0.5.2.tgz
+dsh plugin --profile desktop add https://github.com/having5548/dsh-downloader/releases/latest/download/having5548-dsh-downloader-0.6.0.tgz
 ```
 
 Or build and install locally:
 
 ```bash
 npm pack
-dsh plugin --profile desktop add having5548-dsh-downloader-0.5.2.tgz
+dsh plugin --profile desktop add having5548-dsh-downloader-0.6.0.tgz
 ```
 
 > Profile name: the current Electron desktop app uses `desktop`; the older web CLI used `web`.
+> The README shown on the npm page is the one captured **at publish time** — later documentation edits only reach it with the next release.
 
 Then open **Settings → Download proxy**.
 
@@ -257,7 +265,7 @@ The upstream is resolved in this order; the first hit wins:
 | `downloadDir` | empty | empty = `$DSH_HOME/downloads` |
 | `maxDownloadMb` | `512` | per-file size limit |
 | `downloadTimeoutS` | `600` | per-download wall-clock budget |
-| `threads` | `4` | segmented connection count; `1` = single stream. Falls back to one connection when the server lacks `Range`, answers it dishonestly, or the file is under 1 MiB |
+| `threads` | `4` | segmented connection count; `1` = single stream. Falls back to one connection when the server lacks `Range`, answers it dishonestly, or the file is under 1 MiB |
 | `stallTimeoutS` | `30` | abort after this long with no data |
 | `insecureTls` | `false` | skip TLS verification (corporate TLS interception only) |
 | `allowOutsideWorkspace` | `false` | allow `save_path` outside the workspace and download directory |
@@ -351,7 +359,7 @@ The core (rule engine, CN data, loopback mixed proxy, node transports, subscript
 
 ```bash
 npm install
-node test/smoke.mjs      # 366 checks: rules / subscriptions / profile import / routing / HTTP client / end-to-end / session guard / token gate
+node test/smoke.mjs      # 406 checks: rules / subscriptions / profile import / routing / HTTP client / end-to-end / session guard / token gate
 node --check lib/client.js
 npm pack
 ```

package/README.md

@@ -6,10 +6,11 @@
 
 简体中文 | [English](README.en.md)
 
-![Version](https://img.shields.io/badge/version-0.5.2-4c7ef3?style=flat-square)
+![Version](https://img.shields.io/badge/version-0.6.0-4c7ef3?style=flat-square)
+![npm](https://img.shields.io/npm/v/@having5548/dsh-downloader?style=flat-square&label=npm)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0078d6?style=flat-square)
 ![Protocols](https://img.shields.io/badge/nodes-ss%20%7C%20trojan%20%7C%20vless%20%7C%20vmess%20%7C%20socks5%20%7C%20http-2b6cb0?style=flat-square)
-![Tests](https://img.shields.io/badge/tests-366%20passed-2fa95e?style=flat-square)
+![Tests](https://img.shields.io/badge/tests-406%20passed-2fa95e?style=flat-square)
 ![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)
 
 </div>
@@ -50,20 +51,27 @@ NO_PROXY=localhost,127.0.0.1,::1,deepseek.com,.deepseek.com
 
 ## 📦 安装
 
+从 npm 安装（已发布到官方源）：
+
+```bash
+dsh plugin --profile desktop add @having5548/dsh-downloader
+```
+
 从 GitHub Release 安装：
 
 ```bash
-dsh plugin --profile desktop add https://github.com/having5548/dsh-downloader/releases/latest/download/having5548-dsh-downloader-0.5.2.tgz
+dsh plugin --profile desktop add https://github.com/having5548/dsh-downloader/releases/latest/download/having5548-dsh-downloader-0.6.0.tgz
 ```
 
 本地打包安装：
 
 ```bash
 npm pack
-dsh plugin --profile desktop add having5548-dsh-downloader-0.5.2.tgz
+dsh plugin --profile desktop add having5548-dsh-downloader-0.6.0.tgz
 ```
 
 > profile 名：新版桌面端是 `desktop`，旧版 Web 端是 `web`。
+> npm 页面上显示的 README 是**发布那一刻**的版本 —— 后来改的文档要等下一次发版才会同步过去。
 
 装完打开 **设置 → 下载代理**。
 
@@ -356,7 +364,7 @@ dsh_run_proxied({ command: "git clone https://github.com/x/y.git" })
 
 ```bash
 npm install
-node test/smoke.mjs      # 366 项：规则引擎 / 订阅解析 / 配置导入 / 路由 / HTTP 客户端 / 端到端下载 / 会话守卫 / 令牌鉴权
+node test/smoke.mjs      # 406 项：规则引擎 / 订阅解析 / 配置导入 / 路由 / HTTP 客户端 / 端到端下载 / 会话守卫 / 令牌鉴权
 node --check lib/client.js
 npm pack
 ```

package/lib/core/harness-proxy.js

@@ -0,0 +1,192 @@
+/**
+ * [dsh-downloader] 把内核开放给 harness 自身的出网。
+ *
+ * 默认情况下内核只用「本进程随机令牌」保护，只服务本插件自己的下载。开启
+ * `harnessProxy` 之后：
+ *   1. 内核绑一个**固定端口**（`.env` 里要写死它，随机端口没法指）；
+ *   2. 额外接受一个**持久化令牌**（重启不变，否则每次重启都 407）；
+ *   3. 把 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` 写进 `$DSH_HOME/.env`，
+ *      DSH 启动时会据此装全局 dispatcher，并把变量传给子进程。
+ *
+ * 覆盖范围：`web_fetch`、shell 子进程（curl/git/npm）、MCP 的 HTTP 传输、
+ * 以及 jobs/workflow/subagent 派生的进程。
+ * **覆盖不到**：Electron 渲染进程/内嵌 webview —— Chromium 读的是**系统代理**，
+ * 不读环境变量。
+ *
+ * 本模块只碰自己那 6 个 `*_PROXY` 变量与 `NO_PROXY`，其它行一律不动；写前备份。
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { LOOPBACK_NO_PROXY, composeNoProxy, readNoProxy, splitEntries } from "./session-guard.js";
+
+/** 内核固定端口的默认值。 */
+export const DEFAULT_HARNESS_PORT = 17890;
+
+/** 持久化令牌的文件名（放在插件数据目录里）。 */
+export const HARNESS_TOKEN_FILE = "harness-token.txt";
+
+/** 我们会写入/清除的 `.env` 键。大小写各一份，兼容只认其中一种的程序。 */
+export const HARNESS_ENV_KEYS = [
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"ALL_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"all_proxy"
+];
+
+function tokenPath(dataDir) {
+	return join(dataDir, HARNESS_TOKEN_FILE);
+}
+
+/**
+ * 读取持久化令牌；不存在时生成一个。
+ * @param dataDir - 插件数据目录。
+ * @param create - false 时只读，不存在返回 null（用于 `status` 不改磁盘）。
+ */
+export function loadHarnessToken(dataDir, { create = true } = {}) {
+	const file = tokenPath(dataDir);
+	try {
+		const raw = readFileSync(file, "utf8").trim();
+		if (/^[0-9a-f]{32,}$/i.test(raw)) return raw;
+	} catch {
+		// 不存在或读不了 —— 下面按需生成。
+	}
+	if (!create) return null;
+	const token = randomBytes(24).toString("hex");
+	mkdirSync(dataDir, { recursive: true });
+	writeFileSync(file, `${token}\n`, { encoding: "utf8", mode: 0o600 });
+	return token;
+}
+
+/** 令牌文件路径，供调用方展示。 */
+export function harnessTokenFile(dataDir) {
+	return tokenPath(dataDir);
+}
+
+/** 删掉持久化令牌（关闭开放时可选）。 */
+export function deleteHarnessToken(dataDir) {
+	try {
+		unlinkSync(tokenPath(dataDir));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** 拼出写进 `.env` 的代理地址：`http://dsh:<令牌>@127.0.0.1:<端口>`。 */
+export function buildHarnessProxyUrl({ port, token }) {
+	if (!Number.isInteger(port) || port <= 0) throw new Error("端口无效");
+	if (typeof token !== "string" || token.length === 0) throw new Error("令牌无效");
+	return `http://dsh:${token}@127.0.0.1:${port}`;
+}
+
+/** 从 `.env` 正文里读出现有的 `HTTP_PROXY` 值（没有则 null）。 */
+export function readHarnessProxyUrl(content) {
+	for (const line of String(content).split(/\r?\n/)) {
+		const match = /^\s*http_proxy\s*=\s*(.*)$/i.exec(line);
+		if (match !== null) return match[1].trim() || null;
+	}
+	return null;
+}
+
+/** `.env` 里是否已经有我们写的那几个 `*_PROXY` 键。 */
+export function hasHarnessProxyEnv(content) {
+	const keys = new Set(HARNESS_ENV_KEYS.map((key) => key.toLowerCase()));
+	for (const line of String(content).split(/\r?\n/)) {
+		const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+		if (match !== null && keys.has(match[1].toLowerCase())) return true;
+	}
+	return false;
+}
+
+/** 把 6 个 `*_PROXY` 行摘掉（保留其它所有行）。 */
+export function stripHarnessProxyEnv(content) {
+	const keys = new Set(HARNESS_ENV_KEYS.map((key) => key.toLowerCase()));
+	const kept = String(content)
+		.split(/\r?\n/)
+		.filter((line) => {
+			const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+			if (match === null) return true;
+			return !keys.has(match[1].toLowerCase());
+		});
+	return kept.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+/** 写入或替换 6 个 `*_PROXY` 行。 */
+export function upsertHarnessProxyEnv(content, url) {
+	const keys = new Set(HARNESS_ENV_KEYS.map((key) => key.toLowerCase()));
+	const seen = new Set();
+	const lines = [];
+	for (const line of String(content).split(/\r?\n/)) {
+		const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+		if (match !== null && keys.has(match[1].toLowerCase())) {
+			const key = HARNESS_ENV_KEYS.find((candidate) => candidate.toLowerCase() === match[1].toLowerCase());
+			if (seen.has(key)) continue;
+			seen.add(key);
+			lines.push(`${key}=${url}`);
+			continue;
+		}
+		lines.push(line);
+	}
+	for (const key of HARNESS_ENV_KEYS) {
+		if (!seen.has(key)) lines.push(`${key}=${url}`);
+	}
+	return lines.join("\n");
+}
+
+function backup(envPath, stamp) {
+	const suffix = stamp ?? new Date().toISOString().replace(/[:.]/g, "-");
+	const backupPath = `${envPath}.bak-${suffix}`;
+	copyFileSync(envPath, backupPath);
+	return backupPath;
+}
+
+/**
+ * 把内核地址写进 `$DSH_HOME/.env`。
+ *
+ * `NO_PROXY` 会被补上**回环 + 国内 AI 平台域名**：前者避免「代理指向自己」的死循环，
+ * 后者保证代理抖动时模型长连接不走代理（否则会话会断）。
+ */
+export function writeHarnessProxyEnv({ envPath, url, directDomains = [], stamp }) {
+	const exists = existsSync(envPath);
+	const previous = exists ? readFileSync(envPath, "utf8") : "";
+	let backupPath = null;
+	if (exists) backupPath = backup(envPath, stamp);
+	let next = upsertHarnessProxyEnv(previous, url);
+	const noProxyDomains = [...LOOPBACK_NO_PROXY, ...directDomains];
+	const noProxy = composeNoProxy(readNoProxy(next), noProxyDomains);
+	const withoutNoProxy = next
+		.split(/\r?\n/)
+		.filter((line) => !/^\s*no_proxy\s*=/i.test(line));
+	next = `${withoutNoProxy.join("\n").replace(/\n+$/, "")}\nNO_PROXY=${noProxy}\nno_proxy=${noProxy}\n`;
+	writeFileSync(envPath, next, "utf8");
+	return { changed: true, envPath, backupPath, url, noProxy, previous };
+}
+
+/** 从 `.env` 里撤掉我们写的东西（`NO_PROXY` 保留，它只影响不走代理的域名）。 */
+export function clearHarnessProxyEnv({ envPath, stamp }) {
+	if (!existsSync(envPath)) return { changed: false, envPath, backupPath: null };
+	const previous = readFileSync(envPath, "utf8");
+	if (!hasHarnessProxyEnv(previous)) return { changed: false, envPath, backupPath: null, previous };
+	const backupPath = backup(envPath, stamp);
+	writeFileSync(envPath, stripHarnessProxyEnv(previous), "utf8");
+	return { changed: true, envPath, backupPath, previous };
+}
+
+/** 只读检查：`.env` 现在指向哪、和期望值是否一致。 */
+export function inspectHarnessProxy({ envPath, expectedUrl }) {
+	const exists = existsSync(envPath);
+	const content = exists ? readFileSync(envPath, "utf8") : "";
+	const current = readHarnessProxyUrl(content);
+	return {
+		envPath,
+		exists,
+		current,
+		expected: expectedUrl ?? null,
+		matches: expectedUrl === null ? current !== null : current === expectedUrl,
+		hasProxyVars: hasHarnessProxyEnv(content),
+		noProxy: readNoProxy(content)
+	};
+}

package/lib/core/proxy-server.js

@@ -51,7 +51,7 @@ function pipeSockets(source, target, counter) {
 export class ProxyServer {
 	#engine;
 	#resolveNode;
-	#token = null;
+	#tokens = new Set();
 	#server = null;
 	#port = 0;
 	/** @type {{up: number, down: number}} */
@@ -65,15 +65,19 @@ export class ProxyServer {
 	 * that present it are served; every other connection is refused, so nothing
 	 * outside the owning plugin can borrow this listener as a proxy.
 	 */
-	constructor({ engine, resolveNode, token = null }) {
+	constructor({ engine, resolveNode, token = null, tokens = [] }) {
 		this.#engine = engine;
 		this.#resolveNode = resolveNode;
-		this.#token = typeof token === "string" && token.length > 0 ? token : null;
+		// [dsh-downloader] 接受**多个**令牌：本进程的随机令牌（本插件自己的下载）
+		// 与可选的持久化令牌（`harnessProxy` 开启后给 harness 自身出网用）。
+		for (const candidate of [token, ...tokens]) {
+			if (typeof candidate === "string" && candidate.length > 0) this.#tokens.add(candidate);
+		}
 	}
 
 	/** Whether this listener is token-gated. */
 	get gated() {
-		return this.#token !== null;
+		return this.#tokens.size > 0;
 	}
 
 	/** Bound loopback port (0 until started). */
@@ -87,12 +91,20 @@ export class ProxyServer {
 	 * `Basic dsh:<token>` form (what `curl -x dsh:<token>@…` would send) count.
 	 */
 	#authorized(headers) {
-		if (this.#token === null) return true;
+		if (this.#tokens.size === 0) return true;
 		const raw = headers["proxy-authorization"];
 		if (typeof raw !== "string" || raw.length === 0) return false;
-		if (raw === `Bearer ${this.#token}`) return true;
-		const expectedBasic = `Basic ${Buffer.from(`dsh:${this.#token}`).toString("base64")}`;
-		return raw === expectedBasic;
+		if (raw.startsWith("Bearer ")) {
+			return this.#tokens.has(raw.slice("Bearer ".length));
+		}
+		if (raw.startsWith("Basic ")) {
+			const decoded = Buffer.from(raw.slice("Basic ".length), "base64").toString("utf8");
+			// 形如 `dsh:<令牌>`
+			const colon = decoded.indexOf(":");
+			if (colon < 0) return false;
+			return this.#tokens.has(decoded.slice(colon + 1));
+		}
+		return false;
 	}
 
 	/** Start listening on 127.0.0.1. @returns the bound port. */
@@ -122,7 +134,7 @@ export class ProxyServer {
 				// [dsh-downloader] A SOCKS5 greeting cannot carry the token, so a
 				// gated listener refuses the protocol outright instead of serving
 				// an unauthenticated caller. This plugin's own client uses CONNECT.
-				if (this.#token !== null) {
+				if (this.#tokens.size > 0) {
 					client.end(Buffer.from([0x05, 0xff]));
 					return;
 				}
@@ -151,7 +163,14 @@ export class ProxyServer {
 		}).catch(() => client.destroy());
 		client.on("data", (chunk) => {
 			this.counters.up += chunk.length;
-			face.write(chunk);
+			// [dsh-downloader] 上游可能已经断了（连接器进程退出、socket 被销毁）。
+			// 写入必须兜住：让它抛出去就是未捕获异常，会崩掉整个宿主进程。
+			try {
+				face.write(chunk);
+			} catch {
+				try { face.close(); } catch { /* already gone */ }
+				client.destroy();
+			}
 		});
 		client.on("end", () => face.close());
 		client.on("close", () => face.close());

package/lib/core/transports.js

@@ -552,6 +552,60 @@ export function hasNativeConnector() {
 	try { return existsSync(CONNECTOR_PATH); } catch { return false; }
 }
 
+/**
+ * Wrap a spawned connector's stdio as a duplex face.
+ *
+ * [dsh-downloader] 这三根管道**必须**在第一时间挂上 `error` 监听。连接器进程一死，
+ * 管道就断了，之后任何一次 `write` 都会让 `child.stdin` 抛出 `EPIPE`；而在 Node 里
+ * **没有监听者的 `error` 事件是未捕获异常**，会直接把宿主进程带走 ——
+ * 实测把 DSH 宿主崩掉两次（crash-2026-10-11T03-46 / 03-48，栈就落在下面这行 write）。
+ *
+ * 另外 `ended` 标志挡不住这个竞态：`write` 可能排在一个已经断掉的管道上，
+ * 而 `exit` 事件还没派发。所以写入本身也要兜住。
+ *
+ * 导出只为测试：生产路径只有 `nativeConnect` 调用它。
+ */
+export function stdioFace(child) {
+	let ended = false;
+	let stderrTail = "";
+	const markEnded = () => {
+		ended = true;
+	};
+
+	child.stdin.on("error", markEnded);
+	child.stdout.on("error", markEnded);
+	child.stderr.on("error", markEnded);
+	child.on("error", markEnded);
+	child.on("exit", markEnded);
+	child.stderr.on("data", (chunk) => {
+		stderrTail = (stderrTail + chunk.toString()).slice(-512);
+	});
+
+	return {
+		read: (async function* () {
+			for await (const chunk of child.stdout) {
+				yield chunk;
+			}
+		})(),
+		write: (data) => {
+			if (ended) return;
+			try {
+				child.stdin.write(data);
+			} catch {
+				// 管道已断（连接器已退出）：丢掉这一块，绝不让它冒泡成未捕获异常。
+				ended = true;
+			}
+		},
+		close: () => {
+			try { child.stdin.end(); } catch { /* already closed */ }
+			try { child.stdout.destroy(); } catch { /* already closed */ }
+			if (!ended) setTimeout(() => child.kill(), 500);
+		},
+		/** 连接器最后的 stderr，排查「节点为什么连不上」时有用。 */
+		stderrTail: () => stderrTail
+	};
+}
+
 /**
  * Connect through the self-compiled Go connector via stdio: stdin feeds the
  * remote target, stdout carries the reply. Supports `hysteria2` and `reality`.
@@ -581,28 +635,7 @@ function nativeConnect(proto, node, host, port) {
 		stdio: ["pipe", "pipe", "pipe"],
 		windowsHide: true
 	});
-	let ended = false;
-	let stderrTail = "";
-	child.stderr.on("data", (chunk) => {
-		stderrTail = (stderrTail + chunk.toString()).slice(-512);
-	});
-	child.on("exit", () => { ended = true; });
-
-	return {
-		read: (async function* () {
-			for await (const chunk of child.stdout) {
-				yield chunk;
-			}
-		})(),
-		write: (data) => {
-			if (!ended) child.stdin.write(data);
-		},
-		close: () => {
-			try { child.stdin.end(); } catch { /* already closed */ }
-			try { child.stdout.destroy(); } catch { /* already closed */ }
-			if (!ended) setTimeout(() => child.kill(), 500);
-		}
-	};
+	return stdioFace(child);
 }
 
 /**

package/lib/core/upstream.js

@@ -30,6 +30,7 @@ import { composeDirectDomains, directRuleLines } from "./ai-domains.js";
 import { applyGuard, composeNoProxy, envFilePath, inspectGuard, restoreGuard } from "./session-guard.js";
 import { ProfileStore, parseImportLink } from "./profiles.js";
 import { buildProxyUrl } from "./shell-proxy.js";
+import { DEFAULT_HARNESS_PORT, buildHarnessProxyUrl, loadHarnessToken } from "./harness-proxy.js";
 
 /** Node types the vendored transports implement. */
 const SUPPORTED_TYPES = new Set(["http", "socks5", "socks", "ss", "trojan", "vless", "vmess", "hysteria2"]);
@@ -688,11 +689,46 @@ export class UpstreamManager {
 		this.#state = "no-subscription";
 	}
 
+	/**
+	 * [dsh-downloader] `harnessProxy` 开启时的端口与持久化令牌，否则 null。
+	 * 令牌必须持久化：`.env` 里要写死它，随机令牌每次重启都会失效。
+	 */
+	#harnessOptions(config) {
+		if (config?.harnessProxy !== true) return null;
+		const token = loadHarnessToken(this.dataDir);
+		const port = Number.isInteger(config.harnessProxyPort) && config.harnessProxyPort > 0
+			? config.harnessProxyPort
+			: DEFAULT_HARNESS_PORT;
+		return { token, port, url: buildHarnessProxyUrl({ port, token }) };
+	}
+
+	/** 绑固定端口；被占用时退回随机端口（此时 harnessProxy 实际不生效）。 */
+	async #listenCore(harness) {
+		if (harness === null) return await this.#server.start(0);
+		try {
+			return await this.#server.start(harness.port);
+		} catch (error) {
+			if (error?.code !== "EADDRINUSE") throw error;
+			this.#ctx.logger?.warn?.(
+				"dsh-downloader: 固定端口 %d 被占用，退回随机端口 —— harnessProxy 这一次不生效",
+				harness.port
+			);
+			return await this.#server.start(0);
+		}
+	}
+
 	/** Start the loopback rule core and its timers. */
 	async #startCore() {
+		const config = this.#resolveConfig();
+		const harness = this.#harnessOptions(config);
 		try {
-			this.#server = new ProxyServer({ engine: this.#engine, resolveNode: () => this.#currentNode(), token: this.#scopeToken });
-			this.#port = await this.#server.start(0);
+			this.#server = new ProxyServer({
+				engine: this.#engine,
+				resolveNode: () => this.#currentNode(),
+				token: this.#scopeToken,
+				tokens: harness === null ? [] : [harness.token]
+			});
+			this.#port = await this.#listenCore(harness);
 			this.#state = "running";
 			this.#scheduleTimers(this.#resolveConfig());
 			this.#ctx.logger?.info?.("dsh-downloader: rule core listening on 127.0.0.1:%d (%s)", this.#port, this.#mode);

package/lib/index.js

@@ -23,6 +23,14 @@ import { homedir } from "node:os";
 import { UpstreamManager } from "./core/upstream.js";
 import { AI_DIRECT_DOMAINS, composeDirectDomains, normalizeDomain } from "./core/ai-domains.js";
 import { applyGuard, envFilePath, inspectGuard, restoreGuard } from "./core/session-guard.js";
+import {
+	DEFAULT_HARNESS_PORT,
+	buildHarnessProxyUrl,
+	clearHarnessProxyEnv,
+	inspectHarnessProxy,
+	loadHarnessToken,
+	writeHarnessProxyEnv
+} from "./core/harness-proxy.js";
 import { buildShellPrefix, buildShellToolArguments, classifyShellCommand, explainShellRouting } from "./core/shell-proxy.js";
 import { resolveAuth, sanitizeHeaders } from "./download/auth.js";
 import { decideRoute, NoUpstreamError } from "./download/route.js";
@@ -105,6 +113,8 @@ const Config = z.object({
 	threads: z.number().min(1).max(32).default(4).description("多线程下载的分片连接数；1 = 单连接。服务端不支持 Range 时自动回退单连接").volatile(),
 	insecureTls: z.boolean().default(false).description("跳过 TLS 证书校验（仅企业 TLS 解密环境需要）").volatile(),
 	allowOutsideWorkspace: z.boolean().default(false).description("允许 save_path 写到工作区与配置的下载目录之外").volatile(),
+	harnessProxy: z.boolean().default(false).description("把内核开放给 harness 自身的出网（web_fetch / shell 子进程 / MCP 的 HTTP）。用 dsh_harness_proxy 写入 .env 后重启生效").volatile(),
+	harnessProxyPort: z.number().step(1).min(1024).max(65535).default(17890).description("harness 出网用的固定端口 —— .env 里要写死，所以不能随机；被占用时自动退回随机端口（此时开放不生效）").volatile(),
 	maxRedirects: z.number().step(1).min(0).max(30).default(10).description("最多跟随多少次重定向").volatile()
 });
 
@@ -752,6 +762,84 @@ function apply(ctx, config) {
 		})
 	);
 
+	// ---- dsh_harness_proxy -------------------------------------------------
+	disposers.push(
+		ctx.tools.register({
+			name: "dsh_harness_proxy",
+			description:
+				"让 harness 自身的出网也走本插件的代理内核（而不只是 dsh_download）。" +
+				"开启后覆盖 web_fetch、shell 子进程里的 curl/git/npm、MCP 的 HTTP 传输、以及 jobs/workflow/subagent 派生的进程；" +
+				"**覆盖不到** Electron 渲染进程与内嵌 webview（Chromium 读系统代理，不读环境变量）。" +
+				"做法是把内核绑到固定端口、加一个持久化令牌，再写进 $DSH_HOME/.env 的 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY（写前备份），" +
+				"所以**写入后要重启 DSH 才生效**。国内 AI 平台域名会自动进 NO_PROXY，保证会话不被代理抖动带断。" +
+				"status 只读；apply 写入；remove 撤掉。",
+			parameters: {
+				type: "object",
+				properties: {
+					action: { type: "string", enum: ["status", "apply", "remove"], description: "status（默认）只读；apply 写 .env（需重启）；remove 撤掉那几行。" }
+				},
+				additionalProperties: false
+			},
+			output: { schema: OBJECT_OUTPUT_SCHEMA, render: (_args, value) => renderHarnessProxy(value) },
+			isConcurrencySafe: () => true,
+			presentCall: (args) => ({ card: "generic", kind: "other", title: `harness 出网代理：${args?.action ?? "status"}` }),
+			presentResult: () => ({ card: "generic", title: "harness 出网代理" }),
+			execute: async (args) => {
+				const section = resolveConfig();
+				const requested = ["status", "apply", "remove"].includes(String(args?.action ?? "status")) ? String(args?.action ?? "status") : "status";
+				const enabled = section.harnessProxy === true;
+				const port = Number.isInteger(section.harnessProxyPort) ? section.harnessProxyPort : DEFAULT_HARNESS_PORT;
+				const envPath = envFilePath(process.env.DSH_HOME);
+				const dataDir = upstream.dataDir;
+				const token = loadHarnessToken(dataDir, { create: requested === "apply" });
+				const expectedUrl = token === null ? null : buildHarnessProxyUrl({ port, token });
+				const domains = composeDirectDomains({
+					protectAiPlatforms: section.protectAiPlatforms !== false,
+					extraDirectDomains: section.extraDirectDomains ?? []
+				});
+				const notes = [];
+				let receipt = null;
+
+				if (requested === "apply") {
+					if (!enabled) notes.push("提示：开关 harnessProxy 还没打开 —— 先到设置里打开它，否则内核不会绑这个固定端口，写进去的地址会连不上。");
+					receipt = writeHarnessProxyEnv({ envPath, url: expectedUrl, directDomains: domains });
+					notes.push("已写入。DSH 只在启动时读一次 $DSH_HOME/.env，**重启 DSH 后生效**。");
+				} else if (requested === "remove") {
+					receipt = clearHarnessProxyEnv({ envPath });
+					if (receipt.changed === true) notes.push("已撤掉代理变量，重启 DSH 后恢复直连。");
+				}
+
+				const state = inspectHarnessProxy({ envPath, expectedUrl });
+				if (requested === "status") {
+					if (!enabled) notes.push("harnessProxy 当前关闭：内核只用随机端口 + 随机令牌，只服务本插件自己的下载。");
+					else if (state.current === null) notes.push('已开启但 .env 里还没有代理变量 —— 用 action="apply" 写入，然后重启。');
+					else if (!state.matches) notes.push("已开启，但 .env 里的地址与当前端口/令牌不一致（换过端口或令牌文件被删）—— 重新 apply 一次。");
+					else notes.push("已开启且 .env 指向当前内核。改过隧道/端口后记得重新 apply。");
+				}
+
+				return {
+					action: requested,
+					enabled,
+					port,
+					core_port: upstream.status().core_port ?? null,
+					core_matches_port: (upstream.status().core_port ?? null) === port,
+					env_path: envPath,
+					env_current: state.current,
+					env_expected: expectedUrl,
+					env_matches: state.matches,
+					has_proxy_vars: state.hasProxyVars,
+					no_proxy_count: state.noProxy.length === 0 ? 0 : state.noProxy.split(",").filter((entry) => entry.length > 0).length,
+					protected_domain_count: domains.length,
+					changed: receipt === null ? null : receipt.changed,
+					backup_path: receipt === null ? null : receipt.backupPath,
+					covers: ["web_fetch", "shell 子进程（curl/git/npm）", "MCP 的 HTTP 传输", "jobs/workflow/subagent 派生的进程"],
+					does_not_cover: ["Electron 渲染进程与内嵌 webview（Chromium 读系统代理）", "系统里其它程序"],
+					notes
+				};
+			}
+		})
+	);
+
 	// ---- dsh_profile -------------------------------------------------------
 	disposers.push(
 		ctx.tools.register({
@@ -1029,6 +1117,27 @@ function apply(ctx, config) {
 }
 
 /** Render a session-guard report. */
+function renderHarnessProxy(value) {
+	const lines = [
+		`**harness 出网代理**：${value.enabled ? "已开启" : "已关闭"}`,
+		value.enabled
+			? `内核端口 ${value.port}（实际 ${value.core_port ?? "未运行"}${value.core_matches_port ? "" : " ⚠️ 与配置不一致"}）`
+			: `内核端口 ${value.core_port ?? "随机（未运行）"}`,
+		value.env_current === null
+			? `\`.env\`：还没有代理变量`
+			: value.env_matches
+				? `\`.env\`：指向当前内核 ✅`
+				: `\`.env\`：与当前不一致 ⚠️`
+	];
+	if (value.changed !== null) {
+		lines.push(`变更：${value.changed ? "已写入" : "无变化"}${value.backup_path ? `（备份 \`${value.backup_path}\`）` : ""}`);
+	}
+	lines.push("", "覆盖：" + value.covers.join("、"));
+	lines.push("覆盖不到：" + value.does_not_cover.join("、"));
+	for (const note of value.notes) lines.push("", `> ${note}`);
+	return lines.join("\n");
+}
+
 function renderGuard(value) {
 	if (value === null || typeof value !== "object") return text(value);
 	const lines = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@having5548/dsh-downloader",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "DeepSeek Harness 下载代理插件：注册 dsh_download 等工具，让模型下载境外文件时自动走插件自带的代理内核（订阅自包含，或显式 proxyUrl），境内直连；带 sha256、大小上限、停滞检测与直连失败自动回退，另附「设置 → 下载代理」管理面板。",
   "keywords": [
     "dsh",
@@ -83,6 +83,7 @@
   },
   "license": "MIT",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   }
 }