llm-api-gateway-cli 1.0.5 → 1.0.6

package/lib/i18n.js

@@ -0,0 +1,80 @@
+/**
+ * CLI 语言（20260922）：只覆盖**命令行侧**的输出
+ *
+ * 范围：help / 子命令输出 / 启动横幅 / 报错 / REPL 提示 / 写入批准闸门。
+ * **不覆盖**：Web 界面与手册页的文案、`/api/commands` 下发给网页的清单、发往模型的系统提示词 ——
+ * 那些不是"输出语言"，是另一个决定（见 docs/20260922-迭代计划-英文入口README.md 的遗留项）。
+ *
+ * 四条纪律：
+ *  1. **默认中文**：没给 `--lang` / `LLM_GATEWAY_LANG` 时就是 zh，一个字符都不变 ——
+ *     既有测试断言的中文文案因此完全不受影响（它们不传语言）。
+ *  2. 只在**入口脚本**里 `setLang(resolveLang(args, env))`，其余模块只管 `pick()`：
+ *     语言是进程级的，ESM 模块单实例，设置一次两边都读得到。
+ *  3. `pick(zh, en)` 必须**在函数里调用**（运行时求值）。写在模块顶层会在 setLang 之前求值，
+ *     那时语言还是默认 zh —— 结果就是"加了英文却还是中文"，而且不报错。
+ *     大段模板的正确写法：`const HELP_ZH = '…'; const HELP_EN = '…'; function help(){ return pick(HELP_ZH, HELP_EN); }`
+ *  4. 不引依赖、不做插值语法：缺英文时**自动回落中文**。给英文用户看到中文，
+ *     也比看到空串 / undefined / 半截句子好。
+ */
+
+/** 支持的语言；要加语言就往这里加，并在 normalizeLang 里给出别名 */
+export const LANGS = ['zh', 'en'];
+export const DEFAULT_LANG = 'zh';
+/** 环境变量名（与 --lang 同效，flag 优先） */
+export const LANG_ENV = 'LLM_GATEWAY_LANG';
+
+let current = DEFAULT_LANG;
+
+/** `zh` / `zh-CN` / `cn` / `en` / `en-US` / `english` … → 'zh' | 'en'；认不出返回 null */
+export function normalizeLang(value) {
+  const s = String(value == null ? '' : value).trim().toLowerCase();
+  if (!s) return null;
+  if (s === 'zh' || s === 'cn' || s === 'chinese' || s.startsWith('zh-') || s.startsWith('zh_')) return 'zh';
+  if (s === 'en' || s === 'english' || s.startsWith('en-') || s.startsWith('en_')) return 'en';
+  return null;
+}
+
+/**
+ * 本次该用哪种语言：`--lang` > `LLM_GATEWAY_LANG` > 默认 zh。
+ * 认不出的值不报错（退回默认），因为语言不该拦住任何一次运行。
+ */
+export function resolveLang(args = {}, env = {}) {
+  const fromArgs = normalizeLang(args && (args.lang ?? args['lang']));
+  if (fromArgs) return fromArgs;
+  const fromEnv = normalizeLang(env && env[LANG_ENV]);
+  if (fromEnv) return fromEnv;
+  return DEFAULT_LANG;
+}
+
+export function setLang(lang) {
+  current = normalizeLang(lang) || DEFAULT_LANG;
+  return current;
+}
+
+export function getLang() {
+  return current;
+}
+
+export function isEn() {
+  return current === 'en';
+}
+
+/**
+ * 双语取词：`pick('中文', 'English')`。
+ * 非英文语言、英文缺失、英文是空串 —— 一律回到中文。
+ */
+export function pick(zh, en) {
+  if (current === 'en' && typeof en === 'string' && en) return en;
+  return zh;
+}
+
+/** `--lang` 的选项说明（各入口的 HELP 里用同一份，避免三处措辞不一致） */
+export function langFlagHelp() {
+  return pick(
+    '      --lang <zh|en>      输出语言（默认 zh，也可用环境变量 LLM_GATEWAY_LANG）',
+    '      --lang <zh|en>      Output language (default zh; env LLM_GATEWAY_LANG)',
+  );
+}
+
+/** 供 CLI 参数解析注册用（各入口把这一项并进自己的 VALUE_FLAGS） */
+export const LANG_FLAG = { '--lang': 'lang' };

package/lib/launcher.js

@@ -14,18 +14,29 @@
  */
 
 import { strArg } from './common.js';
