llm-api-gateway-cli 1.0.0

package/lib/commands.js

@@ -0,0 +1,468 @@
+/**
+ * 交互式斜杠命令（M2 → A2 跨端对齐）
+ *
+ * 结构没变：一张表（COMMANDS）+ 一个只依赖 ctx 的 run；循环只做查表，不认识就当作普通输入丢给模型。
+ * A2 对齐做的四件事（口径见网关仓库 docs/SLASH-CLI-ALIGNMENT-20260916.md §3/§4/§6.2）：
+ *  · 每条命令补齐**统一元数据**：name / aliases / args / needsArgs / group / capability / surfaces。
+ *    其中 `capability`（能不能跑：local / api / fs）与 `surfaces`（在这端有没有意义：cli / web / hub）正交，
+ *    与网关侧 `proxy/app/static/js/slash.js` 同一套字段名 —— 同名指令的 args/capability 由两侧的
+ *    跨端契约断言钉住（本文件 commandRows() 是给断言用的机器可读视图）。
+ *  · parseSlash 升级：支持别名、双引号分词、大小写不敏感、全角斜杠、`bare` 裸词（exit / quit），
+ *    并返回 argv。**大小写不敏感是有意的行为变更**：网关 Web 侧一直不敏感，同一台机器上不该两套规矩。
+ *  · 新增 suggest()：REPL **没有候选面板**（`cli-agent.js` 的 readInput 用 rl.question，无 raw mode，
+ *    项目取向是"不引 TUI 库"），所以前缀只补全不执行，候选以**文本列表**打印。
+ *  · `/exit` `/quit` / `exit` / `quit` 从 cli-agent 的硬编码判断搬进本表（`bare: true`），
+ *    让"表"重新成为唯一出处；assertRegistry() 在加载时自检（别名撞车、capability/surfaces 非法、
+ *    缺 run）——这类错误的表现是"某条命令永远调不到"，不报错、不崩，最难查。
+ *
+ * ctx 约定（cli-agent 提供实现，测试提供假实现）：
+ *   { session, setSession(next), newSession(), setModel(name), cfg,
+ *     say(text), persist() }
+ */
+
+import { formatCost } from './pricing.js';
+import { configCommand, splitConfigArg } from './configcmd.js';
+// /mcp：本密钥可用的 MCP 工具清单来自网关（GET /v1/mcp/tools），本文件只负责把它打印给人看
+import { refreshMcpTools, mcpStatusText, mcpToolList } from './mcp.js';
+
+/** 压缩上下文时保留最近几条消息（不含 system） */
+const COMPACT_KEEP = 6;
+
+/** 能力：local = 纯本地；api = 需要网关接口；fs = 需要本地文件/工作目录。 */
+export const CAPABILITIES = ['local', 'api', 'fs'];
+
+/** 端：这条命令在哪一端有意义。CLI 目前只声明 cli；hub（Web 任务页）要等 A3 落地后再加。 */
+export const SURFACES = ['web', 'cli', 'hub'];
+
+/* ============================ 解析 ============================ */
+
+/** 按空白切分，支持双引号包裹带空格的参数；引号未闭合 → 抛错（由 parseSlash 转成命令错误）。 */
+export function tokenize(s) {
+  const out = [];
+  const raw = String(s ?? '');
+  let i = 0;
+  while (i < raw.length) {
+    while (i < raw.length && /\s/.test(raw[i])) i++;
+    if (i >= raw.length) break;
+    if (raw[i] === '"') {
+      const end = raw.indexOf('"', i + 1);
+      if (end < 0) throw new Error('引号没有闭合（用 " 包住带空格的参数）');
+      out.push(raw.slice(i + 1, end));
+      i = end + 1;
+    } else {
+      let j = i;
+      while (j < raw.length && !/\s/.test(raw[j])) j++;
+      out.push(raw.slice(i, j));
+      i = j;
+    }
+  }
+  return out;
+}
+
+function findByAlias(word) {
+  const key = String(word || '').toLowerCase();
+  return Object.keys(COMMANDS).find((n) =>
+    (COMMANDS[n].aliases || []).some((a) => String(a).toLowerCase() === key)) || null;
+}
+
+/**
+ * 把一行输入解析成命令；不是命令、未知命令、`//` 转义都返回 null（调用方按普通输入处理）。
+ *
+ * 返回 `{ name, cmd, arg, argv, error? }`：
+ *   name  规范化后的表键（带 `/`，如 `/model`）—— 保留旧字段，循环里仍可用 COMMANDS[name]
+ *   arg   参数原串（保留旧契约，`/model gpt-4o` → 'gpt-4o'）
+ *   argv  分词结果（分词失败时为空数组 + error），供需要多参数的命令使用
+ *   error 参数不合法（引号未闭合等）：调用方应打印错误与用法，**不要**执行
+ */
+export function parseSlash(line) {
+  const raw0 = typeof line === 'string' ? line : '';
+  const raw = raw0.trim().replace(/^／/, '/');
+  if (!raw) return null;
+  if (raw.startsWith('//')) return null;                 // 转义：当普通文本（见 unescapeSlash）
+
+  if (!raw.startsWith('/')) {                            // 裸词（只有 bare: true 的命令认）
+    const word = raw.toLowerCase();
+    const name = COMMANDS['/' + word] ? '/' + word : findByAlias(word);
+    const cmd = name ? COMMANDS[name] : null;
+    return cmd && cmd.bare ? { name, cmd, arg: '', argv: [] } : null;
+  }
+
+  const sp = raw.search(/\s/);
+  const head = (sp === -1 ? raw : raw.slice(0, sp)).toLowerCase();
+  const rest = sp === -1 ? '' : raw.slice(sp + 1).trim();
+  const name = COMMANDS[head] ? head : findByAlias(head.slice(1));
+  if (!name) return null;
+
+  let argv = [];
+  let error;
+  try {
+    argv = tokenize(rest);
+  } catch (e) {
+    error = e.message;
+  }
+  return { name, cmd: COMMANDS[name], arg: rest, argv, error };
+}
+
+/** `//xxx` → 该发给模型的文本（去掉一个斜杠）；不是转义写法则返回 null。 */
+export function unescapeSlash(line) {
+  const raw = typeof line === 'string' ? line.trim() : '';
+  return raw.startsWith('//') ? raw.slice(1) : null;
+}
+
+/** 前缀候选（供 REPL 打印列表）：主名前缀 + 别名前缀；主名优先，返回命令条目数组。 */
+export function suggest(prefix) {
+  const p = String(prefix ?? '').toLowerCase();
+  if (!p) return [];
+  const scored = [];
+  Object.keys(COMMANDS).forEach((n) => {
+    const cmd = COMMANDS[n];
+    const name = n.slice(1).toLowerCase();
+    let score = -1;
+    if (name === p) score = 0;
+    else if (name.startsWith(p)) score = 1;
+    else if ((cmd.aliases || []).some((a) => String(a).toLowerCase().startsWith(p))) score = 2;
+    if (score >= 0) scored.push({ cmd, score, name });
+  });
+  scored.sort((a, b) => (a.score - b.score) || a.name.localeCompare(b.name));
+  return scored.map((s) => s.cmd);
+}
+
+/** 改过名的旧名（与网关侧同一机制）。CLI 目前没有改名的命令 —— 保留空表与查找函数，
+ *  是为了将来改名时"回显指引"这条路已经通了，而不是临时塞一个 if。 */
+export const MOVED = [];
+
+export function findMoved(word) {
+  const key = String(word || '').toLowerCase().replace(/^\//, '');
+  return MOVED.find((m) => m.name === key || (m.aliases || []).includes(key)) || null;
+}
+
+/* ============================ 自检（加载即跑） ============================ */
+
+/** 别名/主名唯一、capability/surfaces 合法、必填字段齐全、MOVED 不撞名。 */
+export function assertRegistry(registry = COMMANDS) {
+  const seen = new Map();
+  Object.keys(registry).forEach((key) => {
+    const c = registry[key];
+    if (!key.startsWith('/')) throw new Error(`命令键必须以 / 开头：${key}`);
+    if (!c || !c.name) throw new Error(`${key} 缺少 name`);
+    if (key !== '/' + c.name) throw new Error(`${key} 与 name=${c.name} 不一致`);
+    if (CAPABILITIES.indexOf(c.capability) < 0) {
+      throw new Error(`/${c.name} 的 capability 非法：${c.capability}（应为 ${CAPABILITIES.join(' / ')}）`);
+    }
+    if (!Array.isArray(c.surfaces) || !c.surfaces.length ||
+        c.surfaces.some((s) => SURFACES.indexOf(s) < 0)) {
+      throw new Error(`/${c.name} 的 surfaces 非法：${JSON.stringify(c.surfaces)}（应为 ${SURFACES.join(' / ')} 的子集）`);
+    }
+    if (!c.group) throw new Error(`/${c.name} 缺少 group`);
+    if (typeof c.run !== 'function') throw new Error(`/${c.name} 缺少 run()`);
+    [c.name].concat(c.aliases || []).forEach((n) => {
+      const k = String(n).toLowerCase();
+      if (seen.has(k)) throw new Error(`命令名冲突：${k} 同时属于 ${seen.get(k)} 与 /${c.name}`);
+      seen.set(k, '/' + c.name);
+    });
+  });
+  MOVED.forEach((m) => {
+    if (seen.has(m.name)) throw new Error(`改名表冲突：${m.name} 既在命令表又在 MOVED 表`);
+  });
+  return true;
+}
+
+/* ============================ 命令表 ============================ */
+
+/**
+ * 极简行级 diff：掐掉公共前后缀，中间的就是改动。
+ *
+ * 为什么不上正经 diff 算法：审批预览里只需要「让我看出改了哪几行」，
+ * 而引入 diff 库与项目「零第三方依赖（除两个官方 SDK）」的取向冲突。
+ * 前缀/后缀对齐对「改几处」这种场景足够，最坏情况多打几行而已。
+ *
+ * @returns {{lines:string[], removed:number, added:number}}
+ */
+export function diffLines(oldText, newText, { maxLines = 40 } = {}) {
+  const a = String(oldText ?? '').split('\n');
+  const b = String(newText ?? '').split('\n');
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--;
+    endB--;
+  }
+  const removed = a.slice(start, endA);
+  const added = b.slice(start, endB);
+  const lines = [];
+  for (const l of removed) lines.push(`- ${l}`);
+  for (const l of added) lines.push(`+ ${l}`);
+  const clipped = lines.length > maxLines ? [...lines.slice(0, maxLines), `…（另有 ${lines.length - maxLines} 行改动未显示）`] : lines;
+  return { lines: clipped, removed: removed.length, added: added.length };
+}
+
+export const COMMANDS = {
+  '/help': {
+    name: 'help',
+    aliases: ['?', 'h'],
+    args: '[命令名]',
+    needsArgs: false,
+    group: '帮助',
+    capability: 'local',
+    surfaces: ['cli'],
+    usage: '/help [命令名]',
+    desc: '显示命令列表，或查看某条命令的用法',
+    run: (ctx, arg) => ctx.say(helpText(arg)),
+  },
+  '/model': {
+    name: 'model',
+    aliases: [],
+    args: '[模型名]',
+    needsArgs: false,
+    group: '模型与请求参数',
+    capability: 'local',
+    surfaces: ['cli'],
+    usage: '/model [模型名]',
+    desc: '查看或切换当前模型（保留上下文）',
+    run: (ctx, arg) => {
+      if (!arg) return ctx.say(`当前模型：${ctx.session.model}（用法：/model <模型名>）`);
+      ctx.setModel(arg);
+      ctx.persist();
+      ctx.say(`模型已切换为 ${arg}（上下文保留，下一步生效）。`);
+    },
+  },
+  '/config': {
+    name: 'config',
+    aliases: [],
+    args: '[list|get|set|unset …]',
+    needsArgs: false,
+    group: '配置',
+    capability: 'fs',              // 读写本地配置文件（settingsFilePath()）
+    surfaces: ['cli'],
+    usage: '/config [list|get|set|unset …]',
+    desc: '查看或修改持久化配置（与 gateway-agent config 同一套）',
+    run: (ctx, arg) => {
+      const r = configCommand(splitConfigArg(arg), ctx.configOpts ? ctx.configOpts() : {});
+      // 成功走 say，失败也走 say —— REPL 里没有独立的 stderr 通道，
+      // 而且这条命令的输出本来就是给人看的
+      const text = (r.code === 0 ? r.out : r.err).trimEnd();
+      ctx.say(text || '（没有输出）');
+    },
+  },
+  '/cost': {
+    name: 'cost',
+    aliases: [],
+    args: '—',
+    needsArgs: false,
+    group: '用量与费用',
+    capability: 'local',
+    surfaces: ['cli'],
+    usage: '/cost',
+    desc: '查看本会话累计 token 与费用粗估（口径：内置单价表）',
+    run: (ctx) => {
+      ctx.say(formatCost(ctx.session.usage, ctx.session.model));
+      // 自报口径：网关是记账方，内置表只是本机估算。两端口径必须能被一眼区分，
+      // 否则同一台机器上 /cost 与网关账单会"各自说各自的数"（对齐方案 §3.2）。
+      ctx.say('口径：内置单价表估算，非网关计费口径（网关 /admin/prices 才是记账口径）。');
+    },
+  },
+  '/mcp': {
+    name: 'mcp',
+    aliases: [],
+    args: '[refresh]',
+    needsArgs: false,
+    group: '工具与 MCP',
+    capability: 'api',              // 清单来自网关 GET /v1/mcp/tools
+    surfaces: ['cli'],
+    usage: '/mcp [refresh]',
+    desc: '查看本密钥可用的 MCP 工具清单（refresh 立即重拉，否则用缓存）',
+    // 异步：refresh 要真的出网（REPL 循环对 run 的返回值已经 await）
+    run: async (ctx, arg) => {
+      const force = String(arg || '').trim().toLowerCase() === 'refresh';
+      const cfg = ctx.cfg || {};
+      // refreshMcpTools 永不抛（best-effort）：网关没开 MCP / 断网也只记一行原因
+      const info = await refreshMcpTools({ force, baseUrl: cfg.baseUrl, key: cfg.key });
+      ctx.say(mcpStatusText());
+      for (const t of mcpToolList()) {
+        const what = [t.server, t.tool].filter(Boolean).join('/');
+        const brief = String(t.description || '').split('\n')[0].slice(0, 60);
+        ctx.say(`  ${t.name}${what ? `  [${what}]` : ''}${brief ? `  ${brief}` : ''}`);
+      }
+      if (info?.error) {
+        // 把「发没发请求、为什么没有」直说出来：否则「CLI 没拉清单」（GATEWAY_MCP=off、
+        // 密钥配置不全）与「拉了但网关没给」（404/断网）在用户眼里长得一模一样，只能去翻网关日志。
+        // attemptedAt 是 lib/mcp.js 在真正发请求时记下的，所以这句是事实而不是推测。
+        ctx.say(info.attemptedAt
+          ? `  · 已请求 GET ${cfg.baseUrl || '?'}/v1/mcp/tools（${force ? '强制刷新' : '按需'}）：${info.error}`
+          : `  · 未向网关发出请求：${info.error}`);
+        // GATEWAY_MCP=off 是用户自己关的，再让他去查网关就是误导
+        if (!/GATEWAY_MCP=off/.test(info.error)) {
+          ctx.say('  · 常见原因：网关未开启 MCP / 该密钥未绑定任何工具 / 网关版本不带这个接口');
+          ctx.say('  · 看细节：GATEWAY_MCP_DEBUG=1 重跑，每次拉取与调用都会打到 stderr');
+        }
+      } else if (force) {
+        ctx.say('  · 已强制重拉（后续对话立即用这份新清单）');
+      } else {
+        ctx.say('  · 清单来自网关 GET /v1/mcp/tools（60 秒 TTL）；/mcp refresh 可立即重拉');
+      }
+    },
+  },
+  '/reset': {
+    name: 'reset',
+    aliases: [],
+    args: '—',
+    needsArgs: false,
+    group: '会话与上下文',
+    capability: 'local',
+    surfaces: ['cli'],
+    usage: '/reset',
+    desc: '重开会话（清空上下文，工作目录不变）',
+    run: (ctx) => {
+      ctx.setSession(ctx.newSession());
+      ctx.persist();
+      ctx.say('已重开会话（上下文清空，工作目录不变）。');
+    },
+  },
+  '/clear': {
+    name: 'clear',
+    aliases: [],
+    args: '—',
+    needsArgs: false,
+    group: '会话与上下文',
+    capability: 'local',
+    surfaces: ['cli'],
+    usage: '/clear',
+    desc: '/reset 的别名（清空上下文重开）',
+    run: (ctx, arg, argv) => COMMANDS['/reset'].run(ctx, arg, argv),
+  },
+  '/resume': {
+    name: 'resume',
+    aliases: [],
+    args: '<会话id>',
+    needsArgs: false,
+    group: '会话与上下文',
+    capability: 'fs',              // 会话记录在本地磁盘
+    surfaces: ['cli'],
+    usage: '/resume <会话id>',
+    desc: '切到另一个已保存的会话（不带参数列出最近会话）',
+    run: (ctx, arg) => {
+      if (!arg) {
+        const list = ctx.listSessions ? ctx.listSessions() : [];
+        if (!list.length) return ctx.say('没有已保存的会话。（用 /resume <id> 恢复；会话目录见启动横幅）');
+        const lines = list.slice(0, 10).map((s) => `  ${s.id}  ${s.model || '?'}  ${s.messages || 0} 条  ${new Date(s.touchedAt).toLocaleString()}`);
+        return ctx.say(`最近的会话：\n${lines.join('\n')}\n用 /resume <id> 恢复其中一个。`);
+      }
+      const rec = ctx.loadSession ? ctx.loadSession(arg) : null;
+      if (!rec) return ctx.say(`找不到会话 ${arg}（id 是 UUID；可用 /resume 不带参数列出）。`);
+      ctx.setSession(rec);
+      ctx.persist();
+      ctx.say(`已切换到会话 ${rec.id}（${rec.model || '?'}，工作目录 ${rec.workingDir || '?'}）。`);
+    },
+  },
+  '/compact': {
+    name: 'compact',
+    aliases: [],
+    args: '—',
+    needsArgs: false,
+    group: '会话与上下文',
+    capability: 'local',
+    surfaces: ['cli'],
+    usage: '/compact',
+    desc: `压缩上下文：只保留最近 ${COMPACT_KEEP} 条消息（本地操作，不调用模型）`,
+    run: (ctx) => {
+      const msgs = ctx.session.messages;
+      if (!Array.isArray(msgs) || msgs.length <= COMPACT_KEEP + 1) return ctx.say('上下文不长，无需压缩。');
+      const head = msgs[0];
+      const dropped = msgs.length - 1 - COMPACT_KEEP;
+      const note = {
+        role: 'user',
+        content: `（本地已压缩上下文：较早的 ${dropped} 条消息被丢弃。如仍需要那些信息，请重新说明。）`,
+      };
+      ctx.session.messages = [head, note, ...msgs.slice(-COMPACT_KEEP)];
+      ctx.persist();
+      ctx.say(`已压缩上下文：丢弃 ${dropped} 条较早消息，保留最近 ${COMPACT_KEEP} 条。`);
+    },
+  },
+  '/exit': {
+    name: 'exit',
+    aliases: ['quit'],
+    args: '—',
+    needsArgs: false,
+    group: '进程',
+    capability: 'local',
+    surfaces: ['cli'],
+    bare: true,                    // 裸词 exit / quit 也认（原来硬编码在 cli-agent 的循环里）
+    usage: '/exit',
+    desc: '退出（裸词 exit / quit 同样有效）',
+    run: () => ({ exit: true }),
+  },
+};
+
+/** 表里的全部主名，按定义顺序（帮助、补全、测试都用它）。 */
+export const COMMAND_NAMES = Object.keys(COMMANDS);
+
+/** 机器可读的命令行（跨端契约断言用；字段与网关侧 commandRows() 一致）。 */
+export function commandRows(registry = COMMANDS) {
+  return Object.keys(registry).map((key) => {
+    const c = registry[key];
+    return {
+      name: c.name,
+      aliases: (c.aliases || []).slice(),
+      args: c.args || '—',
+      usage: c.usage,
+      help: c.desc,
+      group: c.group,
+      capability: c.capability,
+      surfaces: (c.surfaces || []).slice(),
+      needsArgs: !!c.needsArgs,
+    };
+  });
+}
+
+/** 能力标记（写给终端看的，不是机器口径）。 */
+function capNote(c) {
+  if (c.capability === 'fs') return '（读写本地文件）';
+  if (c.capability === 'api') return '（需网关接口）';
+  return '';
+}
+
+/**
+ * 帮助文本：无参数 = 分组总表；带参数 = 单条用法。
+ * 不做 Markdown（终端里难看），也不做候选面板（无 raw mode）。
+ */
+export function helpText(name) {
+  if (name) {
+    const bare = String(name).replace(/^\//, '');
+    const key = '/' + bare.toLowerCase();
+    const cmd = COMMANDS[key] || COMMANDS[findByAlias(bare.toLowerCase()) || ''];
+    if (!cmd) return `没有这条命令：${name}（用 /help 看全部）`;
+    const lines = [
+      `${cmd.usage}    ${cmd.desc}`,
+      `  别名：${(cmd.aliases || []).length ? cmd.aliases.map((a) => '/' + a).join(' ') : '—'}`,
+      `  能力：${cmd.capability}${capNote(cmd)}　端：${(cmd.surfaces || []).join(' / ')}`,
+    ];
+    if (cmd.bare) lines.push(`  裸词也可以：${cmd.name}`);
+    return lines.join('\n');
+  }
+  const width = Math.max(...COMMAND_NAMES.map((n) => COMMANDS[n].usage.length));
+  const groups = [];
+  COMMAND_NAMES.forEach((n) => {
+    const g = COMMANDS[n].group || '其他';
+    if (!groups.includes(g)) groups.push(g);
+  });
+  const rows = [];
+  groups.forEach((g) => {
+    rows.push(`  ${g}`);
+    COMMAND_NAMES.filter((n) => (COMMANDS[n].group || '其他') === g).forEach((n) => {
+      const c = COMMANDS[n];
+      rows.push(`    ${c.usage.padEnd(width)}  ${c.desc}`);
+    });
+  });
+  return [
+    '斜杠命令（/help <命令名> 看单条用法；同名命令与网关 Web 端语义一致）：',
+    ...rows,
+    '',
+    '其它输入直接交给模型；行尾写 \\ 可续行。',
+    '想让 /clear 这样的文字原样发给模型：写成 //clear。',
+  ].join('\n');
+}
+
+// 加载即自检：配置错误在这里就炸，而不是让某条命令静默失效。
+assertRegistry(COMMANDS);

package/lib/common.js

@@ -0,0 +1,196 @@
+/**
+ * 模式四 / 模式五 共用的基础工具：
+ * .env 加载、命令行参数解析、JSON 收发、SSE 输出、密钥脱敏。
+ * 抽出来是因为两个服务（server.js 与 task-server.js）都要用同一套约定，
+ * 避免各自抄一遍后行为漂移。
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_BASE_URL = 'http://127.0.0.1:9000';
+
+/**
+ * 读取 .env（先脚本目录、再当前工作目录），不覆盖已存在的环境变量。
+ * 用函数声明是为了能在模块顶层前置调用，让 GATEWAY_MODEL 等参与默认值计算。
+ */
+export function loadDotEnv(scriptDir) {
+  for (const file of [path.join(scriptDir, '.env'), path.join(process.cwd(), '.env')]) {
+    if (!existsSync(file)) continue;
+    for (const raw of readFileSync(file, 'utf8').split(/\r?\n/)) {
+      const m = raw.match(/^\s*([A-Za-z_][\w.-]*)\s*=\s*(.*)\s*$/);
+      if (!m) continue;
+      const value = m[2].replace(/^['"]|['"]$/g, '');
+      if (!(m[1] in process.env)) process.env[m[1]] = value;
+    }
+  }
+}
+
+/** 只接受真正的字符串参数值：值型选项缺值时会退化成布尔 true，必须挡掉 */
+export function strArg(v) {
+  return typeof v === 'string' && v.trim() ? v.trim() : '';
+}
+
+/**
+ * 取密钥：--key > SK / GATEWAY_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN > .env
+ * 五种别名都认，是为了让四个 CLI 的密钥来源完全一致 —— 之前 cli-anthropic 只认
+ * ANTHROPIC_API_KEY、cli-claude-code 只认 ANTHROPIC_AUTH_TOKEN，同一个 .env 换个入口就报缺密钥。
+ */
+export function resolveKey(args, env = process.env) {
+  for (const c of [args?.key, env.SK, env.GATEWAY_KEY, env.OPENAI_API_KEY, env.ANTHROPIC_API_KEY, env.ANTHROPIC_AUTH_TOKEN]) {
+    const v = strArg(c);
+    if (v) return v;
+  }
+  return '';
+}
+
+export function resolveBaseUrl(args, env = process.env) {
+  const raw = strArg(args?.['base-url']) || strArg(env.GATEWAY_BASE_URL) || DEFAULT_BASE_URL;
+  return raw.replace(/\/+$/, '');
+}
+
+/** 端口解析：非法值返回 null，由调用方报错退出 */
+export function resolvePort(args, env, envName, fallback) {
+  const raw = strArg(args?.port) || strArg(env?.[envName]) || String(fallback);
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 && n <= 65535 ? n : null;
+}
+
+/**
+ * 通用参数解析。valueFlags/boolFlags 形如 { '--port': 'port', '-p': 'port' }。
+ * 值型选项后面若紧跟另一个选项（以 - 开头）则视为缺值。
+ * `--` 之后的参数原样收进 `_`，不再当选项解析（透传给下游命令时要用）。
+ */
+export function parseArgs(argv, valueFlags = {}, boolFlags = {}) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      args._.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a in valueFlags) {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        args[valueFlags[a]] = next;
+        i++;
+      } else {
+        args[valueFlags[a]] = true;
+      }
+      continue;
+    }
+    if (a in boolFlags) {
+      args[boolFlags[a]] = true;
+      continue;
+    }
+    if (a.startsWith('--') && a.includes('=')) {
+      const eq = a.indexOf('=');
+      args[a.slice(2, eq)] = a.slice(eq + 1);
+      continue;
+    }
+    if (a.startsWith('--')) {
+      args[a.slice(2)] = true;
+      continue;
+    }
+    args._.push(a);
+  }
+  return args;
+}
+
+export function sendJson(res, status, obj) {
+  const payload = JSON.stringify(obj);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(payload);
+}
+
+export function readBody(req, limit = 8 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    let size = 0;
+    req.setEncoding('utf8');
+    req.on('data', (c) => {
+      size += Buffer.byteLength(c);
+      if (size > limit) {
+        reject(Object.assign(new Error('请求体过大'), { status: 413 }));
+        req.destroy();
+        return;
+      }
+      data += c;
+    });
+    req.on('end', () => {
+      if (!data) return resolve({});
+      try {
+        resolve(JSON.parse(data));
+      } catch {
+        reject(Object.assign(new Error('请求体不是合法 JSON'), { status: 400 }));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+export function maskKey(key) {
+  if (!key) return '';
+  if (key.length <= 12) return `${key.slice(0, 4)}****`;
+  return `${key.slice(0, 8)}****${key.slice(-4)}`;
+}
+
+/**
+ * 会话/任务 id 的安全字符集。W3C Baggage 的 baggage-octet 不允许逗号、分号、
+ * 反斜杠、引号、括号和空白（它们会把 baggage 语法拆坏），所以只放行这一小撮字符。
+ * UUID 的全部字符都在里面。
+ */
+export const BAGGAGE_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+/**
+ * 把「这次请求属于哪个任务/会话」编成 W3C Baggage 头值，id 不合法就返回 null。
+ *
+ * 为什么是 baggage：这是 W3C 为跨服务传播 session.id 这类值定义的标准头，
+ * 网关、链路追踪、日志系统都能直接读它，不需要谁去认识一套私有约定；
+ * 而且标准头本来就该原样透传，代理转发它不算篡改请求语义。
+ *
+ * 为什么宁可不发也不硬塞：id 里混进逗号/分号会破坏 baggage 语法，
+ * 让接收方解析出别的东西。发送方拿不到合法 id 时就不发 —— 网关会退回
+ * 自己的推断口径（system + 首条用户指令指纹），功能照常，只是不够权威。
+ */
+export function sessionBaggage(id) {
+  const v = String(id ?? '');
+  return BAGGAGE_ID_RE.test(v) ? `session.id=${v}` : null;
+}
+
+/** 从上游错误响应里尽量挖出可读的中文原因 */
+export async function errorText(resp) {
+  const text = await resp.text().catch(() => '');
+  try {
+    const j = JSON.parse(text);
+    return j?.error?.message || j?.message || j?.detail || text.slice(0, 500) || `HTTP ${resp.status}`;
+  } catch {
+    return text.slice(0, 500) || `HTTP ${resp.status}`;
+  }
+}
+
+/** 建立 SSE 响应，返回 send(obj) —— 每个事件一帧 data: {...} */
+export function openSse(res) {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache, no-transform',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+  });
+  return (obj) => res.write(`data: ${JSON.stringify(obj)}\n\n`);
+}
+
+/** 判断监听地址是否只对本机开放（决定要不要开文件系统浏览接口） */
+export function isLoopbackHost(host) {
+  if (!host) return false;
+  const h = String(host).toLowerCase().replace(/^\[|\]$/g, '');
+  return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h.startsWith('127.');
+}
+
+/** 静态资源安全解析：解析后的路径必须仍在 baseDir 内 */
+export function resolveStatic(baseDir, urlPath) {
+  const rel = urlPath === '/' ? 'index.html' : decodeURIComponent(urlPath).replace(/^\/+/, '');
+  const file = path.resolve(baseDir, rel);
+  if (file !== baseDir && !file.startsWith(baseDir + path.sep)) return null;
+  return file;
+}