llm-api-gateway-cli 1.0.1 → 1.0.3

package/README.md

@@ -1,4 +1,4 @@
-# LLM API Gateway CLI 测试工具
+# LLM API Gateway CLI 编程工具
 
 验证 `llm-api-gateway`（`http://127.0.0.1:9000`）除了 Web 对话页 / SDK 之外，**CLI 方式同样可用**。多个脚本覆盖多种接入方言，其中**原生 Agent（`cli-agent.js`）是终端里干活的推荐方式** —— 自带工具循环，无需安装 Claude Code。
 
@@ -41,6 +41,8 @@ npm install        # 安装 openai 与 @anthropic-ai/sdk
 
 > 不想翻文档也行：起服务后打开 **[操作手册页 `/manual`](http://127.0.0.1:3100/manual)**，第一节就是「安装与启动」—— 三条路线、参数表、换镜像、**首次配置（界面 / 命令行 / 环境变量三种给密钥方式、密钥存哪、网关地址与模型）**、启动自检与卸载，命令都是可复制的。
 
+> **装完第一步是 `gateway-agent setup`**：它会问一次**网关地址**与**网关密钥**并写进本机（`setup --base-url … --key …` 可一步到位；全新机器首次运行会自动进入这一步）。之后**裸敲 `llm-api-gateway-cli`（或 `gateway-agent`）就是启动器**：先问「① 对话 / ② 任务」，再问「① 命令行窗口 / ② 网页 UI」，选完直接进入对应形态 —— 不替你默认。选了网页 UI 才会起服务，然后**自己**打开 http://127.0.0.1:3100/task（「设置 → 其他配置」里地址与密钥都能改）。想跳过启动器：`-p "问题"` / `-i` / `gateway-task`。卸载用 `npm uninstall -g llm-api-gateway-cli`（`-g` 不能少）。
+
 ### macOS / Linux / WSL
 
 ```bash

package/cli-agent.js

@@ -23,6 +23,7 @@
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import readline from 'node:readline';
+import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 
 import { loadDotEnv, parseArgs, DEFAULT_BASE_URL, maskKey } from './lib/common.js';
@@ -32,6 +33,8 @@ import { createSession, restoreSession, runTurn, resumePendingTurn, countTurns }
 import { createSessionStore, resolveSessionDir, SESSION_TTL_MS } from './lib/sessionstore.js';
 import { COMMANDS, parseSlash, unescapeSlash, suggest, helpText, diffLines } from './lib/commands.js';
 import { configCommand, configHelp } from './lib/configcmd.js';
+import { runSetup, isFreshMachine, createTerminalAsk, setupHelp } from './lib/setup.js';
+import { runLauncher } from './lib/launcher.js';
 import { settingsFilePath, summarizeConfigSources } from './lib/settings.js';
 import { secretSourceText } from './lib/secrets.js';
 import { AGENT_LIMITS } from './lib/agent.js';
@@ -44,21 +47,31 @@ loadDotEnv(SCRIPT_DIR);
 const DEFAULT_MODEL = process.env.GATEWAY_MODEL || 'qwen3:8b';
 const HISTORY_LIMIT = 200;
 
-const HELP = `用法：node cli-agent.js [选项] [提示词]
-       node cli-agent.js config <list|get|set|unset|path> [键] [值]
+const HELP = `用法：gateway-agent                    启动器：先问「对话 / 任务」，再问「命令行 / 网页」
+       gateway-agent [选项] [提示词]
+       gateway-agent setup [--base-url <地址>] [--key sk-xxx]      首次配置引导
+       gateway-agent config <list|get|set|unset|path> [键] [值]
+       （同一入口的别名：llm-api-gateway-cli；源码目录里也可以 node cli-agent.js …）
 
 模式六 · 原生 Agent：自带工具循环，直接在终端里读写工作目录内的文件，写入前需确认。
 不依赖 Claude Code（无需安装 @anthropic-ai/claude-code）。
 
+相关命令（本机 Web UI —— 本命令不会替你打开浏览器）：
+  gateway-task [--port 3100]   起本机 Web UI 与任务页（gateway-web 是同一服务的别名）；
+                               没有密钥也能起，网关地址与密钥在任务页「设置」里配
+  http://127.0.0.1:3100/        聊天页
+  http://127.0.0.1:3100/task    任务页（「设置」里可改网关地址 / 模型 / 密钥）
+  http://127.0.0.1:3100/manual  操作手册页（安装、首次配置、指令一览的完整版）
+
 子命令：
+  setup                    首次配置引导：问一次「网关地址」与「网关密钥」并写进本机配置
+                           （地址 → config.json，密钥 → credentials.json）。带 --base-url /
+                           --key 时直接写入、不再提问；全新机器首次运行会自动进入这一步。
   config list|get|set|unset|path
                            查看/修改持久化配置（存到磁盘，清缓存不丢）。config list 会标出
                            每一项「当前生效值」来自命令行、环境变量、配置文件还是内置默认
                            —— 改了没生效时看这一列就知道被谁盖住了。
 
-模式六 · 原生 Agent：自带工具循环，直接在终端里读写工作目录内的文件，写入前需确认。
-不依赖 Claude Code（无需安装 @anthropic-ai/claude-code）。
-
 选项：
   -p, --prompt <文本>      单轮任务（省略则读位置参数 / 标准输入）
   -i, --interactive        进入多轮交互（REPL）
@@ -337,11 +350,53 @@ function saveHistory(sessionDir, rl) {
 
 // ---------- 主流程 ----------
 
+/**
+ * 跑一次设置向导（`setup` 子命令与「首次运行自动引导」共用）。
+ * 只负责接线：问答用真终端，正文走 stdout，失败写 stderr。
+ */
+async function runSetupFlow(args = {}) {
+  const r = await runSetup({
+    ask: createTerminalAsk(),
+    args,
+    env: process.env,
+    log: (s) => process.stdout.write(s),
+  });
+  if (!r.ok) process.stderr.write(`[错误] ${r.error}\n`);
+  return r;
+}
+
+/** 尽力打开浏览器。失败绝不影响服务本身（URL 已经打印出来了） */
+function openBrowser(url) {
+  try {
+    const cmd = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+    const argv = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(cmd, argv, { stdio: 'ignore', detached: true });
+    // 不监听 error 的话，spawn 失败会变成未处理事件把进程炸掉 —— 打不开浏览器不值得让服务挂掉
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function main() {
   // `gateway-agent config …`：配置子命令。放在 parseArgs 之前，而且不需要密钥 ——
   // 「配置还没弄好」恰恰是用户最可能先跑它的场景；交给 parseArgs 还会把
   // `set system --foo` 这类取值当成选项吃掉。
   const raw = process.argv.slice(2);
+  // `gateway-agent setup`：首次配置引导。和 `config` 一样放在 parseArgs 之前 ——
+  // 「还没配」正是最可能先跑它的场景，而它自己收 --base-url / --key（给了就不问）。
+  if (raw[0] === 'setup') {
+    const rest = raw.slice(1);
+    if (rest.includes('-h') || rest.includes('--help')) {
+      process.stdout.write(setupHelp());
+      return;
+    }
+    const r = await runSetupFlow(parseArgs(rest, VALUE_FLAGS, BOOL_FLAGS));
+    if (r.code) process.exitCode = r.code;
+    return;
+  }
   if (raw[0] === 'config') {
     const rest = raw.slice(1);
     if (rest.includes('-h') || rest.includes('--help')) {
@@ -365,7 +420,16 @@ async function main() {
   // bash 默认关闭：命令级权限不该默默打开
   setBashEnabled(Boolean(args['allow-bash']));
 
-  const bootCfg = resolveConfig(args, { defaultModel: DEFAULT_MODEL });
+  let bootCfg = resolveConfig(args, { defaultModel: DEFAULT_MODEL });
+
+  // 首次配置引导：这台机器一条配置来源都没有 + 交互终端 → 先把「网关地址 / 密钥」问清楚，
+  // 配完就地继续启动。不这么做的话，第一次用的人只会收到一句「缺少 sk- 密钥」然后被赶去看文档。
+  // 非 TTY（管道 / CI）不触发，保持原来的报错退出语义。
+  if (!bootCfg.key && process.stdin.isTTY && isFreshMachine({ env: process.env })) {
+    const r = await runSetupFlow(args);
+    if (r.ok) bootCfg = resolveConfig(args, { defaultModel: DEFAULT_MODEL });
+  }
+
   const { key, baseUrl, model, temperature, maxTokens } = bootCfg;
   // 启动横幅必须能回答「这个值从哪来」：用户在新机器上第一次跑，看到 base/model 有值会以为
   // 「已经配好了」，其实那可能只是**内置默认值**，也可能来自**当前目录的 .env**（别的项目的配置）。
@@ -382,10 +446,42 @@ async function main() {
             '          上面那两个值是**内置默认**，不是「已经配好了」——配一次之后就一直用它。\n'
           : ''),
     );
+    // 没密钥时最实用的出口是 Web UI：它没有密钥也能起（KEY_HINT 第①条没说那个页面怎么起起来）
+    process.stderr.write('          Web UI（没密钥也能起）：gateway-task  →  http://127.0.0.1:3100/task\n');
     process.stderr.write(`[错误] ${KEY_HINT}\n`);
     process.exit(1);
   }
 
+  // 裸命令（一个参数都没有）+ 交互终端 → 启动器：先问「对话 / 任务」，再问「命令行 / 网页」。
+  // 只在 argv 恰好没有参数时触发，所以 -p（单轮）、-i（直接进对话）、管道输入三条老路径一点没变。
+  let launcherInteractive = false;
+  if (process.argv.length === 2 && process.stdin.isTTY) {
+    const r = await runLauncher({
+      ask: createTerminalAsk(),
+      log: (s) => process.stdout.write(s),
+      startCli: async (plan) => {
+        launcherInteractive = true;
+        // 任务态要指定在哪个目录干活：走 args.cwd，下面 checkWorkDir 会照常校验它
+        if (plan.workDir) args.cwd = plan.workDir;
+        return { code: 0 };
+      },
+      startWeb: async (plan) => {
+        // 不另起子进程：在本进程内起同一个 hub（聊天页/任务页是同一个服务），Ctrl+C 停止
+        const { runHub } = await import('./lib/hub.js');
+        runHub([], { entry: plan.entry });
+        openBrowser(plan.url);
+        return { code: 0 };
+      },
+    });
+    if (!r.ok) {
+      process.stderr.write(`[错误] ${r.error}\n`);
+      process.exitCode = r.code || 1;
+      return;
+    }
+    // 选了网页：服务已经 listen，本进程就留着当服务用，不再往下走 REPL
+    if (r.plan?.kind === 'web') return;
+  }
+
   // 会话存储（可关）：--no-session 时 store 为 null，行为退回纯内存
   let store = null;
   let sessionDir = null;
@@ -467,7 +563,7 @@ async function main() {
     }
   };
 
-  let interactive = Boolean(args.interactive);
+  let interactive = Boolean(args.interactive) || launcherInteractive;
   let prompt = typeof args.prompt === 'string' ? args.prompt : args._.join(' ').trim();
 
   // 没给提示词又不在交互模式：先尝试标准输入；TTY 下（没有输入）则退化为交互模式
@@ -537,6 +633,7 @@ async function main() {
       `          密钥 ${maskKey(key)}（${keySrcOf}）\n` +
       `          工作目录 ${workDir}\n` +
       `          工具 ${toolNames}${args['allow-bash'] ? '  [bash 已开启]' : ''}\n` +
+      `          Web UI gateway-task → http://127.0.0.1:3100/task（本命令不会替你打开浏览器）\n` +
       `          ${mcpLine}\n` +
       `          轮次上限 ${session.maxSteps || AGENT_LIMITS.MAX_STEPS} 轮\n` +
       (resumedFrom ? `          已恢复会话 ${resumedFrom}（${countTurns(session)} 条消息）\n` : '') +
@@ -680,4 +777,7 @@ async function main() {
   }
 }
 
