@dougen/dsh-deepseek-usage 0.6.1 → 0.7.0

package/README.md

@@ -10,21 +10,23 @@ DeepSeek **余额侧边栏插件**（DeepSeek Harness Web UI）：在 DSH **网
 
 - **Balance**: `¥ 110.00` large display (symbol follows account currency: `¥` CNY / `$` USD)
 - **Unit pricing**: `→|1.5 ⚡0.05 |→4.5` (input / input cache / output, bottom-right of the card; switches with the active model and peak/off-peak window — **updates instantly when you switch models**)
-- **Auto price sync**: unit prices are re-fetched from the official DeepSeek pricing page on first use each day and when you click the card — DeepSeek price changes no longer require a plugin update. The page is parsed **structurally (HTML table cells)**, not by matching surrounding text, so official layout/rewording changes no longer break it; a plain-text strategy remains as a fallback
-- **Rename-proof model mapping**: when DeepSeek renames a model (e.g. `deepseek-v4-flash` → `deepseek-flash`) the old id is charged at the current model's price, and the card notes `Priced as deepseek-flash` instead of silently showing an outdated built-in price
-- **Visible sync state**: if the official page cannot be fetched/parsed, the card is blanked and says prices are not synced (hover for the error) instead of quietly showing stale built-in numbers
+- **Editable price table**: prices live in a JSON file (`<DSH_HOME>/dsh-deepseek-usage/pricing.json`), not in code. The plugin reads it at startup, so the card prices correctly **immediately after a restart**, and a successful official sync is written back into it. Hand-edit it for a gateway/manual pricing; changes apply without restarting (`autoUpdate: false` also turns the automatic sync off completely)
+- **Auto price sync**: prices are re-fetched from the official DeepSeek pricing page on first use each day and when you click the card; the result is merged back into the price table (official entries overwrite same-named ones, your own entries are kept). The page is parsed **structurally (HTML table cells)**, not by matching surrounding text, so official layout/rewording changes no longer break it; a plain-text strategy remains as a fallback
+- **Rename-proof model mapping**: when DeepSeek renames a model (e.g. `deepseek-v4-flash` → `deepseek-flash`) the old id is charged at the current model's price, and the card notes `Priced as deepseek-flash` instead of silently showing an outdated price
+- **Visible sync state**: if the official page cannot be fetched/parsed, the card is blanked and says which prices it is using (hover for the error and the last sync time) instead of quietly showing stale numbers
 - **Peak indicator**: top-right dot, orange during peak hours (Mon–Fri 9:00–12:00, 14:00–18:00 Beijing Time), green otherwise
-- **Auto refresh**: every 5 minutes; click the card to refresh instantly
+- **Auto refresh**: every 5 minutes; click the card to refresh instantly — plus a few quick retries while the host is still syncing, so the card converges within seconds
 - **i18n**: UI copy follows the DSH locale (Chinese / English)
 - Follows the app light/dark theme
 
 - **余额**：`¥ 110.00` 大字显示（符号随账号币种自动切换：人民币 `¥` / 美元 `$`）
 - **档单价**：`→|1.5 ⚡0.05 |→4.5`（输入 / 输入缓存 / 输出，位于卡片右下角；随当前启用模型与峰谷时段自动切换，**切换模型时立即同步**）
-- **单价自动同步**：每日首次使用或点击卡片时，自动从官方价格页拉取最新档单价；官方调价无需更新插件。页面解析采用**结构化表格解析**（直接读 HTML 表格单元格），不再依赖"正文里某段文字长什么样"，官方改版/改文案不会失效；另保留纯文本兜底策略
-- **抗改名映射**：官方给模型改名（如 `deepseek-v4-flash` → `deepseek-flash`）时，旧名按现名价格计费，卡片会注明 `按 deepseek-flash 计价`，不会静默显示内置旧价
-- **同步状态可见**：官方页抓取/解析失败时，卡片会置空并提示"价格未同步"（悬停可看具体错误），而不是悄悄显示内置旧价
+- **可编辑的价格表**：价格不再写在代码里，而是存在 JSON 文件 `<DSH_HOME>/dsh-deepseek-usage/pricing.json`。插件启动时先读它，所以**重启后卡片立刻就是正确价格**；官方同步成功后会自动回写到这份表里。手改该文件即可用于中转/手动计价，改完**无需重启**（`autoUpdate: false` 还能彻底关掉自动同步）
+- **单价自动同步**：每日首次使用或点击卡片时，自动从官方价格页拉取最新档单价，并把结果**合并回写**到价格表（官方条目覆盖同名项，你自己加的条目保留）。页面解析采用**结构化表格解析**（直接读 HTML 表格单元格），不再依赖"正文里某段文字长什么样"，官方改版/改文案不会失效；另保留纯文本兜底策略
+- **抗改名映射**：官方给模型改名（如 `deepseek-v4-flash` → `deepseek-flash`）时，旧名按现名价格计费，卡片会注明 `按 deepseek-flash 计价`，不会静默显示旧价
+- **同步状态可见**：官方页抓取/解析失败时，卡片会置空并说明当前用的是哪份价（悬停可看具体错误与上次同步时间），而不是悄悄显示旧价
 - **峰谷指示灯**：卡片右上角，高峰（周一至周五 9:00–12:00、14:00–18:00 北京时间）橙色，空闲绿色
-- **自动刷新**：每 5 分钟一次；点击卡片任意位置立即刷新
+- **自动刷新**：每 5 分钟一次；点击卡片任意位置立即刷新；宿主正在后台同步时还会在几秒内快速补几次请求，卡片很快收敛到最新官方价
 - **多语言**：界面文案跟随 DSH 语言（中文 / English）
 - 跟随应用明暗主题
 
