dsh-github-hot 0.1.1 → 0.1.3

package/lib/index.js

@@ -39,6 +39,7 @@
 
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -49,7 +50,20 @@ export const name = 'dsh-github-hot';
 /** 硬依赖：只要 webServer（提供路由）。 */
 export const inject = ['webServer'];
 
-const VERSION = '0.1.0';
+/**
+ * 版本号：从 package.json 读，**不要在这里写死**。
+ *
+ * 写死的话每次发版都要记得改两处，漏改就会让 /status 报旧版本
+ * （用户排查问题时会被误导）。这里用 createRequire 读同包的 manifest。
+ */
+const VERSION = (() => {
+  try {
+    const require = createRequire(import.meta.url);
+    return require('../package.json').version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+})();
 const ROUTE_PREFIX = '/dsh-github-hot';
 
 const BASE = 'https://hysenlabs.com';
@@ -106,13 +120,55 @@ function dayKeyInSourceTz(ts) {
 function localDayKey(ts) {
   return dayKeyInSourceTz(ts);
 }
+/** 版本检查缓存：一天查一次足够（npm 上不会一天发几十个版本）。 */
+const UPDATE_CACHE_KEY = 'update:npm';
+const UPDATE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 比较两个 semver 版本号（忽略预发布后缀）。
+ * 返回 1：a 更新；0：相同；-1：b 更新。
+ */
+function compareVersion(a, b) {
+  const norm = (v) => String(v || '').split('-')[0].split('.').map((x) => Number(x) || 0);
+  const pa = norm(a);
+  const pb = norm(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+/**
+ * 退出前把未落盘的译文写掉。
+ * 只注册一次；用 once 事件避免多次注册。
+ */
+let zhExitHookBound = false;
+function bindZhExitHook() {
+  if (zhExitHookBound) return;
+  zhExitHookBound = true;
+  const flush = () => { try { flushZhNow(); } catch { /* 忽略 */ } };
+  process.once('exit', flush);
+  process.once('SIGINT', flush);
+  process.once('SIGTERM', flush);
+}
+
 /** 翻译并发：模型调用是 IO 等待，8 条同时翻比 4 条快一倍。 */
 const TRANSLATE_CONCURRENCY = 8;
 /** 取数并发：抓对方站点，礼貌一点。 */
 const FETCH_CONCURRENCY = 4;
 
 /** 单次请求超时。 */
-const REQUEST_TIMEOUT_MS = 20000;
+/**
+ * 单次出网超时。
+ *
+ * 20 秒太长了：曲线 SVG 偶发挂住时，整个详情页要干等 20 秒才报错，
+ * 用户体感就是「点了没反应，过一会儿才出错」。8 秒足够正常请求完成
+ * （实测 1~3 秒），超了就放弃这条、界面显示「暂无曲线」，不影响简介。
+ */
+const REQUEST_TIMEOUT_MS = 8000;
 /** 简介最多保留多少字（页面提取的第一段结论通常几百字）。 */
 const DESC_MAX_CHARS = 260;
 
@@ -165,6 +221,13 @@ function cleanHtml(input) {
     .replace(/&gt;/g, '>')
     .replace(/&quot;/g, '"')
     .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    /**
+     * 数字字符引用统一解码：&#x27; 和 &#39; 是同一条（十六进制/十进制），
+     * 页面里两种写法都会出现，只处理 &#39; 会漏掉 &#x27;，显示成 GitHub&#x27;s。
+     */
+    .replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
     .replace(/\s+/g, ' ')
     .trim();
 }
@@ -193,8 +256,9 @@ const CACHE_FILE_NAME = 'cache.json';
  * 旧文件会被整体丢弃 —— 否则会用「结构已过期」的数据静默喂给界面。
  *
  * v3：曲线日期改为 UTC 口径统一计算 + 时区统一到数据源（Asia/Shanghai）。
+ * v4：详情增加 glance（At a glance 问答），旧的没有这字段的缓存全部作废。
  */
-const CACHE_STRUCTURE_VERSION = 3;
+const CACHE_STRUCTURE_VERSION = 4;
 const CACHE_MAX_ENTRIES = 800;
 const FLUSH_DELAY_MS = 3000;
 
@@ -220,6 +284,7 @@ function ensureCacheLoaded() {
     const now = Date.now();
     for (const [key, entry] of Object.entries(data.entries)) {
       if (!entry || typeof entry.at !== 'number') continue;
+      if (entry.value && entry.value.chartPending) continue; // 上次进程的在途请求已不存在
       // 只恢复「不是太旧」的条目：按天缓存的跨天就丢，避免恢复一堆废数据
       if (now - entry.at > DAY_MS) continue;
       cache.set(key, { at: entry.at, value: entry.value });
@@ -306,6 +371,8 @@ const HOST_CONCURRENCY = 4;
 /** 每个 host 的在途计数与等待队列。 */
 const hostState = new Map();
 let lastError = null;
+/** 最近一次 /detail 的分段耗时（毫秒），只在 /diag 里暴露。 */
+let lastTiming = null;
 
 function hostOf(url) {
   try {
@@ -556,6 +623,8 @@ async function fetchWeekly() {
   }
 
   let lastError = null;
+/** 最近一次 /detail 的分段耗时（毫秒），只在 /diag 里暴露。 */
+let lastTiming = null;
   for (const week of candidates) {
     const url = BASE + '/weekly/' + week;
     try {
@@ -600,14 +669,37 @@ function parseAvatarUrl(html) {
   return m ? 'https://avatars.githubusercontent.com/u/' + m[1] + '?s=96&v=4' : null;
 }
 
-function parseWhatIsIt(html) {
-  const m = html.match(/What is it\?[\s\S]{0,80}?<\/dt>[\s\S]*?<dd[^>]*>([\s\S]*?)<\/dd>/i)
-    || html.match(/<h3[^>]*>\s*What is it\?\s*<\/h3>[\s\S]*?<p[^>]*>([\s\S]*?)<\/p>/i);
-  if (m) {
-    const cleaned = cleanHtml(m[1]);
-    if (cleaned) return cleaned;
+/**
+ * 解析项目页的「At a glance」区块 —— 一组结构化的问答。
+ *
+ * 页面结构：
+ *   <dl><div><dt>What is it?</dt><dd>...</dd></div>
+ *       <div><dt>Who is it for?</dt><dd>...</dd></div> ...</dl>
+ *
+ * 为什么整组都要：只取「What is it?」那一段会丢掉「能不能商用」「还在维护吗」
+ * 「用什么写的」这些用户真正关心的信息。源码里写成一个数组，
+ * 前端按顺序渲染成表格式问答。
+ *
+ * 返回 [{ q, a }]（英文原文）；解析不出返回空数组。
+ */
+function parseGlance(html) {
+  const items = [];
+  const re = /<dt[^>]*>([\s\S]*?)<\/dt>\s*<dd[^>]*>([\s\S]*?)<\/dd>/gi;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    const q = cleanHtml(m[1]);
+    const a = cleanHtml(m[2]);
+    if (q && a) items.push({ q, a });
+    if (items.length >= 8) break; // 正常 5 条，留点余量
   }
-  return null;
+  return items;
+}
+
+/** 只取「What is it?」的答案（兼容旧字段）。 */
+function parseWhatIsIt(html) {
+  const items = parseGlance(html);
+  const hit = items.find((it) => /^what\s+is\s+it\??$/i.test(it.q));
+  return hit ? hit.a : (items[0] ? items[0].a : null);
 }
 
 /**
@@ -765,24 +857,31 @@ let prewarmRunning = false;
 
 async function prewarmTranslation(ctx, rows) {
   if (prewarmRunning || !ctx) return;
-  const targets = (rows || []).slice(0, PREWARM_LIMIT).filter((r) => r && r.desc);
+  const targets = (rows || []).slice(0, PREWARM_LIMIT).filter((r) => r && (r.desc || (r.glance && r.glance.length)));
   if (targets.length === 0) return;
   prewarmRunning = true;
   try {
-    let cursor = 0;
-    const worker = async () => {
-      for (;;) {
-        const i = cursor++;
-        if (i >= targets.length) return;
-        try {
-          await translateDesc(ctx, targets[i].desc);
-        } catch {
-          /* 单条失败忽略 */
+    /**
+     * **按排名严格串行**预翻译。
+     *
+     * 为什么串行而不是并发 4：用户点开的第一张卡几乎总是排在最前面的那名。
+     * 串行保证「第 1 名先好、第 2 名其次」—— 用户看第一个的时候，后面几个
+     * 正在依次翻译，滚下去时大多已经有了。并发 4 的话前 4 名同时开跑，
+     * 第 1 名反而不一定最早完成。
+     *
+     * 每翻完一条就落盘（zhCacheSet 内部有节流 flush），进程重启也不丢。
+     */
+    for (const row of targets) {
+      try {
+        // 简介与问答都要翻；内部有哈希缓存，翻过的不再调模型
+        if (row.desc) await translateDesc(ctx, row.desc);
+        if (Array.isArray(row.glance) && row.glance.length > 0) {
+          await translateGlance(ctx, row.glance);
         }
+      } catch {
+        /* 单条失败忽略，继续下一条 */
       }
-    };
-    // 并发 4：比用户请求低，避免抢带宽
-    await Promise.all(Array.from({ length: Math.min(4, targets.length) }, worker));
+    }
   } finally {
     prewarmRunning = false;
   }
@@ -922,21 +1021,33 @@ function ensureZhLoaded() {
   }
 }
 
+/** 把译文缓存整体写盘。 */
+function flushZhNow() {
+  try {
+    const file = zhFilePath();
+    const dir = join(file, '..');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    let entries = [...zhCache.entries()];
+    if (entries.length > ZH_MAX) entries = entries.slice(-ZH_MAX);
+    writeFileSync(file, JSON.stringify(Object.fromEntries(entries)), 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 落盘节流：写完一条后 800ms 内不再写，避免批量翻译时频繁 IO。
+ *
+ * 另外注册了进程退出钩子直接同步写一次 —— 否则刚翻完就关掉 DSH，
+ * 那几条译文只在内存里，下次打开还得重翻（用户感知就是「缓存没用」）。
+ */
 function scheduleZhFlush() {
   if (zhFlushTimer !== null) return;
   zhFlushTimer = setTimeout(() => {
     zhFlushTimer = null;
-    try {
-      const file = zhFilePath();
-      const dir = join(file, '..');
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-      let entries = [...zhCache.entries()];
-      if (entries.length > ZH_MAX) entries = entries.slice(-ZH_MAX);
-      writeFileSync(file, JSON.stringify(Object.fromEntries(entries)), 'utf8');
-    } catch {
-      /* 忽略 */
-    }
-  }, 3000);
+    flushZhNow();
+  }, 800);
   if (typeof zhFlushTimer.unref === 'function') zhFlushTimer.unref();
 }
 
@@ -946,12 +1057,23 @@ function sha1(input) {
 
 function zhCacheGet(text) {
   ensureZhLoaded();
+  /**
+   * ⚠️ 这里存的是**纯字符串**（见 zhCacheSet：set(hash, zh)）。
+   *
+   * 之前写成 `hit ? hit.zh : null` —— 字符串没有 .zh 属性，永远取到 undefined，
+   * 于是译文缓存**只写不读**：每条都要重新调模型，用户感知就是「完全没缓存」。
+   * 现在按字符串取，同时兼容历史 JSON 里可能出现的 {zh} 结构。
+   */
   const hit = zhCache.get(sha1(text));
-  return hit ? hit.zh : null;
+  if (hit === undefined || hit === null) return null;
+  if (typeof hit === 'string') return hit || null;
+  if (typeof hit === 'object' && typeof hit.zh === 'string') return hit.zh || null;
+  return null;
 }
 
 function zhCacheSet(text, zh) {
   ensureZhLoaded();
+  bindZhExitHook();
   zhCache.set(sha1(text), zh);
   scheduleZhFlush();
   if (zhCache.size > ZH_MAX) {
@@ -1049,7 +1171,8 @@ async function pickModel(ctx, llm) {
   // 1) 宿主默认模型
   try {
     const svc = service(ctx, 'agentDefaultModel');
-    const def = typeof svc?.get === 'function' ? svc.get() : svc?.current ?? svc?.value;
+    const def = typeof svc?.currentSelection === 'function' ? svc.currentSelection()
+      : typeof svc?.get === 'function' ? svc.get() : svc?.current ?? svc?.value;
     const resolved = await def;
     const provider = resolved?.provider ?? resolved?.providerId;
     const model = resolved?.model ?? resolved?.modelId;
@@ -1083,6 +1206,85 @@ async function pickModel(ctx, llm) {
   return null;
 }
 
+/**
+ * 把一组问答**一次性**翻成中文。
+ *
+ * 为什么批量：3 条问答各调一次模型，光排队就要十几秒；合成一次请求
+ * 让模型按序号返回，总耗时和翻一段差不多。
+ *
+ * 返回与入参等长的数组；任何一条翻不出来就留 null，界面回退英文原文。
+ */
+async function translateGlance(ctx, items) {
+  const list = Array.isArray(items) ? items : [];
+  if (list.length === 0) return [];
+
+  // 先看缓存：每条按原文哈希查，全命中就直接返回，一次模型都不调
+  const cached = list.map((it) => zhCacheGet(it.a));
+  if (cached.every((x) => x)) return cached;
+
+  const llm = service(ctx, 'llm');
+  if (llm === undefined || typeof llm.stream !== 'function') return cached.map((x) => x || null);
+  const picked = await pickModel(ctx, llm);
+  if (!picked) return cached.map((x) => x || null);
+  const { provider, model } = picked;
+  const llmMod = await loadLlmModule();
+
+  // 拼成 1) ... 2) ... 3) ... 的编号格式，要求按同样编号返回
+  const body = list
+    .map((it, i) => (i + 1) + '. ' + String(it.a).trim())
+    .join('\n\n');
+  const system =
+    '你是技术编辑。下面是若干条英文项目说明，按编号逐条翻译成简体中文。' +
+    '要求：严格按 "编号. 译文" 的格式输出，每个编号一行，不要合并或省略；' +
+    '保留专有名词（项目名、工具名、命令、许可证名）原样不译；' +
+    '不要任何解释、前缀或 Markdown。';
+
+  const message =
+    typeof llmMod?.createUserMessage === 'function'
+      ? llmMod.createUserMessage({ content: [{ type: 'text', text: body }], source: { kind: 'user' } })
+      : { id: randomUUID(), role: 'user', content: [{ type: 'text', text: body }], source: { kind: 'user' } };
+
+  try {
+    let raw = '';
+    const options = {
+      provider,
+      model,
+      sessionId: 'dsh-github-hot:translate-glance',
+      messages: [message],
+      system,
+      temperature: 0.2,
+      reasoningEffort: 'off',
+      // 多条一起翻，给足时间但别无限等
+      signal: AbortSignal.timeout(20000),
+    };
+    if (typeof llmMod?.BlockAssembler === 'function') {
+      const assembler = new llmMod.BlockAssembler();
+      for await (const chunk of llm.stream(options)) assembler.push(chunk);
+      raw = assembler.blocks().filter((b) => b.type === 'text').map((b) => ('text' in b ? b.text : '')).join('');
+    } else {
+      const chunks = [];
+      for await (const chunk of llm.stream(options)) chunks.push(chunk);
+      raw = textFromChunks(chunks).text;
+    }
+
+    // 按 "编号." 切开，逐条对上
+    const parts = String(raw || '').split(/\n\s*(?=\d+[.、)]\s)/);
+    const out = list.map((it, i) => {
+      if (cached[i]) return cached[i]; // 已缓存的不动
+      const seg = parts.find((x) => x.trim().startsWith((i + 1) + '.') || x.trim().startsWith((i + 1) + '、'));
+      if (!seg) return null;
+      const zh = seg.replace(/^\s*\d+[.、)]\s*/, '').trim();
+      // 校验：必须含中文且不等于原文
+      if (!zh || !/[\u4e00-\u9fa5]/.test(zh) || zh === String(it.a).trim()) return null;
+      zhCacheSet(it.a, zh);
+      return zh;
+    });
+    return out;
+  } catch {
+    return cached.map((x) => x || null);
+  }
+}
+
 async function translateDesc(ctx, text) {
   const src = String(text || '').trim();
   if (!src) return null;
@@ -1158,6 +1360,15 @@ async function translateDesc(ctx, text) {
  */
 function detailShapeOk(detail) {
   if (!detail || typeof detail !== 'object') return false;
+  /**
+   * 必须带 glance 字段（哪怕是空数组）。
+   *
+   * 少了这一条，0.1.x 时期缓存的老数据会被当成有效缓存继续用 ——
+   * 界面就拿不到问答表，表现为「新版装了但详情页没变化」。宁可重取一次。
+   */
+  if (!Array.isArray(detail.glance)) return false;
+  // 取数失败的结果不能当成有效缓存（否则那天再点都返回错误）
+  if (detail.pageError) return false;
   const chart = detail.chart;
   if (!chart) return true; // 没曲线是允许的（可能只是取不到）
   if (!Array.isArray(chart.series) || chart.series.length === 0) return false;
@@ -1193,22 +1404,49 @@ async function fetchDetailInner(repo, slug) {
   if (cached && detailShapeOk(cached)) return { ...cached, cached: true };
   if (cached) cache.delete(cacheKey); // 结构过期，丢掉重取
 
-  const [pageResult, chartResult] = await Promise.allSettled([
-    fetchText(BASE + '/projects/' + slug),
-    fetchText(BASE + '/chart/' + slug + '.svg', { accept: 'image/svg+xml,*/*' }),
+  /**
+   * 页面与曲线**同时发起**，但**页面一到就先把详情返回给用户**，曲线在后台补。
+   *
+   * 为什么不能等两个都完成：曲线 SVG 偶发挂住（尤其冷门项目），
+   * 等它会让「简介、问答、KPI」一起干等 8 秒 —— 明明页面数据早就到了。
+   * 现在用 GRACE_MS 给曲线一个很短的等待窗口：赶得上就一起返回，
+   * 赶不上就先返回页面数据、曲线稍后由前端再取一次。
+   */
+  const chartPromise = fetchText(BASE + '/chart/' + slug + '.svg', { accept: 'image/svg+xml,*/*' });
+  const pagePromise = fetchText(BASE + '/projects/' + slug);
+  const GRACE_MS = 1200;
+  const race = await Promise.race([
+    Promise.allSettled([pagePromise, chartPromise]),
+    pagePromise.then(
+      (v) => ({ early: true, page: v }),
+      (e) => ({ early: true, pageError: e }),
+    ).then((r) => new Promise((res) => setTimeout(() => res(r), GRACE_MS))),
   ]);
 
+  let pageResult;
+  let chartResult;
+  if (race && race.early) {
+    pageResult = race.pageError ? { status: 'rejected', reason: race.pageError } : { status: 'fulfilled', value: race.page };
+    // 曲线还没回来：给它一个明确的「稍后再取」标记，而不是报错
+    chartResult = { status: 'pending' };
+  } else {
+    [pageResult, chartResult] = race;
+  }
+
   let desc = null;
   let descSource = 'none';
   let pageUrl = BASE + '/projects/' + slug;
   let started = null;
   let whatIsIt = null;
+  /** At a glance 的完整问答（5 组）；详情页展示来源用，比单段简介信息量大 */
+  let glance = [];
 
   let avatarUrl = null;
   if (pageResult.status === 'fulfilled') {
     const html = pageResult.value;
     avatarUrl = parseAvatarUrl(html);
     const conclusion = parseConclusion(html);
+    glance = parseGlance(html);
     whatIsIt = parseWhatIsIt(html);
     started = (html.match(/Last updated\s+([A-Z][a-z]+ \d{1,2}, \d{4})/i) || [])[1] || null;
     if (conclusion) {
@@ -1222,11 +1460,16 @@ async function fetchDetailInner(repo, slug) {
 
   let chart = null;
   let chartError = null;
-  if (chartResult.status === 'fulfilled') {
+  let chartPending = false;
+  if (chartResult.status === 'pending') {
+    chartPending = true; // 前端据此再取一次，不影响页面其它内容
+  } else if (chartResult.status === 'fulfilled') {
     chart = parseChartSvg(chartResult.value);
     if (!chart) chartError = '曲线 SVG 解析失败';
   } else {
-    chartError = String(chartResult.reason && chartResult.reason.message ? chartResult.reason.message : chartResult.reason);
+    const why = chartResult.reason && chartResult.reason.message ? chartResult.reason.message : String(chartResult.reason);
+    // 超时单独说清楚，别把「网络慢」显示成「fetch failed」
+    chartError = /abort|timeout|超时/i.test(why) ? '网络超时' : why;
   }
 
   const value = {
@@ -1238,16 +1481,37 @@ async function fetchDetailInner(repo, slug) {
     desc,
     descSource,
     whatIsIt,
+    glance,
     analysisUpdated: started,
     chart,
     chartError,
+    chartPending,
     pageError:
       pageResult.status === 'rejected'
         ? String(pageResult.reason && pageResult.reason.message ? pageResult.reason.message : pageResult.reason)
         : null,
     fetchedAt: nowIso(),
   };
-  cacheSet(cacheKey, value);
+  /**
+   * 只缓存**页面取到**的结果。
+   *
+   * 之前无条件 cacheSet —— 网络抖一次就把「pageError: fetch failed」存进缓存，
+   * 之后那天再点这个项目都直接返回这份失败结果（cached: true），
+   * 表现就是「第一个项目永远拉取失败，点别的却正常」。失败的不能缓存。
+   */
+  if (!value.pageError) cacheSet(cacheKey, value);
+  if (chartPending) {
+    // 页面先返回后，仍需把晚到的曲线写回缓存，不能全天缓存 pending。
+    void chartPromise.then((svg) => {
+      value.chart = parseChartSvg(svg);
+      value.chartError = value.chart ? null : '曲线 SVG 解析失败';
+    }, (error) => {
+      value.chartError = String(error && error.message ? error.message : error);
+    }).finally(() => {
+      value.chartPending = false;
+      if (cache.get(cacheKey)?.value === value) cacheSet(cacheKey, value);
+    });
+  }
   return { ...value, cached: false };
 }
 
@@ -1398,6 +1662,8 @@ async function fetchAvatar(owner, knownUrl) {
 
   // ③ 出网
   let lastError = null;
+/** 最近一次 /detail 的分段耗时（毫秒），只在 /diag 里暴露。 */
+let lastTiming = null;
   for (const url of avatarSources(key, knownUrl)) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
@@ -1456,13 +1722,28 @@ async function handleRoute(ctx, req, res) {
 
     if (path === '/detail') {
       const repository = url.searchParams.get('repo') || '';
+      const t0 = Date.now();
       const detail = await fetchDetail(repository);
-      // 简介翻成中文（拿不到译文就留 null，界面回退英文原文）
+      const t1 = Date.now();
+      /**
+       * 简介与问答分别翻成中文（拿不到译文就留 null，界面回退英文原文）。
+       *
+       * 两个函数内部都按原文哈希查缓存，命中时不调模型 —— 所以这里直接调用，
+       * 不需要额外判断「翻译过没有」。
+       */
       let descZh = null;
-      if (detail && detail.desc) {
+      if (url.searchParams.get('translate') !== '0' && detail && detail.desc) {
         try { descZh = await translateDesc(ctx, detail.desc); } catch { descZh = null; }
       }
-      sendJson(res, 200, { ok: true, detail: { ...detail, descZh } });
+      const t2 = Date.now();
+      let glanceZh = null;
+      if (url.searchParams.get('translate') !== '0' && detail && Array.isArray(detail.glance) && detail.glance.length > 0) {
+        try { glanceZh = await translateGlance(ctx, detail.glance); } catch { glanceZh = null; }
+      }
+      const t3 = Date.now();
+      // 计时只在 /diag 可见，正常请求不打日志
+      lastTiming = { detail: t1 - t0, descZh: t2 - t1, glanceZh: t3 - t2, total: t3 - t0 };
+      sendJson(res, 200, { ok: true, detail: { ...detail, descZh, glanceZh } });
       return;
     }
 
@@ -1534,6 +1815,7 @@ async function handleRoute(ctx, req, res) {
               descSource: detail.descSource,
               chart: detail.chart,
               chartError: detail.chartError,
+              chartPending: detail.chartPending,
               avatar,
             };
           } catch (error) {
@@ -1556,7 +1838,7 @@ async function handleRoute(ctx, req, res) {
        * 响应发出去之后再**后台预翻译**（不 await，不拖慢这次响应）。
        * 用户此刻看到的是英文；等他切到「中文」时，译文大多已经热好了。
        */
-      if (wantZh !== true) {
+      if (wantZh !== true && url.searchParams.get('translate') !== '0') {
         void prewarmTranslation(ctx, items.map((it) => ({ desc: it.desc, repository: it.repository })));
       }
       return;
@@ -1686,6 +1968,76 @@ async function handleRoute(ctx, req, res) {
       return;
     }
 
+    /**
+     * 版本检查：告诉前端「有没有新版本」。
+     *
+     * 为什么放在宿主侧而不是浏览器直接查 npm：
+     *   · 浏览器跨域请求 npm registry 会被 CORS 拦；
+     *   · 顺便可以做缓存，避免每次开面板都打一次 npm。
+     *
+     * 缓存策略：每天最多查一次（数据源思路一致，不需要分钟级）。
+     * npm 查询失败不影响插件使用，返回 checked:false 即可。
+     */
+    /**
+     * 预翻译：前端拿到榜单后调用，让宿主**按排名顺序**把前 N 个项目的
+     * 简介与问答翻好并落盘。
+     *
+     * 立即返回（不等待），翻译在后台跑。这样用户点开第 1 名时，
+     * 第 2、3、4 名正在依次翻译中。
+     */
+    if (path === '/prewarm') {
+      const repos = String(url.searchParams.get('repos') || '').split(',').map((x) => x.trim()).filter(Boolean);
+      const limit = Math.min(Number(url.searchParams.get('limit')) || 20, 30);
+      sendJson(res, 200, { ok: true, queued: repos.length, running: prewarmRunning });
+      if (!prewarmRunning && repos.length > 0) {
+        void (async () => {
+          const rows = [];
+          for (const repo of repos.slice(0, limit)) {
+            try {
+              const detail = await fetchDetail(repo);
+              rows.push({ repository: repo, desc: detail.desc, glance: detail.glance });
+            } catch {
+              /* 单个失败跳过 */
+            }
+          }
+          await prewarmTranslation(ctx, rows);
+        })();
+      }
+      return;
+    }
+
+    if (path === '/update') {
+      const force = url.searchParams.get('force') === '1';
+      const hit = cacheGet(UPDATE_CACHE_KEY, UPDATE_TTL_MS);
+      if (hit && !force) {
+        sendJson(res, 200, { ok: true, ...hit, cached: true });
+        return;
+      }
+      let latest = null;
+      let error = null;
+      try {
+        const raw = await fetchText('https://registry.npmjs.org/' + name + '/latest', {
+          accept: 'application/json',
+          timeout: 8000,
+        });
+        const parsed = JSON.parse(raw);
+        latest = parsed && parsed.version ? String(parsed.version) : null;
+      } catch (e) {
+        error = String(e && e.message ? e.message : e);
+      }
+      const payload = {
+        current: VERSION,
+        latest,
+        hasUpdate: latest ? compareVersion(latest, VERSION) > 0 : false,
+        checkedAt: nowIso(),
+        error,
+      };
+      // 查到了才缓存；失败不缓存，下次还能重试
+      if (latest) cache.set(UPDATE_CACHE_KEY, { at: Date.now(), value: payload });
+      sendJson(res, 200, { ok: true, ...payload, cached: false });
+      return;
+    }
+
     if (path === '/status') {
       sendJson(res, 200, {
         ok: true,
@@ -1693,6 +2045,7 @@ async function handleRoute(ctx, req, res) {
         version: VERSION,
         cacheSize: cache.size,
         lastError,
+        lastTiming,
       });
       return;
     }
@@ -1732,6 +2085,7 @@ export const __internals = {
   parseChartSvg,
   parseConclusion,
   parseWhatIsIt,
+  parseGlance,
   slugOf,
   currentWeekMonday,
   dayKeyInSourceTz,
@@ -1740,9 +2094,13 @@ export const __internals = {
   handleRoute,
   parseAvatarUrl,
   fetchAvatar,
+  compareVersion,
   detailShapeOk,
   cacheGet,
   cacheSet,
+  flushZhNow,
+  zhCacheGet,
+  zhCacheSet,
   localDayKey,
   DAY_MS,
   /** 仅供测试：直接拿到缓存表，用来伪造写入时间 */