llm-api-gateway-cli 1.0.5 → 1.0.6

package/lib/commands.js

@@ -22,8 +22,17 @@
 
 import { formatCost } from './pricing.js';
 import { configCommand, splitConfigArg } from './configcmd.js';
-// /mcp：本密钥可用的 MCP 工具清单来自网关（GET /v1/mcp/tools），本文件只负责把它打印给人看
+// /mcp：清单来自网关 GET /v1/mcp/tools；绑定与自助登记走管理面（同一条命令，见 mcpCommand）
 import { refreshMcpTools, mcpStatusText, mcpToolList } from './mcp.js';
+import {
+  getMcpBinding, patchMcpBinding, createMcpServer, deleteMcpServer,
+  parseHeaderArgs, urlHasCredential, maskUrl, serverLine, selfServerText, MCP_SUBCOMMANDS,
+  configureMcpAdmin,
+} from './mcpadmin.js';
+// CLI 侧语言：表里每条命令带一份 `en` 元数据，`/help` 的正文按当前语言取。
+// 注意 commandRows() / helpText() 的**默认语言是 zh**（不是 getLang()）—— 网关进程用它生成
+// `/api/commands` 喂给中文手册页，绝不能被 `node server.js --lang en` 带跑偏。
+import { pick, getLang } from './i18n.js';
 
 /** 压缩上下文时保留最近几条消息（不含 system） */
 const COMPACT_KEEP = 6;
