dsh-proxy-routing 0.4.1

package/lib/index.js

@@ -0,0 +1,296 @@
+// lib/index.js — dsh-proxy-routing plugin entry (host half)
+//
+// Runtime state is sourced from the official `proxy-routing` settings namespace.
+// The settings-file provider owns `$DSH_HOME/settings.yaml`, YAML parsing,
+// atomic writes, and external change watching.
+import { canonicalDefaults, profileConfigured, serializeCanonical, toProxy, validateCanonical } from "./config.js";
+import { ControlPlane } from "./control.js";
+import { FetchRouter } from "./fetch-router.js";
+import { LlmRouter } from "./llm-router.js";
+import { ShellRouter } from "./shell-router.js";
+import { resolveAgentRoute, resolveProviderRoute } from "./routes.js";
+import { buildStatus } from "./status.js";
+import { probeProxy } from "./probe.js";
+import { registerProxyTools, installApprovalGate } from "./tools.js";
+import { PROXY_ROUTING_NAMESPACE, ProxyRoutingSettingsSchema, settingsUnavailableError } from "./settings.js";
+import { installProxyRpc } from "./rpc.js";
+
+export const name = "proxy-routing";
+export const inject = ["tools", "settings", "subprocess", "systemPrompt"];
+
+const ONBOARDING_SECTION = "proxy-routing:onboarding";
+
+function sessionIsFullAccess(context) {
+  const events = context?.agent?.session?.events;
+  if (Array.isArray(events)) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index];
+      if (event?.type === "sandbox/mode") return event?.data?.mode === "danger-full-access";
+    }
+  }
+  return false;
+}
+
+function onboardingText(scope, context) {
+  const profile = scope.get()?.profiles?.find((entry) => entry?.id === "default");
+  if (!profileConfigured(profile)) {
+    const discovery = sessionIsFullAccess(context)
+      ? "当前会话是 Full Access：先调用 net_proxy_discover，检查代理环境变量和有限的本机候选端口；只使用探测成功且用户确认用途的候选，不要自动启用。"
+      : "当前会话不是 Full Access：不要主动扫描本机或猜测地址；先向用户询问已经运行的 HTTP/SOCKS5 代理 protocol、host、port。";
+    return [
+      "Proxy routing is installed, but the default proxy endpoint is not configured; Agent traffic remains direct.",
+      discovery,
+      "Use net_proxy_probe before requesting net_proxy_enable; enabling changes Agent routing and may require human approval.",
+    ].join(" ");
+  }
+  return [
+    "Proxy routing has a configured default endpoint.",
+    "Use net_proxy_status to inspect the effective route and net_proxy_probe to verify connectivity before troubleshooting network requests.",
+    "Use net_proxy_disable to restore direct Agent routing when needed; provider overrides remain independent.",
+  ].join(" ");
+}
+
+function installOnboarding(ctx, scope) {
+  const systemPrompt = ctx.systemPrompt ?? ctx.get?.("systemPrompt");
+  if (!systemPrompt || typeof systemPrompt.section !== "function") return undefined;
+  return systemPrompt.section({
+    name: ONBOARDING_SECTION,
+    order: 120,
+    text: (context) => onboardingText(scope, context),
+  });
+}
+
+/** DSH composition base; user values live in ctx.settings. */
+export const Config = ProxyRoutingSettingsSchema;
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {object} config Cordis plugin defaults (reserved for compatibility)
+ */
+export function apply(ctx, config = {}) {
+  const settings = ctx.settings ?? ctx.get?.("settings");
+  if (!settings || typeof settings.register !== "function") throw settingsUnavailableError();
+
+  const base = config && typeof config === "object" ? config : {};
+  const scope = settings.register(PROXY_ROUTING_NAMESPACE, ProxyRoutingSettingsSchema, {
+    base,
+    validate: validateCanonical,
+  });
+  const canonical = validateCanonical(scope.get() ?? canonicalDefaults());
+  const logger = ctx.logger ?? console;
+  const log = (level, message) => {
+    try { logger[level]?.(message); } catch {}
+  };
+
+  // Settings writes use the official raw-user-layer APIs. Internal markers are
+  // removed only when the write is known not to have reached storage.
+  const canonicalSignature = (value) => serializeCanonical(validateCanonical(value));
+  const expectedSettingsCommits = [];
+  const markInternalCommit = (value) => {
+    const token = { signature: canonicalSignature(value), durable: false };
+    expectedSettingsCommits.push(token);
+    return token;
+  };
+  const removeInternalCommit = (token) => {
+    const index = expectedSettingsCommits.indexOf(token);
+    if (index >= 0) expectedSettingsCommits.splice(index, 1);
+  };
+  const consumeInternalCommit = (value) => {
+    const signature = canonicalSignature(value);
+    const index = expectedSettingsCommits.findIndex((token) => token.signature === signature);
+    if (index < 0) return false;
+    expectedSettingsCommits.splice(index, 1);
+    return true;
+  };
+  const isObject = (value) => value && typeof value === "object" && !Array.isArray(value);
+  const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+  const readRawSettings = () => {
+    const descriptor = settings.describe?.({ redactSecrets: false })
+      ?.find((entry) => String(entry.ns) === String(PROXY_ROUTING_NAMESPACE));
+    return {
+      section: isObject(descriptor?.user) ? structuredClone(descriptor.user) : {},
+      revision: Number.isInteger(descriptor?.revision) ? descriptor.revision : undefined,
+    };
+  };
+  let rawSettings = readRawSettings();
+
+  ctx.on?.("settings/document-updated", (ns) => {
+    if (String(ns) !== String(PROXY_ROUTING_NAMESPACE)) return;
+    rawSettings = readRawSettings();
+    for (const token of [...expectedSettingsCommits]) {
+      if (canonicalSignature(scope.get()) === token.signature) removeInternalCommit(token);
+    }
+  });
+
+
+  // Turn resolved canonical changes into a sparse raw user section. Profiles
+  // are handled by id/index so their inherited noProxy/timeout defaults are
+  // not materialized merely because another profile field changed.
+  const rawProfilesFor = (beforeProfiles, afterProfiles, currentProfiles) => {
+    const current = Array.isArray(currentProfiles) ? currentProfiles : [];
+    return afterProfiles.map((afterProfile, index) => {
+      const beforeProfile = beforeProfiles[index] ?? {};
+      const currentProfile = current.find((entry) => entry?.id === afterProfile.id) ?? current[index] ?? {};
+      const rawProfile = isObject(currentProfile) ? structuredClone(currentProfile) : {};
+      for (const key of new Set([...Object.keys(beforeProfile), ...Object.keys(afterProfile)])) {
+        if (sameJson(beforeProfile[key], afterProfile[key])) continue;
+        if (key in afterProfile) rawProfile[key] = structuredClone(afterProfile[key]);
+        else delete rawProfile[key];
+      }
+      rawProfile.id = afterProfile.id;
+      return rawProfile;
+    });
+  };
+  const rawObjectFor = (before, after, current) => {
+    const result = isObject(current) ? structuredClone(current) : {};
+    for (const key of new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])) {
+      if (sameJson(before?.[key], after?.[key])) continue;
+      if (!(key in after)) delete result[key];
+      else if (key === "profiles" && Array.isArray(after[key])) {
+        result[key] = rawProfilesFor(before?.[key] ?? [], after[key], current?.[key]);
+      } else if (isObject(before?.[key]) && isObject(after[key])) {
+        result[key] = rawObjectFor(before[key], after[key], current?.[key]);
+      } else {
+        result[key] = structuredClone(after[key]);
+      }
+    }
+    if (after?.version !== undefined && result.version === undefined) result.version = after.version;
+    return result;
+  };
+  const writeSettings = async (next, previous, expectedRevision) => {
+    const before = readRawSettings();
+    const rawNext = rawObjectFor(previous, next, before.section);
+    if (sameJson(rawNext, before.section)) return { before, after: before };
+    const token = markInternalCommit(next);
+    try {
+      if (typeof settings.replace === "function") {
+        await settings.replace(PROXY_ROUTING_NAMESPACE, rawNext, expectedRevision ?? before.revision);
+      } else {
+        await scope.replace(rawNext);
+      }
+      token.durable = true;
+      const after = readRawSettings();
+      rawSettings = after;
+      return { before, after };
+    } catch (error) {
+      const after = readRawSettings();
+      const durable = token.durable || (before.revision !== undefined && after.revision !== before.revision);
+      if (durable) {
+        token.durable = true;
+        error.settingsPersisted = true;
+        error.settingsRevision = after.revision;
+      } else {
+        error.settingsPersisted = false;
+        removeInternalCommit(token);
+      }
+      throw error;
+    }
+  };
+
+  const plane = new ControlPlane({
+    canonical,
+    persist: async (next, previous, capture, expectedSettingsRevision) => {
+      const result = await writeSettings(next, previous, expectedSettingsRevision);
+      capture?.(result.before.section, result.before.revision);
+      return { compensation: result.before.section, revision: result.after.revision };
+    },
+    compensate: async (previousSection, previousCanonical, _failed, expectedRevision) => {
+      const token = markInternalCommit(previousCanonical ?? validateCanonical(previousSection));
+      try {
+        if (typeof settings.replace === "function") {
+          await settings.replace(PROXY_ROUTING_NAMESPACE, previousSection, expectedRevision);
+        } else {
+          await scope.replace(previousSection);
+        }
+        token.durable = true;
+        rawSettings = readRawSettings();
+      } catch (error) {
+        if (!token.durable) removeInternalCommit(token);
+        throw error;
+      }
+    },
+    logger,
+  });
+  const fetchRouter = new FetchRouter({ getAgentRoute: () => resolveAgentRoute(plane.canonical) });
+  const llmRouter = new LlmRouter({
+    getProviderRoute: (providerId) => resolveProviderRoute(plane.canonical, providerId),
+    getAgentRoute: () => resolveAgentRoute(plane.canonical),
+    getRevision: () => plane.revision,
+  });
+  const shellRouter = new ShellRouter({
+    getAgentRoute: () => resolveAgentRoute(plane.canonical),
+    getRevision: () => plane.revision,
+  });
+  plane.addParticipant(fetchRouter);
+  plane.addParticipant(shellRouter);
+
+  const migration = {
+    from: "settings",
+    configured: profileConfigured(canonical.profiles[0]),
+  };
+  const control = {
+    getStatus: () => buildStatus({
+      canonical: plane.canonical,
+      revision: plane.revision,
+      migration,
+      fetchRouter,
+      shellRouter,
+    }),
+    getSettingsRevision: () => rawSettings.revision,
+    mutate: ({ apply: mutate, persist = true, expectedRevision, expectedSettingsRevision }) => plane.mutate({ apply: mutate, persist, expectedRevision, expectedSettingsRevision }),
+    probe: (proxyCfg, opts) => probeProxy(toProxy(proxyCfg), opts),
+  };
+
+  let settingsWatchDispose;
+  let onboardingDispose;
+  let disposed = false;
+  try {
+    settingsWatchDispose = scope.watch((next, previous) => {
+      const previousRaw = rawSettings;
+      rawSettings = readRawSettings();
+      if (disposed || consumeInternalCommit(next)) return;
+      return plane.reloadSettings({
+        next,
+        previous,
+        previousRaw: previousRaw.section,
+        previousRawRevision: rawSettings.revision,
+      }).catch((error) => {
+        log("warn", "[proxy-routing] settings 热更无法应用，已保留上一成功运行状态");
+        throw error;
+      });
+    });
+    onboardingDispose = installOnboarding(ctx, scope);
+    fetchRouter.install();
+    llmRouter.register(ctx);
+    shellRouter.register(ctx);
+    registerProxyTools(ctx, control);
+    installApprovalGate(ctx);
+    installProxyRpc(ctx, control);
+  } catch (error) {
+    settingsWatchDispose?.();
+    onboardingDispose?.();
+    void llmRouter.dispose();
+    shellRouter.dispose();
+    fetchRouter.dispose();
+    void plane.dispose();
+    throw error;
+  }
+
+  // Test and diagnostics hooks.
+  ctx._proxyControl = control;
+  ctx._proxySettingsScope = scope;
+  ctx._plane = plane;
+
+  log("info", `[proxy-routing] 配置: settings.yaml#proxy-routing（settings，revision ${plane.revision}）`);
+
+  return async () => {
+    if (disposed) return;
+    disposed = true;
+    settingsWatchDispose?.();
+    onboardingDispose?.();
+    await plane.dispose();
+    llmRouter.dispose();
+    shellRouter.dispose();
+    fetchRouter.dispose();
+  };
+}

