llm-api-gateway-cli 1.0.5 → 1.0.6

package/lib/setup.js

@@ -13,11 +13,15 @@
  *
  * 「默认值」的处理是这套东西的关键：默认值**只在提问时以 `[默认]` 形式给出**，
  * 用户回车才采用、也可以直接覆盖 —— 不做「悄悄用默认值跑起来」这件事。
+ *
+ * 输出语言（20260922）：文案全部走 `pick(中文, 英文)`，默认中文一字不变；
+ * 语言由入口脚本 setLang 设好，这里只管取词。**pick 必须在函数里调用**（见 lib/i18n.js 纪律 3）。
  */
 
 import { strArg } from './common.js';
 import { settingsFilePath, writeSettings, resolveSettings } from './settings.js';
 import { secretFilePath, writeSecret, resolveSecretKey, KEY_SHAPE, SECRET_FILE_NAME } from './secrets.js';
+import { pick } from './i18n.js';
 
 /** 地址校验：与 settings 白名单同一口径（lib/settings.js:65） */
 export const HTTP_URL_RE = /^https?:\/\/[^\s]+$/i;
@@ -25,17 +29,20 @@ export const HTTP_URL_RE = /^https?:\/\/[^\s]+$/i;
 /** 校验网关地址；通过返回 ''，否则返回一句人话 */
 export function validateBaseUrl(v) {
   const s = strArg(v);
-  if (!s) return '网关地址不能为空';
-  if (!HTTP_URL_RE.test(s)) return '网关地址需要以 http:// 或 https:// 开头';
+  if (!s) return pick('网关地址不能为空', 'Gateway URL must not be empty');
+  if (!HTTP_URL_RE.test(s)) return pick('网关地址需要以 http:// 或 https:// 开头', 'Gateway URL must start with http:// or https://');
   return '';
 }
 
 /** 校验密钥：与 lib/secrets.js 的 KEY_SHAPE 同一口径 */
 export function validateKey(v) {
   const s = strArg(v);
-  if (!s) return '网关密钥不能为空';
+  if (!s) return pick('网关密钥不能为空', 'Gateway key must not be empty');
   if (!KEY_SHAPE.test(s)) {
-    return `密钥形状不对：需要以 sk- 开头且长度足够（收到 ${s.length} 个字符，前缀 ${s.slice(0, 3)}）`;
+    return pick(
+      `密钥形状不对：需要以 sk- 开头且长度足够（收到 ${s.length} 个字符，前缀 ${s.slice(0, 3)}）`,
+      `Bad key shape: it must start with sk- and be long enough (got ${s.length} characters, prefix ${s.slice(0, 3)})`,
+    );
   }
   return '';
 }
@@ -60,18 +67,45 @@ export function maskKeyish(key) {
   return `${s.slice(0, 6)}****${s.slice(-4)}`;
 }
 
-/** 向导正文（纯文本，便于测试逐字断言） */
+/** 向导正文（纯文本，便于测试逐字断言）；只有默认地址那一行要插值，所以整段在函数里取词 */
 export function setupIntro({ baseUrlDefault }) {
-  return [
-    'LLM API Gateway · 首次配置',
-    '',
-    '这一步问两件事，都只写在本机（不会上传、不会进 git）：',
-    `  1) 网关地址：你部署的 LLM API Gateway 的地址（默认 ${baseUrlDefault}）`,
-    '  2) 网关密钥：网关后台发放的 sk- 密钥',
-    '',
-  ].join('\n');
+  return pick(
+    [
+      'LLM API Gateway · 首次配置',
+      '',
+      '这一步问两件事，都只写在本机（不会上传、不会进 git）：',
+      `  1) 网关地址：你部署的 LLM API Gateway 的地址（默认 ${baseUrlDefault}）`,
+      '  2) 网关密钥：网关后台发放的 sk- 密钥',
+      '',
+    ].join('\n'),
+    [
+      'LLM API Gateway · First-time setup',
+      '',
+      'This asks two things, and both stay on this machine (nothing is uploaded, nothing goes into git):',
+      `  1) Gateway URL: the address of your LLM API Gateway deployment (default ${baseUrlDefault})`,
+      '  2) Gateway key: the sk- key issued by the gateway console',
+      '',
+    ].join('\n'),
+  );
 }
 