@@ -46,7 +55,7 @@ export function tokenize(s) {
     if (i >= raw.length) break;
     if (raw[i] === '"') {
       const end = raw.indexOf('"', i + 1);
-      if (end < 0) throw new Error('引号没有闭合（用 " 包住带空格的参数）');
+      if (end < 0) throw new Error(pick('引号没有闭合（用 " 包住带空格的参数）', 'unclosed quote (wrap arguments containing spaces in ")'));
       out.push(raw.slice(i + 1, end));
       i = end + 1;
     } else {
@@ -209,7 +218,8 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/help [命令名]',
     desc: '显示命令列表，或查看某条命令的用法',
-    run: (ctx, arg) => ctx.say(helpText(arg)),
+    en: { args: '[command]', group: 'Help', usage: '/help [command]', desc: 'List commands, or show the usage of one command' },
+    run: (ctx, arg) => ctx.say(helpText(arg, getLang())),
   },
   '/model': {
     name: 'model',
@@ -221,11 +231,14 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/model [模型名]',
     desc: '查看或切换当前模型（保留上下文）',
+    en: { args: '[model]', group: 'Model & request', usage: '/model [model]', desc: 'Show or switch the current model (context is kept)' },
     run: (ctx, arg) => {
-      if (!arg) return ctx.say(`当前模型：${ctx.session.model}（用法：/model <模型名>）`);
+      if (!arg) {
+        return ctx.say(pick(`当前模型：${ctx.session.model}（用法：/model <模型名>）`, `Current model: ${ctx.session.model} (usage: /model <model>)`));
+      }
       ctx.setModel(arg);
       ctx.persist();
-      ctx.say(`模型已切换为 ${arg}（上下文保留，下一步生效）。`);
+      ctx.say(pick(`模型已切换为 ${arg}（上下文保留，下一步生效）。`, `Model switched to ${arg} (context kept, effective from the next turn).`));
     },
   },
   '/config': {
@@ -238,12 +251,13 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/config [list|get|set|unset …]',
     desc: '查看或修改持久化配置（与 gateway-agent config 同一套）',
+    en: { group: 'Config', desc: 'View or change persisted settings (same as 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 || '（没有输出）');
+      ctx.say(text || pick('（没有输出）', '(no output)'));
     },
   },
   '/cost': {
@@ -256,53 +270,32 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/cost',
     desc: '查看本会话累计 token 与费用粗估（口径：内置单价表）',
+    en: { group: 'Usage & cost', desc: 'Show cumulative tokens and a rough cost estimate for this session (built-in price table)' },
     run: (ctx) => {
       ctx.say(formatCost(ctx.session.usage, ctx.session.model));
       // 自报口径：网关是记账方，内置表只是本机估算。两端口径必须能被一眼区分，
       // 否则同一台机器上 /cost 与网关账单会"各自说各自的数"（对齐方案 §3.2）。
-      ctx.say('口径：内置单价表估算，非网关计费口径（网关 /admin/prices 才是记账口径）。');
+      ctx.say(pick('口径：内置单价表估算，非网关计费口径（网关 /admin/prices 才是记账口径）。', 'Note: estimated from the built-in price table, not the gateway billing figure (the gateway /admin/prices is authoritative).'));
     },
   },
   '/mcp': {
     name: 'mcp',
     aliases: [],
-    args: '[refresh]',
+    args: '[refresh|bind|mode|add|rm]',
     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 可立即重拉');
-      }
+    usage: '/mcp [refresh|bind|mode|add|rm]',
+    desc: 'MCP：看清单与绑定；bind 改绑、mode 选模式、add 登记自己的服务器、rm 删掉',
+    en: {
+      args: '[refresh|bind|mode|add|rm]',
+      group: 'Tools & MCP',
+      usage: '/mcp [refresh|bind|mode|add|rm]',
+      desc: 'MCP: list tools and bindings; bind/mode change them, add registers your own server, rm removes one',
     },
+    // 异步：除了总览，其余子命令都要真的出网（REPL 循环对 run 的返回值已经 await）
+    run: (ctx, arg) => mcpCommand(ctx, arg),
   },
   '/reset': {
     name: 'reset',
@@ -314,10 +307,11 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/reset',
     desc: '重开会话（清空上下文，工作目录不变）',
+    en: { group: 'Session & context', desc: 'Restart the session (context cleared, working directory unchanged)' },
     run: (ctx) => {
       ctx.setSession(ctx.newSession());
       ctx.persist();
-      ctx.say('已重开会话（上下文清空，工作目录不变）。');
+      ctx.say(pick('已重开会话（上下文清空，工作目录不变）。', 'Session restarted (context cleared, working directory unchanged).'));
     },
   },
   '/clear': {
@@ -330,6 +324,7 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/clear',
     desc: '/reset 的别名（清空上下文重开）',
+    en: { group: 'Session & context', desc: 'alias of /reset (clear the context and start over)' },
     run: (ctx, arg, argv) => COMMANDS['/reset'].run(ctx, arg, argv),
   },
   '/resume': {
@@ -342,18 +337,22 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/resume <会话id>',
     desc: '切到另一个已保存的会话（不带参数列出最近会话）',
+    en: { args: '<session-id>', group: 'Session & context', usage: '/resume <session-id>', desc: 'Switch to another saved session (without arguments, list recent sessions)' },
     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> 恢复其中一个。`);
+        if (!list.length) return ctx.say(pick('没有已保存的会话。（用 /resume <id> 恢复；会话目录见启动横幅）', 'No saved sessions. (Use /resume <id> to resume; the session directory is shown in the startup banner.)'));
+        const lines = list.slice(0, 10).map((s) => pick(
+          `  ${s.id}  ${s.model || '?'}  ${s.messages || 0} 条  ${new Date(s.touchedAt).toLocaleString()}`,
+          `  ${s.id}  ${s.model || '?'}  ${s.messages || 0} msgs  ${new Date(s.touchedAt).toLocaleString()}`,
+        ));
+        return ctx.say(pick(`最近的会话：\n${lines.join('\n')}\n用 /resume <id> 恢复其中一个。`, `Recent sessions:\n${lines.join('\n')}\nResume one with /resume <id>.`));
       }
       const rec = ctx.loadSession ? ctx.loadSession(arg) : null;
-      if (!rec) return ctx.say(`找不到会话 ${arg}（id 是 UUID；可用 /resume 不带参数列出）。`);
+      if (!rec) return ctx.say(pick(`找不到会话 ${arg}（id 是 UUID；可用 /resume 不带参数列出）。`, `Session ${arg} not found (the id is a UUID; run /resume without arguments to list them).`));
       ctx.setSession(rec);
       ctx.persist();
-      ctx.say(`已切换到会话 ${rec.id}（${rec.model || '?'}，工作目录 ${rec.workingDir || '?'}）。`);
+      ctx.say(pick(`已切换到会话 ${rec.id}（${rec.model || '?'}，工作目录 ${rec.workingDir || '?'}）。`, `Switched to session ${rec.id} (${rec.model || '?'}, working directory ${rec.workingDir || '?'}).`));
     },
   },
   '/compact': {
@@ -366,18 +365,20 @@ export const COMMANDS = {
     surfaces: ['cli'],
     usage: '/compact',
     desc: `压缩上下文：只保留最近 ${COMPACT_KEEP} 条消息（本地操作，不调用模型）`,
+    en: { group: 'Session & context', desc: `Compact the context: keep only the most recent ${COMPACT_KEEP} messages (local, no model call)` },
     run: (ctx) => {
       const msgs = ctx.session.messages;
-      if (!Array.isArray(msgs) || msgs.length <= COMPACT_KEEP + 1) return ctx.say('上下文不长，无需压缩。');
+      if (!Array.isArray(msgs) || msgs.length <= COMPACT_KEEP + 1) return ctx.say(pick('上下文不长，无需压缩。', 'The context is short; nothing to compact.'));
       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} 条。`);
