@vfvrpq/llm-cli 1.1.0 → 1.2.1

package/lib/args.js

@@ -0,0 +1,93 @@
+"use strict";
+// 命令行参数解析与帮助生成（按入口的 features 开关生成对应选项）。
+const { ApiError } = require("./errors");
+
+const COMMON_ALIASES = {
+  "-m": "model", "--model": "model",
+  "--api-key": "api_key",
+  "--base-url": "base_url",
+  "--system": "system",
+  "-t": "temperature", "--temperature": "temperature",
+  "--max-tokens": "max_tokens",
+  "-f": "file", "--file": "file",
+  "-o": "output", "--output": "output",
+  "--resume": "resume",
+};
+
+function parseArgs(argv, features) {
+  const aliases = { ...COMMON_ALIASES };
+  if (features.provider) Object.assign(aliases, { "-p": "provider", "--provider": "provider" });
+  if (features.thinking) Object.assign(aliases, { "--thinking": "thinking" });
+
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") { opts.help = true; continue; }
+    if (a === "-V" || a === "--version") { opts.version = true; continue; }
+    if (a === "--no-stream") { opts.no_stream = true; continue; }
+    if (a === "--no-color") { opts.no_color = true; continue; }
+    if (a === "--debug") { opts.debug = true; continue; }
+    const key = aliases[a];
+    if (!key) {
+      if (a.startsWith("-")) throw new ApiError(`未知参数: ${a}`);
+      opts._.push(a);
+      continue;
+    }
+    const val = argv[++i];
+    if (val === undefined) throw new ApiError(`参数 ${a} 缺少值`);
+    if (key === "file") (opts.file = opts.file || []).push(val);
+    else opts[key] = val;
+  }
+  return opts;
+}
+
+function printHelp(entry) {
+  const f = entry.features;
+  const registry = entry.registry;
+  let providersBlock = "";
+  if (f.provider) {
+    const rows = Object.entries(registry)
+      .map(([id, pc]) => `  ${id.padEnd(13)} ${pc.label.padEnd(18)} ${pc.defaultModel || "(需 -m)"}`)
+      .join("\n");
+    providersBlock = `
+供应商 (-p/--provider，默认 ${Object.keys(registry)[0]}，也可按模型名前缀自动推断):
+${rows}
+`;
+  } else {
+    const pc = registry[entry.fixedProvider];
+    providersBlock = `
+供应商: ${entry.fixedProvider} (${pc.label})，默认端点 ${pc.defaultBase}，默认模型 ${pc.defaultModel || "(需 -m)"}
+`;
+  }
+
+  const options = [
+    "  -m, --model <名称>       模型名（无默认模型的供应商必须指定）",
+    f.provider ? "  -p, --provider <名称>    供应商" : null,
+    "  --api-key <Key>          本次使用的 API Key（优先级最高）",
+    "  --base-url <地址>        接口地址",
+    "  --system <文本>          system 提示词",
+    "  -t, --temperature <值>   采样温度",
+    "  --max-tokens <数量>      最大输出 token 数",
+    f.thinking ? "  --thinking <on|off>      深度思考开关（仅智谱 GLM 生效）" : null,
+    "  --no-stream              关闭流式输出",
+    "  --no-color / --debug     关闭彩色 / 调试输出",
+  ].filter(Boolean).join("\n");
+
+  console.log(`${entry.name} ${entry.version} —— ${entry.tagline}
+
+用法: node ${entry.file} <command> [参数] [选项]
+
+命令:
+  ask      单次提问: node ${entry.file} ask "问题"
+  chat     多轮交互对话${f.provider ? "（支持 /provider /model /system /save）" : "（支持 /model /system /save）"}
+  models   列出当前账号可用的模型
+  config   管理本地配置: set/get/del${f.list ? "/list" : ""}/path
+${providersBlock}
+选项:
+${options}
+
+示例:
+${entry.examples.map((e) => `  ${e}`).join("\n")}`);
+}
+
+module.exports = { parseArgs, printHelp };

