Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* 出站(上游方向)代理支持 ——
*
* 背景:proxy 转发上游用的是 node:http/https 直连,而 Node 的 http 栈不读系统代理、
* 也不读代理环境变量。用户的代理软件跑在「系统代理」模式(非 TUN)时,浏览器 / Codex CLI
* (reqwest 自动吃 env)都正常,唯独本代理的上游连接裸直连 → 高墙网络下 AggregateError
* → 客户端收 502 "upstream unreachable"。本模块提供:
*
* - parseOutboundProxyUrl:解析 `http://[user:pass@]host:port` 与
* `socks5://[user:pass@]host:port` 形式的代理地址(其余 scheme 返回 null,
* 由调用方回落直连并告警;SOCKS4/4a 与 TLS-to-proxy 的 https: 不支持)
* - createEnvOutboundProxyResolver:按惯例读 HTTPS_PROXY / HTTP_PROXY / ALL_PROXY /
* NO_PROXY(大小写两种拼写),给非 Electron 宿主(CLI / 远端 cc-manager)直接用
* - TunnelingHttpsAgent:经代理 CONNECT 隧道连 https 上游的 keep-alive Agent
* (TLS 端到端,由 https.Agent 原生逻辑完成,代理只见密文)
* - OutboundProxyAgentPool:按 key 缓存 agent,复用连接池,随 proxy dispose 销毁
*
* SOCKS5 的握手与两个 agent 在 socks5.ts(单向依赖本模块的 primitive,不反向引用)。
*
* 边界:HTTP 代理鉴权只支持 URL userinfo → Proxy-Authorization: Basic,SOCKS5 走
* RFC 1929 用户名/密码;系统代理的解析(Electron session.resolveProxy)由宿主注入
* resolver,本包不依赖 Electron。
*/
import { type Agent as HttpAgent, request as httpRequest, type ClientRequestArgs, type RequestOptions } from 'node:http';
import { Agent as HttpsAgent, type AgentOptions } from 'node:https';
import type { TcpSocketConnectOpts } from 'node:net';
import type { Duplex } from 'node:stream';
import { URL } from 'node:url';
/**
* 解析后的出站代理目标。
* kind='http' 用 authHeader(现成的 Proxy-Authorization 值,含 "Basic " 前缀);
* kind='socks5' 用 username / password(RFC 1929 走原始字节,不是 Basic 形态)。
*/
export interface OutboundProxyTarget {
kind: 'http' | 'socks5';
/** 规范化代理地址(不含 userinfo,可安全进日志),例 "http://127.0.0.1:7890"。 */
url: string;
hostname: string;
port: number;
authHeader?: string;
username?: string;
password?: string;
}
/** 出站代理 agent 的公共类型;https.Agent 继承自 http.Agent,http 侧类型即可涵盖两者。 */
export type OutboundProxyAgent = HttpAgent;
/**
* 出站代理解析器 —— per-request 以最终上游 origin(`https://host:port`)现取代理地址。
* 返回 http:// 或 socks5:// 代理 URL = 该请求经代理转发;null/undefined = 直连。
* 抛错按直连处理(fail-open,代理解析故障不断链路)。loopback 上游不会被调用。
*/
export type OutboundProxyResolver = (
upstreamUrl: string,
) => string | null | undefined | Promise<string | null | undefined>;
/**
* 去掉 IPv6 字面量的方括号。WHATWG URL 的 `hostname` 对 IPv6 返回**带方括号**的
* 形式(`new URL('https://[::1]').hostname === '[::1]'`),而比较 / 重组 authority
* 都需要裸地址;所有消费 hostname 的入口先过这里归一化。
* 带括号的形态会一路传到 agent 的 `options.host`(实测 Node 不会自己剥),
* socks5.ts 编码目标地址前也要用它。
*/
export function stripIpv6Brackets(hostname: string): string {
return hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
}
/**
* loopback 上游永不走代理:本机 bridge / gateway 与代理软件无关,而且系统代理的
* bypass 规则(localhost 默认直连)在 env 层不可见,这里必须自兜。
*/
export function isLoopbackHostname(hostname: string): boolean {
const h = stripIpv6Brackets(hostname.toLowerCase());
return h === 'localhost' || h.endsWith('.localhost') || h === '::1' || h.startsWith('127.');
}
/**
* 拼 host:port authority。IPv6 字面量按 RFC 3986 加方括号 —— resolver URL、
* CONNECT 目标、绝对形式 URL 与 Host 头共用,裸拼 `v6:port` 会被代理当成非法目标。
*/
export function formatAuthority(hostname: string, port: number): string {
const bare = stripIpv6Brackets(hostname);
return bare.includes(':') ? `[${bare}]:${port}` : `${bare}:${port}`;
}
/**
* 按 RFC 9110 语义拼 Host 头:默认端口省略,非默认端口带上;IPv6 字面量加方括号。
* 经代理的绝对形式请求用 —— 该分支 socket 连的是代理,Host 头只能靠显式设置。
*/
export function formatHostHeader(hostname: string, port: number, protocol: 'http:' | 'https:'): string {
const defaultPort = protocol === 'https:' ? 443 : 80;
const bare = stripIpv6Brackets(hostname);
const bracketed = bare.includes(':') ? `[${bare}]` : bare;
return port === defaultPort ? bracketed : `${bracketed}:${port}`;
}
/**
* userinfo 解码。decodeURIComponent 对非法百分号编码(如 `user%GG`)会抛 URIError;
* 解析器绝不能抛(在请求热路径上,抛了就是未处理 rejection 而非直连回退),
* 解不开就按用户原文使用。
*/
function safeDecodeUserinfo(value: string): string {
try {
return decodeURIComponent(value);
} catch {
return value;
}
}
// SOCKS5 的三种写法:socks5h 的「域名交给代理解析」正是本实现的固定语义,socks 按
// 惯例视为 v5。SOCKS4/4a(socks4: / socks4a:)不支持 —— 无认证、无 IPv6,且 Chromium
// PAC 里裸 `SOCKS` 前缀就是 v4。
const SOCKS5_PROTOCOLS = new Set(['socks5:', 'socks5h:', 'socks:']);
const DEFAULT_SOCKS_PORT = 1080;
/**
* RFC 1929 的 UNAME / PASSWD 都是单字节长度前缀。解析这一侧把超长凭证降级成「没有
* 凭证」(静默截断会把错误的凭证发给代理,更难排查),代理若要求认证会给出明确的握手
* 错误;socks5.ts 的握手侧另有一道 fail-fast,兜住绕过本函数直接构造 target 的调用方。
*/
export const SOCKS5_CREDENTIAL_MAX_BYTES = 255;
/**
* 解析代理地址。接受明文 HTTP 代理(CONNECT 隧道 / 绝对形式都建立在它上面)与 SOCKS5;
* 其余 scheme(https: 的 TLS-to-proxy、socks4:)不支持,返回 null 由调用方回落直连。
* 任何输入都不抛错:解析失败一律返回 null。
*/
export function parseOutboundProxyUrl(raw: string | null | undefined): OutboundProxyTarget | null {
const trimmed = typeof raw === 'string' ? raw.trim() : '';
if (!trimmed) return null;
let u: URL;
try {
u = new URL(trimmed);
} catch {
return null;
}
const isSocks5 = SOCKS5_PROTOCOLS.has(u.protocol);
if (u.protocol !== 'http:' && !isSocks5) return null;
if (!u.hostname) return null;
const port = u.port ? Number(u.port) : (isSocks5 ? DEFAULT_SOCKS_PORT : 80);
if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
// URL 里的 userinfo 是百分号编码的,先解码再用。
const user = u.username ? safeDecodeUserinfo(u.username) : '';
const pass = u.password ? safeDecodeUserinfo(u.password) : '';
// hostname 去掉 IPv6 方括号:它会被直接用作 TCP connect host(net/tls 只认裸地址);
// url 保留带括号的 u.host 形态(仅用于日志与 pool key)。
const hostname = stripIpv6Brackets(u.hostname);
if (isSocks5) {
const withinLimit = Buffer.byteLength(user, 'utf8') <= SOCKS5_CREDENTIAL_MAX_BYTES
&& Buffer.byteLength(pass, 'utf8') <= SOCKS5_CREDENTIAL_MAX_BYTES;
const useCredentials = user !== '' && withinLimit;
return {
kind: 'socks5',
url: `socks5://${u.host}${u.port ? '' : `:${port}`}`,
hostname,
port,
username: useCredentials ? user : undefined,
password: useCredentials ? pass : undefined,
};
}
return {
kind: 'http',
url: `http://${u.host}`,
hostname,
port,
authHeader: user ? `Basic ${Buffer.from(`${user}:${pass}`, 'utf8').toString('base64')}` : undefined,
};
}
/** 把可能带凭证的代理地址脱敏成可进日志的形式(只留 scheme://host:port)。 */
export function redactProxyUrlForLog(raw: string): string {
try {
const u = new URL(raw.trim());
return `${u.protocol}//${u.host}`;
} catch {
return '<unparseable proxy url>';
}
}
const ENV_HTTPS_KEYS = ['HTTPS_PROXY', 'https_proxy'] as const;
const ENV_HTTP_KEYS = ['HTTP_PROXY', 'http_proxy'] as const;
const ENV_ALL_KEYS = ['ALL_PROXY', 'all_proxy'] as const;
const ENV_NO_PROXY_KEYS = ['NO_PROXY', 'no_proxy'] as const;
function firstEnvValue(env: NodeJS.ProcessEnv, keys: readonly string[]): string | null {
for (const key of keys) {
const value = env[key];
if (typeof value === 'string' && value.trim()) return value.trim();
}
return null;
}
/** 宿主是否配置了任何代理环境变量(用于「env 有配置就以 env 为准」的分层判断)。 */
export function hasProxyEnvConfig(env: NodeJS.ProcessEnv = process.env): boolean {
return firstEnvValue(env, [...ENV_HTTPS_KEYS, ...ENV_HTTP_KEYS, ...ENV_ALL_KEYS]) !== null;
}
/**
* NO_PROXY 匹配(逗号分隔)。支持惯例语义:
* - `*` 全部直连
* - `example.com` / `.example.com` 匹配该域及其子域
* - `host:port` 额外要求端口一致(仅在恰好一个冒号时按 host:port 拆,
* 裸 IPv6 字面量如 `::1` / `2001:db8::1` 整体当 host,不误拆末段为端口)
* - `[v6]` / `[v6]:port` 的无歧义 IPv6 带端口形式
* IP 段(CIDR)不支持 —— 与多数实现一致,按普通字面 host 处理。
*/
function noProxyMatches(noProxy: string, hostname: string, port: number): boolean {
// URL.hostname 的 IPv6 带方括号,先归一成裸地址再与条目比较。
const host = stripIpv6Brackets(hostname.toLowerCase());
for (const rawEntry of noProxy.split(',')) {
const entry = rawEntry.trim().toLowerCase();
if (!entry) continue;
if (entry === '*') return true;
let entryHost = entry;
let entryPort: number | null = null;
if (entry.startsWith('[')) {
// [v6] / [v6]:port —— 唯一无歧义的 IPv6 带端口写法。
const close = entry.indexOf(']');
if (close === -1) continue; // 括号没闭合,条目非法,跳过
entryHost = entry.slice(1, close);
const rest = entry.slice(close + 1);
if (rest.startsWith(':') && /^\d+$/.test(rest.slice(1))) {
entryPort = Number(rest.slice(1));
} else if (rest) {
continue; // `]` 后跟了端口以外的东西,条目非法,跳过
}
} else {
const first = entry.indexOf(':');
// 恰好一个冒号且后缀纯数字才按 host:port 拆;多个冒号 = 裸 IPv6 字面量整体当 host。
if (first !== -1 && first === entry.lastIndexOf(':') && /^\d+$/.test(entry.slice(first + 1))) {
entryHost = entry.slice(0, first);
entryPort = Number(entry.slice(first + 1));
}
}
if (entryPort !== null && entryPort !== port) continue;
const bare = entryHost.startsWith('.') ? entryHost.slice(1) : entryHost;
if (!bare) continue;
if (host === bare || host.endsWith(`.${bare}`)) return true;
}
return false;
}
/**
* 环境变量代理解析器。语义与 curl / reqwest 等惯例对齐:
* https 上游 → HTTPS_PROXY ?? ALL_PROXY;http 上游 → HTTP_PROXY ?? ALL_PROXY;
* NO_PROXY 命中或 loopback 上游 → 直连。
* env 值在每次调用时现读(默认 process.env),宿主运行期改 env 即时生效。
*/
export function createEnvOutboundProxyResolver(
env: NodeJS.ProcessEnv = process.env,
): (upstreamUrl: string) => string | null {
return (upstreamUrl: string): string | null => {
let u: URL;
try {
u = new URL(upstreamUrl);
} catch {
return null;
}
if (isLoopbackHostname(u.hostname)) return null;
const port = u.port ? Number(u.port) : (u.protocol === 'https:' ? 443 : 80);
const noProxy = firstEnvValue(env, ENV_NO_PROXY_KEYS);
if (noProxy && noProxyMatches(noProxy, u.hostname, port)) return null;
const primary = u.protocol === 'https:' ? ENV_HTTPS_KEYS : ENV_HTTP_KEYS;
return firstEnvValue(env, primary) ?? firstEnvValue(env, ENV_ALL_KEYS);
};
}
// CONNECT 握手整体超时。代理通常在本机/局域网,正常毫秒级完成;上限只防代理软件假死
// 时无限悬挂。不宜过短:代理背后可能还要现拨远端节点。
const PROXY_CONNECT_TIMEOUT_MS = 15 * 1000;
// 连接代理自身的 Happy Eyeballs 单地址握手超时,与 server.ts 对上游直连的放宽一致
// (代理若配了 DNS 名且解析出多地址,同样会被 Node 默认 250ms per-attempt 砍死)。
const PROXY_CONNECT_ATTEMPT_TIMEOUT_MS = 2500;
/**
* 经 HTTP 代理 CONNECT 隧道连 https 上游的 keep-alive Agent。
*
* 工作方式:对代理发 `CONNECT host:port`,200 后拿到隧道 socket,把它交回
* https.Agent 原生 createConnection(带 `socket` 选项)完成 TLS 握手 —— TLS 端到端,
* SNI / 证书校验 / session 复用全部沿用 Node 原生逻辑,代理只见密文。
* 连接池语义与直连时的 globalAgent 一致(keepAlive,按 host:port 分 key)。
*/
export class TunnelingHttpsAgent extends HttpsAgent {
private readonly proxy: OutboundProxyTarget;
constructor(proxy: OutboundProxyTarget, opts?: AgentOptions) {
super({ keepAlive: true, ...opts });
this.proxy = proxy;
}
override createConnection(
options: ClientRequestArgs,
callback?: (err: Error | null, stream: Duplex) => void,
): Duplex | null | undefined {
// http.Agent 运行时恒以 callback 形态调用(createSocket → oncreate);无 callback
// 时无法异步建连,直接失败比静默直连安全。
if (!callback) throw new Error('TunnelingHttpsAgent requires callback-style createConnection');
const targetHost = options.host ?? 'localhost';
const targetPort = Number(options.port) || 443;
const authority = formatAuthority(targetHost, targetPort);
let settled = false;
const settle = (err: Error | null, stream?: Duplex): void => {
if (settled) return;
settled = true;
// @types/node 的 callback 把 stream 声明为必选;错误分支按运行时约定传 err 即可。
(callback as (err: Error | null, stream?: Duplex) => void)(err, stream);
};
const connectOptions: RequestOptions & Pick<TcpSocketConnectOpts, 'autoSelectFamilyAttemptTimeout'> = {
host: this.proxy.hostname,
port: this.proxy.port,
method: 'CONNECT',
path: authority,
headers: {
host: authority,
...(this.proxy.authHeader ? { 'proxy-authorization': this.proxy.authHeader } : {}),
},
// CONNECT 会劫持底层 socket,绝不能进共享连接池。
agent: false,
timeout: PROXY_CONNECT_TIMEOUT_MS,
autoSelectFamilyAttemptTimeout: PROXY_CONNECT_ATTEMPT_TIMEOUT_MS,
};
const connectReq = httpRequest(connectOptions);
connectReq.on('connect', (res, socket, head) => {
if (res.statusCode !== 200) {
socket.destroy();
settle(new Error(`outbound proxy ${this.proxy.url} CONNECT ${authority} failed: HTTP ${res.statusCode}`));
return;
}
// CONNECT 成功后代理不应再发字节;万一有(不合规代理提前送了上游数据)塞回流里。
if (head.length > 0) socket.unshift(head);
try {
// 委托 https.Agent 原生 createConnection 做 TLS:`socket` 选项让 tls.connect
// 直接包装隧道 socket 而不再自行拨号,servername / 证书校验 / session 缓存照旧。
const tlsSocket = (HttpsAgent.prototype as unknown as {
createConnection: (opts: unknown) => Duplex;
}).createConnection.call(this, { ...options, socket });
settle(null, tlsSocket);
} catch (err) {
socket.destroy();
settle(err instanceof Error ? err : new Error(String(err)));
}
});
connectReq.on('timeout', () => {
connectReq.destroy(new Error(`outbound proxy ${this.proxy.url} CONNECT ${authority} timed out`));
});
connectReq.on('error', (err) => {
// 保留底层 errno(cause):server.ts 的 502 分类要沿错误链找 ECONNREFUSED + 回环地址。
settle(new Error(`outbound proxy ${this.proxy.url} unreachable: ${err.message}`, { cause: err }));
});
connectReq.end();
// socket 走异步 callback 交付;返回 undefined 告知调用方等 callback。
return undefined;
}
}
// 正常场景同一时刻只有一个系统代理;上限只防 resolver 返回值抖动(PAC 按 host 给不同
// 出口)时 agent 无限累积。超限逐出最旧的并销毁其连接池。
const AGENT_POOL_MAX_ENTRIES = 8;
/**
* agent 缓存 key。凭证参与 key:同地址不同凭证不能共享连接池。上游协议也参与:
* https 与 http 上游用的是不同基类的 agent(TLS 包装 vs 裸隧道),不能混用同一个。
* key 只在进程内做缓存标识,不进日志。
*
* 用 JSON 数组而不是拼接:字段本身可能含分隔符,拼接会撞车 —— 用户名/密码
* `a:b` + `c` 与 `a` + `b:c` 拼出来是同一个 key,第二次查询会复用按第一组凭证建的
* agent,用错身份去认证。JSON 编码逐字段带引号与转义,不存在这种歧义。
*/
export function outboundProxyAgentKey(proxy: OutboundProxyTarget, upstreamProtocol: 'http:' | 'https:'): string {
return JSON.stringify([
proxy.kind,
proxy.url,
proxy.authHeader ?? '',
proxy.username ?? '',
proxy.password ?? '',
upstreamProtocol,
]);
}
/**
* 按 key 缓存出站代理 agent,复用其 keep-alive 连接池。构造交给调用方的 `create`
* (HTTP 隧道与 SOCKS5 的 agent 分别定义在本模块与 socks5.ts,本模块不反向依赖它)。
* 生命周期随 proxy server:dispose 时销毁全部 agent(断开空闲隧道)。
*/
export class OutboundProxyAgentPool {
private readonly agents = new Map<string, OutboundProxyAgent>();
get(key: string, create: () => OutboundProxyAgent): OutboundProxyAgent {
const existing = this.agents.get(key);
if (existing) return existing;
if (this.agents.size >= AGENT_POOL_MAX_ENTRIES) {
const oldest = this.agents.keys().next().value;
if (oldest !== undefined) {
this.agents.get(oldest)?.destroy();
this.agents.delete(oldest);
}
}
const agent = create();
this.agents.set(key, agent);
return agent;
}
destroy(): void {
for (const agent of this.agents.values()) agent.destroy();
this.agents.clear();
}
}