@aiwayds/dsh-llm-proxy 0.2.0

package/lib/match.js

@@ -0,0 +1,103 @@
+/**
+ * Origin matcher for the LLM proxy routing list.
+ *
+ * A match pattern is one of:
+ * - a full origin ("https://api.deepseek.org") — case-insensitive exact match
+ *   against the request origin;
+ * - a host authority ("api.deepseek.org", "api.deepseek.org:8443") — matches
+ *   the host exactly, or with a leading `*.` wildcard also any subdomain and
+ *   the bare domain itself ("*.volces.com" matches "volces.com" and
+ *   "a.volces.com"). An explicit port in the pattern must equal the request
+ *   origin's port (scheme defaults count: https=443, http=80).
+ *
+ * All comparisons are lowercase; matching is purely lexical — no DNS, no I/O.
+ * Hostnames are normalized the way WHATWG URL parsing normalizes request
+ * origins: lowercase ASCII with IDN labels converted to punycode, so a
+ * pattern and an origin written in either the unicode or the xn-- form of
+ * the same domain compare equal.
+ */
+const DEFAULT_PORTS = new Map([
+    ['https:', '443'],
+    ['http:', '80'],
+]);
+/**
+ * Canonical origin of a full-origin URL: lowercase scheme/host with IDN
+ * labels punycoded; `undefined` when the value does not parse.
+ */
+function canonicalOrigin(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Normalize a bare hostname (no port, no scheme) the way WHATWG URL parsing
+ * would for a request origin: lowercase ASCII, IDN labels to punycode.
+ * Falls back to plain lowercasing when the value cannot be parsed.
+ */
+function normalizeHost(host) {
+    try {
+        return new URL(`http://${host}`).hostname;
+    }
+    catch {
+        return host.toLowerCase();
+    }
+}
+/** Split "host[:port]" into host and an optional numeric port. */
+function splitAuthority(authority) {
+    const colon = authority.lastIndexOf(':');
+    if (colon === -1)
+        return { host: authority, port: undefined };
+    const port = authority.slice(colon + 1);
+    if (/^\d+$/.test(port))
+        return { host: authority.slice(0, colon), port };
+    // Not a numeric suffix (e.g. IPv6 literals); treat the whole token as host.
+    return { host: authority, port: undefined };
+}
+/** Wildcard-aware host comparison: "*.base" matches base and subdomains. */
+function hostMatches(pattern, host) {
+    if (pattern.startsWith('*.')) {
+        const base = pattern.slice(2);
+        return base.length > 0 && (host === base || host.endsWith(`.${base}`));
+    }
+    return host === pattern;
+}
+/**
+ * Whether a request origin hits a routing-list match pattern.
+ * @param match - pattern from the llmProxy list entry.
+ * @param origin - request origin, e.g. "https://api.example.com" or
+ *   "https://api.example.com:8443"; a bare host[:port] is tolerated.
+ */
+export function matchOrigin(match, origin) {
+    const normalizedMatch = match.trim().toLowerCase();
+    if (!normalizedMatch)
+        return false;
+    const trimmedOrigin = origin.trim();
+    if (normalizedMatch.includes('://')) {
+        // Full-origin form: compare canonical origins, so scheme/host casing and
+        // punycode vs unicode IDN spellings do not affect the outcome.
+        const patternOrigin = canonicalOrigin(normalizedMatch);
+        return patternOrigin !== undefined && patternOrigin === canonicalOrigin(trimmedOrigin);
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmedOrigin.includes('://') ? trimmedOrigin : `http://${trimmedOrigin}`);
+    }
+    catch {
+        return false;
+    }
+    const { host: patternHost, port: patternPort } = splitAuthority(normalizedMatch);
+    if (!patternHost)
+        return false;
+    if (patternPort !== undefined) {
+        const actualPort = parsed.port || DEFAULT_PORTS.get(parsed.protocol) || '';
+        if (patternPort !== actualPort)
+            return false;
+    }
+    // parsed.hostname is already punycode-normalized by URL parsing; normalize
+    // the pattern host the same way so both sides compare symmetrically.
+    return hostMatches(normalizeHost(patternHost), parsed.hostname);
+}
+//# sourceMappingURL=match.js.map

