dsh-desktop-statusbar 2.1.1 → 2.2.0

package/tools/shot.cjs

@@ -0,0 +1,365 @@
+/**
+ * 生成 README 截图。
+ *
+ * 做法：用插件自己的组件代码（SettingsSection / StatusBar）在 vm 里渲染出虚拟树，
+ * 序列化成 HTML，配上插件自己的 CSS 与 DSH 主题变量，再用无头 Edge/Chrome 截图。
+ * 好处是截图内容永远跟着代码走 —— 改了文案或布局，重跑一次就同步，
+ * 不需要手工开应用摆状态、也不怕忘记更新。
+ *
+ * 用法：
+ *   node tools/shot.cjs            生成全部（中英 × 底栏 / 设置页 / 价格区）
+ *   node tools/shot.cjs zh status  只生成某一张
+ */
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const PLUGIN = path.join(ROOT, 'lib', 'client.js');
+const OUT = path.join(ROOT, 'docs');
+const CONFIG_KEY = 'dsh.desktopStatusBar.v1';
+
+const BROWSERS = [
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe'
+];
+
+/* DSH 主题变量（浅色）。取自主题包里的值，就列插件用到的那一批。 */
+const THEME = [
+  ':root{',
+  '--dsw-alias-bg-layer-1:#ffffff;',
+  '--dsw-alias-label-primary:#0f1115;',
+  '--dsw-alias-label-secondary:#4b5563;',
+  '--dsw-alias-label-tertiary:#6b7280;',
+  '--dsw-alias-separator-primary:rgba(20,24,32,.16);',
+  '--dsw-alias-border-l1:rgba(20,24,32,.14);',
+  '--dsw-alias-border-l3:rgba(20,24,32,.2);',
+  '--dsw-alias-border-l4:rgba(20,24,32,.12);',
+  '--dsw-alias-interactive-bg-hover:rgba(38,49,72,.06);',
+  '--dsw-alias-brand-primary:#4d6bfe;',
+  '--dsw-specific-menu:#f8f9fa94;',
+  '--dsw-menu-backdrop-filter:blur(40px) saturate(150%);',
+  '--dsw-radius-sm:8px;--dsw-radius-md:12px;--dsw-radius-lg:16px;',
+  '--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);',
+  '--dsw-elevation-stroke:0 0 0 .5px var(--dsw-elevation-stroke-color);',
+  '--dsw-elevation-prominent:var(--dsw-elevation-stroke),0 3px 8px 0 #0000000a,0 0 20px 0 #0000000d;',
+  '--dsh-chat-content-width:760px;',
+  '--dsh-content-font-size-secondary:13px;',
+  '--dsh-content-font-delta-secondary:0px;',
+  '--dsh-composer-side-clearance:0px;',
+  '}'
+].join('');
+
+/* 示例会话数据：截图里显示的就是这些数字 */
+const SAMPLE = {
+  turns: 12, steps: 268,
+  ttftMs: 22800, decodeMs: 96000, decodeTokens: 26400, ttftSteps: 12,
+  llmMs: 1512000, toolMs: 402000,
+  pressureTokens: 486000, contextWindow: 1000000,
+  breakdown: { systemTokens: 1900, toolsTokens: 7300, messageTokens: 181000 },
+  usage: { uncachedInputTokens: 29631, cacheReadTokens: 1900000, cacheWriteTokens: 0, outputTokens: 41007 },
+  calls: [
+    { at: 1, model: 'deepseek-v4-pro', input: 9638, cacheRead: 1536, cacheWrite: 0, output: 197 },
+    { at: 2, model: 'deepseek-v4-pro', input: 5966, cacheRead: 11264, cacheWrite: 0, output: 500 },
+    { at: 3, model: 'deepseek-v4-pro', input: 901, cacheRead: 17664, cacheWrite: 0, output: 324 },
+    { at: 4, model: 'deepseek-v4-pro', input: 1473, cacheRead: 18816, cacheWrite: 0, output: 476 },
+    { at: 5, model: 'deepseek-v4-pro', input: 1553, cacheRead: 20736, cacheWrite: 0, output: 1475 },
+    { at: 6, model: 'deepseek-v4-pro', input: 152, cacheRead: 23680, cacheWrite: 0, output: 115 }
+  ],
+  timing: { samples: 12, fastestTtft: 412, slowestTtft: 4458, fastestTps: 394, slowestTps: 167 }
+};
+
+function browser() {
+  for (const one of BROWSERS) {
+    if (fs.existsSync(one)) return one;
+  }
+  throw new Error('没找到 Chrome / Edge，无法截图');
+}
+
+/** 用给定语言与配置加载 client.js，拿回组件与词典；presets 按 useState 调用序号注入初始状态 */
+function loadPlugin(locale, config, presets) {
+  let code = fs.readFileSync(PLUGIN, 'utf8');
+  code = code.replace('\t\texports.apply = apply;',
+    '\t\texports.__shot = { zh: zh, en: en, CSS: CSS, SettingsSection: SettingsSection, StatusBar: StatusBar };\n'
+    + '\t\texports.apply = apply;');
+
+  const store = new Map([[CONFIG_KEY, JSON.stringify(config)]]);
+  const fakeWindow = {
+    localStorage: {
+      getItem: (k) => (store.has(k) ? store.get(k) : null),
+      setItem: (k, v) => { store.set(k, v); },
+      removeItem: (k) => { store.delete(k); }
+    },
+    innerWidth: 1200, innerHeight: 900,
+    setInterval: () => 0, clearInterval: () => {}, setTimeout: () => 0, clearTimeout: () => {},
+    addEventListener: () => {}, removeEventListener: () => {},
+    fetch: () => Promise.resolve({ json: () => Promise.resolve({}) })
+  };
+  let captured = null;
+  fakeWindow.__ModuleLoader__ = { load: (entry) => { captured = entry; } };
+
+  let stateIndex = 0;
+  const reactStub = {
+    createElement: (type, props, ...children) => ({
+      type,
+      props: props === null || props === undefined ? {} : props,
+      children: children.flat(Infinity).filter((c) => c !== null && c !== undefined && c !== false)
+    }),
+    useState: (init) => {
+      const at = stateIndex;
+      stateIndex += 1;
+      /* 截图要的是"某个状态下的样子"：需要展开的卡片靠预设值摆出来，省得模拟点击 */
+      if (presets !== undefined && presets[at] !== undefined) return [presets[at], () => {}];
+      return [typeof init === 'function' ? init() : init, () => {}];
+    },
+    useEffect: () => {},
+    useLayoutEffect: () => {},
+    useRef: () => ({ current: null }),
+    useMemo: (fn) => fn(),
+    useCallback: (fn) => fn,
+    useSyncExternalStore: (subscribe, snapshot) => snapshot(),
+    Fragment: Symbol('Fragment')
+  };
+
+  const sandbox = {
+    window: fakeWindow,
+    document: {
+      documentElement: { classList: { add() {}, remove() {} } },
+      querySelector: () => null,
+      createElement: () => ({ dataset: {}, style: {}, appendChild() {}, setAttribute() {} }),
+      head: { appendChild() {} },
+      addEventListener: () => {}, removeEventListener: () => {}
+    },
+    react: reactStub,
+    console, Promise, Date, Math, JSON, Object, Array, Number, String, Boolean, Symbol, Set, Map, Error
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(code, sandbox, { filename: 'client.js' });
+  if (captured === null || captured.factory === undefined) throw new Error('插件工厂没被捕获');
+  const api = captured.factory((name) => (name === 'react' ? reactStub : undefined));
+  return { api: api, shot: api.__shot };
+}
+
+function esc(text) {
+  return String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** 虚拟树 → HTML */
+function toHtml(node) {
+  if (node === null || node === undefined || node === false || node === true || node === '') return '';
+  if (typeof node === 'string' || typeof node === 'number') return esc(node);
+  if (Array.isArray(node)) return node.map(toHtml).join('');
+  if (typeof node.type === 'symbol') return (node.children || []).map(toHtml).join('');
+  const props = node.props || {};
+  let attrs = '';
+  Object.keys(props).forEach((key) => {
+    if (key === 'children' || key === 'ref' || key === 'key' || key.indexOf('on') === 0) return;
+    const value = props[key];
+    if (value === undefined || value === null || value === false || typeof value === 'function') return;
+    const name = key === 'className' ? 'class' : key;
+    attrs += ' ' + name + '="' + esc(value === true ? '' : value) + '"';
+  });
+  const cls = props.className === undefined ? '' : String(props.className);
+  const style = props.style === undefined ? '' : ' style="' + Object.keys(props.style).map((k) => k + ':' + props.style[k]).join(';') + '"';
+  const open = '<' + node.type + attrs + (style !== '' && String(attrs).indexOf(' style=') === -1 ? style : '') + '>';
+  if (node.type === 'input' || node.type === 'br' || node.type === 'img') return open;
+  return open + (node.children || []).map(toHtml).join('') + '</' + node.type + '>';
+}
+
+function page(body, extraCss, pluginCss) {
+  return '<!doctype html><html lang="zh"><head><meta charset="utf-8"><style>'
+    + THEME
+    + '*{box-sizing:border-box}body{margin:0;padding:0;background:#fff;color:var(--dsw-alias-label-primary);'
+    + 'font-family:"Segoe UI","Microsoft YaHei",system-ui,sans-serif;font-size:13px;line-height:1.5}'
+    + '.shot-wrap{width:100%;padding:26px 30px}'
+    + pluginCss
+    + extraCss
+    + '</style></head><body>' + body + '</body></html>';
+}
+
+/** 语言替身：与插件里的 t() 同语义 */
+function translator(dict, locale) {
+  return (key, params) => {
+    const table = locale === 'en' ? dict.en : dict.zh;
+    let out = table[key] !== undefined ? table[key] : key;
+    if (params !== undefined && params !== null) {
+      out = out.replace(/\{(\w+)\}/g, (m, name) => (name in params ? String(params[name]) : m));
+    }
+    return out;
+  };
+}
+
+const SETTINGS_CONFIG = {
+  version: 7, contextMeter: true, currency: 'CNY', priceConfigured: true,
+  /* 按 SEGMENTS 的声明顺序写（= 出厂默认顺序）：tps 在 ttft 前面 */
+  segments: ['status', 'counts', 'cacheHit', 'tps', 'ttft', 'sessionTime', 'lastCost', 'cost', 'balance'],
+  hidden: [], modelOrder: ['deepseek-flash', 'deepseek-v4-pro'],
+  models: {
+    'deepseek-flash': { tiered: true, peak: { input: 2, cacheRead: 0.04, cacheWrite: 0, output: 8 }, offPeak: { input: 1, cacheRead: 0.02, cacheWrite: 0, output: 4 } },
+    'deepseek-v4-pro': { tiered: true, peak: { input: 9, cacheRead: 0.3, cacheWrite: 0, output: 27 }, offPeak: { input: 4.5, cacheRead: 0.15, cacheWrite: 0, output: 13.5 } }
+  }
+};
+
+/* 英文截图配美元价：币种是可配的，英文场景展示 USD 更贴切 */
+const SETTINGS_USD = Object.assign({}, SETTINGS_CONFIG, {
+  currency: 'USD',
+  models: {
+    'deepseek-flash': { tiered: true, peak: { input: 0.3, cacheRead: 0.006, cacheWrite: 0, output: 1.2 }, offPeak: { input: 0.15, cacheRead: 0.003, cacheWrite: 0, output: 0.6 } },
+    'deepseek-v4-pro': { tiered: true, peak: { input: 1.32, cacheRead: 0.044, cacheWrite: 0, output: 3.96 }, offPeak: { input: 0.66, cacheRead: 0.022, cacheWrite: 0, output: 1.98 } }
+  }
+});
+
+/** 设置页整页 */
+function settingsShot(locale) {
+  const loaded = loadPlugin(locale, locale === 'en' ? SETTINGS_USD : SETTINGS_CONFIG);
+  const t = translator(loaded.shot, locale);
+  const tree = loaded.shot.SettingsSection({
+    t: t,
+    useProjection: (name) => (name === 'desktopStatusbarModel' ? { model: 'deepseek-v4-pro' } : undefined)
+  });
+  return page('<div class="shot-wrap">' + toHtml(tree) + '</div>', '', loaded.shot.CSS);
+}
+
+/** 只要价格区：前两块隐藏、展开第一张卡，并把币种下拉收起（展开会压住右边那列输入框） */
+function pricingShot(locale) {
+  /* SettingsSection 里 useState 的顺序（组件加了 hook 就要回来重数一遍）：
+     0 devOn / 1 drag / 2 newModel / 3 hostModel / 4 editing / 5 draft /
+     6 holidayBusy / 7 holidayNote / 8 currencyOpen。
+     2026-10-05 之前按下标写的是旧顺序（把 editing 当第 5 个、holidayNote 当第 6 个），
+     结果第一张卡展不开、还把草稿对象塞进了 holidayNote，卡片里冒出一句「抓取失败（undefined）」。
+     2026-10-13 又踩了一次同类的坑：新增 devOn（开发模式胶囊）插在最前面，
+     后面整体后移一位，于是 presets[3] 从 editing 变成 hostModel、
+     presets[4] 从 draft 变成 editing、presets[7] 从 currencyOpen 变成 holidayNote。
+     教训：**下标是脆的**，加 hook 必须回来重数，并用 `node tools/shot.cjs` 实际生成一次确认。 */
+  const presets = [];
+  presets[4] = 'deepseek-flash';
+  /* 浮层里的数字也要跟着币种走：预设草稿按语言挑人民币或美元那套 */
+  presets[5] = locale === 'en'
+    ? {
+      tiered: true,
+      peak: { input: '0.3', cacheRead: '0.006', cacheWrite: '0', output: '1.2' },
+      offPeak: { input: '0.15', cacheRead: '0.003', cacheWrite: '0', output: '0.6' }
+    }
+    : {
+      tiered: true,
+      peak: { input: '2', cacheRead: '0.04', cacheWrite: '0', output: '8' },
+      offPeak: { input: '1', cacheRead: '0.02', cacheWrite: '0', output: '4' }
+    };
+  presets[8] = false;   /* 币种下拉收起：展开会压住右边那列输入框 */
+  const loaded = loadPlugin(locale, locale === 'en' ? SETTINGS_USD : SETTINGS_CONFIG, presets);
+  const t = translator(loaded.shot, locale);
+  const tree = loaded.shot.SettingsSection({
+    t: t,
+    useProjection: (name) => (name === 'desktopStatusbarModel' ? { model: 'deepseek-v4-pro' } : undefined)
+  });
+  /* 只留第三块（价格区）：head 与统计字段在前两块，按钮区在后 */
+  const extra = '.dsb-settings > *:nth-child(-n+2){display:none}'
+    + '.dsb-settings > *:nth-child(n+4){display:none}';
+  return page('<div class="shot-wrap">' + toHtml(tree) + '</div>', extra, loaded.shot.CSS);
+}
+
+/** 底栏：垫一层假的对话区背景，让毛玻璃看得出来 */
+function statusbarShot(locale) {
+  /* StatusBar 里 useState 的顺序：now → balance → tipId → tipPos → tipTick。
+     余额平时靠 effect 轮询拿，静态渲染要直接喂进去。 */
+  const presets = [];
+  presets[1] = { ok: true, total: '10.32', toppedUp: '8.00', granted: '2.32', currency: 'CNY', at: Date.now() };
+  const loaded = loadPlugin(locale, SETTINGS_CONFIG, presets);
+  const t = translator(loaded.shot, locale);
+  const calls = SAMPLE.calls;
+  const tree = loaded.shot.StatusBar({
+    t: t,
+    sessionId: 'shot',
+    useProjection: (name) => {
+      if (name === 'sessionStats') return SAMPLE;
+      if (name === 'tokenUsage') return SAMPLE.usage;
+      if (name === 'contextPressure') return { pressureTokens: SAMPLE.pressureTokens, contextWindow: SAMPLE.contextWindow };
+      if (name === 'contextBreakdown') return SAMPLE.breakdown;
+      if (name === 'desktopStatusbarUsage') {
+        return { models: { 'deepseek-v4-pro': { input: 19683, cacheRead: 93696, cacheWrite: 0, output: 3087 } }, calls: calls, current: { calls: calls, input: 19683, cacheRead: 93696, cacheWrite: 0, output: 3087 }, last: null, turn: 12 };
+      }
+      if (name === 'desktopStatusbarTiming') return SAMPLE.timing;
+      if (name === 'desktopStatusbarActiveTime') return { turns: 12, steps: 268, since: Date.now() - 3152000, stepSince: null };
+      if (name === 'desktopStatusbarBalance') return { ok: true, total: '10.32', toppedUp: '8.00', granted: '2.32', currency: 'CNY', at: Date.now() };
+      if (name === 'desktopStatusbarModel') return { provider: 'deepseek', model: 'deepseek-v4-pro', at: Date.now() };
+      return undefined;
+    },
+    useSession: (selector) => (selector === undefined ? undefined : selector({ running: false, partial: null, runningCalls: [], lastAgentError: null, pendingApprovals: null })),
+    useSessions: () => undefined,
+    useChat: () => undefined
+  });
+  const extra = '.shot-wrap{padding:0}'
+    + '.shot-chat{height:190px;padding:18px 24px;background:linear-gradient(180deg,#fff 0%,#f2f4f8 100%);'
+    + 'color:#9aa3b2;font-size:13px;line-height:2}'
+    + '.shot-bar{background:#eef1f6;padding:0 0 10px}';
+  const chat = '<div class="shot-chat">'
+    + '<div>把底栏那几项做成可点的气泡，气泡风格跟官方一致。</div>'
+    + '<div>顺带把峰谷规则挪到可配置的价格表里。</div>'
+    + '<div>写完跑一下测试，确认占位和极值都没问题。</div>'
+    + '</div>';
+  return page(chat + '<div class="shot-bar">' + toHtml(tree) + '</div>', extra, loaded.shot.CSS);
+}
+
+/* status 场景生成的底栏是**合成**的（自己摆的示例数据 + 假对话区背景）。
+   2026-10-05 起 README 里的 docs/statusbar*.png 换成了真机截图（用户自己在 DSH 里截的），
+   所以**跑全量会把它覆盖掉** —— 只想更新设置页/价格区就单跑那两张：
+     node tools/shot.cjs zh settings && node tools/shot.cjs zh pricing（en 同理）。 */
+const SCENES = { settings: settingsShot, pricing: pricingShot, status: statusbarShot };
+/* 窗口高度按内容量出来的（上下留白对齐到页面自己的 30px 内边距）：
+   settings 内容底 1050、pricing 内容底 315.5。改了场景内容要重量一遍再调这里。 */
+const SIZES = { settings: '940,1082', pricing: '940,346', status: '1180,230' };
+
+function shoot(locale, scene) {
+  const html = SCENES[scene](locale);
+  const name = scene === 'settings' ? 'settings' : (scene === 'pricing' ? 'pricing' : 'statusbar');
+  const file = path.join(OUT, locale === 'en' ? name + '.en.png' : name + '.png');
+  /* SHOT_HTML_ONLY=1：只把页面写到系统临时目录、不碰浏览器 ——
+     给「当前环境起不了子进程（AI 沙箱、缺浏览器）」时用：拿这些页面自己调 chrome 截图。 */
+  if (process.env.SHOT_HTML_ONLY === '1') {
+    const out = path.join(require('os').tmpdir(), 'shot-' + locale + '-' + scene + '.html');
+    fs.writeFileSync(out, html, 'utf8');
+    console.log('HTML  ' + out + '  → ' + file);
+    return;
+  }
+  const tmp = path.join(OUT, '_shot-' + locale + '-' + scene + '.html');
+  fs.writeFileSync(tmp, html, 'utf8');
+  const chrome = browser();
+  /* 让浏览器写到临时文件，成功了再改名顶上：
+     目标文件不能在截图前删 —— 浏览器起不来（沙箱拦子进程、缺浏览器）时会把已有截图弄丢，
+     2026-10-05 真丢过一次 docs/statusbar.png。临时名每次都是新的，也就不会有"拒绝覆盖"的问题。 */
+  const staged = file + '.tmp.png';
+  if (fs.existsSync(staged)) fs.unlinkSync(staged);
+  const args = [
+    '--headless=new', '--disable-gpu', '--hide-scrollbars', '--force-device-scale-factor=2',
+    '--default-background-color=00000000',
+    '--window-size=' + SIZES[scene],
+    '--screenshot=' + staged,
+    /* 路径里有空格（AI Project），file:// 后面必须编码，否则浏览器打不开页面、静默截不出图 */
+    'file:///' + encodeURI(tmp.replace(/\\/g, '/'))
+  ];
+  const run = require('child_process').spawnSync(chrome, args, { encoding: 'utf8' });
+  if (fs.existsSync(staged) !== true) {
+    /* 调试用的页面写到系统临时目录：docs/ 是 npm 会打包的目录，失败时不能往里丢东西 */
+    const debug = path.join(require('os').tmpdir(), path.basename(tmp) + '.html');
+    fs.writeFileSync(debug, html, 'utf8');
+    fs.unlinkSync(tmp);
+    console.error('浏览器输出:', String(run.stderr).slice(0, 600));
+    console.error('保留页面: ' + debug);
+    console.error('（已有截图没被动过：' + (fs.existsSync(file) ? '仍在' : '本来就没有') + '）');
+    throw new Error('浏览器没有写出 ' + file + '（检查无头截图是否可用）');
+  }
+  fs.renameSync(staged, file);
+  fs.unlinkSync(tmp);
+  const size = fs.statSync(file).size;
+  console.log('→ ' + path.relative(ROOT, file) + '  ' + Math.round(size / 1024) + ' KB');
+}
+
+const onlyLocale = process.argv[2];
+const onlyScene = process.argv[3];
+const locales = onlyLocale === undefined ? ['zh', 'en'] : [onlyLocale];
+const scenes = onlyScene === undefined ? ['status', 'settings', 'pricing'] : [onlyScene];
+locales.forEach((locale) => scenes.forEach((scene) => shoot(locale, scene)));
+console.log('截图完成');

package/tools/sync-from-plugin.cjs

@@ -0,0 +1,49 @@
+/**
+ * 把已安装的插件源码同步进项目（改完插件跑一次，再跑 tests/）。
+ * 用法：node tools/sync-from-plugin.cjs
+ *
+ * **文件清单自动扫描**，不写死。原先只列了四个文件，插件目录里新增的模块
+ * （self-update.js / release-age.js）不会被搬回项目 —— 于是"插件里改了、项目里没有"，
+ * 下次用 sync-to-plugin.cjs 推回去时又把改动覆盖掉。现在按插件目录的 `lib/*.js` 逐个搬。
+ *
+ * 只同步 lib/ 下的源码；项目的 package.json 有自己的元数据，不覆盖。
+ * 插件目录由 tools/plugin-dir.cjs 自动定位（换机器/换用户名都不必改代码）：
+ * 可用环境变量 DSH_STATUS_BAR_PLUGIN_DIR 显式指定。
+ */
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT = path.join(__dirname, '..');
+const pluginRoot = require('./plugin-dir.cjs').pluginDir();
+if (pluginRoot === null) {
+  console.log('× 找不到已安装的插件目录：请设置 DSH_STATUS_BAR_PLUGIN_DIR 指向它，');
+  console.log('  或把 tools/ 放在插件目录里运行。');
+  process.exit(1);
+}
+const PLUGIN = pluginRoot;
+
+/* 自动列出插件目录里的全部源文件，而不是写死一份清单 */
+const sources = fs.readdirSync(path.join(PLUGIN, 'lib'))
+  .filter((name) => name.endsWith('.js'))
+  .sort()
+  .map((name) => 'lib/' + name);
+
+let changed = 0;
+sources.forEach((rel) => {
+	const from = path.join(PLUGIN, rel);
+	const to = path.join(PROJECT, rel);
+	const before = fs.existsSync(to) ? fs.readFileSync(to, 'utf8') : null;
+	const now = fs.readFileSync(from, 'utf8');
+	if (before === now) {
+		console.log('= ' + rel + '（一致）');
+		return;
+	}
+	fs.writeFileSync(to, now, 'utf8');
+	changed += 1;
+	console.log('→ ' + rel + ' 已更新' + (before === null ? '（项目原先没有）' : ''));
+});
+
+console.log('');
+console.log(changed === 0
+	? '项目已是最新（' + sources.length + ' 个源文件）'
+	: '同步了 ' + changed + ' / ' + sources.length + ' 个文件；接着跑：node tools/test.cjs');

package/tools/sync-to-plugin.cjs

@@ -0,0 +1,71 @@
+/**
+ * 把项目 lib/ 的源码同步到已安装的插件目录（改完项目跑一次，再重启 DSH）。
+ * 用法：node tools/sync-to-plugin.cjs
+ *
+ * **文件清单自动扫描**，不写死。原先写死 `['client.js','index.js','holiday.js','balance-api.js']`，
+ * 新增模块（self-update.js / release-age.js）不会被同步过去 —— 而 index.js 会 import 它们，
+ * 结果是插件直接加载失败，报错还发生在 DSH 启动阶段，很难联想到"同步脚本漏了一个文件"。
+ * 现在按 `lib/*.js` 逐个覆盖，项目里有什么就同步什么。
+ *
+ * 插件目录由 tools/plugin-dir.cjs 自动定位（换机器/换用户名都不必改代码）：
+ * 可用环境变量 DSH_STATUS_BAR_PLUGIN_DIR 显式指定。
+ */
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT = path.join(__dirname, '..', 'lib');
+const pluginRoot = require('./plugin-dir.cjs').pluginDir();
+if (pluginRoot === null) {
+  console.log('× 找不到已安装的插件目录：请设置 DSH_STATUS_BAR_PLUGIN_DIR 指向它，');
+  console.log('  或把 tools/ 放在插件目录里运行。');
+  process.exit(1);
+}
+const PLUGIN = path.join(pluginRoot, 'lib');
+
+let failed = 0;
+
+function writeToPlugin(name, text) {
+  const target = path.join(PLUGIN, name);
+  const before = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+  if (before === text) {
+    console.log('= ' + name + '（一致）');
+    return;
+  }
+  /* 写入前先解除硬链接。
+     已安装目录里的文件通常是 pnpm store 的**硬链接**（同一个 inode 有两个路径）。
+     直接 writeFileSync 是"透过链接写"，会同时改到 store 里那一份 —— store 是跨
+     profile、跨项目共享的，等于把别处也改了。
+     做法：先删掉这个链接（store 的数据仍在，只是少一个引用），再写新文件
+     （新文件是独立 inode，与 store 无关）。 */
+  const wasLinked = fs.existsSync(target) && fs.statSync(target).nlink > 1;
+  if (wasLinked) {
+    fs.unlinkSync(target);
+    console.log('  （' + name + ' 原本是 store 硬链接，已先解除）');
+  }
+  fs.writeFileSync(target, text, 'utf8');
+  /* 复核：新文件必须不再与 store 共享 */
+  if (fs.statSync(target).nlink > 1) {
+    throw new Error(name + ' 写入后仍有多个硬链接（nlink=' + String(fs.statSync(target).nlink) + '），可能污染 pnpm store');
+  }
+  console.log('→ ' + name + ' 已更新' + (before === null ? '（插件目录原先没有）' : ''));
+}
+
+/* 自动列出项目里的全部源文件，而不是写死一份清单 */
+const sources = fs.readdirSync(PROJECT).filter((name) => name.endsWith('.js')).sort();
+
+sources.forEach((name) => {
+  try {
+    writeToPlugin(name, fs.readFileSync(path.join(PROJECT, name), 'utf8'));
+  } catch (error) {
+    failed += 1;
+    console.log('× ' + name + '：' + (error !== null && error !== undefined && error.message ? error.message : error));
+  }
+});
+
+console.log('');
+if (failed === 0) {
+  console.log('插件目录已同步（' + sources.length + ' 个源文件 → ' + PLUGIN + '）；重启 DSH 生效');
+} else {
+  console.log('有文件没同步成功，见上面的 ×');
+}
+process.exitCode = failed === 0 ? 0 : 1;

package/tools/test.cjs

@@ -0,0 +1,99 @@
+/**
+ * 跑 tests/ 下所有 verify*.js 并汇总结果。
+ * 用法：node tools/test.cjs；退出码 0 = 全部通过。
+ *
+ * 两个刻意的写法（都是踩过坑才改的）：
+ *
+ * 1. 子进程用 **stdio: 'inherit'**，不用管道捕获。
+ *    原先用 `spawnSync(..., { encoding: 'utf8' })`（默认 pipe）在某些受限环境下会直接
+ *    EPERM：进程根本没起来，`run.status` 是 null，于是**每个测试都被判失败**，而失败
+ *    原因那一栏是空的 —— 看起来像"40 个测试全挂了"，其实一个都没跑。
+ *    inherit 让子进程直接写本终端的输出，不受这条限制，失败时也能就地看到完整上下文。
+ *
+ * 2. 通配符用 `/^verify.*\.js$/`，**显式包含 verify.js**。
+ *    如果写成 `verify-*.js`（多个连字符）会漏掉 `verify.js` —— 那是最大的一个测试，
+ *    漏跑它时总数看起来"少一个"却不容易察觉。
+ *
+ * 另加超时：单个测试挂住时不能把整个汇总永久卡住。
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const DIR = path.join(__dirname, '..', 'tests');
+/* 单测超时（毫秒）：正常都远小于它，只有挂住时才会触发 */
+const TIMEOUT_MS = 300000;
+
+const files = fs.readdirSync(DIR).filter((name) => /^verify.*\.js$/.test(name)).sort();
+
+let failed = 0;
+for (const name of files) {
+	const run = spawnSync(process.execPath, [path.join(DIR, name)], {
+		stdio: 'inherit',
+		timeout: TIMEOUT_MS,
+	});
+	if (run.status === 0) {
+		console.log('= ' + name + '  通过');
+		continue;
+	}
+	failed += 1;
+	/* 失败原因要能一眼看出是什么：超时 / 被信号杀 / 非零退出码 / 进程都没起来。
+	   原先只打 stderr 第一行，而 EPERM 那种情况 stderr 是空的，于是什么都没显示。 */
+	let why;
+	if (run.error !== undefined && run.error !== null) why = '无法启动：' + String(run.error.message);
+	else if (run.signal !== null && run.signal !== undefined) why = '被信号终止：' + String(run.signal);
+	else if (run.status === null) why = '退出码不可用（很可能超时）';
+	else why = '退出码 ' + String(run.status);
+	console.log('× ' + name + '  ' + why);
+}
+
+console.log('');
+
+/* 一致性守卫：测试跑的都是项目 lib/ 的源码，而 DSH 实际加载的是插件目录那份。
+ * 两边不一致（忘了同步）时这里直接判失败，避免"测试全绿但界面上没变化"。
+ * 插件目录由 tools/plugin-dir.cjs 自动定位（换机器/换用户名都不必改代码）。
+ *
+ * 三个修正（原有实现的问题）：
+ *   ① 报的是**项目**目录的文件数，文案却写"插件目录已同步" —— 数字对不上实际；
+ *      现在报两边各自的数量。
+ *   ② 只检查「项目有、插件目录没有」，反向漏了：插件目录多出一个源文件不会被发现。
+ *      现在两个方向都比。
+ *   ③ 原先不一致时直接 `process.exit(1)`，**在打印测试汇总之前就退出了** ——
+ *      于是"同步问题"会把"测试结果"整个吞掉，看到的只是最后那行退出码。
+ *      现在记为失败并继续往下打印汇总。 */
+const PROJECT_LIB = path.join(__dirname, '..', 'lib');
+const pluginRoot = require('./plugin-dir.cjs').pluginDir();
+if (pluginRoot === null) {
+	console.log('! 找不到已安装的插件目录，跳过一致性检查。');
+	console.log('  可用环境变量 DSH_STATUS_BAR_PLUGIN_DIR 指向它，或把 tools/ 放在插件目录里运行。');
+} else {
+	const PLUGIN_LIB = path.join(pluginRoot, 'lib');
+	const projectFiles = fs.readdirSync(PROJECT_LIB).filter((name) => name.endsWith('.js'));
+	const pluginFiles = fs.existsSync(PLUGIN_LIB)
+		? fs.readdirSync(PLUGIN_LIB).filter((name) => name.endsWith('.js'))
+		: [];
+
+	/* 两个方向都看：项目→插件（漏同步）、插件→项目（多出来的） */
+	const missingInPlugin = projectFiles.filter((name) => !pluginFiles.includes(name));
+	const extraInPlugin = pluginFiles.filter((name) => !projectFiles.includes(name));
+	const different = projectFiles.filter((name) => {
+		if (!pluginFiles.includes(name)) return false;
+		return fs.readFileSync(path.join(PROJECT_LIB, name), 'utf8') !== fs.readFileSync(path.join(PLUGIN_LIB, name), 'utf8');
+	});
+
+	const issues = [];
+	if (missingInPlugin.length > 0) issues.push('插件目录缺：' + missingInPlugin.join(', '));
+	if (extraInPlugin.length > 0) issues.push('插件目录多出：' + extraInPlugin.join(', '));
+	if (different.length > 0) issues.push('内容不一致：' + different.join(', '));
+
+	if (issues.length > 0) {
+		failed += 1;
+		console.log('× 两边源码不一致 —— ' + issues.join('；'));
+		console.log('  项目 → 插件：node tools/sync-to-plugin.cjs');
+		console.log('  插件 → 项目：node tools/sync-from-plugin.cjs');
+	} else {
+		console.log('= 插件目录已同步（项目 ' + projectFiles.length + ' 个源文件 / 插件 ' + pluginFiles.length + ' 个，' + pluginRoot + '）');
+	}
+}
+console.log(failed === 0 ? files.length + ' 个测试全部通过' : failed + ' 项失败（含测试与同步检查）');
+process.exit(failed === 0 ? 0 : 1);