dsh-lighthouse 0.0.0-stage → 0.3.4

package/lib/render.js

@@ -0,0 +1,415 @@
+/**
+ * dsh-lighthouse · render —— 把报告渲染成两种东西：给 agent 看的一段话，和给人看的一张卡片。
+ *
+ * 卡片是**单文件 HTML**：无外链、无脚本依赖、深色、数字大 —— 落盘后可以直接打开、截图发出去。
+ *
+ * @module dsh-lighthouse/render
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hoursText } from './collect.js';
+
+/** HTML 转义。 */
+function esc(text) {
+  return String(text ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** ISO 时间 → `MM-DD HH:mm`。 */
+function shortTime(iso) {
+  if (typeof iso !== 'string' || iso === '') return '—';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '—';
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** 超过这个数量就自动切成紧凑视图（50 个作品时逐张卡片已经读不动了）。 */
+export const COMPACT_THRESHOLD = 12;
+
+/**
+ * 一个作品的"紧急度"排序键：**需要人动手的在前**。
+ *   0 = 有异常（GitHub/市场读不到、仓库不存在、没有 PR）
+ *   1 = 还在等收录（PR open，按等得久的优先）
+ *   2 = 已收录
+ * @param {object} item 报告里的一项
+ * @returns {{tier:number, waitHours:number}} 排序键
+ */
+export function urgencyOf(item) {
+  const { github, market } = item;
+  const pr = github?.pr ?? null;
+  const waitHours = pr?.createdAt ? (Date.now() - Date.parse(pr.createdAt)) / 3600000 : 0;
+  const broken = github?.exists !== true || market?.available !== true || (github?.exists === true && pr === null);
+  if (broken) return { tier: 0, waitHours };
+  if (market?.listed === true) return { tier: 2, waitHours };
+  return { tier: 1, waitHours };
+}
+
+/**
+ * 排好序的作品列表：需要盯的在前，同层里等得久的在前。
+ * @param {Array<object>} works 报告里的 works
+ * @returns {Array<object>} 新数组（不改原对象顺序）
+ */
+export function sortWorks(works) {
+  return [...(Array.isArray(works) ? works : [])]
+    .map((item) => ({ item, key: urgencyOf(item) }))
+    .sort((a, b) => a.key.tier - b.key.tier || b.key.waitHours - a.key.waitHours)
+    .map((entry) => entry.item);
+}
+
+/**
+ * 给 agent 的一段话。
+ * @param {object} report collectAll 的结果
+ * @returns {string} 文本
+ */
+export function renderText(report) {
+  const lines = [];
+  const s = report.summary;
+  const marketReadable = report.market.available === true;
+  lines.push(`作品看板｜${shortTime(report.generatedAt)}｜${report.owner}`);
+  // 市场读不到时**不许显示 0 收录 / 0 下载** —— 那会让人以为"没人用"，而事实是"没读到"。
+  lines.push(
+    marketReadable
+      ? `  汇总：${s.works} 个作品 · 已发布 ${s.published} · 市场已收录 ${s.listed} · 总下载 ${s.totalDownloads} · 总 star ${s.totalStars} · 待合 PR ${s.openPrs}`
+      : `  汇总：${s.works} 个作品 · 已发布 ${s.published} · **市场数据读不到**（不显示 0，免得被当成没人用） · 总 star ${s.totalStars} · 待合 PR ${s.openPrs}`,
+  );
+  if (marketReadable) {
+    lines.push(`  市场登记表：${report.market.count} 条（更新于 ${String(report.market.updated ?? '?')}）`);
+  } else {
+    lines.push(`  市场登记表：**读不到**（${report.market.reason ?? '未知原因'}）—— 已收录/下载量这几项本次一律不报数`);
+  }
+  if (report.upstream?.available === true) {
+    lines.push(`  上游合并节奏：中位数 ${hoursText(report.upstream.medianHours)}（样本 ${report.upstream.samples} 个已合并 PR）`);
+  } else {
+    lines.push(`  上游合并节奏：**没算出来**（${report.upstream?.reason ?? '未知原因'}）`);
+  }
+
+  // 「等得比上游中位数还久」的 PR 单独点名 —— 这是真正需要盯的一批。
+  if (report.upstream?.available === true) {
+    const median = Number(report.upstream.medianHours);
+    const slow = report.works
+      .map((item) => {
+        const pr = item.github?.pr;
+        if (!pr || pr.state !== 'open' || pr.mergedAt) return null;
+        const hours = (Date.now() - Date.parse(pr.createdAt)) / 3600000;
+        return Number.isFinite(hours) && hours > median ? { name: item.work.name, number: pr.number, hours } : null;
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.hours - a.hours);
+    if (slow.length > 0) {
+      // 作品多了以后这一行会变成一坨 —— 只点名最久的几个，其余报总数（详情在卡片里）。
+      const shown = slow.slice(0, 6);
+      const rest = slow.length - shown.length;
+      lines.push(
+        `  ⏳ 超过上游中位数的 PR ${slow.length} 条：${shown.map((x) => `#${x.number}（${hoursText(x.hours)}）`).join('、')}`
+        + (rest > 0 ? ` …其余 ${rest} 条见卡片` : ''),
+      );
+    } else {
+      lines.push('  ⏳ 没有超过上游中位数的 PR（都还在正常等待区间）');
+    }
+  }
+  const ordered = sortWorks(report.works);
+  const compact = ordered.length > COMPACT_THRESHOLD;
+  if (compact) {
+    lines.push(`  （作品 ${ordered.length} 个，超过 ${COMPACT_THRESHOLD} 个自动切紧凑视图：一行一个，需要盯的排前面）`);
+  }
+
+  for (const item of ordered) {
+    const { work, local, github, market, npm } = item;
+    const bits = [];
+    bits.push(local.available === true ? `本地 ${local.version ?? '?'} / ${local.files ?? '?'} 文件${local.hasSmoke ? ' / 有自测' : ''}` : `本地 **读不到**（${local.reason ?? '?'}）`);
+    bits.push(github.exists === true ? `GitHub star ${github.stars} / 最后推送 ${shortTime(github.pushedAt)}` : (github.exists === false ? 'GitHub **没有仓库**' : `GitHub **读不到**（${github.reason ?? '?'}）`));
+    if (market.listed === true) {
+      // 没下载数 ≠ 没发 npm：下载字段市场侧可能不统计。npm 发没发看下面那行 npm 事实，不在这里推。
+      bits.push(market.downloads === null || market.downloads === undefined
+        ? '市场 **已收录**（没有下载数据）'
+        : `市场 **已收录**（下载 ${market.downloads}${market.rankInCategory ? `，同类第 ${market.rankInCategory}/${market.categorySize}` : ''}）`);
+    } else if (market.available === true) {
+      bits.push('市场 **未收录**');
+    } else {
+      bits.push(`市场 **读不到**（${market.reason ?? '?'}）`);
+    }
+    if (npm?.published === true) bits.push(`npm 有包（${npm.version}）`);
+    else if (npm?.available === true) bits.push('npm 没有');
+
+    let prText = '';
+    if (github.pr) {
+      const waited = (Date.now() - Date.parse(github.pr.createdAt)) / 3600000;
+      if (github.pr.mergedAt) prText = `／PR #${github.pr.number} **已合并**`;
+      else if (github.pr.state === 'open') {
+        const median = report.upstream?.available === true ? `（上游中位数 ${hoursText(report.upstream.medianHours)}）` : '';
+        prText = `／PR #${github.pr.number} 待合并，已等 ${hoursText(waited)}${median}`;
+      } else prText = `／PR #${github.pr.number} ${github.pr.state}`;
+    } else {
+      prText = '／**没有市场 PR**';
+    }
+
+    if (compact) {
+      // 一行一个：名字（中文） · 版本 · star · 市场/PR 状态（详情与链接看卡片）
+      const dl = market.downloads === null || market.downloads === undefined ? '下载数暂无' : `${market.downloads}↓`;
+      const marketText = market.listed !== true
+        ? (market.available === true ? '未收录' : '市场读不到')
+        : (npm?.published === true ? `已收录 · ${dl}` : (npm?.available === true ? `已收录 · ${dl} · npm 未发` : `已收录 · ${dl}`));
+      const prShort = github.pr
+        ? (github.pr.mergedAt ? `#${github.pr.number} 已合并` : (github.pr.state === 'open' ? `#${github.pr.number} 等 ${hoursText((Date.now() - Date.parse(github.pr.createdAt)) / 3600000)}` : `#${github.pr.number} ${github.pr.state}`))
+        : '无 PR';
+      lines.push(`  · ${displayName(item)}｜v${local.version ?? '?'}｜star ${github.exists === true ? github.stars : '—'}｜${marketText}｜${prShort}`);
+      if (github.exists !== true) lines.push(`      ⚠ GitHub ${github.exists === false ? '没有仓库' : '读不到'}（${github.reason ?? '?'}）`);
+    } else {
+      lines.push(`  · ${displayName(item)}`);
+      lines.push(`      ${bits.join('｜')}${prText}`);
+      const link = item.links?.github;
+      if (link) lines.push(`      直达：${link}`);
+    }
+  }
+  lines.push('  卡片：见 htmlPath（可直接打开/截图）');
+  return lines.join('\n');
+}
+
+/** 显示名：英文名 +（中文名）。中文名来自名册 nameZh，其次 package.json 的 dsh.displayName。 */
+function displayName(item) {
+  const zh = item?.work?.nameZh ?? item?.local?.displayName ?? null;
+  return zh ? `${item.work.name}（${zh}）` : item.work.name;
+}
+
+/** 一个状态点。 */
+function dot(kind) {
+  const color = { good: '#3fb950', warn: '#d29922', bad: '#f85149', idle: '#6e7681' }[kind] ?? '#6e7681';
+  return `<span class="dot" style="background:${color}"></span>`;
+}
+
+/**
+ * 紧凑表格：作品多（> COMPACT_THRESHOLD）时用一屏多行的表格，而不是一作品一大卡。
+ * @param {Array<object>} ordered 已排序的作品
+ * @returns {string} HTML
+ */
+function renderGrid(ordered) {
+  const rows = ordered.map((item) => {
+    const { work, local, github, market, npm } = item;
+    const key = urgencyOf(item);
+    const pr = github?.pr;
+    const prText = pr
+      ? (pr.mergedAt
+        ? `${dot('good')} #${pr.number} 已合并`
+        : (pr.state === 'open'
+          ? `${dot('warn')} #${pr.number} 等 ${hoursText((Date.now() - Date.parse(pr.createdAt)) / 3600000)}`
+          : `#${pr.number} ${esc(pr.state)}`))
+      : '<span class="bad">没有 PR</span>';
+    const dlGrid = market.downloads === null || market.downloads === undefined ? '下载数暂无' : `${market.downloads}↓`;
+    const marketText = market.listed !== true
+      ? (market.available === true ? `${dot('warn')} 未收录` : '<span class="bad">读不到</span>')
+      : (npm?.available === true && npm.published !== true
+        ? `${dot('warn')} 已收录 · ${dlGrid} · npm 未发`
+        : `${dot('good')} 已收录 · ${dlGrid}`);
+    const ghText = github.exists === true
+      ? `${dot('idle')} star ${github.stars}`
+      : (github.exists === false ? '<span class="bad">仓库不存在</span>' : '<span class="bad">读不到</span>');
+    const why = key.tier === 0 ? '<div class="why">需要处理</div>' : '';
+    const link = item.links?.github ?? null;
+    const zh = work.nameZh ?? local.displayName ?? null;
+    const nameCell = link
+      ? `<a href="${esc(link)}" target="_blank" rel="noreferrer">${esc(work.name)}</a>`
+      : esc(work.name);
+    return `<tr class="t${key.tier}">
+      <td class="name">${nameCell}${zh ? `<span class="zh">${esc(zh)}</span>` : ''}${why}</td>
+      <td>${esc(work.category ?? '—')}</td>
+      <td class="num">${esc(local.available === true ? local.version ?? '?' : '读不到')}</td>
+      <td>${ghText}</td>
+      <td>${marketText}</td>
+      <td class="num">${prText}</td>
+    </tr>`;
+  }).join('\n');
+
+  return `<table class="grid">
+    <thead><tr><th>作品（需要处理的排前面）</th><th>分类</th><th>版本</th><th>GitHub</th><th>市场</th><th>收录 PR</th></tr></thead>
+    <tbody>
+${rows}
+    </tbody>
+  </table>`;
+}
+
+/**
+ * 给人看的卡片（单文件 HTML）。
+ * @param {object} report collectAll 的结果
+ * @returns {string} HTML
+ */
+export function renderHtml(report) {
+  const s = report.summary;
+  const median = report.upstream?.available === true ? `上游中位数 ${hoursText(report.upstream.medianHours)}` : '上游节奏未知';
+  const ordered = sortWorks(report.works);
+  const compact = ordered.length > COMPACT_THRESHOLD;
+
+  const cards = ordered.map((item) => {
+    const { work, local, github, market, npm } = item;
+    const listed = market.listed === true;
+    const rows = [];
+
+    rows.push(`<div class="row"><span class="k">本地</span><span class="v">${
+      local.available === true
+        ? `${esc(local.version ?? '?')} · ${local.files ?? '?'} 文件${local.hasSmoke ? ' · 有自测' : ''}`
+        : `<span class="bad">读不到（${esc(local.reason ?? '')}）</span>`
+    }</span></div>`);
+
+    rows.push(`<div class="row"><span class="k">GitHub</span><span class="v">${
+      github.exists === true
+        ? `${dot(github.stars > 0 ? 'good' : 'idle')} star ${github.stars} · fork ${github.forks} · 最后推送 ${shortTime(github.pushedAt)}`
+        : (github.exists === false ? '<span class="bad">仓库不存在</span>' : `<span class="bad">读不到（${esc(github.reason ?? '')}）</span>`)
+    }</span></div>`);
+
+    rows.push(`<div class="row"><span class="k">市场</span><span class="v">${
+      listed
+        ? (market.downloads === null || market.downloads === undefined
+          ? `${dot('warn')} 已收录 · 下载数暂无`
+          : `${dot('good')} 已收录 · 下载 <b>${market.downloads}</b>${market.rankInCategory ? ` · 同类 ${market.rankInCategory}/${market.categorySize}` : ''}`)
+        : (market.available === true ? `${dot('warn')} 还没收录` : `<span class="bad">读不到（${esc(market.reason ?? '')}）</span>`)
+    }</span></div>`);
+
+    let prHtml = `<div class="row"><span class="k">收录 PR</span><span class="v"><span class="bad">没有 PR</span></span></div>`;
+    if (github.pr) {
+      const waited = (Date.now() - Date.parse(github.pr.createdAt)) / 3600000;
+      if (github.pr.mergedAt) {
+        prHtml = `<div class="row"><span class="k">收录 PR</span><span class="v">${dot('good')} #${github.pr.number} 已合并</span></div>`;
+      } else if (github.pr.state === 'open') {
+        prHtml = `<div class="row"><span class="k">收录 PR</span><span class="v">${dot('warn')} #${github.pr.number} 待合并 · 已等 <b>${hoursText(waited)}</b><span class="muted">（${esc(median)}）</span></span></div>`;
+      } else {
+        prHtml = `<div class="row"><span class="k">收录 PR</span><span class="v">#${github.pr.number} ${esc(github.pr.state)}</span></div>`;
+      }
+    }
+    rows.push(prHtml);
+
+    if (npm?.published === true) {
+      rows.push(`<div class="row"><span class="k">npm</span><span class="v">${dot('good')} 有包 ${esc(npm.version ?? '')}</span></div>`);
+    } else if (npm?.available === true) {
+      rows.push(`<div class="row"><span class="k">npm</span><span class="v">${dot('warn')} registry 上没有这个包</span></div>`);
+    } else if (npm?.reason) {
+      rows.push(`<div class="row"><span class="k">npm</span><span class="v">${dot('idle')} 没查到（${esc(npm.reason)}）</span></div>`);
+    }
+
+    const head = listed ? 'listed' : (github.exists === true ? 'shipped' : 'local');
+    const headText = listed ? '已上市场' : (github.exists === true ? '已发布 · 等收录' : '仅本地');
+    const link = item.links?.github ?? null;
+    const zh = work.nameZh ?? local.displayName ?? null;
+    const title = link
+      ? `<a href="${esc(link)}" target="_blank" rel="noreferrer">${esc(work.name)}</a>`
+      : esc(work.name);
+
+    // 直达：GitHub / npm / 市场条目页（能确定才给，不编地址）
+    const linkBits = [];
+    if (link) linkBits.push(`<a href="${esc(link)}" target="_blank" rel="noreferrer">GitHub</a>`);
+    if (npm?.available === true && item.links?.npm) linkBits.push(`<a href="${esc(item.links.npm)}" target="_blank" rel="noreferrer">npm${npm.published === true ? '' : '（没有）'}</a>`);
+    if (item.links?.market) linkBits.push(`<a href="${esc(item.links.market)}" target="_blank" rel="noreferrer">市场条目</a>`);
+    if (linkBits.length > 0) rows.push(`<div class="row"><span class="k">直达</span><span class="v">${linkBits.join(' · ')}</span></div>`);
+
+    return `<section class="card ${head}">
+      <header>
+        <h2>${title}${zh ? `<span class="zh">${esc(zh)}</span>` : ''}</h2>
+        <span class="badge">${esc(work.category ?? '—')}</span>
+        <span class="state">${headText}</span>
+      </header>
+      ${rows.join('\n      ')}
+    </section>`;
+  }).join('\n    ');
+
+  return `<!doctype html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>作品看板 · ${esc(report.owner)}</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; padding: 32px; background: #0d1117; color: #e6edf3;
+         font-family: "Segoe UI", "Microsoft YaHei", system-ui, sans-serif; }
+  .wrap { max-width: 980px; margin: 0 auto; }
+  h1 { font-size: 26px; margin: 0 0 4px; letter-spacing: .5px; }
+  .sub { color: #8b949e; font-size: 13px; margin-bottom: 22px; }
+  .tiles { display: grid; grid-template-columns: repeat(5, 1fr); gap: 12px; margin-bottom: 24px;
+           position: sticky; top: 0; z-index: 2; background: #0d1117; padding: 8px 0 12px; }
+  .tile { background: #161b22; border: 1px solid #21262d; border-radius: 12px; padding: 14px 16px; }
+  .tile .n { font-size: 26px; font-weight: 700; font-variant-numeric: tabular-nums; }
+  .tile .l { color: #8b949e; font-size: 12px; margin-top: 2px; }
+  .card { background: #161b22; border: 1px solid #21262d; border-left: 3px solid #6e7681;
+          border-radius: 12px; padding: 16px 18px; margin-bottom: 14px; }
+  .card.listed { border-left-color: #3fb950; }
+  .card.shipped { border-left-color: #d29922; }
+  .card header { display: flex; align-items: baseline; gap: 10px; margin-bottom: 10px; }
+  .card h2 { font-size: 17px; margin: 0; font-family: ui-monospace, Consolas, monospace; }
+  .card h2 a { color: inherit; text-decoration: none; border-bottom: 1px dashed #30363d; }
+  .card h2 a:hover { border-bottom-color: #58a6ff; color: #58a6ff; }
+  .zh { font-family: "Microsoft YaHei", system-ui, sans-serif; font-size: 13px; color: #8b949e; margin-left: 6px; }
+  .grid td.name a { color: inherit; text-decoration: none; border-bottom: 1px dashed #30363d; }
+  .grid td.name a:hover { border-bottom-color: #58a6ff; color: #58a6ff; }
+  .badge { font-size: 11px; color: #8b949e; border: 1px solid #30363d; border-radius: 999px; padding: 1px 8px; }
+  .state { margin-left: auto; font-size: 12px; color: #8b949e; }
+  .row { display: flex; gap: 10px; padding: 3px 0; font-size: 13px; line-height: 1.7; }
+  .k { color: #8b949e; width: 68px; flex: none; }
+  .v { font-variant-numeric: tabular-nums; }
+  .muted { color: #6e7681; }
+  .bad { color: #f85149; }
+  .dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; margin-right: 6px; }
+  .grid { width: 100%; border-collapse: collapse; font-size: 13px; }
+  .grid th { text-align: left; color: #8b949e; font-weight: 600; font-size: 12px;
+             padding: 8px 10px; border-bottom: 1px solid #30363d; position: sticky; top: 88px;
+             background: #0d1117; z-index: 1; }
+  .grid td { padding: 7px 10px; border-bottom: 1px solid #21262d; vertical-align: top; }
+  .grid tr:hover td { background: #161b22; }
+  .grid td.name { font-family: ui-monospace, Consolas, monospace; }
+  .grid tr.t0 td.name { border-left: 3px solid #f85149; padding-left: 7px; }
+  .grid tr.t1 td.name { border-left: 3px solid #d29922; padding-left: 7px; }
+  .grid tr.t2 td.name { border-left: 3px solid #3fb950; padding-left: 7px; }
+  .grid .num { font-variant-numeric: tabular-nums; }
+  .grid .why { color: #6e7681; font-size: 12px; }
+  footer { color: #6e7681; font-size: 12px; margin-top: 20px; line-height: 1.8; }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>🚢 作品看板</h1>
+    <div class="sub">${esc(report.owner)} · 生成于 ${esc(shortTime(report.generatedAt))} · 登记表 ${esc(report.market.available === true ? `${report.market.count} 条（${report.market.updated ?? '?'}）` : '读不到')}</div>
+
+    <div class="tiles">
+      <div class="tile"><div class="n">${s.works}</div><div class="l">作品</div></div>
+      <div class="tile"><div class="n">${s.published}</div><div class="l">已发布</div></div>
+      <div class="tile"><div class="n">${s.listed}</div><div class="l">市场已收录</div></div>
+      <div class="tile"><div class="n">${s.totalDownloads}</div><div class="l">总下载</div></div>
+      <div class="tile"><div class="n">${s.openPrs}</div><div class="l">待合 PR</div></div>
+    </div>
+
+    ${compact ? renderGrid(ordered) : cards}
+
+    <footer>
+      上游 ${esc(report.upstream?.upstream ?? '?')}：${esc(median)}${report.upstream?.samples ? `（样本 ${report.upstream.samples}）` : ''}<br>
+      「市场已收录」= 市场登记表里能查到这个名字；「待合并」= 收录 PR 还开着。数字来自 GitHub API 与本机市场接口，**不经模型生成**。
+    </footer>
+  </div>
+</body>
+</html>
+`;
+}
+
+/**
+ * 把报告落盘成卡片（可选同时落一份 JSON）。
+ * @param {object} report 报告
+ * @param {object} opts 选项 `{ dir, html, json, now }`
+ * @returns {Promise<{htmlPath:string|null, jsonPath:string|null}>} 落盘结果
+ */
+export async function writeReport(report, { dir, html = true, json = false, now = Date.now() } = {}) {
+  const target = dir ?? join(process.env.USERPROFILE ?? process.env.HOME ?? '.', '.dsh', 'lighthouse-reports');
+  await mkdir(target, { recursive: true });
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const out = { htmlPath: null, jsonPath: null };
+  if (html) {
+    out.htmlPath = join(target, `lighthouse-${stamp}.html`);
+    await writeFile(out.htmlPath, renderHtml(report), 'utf8');
+  }
+  if (json) {
+    out.jsonPath = join(target, `lighthouse-${stamp}.json`);
+    await writeFile(out.jsonPath, JSON.stringify(report, null, 2), 'utf8');
+  }
+  return out;
+}

package/lib/status-route.js

@@ -0,0 +1,126 @@
+/**
+ * dsh-lighthouse · status-route —— 给界面观察区供数据的一条**只读**接口。
+ *
+ * `GET /dsh-lighthouse/status` → `{ ok, report }`（就是 `collectAll` 的那份报告）。
+ * 界面那一半（`client.js`）只负责画，不负责算 —— 所以同一个数字在面板、工具、卡片里是一致的。
+ *
+ * @module dsh-lighthouse/status-route
+ */
+
+import { collectAll } from './collect.js';
+import { readFleet } from './fleet.js';
+
+/** 观察区取数的路径。 */
+export const STATUS_ROUTE = '/dsh-lighthouse/status';
+
+/** 统一的 JSON 回包。 */
+function send(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+    'Content-Length': Buffer.byteLength(body),
+  });
+  response.end(body);
+}
+
+/** 本机匿名请求的缓存有效期 —— 免得谁都能借我的 PAT 反复去打 GitHub。 */
+export const CACHE_TTL_MS = 60_000;
+
+/**
+ * 造一个请求处理器。
+ * @param {object} options 选项
+ * @param {string} options.fleetFile 名册路径
+ * @param {string} [options.marketUrl] 市场接口根
+ * @param {string|null|Function} [options.token] GitHub PAT（也接受函数：请求时才解析）
+ * @param {Function} [options.collect] 采集实现（测试注入）
+ * @param {Function} [options.readFleetImpl] 读名册实现（测试注入）
+ * @param {Function} [options.now] 取时间（测试注入）
+ * @param {number} [options.cacheTtlMs] 匿名来源的缓存时长
+ * @returns {Function} `(request, response) => Promise<void>`
+ */
+export function createStatusHandler({
+  fleetFile,
+  marketUrl,
+  token = null,
+  collect = collectAll,
+  readFleetImpl = readFleet,
+  now = Date.now,
+  cacheTtlMs = CACHE_TTL_MS,
+} = {}) {
+  let cache = null; // { at, payload }
+
+  /** 从请求头里取来源（Origin 优先，其次 Referer；都没有就返回 null）。 */
+  function sourceOf(request) {
+    const origin = request?.headers?.origin;
+    if (typeof origin === 'string' && origin !== '') return origin;
+    const referer = request?.headers?.referer;
+    if (typeof referer === 'string' && referer !== '') return referer;
+    return null;
+  }
+
+  /**
+   * 跨源来的请求一律拒掉。
+   *
+   * 背景（实测）：**宿主不为插件注册的路由做认证** —— `webServer.register` 没有 auth 选项，
+   * 宿主根 `/` 要认证（401），插件路由却是裸的。所以准入只能自己加：
+   *   · 带了来源头（界面 fetch 会带 Referer）→ 必须与市场接口同源，否则 403；
+   *   · 没带来源头（curl / 本机脚本）→ 放行。这些信息本来就是公开的（仓库名、star 数），
+   *     真要挡本机进程也挡不住（它直接读工程目录就行），装样子没意义。
+   * 另加一层缓存兜底：界面来的请求**永远实时**（刷新按钮必须真的刷新），
+   * 匿名来源的重复请求 60 秒内吃缓存。
+   */
+  function fromElsewhere(request) {
+    const seen = sourceOf(request);
+    if (seen === null) return false;
+    try {
+      return new URL(seen).origin !== new URL(marketUrl).origin;
+    } catch {
+      return true; // 来源头读不懂：当作别处来的
+    }
+  }
+
+  /** 这次请求是不是界面（同源）来的。 */
+  function fromUi(request) {
+    const seen = sourceOf(request);
+    if (seen === null) return false;
+    try {
+      return new URL(seen).origin === new URL(marketUrl).origin;
+    } catch {
+      return false;
+    }
+  }
+
+  return async function handleStatus(request, response) {
+    const method = String(request?.method ?? 'GET').toUpperCase();
+    if (method !== 'GET' && method !== 'HEAD') {
+      send(response, 405, { ok: false, error: 'method-not-allowed' });
+      return;
+    }
+    if (fromElsewhere(request)) {
+      send(response, 403, { ok: false, error: 'cross-origin-denied' });
+      return;
+    }
+    if (fromUi(request) !== true && cache !== null && now() - cache.at < cacheTtlMs) {
+      send(response, 200, cache.payload);
+      return;
+    }
+    try {
+      const read = await readFleetImpl(fleetFile);
+      if (read.ok !== true) {
+        send(response, 200, { ok: false, errors: read.errors, fleetPath: fleetFile });
+        return;
+      }
+      // token 允许传函数：注册路由时它还没被解析，第一次请求时再拿
+      // （省得为了它把 apply 变成异步 —— 插件加载不该等网络）
+      const resolvedToken = typeof token === 'function' ? await token() : token;
+      // 观察区不查 npm（省一次外网往返），其余与工具走同一条采集路径
+      const report = await collect(read.fleet, { token: resolvedToken, marketUrl, includeNpm: false, now: now() });
+      const payload = { ok: true, report };
+      cache = { at: now(), payload };
+      send(response, 200, payload);
+    } catch (err) {
+      send(response, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+  };
+}

package/package.json

@@ -1,6 +1,93 @@
-{
-  "name": "dsh-lighthouse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "dsh-lighthouse",
+  "version": "0.3.4",
+  "description": "一屏看清每个作品现在什么样：本地版本、GitHub star、市场收没收、下载量和同类排名，还能落一张可截图的卡片。 One screen for every work you have shipped: local version, GitHub stars, market listing, downloads and category rank, plus a ready-to-screenshot card.",
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "dsh-lighthouse": "bin/dsh-lighthouse.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./fleet": "./lib/fleet.js",
+    "./collect": "./lib/collect.js",
+    "./render": "./lib/render.js",
+    "./status-route": "./lib/status-route.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "bin",
+    "client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "dashboard",
+    "release-tracker",
+    "market-registry",
+    "downloads",
+    "watchers",
+    "pull-request",
+    "observability",
+    "作品看板",
+    "观察区"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/7gzgn/dsh-lighthouse.git"
+  },
+  "homepage": "https://github.com/7gzgn/dsh-lighthouse#readme",
+  "bugs": {
+    "url": "https://github.com/7gzgn/dsh-lighthouse/issues"
+  },
+  "dsh": {
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.2": "compatible"
+      }
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.4 <5.0.0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.0-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-system-prompt": ">=0.2.0-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.2 <0.3.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-system-prompt": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  }
+}