@@ -53,17 +55,51 @@ Restart the web app (`dsh web`), open http://127.0.0.1:3080 , and the usage card
 | Data | Source |
 |---|---|
 | Balance | Official DeepSeek API `GET /user/balance` (uses `DEEPSEEK_API_KEY` configured in DSH) |
-| Unit pricing / peak window | Auto-synced from the official pricing page (fetched on first daily use and on card click: [api-docs.deepseek.com/zh-cn/quick_start/pricing](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/)); parsed from the HTML **table cells** (text fallback available); built-in table (current official snapshot) as offline fallback |
+| Unit pricing | Local price table `<DSH_HOME>/dsh-deepseek-usage/pricing.json` (read at startup; editable). Refreshed from the official page ([api-docs.deepseek.com/zh-cn/quick_start/pricing](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/)) on first daily use or on card click, then written back. Parsed from the HTML **table cells** (text fallback available); the built-in snapshot in code is only the seed for the very first run |
+| Peak window | Built-in official rule: Mon–Fri 9:00–12:00, 14:00–18:00 Beijing Time (weekends are always off-peak) |
 
 | 数据 | 来源 |
 |---|---|
 | 余额 | DeepSeek 官方 API `GET /user/balance`（使用 DSH 中已配置的 `DEEPSEEK_API_KEY`） |
-| 档单价 / 峰谷时段 | 自动从官方价格页同步（每日首次使用或点击卡片时拉取 [api-docs.deepseek.com/zh-cn/quick_start/pricing](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/)）；解析**官方页 HTML 表格单元格**（另有纯文本兜底策略）；内置价格表仅作离线兜底 |
+| 档单价 | 本地价格表 `<DSH_HOME>/dsh-deepseek-usage/pricing.json`（启动即读取，可手动编辑）；每日首次使用或点击卡片时从官方价格页 [api-docs.deepseek.com/zh-cn/quick_start/pricing](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/) 同步并**回写**该表。官方页解析**读取 HTML 表格单元格**（另有纯文本兜底策略）；代码里的内置快照只在首次运行时用于生成价格表 |
+| 峰谷时段 | 内置官方口径：周一至周五 9:00–12:00、14:00–18:00（北京时间），周末恒为空闲 |
 
 Make sure `DEEPSEEK_API_KEY` is configured in DSH (Model settings page) before use.
 
 使用前请确保 DSH 已配置 `DEEPSEEK_API_KEY`（可在 DSH 设置中的模型页面配置）。
 