package/lib/llm-router.js

@@ -0,0 +1,63 @@
+// lib/llm-router.js — llm/stream 惰性迭代器路由。
+// 以 { prepend: true } 注册为最外层 waterfall 中间件；provider→route 在首次
+// 迭代操作时惰性解析（waterfall 已同步完成，任何改写 options.provider 的
+// 中间件都已在场）；next/return/throw 全部在 AsyncLocalStorage 上下文内执行，
+// 取消/错误/提前 return 均不泄漏上下文。
+import { providerStore } from "./als.js";
+
+/** 惰性异步迭代器包装：上下文只解析一次、迭代器只创建一次。 */
+export function wrapAsyncIterable(resolveContext, sourceFactory) {
+  let context;
+  let iterator;
+  const run = (op) => {
+    if (!context) context = resolveContext();
+    if (!iterator) iterator = sourceFactory()[Symbol.asyncIterator]();
+    return providerStore.run(context, () => op(iterator));
+  };
+  return {
+    [Symbol.asyncIterator]() {
+      return {
+        next: () => run((it) => it.next()),
+        return: () => run((it) => (it.return ? it.return() : Promise.resolve({ done: true }))),
+        throw: (error) => run((it) => (it.throw ? it.throw(error) : Promise.reject(error))),
+      };
+    },
+  };
+}
+
+export class LlmRouter {
+  /**
+   * @param {object} deps
+   * @param {(providerId:string)=>object} deps.getProviderRoute provider 路由快照
+   * @param {()=>object} deps.getAgentRoute Agent 路由快照
+   * @param {()=>number} deps.getRevision 当前配置修订号
+   */
+  constructor({ getProviderRoute, getAgentRoute, getRevision }) {
+    this.name = "llm-router";
+    this.getProviderRoute = getProviderRoute;
+    this.getAgentRoute = getAgentRoute;
+    this.getRevision = getRevision;
+    this.generation = 0;
+  }
+
+  listener = (options, next) => {
+    const generation = ++this.generation;
+    return wrapAsyncIterable(() => this.resolve(options, generation), () => next());
+  };
+
+  resolve(options, generation) {
+    const provider = options && typeof options.provider === "string" ? options.provider : null;
+    const route = provider ? this.getProviderRoute(provider) : this.getAgentRoute();
+    return { route, provider, revision: this.getRevision(), generation };
+  }
+
+  /** 注册 waterfall 监听（prepend → 最外层包裹）。 */
+  register(ctx) {
+    this.disposeListener = ctx.on("llm/stream", this.listener, { prepend: true });
+  }
+
+  dispose() {
+    this.disposeListener?.();
+    this.disposeListener = undefined;
+  }
+}

