@dougen/dsh-deepseek-usage 0.6.1 → 0.8.0

package/lib/index.js

@@ -10,24 +10,37 @@
  *     ok: true,
  *     balance: { isAvailable, total, currency, granted, toppedUp },  // 官方余额接口（API Key）
  *     tier: { input, cacheRead, cacheWrite, output, model, known },  // 当前模型当前档单价
- *     pricing: { source, via, requested, used, syncOk, syncedAt, ... }, // 价格来源/同步状态
+ *     next: { peak, at, ms },                                        // 距下次峰谷切换（界面倒计时）
  *     peak, peakHours,                                               // 峰谷时段（北京时间）
- *     updatedAt, errors
+ *     updatedAt, errors,
+ *     pricing: { source, via, requested, used, syncOk, syncing, syncedAt, layerAt,
+ *                mode, file: { path, updatedAt, ... } },             // 【内部诊断】界面不再消费
  *   }
  *
+ * 界面只使用 balance / tier / next / peak / errors：插件内部的计价来源、同步状态、
+ * 价格表位置属于诊断信息，保留在响应里供排查与测试，但不出现在 UI 上。
+ * errors 只放"用户能理解且需要行动"的余额类失败，不再包含"模型不在价格表"这类内部细节。
+ *
  * `lang` 参数（zh 默认）控制错误消息与峰谷文案的语言；UI 其余文案由
  * client 端（DSH locale 服务）本地化。
  *
- * 单价数据源（0.5.0 起）：
+ * 单价数据源（0.7.0 起，三层：remote → file → seed）：
+ * - 本地价格配置表（lib/pricing-store.js）：`<DSH_HOME>/dsh-deepseek-usage/pricing.json`
+ *   （可用 DEEPSEEK_USAGE_PRICE_FILE 覆盖）。插件启动时先读它并注入 pricing.setFilePrices()，
+ *   所以**重启后卡片立刻就有价格**（上次同步到的官方价 / 用户手改的价），不会再退回内置表。
+ *   首次运行会把内置快照写进该文件，方便用户直接编辑；文件被手改后无需重启，下次请求
+ *   （点击卡片即可）会按 mtime 自动重载。
  * - 默认从 DeepSeek 官方"模型 & 价格"页自动同步（lib/pricing-remote.js）：
  *   每天首次成功同步一次，失败按 10 分钟退避重试；请求带 refresh=1（点击卡片）
- *   时立即重拉并等待结果，便于官方刚调价后手动跟新。
+ *   时立即重拉并等待结果，便于官方刚调价后手动跟新。同步成功后**合并回写**本地价格表
+ *   （官方页列出的模型覆盖同名条目，用户自加条目保留），下次重启即可直接用。
  * - 解析优先走"结构化表格"策略（对官方改版排版不敏感），失败再退回文本策略；
- *   两者都失败才使用内置种子表（lib/pricing.js）。
- * - 拉取/解析失败不打扰用户：记录日志、保留上次成功数据或内置表，并通过
+ *   两者都失败才使用上一层的价格（本地表 / 内置种子表 lib/pricing.js）。
+ * - 拉取/解析失败不打扰用户：记录日志、保留上次成功数据或本地/内置表，并通过
  *   pricing.syncOk / pricing.source 让界面提示"当前价格未同步"，不静默展示旧价。
- * - 官方改名的旧模型 id（如 deepseek-v4-flash）按 MODEL_ALIASES 映射到现名计价。
- *   峰谷时段（周一至周五 9–12、14–18，北京时间）见 lib/pricing.js。
+ * - 本地价格表里 autoUpdate=false 即"手动模式"：完全不联网，档单价完全以该表为准。
+ * - 官方改名的旧模型 id（如 deepseek-v4-flash）按 MODEL_ALIASES / 价格表 aliases 映射到
+ *   现名计价。峰谷时段（周一至周五 9–12、14–18，北京时间）见 lib/pricing.js。
  *
  * 数据源：余额来自 DeepSeek 官方 GET /user/balance（API Key 经凭证服务解析，
  * 与 llm-deepseek 同一引用，不出本机）。本插件仅支持 DeepSeek 官方平台余额显示。
