llm-api-gateway-cli 1.0.0

package/lib/secrets.js

@@ -0,0 +1,198 @@
+/**
+ * 密钥的唯一实现：`<数据根目录>/credentials.json`
+ *
+ * 为什么单开一个文件而不是塞进 config.json：
+ *   config.json 是要被同步、被备份、被 `cat`、被贴进 issue 的东西；密钥进去等于迟早泄露。
+ *   单独一个文件 + 仅属主可读，既能做到「装完在界面里配一次就长期可用」（不用再手写 .env），
+ *   又把爆炸半径限制在「本机上能读这个文件的账户」。这条口径与 20260916 计划里写下的
+ *   「若日后确实要存，必须单文件、仅属主可读、并在启动时明确告知」一致。
+ *
+ * 优先级（自高到低）：`--key` > 环境变量 SK / GATEWAY_KEY / … > `.env` > 本文件。
+ * 也就是说：**环境里给了密钥时，这个文件不参与**（resolveKey 已经把它们都收进去了，
+ * 本模块只在「前三者都没有」时兜底）。
+ *
+ * 平台差异：POSIX 上写入后 chmod 0600，并在启动时检查有没有「同机其他用户可读」；
+ * Windows 上 chmod 只影响只读位、管不了 ACL —— 那里靠用户目录本身的 ACL
+ * （`C:\Users\<你>` 默认只有本人与管理员可读）。这一点在 README 与手册里如实写出，不假装做了权限控制。
+ */
+
+import { existsSync, readFileSync, chmodSync, statSync, unlinkSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import { writeJsonAtomic } from './jsonstore.js';
+import { defaultStoreRoot } from './taskstore.js';
+import { resolveKey, strArg, maskKey } from './common.js';
+
+/** 想单独把密钥文件放别处时用它（整体换数据根用 LLM_GATEWAY_DATA_DIR） */
+export const SECRET_ENV = 'LLM_GATEWAY_SECRET_FILE';
+export const SECRET_FILE_NAME = 'credentials.json';
+/** 只接受网关那种 sk- 形状的密钥：写错一个字符在这里拦住，比在页面上猜「为什么 401」强 */
+export const KEY_SHAPE = /^sk-\S{8,}$/;
+
+/** 密钥文件路径：默认跟任务/配置同一个数据根 */
+export function secretFilePath(env = process.env, home = os.homedir()) {
+  const custom = strArg(env?.[SECRET_ENV]);
+  if (custom) return path.resolve(custom.replace(/^~(?=[\\/]|$)/, home));
+  return path.join(defaultStoreRoot(env, home), SECRET_FILE_NAME);
+}
+
+/**
+ * 读密钥。
+ * 文件不存在 / 内容坏了都**不抛**：前者是「还没配」，后者要让页面与命令行把话说清楚，
+ * 而不是让服务起不来 —— 启动不起来的话用户连界面都进不去，只能去手改文件。
+ *
+ * @returns {{key:string, exists:boolean, file:string, warning:string}}
+ */
+export function readSecret({ file = secretFilePath(), env = process.env } = {}) {
+  if (!existsSync(file)) return { key: '', exists: false, file, warning: '' };
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return {
+      key: '',
+      exists: true,
+      file,
+      warning: `密钥文件读不了（${e.message}）：请修好或删掉 ${file}，然后在设置里重新填一次密钥。`,
+    };
+  }
+  const key = strArg(raw?.key);
+  if (!key) {
+    return { key: '', exists: true, file, warning: `密钥文件里没有 key 字段：${file}（可以在设置里重新填一次）。` };
+  }
+  return { key, exists: true, file, warning: '' };
+}
+
+/** 只要密钥本身（调用方不关心告警时用） */
+export function readSecretKey(opts = {}) {
+  return readSecret(opts).key;
+}
+
+/**
+ * 写入密钥：校验形状 → 原子写（tmp → rename）→ 收权限。
+ * @returns {{file:string, mode:number|null, warning:string}}
+ */
+export function writeSecret(key, { file = secretFilePath() } = {}) {
+  const value = strArg(key);
+  if (!value) throw new Error('密钥不能为空');
+  if (!KEY_SHAPE.test(value)) {
+    throw new Error(`密钥形状不对：需要以 sk- 开头且长度足够（收到 ${value.length} 个字符，前缀 ${value.slice(0, 3)}）`);
+  }
+  // 数据根目录可能还不存在（全新安装、或 LLM_GATEWAY_DATA_DIR 指到新位置）：
+  // writeJsonAtomic 只写文件不建目录，缺目录会直接 ENOENT，用户看到的就是「保存密钥失败」
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeJsonAtomic(file, { version: 1, key: value }, { pretty: true });
+  return { file, ...restrictPermissions(file) };
+}
+
+/**
+ * 收紧权限。Windows 上 chmod 只切只读位、不设 ACL，所以如实返回 mode=null 并由调用方说明。
+ * @returns {{mode:number|null, warning:string}}
+ */
+export function restrictPermissions(file) {
+  if (process.platform === 'win32') return { mode: null, warning: '' };
+  try {
+    chmodSync(file, 0o600);
+    return { mode: 0o600, warning: '' };
+  } catch (e) {
+    return { mode: null, warning: `无法把 ${file} 的权限收到 600（${e.message}）：请手工 chmod 600，或改用环境变量提供密钥。` };
+  }
+}
+
+/**
+ * 检查现有文件的权限位。
+ * @returns {{mode:number|null, groupOrWorldReadable:boolean, warning:string}}
+ */
+export function checkPermissions(file) {
+  if (process.platform === 'win32' || !existsSync(file)) {
+    return { mode: null, groupOrWorldReadable: false, warning: '' };
+  }
+  try {
+    const mode = statSync(file).mode & 0o777;
+    const loose = (mode & 0o077) !== 0;
+    return {
+      mode,
+      groupOrWorldReadable: loose,
+      warning: loose
+        ? `${file} 对同机其他用户可读（权限 ${mode.toString(8)}）：建议 chmod 600，或改用环境变量提供密钥。`
+        : '',
+    };
+  } catch (e) {
+    return { mode: null, groupOrWorldReadable: false, warning: `读不到 ${file} 的权限位：${e.message}` };
+  }
+}
+
+/** 删除密钥文件（`config unset key`）。文件本来就不在也算成功 */
+export function clearSecret({ file = secretFilePath() } = {}) {
+  const existed = existsSync(file);
+  if (existed) unlinkSync(file);
+  return { file, removed: existed };
+}
+
+/**
+ * 运行时密钥解析：把 flag / env / `.env` 与密钥文件合成一个答案，并说清「这一次的密钥是谁给的」。
+ *
+ * `resolveKey`（lib/common.js）已经把 `--key`、环境变量、`.env` 一起认了 —— 它是同一个进程里
+ * 唯一的「非文件来源」。所以这里用「resolveKey 有值 = 文件不生效」来表达优先级，
+ * 不去重复实现一遍 .env 解析。
+ *
+ * @returns {{key:string, source:'flag|env|file'|'', file:string, warning:string}}
+ */
+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: '' };
+  }
+  const read = readSecret({ file, env });
+  return { key: read.key, source: read.key ? 'file' : '', file, warning: read.warning };
+}
+
+export const SECRET_SOURCE_LABELS = {
+  flag: '启动参数 --key',
+  env: '环境变量',
+  file: '密钥文件',
+};
+
+/** 人话来源：给启动横幅与 config list 用（`.env` 走的是 env 层，见 resolveSecretKey 注释） */
+export function secretSourceText(source) {
+  return SECRET_SOURCE_LABELS[source] || '未配置';
+}
+
+/**
+ * 配置行：`/api/settings` 的 `rows` 与 `config list` **共用这一行**，所以页面与命令行看到的是同一份。
+ *
+ * 形状与 `lib/settings.js` 的 `listSettings()` 对齐（key/value/source/def/env/flag/desc/restart/type/…），
+ * 只是多带 `secret: true`、`hasKey`、`mask`、`file` 四个字段：
+ *   · `value` 永远是空串 —— 密钥**不回显**，页面拿 `mask` 显示「已设置 sk-ab****yz」；
+ *   · 它不在 `SETTINGS_SCHEMA` 里，因此不会被写进 config.json，也不会出现在补全脚本的键清单里。
+ */
+export function keyRow({ env = process.env, file = secretFilePath(env), args = null } = {}) {
+  const resolved = resolveSecretKey({ args, env, file });
+  const perms = checkPermissions(file);
+  const fromFile = resolved.source === 'file';
+  return {
+    key: 'key',
+    value: '',
+    source: resolved.source || 'default',
+    def: '',
+    env: 'SK / GATEWAY_KEY',
+    flag: '--key',
+    desc: '网关密钥（存 credentials.json，仅本用户可读；写进 config.json 是不允许的）',
+    restart: false,
+    type: 'secret',
+    values: null,
+    min: null,
+    max: null,
+    secret: true,
+    hasKey: Boolean(resolved.key),
+    mask: maskKey(resolved.key),
+    file,
+    fileMode: perms.mode,
+    // 来源是人话，页面直接显示；命令行同源
+    sourceText: secretSourceText(resolved.source),
+    warning: resolved.warning || perms.warning || '',
+    fromFile,
+  };
+}