package/lib/probe.js

@@ -0,0 +1,68 @@
+// lib/probe.js — 代理连通性 + 延迟探测（不改配置）
+//
+// probeProxy(proxy, opts)：
+//   1. TCP 连代理（测代理可达 + TCP 延迟）
+//   2. 经代理请求目标（测完整链路 + HTTP 状态）
+// 返回 { ok, connectMs, totalMs, httpStatus, target, error? }
+import net from "node:net";
+import { proxiedFetch } from "./proxy/request.js";
+
+/** 默认探测目标：Google 的 204 端点（轻量、全球可达性好）。 */
+const DEFAULT_TARGET = "https://www.gstatic.com/generate_204";
+
+/**
+ * 对配置的代理做一次连通 + 延迟探测。
+ * @param {{protocol:string,host:string,port:number,username?:string,password?:string,noProxy?:string[],timeout?:number}} proxy
+ * @param {{target?:string, timeout?:number, signal?:AbortSignal}} [opts]
+ */
+export async function probeProxy(proxy, { target = DEFAULT_TARGET, timeout = 15000, signal } = {}) {
+  const res = { ok: false, target, connectMs: -1, totalMs: -1, httpStatus: -1 };
+  const t0 = performance.now();
+  try {
+    // 1) TCP 到代理
+    await new Promise((resolve, reject) => {
+      const sock = net.connect({ host: proxy.host, port: proxy.port });
+      const timer = setTimeout(() => {
+        try { sock.destroy(); } catch {}
+        reject(new Error("proxy TCP timeout"));
+      }, timeout);
+      const onAbort = () => {
+        clearTimeout(timer);
+        try { sock.destroy(); } catch {}
+        reject(Object.assign(new Error("aborted"), { code: "ABORT_ERR", name: "AbortError" }));
+      };
+      if (signal) {
+        if (signal.aborted) {
+          clearTimeout(timer);
+          try { sock.destroy(); } catch {}
+          return reject(Object.assign(new Error("aborted"), { code: "ABORT_ERR", name: "AbortError" }));
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      sock.once("connect", () => {
+        clearTimeout(timer);
+        if (signal) signal.removeEventListener("abort", onAbort);
+        res.connectMs = Math.round(performance.now() - t0);
+        try { sock.destroy(); } catch {}
+        resolve();
+      });
+      sock.once("error", (e) => {
+        clearTimeout(timer);
+        if (signal) signal.removeEventListener("abort", onAbort);
+        reject(e);
+      });
+    });
+
+    // 2) 经代理请求目标
+    const r = await proxiedFetch(target, { method: "GET", signal }, proxy, globalThis.fetch);
+    res.httpStatus = r.status;
+    res.totalMs = Math.round(performance.now() - t0);
+    res.ok = res.httpStatus < 400;
+    if (!res.ok) res.error = `target returned HTTP ${res.httpStatus}`;
+  } catch (e) {
+    res.totalMs = Math.round(performance.now() - t0);
+    if (e && e.code === "ABORT_ERR") res.error = "aborted";
+    else res.error = (e && e.message) || String(e);
+  }
+  return res;
+}

package/lib/proxy/connect.js

@@ -0,0 +1,166 @@
+// lib/proxy/connect.js — 代理底层连接：TCP 连接代理 → HTTP CONNECT / SOCKS5 隧道
+//
+// 两种隧道都返回"已与目标建立通道"的裸 socket，供上层做 TLS（HTTPS 目标）
+// 或直接发 HTTP/1.1 请求（HTTP 目标）。握手期间支持 AbortSignal 取消与
+// 空闲超时；CONNECT 读完整有界头块并把随响应一同到达的早字节回灌 socket。
+import net from "node:net";
+import { proxyError, abortError } from "./errors.js";
+import { parseStatusLine } from "./parse.js";
+import { ByteStream } from "./stream.js";
+
+/** CONNECT 响应头块上限（含状态行，超限视为畸形）。 */
+export const MAX_CONNECT_HEADERS = 64 * 1024;
+
+/**
+ * TCP 连接代理服务器（可取消、可设连接超时）。
+ * @param {{host:string,port:number}} proxy
+ * @param {AbortSignal} [signal]
+ * @param {{connectTimeoutMs?:number}} [opts]
+ * @returns {Promise<import("node:net").Socket>}
+ */
+export function connectProxy(proxy, signal, { connectTimeoutMs = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const sock = net.connect({ host: proxy.host, port: proxy.port });
+    sock.setNoDelay(true);
+    let settled = false;
+    const timer = connectTimeoutMs > 0
+      ? setTimeout(() => {
+          try { sock.destroy(); } catch {}
+          done(proxyError("ECONNECT_PROXY", `proxy connect ${proxy.host}:${proxy.port} timed out`));
+        }, connectTimeoutMs)
+      : null;
+    timer?.unref?.();
+    const done = (err, val) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      err ? reject(err) : resolve(val);
+    };
+    const onAbort = () => {
+      try { sock.destroy(); } catch {}
+      done(abortError());
+    };
+    if (signal) {
+      if (signal.aborted) {
+        try { sock.destroy(); } catch {}
+        return done(abortError());
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    sock.once("connect", () => done(null, sock));
+    sock.once("error", (e) => done(proxyError("ECONNECT_PROXY", `proxy connect ${proxy.host}:${proxy.port} failed: ${e.message}`, e)));
+  });
+}
+
+/** Proxy-Authorization 头（仅当配置了凭据）。 */
+function proxyAuthHeader(proxy) {
+  if (!proxy.username && !proxy.password) return "";
+  return "Proxy-Authorization: Basic " + Buffer.from(`${proxy.username || ""}:${proxy.password || ""}`).toString("base64") + "\r\n";
+}
+
+/**
+ * HTTP 代理 CONNECT 隧道（HTTPS 目标）。成功返回已通到目标的裸 socket。
+ * 读完整有界头块；状态行后随响应到达的隧道早字节通过 unshift 回灌 socket。
+ * @param {{host:string,port:number,username?:string,password?:string}} proxy
+ * @param {string} targetHost
+ * @param {number} targetPort
+ * @param {AbortSignal} [signal]
+ * @param {{handshakeTimeoutMs?:number}} [opts]
+ */
+export async function httpConnect(proxy, targetHost, targetPort, signal, { handshakeTimeoutMs = 15000 } = {}) {
+  const sock = await connectProxy(proxy, signal);
+  const authority = `${targetHost}:${targetPort}`;
+  const stream = new ByteStream(sock, { idleMs: handshakeTimeoutMs });
+  try {
+    sock.write(`CONNECT ${authority} HTTP/1.1\r\nHost: ${authority}\r\n${proxyAuthHeader(proxy)}\r\n`);
+    const statusLine = await stream.readLine();
+    const status = parseStatusLine(statusLine);
+    if (status === 0) throw proxyError("EPARSE", `malformed CONNECT status line: ${statusLine.slice(0, 80)}`);
+
+    // 完整有界头块（直到空行）；累计超限视为畸形响应
+    let headerBytes = statusLine.length + 2;
+    for (;;) {
+      const line = await stream.readLine();
+      headerBytes += line.length + 2;
+      if (headerBytes > MAX_CONNECT_HEADERS) throw proxyError("EHEADER", "CONNECT response headers too large");
+      if (line === "") break;
+    }
+
+    if (!(status >= 200 && status < 300)) {
+      stream.detach();
+      try { sock.destroy(); } catch {}
+      throw proxyError("ECONNECT_TARGET", `CONNECT to ${authority} via proxy failed: HTTP ${status}`);
+    }
+
+    // 头块之后的剩余字节 = 隧道早字节：暂停并 unshift 回 readable 队列，
+    // 让后续 TLS 消费者先读到它们。
+    const early = stream.takeBuf();
+    stream.detach();
+    if (early.length > 0) {
+      try { sock.pause(); } catch {}
+      sock.unshift(early);
+    }
+    return sock;
+  } catch (e) {
+    stream.detach();
+    try { sock.destroy(); } catch {}
+    throw e;
+  }
+}
+
+/**
+ * SOCKS5 隧道：方法协商（支持 RFC 1929 user/pass）→ CONNECT。成功返回裸 socket。
+ * @param {{host:string,port:number,username?:string,password?:string}} proxy
+ * @param {string} targetHost
+ * @param {number} targetPort
+ * @param {AbortSignal} [signal]
+ * @param {{handshakeTimeoutMs?:number}} [opts]
+ */
+export async function socksConnect(proxy, targetHost, targetPort, signal, { handshakeTimeoutMs = 15000 } = {}) {
+  const sock = await connectProxy(proxy, signal);
+  const fail = (msg) => {
+    try { sock.destroy(); } catch {}
+    throw proxyError("ECONNECT_TARGET", msg);
+  };
+  // 主机名长度上限：在任何协议 I/O 之前快速失败
+  const hostBuf = Buffer.from(targetHost, "utf8");
+  if (hostBuf.length > 255) return fail(`SOCKS5: hostname too long (${hostBuf.length} bytes, max 255)`);
+  const stream = new ByteStream(sock, { idleMs: handshakeTimeoutMs });
+  try {
+    // 方法协商：无凭据 → 0x00 no-auth；有凭据 → 0x02 user/pass
+    const wantAuth = !!(proxy.username || proxy.password);
+    sock.write(Buffer.from([0x05, 0x01, wantAuth ? 0x02 : 0x00]));
+    const verMethod = await stream.readExactly(2);
+    if (verMethod[0] !== 0x05) return fail(`SOCKS5: bad version ${verMethod[0]}`);
+    if (verMethod[1] === 0x02) {
+      const user = Buffer.from(proxy.username || "", "utf8");
+      const pass = Buffer.from(proxy.password || "", "utf8");
+      sock.write(Buffer.concat([Buffer.from([0x01, user.length]), user, Buffer.from([pass.length]), pass]));
+      const authResp = await stream.readExactly(2);
+      if (authResp[0] !== 0x01 || authResp[1] !== 0x00) return fail(`SOCKS5: auth failed (code ${authResp[1]})`);
+    } else if (verMethod[1] !== 0x00) {
+      return fail(`SOCKS5: server requires auth (method ${verMethod[1]})`);
+    }
+    // CONNECT：统一用域名形式 ATYP=0x03（IP 目标同样可表达，避免 IPv4/IPv6 分支）
+    const req = Buffer.alloc(4 + 1 + hostBuf.length + 2);
+    req[0] = 0x05; req[1] = 0x01; req[2] = 0x00; req[3] = 0x03; req[4] = hostBuf.length;
+    hostBuf.copy(req, 5);
+    req.writeUInt16BE(targetPort, 5 + hostBuf.length);
+    sock.write(req);
+    const head = await stream.readExactly(4);
+    if (head[0] !== 0x05 || head[1] !== 0x00) {
+      return fail(`SOCKS5: connect to ${targetHost}:${targetPort} failed, code ${head[1]}`);
+    }
+    // 吃掉 BND.ADDR / BND.PORT（ATYP: 1=IPv4, 4=IPv6, 3=域名）
+    const atyp = head[3];
+    const alen = atyp === 0x01 ? 4 : atyp === 0x04 ? 16 : 1;
+    await stream.readExactly(alen + 2);
+    stream.detach();
+    return sock;
+  } catch (e) {
+    stream.detach();
+    try { sock.destroy(); } catch {}
+    throw e;
+  }
+}

package/lib/proxy/decode.js

@@ -0,0 +1,60 @@
+// lib/proxy/decode.js — 响应体解码 sink：按 content-encoding 建解压流，
+// 把压缩字节流式解压进 ReadableStream controller（HTTP/1.1 与 HTTP/2 共用）。
+// 解压输出设有上限（防 decompression bomb）。
+import { createDecoder } from "./parse.js";
+import { proxyError } from "./errors.js";
+
+/** 解压输出上限（默认 512MB，超过即终止并报错）。 */
+export const DEFAULT_MAX_DECODED = 512 * 1024 * 1024;
+
+/**
+ * 构建「解压流 → ReadableStream controller」的公共 sink。
+ * @param {ReadableStreamDefaultController} controller
+ * @param {string} ce content-encoding（小写；''/unknown → 不解压）
+ * @param {{maxOutputBytes?:number}} [opts]
+ * @returns {{dec:import("node:stream").Transform|null, write:(c:Uint8Array)=>Promise<void>, finish:()=>Promise<void>, destroy:()=>void}}
+ */
+export function makeBodyController(controller, ce, { maxOutputBytes = DEFAULT_MAX_DECODED } = {}) {
+  const dec = createDecoder(ce);
+  let decDoneResolve = null;
+  const decDone = new Promise((r) => (decDoneResolve = r));
+  let closed = false;
+  let outBytes = 0;
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    try { controller.close(); } catch {}
+    decDoneResolve?.();
+  };
+  const onData = (c) => {
+    outBytes += c.length;
+    if (maxOutputBytes > 0 && outBytes > maxOutputBytes) {
+      try { dec?.destroy(); } catch {}
+      try { controller.error(proxyError("EBODY", "decompressed response body exceeds output cap")); } catch {}
+      decDoneResolve?.();
+      return;
+    }
+    try { controller.enqueue(new Uint8Array(c)); } catch {}
+  };
+  if (dec) {
+    dec.on("data", onData);
+    dec.on("end", close);
+    dec.on("error", (e) => { try { controller.error(e); } catch {} decDoneResolve?.(); });
+  }
+  const write = (c) => new Promise((res) => {
+    if (dec) {
+      if (!dec.write(c)) dec.once("drain", () => res());
+      else res();
+    } else {
+      onData(c);
+      res();
+    }
+  });
+  const finish = () => {
+    if (dec) { dec.end(); return decDone; }
+    close();
+    return Promise.resolve();
+  };
+  const destroy = () => { if (dec) { try { dec.destroy(); } catch {} } };
+  return { dec, write, finish, destroy };
+}

package/lib/proxy/errors.js

@@ -0,0 +1,26 @@
+// lib/proxy/errors.js — 通道层结构化错误（纯函数，零依赖）
+//
+// 所有代理相关错误统一带机器可读 `code` 前缀（E*），方便上层（探测、
+// agent 工具）分类展示；取消与超时对齐 fetch 语义（AbortError）。
+
+/** 构造带 code 的错误。 */
+export function proxyError(code, message, cause) {
+  const e = new Error(message);
+  e.code = code;
+  if (cause !== undefined) e.cause = cause;
+  return e;
+}
+
+/** 对齐 fetch 的取消错误（AbortError）。 */
+export function abortError() {
+  const e = new Error("The operation was aborted.");
+  e.name = "AbortError";
+  e.code = "ABORT_ERR";
+  return e;
+}
+
+/** 单请求超时（ms）：配置了 timeout 用之，否则默认 60000。 */
+export function timeoutFor(proxy) {
+  const t = Number(proxy && proxy.timeout);
+  return Number.isFinite(t) && t > 0 ? t : 60000;
+}