package/lib/chat.js

@@ -0,0 +1,110 @@
+"use strict";
+// 对话调用：payload 构建（thinking 门控）、流式/非流式执行与实时渲染。
+const { ApiError } = require("./errors");
+const { colors } = require("./colors");
+const { STREAM_IDLE_MS, PLAIN_MS, TIMEOUT_REASON, isAbort, apiFetch, iterSSE } = require("./http");
+
+const state = { currentAbort: null };
+
+function buildPayload(rt, messages, args, ctx) {
+  const payload = { model: rt.model, messages, stream: !args.no_stream };
+  if (args.temperature != null) payload.temperature = Number(args.temperature);
+  if (args.max_tokens) payload.max_tokens = Number(args.max_tokens);
+  if (args.thinking != null) {
+    if (rt.pc.supportsThinking) {
+      payload.thinking = { type: args.thinking === "on" ? "enabled" : "disabled" };
+    } else {
+      console.error(`${colors.dim}(提示: --thinking 仅对智谱 GLM 生效，已忽略)${colors.reset}`);
+    }
+  }
+  if (args.debug) {
+    console.error(`[debug] ${rt.baseUrl.replace(/\/+$/, "")}/chat/completions`);
+    console.error(`[debug] ${JSON.stringify(payload)}`);
+  }
+  return payload;
+}
+
+async function chatCompletion(rt, payload) {
+  const url = rt.baseUrl.replace(/\/+$/, "") + "/chat/completions";
+  const stream = !!payload.stream;
+  const controller = new AbortController();
+  let timer = null;
+  const arm = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => controller.abort(TIMEOUT_REASON), stream ? STREAM_IDLE_MS : PLAIN_MS);
+  };
+  arm();
+  state.currentAbort = controller;
+  const contentParts = [];
+  const reasoningParts = [];
+  let usage = null;
+  try {
+    const resp = await apiFetch(url, rt.apiKey, payload, "POST", controller.signal, rt.hints);
+    if (stream) {
+      let inThinking = false;
+      for await (const data of iterSSE(resp.body)) {
+        arm();
+        let obj;
+        try { obj = JSON.parse(data); } catch { continue; }
+        if (obj.error) throw new ApiError("服务端返回错误：" + JSON.stringify(obj.error));
+        if (obj.usage) usage = obj.usage;
+        const choice = (obj.choices || [])[0];
+        if (!choice) continue;
+        const delta = choice.delta || {};
+        const rc = delta.reasoning_content;
+        if (rc) {
+          if (!inThinking) {
+            inThinking = true;
+            console.log(`${colors.dim}—— 思考 ——${colors.reset}`);
+          }
+          process.stdout.write(colors.dim + rc + colors.reset);
+          reasoningParts.push(rc);
+        }
+        const text = delta.content;
+        if (text) {
+          if (inThinking) {
+            inThinking = false;
+            console.log(`\n${colors.bold}—— 回答 ——${colors.reset}`);
+          }
+          process.stdout.write(text);
+          contentParts.push(text);
+        }
+      }
+      console.log();
+    } else {
+      const obj = await resp.json();
+      if (obj.error) throw new ApiError("服务端返回错误：" + JSON.stringify(obj.error));
+      const message = ((obj.choices || [])[0] || {}).message || {};
+      if (message.reasoning_content) {
+        console.log(`${colors.dim}—— 思考 ——\n${message.reasoning_content}${colors.reset}`);
+        reasoningParts.push(message.reasoning_content);
+      }
+      const content = message.content || "";
+      console.log(content);
+      contentParts.push(content);
+      usage = obj.usage || null;
+    }
+  } catch (err) {
+    if (isAbort(err)) {
+      if (controller.signal.reason === TIMEOUT_REASON) {
+        console.log(`\n${colors.dim}(等待数据超时，已中断)${colors.reset}`);
+      } else {
+        console.log(`\n${colors.dim}(已中断本次回复)${colors.reset}`);
+      }
+    } else {
+      throw err;
+    }
+  } finally {
+    clearTimeout(timer);
+    state.currentAbort = null;
+  }
+  return { content: contentParts.join(""), reasoning: reasoningParts.join(""), usage };
+}
+
+function printUsageLine(usage) {
+  if (usage && usage.prompt_tokens != null && usage.completion_tokens != null) {
+    console.log(`${colors.dim}[tokens] 输入 ${usage.prompt_tokens} · 输出 ${usage.completion_tokens}${colors.reset}`);
+  }
+}
+
+module.exports = { state, buildPayload, chatCompletion, printUsageLine };