+/** 向导收尾提示：静态两块模板，函数里 pick（见 lib/i18n.js 纪律 3） */
+const SETUP_NEXT_ZH =
+  '\n接下来：\n' +
+  '  gateway-agent                命令行对话（现在直接可用）\n' +
+  '  gateway-task                 本机 Web UI 与任务页 → http://127.0.0.1:3100\n' +
+  '  gateway-agent config list    看所有配置项与它们的「来源」\n' +
+  '改网关地址 / 模型：gateway-agent config set baseUrl|model …，或在任务页「设置 → 其他配置」里改。\n' +
+  '密钥明文只在网关后台能重新生成；这里只回掩码。\n';
+
+const SETUP_NEXT_EN =
+  '\nNext:\n' +
+  '  gateway-agent                command-line chat (ready to use now)\n' +
+  '  gateway-task                 local Web UI and task page → http://127.0.0.1:3100\n' +
+  '  gateway-agent config list    inspect every setting and where it comes from\n' +
+  'Change the gateway URL / model: gateway-agent config set baseUrl|model …, or use "Settings → Other" on the task page.\n' +
+  'The plaintext key can only be regenerated in the gateway console; only a mask is shown here.\n';
+
 /**
  * 跑一次设置向导。
  *
@@ -104,7 +138,10 @@ export async function runSetup({
     return {
       ok: false,
       code: 1,
-      error: '当前不是交互终端：请用 `gateway-agent setup --base-url <地址> --key sk-xxx` 一次配完。',
+      error: pick(
+        '当前不是交互终端：请用 `gateway-agent setup --base-url <地址> --key sk-xxx` 一次配完。',
+        'Not an interactive terminal: run `gateway-agent setup --base-url <url> --key sk-xxx` to configure everything in one go.',
+      ),
     };
   }
 
@@ -114,7 +151,7 @@ export async function runSetup({
   let baseUrl = givenBase;
   if (!baseUrl) {
     for (let i = 0; i < attempts; i++) {
-      const answer = await ask('网关地址', { default: currentBase });
+      const answer = await ask(pick('网关地址', 'Gateway URL'), { default: currentBase });
       const value = strArg(answer) || currentBase; // 回车 = 采用方括号里的默认值
       const err = validateBaseUrl(value);
       if (!err) {
@@ -123,14 +160,20 @@ export async function runSetup({
       }
       log(`  ✗ ${err}\n`);
     }
-    if (!baseUrl) return { ok: false, code: 1, error: '网关地址没填对，已取消（没有写入任何文件）。' };
+    if (!baseUrl) {
+      return {
+        ok: false,
+        code: 1,
+        error: pick('网关地址没填对，已取消（没有写入任何文件）。', 'Gateway URL was not valid; cancelled (no file was written).'),
+      };
+    }
   }
 
   /* ---------- 2) 网关密钥 ---------- */
   let key = givenKey;
   if (!key) {
     for (let i = 0; i < attempts; i++) {
-      const answer = await ask('网关密钥', { mask: true });
+      const answer = await ask(pick('网关密钥', 'Gateway key'), { mask: true });
       const err = validateKey(answer);
       if (!err) {
         key = strArg(answer);
@@ -138,7 +181,13 @@ export async function runSetup({
       }
       log(`  ✗ ${err}\n`);
     }
-    if (!key) return { ok: false, code: 1, error: '网关密钥没填对，已取消（没有写入任何文件）。' };
+    if (!key) {
+      return {
+        ok: false,
+        code: 1,
+        error: pick('网关密钥没填对，已取消（没有写入任何文件）。', 'Gateway key was not valid; cancelled (no file was written).'),
+      };
+    }
   }
 
   /* ---------- 3) 落盘：复用既有实现，原子写与权限都在里面 ---------- */
@@ -148,30 +197,28 @@ export async function runSetup({
     const res = writeSettings({ baseUrl: baseUrl.replace(/\/+$/, '') }, { file });
     wrote = writeSecret(key, { file: secretFile });
     log(
-      '\n已写入：\n' +
-        `  网关地址  ${baseUrl.replace(/\/+$/, '')}\n            → ${res.file}\n` +
-        `  网关密钥  ${maskKeyish(key)}\n            → ${wrote.file}${wrote.mode ? `（权限 ${wrote.mode.toString(8)}）` : '（Windows：靠用户目录 ACL）'}\n` +
-        (wrote.warning ? `${wrote.warning}\n` : ''),
+      pick(
+        '\n已写入：\n' +
+          `  网关地址  ${baseUrl.replace(/\/+$/, '')}\n            → ${res.file}\n` +
+          `  网关密钥  ${maskKeyish(key)}\n            → ${wrote.file}${wrote.mode ? `（权限 ${wrote.mode.toString(8)}）` : '（Windows：靠用户目录 ACL）'}\n`,
+        '\nWritten:\n' +
+          `  Gateway URL  ${baseUrl.replace(/\/+$/, '')}\n               → ${res.file}\n` +
+          `  Gateway key  ${maskKeyish(key)}\n               → ${wrote.file}${wrote.mode ? ` (mode ${wrote.mode.toString(8)})` : ' (Windows: relies on the user-directory ACL)'}\n`,
+      ) + (wrote.warning ? `${wrote.warning}\n` : ''),
     );
   } catch (e) {
-    return { ok: false, code: 1, error: `写入配置失败：${e.message}` };
+    return { ok: false, code: 1, error: `${pick('写入配置失败：', 'Failed to write the configuration: ')}${e.message}` };
   }
 
-  log(
-    '\n接下来：\n' +
-      '  gateway-agent                命令行对话（现在直接可用）\n' +
-      '  gateway-task                 本机 Web UI 与任务页 → http://127.0.0.1:3100\n' +
-      '  gateway-agent config list    看所有配置项与它们的「来源」\n' +
-      '改网关地址 / 模型：gateway-agent config set baseUrl|model …，或在任务页「设置 → 其他配置」里改。\n' +
-      '密钥明文只在网关后台能重新生成；这里只回掩码。\n',
-  );
+  log(pick(SETUP_NEXT_ZH, SETUP_NEXT_EN));
 
   return { ok: true, code: 0, baseUrl: baseUrl.replace(/\/+$/, ''), key, file: resolveSettings({ file, env }).file, secretFile: wrote.file, secretName: SECRET_FILE_NAME };
 }
 
-/** `setup --help` 的正文 */
+/** `setup --help` 的正文；两块模板里有运行时路径，所以在函数里取词（关键仍是 pick 在函数内求值） */
 export function setupHelp() {
-  return `用法：gateway-agent setup [--base-url <地址>] [--key sk-xxx]
+  return pick(
+    `用法：gateway-agent setup [--base-url <地址>] [--key sk-xxx]
 
 首次配置引导：问一次「网关地址」和「网关密钥」，写进本机的两个文件 ——
   网关地址 → ${settingsFilePath()}
@@ -186,7 +233,24 @@ export function setupHelp() {
   网页「设置」面板（任务页「其他配置」里地址与密钥都有）
   gateway-agent config set baseUrl <地址> / config set key sk-xxx
   环境变量 GATEWAY_BASE_URL / SK / GATEWAY_KEY，或当前目录的 .env
-`;
+`,
+    `Usage: gateway-agent setup [--base-url <url>] [--key sk-xxx]
+
+First-time setup: asks once for the gateway URL and the gateway key, then writes them to two local files —
+  Gateway URL → ${settingsFilePath()}
+  Gateway key → ${secretFilePath()} (not stored in config.json)
+
+  --base-url <url>    give it directly, no question asked (must start with http:// or https://)
+  --key sk-xxx        give it directly, no question asked
+  both given → nothing is asked, good for scripts / CI
+  neither given → interactive Q&A (defaults are shown in [brackets]; Enter accepts them)
+
+Equivalent ways (any one of them; they read and write the same configuration):
+  the Web "Settings" panel (the task page has both URL and key under "Other settings")
+  gateway-agent config set baseUrl <url> / config set key sk-xxx
+  the GATEWAY_BASE_URL / SK / GATEWAY_KEY environment variables, or a .env in the current directory
+`,
+  );
 }
 
 /**
@@ -254,7 +318,8 @@ export function createTerminalAsk({ input = process.stdin, output = process.stdo
 
   return (label, { default: def = '', mask = false } = {}) => {
     const suffix = def ? ` [${def}]` : '';
-    const hint = mask ? '（sk- 开头，输入不回显）' : '';
-    return readLine(`${label}${suffix}${hint}：`, mask);
+    const hint = mask ? pick('（sk- 开头，输入不回显）', ' (starts with sk-, input is hidden)') : '';
+    // 行尾标点也要跟着语言走：中文是全角「：」，英文是半角「: 」
+    return readLine(pick(`${label}${suffix}${hint}：`, `${label}${suffix}${hint}: `), mask);
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-api-gateway-cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "CLI 测试工具：验证 LLM API Gateway（http://127.0.0.1:9000）的 OpenAI / Anthropic / 原生 Agent / Claude Code 多种接入方式",
   "type": "module",
   "bin": {

package/public/manual.html

@@ -70,6 +70,7 @@
       <a href="#s-modes">三种模式</a>
       <a href="#s-workdir">工作目录与边界</a>
       <a href="#s-howto">指令怎么用</a>
+      <a href="#s-lang">输出语言</a>
       <a href="#s-commands">指令一览</a>
       <a href="#s-faq">常见问题</a>
     </nav>
@@ -360,6 +361,7 @@ gateway-agent config set mode auto          # 新任务的默认审批模式</co
         <li>模型的一切文件操作都被限制在你选定<b>工作目录</b>之内；换目录用顶栏的目录芯片，或敲 <code>/cwd &lt;路径&gt;</code>。</li>
         <li><code>/files [子路径]</code> 列目录、<code>/init</code> 在工作目录里生成 <code>AGENTS.md</code> 项目约定骨架、<code>/instructions</code> 看当前注入给模型的项目记忆（<code>AGENTS.md</code> / <code>CLAUDE.md</code>，超上限截断）。</li>
         <li>任务记录（含工具读过的文件正文）由服务端直写磁盘，换浏览器、清缓存都不会丢；存储位置在设置面板里能看到，也可以用启动参数 <code>--store &lt;目录&gt;</code> 换地方。</li>
+        <li><b>命令行里的对话不在这一页</b>：侧边栏列的是<b>任务</b>（<code>&lt;数据根&gt;/tasks/</code>）；命令行 <code>gateway-agent -i</code> 的会话是<b>另一份存储</b>（<code>&lt;数据根&gt;/sessions/&lt;uuid&gt;.json</code>），网页侧不读它 —— 所以终端里聊的内容不会出现在任务列表里，反过来网页任务也不在 <code>--resume</code> 的候选里。想在网页里<b>看</b>它：<a href="/sessions">/sessions</a>（<b>只读</b>回放；首页 Tab 栏的「<b>命令行</b>」就是它，同页切换不开新标签；单独打开任务页时侧栏也有入口）；要接着聊就在终端：<code>gateway-agent -i --continue</code> / <code>--resume &lt;id&gt;</code>，或 REPL 里 <code>/resume</code>（详见下一节与 FAQ）。</li>
         <li>侧边栏<b>按工作目录分组</b>：同一个目录下可以挂多条任务，分组行右侧的 <code>＋</code> 直接在该目录下再开一条。鼠标移到某条任务上，行尾的 <code>＋</code> 可以<b>派生一条子任务</b>（继承父任务的工作目录，第二行以 <code>↳</code> 缩进显示）；删父任务不会连坐，子任务会升一层。</li>
         <li>存储目录若正好落在工作目录之内，页面会提醒你：模型能读到任务历史。要避免就把 <code>--store</code> 指到工作目录之外。</li>
         <li><code>bash</code> 工具默认不开（模型跑不了测试）；要用请在启动服务时加 <code>--allow-bash</code>。设置面板的「可用工具」一行会写清当前有哪些。</li>
@@ -376,11 +378,92 @@ gateway-agent config set mode auto          # 新任务的默认审批模式</co
         <li>指令带「能力」标记：<code>local</code> 本页即可；<code>api</code> 要用服务端接口；<code>fs</code> 需要服务端放行本机文件访问（服务没绑定在本机地址时会不可用，页面会说明原因）。</li>
         <li><code>/help</code> 列任务页全部指令，<code>/help &lt;指令名&gt;</code> 看单条用法（别名、能力、示例）。</li>
         <li><code>/model</code> 改的就是设置面板里的「模型」，这一项<b>只能从网关 <code>/v1/models</code> 拉到的列表里选</b>（设置面板里是个下拉框，打不进字）。不带参数敲 <code>/model</code> 会列出可选模型；想改的模型不在列表里，先点设置面板的「刷新模型」，或检查网关这一侧绑定的上游。</li>
+        <li><b>命令行里的 <code>/mcp</code> 还能管绑定与自助登记</b>（终端 REPL 里敲）：<code>/mcp</code> 看「已绑 / 可自助加 / 我自建」三段；<code>/mcp bind +3 -5</code> 或 <code>/mcp bind =2,7</code> 改绑；<code>/mcp mode off|inject|loop</code> 只改模式、不动绑定；<code>/mcp add &lt;名字&gt; &lt;URL&gt; [--header "k: v"]</code> 登记自己的 http/https 公网 MCP 服务器（网关探测一次并自动绑定）；<code>/mcp rm &lt;名字|id&gt;</code> 删掉自己登记的（先确认）。
+          能不能自助登记<b>由网关说了算</b>：没开放时只打印开启办法（网关 <code>.env</code> 设 <code>MCP_ALLOW_SELF_SERVERS=true</code> 并重启），不发那次注定 403 的请求；地址里的 <code>?key=</code> 这类凭据与 <code>--header</code> 的值<b>只显示掩码</b>（明文只发给网关）。
+          <b>不想敲终端就用网页</b>：首页 Tab 栏的「<b>MCP</b>」（同页切换，不开新标签），或直接开 <a href="/mcp">/mcp</a>；单独打开任务页时侧栏也有入口 —— 同一件事的图形入口，范围同样只是<b>你这把密钥</b>，而且<b>密钥不进浏览器</b>（页面只打本机接口，由服务代发）。全局服务器与统计仍归网关的管理员页面（<code>http://localhost:9000/#/mcp</code>）；「开不开自助登记」是网关 <code>.env</code> 的部署期开关，页面上没有这个按钮。命令与用法在下面的指令表里也有（由代码生成）。</li>
+        <li><b>命令行可以切成英文</b>：<code>--lang en</code>（或环境变量 <code>LLM_GATEWAY_LANG=en</code>），
+          覆盖 <code>--help</code> / 横幅 / 报错 / REPL 提示 / <code>config</code> / <code>setup</code>；
+          <b>不给就是中文</b>，本页与网页界面始终中文 —— 详见下一节「命令行输出语言」。</li>
       </ul>
     </section>
 
+    <section id="s-lang">
+      <h2>七、命令行输出语言（<code>--lang en</code>）</h2>
+      <p>
+        命令行侧可以切成英文，<b>默认仍然是中文</b>（不给语言时与加这个开关之前逐字一致）。
+        两种给法等价，<code>--lang</code> 优先：
+      </p>
+      <div class="code-block"><code>gateway-agent --help --lang en            # 英文帮助
+gateway-agent -i --lang en                # 英文 REPL：提示语、横幅、写入批准闸门都变英文
+LLM_GATEWAY_LANG=en gateway-agent -p "…"  # 环境变量写法，与上面等价
+node server.js --help --lang en           # 起服务的方式也认（只影响这一行帮助）
+# Windows PowerShell：$env:LLM_GATEWAY_LANG='en'; gateway-agent -i</code></div>
+      <div class="manual-table-wrap">
+        <table class="manual-table">
+          <thead>
+            <tr><th>给法</th><th>优先级</th><th>说明</th></tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td class="cmd">--lang en / --lang zh</td>
+              <td>最高</td>
+              <td><code>zh-CN</code> / <code>en-US</code> / <code>english</code> / <code>cn</code> 这类写法都认</td>
+            </tr>
+            <tr>
+              <td class="cmd">LLM_GATEWAY_LANG=en</td>
+              <td>次之</td>
+              <td>认不出的值<b>不报错</b>，直接退回默认中文 —— 语言不该拦住任何一次运行</td>
+            </tr>
+            <tr>
+              <td class="cmd">都不给</td>
+              <td>默认</td>
+              <td><code>zh</code></td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+      <div class="manual-table-wrap">
+        <table class="manual-table">
+          <thead>
+            <tr><th>会跟着变</th><th>不会变（始终中文）</th></tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>四个 CLI 入口与 <code>server.js</code> 的 <code>--help</code></td>
+              <td><b>Web 界面</b>：聊天页 / 任务页 / 设置面板</td>
+            </tr>
+            <tr>
+              <td>启动横幅（网关 / 模型 / 密钥来源那几行）</td>
+              <td><b>这一页手册</b>（包括下面的指令表格）</td>
+            </tr>
+            <tr>
+              <td>各种报错、缺密钥提示</td>
+              <td><code>GET /api/commands</code> 下发给网页的指令清单</td>
+            </tr>
+            <tr>
+              <td>REPL 提示（<code>/help</code> 的指令表、退出语）</td>
+              <td>发给模型的系统提示词与工具描述（那是<b>模型行为语言</b>，不是界面语言）</td>
+            </tr>
+            <tr>
+              <td><code>config list|get|set|unset|path</code> 与 <code>setup</code> 的输出</td>
+              <td>接口下发的报错文案（Web 与集成方的契约）</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+      <p class="manual-note">
+        <b>为什么这一页不受影响</b>：语言是<b>进程级</b>开关（<code>lib/i18n.js</code>，零依赖），只在各入口脚本里
+        <code>setLang(resolveLang(args, env))</code> 设置一次，其余模块只管 <code>pick(中文, English)</code>；
+        手册页的指令表格由 <code>commandRows()</code> 生成，而它的<b>默认语言就是 <code>zh</code></b> ——
+        所以哪怕你用 <code>node server.js --lang en</code> 起服务，这一页与接口下发的清单仍是中文，不会半中半英。
+        缺英文时一律回落中文（不返回空串 / <code>undefined</code>），这是 <code>pick()</code> 的约定。
+        这个开关由 <code>tests/i18n.test.mjs</code> 盯着（含真起子进程跑五个入口的 <code>--help</code>，
+        英文输出里出现中文或全角字符就算失败）。
+      </p>
+    </section>
+
     <section id="s-commands">
-      <h2>七、指令一览（自动生成）</h2>
+      <h2>八、指令一览（自动生成）</h2>
       <p class="manual-note">
         三端对照在前，各端清单在后。<code>命令行 REPL</code> 是终端里的 <code>gateway-agent</code>；
         <code>任务页</code> 是本服务的 <code>/task</code>；<code>本机聊天页</code> 是本服务的 <code>/</code>。
@@ -389,8 +472,26 @@ gateway-agent config set mode auto          # 新任务的默认审批模式</co
     </section>
 
     <section id="s-faq">
-      <h2>八、常见问题</h2>
+      <h2>九、常见问题</h2>
       <dl class="manual-faq">
+        <dt>刚才在命令行聊的那条，网页任务列表里怎么没有？</dt>
+        <dd>
+          这是设计如此，不是丢了：网页侧边栏只列 <code>&lt;数据根&gt;/tasks/</code> 里的<b>任务</b>（模式五），
+          命令行 REPL 的会话在<b>另一个目录</b> <code>&lt;数据根&gt;/sessions/&lt;uuid&gt;.json</code>（模式六，
+          默认数据根是 <code>~/.llm-api-gateway-cli</code>），网页侧<b>没有任何接口读它</b> ——
+          两者的记录字段本来就不同（任务有标题、更新时间、回复索引；会话只有消息与用量），
+          所以两边各列各的，<b>不会互相出现</b>。要接着那条聊：
+          <code>gateway-agent -i --continue</code>（最近一条）或 <code>gateway-agent -i --resume &lt;uuid&gt;</code>，
+          REPL 里敲 <code>/resume</code> 会列出最近几条；在哪个目录启动都行 ——
+          恢复时优先沿用会话里记下的工作目录（<code>-C</code> 才覆盖）。
+          想直接看文件：<code>dir %USERPROFILE%\.llm-api-gateway-cli\sessions</code>
+          （POSIX：<code>ls ~/.llm-api-gateway-cli/sessions</code>），一条会话一个 <code>.json</code>。
+          命令行切成英文（<code>--lang en</code>）与这件事无关。
+          <b>想在网页里看它</b>：打开 <a href="/sessions">/sessions</a>（<b>首页顶栏的「命令行」</b>、任务页顶栏与侧栏也都能进）——
+          那是<b>只读回放</b>：列出 <code>&lt;数据根&gt;/sessions/</code> 里的会话，点开能看全文，
+          但页面上没有输入框、改不了任何东西（要接着聊仍是上面那条终端命令）。
+        </dd>
+
         <dt><code>/files</code> 说"未放行"？</dt>
         <dd>目录浏览、项目记忆、任务记录这类接口会回传本机路径与文件正文，服务只在本机监听（或显式加了 <code>--allow-remote-fs</code>）时才放行。用 <code>--host 0.0.0.0</code> 从别的机器访问时，它们是关着的 —— 这是有意的安全边界。</dd>
 
@@ -429,7 +530,10 @@ gateway-agent config set mode auto          # 新任务的默认审批模式</co
         <dt>装的时候说「没有 Node」或「Node 版本太低」？</dt>
         <dd>安装器<b>不代装</b>运行时：它只报错并告诉你需要什么（<code>node -v</code> 要 ≥ 18），不动你的系统。装好 Node 再重跑同一条命令即可；中途失败也不会留半成品（临时文件必删）。</dd>
 
-        <dt>我不想装，只想在仓库里直接用？</dt>
+        <dt><code>--lang en</code> 给了，网页界面怎么还是中文？</dt>
+        <dd>这是有意的：语言开关只作用于<b>命令行侧</b>（<code>--help</code> / 横幅 / 报错 / REPL 提示 / <code>config</code> / <code>setup</code> / 写入批准闸门），网页界面、这一页手册以及 <code>GET /api/commands</code> 下发的指令清单始终是中文；发往模型的系统提示词与工具描述也不跟着变。给法、优先级与完整边界见第七节「命令行输出语言」。另外注意 <code>node server.js --lang en</code> 只影响它自己那行 <code>--help</code>，不影响它起出来的页面。</dd>
+
+        <dt>不想装，只想在仓库里直接用？</dt>
         <dd>在项目目录 <code>npm install</code> 之后，<code>node cli-agent.js</code>（终端 Agent）、<code>node server.js</code>（本机 Web UI 与任务页 <code>http://127.0.0.1:3100</code>）直接就能跑；<code>npm link</code> 只是把同一份东西做成任意目录可用的全局命令。</dd>
 
         <dt>装完了，但敲 <code>gateway-agent</code> 说找不到命令？</dt>

package/public/mcp.css

@@ -0,0 +1,155 @@
+/**
+ * 网页 MCP 面板（/mcp）样式
+ *
+ * 与 sessions.css 同一纪律：只取 styles.css 里的变量，不定义新变量、不写裸颜色 ——
+ * theme.test.mjs 的「无裸十六进制颜色 / 无裸 rgba / 变量都有定义」三条对本文件同样成立。
+ * 骨架复用 styles.css 的 .app / .sidebar / .main / .topbar / .messages。
+ */
+
+.mcp-doc {
+  padding: 4px 0 40px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.mcp-card {
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--bg-soft);
+  padding: 12px 14px;
+}
+
+.mcp-card > h2 {
+  margin: 0 0 10px;
+  font-size: 13.5px;
+  color: var(--text);
+}
+
+.mcp-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  font-size: 12.5px;
+  color: var(--text-dim);
+  line-height: 1.9;
+}
+
+.mcp-row code {
+  font-family: var(--mono);
+  color: var(--text);
+}
+
+.mcp-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 5px 0;
+  font-size: 12.5px;
+  color: var(--text);
+  border-bottom: 1px dashed var(--border);
+}
+
+.mcp-item:last-child { border-bottom: none; }
+
+.mcp-item .name {
+  font-family: var(--mono);
+}
+
+.mcp-item .meta {
+  color: var(--text-dim);
+  font-size: 11.5px;
+}
+
+.mcp-item .spacer { flex: 1; }
+
+.mcp-tag {
+  padding: 0 5px;
+  border-radius: 999px;
+  font-size: 10px;
+  background: var(--accent-soft);
+  color: var(--accent);
+}
+
+.mcp-tag.warn { background: var(--warn-soft-strong); color: var(--warn); }
+.mcp-tag.off { background: var(--bg-code); color: var(--text-faint); }
+
+.mcp-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin-bottom: 8px;
+  font-size: 12px;
+  color: var(--text-dim);
+}
+
+.mcp-field input,
+.mcp-field textarea,
+.mcp-select {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 6px 8px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border);
+  background: var(--bg-raised);
+  color: var(--text);
+  font-size: 12.5px;
+  font-family: inherit;
+}
+
+.mcp-select { width: auto; }
+
+.mcp-field textarea { font-family: var(--mono); resize: vertical; }
+
+.mcp-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 6px;
+  flex-wrap: wrap;
+}
+
+.mcp-banner {
+  margin: 0;
+  padding: 10px 16px;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-soft);
+  color: var(--text-dim);
+  font-size: 12.5px;
+  line-height: 1.7;
+}
+
+.mcp-banner.danger {
+  background: var(--danger-soft);
+  border-bottom-color: var(--danger-border);
+  color: var(--danger);
+}
+
+.mcp-banner.ok {
+  background: var(--ok-soft);
+  border-bottom-color: var(--border);
+  color: var(--ok);
+}
+
+.mcp-note {
+  margin: 6px 0 0;
+  font-size: 11.5px;
+  color: var(--text-faint);
+  line-height: 1.7;
+}
+
+.mcp-tool {
+  display: block;
+  width: 100%;
+  text-align: left;
+  background: none;
+  border: none;
+  color: var(--text-dim);
+  font-size: 11.5px;
+  padding: 4px 6px;
+  border-radius: var(--radius-sm);
+  cursor: default;
+}
+
+.mcp-tool b { color: var(--text); font-weight: 600; }