agent-dual-proxy 0.0.0-stage → 0.7.1

package/bin/dual-proxy.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createDispatcher } from '../src/server.js';
+import { collectGateways, isLoopbackHost, resolveUpstream } from '../src/gateways.js';
+import { assertNode } from '../src/engines.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+/** 参数错误：打印一行并以退出码 2 结束。 */
+export class UsageError extends Error {}
+
+function usage() {
+  process.stdout.write([
+    'dual-proxy ' + pkg.version,
+    '',
+    'Usage: dual-proxy [options]',
+    '',
+    'Options:',
+    '  --listen-host <host>    default 127.0.0.1',
+    '  --listen-port <port>    default 7898',
+    '  --upstream-host <host>  default 127.0.0.1',
+    '  --upstream-port <port>  default 7897',
+    '  --upstream-url <url>    full upstream URL, may include user:pass',
+    '  --gateway <host:port>   extra candidate gateway, repeatable',
+    '  --health-url <url>      verify the channel with this URL, default off',
+    '  --health-interval-ms <ms>  default 60000, 0 disables',
+    '  --fast-fail-ms <ms>     timeout for the known path, default 2000',
+    '  --cooldown-ms <ms>      failed gateways rest this long, default 30000',
+    '  --timeout-ms <ms>       per-attempt timeout, default 5000',
+    '  --response-timeout-ms <ms>  header wait for plain HTTP, default 60000',
+    '  --pref-ttl-ms <ms>      per-host preference TTL, default 60000',
+    '  --no-verify-tls         skip the TLS reachability probe on 443',
+    '  --retry-non-idempotent-after-send  replay POST/PATCH after the body may have',
+    '                          been sent (dangerous; default off)',
+    '  --retry-non-idempotent-with-idempotency-key',
+    '                          replay POST/PATCH after send when Idempotency-Key is present',
+    '  -h, --help              show this help',
+    '  -v, --version           print version',
+    '',
+    'Env fallbacks: LISTEN_HOST / LISTEN_PORT / UPSTREAM_HOST / UPSTREAM_PORT / UPSTREAM_URL /',
+    '               GATEWAY / HEALTH_URL / HEALTH_INTERVAL_MS / FAST_FAIL_MS /',
+    '               COOLDOWN_MS / ATTEMPT_TIMEOUT_MS / RESPONSE_TIMEOUT_MS /',
+    '               PREF_TTL_MS / VERIFY_TLS=0 / RETRY_NON_IDEMPOTENT_AFTER_SEND=1 /',
+    '               RETRY_NON_IDEMPOTENT_WITH_IDEMPOTENCY_KEY=1',
+    ''
+  ].join('\n'));
+}
+
+function envValue(env, name) {
+  const value = env[name];
+  return value === undefined || value === '' ? undefined : value;
+}
+
+/** 解析整数并校验范围；失败抛 UsageError。 */
+function integer(label, raw, min, max) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new UsageError('invalid value for ' + label + ': ' + raw + ' (expected integer ' + min + '..' + max + ')');
+  }
+  return value;
+}
+
+/** 解析 CLI 参数；args 不含 node 与脚本路径。 */
+export function parseArgs(args, env = {}) {
+  const opts = {
+    listenHost: envValue(env, 'LISTEN_HOST') || '127.0.0.1',
+    listenPort: integer('LISTEN_PORT', envValue(env, 'LISTEN_PORT') ?? 7898, 1, 65535),
+    upstreamHost: envValue(env, 'UPSTREAM_HOST') || '127.0.0.1',
+    upstreamPort: integer('UPSTREAM_PORT', envValue(env, 'UPSTREAM_PORT') ?? 7897, 1, 65535),
+    upstreamUrl: envValue(env, 'UPSTREAM_URL') || '',
+    attemptTimeoutMs: integer('ATTEMPT_TIMEOUT_MS', envValue(env, 'ATTEMPT_TIMEOUT_MS') ?? 5000, 100, 60000),
+    responseTimeoutMs: integer('RESPONSE_TIMEOUT_MS', envValue(env, 'RESPONSE_TIMEOUT_MS') ?? 60000, 100, 600000),
+    prefTtlMs: integer('PREF_TTL_MS', envValue(env, 'PREF_TTL_MS') ?? 60000, 0, 3600000),
+    gateways: envValue(env, 'GATEWAY') ? [envValue(env, 'GATEWAY')] : [],
+    healthUrl: env.HEALTH_URL ?? '',
+    healthIntervalMs: integer('HEALTH_INTERVAL_MS', envValue(env, 'HEALTH_INTERVAL_MS') ?? 60000, 0, 3600000),
+    fastFailTimeoutMs: integer('FAST_FAIL_MS', envValue(env, 'FAST_FAIL_MS') ?? 2000, 100, 60000),
+    cooldownMs: integer('COOLDOWN_MS', envValue(env, 'COOLDOWN_MS') ?? 30000, 0, 600000),
+    retryNonIdempotentAfterSend: env.RETRY_NON_IDEMPOTENT_AFTER_SEND === '1',
+    retryNonIdempotentWithIdempotencyKey: env.RETRY_NON_IDEMPOTENT_WITH_IDEMPOTENCY_KEY === '1',
+    verifyTls: env.VERIFY_TLS !== '0'
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    const next = () => {
+      i += 1;
+      if (i >= args.length) throw new UsageError('missing value for ' + arg);
+      return args[i];
+    };
+    switch (arg) {
+      case '--listen-host': opts.listenHost = next(); break;
+      case '--listen-port': opts.listenPort = integer(arg, next(), 1, 65535); break;
+      case '--upstream-host': opts.upstreamHost = next(); break;
+      case '--upstream-port': opts.upstreamPort = integer(arg, next(), 1, 65535); break;
+      case '--upstream-url': opts.upstreamUrl = next(); break;
+      case '--gateway': opts.gateways.push(next()); break;
+      case '--health-url': opts.healthUrl = next(); break;
+      case '--health-interval-ms': opts.healthIntervalMs = integer(arg, next(), 0, 3600000); break;
+      case '--fast-fail-ms': opts.fastFailTimeoutMs = integer(arg, next(), 100, 60000); break;
+      case '--cooldown-ms': opts.cooldownMs = integer(arg, next(), 0, 600000); break;
+      case '--timeout-ms': opts.attemptTimeoutMs = integer(arg, next(), 100, 60000); break;
+      case '--response-timeout-ms': opts.responseTimeoutMs = integer(arg, next(), 100, 600000); break;
+      case '--pref-ttl-ms': opts.prefTtlMs = integer(arg, next(), 0, 3600000); break;
+      case '--no-verify-tls': opts.verifyTls = false; break;
+      case '--retry-non-idempotent-after-send': opts.retryNonIdempotentAfterSend = true; break;
+      case '--retry-non-idempotent-with-idempotency-key': opts.retryNonIdempotentWithIdempotencyKey = true; break;
+      case '-h':
+      case '--help': opts.help = true; break;
+      case '-v':
+      case '--version': opts.version = true; break;
+      default: throw new UsageError('unknown option: ' + arg);
+    }
+  }
+
+  if (opts.upstreamUrl) {
+    // upstreamUrl 是显式的第一个候选：非法值 fail fast，由 resolveUpstream 给出脱敏原因。
+    try {
+      resolveUpstream(opts);
+    } catch (err) {
+      throw new UsageError(err && err.message ? err.message : 'invalid upstreamUrl (userinfo redacted)');
+    }
+  }
+  // --gateway/GATEWAY 与 gateways 配置一样，交给 collectGateways 做 warning + skip；
+  // 非法额外候选不应阻止启动或悄悄回退。
+  return opts;
+}
+
+async function main() {
+  try {
+    assertNode();
+    const opts = parseArgs(process.argv.slice(2), process.env);
+    if (opts.help) { usage(); return; }
+    if (opts.version) { process.stdout.write(pkg.version + '\n'); return; }
+    let upstream;
+    try {
+      upstream = resolveUpstream(opts);
+    } catch (err) {
+      throw new UsageError(err && err.message ? err.message : 'invalid upstreamUrl (userinfo redacted)');
+    }
+    if (!isLoopbackHost(opts.listenHost)) {
+      process.stderr.write('warning: listening on ' + opts.listenHost + '; this proxy has no authentication\n');
+    }
+
+    const gateways = collectGateways({
+      upstream,
+      extra: opts.gateways,
+      env: process.env,
+      self: { host: opts.listenHost, port: opts.listenPort },
+      onInvalid: (subject, reason) => process.stderr.write('warning: ' + subject + ': ' + reason + '\n')
+    });
+    const dispatcher = createDispatcher(Object.assign({}, opts, {
+      upstreamHost: upstream.host,
+      upstreamPort: upstream.port,
+      upstreamAuth: upstream.auth,
+      gateways
+    }));
+    const addr = await dispatcher.listen();
+    dispatcher.startHealth();
+    process.stderr.write('[dual-proxy] listening on ' + addr.address + ':' + addr.port +
+      ' gateways=' + gateways.map((g) => g.host + ':' + g.port).concat('direct').join(',') +
+      (opts.healthUrl ? ' health=' + opts.healthUrl : '') + '\n');
+
+    const shutdown = () => {
+      dispatcher.close().then(() => process.exit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  } catch (err) {
+    if (err instanceof UsageError) {
+      process.stderr.write(err.message + '\n');
+      process.exitCode = 2;
+    } else {
+      process.stderr.write('error: ' + (err && err.message ? err.message : String(err)) + '\n');
+      process.exitCode = 1;
+    }
+  }
+}
+
+/** 入口判断：npm 通过符号链接调用时，argv[1] 与真实路径不同，必须 realpath 比较。 */
+function isMain() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch (e) {
+    return false;
+  }
+}
+
+if (isMain()) {
+  main();
+}

package/contrib/dual-proxy.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=agent-dual-proxy (upstream proxy first, direct on failure)
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/env node %h/agent-dual-proxy/bin/dual-proxy.js
+Restart=always
+RestartSec=2
+Environment=LISTEN_HOST=127.0.0.1
+Environment=LISTEN_PORT=7898
+Environment=UPSTREAM_HOST=127.0.0.1
+Environment=UPSTREAM_PORT=7897
+Environment=ATTEMPT_TIMEOUT_MS=5000
+
+[Install]
+WantedBy=default.target

package/docs/agents.md

@@ -0,0 +1,94 @@
+# 给主流 CLI agent 用
+
+这些 agent 没有共用的插件 API，唯一通杀的是 `HTTP(S)_PROXY`。所以适配层就一件事：
+
+```
+agent-gateway run <agent>   →   起双路代理 + 把代理变量塞进子进程 + exec
+```
+
+端口已被占用时复用那一个；子进程退出后代理跟着关，不留孤儿进程。agent 的本地端口
+（hook、LSP、语言服务器）走 `NO_PROXY` 直连，不会被代理吞掉。
+
+注入时会替换启动环境里的 socks `ALL_PROXY`：不少客户端会优先读它，留着就绕过了
+`HTTP(S)_PROXY`，双路选路白做。`NO_PROXY` 与用户原有的直连段合并，不覆盖。
+
+```bash
+node bin/agent-gateway.js run claude --resume
+node bin/agent-gateway.js run codex
+node bin/agent-gateway.js run --listen-port 12334 --health-url https://api.deepseek.com -- gemini
+node bin/agent-gateway.js env   # 打印 export 语句，给不支持启动器的场景用
+```
+
+内置短名只是「名字 → 可执行文件」的映射，真正的适配仍然是环境变量：
+
+| 短名 | 可执行文件 | 说明 |
+| :--- | :--- | :--- |
+| `claude` | `claude` | Claude Code |
+| `codex` | `codex` | OpenAI Codex CLI |
+| `gemini` | `gemini` | Gemini CLI |
+| `pi` | `pi` | pi |
+| `aider` | `aider` | Aider |
+| `opencode` | `opencode` | OpenCode |
+| `qwen` | `qwen` | Qwen Code |
+| `cursor` | `cursor-agent` | Cursor CLI |
+| `droid` | `droid` | Factory Droid |
+| `amp` | `amp` | Amp |
+| `crush` | `crush` | Charm Crush |
+| `goose` | `goose` | Goose |
+| `copilot` | `copilot` | GitHub Copilot CLI |
+
+不在表里的 CLI 用 `agent-gateway run -- <cmd> [args...]`，效果一样。客户端不读环境变量时，
+这一层无能为力——见下面的排查提示。
+
+## Claude Code
+
+`~/.claude/settings.json` 支持 `env` 段，写进去就不用每次走启动器：
+
+```json
+{
+  "env": {
+    "HTTPS_PROXY": "http://127.0.0.1:7898",
+    "HTTP_PROXY": "http://127.0.0.1:7898",
+    "ALL_PROXY": "http://127.0.0.1:7898",
+    "NO_PROXY": "localhost,127.0.0.1,::1,[::1]"
+  }
+}
+```
+
+先有代理在听（`agent-gateway run claude` 会自己起；或 `dual-proxy --listen-port 7898`）。
+
+## Codex CLI
+
+`~/.codex/config.toml` 没有代理字段，只能用环境变量，所以走启动器：
+
+```bash
+agent-gateway run codex
+```
+
+## Gemini CLI
+
+同样只有环境变量这一条路：
+
+```bash
+agent-gateway run gemini
+```
+
+如果该版本的内置 HTTP 客户端不读环境变量（表现为请求完全没经过 7898，`ss -tnp | grep 7898` 为空），
+就把它放到系统代理或 TUN 之下——那不是这一层能解决的，别在本插件里加特例。
+
+## pi
+
+```bash
+agent-gateway run pi
+```
+
+pi 自己的长会话里若中途换了网络，重启会话比热改环境可靠：进程环境是启动快照，
+`collectGateways` 也只读一次。
+
+## 通用命令
+
+```bash
+agent-gateway run -- <任意命令> [args...]
+```
+
+任何尊重 `HTTP(S)_PROXY` 的 CLI 都能这样套上，不限于上表。

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "agent-dual-proxy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.1",
+  "description": "Local dual-path proxy for CLI agents: auto-selects a gateway that reaches the model endpoint, verifies the channel, fails over to direct",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/server.js",
+  "exports": {
+    ".": "./src/server.js",
+    "./agents": "./src/agents.js",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gambn/agent-dual-proxy.git"
+  },
+  "homepage": "https://github.com/gambn/agent-dual-proxy#readme",
+  "bugs": {
+    "url": "https://github.com/gambn/agent-dual-proxy/issues"
+  },
+  "author": "Gambn",
+  "bin": {
+    "agent-gateway": "bin/agent-gateway.js",
+    "dual-proxy": "bin/dual-proxy.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "start": "node bin/dual-proxy.js"
+  },
+  "dependencies": {
+    "undici": "8.12.3"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE",
+    "docs",
+    "contrib"
+  ],
+  "keywords": [
+    "proxy",
+    "failover",
+    "cli-agent",
+    "claude-code",
+    "codex",
+    "gemini",
+    "health-check"
+  ]
+}

