llm-api-gateway-cli 1.0.0 → 1.0.1

package/README.md

@@ -37,7 +37,7 @@ npm install        # 安装 openai 与 @anthropic-ai/sdk
 
 装完就能在**任意目录**直接用 `gateway-agent`，密钥不需要手写 `.env`：起服务后在页面「设置」里填一次（或 `gateway-agent config set key sk-xxx`），存进 `~/.llm-api-gateway-cli/credentials.json`（**不进 `config.json`**）；也仍然可以用环境变量 / `.env` / `--key`，那三层优先级更高。
 
-> **⚠️ 装完还差一步：配密钥**（不用手写 `.env`）。`gateway-web` / `gateway-task` **没有密钥也能起**（页面照常打得开，启动横幅写「密钥 未配置」），在页面「设置 → 网关密钥」里填一次即可，保存后立即生效、不用重启；命令行也可 `gateway-agent config set key sk-xxx`。只有一次性命令行 agent（`gateway-agent -p "…"`）没有界面可交互，缺密钥会**直接报错退出**。想用环境变量 / `.env` 也行（优先级更高）：`.env` 的加载顺序是**①安装目录 → ②当前工作目录**，npm 全局安装的包目录里只有 `.env.example`，所以要放在**你运行命令的那个目录**（服务在**启动那一刻**读）。网关不在默认地址（`http://127.0.0.1:9000`）或想固定模型，用 `gateway-agent config set baseUrl|model …`（也能在设置面板里改）。完整步骤见手册页第一节「安装与启动 → 首次配置」。
+> **⚠️ 装完还差一步：配密钥**（不用手写 `.env`）。`gateway-web` / `gateway-task` **没有密钥也能起**（页面照常打得开，启动横幅写「密钥 未配置」），在页面「设置 → 网关密钥」里填一次即可，保存后立即生效、不用重启；命令行也可 `gateway-agent config set key sk-xxx`。**四个命令行入口也读这个文件**，所以配一次 Web 与命令行都认。只有一次性命令行 agent（`gateway-agent -p "…"`）没有界面可交互，缺密钥会**直接报错退出**（横幅会先告诉你当前的网关/模型及其来源，以及「那是内置默认、不是配好了」）。想用环境变量 / `.env` 也行（优先级更高）：`.env` 的加载顺序是**①安装目录 → ②当前工作目录**，npm 全局安装的包目录里只有 `.env.example`，所以要放在**你运行命令的那个目录**（服务在**启动那一刻**读）。网关不在默认地址（`http://127.0.0.1:9000`）或想固定模型，用 `gateway-agent config set baseUrl|model …`（也能在设置面板里改）。完整步骤见手册页第一节「安装与启动 → 首次配置」。
 
 > 不想翻文档也行：起服务后打开 **[操作手册页 `/manual`](http://127.0.0.1:3100/manual)**，第一节就是「安装与启动」—— 三条路线、参数表、换镜像、**首次配置（界面 / 命令行 / 环境变量三种给密钥方式、密钥存哪、网关地址与模型）**、启动自检与卸载，命令都是可复制的。
 
@@ -761,11 +761,14 @@ npm run test:all  # 先离线再联网
 | `tests/task-session.test.mjs` | 任务会话（方案 C）与历史预算：工具结果跨轮活下来、纯工具轮不被丢、旧任务懒迁移（含**带 `args` 时还原成原生 `tool_calls`**）、同一任务并发 409、请求校验 400、旧格式兼容开关、删任务连带删会话、`/api/store` 汇报会话占用；`history.maxChars` 超预算时压正文留记录、改配置立刻生效、`readFileDigest` 清单注入与「已被外部修改」告警 |
 | `tests/settings.test.mjs` | 配置落盘：18 个键的默认值与往返、四层优先级与来源列、越界值/未知键（含模糊建议）、`config.json` 拒收密钥（改名夹带也拒）、`unset` 回默认、坏文件降级与拒绝覆盖、UI 状态键与 `config` 子命令（`list/get/set/unset/path`，含「被环境变量盖住」的警告）、`GET/PUT /api/settings` |
 | `tests/secrets.test.mjs` | 免 `.env` 的密钥配置：密钥文件路径（跟数据根走 / `LLM_GATEWAY_SECRET_FILE` 覆盖）、读写往返与覆盖、POSIX `0600` 与「权限被放松」告警、坏文件降级、优先级（`--key`/env > 文件）、`keyRow` 只回掩码、`config set/get/list/unset/path key` 的落点，以及**没有密钥也能起服务** + 接口回 409 `needsKey` + 界面 PUT 一次即生效/手工改文件刷新即生效 |
+| `tests/config-source.test.mjs` | **配置来源与首次使用引导**：`loadDotEnv` 记下「哪个变量由哪个 `.env` 提供」且真环境变量不算、来源文案四层（内置默认 / 启动参数 / 环境变量 + `.env` 路径 / 配置文件路径）、`summarizeConfigSources` 的「全默认 + 无 config.json = 全新机器」判定、密钥来源说到具体别名、**四个 CLI 也认 `credentials.json`**（本轮修掉的缺陷），以及 CLI/hub 横幅必须带来源、缺密钥时仍退 1 的源码契约 |
 
 ## 配置：住在磁盘上，CLI / Web / REPL 同一套
 
 **优先级一句话**：`--flag` > 环境变量 > `config.json` > 内置默认；密钥是唯一的例外 —— `--key` / 环境变量 / `.env` > `credentials.json`，而它**永远不进 `config.json`**。
 
+**启动横幅会告诉你每个值「从哪来」**（`（内置默认）` / `（启动参数 --model）` / `（环境变量 GATEWAY_MODEL（来自 .env：E:\proj\.env））` / `（配置文件 …\config.json）`），命令行 agent 的横幅还多一行脱敏密钥。这条不是装饰：`.env` 的查找顺序是**①安装目录 → ②当前工作目录**，所以**在别的项目目录里跑会读到那个目录的 `.env`** —— 横幅里那句 `来自 .env：<路径>` 就是用来破「我明明没配过，怎么已经有值了 / 怎么已经有密钥了」这个高频误会的。反过来，全新机器第一次跑会看到两个值都标「内置默认」并多一句「这台机器还没有任何配置」+ 三条填法：**有值不等于配过了**。四个命令行入口与两个 Web 入口读同一套配置（含 `credentials.json`）。
+
 配置文件的默认位置是 `~/.llm-api-gateway-cli/config.json`（Windows 也就是 `C:\Users\<你>\.llm-api-gateway-cli\config.json`；与任务、会话同一个数据根，整体想换地方用 `LLM_GATEWAY_DATA_DIR`），也可以用环境变量 `LLM_GATEWAY_CONFIG` 只把配置文件指到别处。文件不存在也没关系，第一次 `config set` 会自动建。
 
 ```bash

package/cli-agent.js

@@ -25,14 +25,15 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 
-import { loadDotEnv, parseArgs, DEFAULT_BASE_URL } from './lib/common.js';
+import { loadDotEnv, parseArgs, DEFAULT_BASE_URL, maskKey } from './lib/common.js';
 import { resolveConfig, numArg, fail, KEY_HINT } from './lib/config.js';
 import { checkWorkDir, setBashEnabled, availableTools } from './lib/tools.js';
 import { createSession, restoreSession, runTurn, resumePendingTurn, countTurns } from './lib/runner.js';
 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 { settingsFilePath } from './lib/settings.js';
+import { settingsFilePath, summarizeConfigSources } from './lib/settings.js';
+import { secretSourceText } from './lib/secrets.js';
 import { AGENT_LIMITS } from './lib/agent.js';
 import { MEMORY_FILES, readMemory } from './lib/memory.js';
 import { refreshMcpTools, mcpStatusText } from './lib/mcp.js';
@@ -364,10 +365,23 @@ async function main() {
   // bash 默认关闭：命令级权限不该默默打开
   setBashEnabled(Boolean(args['allow-bash']));
 
-  const { key, baseUrl, model, temperature, maxTokens } = resolveConfig(args, { defaultModel: DEFAULT_MODEL });
+  const bootCfg = resolveConfig(args, { defaultModel: DEFAULT_MODEL });
+  const { key, baseUrl, model, temperature, maxTokens } = bootCfg;
+  // 启动横幅必须能回答「这个值从哪来」：用户在新机器上第一次跑，看到 base/model 有值会以为
+  // 「已经配好了」，其实那可能只是**内置默认值**，也可能来自**当前目录的 .env**（别的项目的配置）。
+  const srcInfo = summarizeConfigSources({ env: process.env, args });
+  const srcOf = (k) => (srcInfo.rows[k] ? `（${srcInfo.rows[k].sourceText}）` : '');
+  const keySrcOf = key ? secretSourceText(bootCfg.secret) : '';
   // 模型轮次上限：与 Web 侧同名同义；非法值交给 resolveMaxSteps 回落到默认
   const maxSteps = numArg(args['max-steps']);
   if (!key) {
+    process.stderr.write(
+      `[gateway] 还没配密钥 · base=${baseUrl}${srcOf('baseUrl')} model=${model}${srcOf('model')}\n` +
+        (srcInfo.allDefault && !srcInfo.configExists
+          ? '          这台机器还没有任何配置（没找到 config.json / credentials.json / .env / 相关环境变量）：\n' +
+            '          上面那两个值是**内置默认**，不是「已经配好了」——配一次之后就一直用它。\n'
+          : ''),
+    );
     process.stderr.write(`[错误] ${KEY_HINT}\n`);
     process.exit(1);
   }
@@ -517,7 +531,10 @@ async function main() {
         : '按上述原因未向网关发出请求'}（CLI 本次不携带 MCP 工具）`
     : mcpStatusText();
   process.stderr.write(
-    `[gateway] 原生 Agent · base=${baseUrl} model=${model}\n` +
+    `[gateway] 原生 Agent · base=${baseUrl}${srcOf('baseUrl')} model=${model}${srcOf('model')}\n` +
+      // 密钥这一行上轮只做在 Web 横幅里，CLI 的横幅反倒不说密钥从哪来 —— 而「我没配过密钥，
+      // 它怎么跑起来了」正是最需要一句解释的情形（多半是当前目录的 .env 给的）
+      `          密钥 ${maskKey(key)}（${keySrcOf}）\n` +
       `          工作目录 ${workDir}\n` +
       `          工具 ${toolNames}${args['allow-bash'] ? '  [bash 已开启]' : ''}\n` +
       `          ${mcpLine}\n` +

package/lib/common.js

@@ -11,19 +11,40 @@ import path from 'node:path';
 export const DEFAULT_BASE_URL = 'http://127.0.0.1:9000';
 
 /**
- * 读取 .env（先脚本目录、再当前工作目录），不覆盖已存在的环境变量。
- * 用函数声明是为了能在模块顶层前置调用，让 GATEWAY_MODEL 等参与默认值计算。
+ * 「这个环境变量是哪个 .env 给的」。
+ *
+ * 只记**真正被 .env 写入**的那些：真环境变量本来就存在时 .env 不参与（下面的
+ * `!(m[1] in process.env)` 分支），也就不该被标成「来自 .env」。
+ * 有了它，配置来源才能说清「环境变量 GATEWAY_MODEL（来自 .env：E:\proj\.env）」，
+ * 而不是笼统一句「环境变量」—— 用户排查「我没配过怎么会有值」时，差别就在这。
  */
+const dotEnvOrigins = new Map();
+
+/** 读取 .env（先脚本目录、再当前工作目录），不覆盖已存在的环境变量。
+ *  返回值是**本次调用**真正写入的来源表，便于调用方/测试确认「谁被写进来了」。 */
 export function loadDotEnv(scriptDir) {
+  const files = [];
+  const origins = new Map();
   for (const file of [path.join(scriptDir, '.env'), path.join(process.cwd(), '.env')]) {
     if (!existsSync(file)) continue;
+    files.push(file);
     for (const raw of readFileSync(file, 'utf8').split(/\r?\n/)) {
       const m = raw.match(/^\s*([A-Za-z_][\w.-]*)\s*=\s*(.*)\s*$/);
       if (!m) continue;
       const value = m[2].replace(/^['"]|['"]$/g, '');
-      if (!(m[1] in process.env)) process.env[m[1]] = value;
+      if (!(m[1] in process.env)) {
+        process.env[m[1]] = value;
+        dotEnvOrigins.set(m[1], file);
+        origins.set(m[1], file);
+      }
     }
   }
+  return { files, origins };
+}
+
+/** 某个环境变量的 .env 出处；不是 .env 给的（没设 / 真环境变量）返回 '' */
+export function dotEnvOrigin(name) {
+  return name ? dotEnvOrigins.get(name) || '' : '';
 }
 
 /** 只接受真正的字符串参数值：值型选项缺值时会退化成布尔 true，必须挡掉 */

package/lib/config.js

@@ -8,12 +8,20 @@
  * 所有 CLI 都走 resolveConfig，保证问「密钥从哪来」只有一种答案。
  */
 
-import { resolveKey, resolveBaseUrl, strArg } from './common.js';
+import { resolveBaseUrl, strArg } from './common.js';
+import { resolveSecretKey } from './secrets.js';
 
-/** 缺密钥时的统一提示（各 CLI 文案一致，避免用户按提示改了还是不通） */
+/**
+ * 缺密钥时的统一提示（各 CLI 文案一致，避免用户按提示改了还是不通）。
+ *
+ * 三条路都必须是真的：界面 / `config set key` 写的是 `credentials.json`，而四个 CLI 现在
+ * 也读这个文件（下面的 resolveConfig 走 resolveSecretKey）—— 提示与行为对不上，
+ * 用户会按着提示配完发现还是报缺密钥。
+ */
 export const KEY_HINT =
-  '缺少 sk- 密钥：可在 Web 界面「设置」里填，或执行 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';
+  '缺少 sk- 密钥：① 在任务页/聊天页「设置」里填（存 credentials.json，仅本用户可读，命令行也认它）；'
+  + '② 或执行 gateway-agent config set key sk-xxx；'
+  + '③ 或 --key sk-xxx、环境变量 SK / GATEWAY_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY，或在 .env 中写 GATEWAY_KEY=sk-xxx';
 
 /**
  * 数字参数：非法值（NaN / 布尔 / 空串）一律返回 undefined。
@@ -38,8 +46,17 @@ export function numArg(v) {
  */
 export function resolveConfig(args = {}, { defaultModel = '', defaultMaxTokens, env = process.env } = {}) {
   const maxTokens = numArg(args['max-tokens']) ?? defaultMaxTokens;
+  // 密钥走 lib/secrets.js：`--key` > 环境变量 / `.env` > credentials.json。
+  // 命令行必须认那个文件，否则「在界面里配一次就能用」对 CLI 入口是句空话
+  // （界面与 config set key 写的都是它）。来源字段一并带出来，横幅才能说清「谁给的」。
+  const secret = resolveSecretKey({ args, env });
   return {
-    key: resolveKey(args, env),
+    key: secret.key,
+    keySource: secret.source,
+    keyFile: secret.file,
+    // 整个来源对象一并带出：横幅要 `secretSourceText(cfg.secret)` 才能说清
+    // 「环境变量 GATEWAY_KEY（来自 .env：…）」这类细节
+    secret,
     baseUrl: resolveBaseUrl(args, env),
     // 顺序：--model > GATEWAY_MODEL > 该入口的默认模型
     model: strArg(args.model) || strArg(env.GATEWAY_MODEL) || defaultModel,

package/lib/hub.js

@@ -78,6 +78,8 @@ import {
   isSecretKey,
   parseSettingValue,
   unknownKeyError,
+  settingSourceText,
+  summarizeConfigSources,
 } from './settings.js';
 import { commandRows } from './commands.js';
 import { estimateCost, formatCost } from './pricing.js';
@@ -1456,11 +1458,17 @@ export function runHub(argv, { entry = 'web' } = {}) {
     console.log('LLM API Gateway · 本地 Web UI');
     console.log(`  聊天   http://${host}:${port}/`);
     console.log(`  任务   http://${host}:${port}/task`);
-    console.log(`  网关   ${baseUrl}`);
-    console.log(`  模型   ${model}`);
+    // 网关 / 模型也要带来源：新机器上「有值」不等于「配过」——默认值、当前目录的 .env、
+    // config.json 三者长得很像，不说清来源就只能靠猜（与 CLI 横幅同一套文案）
+    console.log(`  网关   ${baseUrl}（${settingSourceText(settings, 'baseUrl')}）`);
+    console.log(`  模型   ${model}（${settingSourceText(settings, 'model')}）`);
     // 密钥一行要能回答「配没配、从哪来」——来源是环境时，credentials.json 不参与，这一点要说清
-    console.log(`  密钥   ${key ? `${maskKey(key)}（${secretSourceText(secret.source)}）` : '未配置'}`);
+    console.log(`  密钥   ${key ? `${maskKey(key)}（${secretSourceText(secret)}）` : '未配置'}`);
     if (!key) {
+      const srcInfo = summarizeConfigSources({ keys: ['baseUrl', 'model'], env: cfg.env, args });
+      if (srcInfo.allDefault && !srcInfo.configExists) {
+        console.log('         这台机器还没有任何配置：上面的网关与模型是**内置默认值**，不是「已经配好了」');
+      }
       console.log('         填法：页面「设置」里填（存 credentials.json，仅本用户可读）');
       console.log('               或 gateway-agent config set key sk-xxx；或环境变量 GATEWAY_KEY / --key');
     }

package/lib/secrets.js

@@ -22,7 +22,7 @@ import os from 'node:os';
 
 import { writeJsonAtomic } from './jsonstore.js';
 import { defaultStoreRoot } from './taskstore.js';
-import { resolveKey, strArg, maskKey } from './common.js';
+import { resolveKey, strArg, maskKey, dotEnvOrigin } from './common.js';
 
 /** 想单独把密钥文件放别处时用它（整体换数据根用 LLM_GATEWAY_DATA_DIR） */
 export const SECRET_ENV = 'LLM_GATEWAY_SECRET_FILE';
@@ -142,11 +142,14 @@ export function clearSecret({ file = secretFilePath() } = {}) {
 export function resolveSecretKey({ args = null, env = process.env, file = secretFilePath(env) } = {}) {
   const external = resolveKey(args, env);
   if (external) {
-    // 区分 --key 与其它：args.key 存在就是命令行显式给的
-    return { key: external, source: strArg(args?.key) ? 'flag' : 'env', file, warning: '' };
+    // 区分 --key 与其它：args.key 存在就是命令行显式给的。
+    // env 层再细分到「哪个别名」以及「是不是某个 .env 给的」——横幅要说清这个。
+    if (strArg(args?.key)) return { key: external, source: 'flag', envName: '', dotEnvFile: '', file, warning: '' };
+    const envName = KEY_ENV_NAMES.find((n) => strArg(env?.[n])) || '';
+    return { key: external, source: 'env', envName, dotEnvFile: envName ? dotEnvOrigin(envName) : '', file, warning: '' };
   }
   const read = readSecret({ file, env });
-  return { key: read.key, source: read.key ? 'file' : '', file, warning: read.warning };
+  return { key: read.key, source: read.key ? 'file' : '', envName: '', dotEnvFile: '', file, warning: read.warning };
 }
 
 export const SECRET_SOURCE_LABELS = {
@@ -155,9 +158,22 @@ export const SECRET_SOURCE_LABELS = {
   file: '密钥文件',
 };
 
-/** 人话来源：给启动横幅与 config list 用（`.env` 走的是 env 层，见 resolveSecretKey 注释） */
-export function secretSourceText(source) {
-  return SECRET_SOURCE_LABELS[source] || '未配置';
+/** 认的密钥环境变量别名（顺序即优先级，与 lib/common.js 的 resolveKey 一致） */
+const KEY_ENV_NAMES = ['SK', 'GATEWAY_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN'];
+
+/**
+ * 人话来源：给启动横幅与 config list 用（`.env` 走的是 env 层，见 resolveSecretKey 注释）。
+ *
+ * 第二参可以传 `{ envName, dotEnvFile }`（或整个 resolveSecretKey 的返回值），
+ * 这样「环境变量」能细到「环境变量 GATEWAY_KEY（来自 .env：E:\proj\.env）」——
+ * 用户排查「我没配过哪来的密钥」时靠的就是这一句。
+ */
+export function secretSourceText(source, detail = {}) {
+  const s = typeof source === 'object' && source ? source.source : source;
+  const d = typeof source === 'object' && source ? source : detail || {};
+  const base = SECRET_SOURCE_LABELS[s] || '未配置';
+  if (s !== 'env' || !d.envName) return base;
+  return d.dotEnvFile ? `${base} ${d.envName}（来自 .env：${d.dotEnvFile}）` : `${base} ${d.envName}`;
 }
 
 /**
@@ -190,8 +206,8 @@ export function keyRow({ env = process.env, file = secretFilePath(env), args = n
     mask: maskKey(resolved.key),
     file,
     fileMode: perms.mode,
-    // 来源是人话，页面直接显示；命令行同源
-    sourceText: secretSourceText(resolved.source),
+    // 来源是人话，页面直接显示；命令行同源（带别名与 .env 出处，见 secretSourceText）
+    sourceText: secretSourceText(resolved),
     warning: resolved.warning || perms.warning || '',
     fromFile,
   };

package/lib/settings.js

@@ -20,7 +20,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { readFileSync, mkdirSync } from 'node:fs';
 
-import { DEFAULT_BASE_URL } from './common.js';
+import { DEFAULT_BASE_URL, dotEnvOrigin } from './common.js';
 import { MODES, AGENT_LIMITS } from './agent.js';
 import { TTL_DAYS, MAX_TASKS, defaultStoreRoot } from './taskstore.js';
 import { TASK_SESSION_MAX_BYTES, HISTORY_MAX_CHARS, HISTORY_KEEP_RECENT_TURNS } from './tasksession.js';
@@ -399,6 +399,70 @@ export function resolveSettings({ file = settingsFilePath(), env = process.env,
   return { values, sources, warnings, file: read.file, exists: read.exists };
 }
 
+/** 四层优先级的展示名 */
+export const SOURCE_LABELS = {
+  flag: '启动参数',
+  env: '环境变量',
+  file: '配置文件',
+  default: '内置默认',
+};
+
+/**
+ * 把某一项的来源翻成**能直接打印**的一句话。
+ *
+ * 只写「环境变量」是不够的：用户最常卡住的正是「我没配过，这值哪来的」——
+ * 而 `GATEWAY_MODEL` 可能来自真环境变量，也可能来自**某个 .env 文件**
+ * （`.env` 的查找顺序是「安装目录 → 当前工作目录」，见 lib/common.js）。
+ * 所以这里把变量名与 .env 路径都写出来，一眼能看出是不是别的项目的配置漏进来了。
+ *
+ * 第三参 `originOf` 是「查 .env 出处」的函数（默认用全局记录的 `dotEnvOrigin`），
+ * 与 `resolveSettings({env, file})` 同一个思路：可注入，测试才能给出确定的环境。
+ */
+export function settingSourceText(resolved, key, originOf = dotEnvOrigin) {
+  const entry = SETTINGS_SCHEMA.find((e) => e.key === key) || {};
+  switch (resolved.sources[key]) {
+    case 'flag': {
+      // flag 里可能已经自带横线（`--base-url` / `-m/--model`），别再补一个变成 `----base-url`
+      const flag = entry.flag || key;
+      return `${SOURCE_LABELS.flag} ${flag.startsWith('-') ? flag : `--${flag}`}`;
+    }
+    case 'env': {
+      const name = entry.env || '';
+      const dot = name ? originOf(name) : '';
+      if (!name) return SOURCE_LABELS.env;
+      return dot ? `${SOURCE_LABELS.env} ${name}（来自 .env：${dot}）` : `${SOURCE_LABELS.env} ${name}`;
+    }
+    case 'file':
+      return `${SOURCE_LABELS.file} ${resolved.file}`;
+    default:
+      return SOURCE_LABELS.default;
+  }
+}
+
+/**
+ * 启动横幅与「首次使用」判定共用的摘要。
+ *
+ * `allDefault` 看的是**整个白名单**而不是传进来的几个键：只要任何一项被 flag / 环境变量 /
+ * config.json 给过值，这台机器就算「配置过」，不该再唠叨首次使用引导。
+ */
+export function summarizeConfigSources({ keys = ['baseUrl', 'model'], env = process.env, args = null, file = settingsFilePath() } = {}) {
+  const resolved = resolveSettings({ file, env, args });
+  const rows = {};
+  for (const key of keys) {
+    rows[key] = {
+      value: getByPath(resolved.values, key),
+      source: resolved.sources[key],
+      sourceText: settingSourceText(resolved, key),
+    };
+  }
+  return {
+    rows,
+    file: resolved.file,
+    configExists: resolved.exists,
+    allDefault: SETTINGS_SCHEMA.every((entry) => resolved.sources[entry.key] === 'default'),
+  };
+}
+
 /**
  * `config list` 与 Web 设置面板共用的行：键、当前值、来源、默认、说明，
  * 外加**渲染所需的类型信息**（type / 枚举取值 / 范围）。

package/package.json

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

package/public/manual.html

@@ -178,6 +178,8 @@ gateway-agent config unset key          # 清掉，回到「未配置」</code><
           <code>OPENAI_API_KEY</code> / <code>ANTHROPIC_API_KEY</code> / <code>ANTHROPIC_AUTH_TOKEN</code>）&gt;
           <code>.env</code> 里写 <code>GATEWAY_KEY=sk-xxx</code> &gt; <code>credentials.json</code>。
           环境里给了密钥时，那个文件<b>不参与</b>（<code>config list</code> 的「来源」列会告诉你是哪一层在生效）。
+          <b>四个命令行入口（agent / openai / anthropic / claude-code）也读 <code>credentials.json</code></b>——
+          也就是说「路线一 / 二」配一次，Web 与命令行<b>都认</b>，不必为了命令行再手写 <code>.env</code>。
           <code>.env</code> 的加载顺序是<b>①安装目录 → ②当前工作目录</b>；<b>npm 全局安装后包目录里只有
           <code>.env.example</code></b>，所以要用 <code>.env</code> 就放在<b>你起服务的那个目录</b>：
           <div class="code-block"><code># 在你干活的项目目录里（可选，不是必须）
@@ -217,6 +219,17 @@ gateway-agent config set mode auto          # 新任务的默认审批模式</co
           启动横幅会打印<b>网关 / 模型 / 密钥（脱敏 + 来源）/ 工具 / 存储 / 配置文件与密钥文件路径</b> ——
           先对着这几行核一遍，比在页面上猜快：密钥那行写「未配置」时，同一段还有三条填法。
         </li>
+        <li>
+          <b>每个值都带「来源」——看到有值不等于配过了</b>：横幅上写的是
+          <code>网关 http://127.0.0.1:9000（内置默认）</code>、<code>模型 qwen3:8b（内置默认）</code> 这样，
+          来源分四种：<b>内置默认</b> / <b>启动参数</b> / <b>环境变量（含 <code>.env</code>，会连文件路径一起写出来）</b> /
+          <b>配置文件 <code>config.json</code></b>。命令行 agent 的横幅同样带来源，并且有一行脱敏的密钥。
+          <div class="code-block"><code>[gateway] 原生 Agent · base=http://127.0.0.1:9000（内置默认） model=deepseek-v4-flash（环境变量 GATEWAY_MODEL（来自 .env：E:\proj\.env））
+          密钥 sk-abcd****wxyz（环境变量 GATEWAY_KEY（来自 .env：E:\proj\.env））</code></div>
+          这条信息专门用来破一个高频误会：<b>在别的项目目录里跑，会读到那个目录的 <code>.env</code></b>
+          （查找顺序是「安装目录 → 当前工作目录」），于是「我明明没配过，怎么已经有值了」。
+          全新机器第一次跑则是另一副样子：两个值都标「内置默认」，并多一句「这台机器还没有任何配置」+ 三条填法。
+        </li>
         <li>打开 <code>http://127.0.0.1:3100/task</code> —— 你正在看的这一页就是它。</li>
         <li>
           <b>连不上网关时怎么判断</b>：<code>curl http://127.0.0.1:9000/v1/models</code>（Windows：<code>irm http://127.0.0.1:9000/v1/models</code>）