@@ -41,11 +54,17 @@ import {
   DEFAULT_MODEL,
   PEAK_HOURS_TEXT,
   PEAK_HOURS_TEXT_EN,
+  filePriceMeta,
   isPeak,
+  nextChange,
   remotePriceMeta,
+  seedAliases,
+  seedPrices,
+  setFilePrices,
   setRemotePrices,
   unitAt,
 } from "./pricing.js";
+import { loadPriceTable, priceTableStat, savePriceTable } from "./pricing-store.js";
 import { fetchOfficialPrices } from "./pricing-remote.js";
 
 const name = "dsh-deepseek-usage";
@@ -71,19 +90,18 @@ const JSON_HEADERS = {
   "cache-control": "no-store",
 };
 
-/** 错误消息字典（zh/en）。 */
+/** 错误消息字典（zh/en）。只保留"余额为什么拿不到"这类用户能理解、且需要行动的信息；
+ *  插件内部细节（计价来源、同步状态等）不再作为错误推给界面。 */
 const MESSAGES = {
   zh: {
     noKey: "未配置 DEEPSEEK_API_KEY",
     balanceHttp: (status) => `余额接口 HTTP ${status}`,
     balanceFail: (detail) => `余额获取失败: ${detail}`,
-    modelUnknown: (model) => `当前模型 ${model} 不在价格表，档单价按 deepseek-chat 展示`,
   },
   en: {
     noKey: "DEEPSEEK_API_KEY is not configured",
     balanceHttp: (status) => `Balance API HTTP ${status}`,
     balanceFail: (detail) => `Failed to fetch balance: ${detail}`,
-    modelUnknown: (model) => `Model ${model} is not in the price table, showing deepseek-chat pricing`,
   },
 };
 
@@ -95,6 +113,130 @@ let lastForcedAt = 0;        // 上次手动重拉时刻
 /** 同步状态（透出到界面：同步失败时让用户看到"当前是内置/旧价"，而不是静默展示）。 */
 let remoteStatus = { ok: false, at: 0, error: null, models: 0, strategy: null };
 