package/lib/colors.js

@@ -0,0 +1,15 @@
+"use strict";
+// 终端颜色输出：仅在 TTY 且未显式禁用时启用 ANSI。
+const colors = { dim: "", bold: "", red: "", green: "", cyan: "", reset: "" };
+
+function enableColors(noColor) {
+  if (noColor || process.env.NO_COLOR || !process.stdout.isTTY) return;
+  colors.dim = "\x1b[2m";
+  colors.bold = "\x1b[1m";
+  colors.red = "\x1b[31m";
+  colors.green = "\x1b[32m";
+  colors.cyan = "\x1b[36m";
+  colors.reset = "\x1b[0m";
+}
+
+module.exports = { colors, enableColors };

package/lib/commands/ask.js

@@ -0,0 +1,50 @@
+"use strict";
+// ask 子命令：单次提问（位置参数 / 管道 / 附带文件 / 保存回答）。
+const fs = require("node:fs");
+const path = require("node:path");
+const { ApiError } = require("../errors");
+const { colors } = require("../colors");
+const { resolveRuntime, requireKey } = require("../registry");
+const { buildPayload, chatCompletion, printUsageLine } = require("../chat");
+
+function readQuestionFromFiles(files) {
+  return files.map((fp) => {
+    let text;
+    try {
+      text = fs.readFileSync(fp, "utf8");
+    } catch (e) {
+      throw new ApiError(`无法读取文件 ${fp}：${e.message}`);
+    }
+    return `文件 \`${path.basename(fp)}\` 内容：\n\`\`\`\n${text}\n\`\`\``;
+  });
+}
+
+async function ask(args, cfg, ctx) {
+  const rt = resolveRuntime(args, cfg, ctx);
+  requireKey(rt.apiKey, rt);
+
+  let question = args._.join(" ").trim();
+  if (!question && !process.stdin.isTTY) {
+    try { question = fs.readFileSync(0, "utf8").trim(); } catch {}
+  }
+  if (args.file && args.file.length) {
+    question = (question ? question + "\n\n" : "") + readQuestionFromFiles(args.file).join("\n\n");
+  }
+  if (!question) {
+    throw new ApiError(`请提供问题内容，例如：node ${ctx.entry.file} ask "你好"（或用管道传入；交互式多轮请用 chat 子命令）`);
+  }
+
+  const messages = [];
+  if (args.system) messages.push({ role: "system", content: args.system });
+  messages.push({ role: "user", content: question });
+
+  const { content, usage } = await chatCompletion(rt, buildPayload(rt, messages, args, ctx));
+  if (args.output) {
+    fs.mkdirSync(path.dirname(path.resolve(args.output)), { recursive: true });
+    fs.writeFileSync(args.output, content, "utf8");
+    console.log(`${colors.dim}回答已保存到 ${args.output}${colors.reset}`);
+  }
+  printUsageLine(usage);
+}
+
+module.exports = ask;

package/lib/commands/chat.js