package/src/agents.js

@@ -0,0 +1,61 @@
+/**
+ * 主流 AGENT 的适配表与环境构造。
+ *
+ * 这些 CLI agent 没有共用的插件 API，唯一通杀的是 HTTP(S)_PROXY 环境变量，
+ * 所以适配层只做两件事：起一个双路代理，把变量塞进子进程环境里再 exec。
+ */
+export const AGENTS = {
+  claude: { bin: 'claude', note: 'Claude Code' },
+  codex: { bin: 'codex', note: 'OpenAI Codex CLI' },
+  gemini: { bin: 'gemini', note: 'Gemini CLI' },
+  pi: { bin: 'pi', note: 'pi' },
+  aider: { bin: 'aider', note: 'Aider' },
+  opencode: { bin: 'opencode', note: 'OpenCode' },
+  qwen: { bin: 'qwen', note: 'Qwen Code' },
+  cursor: { bin: 'cursor-agent', note: 'Cursor CLI' },
+  droid: { bin: 'droid', note: 'Factory Droid' },
+  amp: { bin: 'amp', note: 'Amp' },
+  crush: { bin: 'crush', note: 'Charm Crush' },
+  goose: { bin: 'goose', note: 'Goose' },
+  copilot: { bin: 'copilot', note: 'GitHub Copilot CLI' }
+};
+
+/** 适配表里的短名，供用法/报错文本使用。 */
+export const AGENT_NAMES = Object.keys(AGENTS);
+
+/** 按名字取适配项；不认识的返回 null，由 CLI 负责报错。 */
+export function resolveAgent(name) {
+  if (typeof name !== 'string') return null;
+  return AGENTS[name.trim().toLowerCase()] || null;
+}
+
+export function proxyUrl({ listenHost = '127.0.0.1', listenPort }) {
+  const loopback = listenHost === '0.0.0.0' || listenHost === '::' ? '127.0.0.1' : listenHost;
+  const host = loopback.includes(':') && !loopback.startsWith('[') ? '[' + loopback + ']' : loopback;
+  return 'http://' + host + ':' + listenPort;
+}
+
+/** 回环地址一律直连：agent 自己的本地端口（hook、LSP、语言服务器）不能被代理吞掉。 */
+const LOCAL_BYPASS = ['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0'];
+
+/**
+ * 生成子进程环境：代理变量大小写各一份，其余原样继承。
+ *
+ * ALL_PROXY 也指向本代理：启动环境里的 socks ALL_PROXY 会让客户端绕过
+ * HTTP(S)_PROXY，双路选路就白做了。NO_PROXY 是合并而不是覆盖，避免丢掉
+ * 用户原有的内网直连段。
+ */
+export function buildProxyEnv(url, base = process.env) {
+  const env = { ...base };
+  for (const key of ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy', 'ALL_PROXY', 'all_proxy']) {
+    env[key] = url;
+  }
+  const noProxy = [...LOCAL_BYPASS];
+  for (const item of String(base.NO_PROXY ?? base.no_proxy ?? '').split(',')) {
+    const value = item.trim();
+    if (value && !noProxy.includes(value)) noProxy.push(value);
+  }
+  env.NO_PROXY = noProxy.join(',');
+  env.no_proxy = env.NO_PROXY;
+  return env;
+}