package/lib/sessionstore.js

@@ -0,0 +1,269 @@
+/**
+ * 会话落盘（M2）
+ *
+ * 在此之前 createSession 只活在一个进程里：CLI 一退，上下文就没了，
+ * 想问「接着刚才那个任务继续」只能把话重新说一遍。
+ * 这里把会话（消息、用量、待批准态）落到磁盘，支撑 cli-agent 的 --continue / --resume。
+ *
+ * 目录布局：<dir>/<sessionId>.json
+ * 目录选择复刻 taskstore 的策略（主目录下的 .llm-api-gateway-cli/sessions → 旧位置 → 临时目录），
+ * 这样「任务」与「会话」落在同一个应用数据根下，用户要清理就一起清理。
+ *
+ * 关键词：isSafeId（id 必须是 UUID 形状，防目录穿越）、writeJsonAtomic（防半截文件）、
+ * 体积上限（会话含完整工具输出，不设限迟早把磁盘写满）。
+ */
+
+import path from 'node:path';
+import os from 'node:os';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, readdirSync, statSync } from 'node:fs';
+import { isSafeId, defaultStoreRoot, isWritable, migrateLegacyData, legacyLocations } from './taskstore.js';
+import { writeJsonAtomic } from './jsonstore.js';
+
+export const SESSION_TTL_DAYS = 15;
+export const SESSION_TTL_MS = SESSION_TTL_DAYS * 24 * 60 * 60 * 1000; // 滑动 15 天，与任务存储一致
+export const MAX_SESSIONS = 50;
+export const MAX_SESSION_MESSAGES = 400; // 超出就丢最老的非 system 消息
+export const MAX_SESSION_BYTES = 1024 * 1024; // 单文件 1MB 上限
+
+/**
+ * 挑一个能写的会话目录。与 taskstore.resolveStoreDir 同一套候选顺序：
+ *   1. 用户显式指定的 --session-dir（指定了必须能写，否则报错，不偷偷换地方）
+ *   2. 用户主目录下 `.llm-api-gateway-cli/sessions`（新家；顺手把旧位置的会话搬过来）
+ *   3. 旧位置（平台数据目录 / 脚本目录 `.sessions`）—— 主目录不可写时的保命通道
+ *   4. 系统临时目录
+ */
+export function resolveSessionDir(explicit, scriptDir, env = process.env, home = os.homedir()) {
+  if (explicit) {
+    const dir = path.resolve(explicit);
+    if (!isWritable(dir)) throw new Error(`指定的会话目录不可写：${dir}`);
+    return { dir, source: 'explicit', warning: null, notice: null };
+  }
+
+  const dataRoot = defaultStoreRoot(env, home);
+  const preferred = path.join(dataRoot, 'sessions');
+  if (isWritable(preferred)) {
+    // 模式六可能只用会话、不碰任务存储，所以搬家在这里也要触发一次（不覆盖，幂等）
+    const moved = migrateLegacyData(dataRoot, { scriptDir, env, home });
+    const notice = moved.length
+      ? `已把旧位置的数据搬到 ${dataRoot}：${moved.map((m) => `${m.from}（${m.files} 个文件）`).join('、')}；确认无误后旧目录可以自己删掉。`
+      : null;
+    return { dir: preferred, source: 'user-data', warning: null, notice };
+  }
+
+  // 主目录不可写：旧位置里有会话就继续用那儿，别让用户以为会话丢了
+  for (const loc of legacyLocations(scriptDir, dataRoot, env, home)) {
+    const candidate = loc.kind === 'sessions' ? loc.from : path.join(loc.from, 'sessions');
+    if (!isWritable(candidate)) continue;
+    let has = false;
+    try {
+      has = readdirSync(candidate).some((f) => f.endsWith('.json'));
+    } catch {
+      has = false;
+    }
+    if (!has) continue;
+    return {
+      dir: candidate,
+      source: 'legacy',
+      warning: `用户主目录下的会话目录不可写（${preferred}），继续使用旧位置：${candidate}。想固定下来请用 --session-dir 指定。`,
+      notice: null,
+    };
+  }
+
+  const tmp = path.join(os.tmpdir(), 'llm-api-gateway-cli-sessions');
+  if (isWritable(tmp)) {
+    return {
+      dir: tmp,
+      source: 'temp',
+      warning: `主目录与旧位置都不可写，会话已改用临时目录（重启后可能被清理）：${tmp}`,
+      notice: null,
+    };
+  }
+
+  throw new Error(`找不到可写的会话目录，试过：${preferred} / ${tmp}`);
+}
+
+const str = (v, max) => (typeof v === 'string' && v ? v.slice(0, max) : undefined);
+
+/**
+ * 落盘前的清洗：只留认识的字段，按体积上限裁掉最老的消息。
+ * 返回 { record, dropped } —— dropped 是本次为压体积丢掉的用户/助手消息条数。
+ */
+export function sanitizeSession(session, { maxMessages = MAX_SESSION_MESSAGES, maxBytes = MAX_SESSION_BYTES } = {}) {
+  if (!session || typeof session !== 'object' || !isSafeId(session.id)) return null;
+  const messages = Array.isArray(session.messages) ? session.messages.filter((m) => m && typeof m === 'object') : [];
+  // 消息也可能大到离谱（工具结果里全是文件正文），逐条截断
+  const trimmed = messages.slice(-maxMessages).map((m) => {
+    const copy = { ...m };
+    if (typeof copy.content === 'string' && copy.content.length > 200000) {
+      copy.content = `${copy.content.slice(0, 200000)}\n…（落盘时截断）`;
+    }
+    return copy;
+  });
+
+  const usage = {
+    prompt: Number(session.usage?.prompt) || 0,
+    completion: Number(session.usage?.completion) || 0,
+  };
+
+  const record = {
+    version: 1,
+    id: session.id,
+    workingDir: str(session.workingDir, 4096) || '',
+    model: str(session.model, 200) || '',
+    mode: str(session.mode, 20) || 'manual',
+    temperature: Number.isFinite(session.temperature) ? session.temperature : undefined,
+    maxTokens: Number.isFinite(session.maxTokens) ? session.maxTokens : undefined,
+    messages: trimmed,
+    usage,
+    pending: session.pending && typeof session.pending === 'object' ? session.pending : null,
+    pendingPreview: session.pendingPreview && typeof session.pendingPreview === 'object' ? session.pendingPreview : null,
+    touchedAt: Number(session.touchedAt) || Date.now(),
+  };
+
+  // 体积兜底：先丢正文最长的工具结果，再丢最老的非 system 消息，直到低于上限
+  let dropped = 0;
+  const size = () => Buffer.byteLength(JSON.stringify(record));
+  while (size() > maxBytes && record.messages.length > 1) {
+    // 保留 system（messages[0]），从第 1 条开始丢
+    const idx = record.messages.length > 1 ? 1 : 0;
+    record.messages.splice(idx, 1);
+    dropped++;
+    if (record.messages.length <= 1) break;
+  }
+  return { record, dropped };
+}
+
+/**
+ * 通用「消息存储」：文件布局 `<dir>/<id>.json`，负责 UUID 校验、原子写、TTL 清理、
+ * 「最多留 N 条」的裁剪。CLI 会话（`--continue` / `--resume`）与任务会话（模型态消息，
+ * 见 `lib/tasksession.js`）都建在它上面 ——
+ * 两边的**记录字段**不同，但**落盘机制**一模一样，各抄一份必然漂移。
+ *
+ * @param {object}   opts
+ * @param {string}   opts.dir              目录（不存在会建）
+ * @param {Function} opts.sanitize         记录清洗：返回 { record, dropped } 或 null（非法）
+ * @param {Function} opts.idOf             从清洗后的记录里取 id（CLI 会话取 id，任务会话取 taskId）
+ * @param {number=}  opts.maxItems         prune 时最多保留几条（0 = 不裁剪）
+ * @param {string=}  opts.label            报错文案里的名字
+ */
+export function createMessageStore({ dir, sanitize, idOf, maxItems = 0, label = '会话' }) {
+  mkdirSync(dir, { recursive: true });
+  const file = (id) => path.join(dir, `${id}.json`);
+
+  const write = (session) => {
+    const clean = sanitize(session);
+    const id = clean ? idOf(clean.record) : null;
+    if (!clean || !isSafeId(id)) throw new Error(`${label} id 非法（必须是 UUID）`);
+    writeJsonAtomic(file(id), clean.record);
+    return { dropped: clean.dropped, bytes: statSync(file(id)).size };
+  };
+
+  const read = (id) => {
+    if (!isSafeId(id)) return null;
+    const f = file(id);
+    if (!existsSync(f)) return null;
+    try {
+      const data = JSON.parse(readFileSync(f, 'utf8'));
+      return data && typeof data === 'object' && isSafeId(idOf(data) || id) ? data : null;
+    } catch {
+      // 损坏的记录读不回来就没有保留价值，清掉免得每次都报错
+      try {
+        unlinkSync(f);
+      } catch {
+        /* 忽略 */
+      }
+      return null;
+    }
+  };
+
+  const drop = (id) => {
+    if (!isSafeId(id)) return false;
+    try {
+      unlinkSync(file(id));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  /** 列出会话（新的在前）；带 ttlMs 时顺带清理过期与杂物 */
+  const list = (ttlMs) => {
+    const out = [];
+    let names = [];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return out;
+    }
+    const now = Date.now();
+    for (const n of names) {
+      if (n.endsWith('.tmp')) {
+        try {
+          unlinkSync(path.join(dir, n));
+        } catch {
+          /* 忽略 */
+        }
+        continue;
+      }
+      if (!n.endsWith('.json')) continue;
+      const id = n.slice(0, -'.json'.length);
+      if (!isSafeId(id)) {
+        try {
+          unlinkSync(path.join(dir, n));
+        } catch {
+          /* 忽略 */
+        }
+        continue;
+      }
+      const rec = read(id);
+      if (!rec) continue;
+      if (ttlMs && now - (rec.touchedAt || 0) > ttlMs) {
+        drop(id);
+        continue;
+      }
+      out.push(rec);
+    }
+    out.sort((a, b) => (b.touchedAt || 0) - (a.touchedAt || 0));
+    return out;
+  };
+
+  /** 最近一次（--continue 用） */
+  const latest = (ttlMs = SESSION_TTL_MS) => list(ttlMs)[0] || null;
+
+  /** 只保留最近的 maxItems 条，返回被清掉的 id */
+  const prune = () => {
+    if (!maxItems) return [];
+    const all = list();
+    const removed = all.slice(maxItems);
+    for (const r of removed) drop(idOf(r));
+    return removed.map((r) => idOf(r));
+  };
+
+  /** 条数与占用字节（/api/store 用它把「会话占了多大」告诉用户） */
+  const stats = () => {
+    let count = 0;
+    let bytes = 0;
+    for (const r of list()) {
+      count++;
+      try {
+        bytes += statSync(file(idOf(r))).size;
+      } catch {
+        /* 读不到大小就不计 */
+      }
+    }
+    return { dir, count, bytes };
+  };
+
+  return { dir, write, read, drop, list, latest, prune, stats };
+}
+
+/** CLI 会话存储（`--continue` / `--resume`）：行为与抽公共实现之前完全一致 */
+export function createSessionStore(dir) {
+  return createMessageStore({
+    dir,
+    sanitize: sanitizeSession,
+    idOf: (r) => r.id,
+    maxItems: MAX_SESSIONS,
+    label: '会话',
+  });
+}