+// ---- 本地价格配置表状态（进程内镜像；文件才是持久层，见 lib/pricing-store.js） ----
+/** 本地价格表当前状态：路径 / 上次写入时间 / mtime（探测手改）/ 模型数 / 是否自动同步。 */
+let fileState = { path: "", exists: false, updatedAt: null, updatedFrom: null, mtimeMs: 0, models: 0, autoUpdate: true };
+
+/** 把一份读取结果注入 pricing 层，并刷新进程内镜像。 */
+function applyPriceFile(loaded, mtimeMs) {
+  const table = loaded.table;
+  setFilePrices(
+    table.models,
+    {
+      path: loaded.path,
+      updatedAt: table.updatedAt,
+      source: table.updatedFrom,
+      strategy: table.strategy,
+      autoUpdate: table.autoUpdate,
+      version: table.version,
+    },
+    table.aliases,
+  );
+  fileState = {
+    path: loaded.path,
+    exists: true,
+    updatedAt: table.updatedAt,
+    updatedFrom: table.updatedFrom,
+    mtimeMs: mtimeMs ?? priceTableStat({ path: loaded.path }).mtimeMs,
+    models: Object.keys(table.models).length,
+    autoUpdate: table.autoUpdate !== false,
+  };
+  return fileState;
+}
+
+/**
+ * 启动时载入本地价格配置表：有 → 直接注入（重启后卡片立刻有价）；没有 → 用内置快照
+ * 生成一份，让用户有个可直接编辑的起点；损坏 → 只记日志、不覆盖文件（避免毁掉用户
+ * 正在编辑的内容），内存里仍用内置快照兜底。
+ */
+function initPriceFile(ctx) {
+  const loaded = loadPriceTable();
+  fileState.path = loaded.path;
+  for (const warning of loaded.warnings ?? []) ctx.logger.warn(`dsh-deepseek-usage: ${warning}`);
+
+  if (loaded.table) {
+    applyPriceFile(loaded);
+    if (loaded.table.autoUpdate === false) {
+      ctx.logger.info(`dsh-deepseek-usage: 已载入本地价格表 ${loaded.path}（${fileState.models} 个模型，手动模式：不再联网同步）`);
+    } else {
+      ctx.logger.info(
+        `dsh-deepseek-usage: 已载入本地价格表 ${loaded.path}（${fileState.models} 个模型，上次写入 ${fileState.updatedAt ? new Date(fileState.updatedAt).toISOString() : "未知"}）`,
+      );
+    }
+    return;
+  }
+
+  const seed = { models: seedPrices(), aliases: seedAliases() };
+  if (loaded.exists) {
+    ctx.logger.warn(`dsh-deepseek-usage: 本地价格表无法解析（${loaded.error}），本次先用内置快照，文件未被覆盖：${loaded.path}`);
+    setFilePrices(seed.models, { path: loaded.path, updatedAt: null, source: "built-in", strategy: "seed", autoUpdate: true }, seed.aliases);
+    fileState = {
+      ...fileState,
+      exists: true,
+      updatedFrom: "built-in",
+      models: Object.keys(seed.models).length,
+      autoUpdate: true,
+      mtimeMs: priceTableStat({ path: loaded.path }).mtimeMs, // 用户改好文件后 mtime 变化即可自动重载
+    };
+    return;
+  }
+
+  try {
+    const written = savePriceTable({
+      models: seed.models,
+      aliases: seed.aliases,
+      updatedAt: Date.now(),
+      updatedFrom: "built-in",
+      strategy: "seed",
+      autoUpdate: true,
+    });
+    applyPriceFile({ path: written.path, table: written.doc });
+    ctx.logger.info(`dsh-deepseek-usage: 未找到本地价格表，已用内置快照生成 ${written.path}（可手动编辑，autoUpdate=false 可关闭自动同步）`);
+  } catch (error) {
+    ctx.logger.warn(`dsh-deepseek-usage: 无法写入本地价格表 ${loaded.path}（${error instanceof Error ? error.message : String(error)}），本次用内置快照`);
+    setFilePrices(seed.models, { path: loaded.path, updatedAt: null, source: "built-in", strategy: "seed", autoUpdate: true }, seed.aliases);
+    fileState = { ...fileState, updatedFrom: "built-in", models: Object.keys(seed.models).length };
+  }
+}
+
+/**
+ * 手改价格表后免重启生效：每次请求先比 mtime，变了就重载（一次 stat，成本可忽略）。
+ * 只重载"能解析"的文件；解析失败保持现状并记日志。
+ */
+function reloadPriceFileIfChanged(ctx) {
+  if (!fileState.path) return;
+  const stat = priceTableStat({ path: fileState.path });
+  if (!stat.exists || stat.mtimeMs === fileState.mtimeMs) return;
+  const loaded = loadPriceTable({ path: fileState.path });
+  if (!loaded.table) {
+    fileState.mtimeMs = stat.mtimeMs; // 别每请求都重读坏文件
+    ctx.logger.warn(`dsh-deepseek-usage: 本地价格表改动后无法解析，继续用上一次的价格：${loaded.error}`);
+    return;
+  }
+  applyPriceFile(loaded, stat.mtimeMs);
+  for (const warning of loaded.warnings ?? []) ctx.logger.warn(`dsh-deepseek-usage: ${warning}`);
+  ctx.logger.info(`dsh-deepseek-usage: 本地价格表已重新载入 ${fileState.path}（${fileState.models} 个模型）`);
+}
+
+/**
+ * 把官方同步结果合并回写本地价格表（官方页列出的模型覆盖同名条目，用户自加条目保留），
+ * 并同步刷新内存里的 file 层——这样"这次同步失败"的后续请求也还能用上最新一份官方价。
+ */
+function persistOfficialPrices(ctx, models, meta) {
+  try {
+    const written = savePriceTable({
+      models,
+      updatedAt: meta.fetchedAt || Date.now(),
+      updatedFrom: meta.source,
+      strategy: meta.strategy,
+    });
+    applyPriceFile({ path: written.path, table: written.doc }, priceTableStat({ path: written.path }).mtimeMs);
+    ctx.logger.info(`dsh-deepseek-usage: 官方价格已回写本地价格表 ${written.path}（共 ${fileState.models} 个模型）`);
+  } catch (error) {
+    ctx.logger.warn(`dsh-deepseek-usage: 官方价格回写本地价格表失败（本次仍按内存里的官方价显示）：${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 /** 北京时间日期键（yyyy-mm-dd）。 */
 function beijingDayKey(ms) {
   const d = new Date(ms + SHANGHAI_OFFSET_MS);
@@ -106,10 +248,13 @@ function beijingDayKey(ms) {
 /**
  * 保证官方价格已同步：每天首次自动拉取一次，失败则按 RETRY_GAP_MS 退避重试；
  * force（点击卡片 refresh=1）时立即重拉并等待。
- * 拉取成功 → pricing.setRemotePrices() 注入；失败 → 记日志并记录状态，
- * 继续用内置/上次数据，同时把失败状态透出到界面。
+ * 拉取成功 → pricing.setRemotePrices() 注入 + 合并回写本地价格表；失败 → 记日志并记录
+ * 状态，继续用本地表/上次数据，同时把失败状态透出到界面。
+ * 注意：非强制（自动）路径不在请求内等待拉取结果，界面用 pricing.syncing 表示"正在同步"，
+ * 免得把一次正常的后台刷新误报成"未同步"。
  */
 async function refreshRemote(ctx, force) {
+  if (!fileState.autoUpdate) return;                         // 手动模式：完全不联网
   const now = Date.now();
   if (!force) {
     if (remoteDay === beijingDayKey(now)) return;            // 今天已成功同步过
@@ -137,10 +282,11 @@ async function refreshRemote(ctx, force) {
       ctx.logger.info(
         `dsh-deepseek-usage: 官方价格已同步（${Object.keys(models).length} 个模型，策略 ${meta.strategy}，来源 ${meta.source}）`,
       );
+      persistOfficialPrices(ctx, models, meta);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       remoteStatus = { ...remoteStatus, ok: false, error: message };
-      ctx.logger.warn(`dsh-deepseek-usage: 官方价格同步失败，沿用内置/上次价格: ${message}`);
+      ctx.logger.warn(`dsh-deepseek-usage: 官方价格同步失败，沿用本地价格表/上次价格: ${message}`);
     } finally {
       remoteInFlight = null;
     }
@@ -202,6 +348,13 @@ function resolveQuery(req) {
 }
 
 function apply(ctx) {
+  // ---- 本地价格配置表：启动即载入（重启后卡片立刻有价，不再退回内置表）----
+  try {
+    initPriceFile(ctx);
+  } catch (error) {
+    ctx.logger.warn(`dsh-deepseek-usage: 载入本地价格表失败，改用内置快照：${error instanceof Error ? error.message : String(error)}`);
+  }
+
   ctx.effect(
     () => ctx.webServer.register({
       kind: "exact",
@@ -216,7 +369,14 @@ function apply(ctx) {
           const { lang, refresh } = resolveQuery(req);
           const msg = MESSAGES[lang] || MESSAGES.zh;
 
-          // ---- 官方价格自动同步（每日首次后台拉取；点击卡片强制并等待）----
+          // ---- 手改价格表免重启生效（mtime 变了才重读）----
+          try {
+            reloadPriceFileIfChanged(ctx);
+          } catch (error) {
+            ctx.logger.warn(`dsh-deepseek-usage: 重载本地价格表失败：${error instanceof Error ? error.message : String(error)}`);
+          }
+
+          // ---- 官方价格自动同步（每日首次后台拉取；点击卡片强制并等待；手动模式跳过）----
           await refreshRemote(ctx, refresh);
 
           // ---- 当前模型当前档单价（展示用）----
@@ -260,14 +420,17 @@ function apply(ctx) {
             errors.push(msg.balanceFail(error instanceof Error ? error.message : String(error)));
           }
 
-          // ---- 档单价提示（未知模型回退 chat 档）----
-          if (!unit.known) errors.push(msg.modelUnknown(model));
+          // ---- 档单价：未知模型静默回退 chat 档（属内部兜底，不再作为错误推给界面）----
+          const next = nextChange(now);
 
           sendJson(res, 200, {
             ok: true,
             balance,
             peak: isPeak(now),
             peakHours: lang === "en" ? PEAK_HOURS_TEXT_EN : PEAK_HOURS_TEXT,
+            // 距下一次峰谷切换的剩余时间（界面用它在指示灯旁显示倒计时）：
+            //   peak = 切换后所处的时段，at = 切换时刻，ms = 剩余毫秒
+            next,
             tier: {
               input: unit.input,
               cacheRead: unit.cacheRead,
@@ -276,19 +439,32 @@ function apply(ctx) {
               model: unit.model,
               known: unit.known,
             },
-            // 价格来源与同步状态：让"官方页改版/网络失败 → 正在用内置旧价"可见，
-            // 而不是静默按过期价格展示。
+            // 【内部诊断】价格来源与同步状态：界面不再展示（卡片去技术化），保留字段
+            // 供排查问题与回归测试使用。
             pricing: {
-              source: unit.source,                  // remote=官方页同步 / seed=内置兜底
-              via: unit.via,                        // remote | remote-alias | remote-family | alias | seed | fallback
+              source: unit.source,                  // remote=本次官方页同步 / file=本地价格表 / seed=内置兜底
+              via: unit.via,                        // remote* | file* | alias | seed | fallback
               requested: unit.requested,            // 当前启用的模型 id
               used: unit.model,                     // 实际取价使用的模型 id
+              mode: fileState.autoUpdate ? "auto" : "manual", // manual=价格表 autoUpdate:false，不联网
+              syncing: remoteInFlight !== null,      // 后台正在拉官方页（别误报成"未同步"）
               syncOk: remoteStatus.ok,
               syncedAt: remoteStatus.at || null,
+              layerAt: unit.layerAt,                 // 当前这份单价所属层的时间戳（remote/file）
               strategy: remoteStatus.strategy,      // table=结构化表格 / flat=文本兜底
               modelCount: remoteStatus.models,
               syncError: remoteStatus.error,
               remoteMeta: remotePriceMeta(),
+              // 本地价格配置表（用户可编辑；路径透出给界面，方便知道去哪儿改价）
+              file: fileState.path
+                ? {
+                    path: fileState.path,
+                    updatedAt: fileState.updatedAt,
+                    updatedFrom: fileState.updatedFrom,
+                    autoUpdate: fileState.autoUpdate,
+                    models: fileState.models,
+                  }
+                : null,
             },
             updatedAt: now,
             errors,

package/lib/pricing-store.js

@@ -0,0 +1,253 @@
+/**
+ * dsh-deepseek-usage — 本地价格配置表（磁盘文件，lib/pricing.js 的数据源之一）。
+ *
+ * 为什么有这一层：价格同步状态原来只活在进程内存里，dsh 一重启就没了，于是重启后
+ * 的第一张卡片只能用代码内置的价格表（表现为"价格未同步（用内置表）"）。现在把
+ * "模型 → 档单价"从代码里抽出来存成配置文件：
+ *
+ *   启动  → 读本文件（上次同步到的官方价 / 用户手改的价）→ 卡片立刻有价
+ *   每天/点击 → 拉官方价格页 → 合并回写本文件（官方条目覆盖同名项，用户自加条目保留）
+ *
+ * 路径解析优先级：
+ *   1. 环境变量 DEEPSEEK_USAGE_PRICE_FILE（显式指定，测试/多实例用）
+ *   2. <DSH_HOME|~/.dsh>/dsh-deepseek-usage/pricing.json
+ *
+ * 文件格式（JSON；允许**整行** `//` 注释，方便手改）：
+ * {
+ *   "version": 1,
+ *   "autoUpdate": true,             // false = 手动模式：不再联网同步，直接用本表
+ *   "updatedAt": 1789090582880,     // 上次写入时间（ms；也接受 ISO 字符串）
+ *   "updatedFrom": "https://api-docs.deepseek.com/zh-cn/quick_start/pricing/",
+ *   "strategy": "table",            // 官方页解析策略（table=结构化表格 / flat=文本兜底 / seed=内置快照）
+ *   "aliases": { "deepseek-v4-flash": "deepseek-flash" },
+ *   "models": {
+ *     "deepseek-flash": { "input": [2, 1], "cacheRead": [0.04, 0.02], "cacheWrite": 0, "output": [8, 4] }
+ *   }
+ * }
+ * 单价单位：元 / 百万 tokens；input / cacheRead / output 均为 [高峰, 空闲] 两档
+ * （cacheWrite 目前官方不计费，恒 0）。也接受"整个文件就是模型映射"的简写形式：
+ * { "deepseek-flash": { "input": [2, 1], ... } }
+ *
+ * 写入策略：读-改-写 + 原子替换（先写同目录 .tmp 再 rename），避免半截文件。
+ * 本文件不做任何网络访问，也不含运行时状态（解析 → 返回，交给调用方注入）。
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** 价格表文件格式版本（结构不兼容时递增）。 */
+export const PRICE_FILE_VERSION = 1;
+/** 价格表路径覆盖（便于测试与多实例）。 */
+const FILE_ENV = "DEEPSEEK_USAGE_PRICE_FILE";
+/** DSH 家目录覆盖（与 dsh-home-paths 的约定一致）。 */
+const HOME_ENV = "DSH_HOME";
+/** 插件在 DSH 家目录下的子目录 / 文件名。 */
+const DIR_NAME = "dsh-deepseek-usage";
+const FILE_NAME = "pricing.json";
+
+/** 写进文件的格式说明（JSON 无注释，只能占一个字段）。 */
+const FILE_COMMENT =
+  "dsh-deepseek-usage 价格表：input/cacheRead/output 为 [高峰, 空闲] 两档单价，单位 元/百万 tokens；"
+  + "autoUpdate=true 时插件每天首次使用（或点击卡片）会拉取官方价格页并回写本文件——"
+  + "官方页列出的模型覆盖同名条目，你自己加的条目保留；autoUpdate=false 表示不再联网同步，完全以本表为准。"
+  + "允许整行 // 注释。";
+
+/** 当前生效的价格表路径（env > DSH_HOME/dsh-deepseek-usage/pricing.json > ~/.dsh/...）。 */
+export function defaultPriceFilePath() {
+  const fromEnv = process.env[FILE_ENV];
+  if (typeof fromEnv === "string" && fromEnv.trim() !== "") return fromEnv.trim();
+  const home = process.env[HOME_ENV];
+  const base = typeof home === "string" && home.trim() !== "" ? home.trim() : join(homedir(), ".dsh");
+  return join(base, DIR_NAME, FILE_NAME);
+}
+
+/** 只剥掉"整行 //"注释：URL 里的 `//` 在行中间，不会被误伤。 */
+function stripLineComments(text) {
+  return text
+    .split(/\r?\n/)
+    .map((line) => (/^\s*\/\//.test(line) ? "" : line))
+    .join("\n");
+}
+
+/** [高峰, 空闲] 二元组校验。 */
+const okPair = (v) => Array.isArray(v) && v.length === 2 && v.every((n) => Number.isFinite(n) && n >= 0);
+
+/** 时间容忍数字（ms）/ ISO 字符串。 */
+function toMs(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isFinite(n) && n > 0) return n;
+    const t = Date.parse(value);
+    if (Number.isFinite(t)) return t;
+  }
+  return null;
+}
+
+/** 清洗模型映射：非法条目丢弃并记入 dropped（缺失的档位回退到 input 档）。 */
+function cleanModels(raw) {
+  const models = {};
+  const dropped = [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { models, dropped };
+  for (const [id, entry] of Object.entries(raw)) {
+    if (typeof id !== "string" || id === "" || !entry || typeof entry !== "object" || Array.isArray(entry)) {
+      dropped.push(String(id));
+      continue;
+    }
+    const input = okPair(entry.input) ? entry.input.slice() : null;
+    if (!input) {
+      dropped.push(id);
+      continue;
+    }
+    const cacheWrite = Number(entry.cacheWrite);
+    models[id] = {
+      input,
+      cacheRead: okPair(entry.cacheRead) ? entry.cacheRead.slice() : input.slice(),
+      cacheWrite: Number.isFinite(cacheWrite) && cacheWrite >= 0 ? cacheWrite : 0,
+      output: okPair(entry.output) ? entry.output.slice() : input.slice(),
+    };
+  }
+  return { models, dropped };
+}
+
+/** 清洗别名映射（旧名 → 现名）。 */
+function cleanAliases(raw) {
+  const aliases = {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return aliases;
+  for (const [from, to] of Object.entries(raw)) {
+    if (typeof from === "string" && from !== "" && typeof to === "string" && to !== "") aliases[from] = to;
+  }
+  return aliases;
+}
+
+/** 按键名排序（让文件 diff 稳定、便于人读）。 */
+function sorted(obj) {
+  return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/**
+ * 解析价格表 JSON 文本。
+ * @throws 根节点/模型条目完全不合法时抛错（调用方据此判定"文件损坏"）。
+ * @returns {{ doc: { version, autoUpdate, updatedAt, updatedFrom, strategy, aliases, models }, dropped: string[] }}
+ */
+export function parsePriceTable(text) {
+  const raw = JSON.parse(stripLineComments(String(text)));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("价格表根节点必须是对象");
+
+  // 显式结构（带 models/autoUpdate/... 字段）与简写结构（整个文件就是模型映射）都支持。
+  const explicit = ["models", "aliases", "autoUpdate", "updatedAt", "updatedFrom", "strategy", "version"].some(
+    (k) => raw[k] !== undefined,
+  );
+  const { models, dropped } = cleanModels(explicit ? raw.models : raw);
+  if (Object.keys(models).length === 0) {
+    throw new Error("价格表里没有可用模型条目（每项至少要有 input: [高峰, 空闲]）");
+  }
+  return {
+    doc: {
+      version: Number.isFinite(Number(raw.version)) ? Number(raw.version) : PRICE_FILE_VERSION,
+      autoUpdate: raw.autoUpdate !== false,
+      updatedAt: toMs(raw.updatedAt),
+      updatedFrom: typeof raw.updatedFrom === "string" && raw.updatedFrom !== "" ? raw.updatedFrom : null,
+      strategy: typeof raw.strategy === "string" && raw.strategy !== "" ? raw.strategy : null,
+      aliases: explicit ? sorted(cleanAliases(raw.aliases)) : {},
+      models: sorted(models),
+    },
+    dropped,
+  };
+}
+
+/**
+ * 读取价格表文件。
+ * @returns {{ path: string, exists: boolean, error: string|null, table: object|null, warnings: string[] }}
+ *   exists=false 表示文件不存在（首次运行，error 为 null）；table=null 且 error 非空表示文件损坏。
+ */
+export function loadPriceTable(options = {}) {
+  const path = options.path ?? defaultPriceFilePath();
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    const code = error && typeof error === "object" ? error.code : void 0;
+    return {
+      path,
+      exists: false,
+      error: code === "ENOENT" ? null : error instanceof Error ? error.message : String(error),
+      table: null,
+      warnings: [],
+    };
+  }
+  try {
+    const { doc, dropped } = parsePriceTable(text);
+    return {
+      path,
+      exists: true,
+      error: null,
+      table: doc,
+      warnings: dropped.length > 0 ? [`忽略 ${dropped.length} 个无法解析的模型条目：${dropped.join(", ")}`] : [],
+    };
+  } catch (error) {
+    return {
+      path,
+      exists: true,
+      error: error instanceof Error ? error.message : String(error),
+      table: null,
+      warnings: [],
+    };
+  }
+}
+
+/** 文件状态（用于"手改价格表后免重启生效"的变更探测）。 */
+export function priceTableStat(options = {}) {
+  const path = options.path ?? defaultPriceFilePath();
+  try {
+    const st = statSync(path);
+    return { path, exists: true, mtimeMs: st.mtimeMs, size: st.size };
+  } catch {
+    return { path, exists: false, mtimeMs: 0, size: 0 };
+  }
+}
+
+/**
+ * 合并写回价格表：patch.models / patch.aliases 覆盖同名项，其余条目（含用户自加模型）
+ * 保留；未给出的字段沿用磁盘上的旧值。写盘为"临时文件 + rename"原子替换。
+ * @returns {{ path: string, doc: object }}
+ */
+export function savePriceTable(patch = {}, options = {}) {
+  const path = options.path ?? defaultPriceFilePath();
+  const base = loadPriceTable({ path }).table ?? {
+    version: PRICE_FILE_VERSION,
+    autoUpdate: true,
+    updatedAt: null,
+    updatedFrom: null,
+    strategy: null,
+    aliases: {},
+    models: {},
+  };
+  const { models } = cleanModels({ ...base.models, ...(patch.models ?? {}) });
+  const aliases = cleanAliases({ ...base.aliases, ...(patch.aliases ?? {}) });
+  const doc = {
+    $comment: FILE_COMMENT,
+    version: PRICE_FILE_VERSION,
+    autoUpdate: patch.autoUpdate ?? base.autoUpdate ?? true,
+    updatedAt: patch.updatedAt ?? Date.now(),
+    updatedFrom: patch.updatedFrom ?? base.updatedFrom ?? null,
+    strategy: patch.strategy ?? base.strategy ?? null,
+    aliases: sorted(aliases),
+    models: sorted(models),
+  };
+
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+  try {
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      /* 清理失败不影响报错 */
+    }
+    throw error;
+  }
+  return { path, doc };
+}