| name | refresh-site |
| description | 跑一整轮站点数据刷新并上线：GitHub 同步（新插件/star）→ 头部插件下载量 → 头部插件安装方式 → 静态快照（首页三条 rail、插件库、排名）→ 构建验证 → 只提交生成物 → 推送触发 Cloudflare 部署。用于「好几天没更新了，把数据刷一遍」，也用于排查某一步为什么没生效。 |
站点数据刷新
一条命令：pnpm refresh（脚本 scripts/refresh-site.mjs）。五步串起来，任一步失败即中止，
工作区不会留下半截状态。
pnpm refresh
pnpm refresh --push
pnpm refresh --dry-run
pnpm refresh --with-contributors
pnpm refresh --skip-sync
pnpm refresh --min-stars 200
pnpm refresh --skip-install
五步各自在做什么
| 步骤 | 命令 | 产出 | 耗时 |
|---|
| 1 同步 | sync-plugins-db.mjs --skip-contributors | Turso：新仓库、star、每日快照 | 5-10 分钟 |
| 2 下载量 | probe-downloads.mjs --min-stars 100 --include-offtopic | Turso：dl_* 五列（增量，只探没探过或超 7 天的） | 1-5 分钟 |
| 3 安装方式 | probe-install.mjs --all --min-stars 100 | Turso：install_* / npm_latest_version / npm_desktop_installable | 1-2 分钟 |
| 4 重生成 | pnpm gen:data | plugins-real.ts / home-picks.ts（首页三条 rail）/ ranking-real.ts / plugin-i18n.ts / 文档课程清单 | 1 分钟 |
| 5 构建 | pnpm build | 验证；顺带确认详情页仍是 SSG 而不是 ƒ | 2-4 分钟 |
首页的「编辑推荐 / 本周飙升 / 新面孔」全部来自第 4 步的 home-picks.ts——不跑第 4 步，首页就不会换人。
脚本跑完会打印这三条 rail 的进出名单，一眼能看出首页变了谁。
第 3 步是头部全量重探而不是按新鲜度增量：npm_latest_version 会作为精确 revision
发给 DSH 桌面端插件市场，桌面端照着它装。头部插件一周能发十几个版本，7 天的 stale
阈值根本追不上。脚本跑完会打印「桌面端市场契约变化」，谁开始能装、谁的版本变了一目了然。
全库补探（让新收录的仓库进得了市场）不在本流程里，见 desktop-market skill。
三个容易踩的坑（脚本已经处理，但要知道为什么）
- 只提交生成物，不要
git add -A。 工作区经常有在途的功能代码（未提交的新模块），
一把梭会把没验证过的东西推上生产；更糟的是漏掉它依赖的未跟踪文件，线上构建直接
module not found。脚本里的 GENERATED 白名单只有 6 个文件。
- push 必须推
origin。 本仓库有两个远端：origin = hikariming/dshfind（驱动生产），
dsh-external = 镜像仓。推错的结果是「以为部署了，其实生产纹丝不动」。
脚本把远端写死成 origin。
- 贡献者数默认跳过。 它要逐仓库打 core API（限额 5000/时），一万多个仓库要跨 3 个
限额窗口、约 3 小时。跳过时沿用上一轮的值（upsert 里是
COALESCE）。
想补就 --with-contributors，建议单独挂后台跑。
上线与验证
推送后 Cloudflare Workers Builds 自动构建，约 6 分钟生效。验证：
curl -s "https://dshfind.com/api/badge/omdsh-dev/DSH-better-sidebar?metric=downloads" | grep -o 'aria-label="[^"]*"'
curl -s "https://dshfind.com/zh/plugins/omdsh-dev/DSH-better-sidebar" | grep -o '下载量.\{0,40\}'
看响应头 x-nextjs-prerender 能区分两类页面：1,1 是构建期预渲染的头部 24 个，
1 是按需渲染的其余一万多个。两类的数据来源不同——见下。
数据为什么可能「看起来没更新」
按可能性排序：
- 第 4 步没跑：数据在 Turso 里是新的，但首页/插件库读的是构建期快照。
pnpm refresh 一定会跑。
- 推错远端（见坑 2）：commit 有了、生产没动。
- ISR 缓存：详情页 24h 缓存（
revalidate = 86400），改动要等过期或重新部署。
- 构建期读不到 Turso：Workers Builds 的构建环境没有 Turso 凭据，预渲染的 24 个头部页会落到
realPlugins 静态兜底。所以凡是要在头部页显示的字段，都必须进构建期快照——
下载量（downloadsOf）与安装方式（installOf）都已经进了，贡献者数还没有，
那一栏在头部页恒显示 -。要修就照它俩的样子把它也写进快照。
相关
- 下载量的采集口径与档位：
.claude/skills/track-downloads/SKILL.md
- 桌面端市场安装契约：
.claude/skills/desktop-market/SKILL.md
- 评分批次：
.claude/skills/score-plugins/SKILL.md（评分不在本流程里，需要单独跑）