-main();
+main().catch((e) => {
+  process.stderr.write(`[错误] ${e?.message || e}\n`);
+  process.exit(1);
+});

package/lib/config.js

@@ -8,8 +8,9 @@
  * 所有 CLI 都走 resolveConfig，保证问「密钥从哪来」只有一种答案。
  */
 
-import { resolveBaseUrl, strArg } from './common.js';
+import { DEFAULT_BASE_URL, strArg } from './common.js';
 import { resolveSecretKey } from './secrets.js';
+import { resolveSettings, settingsFilePath } from './settings.js';
 
 /**
  * 缺密钥时的统一提示（各 CLI 文案一致，避免用户按提示改了还是不通）。
@@ -19,8 +20,8 @@ import { resolveSecretKey } from './secrets.js';
  * 用户会按着提示配完发现还是报缺密钥。
  */
 export const KEY_HINT =
-  '缺少 sk- 密钥：① 在任务页/聊天页「设置」里填（存 credentials.json，仅本用户可读，命令行也认它）；'
-  + '② 或执行 gateway-agent config set key sk-xxx；'
+  '缺少 sk- 密钥：① 执行 gateway-agent setup（首次配置引导：问一次网关地址与密钥，直接可用）；'
+  + '② 或 gateway-agent config set key sk-xxx / 在任务页·聊天页「设置」里填（都存 credentials.json，仅本用户可读）；'
   + '③ 或 --key sk-xxx、环境变量 SK / GATEWAY_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY，或在 .env 中写 GATEWAY_KEY=sk-xxx';
 
 /**
@@ -44,12 +45,21 @@ export function numArg(v) {
  * @returns {{key:string, baseUrl:string, model:string, workDir:string,
  *            temperature:number|undefined, maxTokens:number|undefined, system:string|undefined}}
  */