@@ -0,0 +1,142 @@
+"use strict";
+// chat 子命令：多轮交互对话（REPL + 斜杠命令 + Ctrl+C 中断单次回复）。
+const fs = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline");
+const { ApiError } = require("../errors");
+const { colors } = require("../colors");
+const { resolveRuntime, requireKey, normalizeProvider } = require("../registry");
+const { buildPayload, chatCompletion, printUsageLine, state } = require("../chat");
+
+const SLASH_HELP = [
+  "命令:",
+  "  /help              显示本帮助",
+  "  /new               清空当前对话，重新开始",
+  "  /provider <名称>    临时切换供应商",
+  "  /model <名称>       临时切换模型",
+  "  /system <文本>      设置/更新 system 提示词（不带文本则清除）",
+  "  /save [路径]        保存当前对话记录为 JSON",
+  "  /exit              退出（或 Ctrl+C / Ctrl+D）",
+].join("\n");
+
+async function chat(args, cfg, ctx) {
+  const rt = resolveRuntime(args, cfg, ctx);
+  requireKey(rt.apiKey, rt);
+
+  let messages = args.system ? [{ role: "system", content: args.system }] : [];
+  if (args.resume) {
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(args.resume, "utf8"));
+    } catch (e) {
+      throw new ApiError(`无法读取对话记录 ${args.resume}：${e.message}`);
+    }
+    messages = data.messages || messages;
+    if (data.model) rt.model = data.model;
+  }
+
+  console.log(`${colors.cyan}${ctx.entry.name} ${ctx.entry.version} · ${rt.provider}(${rt.label}) · 模型 ${rt.model} · ${rt.baseUrl}${colors.reset}`);
+  console.log(`${colors.dim}输入消息开始对话，/help 查看命令，/exit 退出。${colors.reset}`);
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.setPrompt(`${colors.green}你${colors.reset} > `);
+  rl.prompt();
+
+  // 输入流结束（EOF）会自动关闭 readline，此时再 prompt 会抛 ERR_USE_AFTER_CLOSE
+  let rlClosed = false;
+  rl.on("close", () => { rlClosed = true; });
+  const safePrompt = () => { if (!rlClosed) rl.prompt(); };
+
+  // Ctrl+C：正在生成时中断本次回复，空闲时退出
+  rl.on("SIGINT", () => {
+    if (state.currentAbort) state.currentAbort.abort();
+    else rl.close();
+  });
+
+  try {
+    for await (const line of rl) {
+      const text = line.trim();
+      if (!text) { safePrompt(); continue; }
+
+      if (text.startsWith("/")) {
+        const cmd = text.split(/\s+/)[0].toLowerCase();
+        const rest = text.slice(cmd.length).trim();
+        if (["/exit", "/quit", "/q"].includes(cmd)) break;
+        else if (cmd === "/help") console.log(SLASH_HELP);
+        else if (cmd === "/new") {
+          messages = messages.filter((m) => m.role === "system");
+          console.log(`${colors.dim}已清空对话。${colors.reset}`);
+        } else if (cmd === "/provider") {
+          if (!ctx.features.provider) {
+            console.log(`${colors.dim}当前入口不支持切换供应商。${colors.reset}`);
+          } else if (rest) {
+            const p = normalizeProvider(rest, ctx.registry);
+            const pc = ctx.registry[p];
+            const conf = (cfg.providers && cfg.providers[p]) || {};
+            const k = process.env[pc.envKeys[0]] || conf.api_key;
+            if (!k) {
+              console.log(`${colors.red}[${p}] 未配置 Key：config set api-key --provider ${p}${colors.reset}`);
+            } else {
+              rt.provider = p;
+              rt.pc = pc;
+              rt.apiKey = k;
+              rt.baseUrl = conf.base_url || pc.defaultBase;
+              rt.model = conf.model || pc.defaultModel;
+              rt.hints = { ...rt.hints, ...(pc.hints || {}) };
+              if (!rt.model) console.log(`${colors.dim}注意：[${p}] 无默认模型，请用 /model 指定。${colors.reset}`);
+              console.log(`${colors.dim}已切换供应商: ${p} (${pc.label})${colors.reset}`);
+            }
+          } else {
+            console.log(`当前供应商: ${rt.provider} (${rt.label})`);
+          }
+        } else if (cmd === "/model") {
+          if (rest) { rt.model = rest; console.log(`${colors.dim}已切换模型: ${rt.model}${colors.reset}`); }
+          else console.log(`当前模型: ${rt.model}`);
+        } else if (cmd === "/system") {
+          messages = messages.filter((m) => m.role !== "system");
+          if (rest) {
+            messages.unshift({ role: "system", content: rest });
+            console.log(`${colors.dim}system 已设置。${colors.reset}`);
+          } else {
+            console.log(`${colors.dim}system 已清除。${colors.reset}`);
+          }
+        } else if (cmd === "/save") {
+          const file = rest || ctx.historyFile;
+          fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+          fs.writeFileSync(file, JSON.stringify({ provider: rt.provider, model: rt.model, messages }, null, 2) + "\n", "utf8");
+          console.log(`${colors.dim}对话已保存到 ${file}${colors.reset}`);
+        } else {
+          console.log(`${colors.dim}未知命令 ${cmd}，输入 /help 查看帮助。${colors.reset}`);
+        }
+        safePrompt();
+        continue;
+      }
+
+      if (!rt.model) {
+        console.log(`${colors.red}当前供应商没有默认模型，请先 /model <名称>。${colors.reset}`);
+        safePrompt();
+        continue;
+      }
+
+      messages.push({ role: "user", content: text });
+      try {
+        const { content, usage } = await chatCompletion(rt, buildPayload(rt, messages, args, ctx));
+        if (content.trim()) messages.push({ role: "assistant", content });
+        else messages.pop(); // 回复为空（如被中断），移除未完成回合的用户消息
+        printUsageLine(usage);
+      } catch (e) {
+        if (e instanceof ApiError) {
+          console.error(`${colors.red}${e.message}${colors.reset}`);
+          messages.pop(); // 回合失败，移除未送达的用户消息
+        } else {
+          throw e;
+        }
+      }
+      safePrompt();
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+module.exports = chat;

package/lib/commands/config-cmd.js

@@ -0,0 +1,92 @@
+"use strict";
+// config 子命令：set/get/del/(list)/path。多供应商入口才支持 provider 项与 list。
+const { ApiError } = require("../errors");
+const { promptHidden } = require("../hidden");
+const { mask, providerOf } = require("../registry");
+
+async function configCmd(args, cfg, ctx) {
+  const [action, item, value] = args._;
+  const multi = ctx.features.provider;
+
+  if (action === "path") {
+    console.log(ctx.configFile);
+    return;
+  }
+
+  if (action === "list") {
+    if (!multi) throw new ApiError("用法: config set|get|del|path");
+    for (const [id, pc] of Object.entries(ctx.registry)) {
+      const conf = (cfg.providers && cfg.providers[id]) || {};
+      const configured = conf.api_key || process.env[pc.envKeys[0]];
+      const model = conf.model || pc.defaultModel || "(需 -m 指定)";
+      console.log(`${id.padEnd(13)} ${pc.label.padEnd(18)} key:${configured ? "已配" : "未配"}  默认模型: ${model}`);
+    }
+    console.log(`默认供应商: ${cfg.default_provider || Object.keys(ctx.registry)[0]}`);
+    return;
+  }
+
+  if (action === "get") {
+    if (multi) {
+      console.log(`配置文件      : ${ctx.configFile}`);
+      console.log(`默认供应商    : ${cfg.default_provider || Object.keys(ctx.registry)[0]}`);
+      for (const [id, pc] of Object.entries(ctx.registry)) {
+        const conf = (cfg.providers && cfg.providers[id]) || {};
+        if (!conf.api_key && !conf.model && !conf.base_url) continue;
+        console.log(`[${id}]`);
+        console.log(`  api_key  : ${mask(conf.api_key)}`);
+        console.log(`  model    : ${conf.model || `(默认 ${pc.defaultModel || "需 -m 指定"})`}`);
+        console.log(`  base_url : ${conf.base_url || `(默认 ${pc.defaultBase})`}`);
+      }
+    } else {
+      const pc = ctx.registry[ctx.fixedProvider];
+      const conf = (cfg.providers && cfg.providers[ctx.fixedProvider]) || {};
+      console.log(`配置文件 : ${ctx.configFile}`);
+      console.log(`api_key  : ${mask(conf.api_key)}`);
+      console.log(`model    : ${conf.model || `(默认 ${pc.defaultModel})`}`);
+      console.log(`base_url : ${conf.base_url || `(默认 ${pc.defaultBase})`}`);
+    }
+    return;
+  }
+
+  const items = { "api-key": "api_key", model: "model", "base-url": "base_url" };
+
+  if (action === "set") {
+    if (item === "provider") {
+      if (!multi) throw new ApiError("支持设置: api-key / model / base-url");
+      const key = providerOf({ provider: value }, cfg, ctx);
+      cfg.default_provider = key;
+      ctx.saveCfg(cfg);
+      console.log(`已设置默认供应商: ${key}（${ctx.registry[key].label}）`);
+      return;
+    }
+    if (!item || !(item in items)) {
+      throw new ApiError(multi ? "支持设置: api-key / model / base-url / provider" : "支持设置: api-key / model / base-url");
+    }
+    const provider = providerOf(args, cfg, ctx);
+    let v = value;
+    if (item === "api-key" && !v) v = await promptHidden(`请输入 [${provider}] 的 API Key（输入不会回显）: `);
+    v = (v || "").trim();
+    if (!v) throw new ApiError(`缺少 ${item} 的值，例如: config set ${item} <值>${multi ? ` --provider ${provider}` : ""}`);
+    cfg.providers = cfg.providers || {};
+    cfg.providers[provider] = cfg.providers[provider] || {};
+    cfg.providers[provider][items[item]] = v;
+    ctx.saveCfg(cfg);
+    console.log(multi
+      ? `已保存到 [${provider}]。配置文件: ${ctx.configFile}`
+      : `已保存。配置文件: ${ctx.configFile}`);
+    return;
+  }
+
+  if (action === "del") {
+    if (!item || !(item in items)) throw new ApiError("支持删除: api-key / model / base-url");
+    const provider = providerOf(args, cfg, ctx);
+    if (cfg.providers && cfg.providers[provider]) delete cfg.providers[provider][items[item]];
+    ctx.saveCfg(cfg);
+    console.log(multi ? `已删除 [${provider}] 的 ${item}。` : "已删除。");
+    return;
+  }
+
+  throw new ApiError(multi ? "用法: config set|get|del|list|path" : "用法: config set|get|del|path");
+}
+
+module.exports = configCmd;

package/lib/commands/models.js

@@ -0,0 +1,30 @@
+"use strict";
+// models 子命令：GET /models 列出当前账号可用的模型。
+const { ApiError } = require("../errors");
+const { resolveRuntime, requireKey } = require("../registry");
+const { TIMEOUT_REASON, isAbort, apiFetch } = require("../http");
+
+async function models(args, cfg, ctx) {
+  const rt = resolveRuntime(args, cfg, ctx);
+  requireKey(rt.apiKey, rt);
+  const url = rt.baseUrl.replace(/\/+$/, "") + "/models";
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(TIMEOUT_REASON), 60000);
+  try {
+    const resp = await apiFetch(url, rt.apiKey, null, "GET", controller.signal, rt.hints);
+    const obj = await resp.json();
+    const items = obj.data || [];
+    if (!items.length) {
+      console.log("服务端未返回模型列表。请直接用 -m 指定模型名，或查阅对应平台文档。");
+      return;
+    }
+    for (const it of items) console.log(typeof it === "string" ? it : it.id);
+  } catch (err) {
+    if (isAbort(err)) throw new ApiError("请求超时（>60s）。");
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+module.exports = models;

package/lib/config.js

@@ -0,0 +1,50 @@
+"use strict";
+// 配置文件读写。单供应商入口沿用 1.x 的扁平结构，多供应商入口用嵌套结构。
+const fs = require("node:fs");
+const path = require("node:path");
+
+function loadJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    console.error(`警告：配置文件 ${file} 读取失败（${e.message}），将忽略已有配置。`);
+    return {};
+  }
+}
+
+function saveJson(file, obj) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  if (process.platform !== "win32") {
+    try { fs.chmodSync(file, 0o600); } catch {}
+  }
+}
+
+// 把 1.x 单供应商的扁平配置 {api_key,...} 包装成统一的 {providers:{...}} 结构
+function loadUnified(file, { singleProvider } = {}) {
+  const raw = loadJson(file);
+  if (singleProvider && !raw.providers && (raw.api_key || raw.model || raw.base_url)) {
+    return { default_provider: singleProvider, providers: { [singleProvider]: raw } };
+  }
+  return raw;
+}
+
+// 单供应商入口写回时保持扁平结构（与 1.x 配置文件完全兼容）
+function saveUnified(file, cfg, { singleProvider } = {}) {
+  if (singleProvider) {
+    saveJson(file, (cfg.providers && cfg.providers[singleProvider]) || {});
+    return;
+  }
+  saveJson(file, cfg);
+}
+
+function resolveConfigPath({ configEnv, configDirName }) {
+  return path.join(process.env[configEnv] || path.join(require("node:os").homedir(), configDirName), "config.json");
+}
+
+function historyPathFor(configFile) {
+  return path.join(path.dirname(configFile), "chat-latest.json");
+}
+
+module.exports = { loadJson, saveJson, loadUnified, saveUnified, resolveConfigPath, historyPathFor };