+## Price table / 价格表
+
+`<DSH_HOME>/dsh-deepseek-usage/pricing.json` (default `~/.dsh/dsh-deepseek-usage/pricing.json`; override with `DEEPSEEK_USAGE_PRICE_FILE`). Created from the built-in snapshot on first run, then maintained by the plugin:
+
+```jsonc
+{
+  "autoUpdate": true,            // false = manual mode: never fetch, use this table as-is
+  "updatedAt": 1789090582880,    // last write (ms or ISO string)
+  "updatedFrom": "https://api-docs.deepseek.com/zh-cn/quick_start/pricing/",
+  "strategy": "table",           // table | flat | seed
+  "aliases": { "deepseek-v4-flash": "deepseek-flash" },   // old id → current id
+  "models": {
+    // input / cacheRead / output are [peak, off-peak] in CNY per 1M tokens
+    "deepseek-flash": { "input": [2, 1], "cacheRead": [0.04, 0.02], "cacheWrite": 0, "output": [8, 4] }
+  }
+}
+```
+
+- Full-line `//` comments are allowed; a bare `{"model-id": {...}}` map (no `models` wrapper) also works.
+- Every successful official sync **merges** into this file: official entries overwrite same-named ones, your own entries stay.
+- Edits are picked up without restarting the plugin (the file's mtime is checked per request).
+- If the file is corrupt, the plugin keeps the last good prices and **never overwrites** it — fix it and it reloads.
+- The card's peak-dot tooltip shows the file path and the time the displayed prices came from.
+
+价格表文件位于 `<DSH_HOME>/dsh-deepseek-usage/pricing.json`（默认 `~/.dsh/dsh-deepseek-usage/pricing.json`，可用 `DEEPSEEK_USAGE_PRICE_FILE` 覆盖）。首次运行由内置快照生成，之后由插件维护：
+
+- 允许**整行** `//` 注释；也接受省略 `models` 外壳的简写形式 `{"deepseek-flash": {...}}`。
+- 每次官方同步成功都会**合并回写**本文件：官方页列出的模型覆盖同名条目，你自己加的条目保留。
+- 手改后无需重启（每次请求会比对文件 mtime），改完点一下卡片即生效。
+- 文件损坏时不会覆盖你的内容，会继续用上一次的价格并写日志；修好后自动重载。
+- 卡片峰谷灯的悬停提示里会显示该文件路径，以及当前这份价是什么时候同步的。
+
 ## FAQ / 常见问题
 
 **Balance shows "—"? / 余额显示"—"？**
@@ -76,25 +112,33 @@ Make sure `DEEPSEEK_API_KEY` is configured in DSH (Model settings page) before u
 
 **Price differs from the official one? / 单价与官方价格不一致？**
 
-- The unit price switches with the **active model** and the **peak/off-peak window**; prices are re-synced from the official pricing page daily (first use) or on card click. If the active model is not on the official page nor in the built-in table, `deepseek-chat` pricing is shown with a notice.
-- Any such notice (or an error) blanks the card: balance, unit prices and the peak dot are hidden and only the notice text is shown (hover it for the exact error). Purely informational notices (priced as a renamed or built-in model) are dismissable: **click the card to flip back to the normal balance/price card** — the notice stays reachable from the peak dot's tooltip, and clicking again brings it back. Sync failures and API errors always keep the card blanked; there, clicking only refreshes. The text tells you where the number comes from:
-  - *Prices not synced (built-in table)* — the official page could not be fetched/parsed; click the card to retry (hover the text for the exact error).
+- The unit price switches with the **active model** and the **peak/off-peak window**. Prices come from the local price table (last successful official sync, or your own edits); the plugin re-syncs the official page on first daily use or on card click and writes the result back into that table.
+- If a notice or an error appears, the card is blanked: balance, unit prices and the peak dot are hidden and only the notice text is shown (hover it for the exact error / last sync time). Purely informational notices (priced as a renamed model) are dismissable: **click the card to flip back to the normal balance/price card** — the notice stays reachable from the peak dot's tooltip. Sync failures and API errors always keep the card blanked; there, clicking only refreshes. The text tells you where the number comes from:
+  - *Prices not synced (built-in table)* — no usable price table **and** the official page could not be fetched/parsed; click the card to retry (hover for the error).
+  - *Sync failed; using last prices (09-11 09:36)* — the price table has the last good official prices; only the refresh failed.
   - *Priced as `deepseek-flash`* — the active model id was renamed by DeepSeek; the current model's price is used.
-  - *Priced as built-in `…`* — the model is not listed on the official page; a built-in entry is used.
+  - *Priced as built-in `…`* — the model is neither in the official page nor in the price table; the built-in entry is used.
+- **After every `dsh` restart the card used to say "prices not synced (built-in table)"** — that was a race: sync state only lived in memory, so the first request after a restart was always answered from the built-in table. Since 0.7.0 the price table is persisted and read at startup, so restarts show real prices right away.
 
-- 单价按**当前启用模型**与**峰谷时段**自动切换；单价每日（首次使用）或点击卡片时从官方价格页同步。若当前模型不在官方价格页也不在内置表，会按 `deepseek-chat` 档展示并给出提示。
-- 一旦出现这类提示或错误，卡片会**置空**：不显示余额、档单价与峰谷灯，只显示提示文字（悬停看具体错误）。其中纯说明性的良性提示（按现名计价 / 按内置档计价）可以**点击卡片切回普通状态**（余额 + 档单价 + 峰谷灯），提示此时保留在峰谷灯的 hover 里，再点一下切回提示；同步失败与接口错误属于异常，卡片始终置空（此时点击只刷新）。文字说明数字来自哪里：
-  - *价格未同步（用内置表）*：官方页抓取/解析失败，点击卡片可重试（悬停看具体错误）。
+- 单价按**当前启用模型**与**峰谷时段**自动切换；价格取自本地价格表（上次成功同步到的官方价，或你自己改的价）。插件在每日首次使用或点击卡片时重新同步官方页，并把结果回写到该表。
+- 一旦出现提示或错误，卡片会**置空**：不显示余额、档单价与峰谷灯，只显示提示文字（悬停看具体错误与上次同步时间）。其中纯说明性的良性提示（按现名计价）可以**点击卡片切回普通状态**（余额 + 档单价 + 峰谷灯），提示此时保留在峰谷灯的 hover 里。同步失败与接口错误属于异常，卡片始终置空（此时点击只刷新）。文字说明数字来自哪里：
+  - *价格未同步（用内置表）*：既没有可用价格表，官方页也抓不到；点击卡片可重试（悬停看具体错误）。
+  - *同步失败，仍用上次价格（09-11 09:36）*：价格表里是上次同步到的官方价，只是这次刷新失败了。
   - *按 `deepseek-flash` 计价*：官方给该模型改名了，已按现名价格计费。
-  - *按内置 `…` 档计价*：该模型不在官方价格页，用了内置表。
+  - *按内置 `…` 档计价*：该模型既不在官方价格页，也不在价格表里，用了内置条目。
+- **以前每次 `dsh` 重启后卡片都会提示"价格未同步（用内置表）"**：那是竞态——同步状态只存在内存里，重启后的第一次请求只能用内置表回答。0.7.0 起价格表落盘并在启动时读取，重启后立即显示真实价格。
 
 ## Development / 开发与自检
 
 ```sh
-npm test                 # 解析 + 定价单测（node --test）
+npm test                 # 解析 + 定价 + 价格表 + 卡片布局 + 宿主路由（node --test）
 npm run check:pricing    # 联网抓取官方页并打印解析结果；失败时退出码非 0
 ```
 
+模块划分：`lib/index.js` 宿主路由（同步节流、余额、状态透出）· `lib/pricing.js` 三层价格
+（remote/file/seed）· `lib/pricing-store.js` 价格表读写（可编辑的 pricing.json）·
+`lib/pricing-remote.js` 官方页抓取与解析 · `lib/client.js` 侧边栏卡片。
+
 官方页再次改版时（自检失败 / 卡片提示"价格未同步"）：
 
 ```sh
@@ -106,11 +150,18 @@ node lib/pricing-remote.js --check --save page.html
 node lib/pricing-remote.js --check --html page.html --json
 
 # 3. 把新页面存为 test/fixtures/official-pricing-zh.html，跑 npm test 防回归
+#    （若解析出的模型集合变了，再同步更新 lib/pricing.js 里的内置快照——
+#      它只用于首次运行生成 pricing.json）
 ```
 
+> 测试里的"重启"是给模块图打 `?graph=<tag>`（见 `test/host-route.test.mjs`），每个 tag
+> 都拿到全新模块实例；peer 依赖 `@deepseek-ai/dsh-credentials` 由 `test/stubs/` 里的
+> 替身接管，所以本仓库不需要 node_modules 也能跑宿主逻辑。
+>
 > DSH 沙箱内 `node --test test/` 可能因禁止子进程管道而报 `spawn EPERM`，此时用
 > `node --test --test-isolation=none "test/*.test.mjs"`（Node ≥ 22.8），或逐个跑
-> `node test/parse.test.mjs`、`node test/pricing.test.mjs`、`node test/client-layout.test.mjs`。
+> `node test/parse.test.mjs`、`node test/pricing.test.mjs`、`node test/pricing-store.test.mjs`、
+> `node test/client-layout.test.mjs`、`node test/host-route.test.mjs`。
 
 ## Uninstall / 卸载
 

package/lib/client.js

@@ -2,9 +2,13 @@
 //
 // 侧边栏底部用量卡片（注册进 `sidebar.footer.action` 槽位，独占一行，位于
 // Cordis 面板按钮下方）。轮询宿主路由 `/api/deepseek-usage`（见 lib/index.js）
-// 每 5 分钟一次，点击卡片任意位置可立即刷新。
+// 每 5 分钟一次，点击卡片任意位置可立即刷新；宿主还在后台同步官方价
+// （pricing.syncing）时按 QUICK_RETRY_MS 阶梯快速补几次请求，卡片几秒内收敛。
 // 卡片显示：余额（放大显示，符号随币种 ¥/$）+ 当前模型档单价（输入/输入缓存/
 // 输出，图标 + 数字，位于卡片右下角）+ 峰谷指示灯（右上角）。
+// 价格来源（宿主 pricing.source）：remote=本次官方同步 / file=本地价格表
+// （重启后即用它，属正常态）/ seed=内置兜底；峰谷灯 hover 里可看到来源、
+// 上次同步时间与价格表文件路径。
 // 样式仅使用 `--dsw-*` 主题变量（含兜底值），跟随明暗主题。
 window.__ModuleLoader__.load({
 	id: "@dougen/dsh-deepseek-usage",
@@ -22,6 +26,9 @@ window.__ModuleLoader__.load({
 		// 常态卡片高度：上下 padding 8+8 + 余额行 lineHeight 28 + 边框 2 = 46。
 		// 异常态把卡片置空时用它兜住高度，侧边栏高度不跳动。
 		const CARD_MIN_HEIGHT = 46;
+		// 宿主正在后台同步官方价格（pricing.syncing）或本地接口刚重启时的快速重试节奏：
+		// 否则卡片要等满 5 分钟轮询才会从"本地价格表"变成最新官方价。
+		const QUICK_RETRY_MS = [4000, 8000, 15000, 30000];
 
 		// ---- i18n（DSH locale 服务；zh 为兜底）----
 		const NS = "dsh-deepseek-usage";
@@ -32,9 +39,12 @@ window.__ModuleLoader__.load({
 			"peak.peak": "高峰时段",
 			"peak.off": "空闲时段",
 			"price.stale": "价格未同步（用内置表）",
-			"price.lastGood": "同步失败，仍用上次价格",
+			"price.lastGood": "同步失败，仍用上次价格（{at}）",
 			"price.alias": "按 {model} 计价",
 			"price.builtin": "按内置 {model} 档计价",
+			"price.file": "本地价格表（{at} 同步）",
+			"price.manual": "本地价格表（自动同步已关闭）",
+			"price.filePath": "价格表：{path}",
 		};
 		const EN = {
 			"price.input": "Input",
@@ -43,9 +53,12 @@ window.__ModuleLoader__.load({
 			"peak.peak": "Peak hours",
 			"peak.off": "Off-peak hours",
 			"price.stale": "Prices not synced (built-in table)",
-			"price.lastGood": "Sync failed; using last prices",
+			"price.lastGood": "Sync failed; using last prices ({at})",
 			"price.alias": "Priced as {model}",
 			"price.builtin": "Priced as built-in {model}",
+			"price.file": "Local price table (synced {at})",
+			"price.manual": "Local price table (auto-sync off)",
+			"price.filePath": "Price table: {path}",
 		};
 
 		// ---- helpers ---------------------------------------------------
@@ -61,6 +74,15 @@ window.__ModuleLoader__.load({
 			return String(parseFloat(n.toFixed(2)));
 		}
 
+		/** 时间戳（ms）→ `MM-DD HH:mm`（本地时区）；无效值返回空串。 */
+		function fmtWhen(value) {
+			const n = Number(value);
+			if (!Number.isFinite(n) || n <= 0) return "";
+			const d = new Date(n);
+			const p = (v) => String(v).padStart(2, "0");
+			return `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+		}
+
 		// 主题变量（带兜底值）
 		const C = {
 			bg: "var(--dsw-alias-bg-layer-1, rgba(127,127,127,.12))",
@@ -107,6 +129,9 @@ window.__ModuleLoader__.load({
 			// 状态（余额 + 单价 + 峰谷灯），再点切回提示。异常不受它影响，始终置空。
 			const [showNormal, setShowNormal] = useState(false);
 			const mounted = useRef(true);
+			// 快速重试：阶梯下标 + 定时器（宿主正在后台同步时，几秒后自己再看一眼）。
+			const retryStep = useRef(0);
+			const retryTimer = useRef(null);
 			const locale = ctx && ctx.locale;
 
 			// 订阅语言变化（DSH locale 服务；不可用时回退中文）。
@@ -127,6 +152,20 @@ window.__ModuleLoader__.load({
 				return ZH[key] || key;
 			};
 
+			// 价格还没到位时按 QUICK_RETRY_MS 阶梯补一次请求（封顶后回到 5 分钟轮询）：
+			// 覆盖两种情况——宿主正在后台同步官方价（pricing.syncing）、本地接口刚重启/报错。
+			const scheduleRetry = () => {
+				if (!mounted.current) return;
+				const delay = QUICK_RETRY_MS[retryStep.current];
+				if (delay === undefined) return;
+				retryStep.current += 1;
+				if (retryTimer.current !== null) clearTimeout(retryTimer.current);
+				retryTimer.current = setTimeout(() => {
+					retryTimer.current = null;
+					load();
+				}, delay);
+			};
+
 			const load = useCallback(async (force) => {
 				try {
 					const res = await fetch(USAGE_PATH + "?lang=" + lang + (force ? "&refresh=1" : ""), { cache: "no-store" });
@@ -140,9 +179,15 @@ window.__ModuleLoader__.load({
 					if (!mounted.current) return;
 					setData(body);
 					setError("");
+					// 宿主还在拉官方价 → 价格只是"本地价格表"的历史值，几秒后再确认一次；
+					// 已经拿到官方价（或手动模式/同步失败）就不再补请求。
+					const pricing = body.pricing && typeof body.pricing === "object" ? body.pricing : null;
+					if (pricing && pricing.mode !== "manual" && pricing.syncing === true) scheduleRetry();
+					else retryStep.current = 0;
 				} catch (e) {
 					if (!mounted.current) return;
 					setError(e instanceof Error ? e.message : String(e));
+					scheduleRetry();
 				}
 			}, [lang]);
 
@@ -164,6 +209,10 @@ window.__ModuleLoader__.load({
 				return () => {
 					mounted.current = false;
 					clearInterval(timer);
+					if (retryTimer.current !== null) {
+						clearTimeout(retryTimer.current);
+						retryTimer.current = null;
+					}
 					try {
 						if (typeof off === "function") off();
 					} catch (e) { /* 忽略退订错误 */ }
@@ -175,22 +224,42 @@ window.__ModuleLoader__.load({
 			const pricing = data && data.pricing ? data.pricing : null;
 			const symbol = balance && balance.currency === "USD" ? "$" : "¥";
 			const errs = (Array.isArray(data && data.errors) ? data.errors : []).concat(error ? [error] : []);
-			// 价格来源提示：模型改名按现名计价 / 价格取自内置表（同步失败或该模型不在官方页）
-			// 时明示，避免"官方已调价但卡片静静显示内置旧价"。
+			// 价格来源提示：模型改名按现名计价 / 价格来自本地价格表或内置表时明示，避免
+			// "官方已调价但卡片静静显示旧价"。
 			// friendly=true 表示只是"价格从哪来"的良性说明（可点击切回普通状态）；
 			// friendly=false 表示同步失败/旧价兜底，属于异常，必须一直可见。
+			//
+			// 0.7.0 起价格有三层（宿主 pricing.source）：
+			//   remote = 本次已从官方页同步到；
+			//   file   = 本地价格表（上次同步到的官方价 / 用户手改价）→ 属于正常态，不置空卡片，
+			//            只有"这次同步确实失败"才提示，并写明这份价是什么时候的；
+			//   seed   = 内置兜底（本地价格表缺失/损坏且官方页也拿不到）。
+			// 另外宿主正在后台同步（syncing）时不提示：这是正常过程，不是"未同步"。
 			const hints = [];
 			const addHint = (text, friendly) => hints.push({ text, friendly });
+			const at = fmtWhen(pricing && (pricing.layerAt || pricing.syncedAt));
+			const withAt = (key) => t(key).replace("{at}", at || "—");
 			if (pricing && typeof pricing === "object") {
 				const used = pricing.used ? String(pricing.used) : "";
-				if (pricing.via === "remote-alias" || pricing.via === "remote-family") {
+				const via = String(pricing.via || "");
+				if (via === "remote-alias" || via === "remote-family" || via === "file-alias" || via === "file-family") {
 					addHint(t("price.alias").replace("{model}", used), true);
-				} else if (pricing.source === "seed" && pricing.via !== "fallback") {
-					if (pricing.syncOk === false) addHint(t("price.stale"), false);
-					else addHint(t("price.builtin").replace("{model}", used), true);
+				} else if (pricing.syncing === true) {
+					// 后台正在拉官方页：此刻显示的是本地价格表里的价，属于正常过程，不提示。
+				} else if (pricing.source === "file") {
+					if (pricing.mode !== "manual" && pricing.syncOk === false) addHint(withAt("price.lastGood"), false);
+				} else if (pricing.source === "seed" && via !== "fallback") {
+					if (pricing.mode === "manual") {
+						// 手动模式下不联网，模型不在表里只是"用了内置条目"，不是同步失败
+						addHint(t("price.builtin").replace("{model}", used), true);
+					} else if (pricing.syncOk === false) {
+						addHint(t("price.stale"), false);
+					} else {
+						addHint(t("price.builtin").replace("{model}", used), true);
+					}
 				} else if (pricing.syncOk === false && pricing.syncedAt) {
 					// 本次刷新失败，但仍在用上次成功同步到的官方价格
-					addHint(t("price.lastGood"), false);
+					addHint(withAt("price.lastGood"), false);
 				}
 			}
 			const hintText = hints.map((x) => x.text).join(" · ");
@@ -208,9 +277,25 @@ window.__ModuleLoader__.load({
 				boxShadow: "0 0 4px rgba(0,0,0,.3)",
 			};
 			// 指示灯 hover 提示只显示当前处于高峰/空闲时段，不拼时段明细（太长）；
-			// 价格来源提示附在末尾——普通状态（良性提示被点开后）它是提示唯一可见处。
-			const peakTitle = (data && data.peak ? t("peak.peak") : t("peak.off"))
-				+ (hints.length ? " · " + hintText : "");
+			// 价格来源提示、价格表位置附在末尾——普通状态（良性提示被点开后）它是提示
+			// 唯一可见处，也是用户想知道"价从哪来、去哪儿改价"时的入口。
+			const fileInfo = pricing && pricing.file && typeof pricing.file === "object" ? pricing.file : null;
+			const sourceNote = !pricing
+				? ""
+				: pricing.mode === "manual"
+					? t("price.manual")
+					: pricing.source === "file"
+						? t("price.file").replace("{at}", at || "—")
+						: "";
+			const pathNote = fileInfo && typeof fileInfo.path === "string" && fileInfo.path !== ""
+				? t("price.filePath").replace("{path}", fileInfo.path)
+				: "";
+			const peakTitle = [
+				data && data.peak ? t("peak.peak") : t("peak.off"),
+				hintText,
+				sourceNote,
+				pathNote,
+			].filter((x) => x !== "").join(" · ");
 			// 点击卡片：刷新数据；若是纯良性提示，再在「提示态 / 普通态」之间切换。
 			const onCardClick = () => {
 				if (hints.length > 0 && !blocking) setShowNormal((v) => !v);
@@ -245,7 +330,9 @@ window.__ModuleLoader__.load({
 			// A2/A3（价格来源提示 / 错误）出现时，卡片直接置空：不画余额、档单价与峰谷灯，
 			// 只在空白卡片上显示提示文字——提示不再和余额数字、单价行抢同一块版面，从根本
 			// 上消除遮挡。minHeight 兜住常态卡片高度（CARD_MIN_HEIGHT），侧边栏不跳动；
-			// 文字多行时卡片自然变高。纯良性提示可由点击切回普通状态（见 blanked）。
+			// 文字多行时卡片自然变高。提示/错误字号取 12px（与卡片正文同级；原来 10px 可读性
+			// 差），字号变大后靠换行留在卡片内，不再用 nowrap + 省略号截断。纯良性提示可由
+			// 点击切回普通状态（见 blanked）。
 			// 窄卡片（!wide）没有文字空间，维持原样（提示在峰谷灯 hover 里）。
 			if (blanked) {
 				return h("div", {
@@ -273,13 +360,13 @@ window.__ModuleLoader__.load({
 				},
 					hints.length
 						? h("div", {
-							style: { color: C.sub, fontSize: 10, lineHeight: "13px", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
+							style: { color: C.sub, fontSize: 12, lineHeight: "16px", whiteSpace: "pre-wrap", overflowWrap: "anywhere" },
 							title: hintTitle || hintText,
 						}, hintText)
 						: null,
 					errs.length
 						? h("div", {
-							style: { color: C.err, fontSize: 10, lineHeight: "13px", whiteSpace: "pre-wrap", overflowWrap: "anywhere" },
+							style: { color: C.err, fontSize: 12, lineHeight: "16px", whiteSpace: "pre-wrap", overflowWrap: "anywhere" },
 						}, errs.join(" | "))
 						: null);
 			}

package/lib/index.js

@@ -10,7 +10,8 @@
  *     ok: true,
  *     balance: { isAvailable, total, currency, granted, toppedUp },  // 官方余额接口（API Key）
  *     tier: { input, cacheRead, cacheWrite, output, model, known },  // 当前模型当前档单价
- *     pricing: { source, via, requested, used, syncOk, syncedAt, ... }, // 价格来源/同步状态
+ *     pricing: { source, via, requested, used, syncOk, syncing, syncedAt, layerAt,
+ *                mode, file: { path, updatedAt, ... } },             // 价格来源/同步状态
  *     peak, peakHours,                                               // 峰谷时段（北京时间）
  *     updatedAt, errors
  *   }
@@ -18,16 +19,23 @@
  * `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 +49,16 @@ import {
   DEFAULT_MODEL,
   PEAK_HOURS_TEXT,
   PEAK_HOURS_TEXT_EN,
+  filePriceMeta,
   isPeak,
   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";
@@ -95,6 +108,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 +243,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 +277,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 +343,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 +364,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);
 
           // ---- 当前模型当前档单价（展示用）----
@@ -276,19 +431,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 };
+}

package/lib/pricing.js

@@ -1,12 +1,16 @@
 /**
  * dsh-deepseek-usage — 定价表（元 / 百万 tokens）。
  *
- * 价格来源（0.5.0 起）：
- * - 首选：DeepSeek 官方"模型 & 价格"页（lib/pricing-remote.js 抓取，每日首次
- *   访问/点击卡片时刷新），解析结果经 setRemotePrices() 注入本模块，作为 LIVE
- *   层按模型覆盖内置种子——官方调价只需页面更新，无需再改本文件。
- * - 兜底：下方 PRICE_TABLE 内置种子表——DeepSeek 官方峰谷定价快照
- *   （2026-09-10，与当时官方价格页一致），仅当官方页抓取/解析失败时生效。
+ * 价格来源优先级（0.7.0 起，三层）：
+ * - remote（进程内最新）：DeepSeek 官方"模型 & 价格"页（lib/pricing-remote.js 抓取，
+ *   每日首次访问/点击卡片时刷新），解析结果经 setRemotePrices() 注入本模块——官方调价
+ *   只需页面更新，无需改本文件。
+ * - file（本地价格配置表）：lib/pricing-store.js 维护的 pricing.json，内容是"上次同步到
+ *   的官方价 + 用户手改的价"，经 setFilePrices() 注入。进程重启后 remote 层为空，卡片
+ *   直接用它，因此不会再退回内置表（也就不会再出现"价格未同步（用内置表）"）。
+ * - seed（内置兜底）：下方 PRICE_TABLE 内置种子表——DeepSeek 官方峰谷定价快照
+ *   （2026-09-10，与当时官方价格页一致）。首次运行会拿它生成初始 pricing.json；
+ *   只有"本地价格表缺失/损坏且官方页也拿不到"时才会真正被展示。
  *
  * 模型改名（0.6.0 起）：官方会把模型改名并把旧名保留为别名（如
  * deepseek-v4-flash / deepseek-v4-flash-vision-exp → deepseek-flash）。旧名若
@@ -32,7 +36,8 @@ export const SHANGHAI_OFFSET_MS = 8 * 60 * 60 * 1000;
 /**
  * 内置种子表：input（缓存未命中）/ cacheRead（缓存命中）/ output 均为
  * [高峰, 空闲] 二元组；cacheWrite 为常量 0。
- * 仅作离线兜底，正常情况会被官方价格页同步结果覆盖。
+ * 只用于两处：首次运行生成 pricing.json（lib/pricing-store.js），以及"价格表缺失/
+ * 损坏且官方页也拿不到"时的最后兜底；正常运行时都会被 file / remote 层覆盖。
  */
 const PRICE_TABLE = {
   'deepseek-flash': { input: [2, 1], cacheRead: [0.04, 0.02], cacheWrite: 0, output: [8, 4] },
@@ -55,6 +60,12 @@ export const MODEL_ALIASES = {
 let remoteTable = null;
 /** 远端同步元信息（解析策略 / 抓取时间 / 来源），供界面展示同步状态。 */
 let remoteMeta = null;
+/** 本地价格配置表（setFilePrices 注入；重启后由它接管，见 lib/pricing-store.js）。 */
+let fileTable = null;
+/** 本地价格表元信息（路径 / 上次写入时间 / 来源）。 */
+let fileMeta = null;
+/** 本地价格表里的模型别名（旧名 → 现名），与内置 MODEL_ALIASES 合并使用。 */
+let fileAliases = {};
 
 /** 默认模型（当 agentDefaultModel 不可用时的展示默认）。 */
 export const DEFAULT_MODEL = 'deepseek-flash';
@@ -84,15 +95,11 @@ export function isPeak(ms) {
   return PEAK_WINDOWS.some(([start, end]) => h >= start && h < end);
 }
 
-/** 注入远端官方价格（parseOfficialPrices 的结果）；传 null/空表即清除回种子。 */
-export function setRemotePrices(table, meta) {
-  if (!table || typeof table !== 'object') {
-    remoteTable = null;
-    remoteMeta = null;
-    return;
-  }
-  const clean = {};
+/** 清洗一张价格表（形状校验 + 档位回退），供 remote / file 两层共用。 */
+function cleanTable(table) {
+  if (!table || typeof table !== 'object') return null;
   const okPair = (v) => Array.isArray(v) && v.length === 2 && v.every((n) => Number.isFinite(n) && n >= 0);
+  const clean = {};
   for (const [id, e] of Object.entries(table)) {
     if (typeof id !== 'string' || id === '' || !e || typeof e !== 'object') continue;
     const input = okPair(e.input) ? e.input : null;
@@ -104,7 +111,12 @@ export function setRemotePrices(table, meta) {
       output: okPair(e.output) ? e.output : input,
     };
   }
-  remoteTable = Object.keys(clean).length > 0 ? clean : null;
+  return Object.keys(clean).length > 0 ? clean : null;
+}
+
+/** 注入远端官方价格（parseOfficialPrices 的结果）；传 null/空表即清除回下一层。 */
+export function setRemotePrices(table, meta) {
+  remoteTable = cleanTable(table);
   remoteMeta = remoteTable && meta && typeof meta === 'object' ? { ...meta } : null;
 }
 
@@ -118,6 +130,38 @@ export function hasRemotePrices() {
   return remoteTable !== null;
 }
 
+/**
+ * 注入本地价格配置表（lib/pricing-store.js 的读取结果）。
+ * @param table 模型映射（models 字段）
+ * @param meta 元信息（path / updatedAt / source / strategy / autoUpdate）
+ * @param aliases 文件里的模型别名（旧名 → 现名），与内置 MODEL_ALIASES 合并
+ */
+export function setFilePrices(table, meta, aliases) {
+  fileTable = cleanTable(table);
+  fileMeta = fileTable && meta && typeof meta === 'object' ? { ...meta } : null;
+  fileAliases = aliases && typeof aliases === 'object' && !Array.isArray(aliases) ? { ...aliases } : {};
+}
+
+/** 本地价格表元信息（未载入时为 null）。 */
+export function filePriceMeta() {
+  return fileMeta ? { ...fileMeta } : null;
+}
+
+/** 本地价格表是否可用。 */
+export function hasFilePrices() {
+  return fileTable !== null;
+}
+
+/** 内置种子价格表快照（深拷贝；用于首次运行生成 pricing.json）。 */
+export function seedPrices() {
+  return JSON.parse(JSON.stringify(PRICE_TABLE));
+}
+
+/** 内置模型改名映射快照（用于首次运行生成 pricing.json）。 */
+export function seedAliases() {
+  return { ...MODEL_ALIASES };
+}
+
 /** 模型家族名（用于官方改名后的兜底匹配）。 */
 function familyOf(id) {
   const m = /(flash|pro|chat|reasoner)/.exec(id);
@@ -126,41 +170,51 @@ function familyOf(id) {
 
 const has = (obj, key) => !!obj && Object.prototype.hasOwnProperty.call(obj, key);
 
-/** 在远端表里找模型：精确 → 别名 → 同家族唯一匹配。 */
-function remoteLookup(id) {
-  if (!remoteTable || typeof id !== 'string' || id === '') return null;
-  if (has(remoteTable, id)) return { id, via: 'remote' };
-  const alias = MODEL_ALIASES[id];
-  if (alias && has(remoteTable, alias)) return { id: alias, via: 'remote-alias' };
+/** 别名（旧名 → 现名）：本地价格表的 aliases 覆盖内置 MODEL_ALIASES。 */
+function aliasOf(id) {
+  if (typeof id !== 'string' || id === '') return undefined;
+  return has(fileAliases, id) ? fileAliases[id] : MODEL_ALIASES[id];
+}
+
+/** 在某一层价格表里找模型：精确 → 别名 → 同家族唯一匹配。 */
+function layerLookup(table, tag, id) {
+  if (!table || typeof id !== 'string' || id === '') return null;
+  if (has(table, id)) return { id, via: tag };
+  const alias = aliasOf(id);
+  if (alias && has(table, alias)) return { id: alias, via: `${tag}-alias` };
   const fam = familyOf(id);
   if (fam) {
-    const hits = Object.keys(remoteTable).filter((k) => familyOf(k) === fam);
+    const hits = Object.keys(table).filter((k) => familyOf(k) === fam);
     // 仅在家族唯一时匹配，避免把 flash 档算成 pro 档。
-    if (hits.length === 1) return { id: hits[0], via: 'remote-family' };
+    if (hits.length === 1) return { id: hits[0], via: `${tag}-family` };
   }
   return null;
 }
 
 /**
- * 解析模型的计价条目。
- * @returns {{ price: object, id: string, via: 'remote'|'remote-alias'|'remote-family'|'alias'|'seed'|'fallback', known: boolean }}
+ * 解析模型的计价条目（优先级：remote → file → seed → chat 兜底）。
+ * @returns {{ price: object, id: string, via: 'remote'|'remote-alias'|'remote-family'|'file'|'file-alias'|'file-family'|'alias'|'seed'|'fallback', source: 'remote'|'file'|'seed', known: boolean }}
  */
 function lookup(model) {
-  const hit = remoteLookup(model);
-  if (hit) return { price: remoteTable[hit.id], id: hit.id, via: hit.via, known: true };
+  const remote = layerLookup(remoteTable, 'remote', model);
+  if (remote) return { price: remoteTable[remote.id], id: remote.id, via: remote.via, source: 'remote', known: true };
+
+  // 进程重启后 remote 层为空 → 先用本地价格表（上次同步到的官方价 / 用户手改价）。
+  const file = layerLookup(fileTable, 'file', model);
+  if (file) return { price: fileTable[file.id], id: file.id, via: file.via, source: 'file', known: true };
 
-  // 远端不可用（尚未同步/同步失败）或该模型确实不在官方页 → 内置表兜底。
-  const alias = typeof model === 'string' ? MODEL_ALIASES[model] : undefined;
+  // 本地表也没有（首次运行、文件损坏、或模型确实不在表里）→ 内置种子兜底。
+  const alias = aliasOf(model);
   if (alias && has(PRICE_TABLE, alias)) {
-    return { price: PRICE_TABLE[alias], id: alias, via: 'alias', known: true };
+    return { price: PRICE_TABLE[alias], id: alias, via: 'alias', source: 'seed', known: true };
   }
   if (has(PRICE_TABLE, model)) {
-    return { price: PRICE_TABLE[model], id: model, via: 'seed', known: true };
+    return { price: PRICE_TABLE[model], id: model, via: 'seed', source: 'seed', known: true };
   }
-  return { price: PRICE_TABLE['deepseek-chat'], id: 'deepseek-chat', via: 'fallback', known: false };
+  return { price: PRICE_TABLE['deepseek-chat'], id: 'deepseek-chat', via: 'fallback', source: 'seed', known: false };
 }
 
-/** 模型是否能解析出价格（远端精确/别名/家族，或内置表/别名）。 */
+/** 模型是否能解析出价格（远端精确/别名/家族，或本地表/内置表）。 */
 export function isKnownModel(model) {
   return lookup(model).known;
 }
@@ -168,7 +222,9 @@ export function isKnownModel(model) {
 /**
  * 某模型在某一时刻的单位价格（元/百万 tokens）。
  * 未知模型回退 chat 档；known=false 供调用方提示，避免静默算错。
- * via 说明价格来源，供界面区分"官方页同步"与"内置兜底"。
+ * via 说明取价路径，source 说明价格来自哪一层（remote 官方页本次同步 / file 本地价格表 /
+ * seed 内置兜底）；layerAt 是该层数据的时间戳（remote.fetchedAt / file.updatedAt），
+ * 供界面说明"这份价是什么时候同步的"。
  */
 export function unitAt(model, ms) {
   const found = lookup(model);
@@ -183,6 +239,12 @@ export function unitAt(model, ms) {
     requested: typeof model === 'string' ? model : '',
     known: found.known,
     via: found.via,
-    source: found.via.startsWith('remote') ? 'remote' : 'seed',
+    source: found.source,
+    layerAt:
+      found.source === 'remote'
+        ? (remoteMeta && Number.isFinite(remoteMeta.fetchedAt) ? remoteMeta.fetchedAt : null)
+        : found.source === 'file'
+          ? (fileMeta && Number.isFinite(fileMeta.updatedAt) ? fileMeta.updatedAt : null)
+          : null,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougen/dsh-deepseek-usage",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "DeepSeek 余额侧边栏插件：余额（官方 API）、当前档单价与峰谷时段指示灯，支持中/英文界面。",
   "type": "module",
   "main": "lib/index.js",