+// CLI 侧语言：启动器由 cli-agent 调用，语言是进程级的 —— **这里不 setLang**，只按需 pick()。
+// setLang 只发生在入口脚本（cli-agent.js），见 lib/i18n.js 纪律 2。
+import { pick } from './i18n.js';
 
 /** 本机 Web UI 的默认端口。事实来源是 `lib/hub.js` 的 `DEFAULT_PORT`，测试会交叉断言两者一致 */
 export const WEB_PORT = 3100;
 
+/**
+ * 两个菜单项。label / desc 是中文（默认语言，逐字不变，测试据此断言），
+ * `labelEn` / `descEn` 是英文，缺了就自动回落中文。
+ *
+ * 注意**不能**在数组里直接写 `pick(...)`：模块顶层求值会赶在入口脚本 setLang 之前，
+ * 结果永远是中文（还不报错）。取词统一放 menuText() 里按当前语言选 ——
+ * 导出形状（value/label/desc）保持不变，只是多了两个英文附加字段。
+ */
 export const TOPICS = [
-  { value: 'chat', label: '对话', desc: '纯聊天，不碰你的文件' },
-  { value: 'task', label: '任务', desc: '在指定目录里真读写文件，每次写入前先问你' },
+  { value: 'chat', label: '对话', labelEn: 'chat', desc: '纯聊天，不碰你的文件', descEn: 'pure chat; your files stay untouched' },
+  { value: 'task', label: '任务', labelEn: 'task', desc: '在指定目录里真读写文件，每次写入前先问你', descEn: 'really reads and writes files in a chosen directory; asks before every write' },
 ];
 
 export const SURFACES = [
-  { value: 'cli', label: '命令行窗口', desc: '就在这个终端里继续' },
-  { value: 'web', label: '网页 UI', desc: `起本机网页 http://127.0.0.1:${WEB_PORT}（聊天 / 任务 / 手册，顶部 Tab 切换）` },
+  { value: 'cli', label: '命令行窗口', labelEn: 'terminal', desc: '就在这个终端里继续', descEn: 'continue in this terminal' },
+  { value: 'web', label: '网页 UI', labelEn: 'web UI', desc: `起本机网页 http://127.0.0.1:${WEB_PORT}（聊天 / 任务 / 手册，顶部 Tab 切换）`, descEn: `start the local web page http://127.0.0.1:${WEB_PORT} (chat / task / manual, switch with the top tabs)` },
 ];
 
 /**
@@ -62,28 +73,41 @@ export function pickOption(answer, list, defaultIndex = 0) {
   return list.find((o) => o.value === s)?.value ?? '';
 }
 
-/** 菜单正文 */
+/** 当前语言下这一项的 label / desc（英文缺失时 pick 自动回落中文） */
+const labelOf = (o) => pick(o.label, o.labelEn);
+const descOf = (o) => pick(o.desc, o.descEn);
+
+/** 菜单正文。中文用全角空格对齐（汉字宽度 2），英文用普通空格 —— 否则英文行里会混进全角字符 */
 export function menuText(title, list) {
-  const lines = list.map((o, i) => `  ${i + 1}) ${o.label.padEnd(6, '　')} ${o.desc}`);
+  const pad = pick('　', ' ');
+  const lines = list.map((o, i) => `  ${i + 1}) ${labelOf(o).padEnd(6, pad)} ${descOf(o)}`);
   return `${title}\n${lines.join('\n')}\n`;
 }
 
+const INTRO_ZH =
+  'LLM API Gateway · 启动器\n' +
+  '两个问题选完就进入对应形态（直接回车 = 选 1）。\n' +
+  '想跳过这个菜单：-p "你的问题"（单轮）· -i（直接进命令行对话）· gateway-task（直接起网页）\n\n';
+const INTRO_EN =
+  'LLM API Gateway · launcher\n' +
+  'Answer two questions and you land in the matching mode (press Enter = option 1).\n' +
+  'To skip this menu: -p "your question" (one-shot) · -i (straight into the CLI chat) · gateway-task (start the web UI)\n\n';
+
 export function launcherIntro() {
-  return (
-    'LLM API Gateway · 启动器\n' +
-    '两个问题选完就进入对应形态（直接回车 = 选 1）。\n' +
-    '想跳过这个菜单：-p "你的问题"（单轮）· -i（直接进命令行对话）· gateway-task（直接起网页）\n\n'
-  );
+  return pick(INTRO_ZH, INTRO_EN);
 }
 
 /** 问一次选择题；问不出合法值返回 null（**不会**替用户默认） */
 async function askChoice(ask, title, list, log, attempts) {
   log(menuText(title, list));
   for (let i = 0; i < attempts; i++) {
-    const answer = await ask('选择', { default: '1' });
+    const answer = await ask(pick('选择', 'choice'), { default: '1' });
     const value = pickOption(answer, list, 0);
     if (value) return value;
-    log(`  ✗ 请输入 1-${list.length}${list.map((o) => ` / ${o.value}`).join('')}\n`);
+    log(pick(
+      `  ✗ 请输入 1-${list.length}${list.map((o) => ` / ${o.value}`).join('')}\n`,
+      `  ✗ enter 1-${list.length}${list.map((o) => ` / ${o.value}`).join('')}\n`,
+    ));
   }
   return null;
 }