package/src/engines.js

@@ -0,0 +1,25 @@
+/** Node 版本门槛：undici 8 要求 >= 22.19.0。 */
+export const MIN_NODE = '22.19.0';
+
+function parts(version) {
+  return String(version)
+    .split('-')[0]
+    .split('.')
+    .map((value) => Number.parseInt(value, 10) || 0);
+}
+
+/** 版本比较；只比较 major.minor.patch。 */
+export function nodeAtLeast(version, min = MIN_NODE) {
+  const [a, b, c] = parts(version);
+  const [x, y, z] = parts(min);
+  if (a !== x) return a > x;
+  if (b !== y) return b > y;
+  return c >= z;
+}
+
+/** 低于门槛时抛出可读错误，避免在 undici 里报出看不懂的运行期错误。 */
+export function assertNode(version = process.versions.node) {
+  if (!nodeAtLeast(version)) {
+    throw new Error('agent-dual-proxy requires Node >= ' + MIN_NODE + ' (current ' + version + ')');
+  }
+}

package/src/gateways.js

@@ -0,0 +1,163 @@
+/** 网关候选：把配置与启动环境里的代理地址归一化成 {host, port, auth?}。 */
+
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '0.0.0.0']);
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+const ENV_NAMES = ['https_proxy', 'HTTPS_PROXY', 'all_proxy', 'ALL_PROXY', 'http_proxy', 'HTTP_PROXY'];
+
+/** upstreamUrl 解析失败：消息里不含原始 URL 或 userinfo。 */
+export class UpstreamError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UpstreamError';
+    this.code = 'EUPSTREAMURL';
+  }
+}
+
+/** 把 userinfo 编成 Proxy-Authorization 的 Basic 值；没有凭证回 null。 */
+function basicAuth(url) {
+  if (!url.username && !url.password) return null;
+  try {
+    const user = decodeURIComponent(url.username);
+    const pass = decodeURIComponent(url.password);
+    return 'Basic ' + Buffer.from(user + ':' + pass).toString('base64');
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 解析 `host:port`、`http://host:port` 或带 userinfo 的 HTTP 代理 URL，失败回 null。
+ * 0.7.0 只支持明文 HTTP CONNECT 代理；`https://` 一律拒绝，避免把 CONNECT 明文发给
+ * 实际期望 TLS 的端口。
+ */
+export function parseGateway(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value).trim();
+  if (!text) return null;
+
+  let url;
+  try {
+    url = new URL(text.includes('://') ? text : 'http://' + text);
+  } catch (e) {
+    return null;
+  }
+  if (url.protocol !== 'http:') return null;
+
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  const port = Number(url.port || 80);
+  if (!host || !Number.isInteger(port) || port < 1 || port > 65535) return null;
+
+  const auth = basicAuth(url);
+  if ((url.username || url.password) && !auth) return null;
+  return auth ? { host, port, auth } : { host, port };
+}
+
+/** 去掉 userinfo 的展示形式；只用于警告/错误，不用于连接。 */
+export function redactGateway(value) {
+  const text = String(value === undefined || value === null ? '' : value).trim();
+  if (!text) return '<empty>';
+  try {
+    const url = new URL(text.includes('://') ? text : 'http://' + text);
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (!host) return '<invalid>';
+    const shown = host.includes(':') ? '[' + host + ']' : host;
+    return url.protocol + '//' + shown + (url.port ? ':' + url.port : '');
+  } catch (e) {
+    return '<invalid>';
+  }
+}
+
+/** 拒绝原因：https 与普通非法值分开，便于调用方给出可操作的提示。 */
+function rejectReason(value) {
+  return /^\s*https:\/\//i.test(String(value === undefined || value === null ? '' : value))
+    ? 'https upstream proxy is not supported'
+    : 'invalid gateway';
+}
+
+/**
+ * 汇总候选网关：配置的上游、额外网关、启动环境里的代理，去重并排除自身监听端口。
+ * `direct` 不在这里，由调用方补在最后。
+ *
+ * 同一 host:port 只保留一条，但会合并凭证：无 auth + 有 auth → 补上；
+ * 两边都有且不同 → 保留第一条并回调 warning（subject 已脱敏）。
+ */
+export function collectGateways({ upstream, extra = [], env = {}, self, onInvalid } = {}) {
+  const list = [];
+  const warn = (subject, reason) => {
+    if (typeof onInvalid === 'function') onInvalid(subject, reason);
+  };
+  const add = (gateway, raw) => {
+    const fallback = gateway && gateway.host
+      ? String(gateway.host) + ':' + String(gateway.port)
+      : raw;
+    if (!gateway) {
+      warn(redactGateway(fallback), rejectReason(fallback));
+      return;
+    }
+    const host = String(gateway.host || '');
+    const port = Number(gateway.port);
+    if (!host || !Number.isInteger(port) || port < 1 || port > 65535) {
+      warn(redactGateway(fallback), 'invalid gateway');
+      return;
+    }
+    const isSelf = self !== undefined && self !== null && port === Number(self.port) &&
+      LOOPBACK.has(host) && LOOPBACK.has(String(self.host || ''));
+    if (isSelf) return;
+
+    const existing = list.find((item) => item.host === host && item.port === port);
+    if (existing) {
+      if (!existing.auth && gateway.auth) {
+        existing.auth = gateway.auth;
+      } else if (existing.auth && gateway.auth && existing.auth !== gateway.auth) {
+        warn(host + ':' + port, 'conflicting proxy credentials; keeping first');
+      }
+      return;
+    }
+    list.push(gateway.auth ? { host, port, auth: gateway.auth } : { host, port });
+  };
+
+  if (upstream) add(typeof upstream === 'string' ? parseGateway(upstream) : upstream, upstream);
+  for (const item of extra) {
+    add(typeof item === 'string' ? parseGateway(item) : item, item);
+  }
+  for (const name of ENV_NAMES) {
+    if (env[name] !== undefined && env[name] !== null && String(env[name]).trim()) {
+      add(parseGateway(env[name]), env[name]);
+    }
+  }
+  return list;
+}
+
+/**
+ * 解析上游：upstreamUrl 非空时替换 host/port/auth；为空时沿用 host/port。
+ * 非法值抛 UpstreamError（消息已脱敏），由 index/CLI 分别转成日志或退出码 2。
+ */
+export function resolveUpstream({ upstreamUrl, upstreamHost = '127.0.0.1', upstreamPort = 7897 } = {}) {
+  const text = String(upstreamUrl === undefined || upstreamUrl === null ? '' : upstreamUrl).trim();
+  if (text) {
+    if (/^https:\/\//i.test(text)) {
+      throw new UpstreamError('invalid upstreamUrl: https upstream proxy is not supported (userinfo redacted)');
+    }
+    const parsed = parseGateway(text);
+    if (!parsed) throw new UpstreamError('invalid upstreamUrl (userinfo redacted)');
+    return parsed;
+  }
+  const host = String(upstreamHost || '127.0.0.1');
+  const port = Number(upstreamPort);
+  if (!host || !Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new UpstreamError('invalid upstreamHost/upstreamPort');
+  }
+  return { host, port };
+}
+
+/** 这个 host 是不是回环地址（用于“非回环绑定”告警）。 */
+export function isLoopbackHost(host) {
+  return LOOPBACK_HOSTS.has(String(host || '').toLowerCase());
+}
+
+/** 归一化成候选列表（最后一条 direct），供 dispatcher 使用。 */
+export function buildCandidates(upstream, gateways = [], self, onInvalid) {
+  return collectGateways({ upstream, extra: gateways, self, onInvalid })
+    .map((gateway) => Object.assign({ id: gateway.host + ':' + gateway.port }, gateway))
+    .concat({ id: 'direct', direct: true });
+}