package/lib/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../src/match.ts"],"names":[],"mappings":"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"}

package/lib/router.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The routing dispatcher: forwards every request to the first llmProxy entry
+ * whose match pattern hits the request origin, or to a shared fallback
+ * (system) dispatcher otherwise. Priority is decided here; the fallback
+ * itself — an EnvHttpProxyAgent for env semantics, or a direct Agent — is
+ * supplied by the caller.
+ */
+import * as undici from 'undici';
+/** One configured routing entry: origin pattern plus its proxy URL. */
+export interface LlmProxyEntry {
+    readonly match: string;
+    readonly proxy: string;
+}
+/**
+ * Route decision for an origin: either the first matching llmProxy entry, or
+ * the shared system fallback.
+ */
+export type RouteDecision = {
+    readonly kind: 'llm';
+    readonly index: number;
+    readonly proxyUrl: string;
+} | {
+    readonly kind: 'system';
+};
+export declare function withUndiciErrorListener<T extends undici.Dispatcher>(dispatcher: T): T;
+/**
+ * Which route an origin takes under the given entry list.
+ * @param entries - ordered llmProxy list; first hit wins.
+ * @param origin - request origin string.
+ */
+export declare function resolveRoute(entries: readonly LlmProxyEntry[], origin: string): RouteDecision;
+/** Injectable seams for tests and custom construction. */
+export interface RouterDeps {
+    /** Fallback for requests no llmProxy entry matches. Defaults to a direct Agent. */
+    systemDispatcher?: undici.Dispatcher;
+    /** Creates the per-proxy dispatcher; defaults to ProxyAgent. Overridable in tests. */
+    proxyFactory?: (proxyUrl: string) => undici.Dispatcher;
+}
+/**
+ * Create the process-global routing dispatcher.
+ * @param entries - ordered llmProxy list; first hit wins.
+ * @param deps - optional injectable system dispatcher / proxy factory.
+ */
+export declare function createProxyRouterDispatcher(entries: readonly LlmProxyEntry[], deps?: RouterDeps): undici.Dispatcher;

package/lib/router.js