package/lib/errors.js

@@ -0,0 +1,32 @@
+"use strict";
+// 错误类型与 HTTP 错误的用户可读映射。
+class ApiError extends Error {}
+
+const DEFAULT_HINTS = {
+  401: "API Key 缺失、无效或未生效。请执行: config set api-key（多供应商时加 --provider）",
+  403: "当前 Key 无权访问该模型，或账户余额不足。",
+  404: "模型名或接口地址可能有误：用 -m/--model 指定模型，--base-url 指定接口地址。",
+  402: "账户余额不足，请前往对应平台充值。",
+  429: "请求过于频繁，或额度/资源包不足，请稍后再试。",
+};
+
+// 把 HTTP 错误响应转成带提示的可读消息；hints 可被供应商覆盖
+async function friendlyHTTPError(resp, hints = DEFAULT_HINTS) {
+  let detail = "";
+  try {
+    const text = await resp.text();
+    try {
+      const obj = JSON.parse(text);
+      detail = (obj.error && (obj.error.message || obj.error.msg)) || text.trim();
+    } catch {
+      detail = text.trim();
+    }
+  } catch {}
+  let msg = `请求失败 [HTTP ${resp.status}]`;
+  if (detail) msg += `：${detail}`;
+  const hint = hints[resp.status];
+  if (hint) msg += `\n提示：${hint}`;
+  return msg;
+}
+
+module.exports = { ApiError, DEFAULT_HINTS, friendlyHTTPError };

package/lib/hidden.js

@@ -0,0 +1,24 @@
+"use strict";
+// 终端隐藏输入（保存 API Key 时回显关闭）。
+const readline = require("node:readline");
+const { Writable } = require("node:stream");
+
+function promptHidden(question) {
+  return new Promise((resolve) => {
+    process.stderr.write(question);
+    const sink = new Writable({ write(_chunk, _enc, cb) { cb(); } });
+    const rl = readline.createInterface({ input: process.stdin, output: sink, terminal: true });
+    let done = false;
+    const finish = (answer) => {
+      if (done) return;
+      done = true;
+      rl.close();
+      process.stderr.write("\n");
+      resolve(String(answer || "").trim());
+    };
+    rl.on("close", () => finish(""));
+    rl.question("", finish);
+  });
+}
+
+module.exports = { promptHidden };