@@ -108,34 +132,64 @@ export async function runLauncher({
   port = WEB_PORT,
   attempts = 3,
 } = {}) {
-  if (!ask) return { ok: false, code: 1, error: '当前不是交互终端：请直接用参数表达意图（-p / -i / gateway-task）。' };
+  if (!ask) {
+    return {
+      ok: false,
+      code: 1,
+      error: pick(
+        '当前不是交互终端：请直接用参数表达意图（-p / -i / gateway-task）。',
+        'not an interactive terminal: express your intent with flags instead (-p / -i / gateway-task).',
+      ),
+    };
+  }
 
   log(launcherIntro());
 
-  const topic = await askChoice(ask, '你要做什么？', TOPICS, log, attempts);
-  if (!topic) return { ok: false, code: 1, error: '没有选出「做什么」，已退出（没有改动任何配置）。' };
+  const topic = await askChoice(ask, pick('你要做什么？', 'What do you want to do?'), TOPICS, log, attempts);
+  if (!topic) {
+    return {
+      ok: false,
+      code: 1,
+      error: pick('没有选出「做什么」，已退出（没有改动任何配置）。', 'no choice for "what to do"; exiting (nothing was changed).'),
+    };
+  }
 
-  const surface = await askChoice(ask, '要在哪里跑？', SURFACES, log, attempts);
-  if (!surface) return { ok: false, code: 1, error: '没有选出「在哪里跑」，已退出（没有改动任何配置）。' };
+  const surface = await askChoice(ask, pick('要在哪里跑？', 'Where should it run?'), SURFACES, log, attempts);
+  if (!surface) {
+    return {
+      ok: false,
+      code: 1,
+      error: pick('没有选出「在哪里跑」，已退出（没有改动任何配置）。', 'no choice for "where to run"; exiting (nothing was changed).'),
+    };
+  }
 
   const plan = resolvePlan({ topic, surface, port });
 
   // 任务 + 命令行：还得知道在哪个目录干活（这是任务态与纯对话唯一的区别）
   if (plan.kind === 'cli' && plan.needWorkDir) {
-    const answer = await ask(`任务工作目录 [${cwd}]`, { default: cwd });
+    const answer = await ask(pick(`任务工作目录 [${cwd}]`, `Task working directory [${cwd}]`), { default: cwd });
     plan.workDir = strArg(answer) || cwd;
   }
 
   if (plan.kind === 'web') {
-    log(`\n→ 起本机 Web UI：${plan.url}${plan.entry === 'task' ? '（任务页）' : '（聊天页）'}\n  停止：Ctrl+C\n\n`);
-    if (!startWeb) return { ok: false, code: 1, plan, error: '内部错误：没有注入 startWeb。' };
+    log(pick(
+      `\n→ 起本机 Web UI：${plan.url}${plan.entry === 'task' ? '（任务页）' : '（聊天页）'}\n  停止：Ctrl+C\n\n`,
+      `\n→ starting the local web UI: ${plan.url}${plan.entry === 'task' ? ' (task page)' : ' (chat page)'}\n  stop: Ctrl+C\n\n`,
+    ));
+    if (!startWeb) {
+      return { ok: false, code: 1, plan, error: pick('内部错误：没有注入 startWeb。', 'internal error: startWeb was not injected.') };
+    }
     return { ok: true, ...(await startWeb(plan)), plan };
   }
 
-  log(
+  log(pick(
     `\n→ 命令行${plan.topic === 'task' ? `任务态（工作目录 ${plan.workDir}，写入前会问你）` : '对话'}\n` +
       '  退出：/exit 或 Ctrl+C\n\n',
-  );
-  if (!startCli) return { ok: false, code: 1, plan, error: '内部错误：没有注入 startCli。' };
+    `\n→ CLI ${plan.topic === 'task' ? `task mode (working directory ${plan.workDir}; asks before writes)` : 'chat'}\n` +
+      '  quit: /exit or Ctrl+C\n\n',
+  ));
+  if (!startCli) {
+    return { ok: false, code: 1, plan, error: pick('内部错误：没有注入 startCli。', 'internal error: startCli was not injected.') };
+  }
   return { ok: true, ...(await startCli(plan)), plan };
 }