-export function resolveConfig(args = {}, { defaultModel = '', defaultMaxTokens, env = process.env } = {}) {
+export function resolveConfig(args = {}, { defaultModel = '', defaultMaxTokens, env = process.env, file = settingsFilePath(env) } = {}) {
   const maxTokens = numArg(args['max-tokens']) ?? defaultMaxTokens;
   // 密钥走 lib/secrets.js：`--key` > 环境变量 / `.env` > credentials.json。
   // 命令行必须认那个文件，否则「在界面里配一次就能用」对 CLI 入口是句空话
   // （界面与 config set key 写的都是它）。来源字段一并带出来，横幅才能说清「谁给的」。
   const secret = resolveSecretKey({ args, env });
+  // 网关地址与模型走 lib/settings.js 的**四层**优先级：--flag > 环境变量/.env > config.json > 内置默认。
+  //
+  // 这一段曾经用的是 lib/common.js 的 resolveBaseUrl —— 它只认 flag 与环境变量，**不读 config.json**。
+  // 后果是 `gateway-agent setup` 与 `config set baseUrl` 写进配置文件的地址，命令行根本不认：
+  // 网页/设置面板显示 192.168.x.x，命令行却仍旧连内置默认的 127.0.0.1:9000（模型同理）。
+  // 网页侧一直走 resolveSettings，所以「页面是对的、命令行是错的」——两条链必须合成一条。
+  const settings = resolveSettings({ file, env, args });
+  // 模型：配置文件里**真写了**才用它，否则保留各入口自己的 defaultModel（cli-anthropic 等默认值不同）
+  const modelFromFile = settings.sources.model === 'default' ? '' : strArg(settings.values.model);
   return {
     key: secret.key,
     keySource: secret.source,
@@ -57,9 +67,12 @@ export function resolveConfig(args = {}, { defaultModel = '', defaultMaxTokens,
     // 整个来源对象一并带出：横幅要 `secretSourceText(cfg.secret)` 才能说清
     // 「环境变量 GATEWAY_KEY（来自 .env：…）」这类细节
     secret,
-    baseUrl: resolveBaseUrl(args, env),
-    // 顺序：--model > GATEWAY_MODEL > 该入口的默认模型
-    model: strArg(args.model) || strArg(env.GATEWAY_MODEL) || defaultModel,
+    // 与 resolveBaseUrl / Web 侧同一口径：去掉尾部斜杠
+    baseUrl: String(settings.values.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, ''),
+    // 顺序：--model > GATEWAY_MODEL > config.json > 该入口的默认模型
+    model: strArg(args.model) || strArg(env.GATEWAY_MODEL) || modelFromFile || defaultModel,
+    // 整份解析结果：调用方要 `settingSourceText(settings, 'baseUrl')` 这类「谁给的」信息
+    settings,
     workDir: strArg(args.cwd) || strArg(args['work-dir']) || '',
     temperature: numArg(args.temperature),
     maxTokens: Number.isFinite(maxTokens) && maxTokens > 0 ? maxTokens : undefined,

package/lib/hub.js

@@ -22,7 +22,6 @@ import {
   parseArgs,
   strArg,
   resolveKey,
-  resolveBaseUrl,
   resolvePort,
   sendJson,
   readBody,
@@ -1345,8 +1344,13 @@ export function runHub(argv, { entry = 'web' } = {}) {
   const settingsFile = settingsFilePath();
   const settings = resolveSettings({ file: settingsFile, env: process.env, args });
   for (const w of settings.warnings) console.warn(`[警告] ${w}`);
-  const baseUrl = resolveBaseUrl(args);
-  const model = strArg(args.model) || DEFAULT_MODEL;
+  // 网关地址与模型：事实来源是 lib/settings.js 的四层优先级（flag > 环境变量/.env > config.json > 内置默认）。
+  // 这里曾经用 resolveBaseUrl（只认 flag/env），于是**横幅把 config.json 里的地址显示成内置默认**，
+  // 而 applySettings 之后的运行态用的却是配置文件里的值 —— 横幅与事实打架，用户以为配置没生效。
+  // 现在两边同源：横幅打印的就是运行态那个值。
+  const baseUrl = String(settings.values.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const modelFromFile = settings.sources.model === 'default' ? '' : strArg(settings.values.model);
+  const model = strArg(args.model) || strArg(process.env.GATEWAY_MODEL) || modelFromFile || DEFAULT_MODEL;
   // 老的两个服务各用各的环境变量名，这里都认
   const port =
     resolvePort(args, process.env, 'WEB_PORT', null) ??

package/lib/launcher.js

@@ -0,0 +1,141 @@
+/**
+ * 裸命令启动器（`llm-api-gateway-cli` 不带参数时）
+ *
+ * 用户的要求很直接：**每次敲这个命令，应该由它来问「你要对话还是任务、要在命令行还是网页」**，
+ * 而不是默默替他选一个（今天的实现是「无参数 + TTY → 直接进 REPL」）。
+ *
+ * 为什么拆成「纯映射 + 注入动作」两层：
+ *   · `resolvePlan()` 是纯函数，四条路径的映射可以被测试逐条钉住；
+ *   · `runLauncher()` 只管问与打印，真去起服务还是进 REPL 由调用方注入 ——
+ *     测试里换成假的，就永远不会在测试机上偷偷起一个 3100。
+ *
+ * 兼容性红线：**只有「无参数 + 交互终端」才进这里**。`-p`（单轮）、`-i`（直接进对话）、
+ * 管道输入（`echo … | llm-api-gateway-cli`）三条老路径一律不弹菜单。
+ */
+
+import { strArg } from './common.js';
+
+/** 本机 Web UI 的默认端口。事实来源是 `lib/hub.js` 的 `DEFAULT_PORT`，测试会交叉断言两者一致 */
+export const WEB_PORT = 3100;
+
+export const TOPICS = [
+  { value: 'chat', label: '对话', desc: '纯聊天，不碰你的文件' },
+  { value: 'task', label: '任务', desc: '在指定目录里真读写文件，每次写入前先问你' },
+];
+
+export const SURFACES = [
+  { value: 'cli', label: '命令行窗口', desc: '就在这个终端里继续' },
+  { value: 'web', label: '网页 UI', desc: `起本机网页 http://127.0.0.1:${WEB_PORT}（聊天页 / 任务页）` },
+];
+
+/**
+ * 纯函数：两个选择 → 要执行的动作。
+ *
+ * | topic | surface | 结果 |
+ * | --- | --- | --- |
+ * | chat | cli | 命令行对话（REPL） |
+ * | task | cli | 先问工作目录，再进任务态（REPL，写入需批准） |
+ * | chat | web | 起服务，落到 `/` |
+ * | task | web | 起服务，落到 `/task` |
+ */
+export function resolvePlan({ topic, surface, port = WEB_PORT } = {}) {
+  const t = topic === 'task' ? 'task' : 'chat';
+  const s = surface === 'web' ? 'web' : 'cli';
+  if (s === 'web') {
+    return {
+      kind: 'web',
+      topic: t,
+      entry: t === 'task' ? 'task' : 'web',
+      path: t === 'task' ? '/task' : '/',
+      url: `http://127.0.0.1:${port}${t === 'task' ? '/task' : '/'}`,
+    };
+  }
+  return { kind: 'cli', topic: t, interactive: true, needWorkDir: t === 'task' };
+}
+
+/** 把一行输入解析成选项值：支持序号 `1`/`2`、空回车（取默认）、也支持直接写 `task` / `web` */
+export function pickOption(answer, list, defaultIndex = 0) {
+  const s = strArg(answer).toLowerCase();
+  if (!s) return list[defaultIndex]?.value ?? '';
+  const n = Number(s);
+  if (Number.isInteger(n) && n >= 1 && n <= list.length) return list[n - 1].value;
+  return list.find((o) => o.value === s)?.value ?? '';
+}
+
+/** 菜单正文 */
+export function menuText(title, list) {
+  const lines = list.map((o, i) => `  ${i + 1}) ${o.label.padEnd(6, '　')} ${o.desc}`);
+  return `${title}\n${lines.join('\n')}\n`;
+}
+
+export function launcherIntro() {
+  return (
+    'LLM API Gateway · 启动器\n' +
+    '两个问题选完就进入对应形态（直接回车 = 选 1）。\n' +
+    '想跳过这个菜单：-p "你的问题"（单轮）· -i（直接进命令行对话）· gateway-task（直接起网页）\n\n'
+  );
+}
+
+/** 问一次选择题；问不出合法值返回 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 value = pickOption(answer, list, 0);
+    if (value) return value;
+    log(`  ✗ 请输入 1-${list.length}${list.map((o) => ` / ${o.value}`).join('')}\n`);
+  }
+  return null;
+}
+
+/**
+ * 跑一次启动器。
+ *
+ * @param {object} o
+ * @param {(label:string, opts?:{default?:string, mask?:boolean}) => Promise<string>} o.ask
+ * @param {(s:string)=>void} [o.log]
+ * @param {(plan:object)=>Promise<{code:number}>} [o.startWeb]  真去起服务（注入，便于测试）
+ * @param {(plan:object)=>Promise<{code:number}>} [o.startCli]  真去进 REPL
+ * @param {string} [o.cwd]  任务工作目录的默认值（默认 process.cwd()）
+ * @returns {Promise<{ok:boolean, code:number, plan?:object, error?:string}>}
+ */
+export async function runLauncher({
+  ask = null,
+  log = () => {},
+  startWeb = null,
+  startCli = null,
+  cwd = process.cwd(),
+  port = WEB_PORT,
+  attempts = 3,
+} = {}) {
+  if (!ask) return { ok: false, code: 1, error: '当前不是交互终端：请直接用参数表达意图（-p / -i / gateway-task）。' };
+
+  log(launcherIntro());
+
+  const topic = await askChoice(ask, '你要做什么？', TOPICS, log, attempts);
+  if (!topic) return { ok: false, code: 1, error: '没有选出「做什么」，已退出（没有改动任何配置）。' };
+
+  const surface = await askChoice(ask, '要在哪里跑？', SURFACES, log, attempts);
+  if (!surface) return { ok: false, code: 1, error: '没有选出「在哪里跑」，已退出（没有改动任何配置）。' };
+
+  const plan = resolvePlan({ topic, surface, port });
+
+  // 任务 + 命令行：还得知道在哪个目录干活（这是任务态与纯对话唯一的区别）
+  if (plan.kind === 'cli' && plan.needWorkDir) {
+    const answer = await ask(`任务工作目录 [${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。' };
+    return { ok: true, ...(await startWeb(plan)), plan };
+  }
+
+  log(
+    `\n→ 命令行${plan.topic === 'task' ? `任务态（工作目录 ${plan.workDir}，写入前会问你）` : '对话'}\n` +
+      '  退出：/exit 或 Ctrl+C\n\n',
+  );
+  if (!startCli) return { ok: false, code: 1, plan, error: '内部错误：没有注入 startCli。' };
+  return { ok: true, ...(await startCli(plan)), plan };
+}

package/lib/setup.js

@@ -0,0 +1,260 @@
+/**
+ * 首次配置引导（`gateway-agent setup`）
+ *
+ * 为什么必须有这一步：在这之前，「第一次用」的唯一出口是**报错** —— 缺密钥就退 1，
+ * 让用户自己去文档里拼 `config set` / 环境变量 / `.env`；网关地址更是提都没提。
+ * 别的 CLI 工具装完都会问一次「服务地址是什么、凭据是什么」，本项目缺的正是这一步。
+ *
+ * 三条设计约束：
+ *   1. **交互与业务分离**：问题由调用方注入（`ask`），所以测试能喂固定答案，不需要真终端；
+ *   2. **非交互可配**：`setup --base-url … --key …` 一条命令配完，CI 里能跑；
+ *   3. **不另立一套读写**：地址走 `writeSettings`（→ `config.json`），密钥走 `writeSecret`
+ *      （→ `credentials.json`），校验口径与网页设置面板、`config set` 完全同一份。
+ *
+ * 「默认值」的处理是这套东西的关键：默认值**只在提问时以 `[默认]` 形式给出**，
+ * 用户回车才采用、也可以直接覆盖 —— 不做「悄悄用默认值跑起来」这件事。
+ */
+
+import { strArg } from './common.js';
+import { settingsFilePath, writeSettings, resolveSettings } from './settings.js';
+import { secretFilePath, writeSecret, resolveSecretKey, KEY_SHAPE, SECRET_FILE_NAME } from './secrets.js';
+
+/** 地址校验：与 settings 白名单同一口径（lib/settings.js:65） */
+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:// 开头';
+  return '';
+}
+
+/** 校验密钥：与 lib/secrets.js 的 KEY_SHAPE 同一口径 */
+export function validateKey(v) {
+  const s = strArg(v);
+  if (!s) return '网关密钥不能为空';
+  if (!KEY_SHAPE.test(s)) {
+    return `密钥形状不对：需要以 sk- 开头且长度足够（收到 ${s.length} 个字符，前缀 ${s.slice(0, 3)}）`;
+  }
+  return '';
+}
+
+/**
+ * 这台机器是不是「全新、还没配过」。
+ *
+ * 判据是「四条来源一条都没有」：环境变量 / `.env`（会被 loadDotEnv 灌进 env）、
+ * `config.json`、`credentials.json`。任何一条有值就说明用户配过，不该再拿向导烦他。
+ * 与启动横幅那句「这台机器还没有任何配置」用的是同一套事实。
+ */
+export function isFreshMachine({ env = process.env, file = settingsFilePath(env), secretFile = secretFilePath(env) } = {}) {
+  if (resolveSecretKey({ env, file: secretFile }).key) return false;
+  if (!strArg(env.GATEWAY_BASE_URL) && !resolveSettings({ file, env }).exists) return true;
+  return false;
+}
+
+/** 脱敏：只留前 6 后 4，给向导的回执用（`config get key` 也是这个口径） */
+export function maskKeyish(key) {
+  const s = strArg(key);
+  if (s.length <= 10) return s ? `${s.slice(0, 3)}****` : '';
+  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');
+}
+
+/**
+ * 跑一次设置向导。
+ *
+ * @param {object} o
+ * @param {(label:string, opts?:{default?:string, mask?:boolean}) => Promise<string>} o.ask
+ *        读一行；**返回原始输入**（可能是空串），默认值由本函数套用 —— 提问方不承担校验
+ * @param {(s:string) => void} [o.log]   正文输出（默认丢弃，调用方传 process.stdout.write）
+ * @param {object} [o.args]              `setup` 的参数（`--base-url` / `--key` 给了就不问）
+ * @param {number} [o.attempts]          单个问题的最多重问次数
+ * @returns {Promise<{ok:boolean, code:number, baseUrl?:string, key?:string,
+ *                    file?:string, secretFile?:string, error?:string}>}
+ */
+export async function runSetup({
+  ask = null,
+  log = () => {},
+  args = {},
+  env = process.env,
+  file = settingsFilePath(env),
+  secretFile = secretFilePath(env),
+  attempts = 3,
+} = {}) {
+  const resolved = resolveSettings({ file, env });
+  const currentBase = strArg(args['base-url']) || strArg(resolved.values.baseUrl) || 'http://127.0.0.1:9000';
+  const givenBase = strArg(args['base-url']);
+  const givenKey = strArg(args.key);
+
+  // 参数已经给全 → 纯写盘，一个问题都不问（CI / 脚本路径）
+  const needAsk = !(givenBase && givenKey);
+  if (needAsk && !ask) {
+    return {
+      ok: false,
+      code: 1,
+      error: '当前不是交互终端：请用 `gateway-agent setup --base-url <地址> --key sk-xxx` 一次配完。',
+    };
+  }
+
+  log(setupIntro({ baseUrlDefault: currentBase }));
+
+  /* ---------- 1) 网关地址 ---------- */
+  let baseUrl = givenBase;
+  if (!baseUrl) {
+    for (let i = 0; i < attempts; i++) {
+      const answer = await ask('网关地址', { default: currentBase });
+      const value = strArg(answer) || currentBase; // 回车 = 采用方括号里的默认值
+      const err = validateBaseUrl(value);
+      if (!err) {
+        baseUrl = value;
+        break;
+      }
+      log(`  ✗ ${err}\n`);
+    }
+    if (!baseUrl) return { ok: false, code: 1, error: '网关地址没填对，已取消（没有写入任何文件）。' };
+  }
+
+  /* ---------- 2) 网关密钥 ---------- */
+  let key = givenKey;
+  if (!key) {
+    for (let i = 0; i < attempts; i++) {
+      const answer = await ask('网关密钥', { mask: true });
+      const err = validateKey(answer);
+      if (!err) {
+        key = strArg(answer);
+        break;
+      }
+      log(`  ✗ ${err}\n`);
+    }
+    if (!key) return { ok: false, code: 1, error: '网关密钥没填对，已取消（没有写入任何文件）。' };
+  }
+
+  /* ---------- 3) 落盘：复用既有实现，原子写与权限都在里面 ---------- */
+  let wrote;
+  try {
+    // 地址去掉尾部斜杠，与 resolveBaseUrl / Web 侧同一口径
+    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` : ''),
+    );
+  } catch (e) {
+    return { ok: false, code: 1, error: `写入配置失败：${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',
+  );
+
+  return { ok: true, code: 0, baseUrl: baseUrl.replace(/\/+$/, ''), key, file: resolveSettings({ file, env }).file, secretFile: wrote.file, secretName: SECRET_FILE_NAME };
+}
+
+/** `setup --help` 的正文 */
+export function setupHelp() {
+  return `用法：gateway-agent setup [--base-url <地址>] [--key sk-xxx]
+
+首次配置引导：问一次「网关地址」和「网关密钥」，写进本机的两个文件 ——
+  网关地址 → ${settingsFilePath()}
+  网关密钥 → ${secretFilePath()}（不进 config.json）
+
+  --base-url <地址>   直接给定，不再提问（必须 http:// 或 https:// 开头）
+  --key sk-xxx        直接给定，不再提问
+  两个都给 → 完全不问，适合脚本 / CI
+  一个都不给 → 进入交互问答（默认值以 [方括号] 给出，回车即采用）
+
+等价做法（任选，读写的是同一份配置）：
+  网页「设置」面板（任务页「其他配置」里地址与密钥都有）
+  gateway-agent config set baseUrl <地址> / config set key sk-xxx
+  环境变量 GATEWAY_BASE_URL / SK / GATEWAY_KEY，或当前目录的 .env
+`;
+}
+
+/**
+ * 造一个真终端问答器（TTY 专用）。
+ *
+ * 不用 readline 的私有 `_writeToOutput` 做掩码：那种写法随 Node 版本变，
+ * 这里直接上 raw 模式自己回显 —— 普通问题回显字符，密钥只回 `*`。
+ * 非 TTY 返回 null，调用方据此走 `--base-url/--key` 的非交互路径。
+ *
+ * @returns {null | ((label:string, opts?:{default?:string, mask?:boolean}) => Promise<string>)}
+ */
+export function createTerminalAsk({ input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) return null;
+
+  function readLine(prompt, mask) {
+    return new Promise((resolve) => {
+      output.write(prompt);
+      const wasRaw = input.isRaw === true;
+      let text = '';
+      const finish = () => {
+        input.removeListener('data', onData);
+        try {
+          input.setRawMode(wasRaw);
+        } catch {
+          /* 平台不支持就保持原状 */
+        }
+        input.pause();
+      };
+      const onData = (chunk) => {
+        for (const ch of String(chunk)) {
+          if (ch === '\r' || ch === '\n') {
+            finish();
+            output.write('\n');
+            resolve(text);
+            return;
+          }
+          if (ch === '\u0003') {
+            // Ctrl+C：别把终端留在 raw 模式里
+            finish();
+            output.write('\n');
+            process.exit(130);
+          }
+          if (ch === '\u007f' || ch === '\b') {
+            if (text) {
+              text = text.slice(0, -1);
+              output.write('\b \b');
+            }
+            continue;
+          }
+          if (ch < ' ') continue; // 其余控制字符（方向键等）忽略
+          text += ch;
+          output.write(mask ? '*' : ch);
+        }
+      };
+      try {
+        input.setRawMode(true);
+      } catch {
+        /* 某些环境（如 Windows 的旧终端）可能拒绝，退化成带回显 */
+      }
+      input.setEncoding('utf8');
+      input.resume();
+      input.on('data', onData);
+    });
+  }
+
+  return (label, { default: def = '', mask = false } = {}) => {
+    const suffix = def ? ` [${def}]` : '';
+    const hint = mask ? '（sk- 开头，输入不回显）' : '';
+    return readLine(`${label}${suffix}${hint}：`, mask);
+  };
+}

package/package.json

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

package/public/app.js

@@ -61,6 +61,9 @@ const dom = {
   setHistoryChars: document.getElementById('set-history-chars'),
   setKey: document.getElementById('set-key'),
   keyHint: document.getElementById('key-hint'),
+  setBaseUrl: document.getElementById('set-base-url'),
+  baseHint: document.getElementById('base-hint'),
+  btnSaveBase: document.getElementById('btn-save-base'),
   btnSaveKey: document.getElementById('btn-save-key'),
   btnRefreshModels: document.getElementById('btn-refresh-models'),
   btnReset: document.getElementById('btn-reset'),
@@ -849,6 +852,10 @@ async function loadConfig() {
     const resp = await fetch('/api/config');
     state.config = await resp.json();
     setInfo(dom.infoBase, state.config.baseUrl);
+    // 地址是可改项（下一行的 infoBase 只是只读回显）：回填输入框，但别踩用户正在输入的内容
+    if (dom.setBaseUrl && document.activeElement !== dom.setBaseUrl) {
+      dom.setBaseUrl.value = state.config.baseUrl || '';
+    }
     setInfo(dom.infoKey, state.config.hasKey
       ? `${state.config.keyMask}${state.config.keySourceText ? ` · ${state.config.keySourceText}` : ''}`
       : '未配置');
@@ -876,6 +883,38 @@ async function loadConfig() {
   }
 }
 
+/**
+ * 保存网关地址。
+ *
+ * 这一页的设置项大多存在浏览器里，地址和密钥是例外：它们决定**服务端**往哪发请求、用什么凭据，
+ * 所以必须走 `PUT /api/settings`（地址 → config.json，密钥 → credentials.json）。
+ * 任务页「设置 → 其他配置 → 网关地址」走的是同一个接口、同一份文件，两处不会各存一处。
+ */
+async function saveBaseUrl() {
+  const value = String(dom.setBaseUrl.value || '').trim();
+  if (!value) {
+    setStatus('网关地址不能为空（默认 http://127.0.0.1:9000）', 'err');
+    return;
+  }
+  dom.btnSaveBase.disabled = true;
+  try {
+    const resp = await fetch('/api/settings', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ values: { baseUrl: value } }),
+    });
+    const data = await resp.json().catch(() => ({}));
+    if (!resp.ok) throw new Error(data.error || `HTTP ${resp.status}`);
+    await loadConfig();
+    await loadModels();
+    setStatus(data.note || `网关地址已保存：${state.config?.baseUrl || value}`, 'ok');
+  } catch (e) {
+    setStatus(`保存网关地址失败：${e.message}`, 'err');
+  } finally {
+    dom.btnSaveBase.disabled = false;
+  }
+}
+
 /**
  * 保存密钥。
  *
@@ -1022,6 +1061,18 @@ function init() {
   dom.setSystem.addEventListener('blur', readSettingsFromUI);
 
   dom.btnRefreshModels.addEventListener('click', loadModels);
+  // 网关地址：和密钥一样属于**服务端配置**（它决定服务端往哪发请求，写进 config.json），
+  // 所以不能像这页其它项那样存浏览器本地 —— 走服务端的 PUT /api/settings，
+  // 与任务页「设置 → 其他配置 → 网关地址」是同一条路、同一份文件。
+  if (dom.btnSaveBase) {
+    dom.btnSaveBase.addEventListener('click', saveBaseUrl);
+    dom.setBaseUrl.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') {
+        e.preventDefault();
+        saveBaseUrl();
+      }
+    });
+  }
   // 密钥：唯一的写入路径是服务端的 PUT /api/settings（它写 credentials.json，不写 config.json）。
   // 这页的设置项大多存在浏览器里，密钥是例外 —— 它是服务端的事，所以单独一个「保存密钥」按钮。
   dom.btnSaveKey.addEventListener('click', saveKey);

package/public/index.html

@@ -110,6 +110,13 @@
         <textarea id="set-system" rows="4" placeholder="留空则不发送 system 消息"></textarea>
       </label>
 
+      <label class="field">
+        <span>网关地址</span>
+        <input id="set-base-url" type="text" autocomplete="off" spellcheck="false"
+               placeholder="http://127.0.0.1:9000" />
+        <small id="base-hint">http:// 或 https:// 开头。与「网关密钥」一样属于服务端配置（写 config.json，不进浏览器本地），改完立即生效。</small>
+      </label>
+
       <label class="field">
         <span>网关密钥</span>
         <input id="set-key" type="password" autocomplete="off" spellcheck="false"
@@ -145,6 +152,7 @@
       </label>
 
       <div class="settings-actions">
+        <button class="btn ghost" id="btn-save-base" type="button">保存地址</button>
         <button class="btn ghost" id="btn-save-key" type="button">保存密钥</button>
         <button class="btn ghost" id="btn-refresh-models" type="button">刷新模型</button>
         <button class="btn ghost" id="btn-reset" type="button">恢复默认</button>

package/public/manual.html

@@ -75,6 +75,19 @@
         <b>注意：装完还差一步「配密钥」</b> —— 但这一步<b>不用手写 <code>.env</code></b>：起服务后在界面「设置」里填一次，
         或者 <code>gateway-agent config set key sk-xxx</code>。没配之前页面能打开，只是发消息会被提示去配密钥（见下面「首次配置」）。
       </p>
+      <p class="manual-note">
+        <b>装完先做三件事（都可以让命令自己引导）</b>：
+        ① <b>配一次</b>：<code>gateway-agent setup</code> 会问「网关地址」和「网关密钥」并写进本机
+        （想一步到位就 <code>gateway-agent setup --base-url http://127.0.0.1:9000 --key sk-xxx</code>；
+        <b>全新机器首次运行会自动进入这一步</b>，不再只丢一句「缺少密钥」）。
+        ② <b>选做什么、在哪跑</b>：<b>裸敲</b> <code>llm-api-gateway-cli</code>（或 <code>gateway-agent</code>）会先问
+        「① 对话 / ② 任务」，再问「① 命令行窗口 / ② 网页 UI」，选完直接进入对应形态 —— 不替你默认。
+        ③ 只有选了「网页 UI」才会起服务；<b>起服务后要自己用浏览器</b>打开
+        <code>http://127.0.0.1:3100/</code>（聊天）或 <code>/task</code>（任务），
+        而<b>这一页手册本身就是 3100 上的 <code>/manual</code></b>，也要服务起着才看得到。
+        网关地址与密钥在任务页「设置 → 其他配置」里也能改；命令行是 <code>gateway-agent config set baseUrl|key …</code>。
+        想跳过启动器：<code>-p "问题"</code>（单轮）· <code>-i</code>（直接进对话）· <code>gateway-task</code>（直接起网页）。
+      </p>
       <p>
         <b>前置条件只有一个：Node.js ≥ 18</b>（用 <code>node -v</code> 自检）。脚本<b>不会替你装 Node</b> ——
         缺失或版本过低时它明确报错并停下，不动你的系统运行时。
@@ -159,9 +172,18 @@ $env:LLM_GATEWAY_INSTALL_BASE = 'https://your-mirror.example.com'; irm .../insta
       </p>
       <ol>
         <li>
-          <b>路线一（推荐）：起服务 → 在界面里填</b>
+          <b>路线零（推荐，装完第一步）：<code>gateway-agent setup</code></b>
+          <div class="code-block"><code>gateway-agent setup                                  # 交互问答：先问网关地址，再问密钥（不回显）
+gateway-agent setup --base-url http://127.0.0.1:9000 --key sk-xxx   # 两个都给就不问，适合脚本 / CI</code></div>
+          地址写进 <code>config.json</code>、密钥写进 <code>credentials.json</code>，与界面 / <code>config set</code> 是同一份。
+          默认值以 <code>[方括号]</code> 形式给出，<b>回车才采用</b>，也可以直接改；填错会重问，连错三次则<b>一个文件都不写</b>。
+          全新机器首次运行（无 config.json / credentials.json / 环境变量 / <code>.env</code>）会自动进入这一步；
+          <b>非交互终端（管道、CI）不会触发</b>，仍按老样子报错退出。
+        </li>
+        <li>
+          <b>路线一：起服务 → 在界面里填</b>
           <div class="code-block"><code>gateway-web          # 或 gateway-task，等价于 node server.js / node task-server.js
-# 打开 http://127.0.0.1:3100/task → 右上「设置」→「网关密钥」→ 粘贴 sk-xxx → 回车/保存</code></div>
+# 打开 http://127.0.0.1:3100/task → 右上「设置」→「其他配置」→ 网关地址 / 网关密钥</code></div>
           没有密钥时启动横幅会打印「密钥 未配置」，并给出三种填法；页面的信息行显示「未配置」，发消息会被挡下并提示你打开设置
           （聊天页与任务页都有这个输入框，写的是同一个文件）。<b>保存后立即生效，不用重启服务。</b>
         </li>
@@ -237,9 +259,15 @@ gateway-agent config set mode auto          # 新任务的默认审批模式</co
         </li>
       </ol>
       <p class="manual-note">
-        卸载：删掉安装目录（<code>rm -rf ~/.llm-api-gateway</code>，Windows 删 <code>$HOME\.llm-api-gateway</code>），
+        <b>卸载：按你的安装路线选一条。</b><b>npm 全局安装</b>的用
+        <code>npm uninstall -g llm-api-gateway-cli</code>（<b><code>-g</code> 不能少</b>，少了是去当前目录的
+        <code>node_modules</code> 里找它）—— 包目录与 <code>gateway-agent</code> / <code>gateway-web</code> /
+        <code>gateway-task</code> / <code>llm-api-gateway-cli</code> 等命令入口会一起删掉；
+        验一下干不干净：<code>where gateway-agent</code>（POSIX：<code>which gateway-agent</code>）报找不到就是干净了。
+        <b>脚本安装</b>的则删掉安装目录（<code>rm -rf ~/.llm-api-gateway</code>，Windows 删 <code>$HOME\.llm-api-gateway</code>），
         再把写进 shell 启动文件 / 用户 PATH 的那一行删掉。数据（任务与配置，在 <code>~/.llm-api-gateway-cli</code>）
-        与安装目录是两回事，卸载不会连带删数据。
+        与安装目录是两回事，卸载不会连带删数据 —— 想连密钥与任务一起清掉，再删那个目录
+        （<code>credentials.json</code> 里有你的 <code>sk-</code> 密钥，删掉就要重新配一次）。
       </p>
       <p class="manual-note">
         更细的说明（换镜像、源码安装、CI 产物）见仓库