+      ctx.say(pick(`已压缩上下文：丢弃 ${dropped} 条较早消息，保留最近 ${COMPACT_KEEP} 条。`, `Context compacted: dropped ${dropped} earlier messages, kept the most recent ${COMPACT_KEEP}.`));
     },
   },
   '/exit': {
@@ -391,24 +392,318 @@ export const COMMANDS = {
     bare: true,                    // 裸词 exit / quit 也认（原来硬编码在 cli-agent 的循环里）
     usage: '/exit',
     desc: '退出（裸词 exit / quit 同样有效）',
+    en: { group: 'Process', desc: 'Quit (the bare words exit / quit work too)' },
     run: () => ({ exit: true }),
   },
 };
 
+/* ============================ /mcp（清单 + 绑定 + 自助登记） ============================ */
+
+/**
+ * `/mcp` 的分派。
+ *
+ * 分成两类，纪律完全不同：
+ *  · **清单**（无参数 / `refresh`）走 `lib/mcp.js`：best-effort、失败静默降级，
+ *    因为它也在对话开场路径上，绝不能把一次正常对话搞挂。
+ *  · **管理**（`bind` / `mode` / `add` / `rm`）走 `lib/mcpadmin.js`：**显式失败**。
+ *    用户敲了「加」，就必须看到成没成；在这里静默是缺陷不是稳健。
+ *
+ * 「能不能自助登记」的判据一律来自网关（`self_server.allowed`），CLI 不猜默认值——
+ * 猜错的表现是「显示了入口、一点就 403」或者「明明开了却不给用」。
+ */
+async function mcpCommand(ctx, arg) {
+  const cfg = ctx.cfg || {};
+  // 管理面（lib/mcpadmin.js）用的是**自己的**连接状态，正常由 refreshMcpTools → configureMcp 顺带同步。
+  // 但命令层手里直接就有 cfg，这里显式同步一次，免得两条路各说各话：
+  //  · 宿主没先刷过清单（或刷完又 /config set key / set baseUrl）时，绑定信息会用空/旧的地址与密钥，
+  //    表现是「工具清单是新的，绑定信息却是旧的，甚至误报『未配置网关地址或密钥』」（实测踩到）。
+  if (cfg.baseUrl || cfg.key) configureMcpAdmin({ baseUrl: cfg.baseUrl, key: cfg.key });
+  const argv = tokenize(String(arg || ''));
+  const head = String(argv[0] || '').toLowerCase();
+  if (!head || head === 'help' || head === '?') return mcpOverview(ctx, cfg);
+  if (head === 'refresh') return mcpRefresh(ctx, cfg, true);
+  // 认不出的**第一个词**按子命令处理并给出正确提示；认不出的后续参数交给各子命令自己报错
+  if (MCP_SUBCOMMANDS.includes(head)) {
+    if (head === 'bind') return mcpBind(ctx, cfg, argv.slice(1));
+    if (head === 'mode') return mcpMode(ctx, cfg, argv.slice(1));
+    if (head === 'add') return mcpAdd(ctx, cfg, argv.slice(1));
+    if (head === 'rm') return mcpRemove(ctx, cfg, argv.slice(1));
+  }
+  if (/^[+-=]?\d/.test(head)) {
+    ctx.say(pick(`  · 不认识的参数：${head}　要改绑定请写 /mcp bind ${head}`,
+      `  · unknown argument: ${head} — to change bindings write /mcp bind ${head}`));
+  }
+  return mcpOverview(ctx, cfg);
+}
+
+/** 总览：本密钥绑了什么 / 可自助加什么 / 我自建了什么 + 工具清单（**不含地址与凭据**） */
+async function mcpOverview(ctx, cfg) {
+  const b = await getMcpBinding();
+  if (b.ok) {
+    ctx.say(pick(`绑定模式：${b.mode || '未报'}　总开关：${b.enabled ? '开' : '关'}`,
+      `Binding mode: ${b.mode || 'n/a'}  master switch: ${b.enabled ? 'on' : 'off'}`));
+    const row = (label, list, empty) => {
+      ctx.say(pick(`${label}（${list.length}）`, `${label} (${list.length})`));
+      if (!list.length) { ctx.say(`  ${empty}`); return; }
+      list.forEach((s) => ctx.say(`  ${serverLine(s)}`));
+    };
+    row(pick('已绑定', 'Bound'), b.bound, pick('（没有：/mcp bind +<id> 加上一台）', '(none: /mcp bind +<id> to add one)'));
+    row(pick('可自助加', 'Addable'), b.addable, pick('（没有：管理员没把服务器标成可自助）', '(none: no server is marked self-service)'));
+    row(pick('我自建的', 'Registered by me'), b.mine, pick('（没有）', '(none)'));
+    ctx.say('  ' + selfServerText(b));
+    if (b.selfServer.allowed) {
+      ctx.say(pick('  · 登记自己的：/mcp add <名字> <URL>　删掉：/mcp rm <名字|id>',
+        '  · register your own: /mcp add <name> <URL>   remove: /mcp rm <name|id>'));
+      ctx.say(pick('  · 只支持 http/https 且必须是公网可达地址（指向本机/内网的会被网关拒绝）',
+        '  · only public http/https addresses (loopback/private ones are rejected by the gateway)'));
+    }
+  } else {
+    // 管理面失败**不**连累清单：清单走的是另一条 best-effort 路径，网关老版本没有这个接口时
+    // 也照样能看工具。所以这里只把原因说清，然后继续拉清单。
+    ctx.say(pick(`绑定信息不可用：${b.message}`, `binding info unavailable: ${b.message}`));
+    if (b.hint) ctx.say(`  · ${b.hint}`);
+  }
+  return mcpRefresh(ctx, cfg, false);
+}
+
+/** 拉清单并打印（refresh 立即重拉，否则按 TTL）。失败文案要能区分「没发请求」与「发了失败」 */
+async function mcpRefresh(ctx, cfg, force) {
+  // 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
+      ? pick(
+          `  · 已请求 GET ${cfg.baseUrl || '?'}/v1/mcp/tools（${force ? '强制刷新' : '按需'}）：${info.error}`,
+          `  · requested GET ${cfg.baseUrl || '?'}/v1/mcp/tools (${force ? 'forced refresh' : 'on demand'}): ${info.error}`,
+        )
+      : pick(`  · 未向网关发出请求：${info.error}`, `  · no request sent to the gateway: ${info.error}`));
+    // GATEWAY_MCP=off 是用户自己关的，再让他去查网关就是误导
+    if (!/GATEWAY_MCP=off/.test(info.error)) {
+      ctx.say(pick('  · 常见原因：网关未开启 MCP / 该密钥未绑定任何工具 / 网关版本不带这个接口', '  · usual causes: MCP is off on the gateway / this key has no tools bound / the gateway version lacks this endpoint'));
+      ctx.say(pick('  · 看细节：GATEWAY_MCP_DEBUG=1 重跑，每次拉取与调用都会打到 stderr', '  · for details: rerun with GATEWAY_MCP_DEBUG=1; every fetch and call is traced to stderr'));
+    }
+  } else if (force) {
+    ctx.say(pick('  · 已强制重拉（后续对话立即用这份新清单）', '  · force-refreshed (later turns use this new list immediately)'));
+  } else {
+    ctx.say(pick('  · 清单来自网关 GET /v1/mcp/tools（60 秒 TTL）；/mcp refresh 可立即重拉', '  · list comes from the gateway GET /v1/mcp/tools (60s TTL); /mcp refresh re-fetches now'));
+  }
+  ctx.say(pick(`  · 改绑：/mcp bind +<id> -<id> 或 =<id,...>　改模式：/mcp mode off|inject|loop　看全部：/help mcp`,
+    `  · bindings: /mcp bind +<id> -<id> or =<id,...>  mode: /mcp mode off|inject|loop  all: /help mcp`));
+}
+
+/** `/mcp bind +3 -5` 或 `/mcp bind =2,7`：在我可选的范围内改绑 */
+async function mcpBind(ctx, cfg, argv) {
+  const b = await getMcpBinding();
+  if (!b.ok) return mcpAdminFailed(ctx, b, pick('改绑未执行', 'binding not changed'));
+  if (!argv.length) {
+    ctx.say(pick('用法：/mcp bind +<id> -<id>（加减）或 /mcp bind =<id,...>（整份设定）',
+      'usage: /mcp bind +<id> -<id> (add/remove) or /mcp bind =<id,...> (set all)'));
+    ctx.say(pick(`  当前绑定：${b.bound.length ? b.bound.map((s) => `#${s.id}`).join(' ') : '（空）'}`,
+      `  current: ${b.bound.length ? b.bound.map((s) => `#${s.id}`).join(' ') : '(empty)'}`));
+    ctx.say(pick(`  可选 id：${b.selectableIds.join(' ') || '（无）'}`, `  selectable ids: ${b.selectableIds.join(' ') || '(none)'}`));
+    return;
+  }
+  let want;
+  const setAll = argv.find((a) => String(a).startsWith('='));
+  if (setAll) {
+    want = String(setAll).slice(1).split(',').map((s) => Number(String(s).trim())).filter((n) => Number.isFinite(n));
+  } else {
+    // 不认识的记号（例如 `3` 少打了 +）必须报错：静默忽略会让用户以为「加上了」
+    const unknown = argv.filter((a) => !/^[+-]\d+$/.test(String(a)));
+    if (unknown.length) {
+      ctx.say(pick(`参数要写成 +id / -id（缺了 +/- 的：${unknown.join(' ')}）`,
+        `arguments must be +id / -id (missing +/-, got: ${unknown.join(' ')})`));
+      ctx.say(pick('  例：/mcp bind +3 -5　或　/mcp bind =2,7', '  e.g. /mcp bind +3 -5  or  /mcp bind =2,7'));
+      return;
+    }
+    const cur = b.bound.map((s) => Number(s.id));
+    const out = cur.slice();
+    argv.forEach((a) => {
+      const s = String(a);
+      const id = Number(s.slice(1));
+      if (s[0] === '+') { if (!out.includes(id)) out.push(id); }
+      else { const i = out.indexOf(id); if (i >= 0) out.splice(i, 1); }
+    });
+    want = out;
+  }
+  // 越权/不存在的 id 本地先拦：网关也会整单拒绝（并点名），但白跑一趟没必要
+  const bad = want.filter((id) => !b.selectableIds.includes(id));
+  if (bad.length) {
+    ctx.say(pick(`这几个不在你可选的范围内：${bad.join(' ')}`, `not in your selectable range: ${bad.join(' ')}`));
+    ctx.say(pick(`  可选 id：${b.selectableIds.join(' ') || '（无）'}　可自助加的：${b.addable.map((s) => `#${s.id} ${s.name}`).join('，') || '（无）'}`,
+      `  selectable ids: ${b.selectableIds.join(' ') || '(none)'}  addable: ${b.addable.map((s) => `#${s.id} ${s.name}`).join(', ') || '(none)'}`));
+    ctx.say(pick('  想从零加一台新的：/mcp add <名字> <URL>（或让管理员把它标成可自助）',
+      '  to add a brand-new one: /mcp add <name> <URL> (or ask an admin to mark it self-service)'));
+    return;
+  }
+  const r = await patchMcpBinding({ serverIds: want });
+  if (!r.ok) return mcpAdminFailed(ctx, r, pick('改绑未生效', 'binding not changed'));
+  const now = Array.isArray(r.data?.bound) ? r.data.bound : [];
+  ctx.say(pick(`已改绑：现在 ${now.length} 台${now.length ? `（${now.map((s) => `#${s.id} ${s.name}`).join('，')}）` : ''}`,
+    `bindings updated: ${now.length} server(s)${now.length ? ` (${now.map((s) => `#${s.id} ${s.name}`).join(', ')})` : ''}`));
+  await mcpRefresh(ctx, cfg, true);
+}
+
+/** `/mcp mode off|inject|loop`：只改模式。**不下发 server_ids**（那会把绑定解掉） */
+async function mcpMode(ctx, cfg, argv) {
+  const m = String(argv[0] || '').toLowerCase();
+  if (!['off', 'inject', 'loop'].includes(m)) {
+    ctx.say(pick('用法：/mcp mode off|inject|loop', 'usage: /mcp mode off|inject|loop'));
+    ctx.say(pick('  off：本密钥不用 MCP（工具仍可列、仍可由 CLI 执行）　inject：只把工具定义注入上游　loop：网关代执行',
+      '  off: this key does not use MCP (tools can still be listed/executed by the CLI)  inject: definitions injected upstream  loop: gateway executes'));
+    return;
+  }
+  const r = await patchMcpBinding({ mode: m });
+  if (!r.ok) return mcpAdminFailed(ctx, r, pick('模式未改', 'mode not changed'));
+  const bound = Array.isArray(r.data?.bound) ? r.data.bound : [];
+  ctx.say(pick(`模式已改为 ${m}（绑定未动：${bound.length} 台）`, `mode set to ${m} (bindings untouched: ${bound.length})`));
+  await mcpRefresh(ctx, cfg, true);
+}
+
+/** `/mcp add <名字> <URL> [--header "k: v"]...`：登记自己的 HTTP MCP 服务器（BYO-A） */
+async function mcpAdd(ctx, cfg, argv) {
+  let name = '';
+  let url = '';
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = String(argv[i]);
+    if (a === '--header' || a === '-H' || /^--header=/i.test(a)) { rest.push(a); continue; }
+    if (!name) name = a;
+    else if (!url) url = a;
+    else rest.push(a);
+  }
+  // 少参数时：**有交互通道就问**，没有就直接说用法（不静默取默认值）
+  const hasAsk = typeof ctx.ask === 'function';
+  if (!name && hasAsk) name = String((await ctx.ask(pick('服务器名（用于绑定与识别，全局唯一）：', 'server name (globally unique, used for binding): '))) || '').trim();
+  if (!url && hasAsk) url = String((await ctx.ask(pick('MCP 地址（http/https 公网可达）：', 'MCP URL (public http/https): '))) || '').trim();
+  if (!name || !url) {
+    ctx.say(pick('用法：/mcp add <名字> <URL> [--header "Authorization: Bearer xxx"]',
+      'usage: /mcp add <name> <URL> [--header "Authorization: Bearer xxx"]'));
+    ctx.say(pick('  · 只支持 http/https，且必须是**公网可达**地址（指向本机/内网的会被网关拒绝）',
+      '  · http/https only, and the address must be publicly reachable (loopback/private ones are rejected)'));
+    ctx.say(pick('  · 凭据可以放在查询参数里（?key=…）；CLI 只显示掩码，明文存在网关侧',
+      '  · credentials may live in the query string (?key=…); the CLI only shows a masked form, the plaintext is kept on the gateway'));
+    return;
+  }
+  const { headers, bad } = parseHeaderArgs(rest);
+  if (bad.length) {
+    ctx.say(pick(`--header 要写成 "名字: 值"（这两条不合法：${bad.join(' | ')}）`,
+      `--header must be "name: value" (invalid: ${bad.join(' | ')})`));
+    return;
+  }
+  // 先读一次绑定：① 判据来自网关（能不能自助登记）② allowed=false 时**不发那次注定 403 的请求**
+  const b = await getMcpBinding();
+  if (b.ok && !b.selfServer.allowed) {
+    ctx.say(pick('网关未开放自助登记：需要部署方在 .env 设 MCP_ALLOW_SELF_SERVERS=true 后**重启网关**（重启才生效）',
+      'the gateway has self-registration closed: the operator must set MCP_ALLOW_SELF_SERVERS=true in .env and restart the gateway'));
+    ctx.say(pick('  · 现在仍可用管理员登记好的、标了「可自助」的服务器：/mcp bind +<id>',
+      '  · you can still bind admin-registered servers marked self-service: /mcp bind +<id>'));
+    return;
+  }
+  if (b.ok && b.selfServer.max && b.selfServer.used >= b.selfServer.max) {
+    ctx.say(pick(`自助登记已满（${b.selfServer.used}/${b.selfServer.max}）：先 /mcp rm 掉不用的`,
+      `self-registration is full (${b.selfServer.used}/${b.selfServer.max}): /mcp rm an unused one first`));
+    return;
+  }
+  // 明文 URL 只在这一行内部存在：发给网关是必须的，打印出来的每一处都过掩码
+  ctx.say(pick(`登记中：${name} ← ${maskUrl(url)}${Object.keys(headers).length ? `（自定义头：${Object.keys(headers).join(', ')}，值不显示）` : ''}`,
+    `registering: ${name} ← ${maskUrl(url)}${Object.keys(headers).length ? ` (headers: ${Object.keys(headers).join(', ')}, values hidden)` : ''}`));
+  if (urlHasCredential(url)) {
+    ctx.say(pick('  · 这个地址带凭据（查询参数）：CLI 只显示掩码，明文保存在网关侧（与管理员登记的服务器同一套机制）',
+      '  · this URL carries credentials in its query string: the CLI only shows a masked form; the plaintext is stored on the gateway'));
+  }
+  const r = await createMcpServer({ name, url, headers });
+  if (!r.ok) return mcpAdminFailed(ctx, r, pick('登记未完成', 'registration failed'));
+  const s = r.server || {};
+  ctx.say(pick(`已登记 #${s.id} ${s.name}（工具 ${Number(s.tool_count || 0)} 个${s.enabled === false ? '，已置为停用' : ''}），并已绑定到本密钥`,
+    `registered #${s.id} ${s.name} (${Number(s.tool_count || 0)} tools${s.enabled === false ? ', disabled' : ''}) and bound to this key`));
+  if (r.probeError) {
+    // 探测失败 ≠ 登记失败：网关留着行、置成停用（地址可能只是暂时不可达）
+    ctx.say(pick(`  · 探测失败（这台已置为停用）：${r.probeError}`, `  · probe failed (server disabled): ${r.probeError}`));
+    ctx.say(pick('  · 改完地址后到管理页或重新登记一次探测即可启用', '  · fix the address and probe again to enable it'));
+  } else if (r.note) {
+    ctx.say(`  · ${r.note}`);
+  }
+  await mcpRefresh(ctx, cfg, true);
+}
+
+/** `/mcp rm <名字|id>`：删掉**自己登记**的服务器。先确认，且只认 mine 里的 */
+async function mcpRemove(ctx, cfg, argv) {
+  const key = String(argv[0] || '').trim();
+  const b = await getMcpBinding();
+  if (!b.ok) return mcpAdminFailed(ctx, b, pick('删除未执行', 'delete not executed'));
+  if (!key) {
+    ctx.say(pick('用法：/mcp rm <名字|id>（只能删你自己登记的）', 'usage: /mcp rm <name|id> (only your own registrations)'));
+    ctx.say(pick(`  你登记的：${b.mine.length ? b.mine.map((s) => `#${s.id} ${s.name}`).join('，') : '（没有）'}`,
+      `  yours: ${b.mine.length ? b.mine.map((s) => `#${s.id} ${s.name}`).join(', ') : '(none)'}`));
+    return;
+  }
+  const target = /^\d+$/.test(key)
+    ? b.mine.find((s) => Number(s.id) === Number(key))
+    : b.mine.find((s) => String(s.name) === key);
+  if (!target) {
+    // 刻意不区分「不是你的」与「不存在」：与网关的 404 同一态度（不给出存在性信号）
+    ctx.say(pick(`你登记的服务器里没有 ${key}`, `no registration of yours matches ${key}`));
+    ctx.say(pick(`  你登记的：${b.mine.length ? b.mine.map((s) => `#${s.id} ${s.name}`).join('，') : '（没有）'}`,
+      `  yours: ${b.mine.length ? b.mine.map((s) => `#${s.id} ${s.name}`).join(', ') : '(none)'}`));
+    if (!b.selfServer.allowed) ctx.say('  ' + selfServerText(b));
+    return;
+  }
+  // 删是不可逆的：能问就问一句。没有交互通道（非 TTY）时**不删**，让用户写成确定的参数
+  if (typeof ctx.ask === 'function') {
+    const a = String((await ctx.ask(pick(`确认删除 #${target.id} ${target.name}？（y/N）`, `delete #${target.id} ${target.name}? (y/N) `))) || '').trim().toLowerCase();
+    if (a !== 'y' && a !== 'yes') {
+      ctx.say(pick('已取消（没有删除任何东西）', 'cancelled (nothing was deleted)'));
+      return;
+    }
+  } else {
+    ctx.say(pick('非交互环境不自动删：请把名字或 id 写全（/mcp rm <名字|id>）',
+      'refusing to delete in a non-interactive environment: pass the name or id explicitly (/mcp rm <name|id>)'));
+    return;
+  }
+  const r = await deleteMcpServer(target.id);
+  if (!r.ok) return mcpAdminFailed(ctx, r, pick('删除未完成', 'delete failed'));
+  ctx.say(r.message);
+  if (r.note) ctx.say(`  · ${r.note}`);
+  await mcpRefresh(ctx, cfg, true);
+}
+
+/** 管理面失败的统一出口：原因 + 能照着修的一句（hint 来自 lib/mcpadmin.js） */
+function mcpAdminFailed(ctx, r, what) {
+  ctx.say(pick(`${what}：${r.message}`, `${what}: ${r.message}`));
+  if (r.hint) ctx.say(`  · ${r.hint}`);
+}
+
 /** 表里的全部主名，按定义顺序（帮助、补全、测试都用它）。 */
 export const COMMAND_NAMES = Object.keys(COMMANDS);
 
-/** 机器可读的命令行（跨端契约断言用；字段与网关侧 commandRows() 一致）。 */
-export function commandRows(registry = COMMANDS) {
+/**
+ * 机器可读的命令行（跨端契约断言用；字段与网关侧 commandRows() 一致）。
+ *
+ * `lang` **默认 zh**：网关用它生成 `/api/commands` 喂给中文手册页，
+ * 不能被 `node server.js --lang en` 带跑偏（那样手册正文是中文、表格是英文）。
+ */
+export function commandRows(registry = COMMANDS, lang = 'zh') {
+  const en = lang === 'en';
   return Object.keys(registry).map((key) => {
     const c = registry[key];
+    const e = (en && c.en) || {};
     return {
       name: c.name,
       aliases: (c.aliases || []).slice(),
-      args: c.args || '—',
-      usage: c.usage,
-      help: c.desc,
-      group: c.group,
+      args: e.args || c.args || '—',
+      usage: e.usage || c.usage,
+      help: e.desc || c.desc,
+      group: e.group || c.group,
       capability: c.capability,
       surfaces: (c.surfaces || []).slice(),
       needsArgs: !!c.needsArgs,
@@ -416,51 +711,83 @@ export function commandRows(registry = COMMANDS) {
   });
 }
 
+/**
+ * 表内取词：按**传入的 lang** 取，而不是进程语言 ——
+ * 否则 `helpText(x, 'zh')` 会出现「标题中文、正文英文」这种半中半英（两处语言来源不同）。
+ */
+const byLang = (lang, zh, en) => (lang === 'en' && en ? en : zh);
+
 /** 能力标记（写给终端看的，不是机器口径）。 */
-function capNote(c) {
-  if (c.capability === 'fs') return '（读写本地文件）';
-  if (c.capability === 'api') return '（需网关接口）';
+function capNote(c, lang = 'zh') {
+  if (c.capability === 'fs') return byLang(lang, '（读写本地文件）', ' (reads/writes local files)');
+  if (c.capability === 'api') return byLang(lang, '（需网关接口）', ' (needs the gateway API)');
   return '';
 }
 
 /**
  * 帮助文本：无参数 = 分组总表；带参数 = 单条用法。
  * 不做 Markdown（终端里难看），也不做候选面板（无 raw mode）。
+ *
+ * `lang` 默认取**当前进程语言**：只有 CLI 的 `/help` 调它（Web 侧走 commandRows，默认 zh）。
+ * 整段（含标题与脚注）都由同一个 lang 决定，不混用 pick()。
  */
-export function helpText(name) {
+export function helpText(name, lang = getLang()) {
+  const L = (zh, en) => byLang(lang, zh, en);
+  /** 表里那条命令在当前语言下的元数据 */
+  const meta = (c) => {
+    const e = (lang === 'en' && c.en) || {};
+    return {
+      usage: e.usage || c.usage,
+      desc: e.desc || c.desc,
+      group: e.group || c.group || L('其他', 'Other'),
+      args: e.args || c.args,
+    };
+  };
   if (name) {
     const bare = String(name).replace(/^\//, '');
     const key = '/' + bare.toLowerCase();
     const cmd = COMMANDS[key] || COMMANDS[findByAlias(bare.toLowerCase()) || ''];
-    if (!cmd) return `没有这条命令：${name}（用 /help 看全部）`;
+    if (!cmd) {
+      return L(`没有这条命令：${name}（用 /help 看全部）`, `No such command: ${name} (use /help to list all)`);
+    }
+    const m = meta(cmd);
     const lines = [
-      `${cmd.usage}    ${cmd.desc}`,
-      `  别名：${(cmd.aliases || []).length ? cmd.aliases.map((a) => '/' + a).join(' ') : '—'}`,
-      `  能力：${cmd.capability}${capNote(cmd)}　端：${(cmd.surfaces || []).join(' / ')}`,
+      `${m.usage}    ${m.desc}`,
+      L(
+        `  别名：${(cmd.aliases || []).length ? cmd.aliases.map((a) => '/' + a).join(' ') : '—'}`,
+        `  aliases: ${(cmd.aliases || []).length ? cmd.aliases.map((a) => '/' + a).join(' ') : '—'}`,
+      ),
+      L(
+        `  能力：${cmd.capability}${capNote(cmd, lang)}　端：${(cmd.surfaces || []).join(' / ')}`,
+        `  capability: ${cmd.capability}${capNote(cmd, lang)}  surfaces: ${(cmd.surfaces || []).join(' / ')}`,
+      ),
     ];
-    if (cmd.bare) lines.push(`  裸词也可以：${cmd.name}`);
+    if (cmd.bare) lines.push(L(`  裸词也可以：${cmd.name}`, `  the bare word works too: ${cmd.name}`));
     return lines.join('\n');
   }
-  const width = Math.max(...COMMAND_NAMES.map((n) => COMMANDS[n].usage.length));
+  const width = Math.max(...COMMAND_NAMES.map((n) => meta(COMMANDS[n]).usage.length));
   const groups = [];
   COMMAND_NAMES.forEach((n) => {
-    const g = COMMANDS[n].group || '其他';
+    const g = meta(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}`);
+    COMMAND_NAMES.filter((n) => meta(COMMANDS[n]).group === g).forEach((n) => {
+      const m = meta(COMMANDS[n]);
+      rows.push(`    ${m.usage.padEnd(width)}  ${m.desc}`);
     });
   });
   return [
-    '斜杠命令（/help <命令名> 看单条用法；同名命令与网关 Web 端语义一致）：',
+    L(
+      '斜杠命令（/help <命令名> 看单条用法；同名命令与网关 Web 端语义一致）：',
+      'Slash commands (/help <command> for one command; same-name commands mean the same on the gateway web UI):',
+    ),
     ...rows,
     '',
-    '其它输入直接交给模型；行尾写 \\ 可续行。',
-    '想让 /clear 这样的文字原样发给模型：写成 //clear。',
+    L('其它输入直接交给模型；行尾写 \\ 可续行。', 'Anything else goes straight to the model; end a line with \\ to continue it.'),
+    L('想让 /clear 这样的文字原样发给模型：写成 //clear。', 'To send text like /clear to the model verbatim, write //clear.'),
   ].join('\n');
 }