package/lib/mcp.js

@@ -23,6 +23,10 @@
  *     （`mcpToolSpecs(reserved)` 的 reserved 就是为此传入的）。
  */
 import { sessionBaggage } from './common.js';
+// CLI 侧语言：mcpStatusText 会打到启动横幅与 /mcp 的输出里（默认中文）
+import { pick } from './i18n.js';
+// 管理面（改绑 / 自助登记）走另一个模块，但**共用同一份连接状态**（见 configureMcp）
+import { configureMcpAdmin } from './mcpadmin.js';
 
 /**
  * 「这次调用属于哪个任务节点」的头。
@@ -91,6 +95,9 @@ export function configureMcp({ baseUrl, key, fetchImpl, ttlMs } = {}) {
   }
   cache.baseUrl = conn.baseUrl;
   cache.key = conn.key;
+  // 管理面（/mcp bind|mode|add|rm）用同一份地址与密钥：两边各存一份迟早会不一样
+  // （换了网关却只有一边生效的表现是「清单来自新网关、改绑改到旧网关」）。
+  configureMcpAdmin({ baseUrl: conn.baseUrl, key: conn.key, fetchImpl: conn.fetchImpl });
   return conn;
 }
 
@@ -300,14 +307,17 @@ export function mcpPreview(name, args = {}) {
   };
 }
 
-/** 会话开场/排障用的一行状态 */
+/** 会话开场/排障用的一行状态（CLI 侧输出：横幅与 /mcp 都会用到，按当前 CLI 语言取词） */
 export function mcpStatusText() {
   const usable = usableTools();
-  if (!cache.loaded && !cache.error) return 'MCP：未加载';
-  if (cache.error) return `MCP：不可用（${cache.error}）`;
-  if (!usable.length) return 'MCP：本密钥未绑定任何可用工具';
-  const names = cache.servers.map((s) => `${s.name}(${s.tool_count})`).join('、');
-  return `MCP：${usable.length} 个工具 · ${names}${cache.mode ? ` · 模式 ${cache.mode}` : ''}`;
+  if (!cache.loaded && !cache.error) return pick('MCP：未加载', 'MCP: not loaded');
+  if (cache.error) return pick(`MCP：不可用（${cache.error}）`, `MCP: unavailable (${cache.error})`);
+  if (!usable.length) return pick('MCP：本密钥未绑定任何可用工具', 'MCP: this key has no usable tools bound');
+  const names = cache.servers.map((s) => `${s.name}(${s.tool_count})`).join(pick('、', ', '));
+  return pick(
+    `MCP：${usable.length} 个工具 · ${names}${cache.mode ? ` · 模式 ${cache.mode}` : ''}`,
+    `MCP: ${usable.length} tools · ${names}${cache.mode ? ` · mode ${cache.mode}` : ''}`,
+  );
 }
 
 /**

package/lib/mcpadmin.js

@@ -0,0 +1,331 @@
+/**
+ * MCP 管理面（客户端自助）：挑服务器、改绑定、登记/删除自己的 MCP 服务器
+ *
+ * 与 `lib/mcp.js` 的分工（两者都打网关的 `/v1/mcp/*`，但性质完全不同）：
+ *  · `lib/mcp.js`  —— **运行面**：拉工具清单（同步读缓存、TTL、失败静默降级）。
+ *     它是会话路径上的一环，绝不能因为 MCP 把一次正常对话搞挂。
+ *  · 本模块        —— **管理面**：`GET/PATCH /v1/mcp/binding`、`POST/DELETE /v1/mcp/servers`。
+ *     它是用户**显式**敲的 `/mcp bind|mode|add|rm`，所以性质相反：**失败必须说出来**。
+ *     用户点了「加」，就必须看到「加上了没有、为什么没加上」——静默在这里是缺陷不是稳健。
+ *
+ * 网关侧接口（`proxy/app/mcp_api.py`）：`GET /v1/mcp/binding` 回 `bound`（已绑）/`addable`
+ * （可自助加）/`mine`（自建）/`selectable_ids`（可选全集）/`self_server{allowed,max,used}`；
+ * `PATCH` 在自己可选的范围内改绑与模式；`POST /v1/mcp/servers` 登记 http 服务器并就地探测一次；
+ * `DELETE /v1/mcp/servers/{id}` 只能删自己登记的。
+ *
+ * **「能不能自助登记」的判据只在网关**（`self_server.allowed`）。CLI 不猜、不用默认值兜：
+ * 猜错的两种表现（显示了入口却一点就 403 / 明明开了却不给用）都只能靠读网关代码才能查。
+ *
+ * 凭据纪律（本模块最重要的一件事）：登记 URL 的查询参数（`?key=` / `?ak=`）与 `--header`
+ * 的值就是凭据。它们**必须**真发给网关（网关拿它去连第三方），但**绝不允许**进任何输出——
+ * 包括 `GATEWAY_MCP_DEBUG=1` 的排障行，以及网关自己回显在错误 `detail` 里的那份 URL。
+ * 所以掩码只有一处实现（本文件的 `maskUrl` / `maskSecrets`），所有打印与错误回显都过它。
+ */
+import { pick } from './i18n.js';
+
+/** 网关地址与密钥（由 `lib/mcp.js` 的 configureMcp 同步过来，避免两套连接状态互相打架） */
+let conn = { baseUrl: '', key: '', fetchImpl: null };
+
+/** 提交（登记/改绑/删除）的超时。比清单的 4s 宽一点：登记会**就地探测一次**第三方 */
+const ADMIN_TIMEOUT_MS = 15000;
+
+export function configureMcpAdmin({ baseUrl, key, fetchImpl } = {}) {
+  conn = {
+    baseUrl: String(baseUrl || '').trim().replace(/\/+$/, ''),
+    key: String(key || '').trim(),
+    fetchImpl: fetchImpl || conn.fetchImpl,
+  };
+  return conn;
+}
+
+/** 复位（测试与「换会话」用）：与 `resetMcpTools()` 一起被调用 */
+export function resetMcpAdmin() {
+  conn = { baseUrl: '', key: '', fetchImpl: null };
+}
+
+export const mcpAdminBase = () => ({ baseUrl: conn.baseUrl, key: conn.key });
+
+/** 排障开关：与 lib/mcp.js 同一口径（不设变量零输出）。**输出一律过掩码。** */
+const debugOn = () => Boolean(process.env.GATEWAY_MCP_DEBUG);
+function debug(...parts) {
+  if (debugOn()) console.error('[mcp-admin]', ...parts.map((p) => maskSecrets(p)));
+}
+
+const pickFetch = () => (typeof conn.fetchImpl === 'function' ? conn.fetchImpl : globalThis.fetch);
+
+function timeoutSignal() {
+  return typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+    ? AbortSignal.timeout(ADMIN_TIMEOUT_MS)
+    : undefined;
+}
+
+/* ============================ 掩码（唯一实现） ============================ */
+
+/** 查询参数里哪些名字算凭据。宁可多掩几个，也不能漏 —— 漏一个就是明文进终端/日志。 */
+const SECRET_PARAMS = [
+  'key', 'apikey', 'api_key', 'ak', 'sk', 'token', 'access_token', 'auth', 'authorization',
+  'password', 'passwd', 'pwd', 'secret', 'client_secret', 'sign', 'signature', 'sig',
+];
+
+/**
+ * 把 URL 里的凭据掩掉：`https://h/p?key=abc&x=1` → `https://h/p?key=***&x=1`。
+ *
+ * 策略是「按名字掩值」，不按值掩：值可能很短（`?key=a`），按值掩会把 URL 里的普通字符
+ * 一起换掉，读起来更糟。认不出的参数名**保留原值**（否则掩码会把一个正常的查询串变得没法看），
+ * 所以带凭据的地址请不要用自定义参数名——这条写进 README。
+ */
+export function maskUrl(url) {
+  const raw = String(url == null ? '' : url);
+  if (!raw) return '';
+  try {
+    // URL 规范化（会带上末尾 `/`），只为拿到 host/path/search；拼不回原样就退回纯文本替换
+    const u = new URL(raw);
+    const params = [...u.searchParams.keys()];
+    if (!params.length) return u.origin + u.pathname;
+    const q = params
+      .map((k) => `${encodeURIComponent(k)}=${SECRET_PARAMS.includes(k.toLowerCase()) ? '***' : (u.searchParams.get(k) ?? '')}`)
+      .join('&');
+    return `${u.origin}${u.pathname}?${q}${u.hash || ''}`;
+  } catch {
+    // 不是合法 URL（用户少打了协议）：把 `名字=值` 里可疑名字的值手动换掉
+    return raw.replace(/([?&])([A-Za-z0-9_.\-]+)=([^&\s]*)/g,
+      (m, sep, name, value) => (SECRET_PARAMS.includes(String(name).toLowerCase()) ? `${sep}${name}=***` : `${sep}${name}=${value}`));
+  }
+}
+
+/**
+ * 把任意一段文本里**所有** URL 的凭据掩掉（含网关错误 `detail` 里回显的那份地址）。
+ * 这是「回显前先过掩码」这条纪律的实现点：自己打印的、网关回的，都走这里。
+ */
+export function maskSecrets(text) {
+  const s = String(text == null ? '' : text);
+  if (!s) return '';
+  return s.replace(/https?:\/\/[^\s"'<>）)，,；;]+/g, (m) => maskUrl(m));
+}
+
+/** 请求头：值一律掩掉（头就是用来放鉴权的），名字保留 —— 名字是给人看的排障信息 */
+export function maskHeaders(headers) {
+  const out = {};
+  Object.keys(headers || {}).forEach((k) => { out[k] = '***'; });
+  return out;
+}
+
+/** 一行可读的 headers 摘要（掩码后） */
+const headerBrief = (headers) => Object.keys(headers || {}).join(', ');
+
+/* ============================ 调用骨架 ============================ */
+
+/**
+ * 统一出口：**显式失败**（永不静默）。
+ *
+ * 失败对象形状 `{ ok:false, code, message, hint }`：
+ *  · `message` —— 网关的 `detail` 原文或本地判定的原因（**已过掩码**）；
+ *  · `hint`    —— 能照着修的一句话（网关没重启 / 没开自助 / 版本较旧）。
+ *
+ * 为什么把 hint 放在这里而不是调用方：同一个失败现象（404/502）有不止一个原因，
+ * 而每一个原因的下一步都不同；散在各子命令里写，迟早会漏掉某一处。
+ */
+function failMessage(resp, body) {
+  const detail = body && typeof body.detail === 'string' ? body.detail : '';
+  return maskSecrets(detail || `HTTP ${resp.status}`);
+}
+
+function hintFor(status, msg) {
+  if (status === 404 || status === 502) {
+    return '网关可能没重启或版本较旧（这几个接口是新增的；重启网关后再试一次）';
+  }
+  if (status === 401) return '网关不认这把密钥（检查 /config 里的网关地址与密钥）';
+  if (status === 403) return '这一档在网关侧没开放：需要部署方在 .env 设 MCP_ALLOW_SELF_SERVERS=true 后重启网关';
+  if (status === 0) return '网关不可达（地址填错 / 网关没起 / 网络不通）';
+  if (/上限/.test(msg)) return '自助登记有台数上限：先删掉不用的（/mcp rm），或让管理员登记';
+  if (/已存在/.test(msg)) return '换一个服务器名：名字全局唯一，用于绑定与识别';
+  if (/本机|内网|回环|私网/.test(msg)) return '自助登记只接受公网可达的 http/https 地址；内网 MCP 请让管理员登记';
+  return '';
+}
+
+async function req(method, path, body) {
+  if (!conn.baseUrl || !conn.key) {
+    return { ok: false, code: 0, message: '未配置网关地址或密钥', hint: '先跑 gateway-agent setup（或 /config set key sk-xxx）', data: null };
+  }
+  const f = pickFetch();
+  if (typeof f !== 'function') {
+    return { ok: false, code: 0, message: '当前 Node 没有 fetch（需要 Node 18+）', hint: '', data: null };
+  }
+  debug(method, conn.baseUrl + path, body ? JSON.stringify(payloadBrief(body)) : '');
+  let resp;
+  try {
+    resp = await f(`${conn.baseUrl}${path}`, {
+      method,
+      headers: { authorization: `Bearer ${conn.key}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      signal: timeoutSignal(),
+    });
+  } catch (e) {
+    const msg = maskSecrets(e?.message || String(e));
+    debug('→ 失败：' + msg);
+    return { ok: false, code: 0, message: msg, hint: hintFor(0, msg), data: null };
+  }
+  let data = null;
+  try {
+    data = await resp.json();
+  } catch {
+    /* 非 JSON 响应体：状态码与 hint 已经够定位（网关旧版的 502 就走这里） */
+  }
+  if (!resp.ok) {
+    const message = failMessage(resp, data);
+    debug('→ HTTP ' + resp.status + ' ' + message);
+    return { ok: false, code: resp.status, message, hint: hintFor(resp.status, message), data };
+  }
+  debug('→ HTTP ' + resp.status);
+  return { ok: true, code: resp.status, message: '', hint: '', data: data || {} };
+}
+
+/** debug 行里也不许出现明文凭据：登记用的 URL 与 headers 先掩掉再打 */
+function payloadBrief(body) {
+  const b = { ...(body || {}) };
+  if (typeof b.url === 'string') b.url = maskUrl(b.url);
+  if (b.headers) b.headers = maskHeaders(b.headers);
+  return b;
+}
+
+/* ============================ 四个接口 ============================ */
+
+/**
+ * `GET /v1/mcp/binding` —— 我这把密钥绑了什么、还能自己加哪些、我自建了哪些。
+ * 客户端据此决定**要不要显示**「登记自己的 MCP」入口（`self_server.allowed`）。
+ */
+export async function getMcpBinding() {
+  const r = await req('GET', '/v1/mcp/binding');
+  if (!r.ok) return r;
+  const d = r.data || {};
+  return {
+    ok: true,
+    bound: Array.isArray(d.bound) ? d.bound : [],
+    addable: Array.isArray(d.addable) ? d.addable : [],
+    mine: Array.isArray(d.mine) ? d.mine : [],
+    selectableIds: Array.isArray(d.selectable_ids) ? d.selectable_ids.map(Number) : [],
+    mode: String(d.mode || ''),
+    enabled: d.enabled !== false,
+    selfServer: {
+      allowed: Boolean(d.self_server && d.self_server.allowed),
+      max: Number(d.self_server?.max || 0),
+      used: Number(d.self_server?.used || 0),
+      note: String(d.self_server?.note || ''),
+    },
+    note: String(d.note || ''),
+  };
+}
+
+/**
+ * `PATCH /v1/mcp/binding` —— 改绑与/或改模式。
+ *
+ * **只改模式时绝不下发 `server_ids`**：网关那边「不传 server_ids」与「传 []」是两件事
+ * （前者保留绑定、后者解绑）。传一个空的过去，用户的绑定就被静默清空了。
+ */
+export async function patchMcpBinding({ serverIds, mode } = {}) {
+  const body = {};
+  if (Array.isArray(serverIds)) body.server_ids = serverIds.map(Number);
+  if (mode) body.mode = String(mode);
+  if (!Object.keys(body).length) {
+    return { ok: false, code: 0, message: '没有要改的内容', hint: '', data: null };
+  }
+  return req('PATCH', '/v1/mcp/binding', body);
+}
+
+/**
+ * `POST /v1/mcp/servers` —— 自助登记一台 HTTP MCP 服务器（BYO-A）。
+ *
+ * `url` 原样发给网关（凭据就在查询参数里，改写它等于把凭据弄坏）；`headers` 只在网关侧保存。
+ * 网关会**就地探测一次**：探测失败不删行、建成即置停用，并把原因放在 `probe_error` 里——
+ * 那不是「登记失败」，是「登记上了但连不通」，两种结局必须分开告诉用户。
+ */
+export async function createMcpServer({ name, url, headers } = {}) {
+  const body = { name: String(name || '').trim(), url: String(url || '').trim(), transport: 'http' };
+  if (headers && Object.keys(headers).length) body.headers = { ...headers };
+  if (!body.name) return { ok: false, code: 0, message: '服务器名不能为空', hint: '用法：/mcp add <名字> <URL>', data: null };
+  if (!/^https?:\/\//i.test(body.url)) {
+    return { ok: false, code: 0, message: 'URL 必须是 http:// 或 https:// 开头', hint: '例：/mcp add demo https://mcp.example.com/mcp', data: null };
+  }
+  const r = await req('POST', '/v1/mcp/servers', body);
+  if (!r.ok) return r;
+  const d = r.data || {};
+  debug('登记成功：' + (d.server?.name || body.name) + ' 工具 ' + Number(d.server?.tool_count || 0)
+    + (d.probe_error ? ' 探测失败' : ''));
+  return {
+    ok: true,
+    server: d.server || { id: 0, name: body.name, enabled: !d.probe_error, tool_count: 0 },
+    probeError: maskSecrets(String(d.probe_error || '')),
+    note: String(d.note || ''),
+  };
+}
+
+/** `DELETE /v1/mcp/servers/{id}` —— 只能删**自己登记**的；删别人的/管理员建的一律 404 */
+export async function deleteMcpServer(id) {
+  const n = Number(id);
+  if (!Number.isFinite(n) || n <= 0) {
+    return { ok: false, code: 0, message: `服务器 id 不合法：${id}`, hint: '用 /mcp 看自己登记的 id', data: null };
+  }
+  const r = await req('DELETE', `/v1/mcp/servers/${n}`);
+  if (!r.ok) return r;
+  return { ok: true, message: String(r.data?.message || `已删除自建服务器 #${n}`), note: String(r.data?.note || '') };
+}
+
+/* ============================ 给命令层用的小工具 ============================ */
+
+/**
+ * URL 是否**含有凭据**（查询参数里出现了 SECRET_PARAMS 里的名字）。
+ * 命令层用它决定要不要多打一句提醒（「这个地址带 key，CLI 只显示掩码，明文存在网关侧」）。
+ */
+export function urlHasCredential(url) {
+  try {
+    const u = new URL(String(url || ''));
+    return [...u.searchParams.keys()].some((k) => SECRET_PARAMS.includes(k.toLowerCase()));
+  } catch {
+    return /[?&](key|ak|sk|token|secret|auth|password)=/i.test(String(url || ''));
+  }
+}
+
+/** 把 `--header "k: v"` 参数解析成对象；非法的一律**报错返回**，不静默丢弃 */
+export function parseHeaderArgs(argv = []) {
+  const out = {};
+  const bad = [];
+  const list = Array.isArray(argv) ? argv : [];
+  for (let i = 0; i < list.length; i++) {
+    let raw = String(list[i] || '');
+    if (raw === '--header' || raw === '-H') raw = String(list[++i] || '');
+    else if (/^--header=/i.test(raw)) raw = raw.slice('--header='.length);
+    else continue;
+    const idx = raw.indexOf(':');
+    const k = idx < 0 ? '' : raw.slice(0, idx).trim();
+    const v = idx < 0 ? '' : raw.slice(idx + 1).trim();
+    if (!k || !v) { bad.push(raw); continue; }
+    out[k] = v;
+  }
+  return { headers: out, bad };
+}
+
+/** 子命令清单（帮助与分派共用一份，避免「帮助里写了、分派里没有」） */
+export const MCP_SUBCOMMANDS = ['refresh', 'bind', 'mode', 'add', 'rm'];
+
+/** 状态一行（`/mcp` 总览用）：自助登记这一档开没开、用了几台 */
+export function selfServerText(binding) {
+  const s = binding?.selfServer || {};
+  if (!s.allowed) {
+    return pick('自助登记：未开放（需部署方在 .env 设 MCP_ALLOW_SELF_SERVERS=true 后重启网关）',
+      'Self-registration: closed (the operator must set MCP_ALLOW_SELF_SERVERS=true in .env and restart the gateway)');
+  }
+  return pick(`自助登记：开放（${s.used}/${s.max} 台）`, `Self-registration: open (${s.used}/${s.max})`);
+}
+
+/** 服务器简表一行：`#3 名字（3 个工具，停用）` */
+export function serverLine(s) {
+  const bits = [];
+  if (Number.isFinite(Number(s?.tool_count))) bits.push(pick(`${Number(s.tool_count)} 个工具`, `${Number(s.tool_count)} tools`));
+  if (s && s.enabled === false) bits.push(pick('已停用', 'disabled'));
+  if (s && s.owner === 'self') bits.push(pick('自建', 'self-registered'));
+  else if (s && s.self_service) bits.push(pick('可自助', 'self-service'));
+  return `#${s?.id} ${s?.name || ''}${bits.length ? `（${bits.join('，')}）` : ''}`;
+}
+
+/** 供测试与排障：登记带的 headers 会出现在哪些输出里（一律掩码） */
+export const __internals = { maskHeaders, headerBrief, payloadBrief };