@@ -0,0 +1,88 @@
+/**
+ * The routing dispatcher: forwards every request to the first llmProxy entry
+ * whose match pattern hits the request origin, or to a shared fallback
+ * (system) dispatcher otherwise. Priority is decided here; the fallback
+ * itself — an EnvHttpProxyAgent for env semantics, or a direct Agent — is
+ * supplied by the caller.
+ */
+import { EventEmitter } from 'node:events';
+import * as undici from 'undici';
+import { matchOrigin } from "./match.js";
+const ignoreUndiciDispatcherError = (_error) => { };
+// Undici can emit an internal Client "error" while terminating a mid-stream
+// fetch body. The body stream still rejects through reader.read(); this
+// listener only prevents EventEmitter's unhandled "error" special case from
+// crashing the host process. Applied to every dispatcher this plugin creates.
+export function withUndiciErrorListener(dispatcher) {
+    if (dispatcher instanceof EventEmitter) {
+        EventEmitter.prototype.on.call(dispatcher, 'error', ignoreUndiciDispatcherError);
+    }
+    return dispatcher;
+}
+/**
+ * Which route an origin takes under the given entry list.
+ * @param entries - ordered llmProxy list; first hit wins.
+ * @param origin - request origin string.
+ */
+export function resolveRoute(entries, origin) {
+    const index = entries.findIndex((entry) => matchOrigin(entry.match, origin));
+    if (index === -1)
+        return { kind: 'system' };
+    return { kind: 'llm', index, proxyUrl: entries[index].proxy };
+}
+function originToString(origin) {
+    if (origin instanceof URL)
+        return origin.origin;
+    if (typeof origin === 'string')
+        return origin;
+    return '';
+}
+class ProxyRouterDispatcher extends undici.Dispatcher {
+    #entries;
+    #systemDispatcher;
+    #proxyFactory;
+    #proxies = new Map();
+    constructor(entries, deps) {
+        super();
+        this.#entries = entries;
+        this.#systemDispatcher = deps.systemDispatcher ?? withUndiciErrorListener(new undici.Agent());
+        this.#proxyFactory = deps.proxyFactory ?? ((proxyUrl) => withUndiciErrorListener(new undici.ProxyAgent(proxyUrl)));
+    }
+    dispatch(options, handler) {
+        const decision = resolveRoute(this.#entries, originToString(options.origin));
+        const target = decision.kind === 'llm'
+            ? this.#proxyFor(decision.proxyUrl)
+            : this.#systemDispatcher;
+        return target.dispatch(options, handler);
+    }
+    #proxyFor(proxyUrl) {
+        let proxy = this.#proxies.get(proxyUrl);
+        if (!proxy) {
+            proxy = this.#proxyFactory(proxyUrl);
+            this.#proxies.set(proxyUrl, proxy);
+        }
+        return proxy;
+    }
+    /** All dispatchers owned by this router, including the system fallback. */
+    #owned() {
+        return [this.#systemDispatcher, ...this.#proxies.values()];
+    }
+    async close() {
+        await Promise.all(this.#owned().map((dispatcher) => dispatcher.close()));
+    }
+    async destroy() {
+        await Promise.all(this.#owned().map((dispatcher) => dispatcher.destroy()));
+    }
+}
+/**
+ * Create the process-global routing dispatcher.
+ * @param entries - ordered llmProxy list; first hit wins.
+ * @param deps - optional injectable system dispatcher / proxy factory.
+ */
+export function createProxyRouterDispatcher(entries, deps = {}) {
+    // The router itself performs no I/O and currently emits no 'error', but it
+    // is an EventEmitter; attach the guard here so the factory exit always
+    // hands out a protected dispatcher even if that ever changes.
+    return withUndiciErrorListener(new ProxyRouterDispatcher(entries, deps));
+}
+//# sourceMappingURL=router.js.map

package/lib/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@aiwayds/dsh-llm-proxy",
+  "version": "0.2.0",
+  "description": "dsh plugin: SYSTEM proxy (env) + LLM traffic-splitting proxy via a process-global undici routing dispatcher",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "plugin",
+    "proxy",
+    "undici",
+    "deepseek-harness",
+    "llm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fan56/dsh-llm-proxy.git"
+  },
+  "homepage": "https://github.com/fan56/dsh-llm-proxy",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "pretest": "npm run build",
+    "prepare": "npm run build",
+    "test": "node --test test/match.test.mjs test/router.test.mjs test/config.test.mjs test/skill.test.mjs test/dispose.test.mjs test/e2e.test.mjs"
+  },
+  "dependencies": {
+    "undici": "8.9.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-skill": "0.1.1-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-skill": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-skill": "0.1.1-rc.2",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "author": "fliu56",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/dsh-llm-proxy/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: dsh-llm-proxy
+description: "dsh 出站代理 / LLM 分流插件（@aiwayds/dsh-llm-proxy）使用指南。凡给 dsh 插件配置 HTTP 代理、LLM 出站分流，或排查代理网络问题时先读本指南：settings.yaml 顶层 `dsh-llm-proxy:` 段（enabled/systemMode/llmProxy）、llmProxy match 规则、代理 407、CONNECT 挂起、socks5 报错（SOCKS 不支持）、NODE_USE_ENV_PROXY 等价替代。触发词：dsh 代理、HTTP 代理、LLM 分流、llmProxy、llm-proxy、407、CONNECT 挂起、SOCKS、HTTPS_PROXY、NO_PROXY、出站代理、NODE_USE_ENV_PROXY。"
+---
+
+# dsh-llm-proxy 使用指南（LLM 分流代理）
+
+> dsh 插件：**SYSTEM proxy + LLM 分流代理**。进程级 undici 路由 Dispatcher 把 LLM 流量
+> 按配置列表分流到指定代理，其余流量走系统代理（启动环境变量），都没配则直连。
+
+## 配置入口（settings.yaml 顶层命名空间段）
+
+在 `~/.dsh/settings.yaml` 写**顶层 `dsh-llm-proxy:` 段**（与插件 id 一致，同 harness 内置
+插件 `llm-deepseek:` 段机制）：
+
+```yaml
+dsh-llm-proxy:
+  enabled: true                    # 总开关，默认 true；false 时完全不动全局
+  systemMode: env                  # 'env'（默认，读环境变量）| 'off'（全部直连，仅 llmProxy 生效）
+  llmProxy:                        # 匹配列表，按顺序首条命中生效
+    - match: "api.deepseek.org"    # host 精确匹配（含任意端口）
+      proxy: "http://127.0.0.1:7890"
+    - match: "*.volces.com"        # 通配：volces.com 本身 + 任意子域
+      proxy: "http://127.0.0.1:7891"
+    - match: "https://api.openai.com"  # 完整 origin 精确匹配（大小写不敏感）
+      proxy: "http://127.0.0.1:7892"
+```
+
+要点：
+
+- 编辑 **热生效**：无需重启，插件拆旧 router 按新配置重建。
+- bundle entry config（cordis.patch.yml 的 `config:`）是 base 层；settings.yaml 段覆盖其上
+  同名键。未挂载 settings 服务的宿主自动回退 entry config，插件照常工作。
+
+## 优先级语义
+
+```
+LLM 列表命中 > SYSTEM proxy（env 语义）> 直连
+```
+
+- 命中 `llmProxy` 条目 → 走该条目指定的代理（undici `ProxyAgent`）；**命中条目直接进指定
+  代理，不读 env `no_proxy`**。
+- 未命中 → 共享 `EnvHttpProxyAgent`：`HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` /
+  `NO_PROXY`（大小写均兼容）；`systemMode: off` 时未命中流量一律直连。
+- 环境变量**只读不写**：插件不改 `process.env.HTTP_PROXY`（对已启动进程无意义）。
+- 与 `NODE_USE_ENV_PROXY` 的关系：等价替代——无需该变量、无需重启，对新请求即时生效，
+  且额外提供 LLM 分流。
+
+## match 规则
+
+| 写法 | 含义 |
+|------|------|
+| `api.example.com` | host 精确匹配，**任意端口**都算命中 |
+| `api.example.com:8443` | host + 显式端口必须相等（https 默认 443 / http 默认 80 会补全比较） |
+| `*.example.com` | `example.com` 本身及任意层级子域 |
+| `https://api.example.com` | 完整 origin 精确匹配（scheme 也要一致） |
+
+匹配全部大小写不敏感、纯词法比较（无 DNS/IO）；IDN 域名两侧统一归一化为 punycode。
+
+**proxy 仅支持 http:// 与 https://**（undici ProxyAgent 限制）；`socks5://` 等在启动校验
+时直接报错（fail-fast）：**SOCKS 不支持**。
+
+## 排障清单
+
+1. **完全不生效** → 先查顶层键名：必须是 `dsh-llm-proxy:`；写成 `llm-proxy:` 等其他键
+   不会被读到，**静默失效**。
+2. **启动即报错** → proxy 用了 `socks5://` 等不支持的 schema；换 http(s) 代理。
+3. **走了代理但目标返回 407** → 代理自身认证问题，检查代理凭证；本插件日志/error
+   message 中 proxy URL 的 userinfo 一律脱敏为 `***@host`。
+4. **疑似代理问题** → 先用 `curl -x <proxy> <目标URL>` 复验代理本身通不通，通了再查 dsh
+   侧配置；随后按仓库 README「手动 e2e 验证」观察代理访问日志确认分流是否按预期。