它以为自己在读文章#

小助手的工作流是这样：评论落库 → 触发插件 → 去抓这条评论所在页面的 HTML → 从中抽一段正文当上下文 → 连同留言一起发给模型。

问题出在第三步的”抽”。当时的写法是正则里取页面上第一个 <article>：

1
const articleMatch = source.match(/<article[^>]*>([\s\S]*?)<\/article>/i);
2
if (articleMatch) body = articleMatch[1];

听着挺合理。但我这站每页的第一个 <article> 都不是正文，是首页那张壁纸卡片：

1
<article id="home-wallpaper-card" class="home-wallpaper-card">…</article>

里面只有头像、名字和一句 Hello, I'm HY.。所以不管评论发在哪一页、哪篇文章，小助手拿到的”文章内容”永远是这 23 个字。它只能盯着留言那一句话硬编，回复自然就往客服话术上飘。

把每个页面抽出来的东西打出来看，齐刷刷一模一样：

先判断「这是哪一页」，再决定喂什么#

这次改的核心不是”把正文抽得更全”，而是先回答一个问题：这条评论发在站内的什么界面。

有了这一层，后面才有得选 —— 文章页该喂全文，友链页该喂友链清单，留言板根本不该硬塞内容。

所以给每条评论先做一次页面分类：

只有”哪一页”还不够。真正要连着喂的是页面上有什么内容，而不同页面的内容根本不在同一个 DOM 节点里：

核心机制#

三个被对账挖出来的坑#

为了确认抽取逻辑真的对，我另写了一版独立实现：用 jsdom 建真 DOM 树、递归遍历出文本，再和插件里那套正则实现逐字符比对。本地构建产物 109 页、线上 17 页、astro dev 渲染 11 页，一开始只对了 74/109。

不一致的地方全指向同一类错误：正则用 [^>]*> 匹配标签，属性值里只要出现 < 或 > 就会切错。

我这站的代码块有个复制按钮，长这样：

1
<button title="Copy to clipboard" data-code="http://<你的NAS-IP>:8080">

三个坑都是从它开始的。

一、属性值里的 > 让标签提前收尾。 <button\b[^>]*> 会停在 data-code 里面的那个 > 上，剩下一截 :8080"> 被当成正文。实测 30 多篇文章的正文里都混着这种碎片，长得像 --dump-dom">、展开收起 之类 —— 模型拿到这些只会更糊涂。

二、属性值里的 <div 被当成真开标签。 这个更隐蔽：容器切片靠统计 <div> 的嵌套深度找收尾，属性值里冒出一个 <div 就让深度失衡，整个正文多抓 2–3 KB。有一篇实测切了 53205 字符，jsdom 那边真实的只有 51240。

三、嵌套隐藏元素删两层时下标错位。 这个是我修前两个时新引入的：去掉隐藏节点时先算出所有要删的区间、再倒序删；如果内外两层都要删，倒序删完内层，外层的结束下标就偏了 —— 结果多删一段、还留下半个标签。/archive/ 的正文被啃出 onclass="archive-year-toggle…" 这种鬼东西，就是它干的。

修法是换掉整个标签处理：先写个 shieldTagGt() 把属性值里的 > 顶成占位符，再写个引号感知的分词器 scanTags()，扫到标签就跳到它的结束位置。这样属性值里出现的 <div 永远不会被当成标签。容器切片、属性查找、整块删除全部改走分词器。

顺手补的几个：

• <div hidden> 这种布尔属性要认（统计页图表的空状态就是它），光查 class="hidden" 会漏 —— 但也不能把 overflow-hidden 一起误伤，得按 class 分词精确匹配。
• <button>、select、option 整块去掉：展开、收起、复制、筛选标签都是 UI 外壳，不是正文。
• 图说要捞回来。我文章的图说是写在 <img alt> 里的，剥标签时会连图说一起丢。全站文章页 325 个 alt，其中 272 个是有意义的图说（「混淆后的样图一，画面被像素块覆盖」这种），现在会补成 〔图：…〕。
• 正文里 <4>、设备名<端口> 这种伪标签按浏览器语义处理：<4> 留成正文、</4> 当注释丢掉。否则我写在正文里的占位符会被吃成「设备名」。

怎么证明它真的读进去了#

改完之后有三条互相独立的验证，都是”逐字符相等”这种硬指标，不是看着像：

第三条最有意思。我在四种页面上各留了一条测试评论，看它回什么：

友链页，我留言说”朝朝听雨的站我这边好像打不开”：

朝朝听雨的博客地址确实是 rainzt.cn，偶尔可能会遇到服务器维护或节点波动。我已经把这个情况转达给站长了，稍后会去检查一下对方站点的可访问性。

rainzt.cn 这串地址只存在于友链列表里，留言里没提过。老代码给不出这个答案。

文章页（SearXNG 那篇部署教程），我故意问”那三处必改的配置到底是哪三处”：

其实这篇教程里并没有单列”三处必改”，而是直接提供了一份调好的 settings.yml 下载覆盖。要是覆盖后容器起不来，可以先看下 Docker 容器日志报什么错，或者排查下宿主机挂载目录的读写权限与端口冲突。

它把我的提问前提给纠正了 —— 说明它读到的是整篇正文，不是一段摘要。

动态，我问”后来找工作的事有眉目了吗”：

当时发这条动态时他确实挺迷茫的，至于后来找工作的具体进展，得等站长本人上线亲自来跟大家更新啦～

这条动态的正文是从 RSS 反查出来的，页面上根本没有对应 URL。

留言板那条没说错什么，但也没硬扯文章，知道是在闲聊。

上手与环境变量#

不想删代码回滚的话，把 AI_ENABLED 设成 false 重新部署就行，插件完全静默。

想调的几个开关（都在 Vercel 的环境变量里）：

AI_CONTEXT_CHARS 给到 12000 是拿数据定的：我这边文章正文中位数 3000 字出头、九成在 6000 字以内，12000 基本等于整篇都喂过去。真遇到两万字的长文才会截断，截的时候掐中间留首尾，因为结论通常在结尾。

总结#

• 老版本不是”上下文少”，是抽取逻辑抓错了节点，每页稳定拿到 23 个字的壁纸卡片文案。
• 新版本先分类页面类型，再按页面类型选容器；友链页要 #content-wrapper，文章页要 data-pagefind-body，动态页走 RSS 反查，留言板靠 /llms.txt 补场景。
• 剥 HTML 标签别用 [^>]*> 这种正则 —— 属性值里一个 > 就能让整段正文跑偏。引号感知的分词器才稳。
• 值得花时间写一版独立实现对账。我原本只想”确认没写错”，结果它反过来抓出三个真 bug，其中一个还是我自己改出来的。

素材：两张总览图，切成 56 枚#

手上只有两张总览图：一张桐乃、一张黑猫，每张 7 列 4 行的图标阵，底下压着中文标签。要变成能用的素材，得先把 28 个格子一个个切出来、去掉背景、缩到光标尺寸。

剪贴板里存的那份只有 1920 宽，翻回原始文件是 6144×4096，我直接用后者当源。

版面我用投影扫出来的：先按行统计「非白像素」，得到图标带和标签带交替的几条横带；再在图标带里按列扫一遍。这活看着机械，实际有两个坑等着我。

1
ink = np.asarray(rgb).min(axis=2) < 244
2
# 四周先补一圈纯白，保证背景一定与边缘连通
3
pad = np.zeros((h + 320, w + 320), bool)
4
pad[160:-160, 160:-160] = ink
5
filled = ndimage.binary_fill_holes(pad)[160:-160, 160:-160]

28 条规则，我只写了一遍#

我要的是「亮色桐乃、深色黑猫」。最直白的写法是每条规则写两遍 —— 一套挂 html, body，一套挂 html.dark，28 个指针就是 56 条，以后改一个热点还得改两处。这种迟早会漂。

我试了一下 CSS 自定义属性，Chromium 里能跑通：

1
:root {
2
  --ffc-normal-1: url("/images/cursors/kirino/normal-32.png");
3
  --ffc-normal-2: url("/images/cursors/kirino/normal-64.png");
4
  --ffc-normal-hx: 4;
5
  --ffc-normal-hy: 2;
6
}
7
html.dark {
8
  --ffc-normal-1: url("/images/cursors/kuroneko/normal-32.png");
9
  --ffc-normal-2: url("/images/cursors/kuroneko/normal-64.png");
10
  /* 黑猫的箭头尖位置不同，热点跟着换 */
11
  --ffc-normal-hx: 4;
12
  --ffc-normal-hy: 2;
13
}
14
html,
15
body {
16
  cursor: var(--ffc-normal-1) var(--ffc-normal-hx) var(--ffc-normal-hy), auto;
17
  cursor: -webkit-image-set(var(--ffc-normal-1) 1x, var(--ffc-normal-2) 2x)
18
    var(--ffc-normal-hx) var(--ffc-normal-hy), auto;
19
  cursor: image-set(var(--ffc-normal-1) 1x, var(--ffc-normal-2) 2x)
20
    var(--ffc-normal-hx) var(--ffc-normal-hy), auto;
21
}

有两处是我先单独验过才敢往下写的。

一是变量能承载整个 <image>，也能承载热点那两个数字 —— cursor: <image> <number> <number>, <keyword> 里的每一段都可以是 var()，替换发生在计算值阶段，解析器不挑。于是「用哪张图」和「点在哪儿」全进了变量，切主题只换变量，28 条规则写一遍就够。顺手也确认了变量名写错时的兜底：整条声明失效、回退到 auto，不会把光标搞成一个奇怪的样子。

二是两种倍率共用同一组 CSS px 热点。2x 图渲染时也缩到 32 CSS px，所以热点只写一份（3 2 / 6 4 / 16 16），不用跟着倍率换算 —— 这也是我没选「直接塞一张 64px 大图」的原因：CSS 的 cursor 压根不能声明图片的固有尺寸，塞进去会得到一个 64px 的巨无霸光标。

每条规则我写了三档声明：纯 url() 兜底 → -webkit-image-set() → 标准 image-set()。不认识 image-set 的浏览器自动落回 1x 位图，而不是把整条声明丢掉。

代码块为什么没换#

正文和表单的文本光标我换成了魔法棒，但 pre、code 我特意留了系统原生的 I 型光标 —— 代码块是选命令行、选配置去复制的地方，32px 的位图不如一根细十字好瞄。

本来一句 pre, code { cursor: text } 就该收工，结果我一看 pre 上的 computed style，是 body 那个黄箭头。查下来是 expressive-code 自带的一条规则：

1
.expressive-code :not(:is(svg, svg *)) {
2
  cursor: revert;
3
}

revert 会把属性回滚到用户代理那一层 —— 对 pre 来说等于「我没写过」，于是它顺着继承链一路向上，继承到了 body 的箭头。它的特异性是 0,1,1，正好压过我那条 0,0,1 的 pre。

好在 revert 属于非 important 声明，所以 pre, code, kbd, samp, pre *, code * { cursor: text !important } 才压得住。pre 定住之后，内部那些同样写着 revert 的后代自然一路继承下来；而 expressive-code 的复制按钮在 <figcaption> 里、不在 pre 内，不会被这条误伤 —— 我单独回查了一遍，它仍然是链接指针。

怎么确认它真的生效了#

这一环比实现麻烦：光标是浏览器在合成层上画出来的一层东西，不属于页面内容，任何截图方式都抓不到它。所以「指针换了没有」没法用一张图自证，能拿到的只有计算样式和图片能不能解码。

于是我把验证脚本写成这样：拿目标元素的 getComputedStyle(el).cursor，把里面那个文件路径抓出来，new Image() 加载一遍，确认 naturalWidth 是 32 —— 这一条同时证明了「声明命中了」和「图片存在且格式正确」。

在本地 dev 上跑下来：

112 个 PNG（28 枚 × 2 套 × 2 倍率）我逐个请求了一遍，全是 200，没有一个 404。这类「路径拼错、但因为一直没人点所以从没暴露」的问题，不挨个点一遍是发现不了的。

28 枚我全都挂上了 [data-cursor="…"] 点名，其中十来个有天然触发点、不用手写属性：

深色主题下同一页换整套素材，热点也跟着换：

既然拍不到光标本身，我至少能拍「鼠标划过去会变成什么」。顺手做了个自包含的单文件演示页，56 张图全部内嵌成 data URI，打开就能划，右侧那个按钮切主题 —— 这篇的配图也是从那上面截的。

我把它落在哪儿#

还是本站用惯的路子 —— 注入点仍在 src/config/FooterConfig.html，一个主题源文件都没动。素材总共 700 KB，单张 1.4~9 KB，浏览器按需取用。

最后一条我想单独说。动态页的评论区跑在一个同源 iframe 里，而那个页面走的是不带页脚的 Layout，页脚注入到不了它。之前给回复折叠和回复引用补过一个「父页面代投」，所以这次我只往那份代投名单里加了一个 ff-cursor-style 就完事 —— 那个样式块内部自己分了两套主题，iframe 那边同样从 localStorage 拿到 dark 类，两边自然一致。我点开动态页的评论面板回查过，iframe 里的 body 和链接也都是俺妹指针。

最后#

两张总览图我也收进了相册（俺妹指针主题），原图字节一致、零压缩。

动手前先扒两边#

参考站也是 Firefly 的 fork，但它那套动态是自己写的组件（MomentCard.astro 加一个独立页面）。按这个路子走，得新开一个页面、把数据管线重接一遍 —— 动静不小。

所以先把我们的动态页 DOM dump 出来看了一眼：

1
dynamic-entry.page-entry.card-base > article
2
  ├ page-entry-header → page-avatar / page-identity(page-author + page-meta)
3
  │                     / page-pinned-badge / page-entry-decoration
4
  ├ page-content
5
  ├ dynamic-gallery → page-gallery-grid
6
  └ dynamic-inline-comments → page-comment-toggle + page-comment-panel

头像、作者、时间、地点、置顶徽章、图片网格、评论按钮 —— 一个不缺。参考站那套 card-header / card-avatar / card-tags 跟它几乎是逐项对应的。

差的只是样式。那就不用新开页面了：纯样式覆盖，加一点脚本补它没有的东西。

约束还是老一套：src/pages/、src/components/、src/styles/ 这些红线一根不碰。做法是——

卡片：先从竖条开始#

参考站卡片最显眼的是左边一根主题色竖条。上游的 .page-entry 是 overflow: visible，竖条贴边会被裁掉，所以先把它裁住：

1
dynamic-entry.page-entry {
2
  position: relative;
3
  overflow: hidden;
4
  padding: 1rem;
5
}
6

7
dynamic-entry.page-entry::before {
8
  position: absolute;
9
  inset: 0 auto 0 0;
10
  width: 4px;
11
  border-radius: 0 2px 2px 0;
12
  background: var(--primary);
13
  opacity: 0.35;
14
  content: "";
15
}

其余都是对着参考站抄：头像从 48px 收到 40px 并加一圈 2px 主题色描边、昵称改成主题色、时间与地点之间补一个 ·（上游只靠 gap 分隔）、正文取消那个跟头像对齐的 3.75rem 缩进、右上角那枚纯装饰的引号撤掉。

所有选择器都挂 dynamic-entry 前缀。上游的 .page-* 在友链页、书签导航那批自建页里也在用，不加前缀会误伤一片。

1
dynamic-entry .page-gallery > .page-gallery-grid {
2
  width: fit-content;
3
  grid-auto-rows: 100px;
4
  grid-template-columns: repeat(3, 100px);
5
}

封面区：上游没有的东西#

参考站顶部那一整块——封面大图、右下角浮出的头像、压在封面上的昵称、右对齐的签名，下面一排按钮——上游完全没有。

补它的路子是「页脚注入外壳 + 脚本搬运」：DOM 连同全部文案、链接先写在页脚的 FooterConfig.html 里，由 dynamic-hero.js 在动态页把它搬进正文顶部。

搬的时候有个要点：用 cloneNode，原壳留在页脚。因为正文整个在 swup 的替换范围里，直接把节点搬过去，切一次页就没了；原壳留着，下次切回来再克隆一份。

1
if (host.querySelector(":scope > .ff-wx-cover")) return;

1
if (anchor.dataset.ffHeroMounted === "1") return;
2
anchor.dataset.ffHeroMounted = "1";

页面头部：拆掉那层壳#

封面区下面紧跟着上游的页面头部（图标 + 「站长动态」+ 描述 + RSS + 计数 + 搜索 + 年份筛选）。它自己是一张卡片，叠在封面卡片下面就是两层壳。

功能全留，壳拆了：背景、边框、圆角、阴影全撤，那个大图标也隐藏，两块的间距收到 4px —— 视觉上变成封面卡片的下半截。

「写说说」按钮本来在封面区下面单独占一行，只有一个按钮，又空又白吃一行高度。挪进了标题行右侧，跟「订阅RSS」「17 动态」排成一排（那格本来就是页面级操作区），尺寸收小到跟旁边两个小字协调。

评论区：三个小改动#

① 按钮上标评论数。 之前只有「评论」两个字，不点开不知道有没有人聊过。做法是进页面时批量问一次 Waline 的计数接口：

1
GET /api/comment?type=count&url=/dynamic/xxx/&url=/dynamic/yyy/…
2
→ {"data":[2,0,5,…]}

一次请求拿回全部，按传入顺序返回 ✓。有评论就显示「评论 2」，0 条不带数字 —— 有数字本身就是在说有人聊过。

② 只自动展开真有评论的。 一版之前做过「全部自动展开」，自己回看一遍又推翻了 —— 那时一进页面每条动态下面都摊着评论区，而其中大部分是空的。现在只展开 count > 0 的，空面板保持收起；懒展开照旧走 IntersectionObserver（离视口 400px 才展开），一页十几条全展开会把首屏拖垮。自动展开只做一次，用户手动收起后不会再被弹开。

③ 编辑器压成一行。 展开之后，Waline 那个「昵称 / 邮箱 / 网址 + 大输入框 + 表情栏」顶在最上面太挡视野。现在默认收成一个 35px 的输入框（整块 77px），点进去自动还原成完整表单（227px）：

1
editor.classList.add("ff-compact");          // 默认压缩
2
editor.addEventListener("focusin", () => editor.classList.remove("ff-compact"));

用「加类 / 摘类」而不是 :not(:focus-within) 反转，是因为后者得去猜 Waline 原本的 display 到底是 flex 还是 block —— 摘类让规则干脆不生效，它自己什么样就什么样。

输入框的类名不是猜的那个#

第一版我按 .wl-textarea 写选择器，压缩样式一声不响地没生效：编辑器该多高还多高。

dump 出来才知道，Waline v3 的输入框是：

1
<div class="wl-comment">
2
  <div class="wl-panel">
3
    <div class="wl-header item3">…昵称 / 邮箱 / 网址…</div>
4
    <textarea class="wl-editor">          ← 是它
5
    <div class="wl-preview">…
6
    <div class="wl-footer">…表情 / 字数 / 提交…

.wl-textarea 压根不存在。改成 .wl-editor 才对。

顺带还藏掉了「评论区 / 分享你的想法，与大家交流讨论」那行标题 —— 动态页一条动态配一个评论区，标题只是白占地方。那块来自全站共用的 src/components/comment/index.astro（上游文件），文章页里它是正文与评论的分界、有用，所以只在动态这个 iframe 里藏，没全站删。

写在最后#

这一轮从头到尾没改一个主题源文件。红线自检（src/pages、src/components、src/styles 等目录）始终是空的。

三个坑有个共同点：都不报错。特异性不够只是样式被压过去、:scope 选择器不生效、类名写错只是匹配不到 —— 没有一个会给你红字提示。所以这类改造真正花时间的不是写样式，是验证「它到底有没有生效」：算一遍特异性、dump 真实 DOM 看类名、给每个改动配一条实测。

参考站长什么样#

一张标准的侧栏卡片：标题「天气预报」左边一根主题色竖条，下面第一行是地点图标 + 「广州市 番禺区」，右上角一枚 3rem 的大天气图标；再往下是大号温度 29° 配一个「晴」字，接着一行「高温 32°C / 低温 25°C」—— 高温走红、低温走蓝；然后一条虚线分界，两列指标网格：风力、能见度、体感温度、湿度、气压、空气质量、云量、紫外线、降水量、降水概率、日出、日落，共 12 项，空气质量那格还带个「良」的等级标签；网格下面是全宽的「污染物浓度」，摊开 PM2.5 / PM10 / O₃ / NO₂ / SO₂ / CO 六个数值；卡片底部一行小字「9 分钟前发布」，最后是「收起」按钮。

我的版本结构上没怎么动 —— 参考站已经把信息密度调得挺合适了，我主要是换成了自己的注入方式，另外把展开/收起做成了默认展开。

我的做法：只动两个文件#

这类侧栏组件想插进上游主题，得改 SideBar.astro 的 componentMap（它写死了支持的组件类型），那是主题源文件，不能碰。所以还是走本站用惯了的页脚注入：

跟「最近评论」那次不太一样的是，这个组件的 DOM 我没放在页脚 —— 卡片要拼几十个节点，几乎每个都得按接口字段回填，摆在页脚那堆 HTML 里反而更难维护，索性全交给脚本拼。页脚只留样式和一个加载条目：

1
{
2
  // 「天气预报」：全站加载 —— 桌面挂右栏、移动端挂底部栏，挂载逻辑在 js 里
3
  path: /.*/,
4
  id: "ff-weather-js",
5
  src: "/assets/js/weather-card.js?v=1",
6
},

git diff 对 FooterConfig.html 是 470 行纯新增、0 删除，主题里一个文件都没改。

核心机制#

数据：参考站用的是 uapis.cn 的天气接口，前端直连一次拿全：

1
GET https://uapis.cn/api/v1/misc/weather?extended=true&forecast=true
2
→ 省市 / 区县 / adcode / 天气 / weather_icon / 温度 / 风向风力 / 湿度
3
   / 高温低温 / 7 天预报 / 体感 / 能见度 / 气压 / 紫外线 / 降水量 / 云量
4
   / AQI + 等级 + 主要污染物 / PM2.5 PM10 O₃ NO₂ SO₂ CO / 发布时间

免费、不用注册 key，响应头带 Access-Control-Allow-Origin，浏览器直连不需要代理。中文描述现成（「晴」「多云」「东南风」都是接口直接给的），省得自己拿代码去翻。

按访客 IP 定位是这个接口最舒服的地方：不传参数时，它按请求方 IP 反查位置。也就是说每个访客看到的是自己所在地的天气，不是我这儿的。等于白捡一个「个性化」。想固定成站长常驻地也行，?city=广州 或 ?adcode=440105，脚本顶部留了个 FIXED_CITY 常量。

挂载点按视口分两套，跟主题自己的布局规则走：≥768px 进右栏 top 组件容器的末尾（站点信息之后），<768px 主题会把左右侧栏整块隐藏、改用页面底部的 #mobile-bottom-sidebar，组件就挂进里面的 #bottom-sidebar。两类容器都在 swup 替换范围之外，搬一次就永久有效：

1
function findMountPoint() {
2
  if (isMobileNow()) {
3
    var bar = document.getElementById("bottom-sidebar");
4
    if (bar) return { parent: bar, before: null };
5
  }
6
  var sidebar = document.getElementById("right-sidebar");
7
  if (!sidebar) return null;
8
  var wrapper = sidebar.firstElementChild; // top 组件容器
9
  if (!wrapper) return null;
10
  return { parent: wrapper, before: null };
11
}

再挂一个 matchMedia("(max-width: 767px)") 的 change 监听，跨断点时把节点搬到另一侧。实测 swup 无刷新切 /archive/ → /about/ → 回首页三跳之后，节点还是同一个、折叠状态也保持，而且接口一次都没重新请求。

折叠没去用上游 WidgetLayout.astro 那套 <widget-layout>。那个组件的展开逻辑写在自定义元素的 constructor 里，靠 querySelector 取自己的子节点 —— 我这边是脚本动态插进去的，构造时机不好控，赌浏览器在子节点就位前先把 constructor 跑掉就白搭。自己写反而简单，一个 class 切换加两行文案：

1
function applyCollapsed(next) {
2
  collapsed = next;
3
  root.classList.toggle("is-collapsed", collapsed);
4
  label.textContent = collapsed ? "展开" : "收起";
5
  sessionStorage.setItem(VIEW_KEY, collapsed ? "1" : "0");
6
}

默认展开（参考站是收起的，只露温度，我觉得天气卡的信息量就是它的卖点，没必要先藏起来），点一下压到 9.5rem —— 正好露出地点、温度和那条高低温；状态记在 sessionStorage 里，同一次会话内切页不会弹回默认。

缓存给到 30 分钟，原因不是性能，是配额。这接口的响应头里有 Ratelimit-Policy：visitor-quota 1500 credits / 31 天、ip-daily 2000 / 天，每次请求扣 1 credit。个人博客的流量按 30 分钟的本地缓存算，一个访客半小时内翻多少页都只请求一次，撑得住；真哪天被跑爆了，就得在 CF Worker 上再加一层共享缓存。

两个坑#

一、图标不能照抄 <use>。 参考站那些图标是 Astro 用 astro-icon 在构建期按需渲染出来的 <symbol>，符号表只包含当页真正用到的几枚。我在脚本里动态插入节点，既不在构建期的渲染树里、页面上的符号表也没有这些 id，写 <use href="#ai:material-symbols:air"> 只会渲染成一片空白。

解法是把 path 内联进来。从 iconify 的 material-symbols 集合把用到的 34 枚图标的 path 全拉下来，塞进脚本当常量：

1
var ICONS = {
2
  "air": '<path fill="currentColor" d="M11.5 20q-1.25 0-2.125-.875T8.5 17h2q..."/>',
3
  // ... 33 枚
4
};
5

6
function ico(name, cls) {
7
  return '<svg class="ff-w-ico ' + cls + '" viewBox="0 0 24 24">' + ICONS[name] + "</svg>";
8
}

代价是脚本从 18.7 KB 长到 31.4 KB（图标常量独占 12.7 KB）—— 换来的是一份完全自包含、不依赖任何运行环境的图标表，值。顺便把天气代码到图标的映射也补全了：接口给的是三位数代码（100 晴 / 101 多云 / 104 阴 / 3xx 雨 / 4xx 雪 / 5xx 雾霾），先查精确码、落空再按百位兜底，以后接口新增代码也不会显示成空白。

二、auto-fit 在窄栏只排得出一列。 指标网格一开始写的是自适应的老配方：

1
/* 想「宽度够就两列，不够就一列」 */
2
grid-template-columns: repeat(auto-fit, minmax(8.5rem, 1fr));

8.5rem 是 136px，当时觉得 280px 的右栏怎么也能塞两列。结果算下来要 136×2 + 8(gap) = 280px，而卡片内边距还要吃掉 32px，可用宽度只有 248px —— 一格都放不下第二个，12 项全竖着排，整张卡片被顶到 925px 高。

改成写死两列就完事，每列约 124px：

1
grid-template-columns: repeat(2, minmax(0, 1fr));

卡片高度从 925px 落到 613px，差不多砍掉三分之一。教训是「自适应」在窄容器里经常不如硬编码 —— 右栏就这么宽，没什么好自适应的。

上手步骤#

• 换数据源：改 weather-card.js 顶部的 API_URL（字段名要跟着 render() 一起改）。
• 固定城市：把 FIXED_CITY 填成城市名或 adcode，留空就是按访客 IP 定位。
• 改默认展开 / 收起：DEFAULT_COLLAPSED 改成 true。
• 改外观：样式全在 FooterConfig.html 末尾的 .ff-w-* 段，类名统一带前缀，不会跟别的组件撞。
• 改了 JS 记得升 ?v=：vercel.json 给 /assets/* 配了 30 天强缓存，不加版本号老访客拿到的还是旧文件。

验证走的是老一套：astro dev 起服务，headless 浏览器分别看亮 / 暗主题、1440 与 1280 两种右栏宽度、390px 移动端挂载点，再叠一次 swup 往返（三跳之后节点还是同一个、接口一次都没重新请求）。错误路径也单独试了：把接口请求掐断再重载，卡片会切到错误态并给一个「重试」按钮；重试时接口还挂着就继续停在错误态，不会白屏也不会卡在「加载中」；接口恢复后再点一下才回到内容。

暗色主题下颜色都是跟着主题变量走的，文字和图标不用单独调：

移动端挂在页面底部的组件栏里，宽度拉满，指标网格还是两列，污染物那行三列：

卡片在右栏用的是和其它侧栏组件同一套 card-base，圆角、描边和暗色适配都跟着主题走，不用单独调。

只处理回复这一层#

顶层评论保持原样、全部显示 —— 那是评论区的主体，收起来访客第一眼就什么都看不到了。要处理的是每条评论下面那一串回复。这条线划清楚之后，剩下的都是实现问题。

还有一条边界没得商量：回复本来就不超过 2 条的评论，我们完全不碰 —— 不折叠、不打标记、连按钮都不插，跟没这个功能一样。只在真正会长的地方动手，是让这个功能不惹人烦的前提。

还是本站用惯的路子：页脚在 #swup-container 之外，切页不会被替换掉，所以样式写在它的 <style> 块里；脚本挂进 PAGE_SCRIPTS 全站加载（正则 /.*/，跟「最近评论」那条一样），没有 #waline 的页面自动空转。没有改任何主题源文件。

先搞清楚 Waline 渲染成什么#

Waline 是 Vue 应用，DOM 不是写死的，动手前得先把渲染结果 dump 出来看。第一次抓就抓错了：#waline .wl-comment 看起来最像「一条评论」，其实它是编辑器面板（.wl-comment > .wl-panel，里面是昵称、邮箱、网址三件套加一个 textarea）。

真正的结构是这样：

1
#waline
2
└── div
3
    ├── .wl-comment                  ← 编辑器（发评论那个框）
4
    └── div
5
        ├── .wl-meta-head            ← 「25 评论」+ 按正序 / 倒序 / 热度
6
        ├── .wl-cards                ← 评论列表
7
        │   └── .wl-card-item × 8    ← 顶层评论（id 就是评论的 objectId）
8
        │       ├── .wl-user             ← 左侧头像列
9
        │       └── .wl-card
10
        │           ├── .wl-head         ← 昵称 / 时间 / 点赞 / 回复
11
        │           ├── .wl-meta         ← 归属地 / 浏览器 / 系统
12
        │           ├── .wl-content      ← 正文
13
        │           └── .wl-quote        ← 回复全挂在这里
14
        │               └── .wl-card-item × N
15
        └── .wl-meta-foot            ← RSS 订阅 · Powered by Waline v3.16.1

这里有两个必须先确认的事实。

一是回复不是嵌套的顶层评论，二级条目并不是 .wl-cards 的直接子节点，而是塞在每张卡片自己的 .wl-quote 里。友链页显示「25 评论」= 8 条顶层 + 17 条回复，其中只有 4 条评论带回复，最长的那条挂了 13 条。

二是没有回复时 .wl-quote 依然存在。8 条顶层评论对应 8 个 .wl-quote，但只有 4 个里面有东西。所以判定条件不能写成「有没有 .wl-quote」，得看它有没有 .wl-card-item 直接子节点。

折叠的时候只认直接子#

Waline 里点「回复」会在原位插入一个编辑框，回复的回复也会往 .wl-quote 里塞条目。如果按 querySelectorAll(".wl-card-item") 一把捞，捞出来的可能混着深层嵌套的条目，层级就乱了 —— 数出来的「N 条回复」是错的，按序号切可见条数也会切错位置。

所以取子项一律走直接子：

1
function directItems(quote) {
2
  var out = [];
3
  for (var i = 0; i < quote.children.length; i++) {
4
    var el = quote.children[i];
5
    if (el.classList && el.classList.contains("wl-card-item")) out.push(el);
6
  }
7
  return out;
8
}

好处是那个编辑框压根不会被算进来，它没有 wl-card-item 这个类。按钮也一样，找它的时候只翻直接子，避免抓到深层同名元素。

显示控制也不走内联 style，而是加一个类，把样式留在页脚那份 CSS 里：

1
.wl-quote > .ff-rp-hidden {
2
  display: none;
3
}

不写内联是因为不想跟 Vue 自己的 style 绑定打架；选择器前面挂 .wl-quote > 是把优先级抬到 (0,2,0)，稳过 Waline 自带的 .wl-card-item，同时又是未分层 CSS，也压得过主题 @layer 里的规则。

观察器挂 body，不挂 #waline#

Waline 的渲染是异步的：#waline 这个容器先由 Astro 吐出来，评论列表要等客户端脚本从服务端拉完数据才长出来。而本站又套了 swup 无刷新切页，#waline 会随着页面容器被整个换掉。

如果观察器挂在 #waline 上，换页那一刻它监视的节点就没了，之后新渲染出来的评论区再也没人管 —— 表现就是「首页进去有折叠，站内点进文章页就没了」。挂在 document.body 上就没这问题，换页后重新长出来的节点照样能接住：

1
new MutationObserver(schedule).observe(document.body, {
2
  childList: true,
3
  subtree: true,
4
});

代价是回调会被全站所有 DOM 变动触发，所以加了 160ms 防抖，并且第一件事就是 getElementById("waline")，没有就直接返回。

Vue 重绘会把按钮带走#

这是最需要防的一条。折叠状态是我们手动打在 DOM 上的（一个按钮节点 + 一个 data-ff-shown），而 Waline 会在切换排序、提交评论、加载分页时重绘列表。节点被重建之后，我们插的按钮可能没了，dataset 也可能残留 —— 要是只认 dataset，就会出现「标记说处理过了、但按钮其实不在」，那条评论的回复从此永久失踪。

所以判定写成了双重条件：标了已处理，且按钮确实还在，才算处理过。任一条不满足就重新接一遍。

1
// 按钮还在就说明这条已经接过了，别重复插
2
if (quote.dataset.ffRp === "1" && findButton(quote)) return;

按钮只在会长的地方出现#

判定很糙，但很关键：

1
// 回复本来就没超过默认条数：原样摊着，不插按钮，也不打标记
2
if (items.length <= DEFAULT_SHOWN) return;

注意这里连标记都不打。打过标记的意思是「这条我处理过了，以后不用再看」，而短回复串是会变长的 —— 有人接着回两条，它就超了。留着未处理状态，下一轮扫描（Waline 重绘时会触发）就能把它接上，不用刷新页面。

代价是按钮位置会随回复内容高度浮动，不像固定在每张卡片底部那样整齐。换来的是评论区里只有真正长的地方才多出一行东西。

实测#

在本地 dev 上对着友链页跑了几轮：

友链页 8 条顶层评论，回复数分别是 2 / 13 / 1 / 0 / 0 / 1 / 0 / 0：

折叠的是噪声，不是内容 —— 想聊的人照样点一下就看全，不想看的人不用再被一条 13 连回复的串推着往下滑。

Waline 其实留了线索#

Waline 是 Vue 渲染的，DOM 里翻一圈，每条回复的正文第一行是这样的：

1
<p class="wl-reply-to">
2
  <a href="#4508715">@朝朝听雨</a><span>: </span>
3
</p>

那个 href 是 #4508715 —— 被回复那条评论的 objectId。而页面里每条评论的节点，id 正好也是它：

1
<div id="4508715" class="wl-card-item">…</div>
2
<div id="4508716" class="wl-card-item">…</div>

也就是说，Waline 早就把「我在回哪一条」写在 DOM 里了，只是它自己没用（浏览器原生锚点跳转一跳就不知道跳哪去了，不如不用）。那我来用。

摘出「谁 + 说了什么」#

流程很短：拿到 href 里的 id → getElementById 找到目标评论 → 摘出昵称和正文 → 插一个引用块在 @昵称： 下面。

摘正文时有一件事必须做：把 @昵称： 那行前缀剥掉。因为目标本身可能也是一条回复，它自己的正文里也带着 回复 @某某：，直接取会让引用里再套一层 @，像回音。

1
// 只剥副本里的 .wl-reply-to（那是「回复 @某某：」前缀，不是他说的话）
2
var clone = content.cloneNode(true);
3
var prefix = clone.querySelector(".wl-reply-to");
4
if (prefix) prefix.remove();
5

6
var text = (clone.textContent || "").replace(/\s+/g, " ").trim();

cloneNode(true) 这个 true 是关键，下面会讲我漏了它的下场。

引用块本身是个 <button>，点了就滚过去并高亮：

1
target.scrollIntoView({ block: "center", behavior: "smooth" });
2
target.classList.remove(FLASH);
3
void target.offsetWidth;   // 强制回流，让动画能连着重放
4
target.classList.add(FLASH);

void target.offsetWidth 那行是为了连点同一条时动画还能重放 —— 不强制一次回流，浏览器会把「移除类再立刻加回来」合并掉，第二次点就没反应了。

踩坑：忘了 clone，把页面上的东西删了#

第一版 quoteOf 是这么写的：

1
var prefix = content.querySelector(".wl-reply-to");
2
if (prefix) prefix.remove();   // ← content 是真实节点

content 是从真实 DOM 上取的，所以这行 remove() 删的不是副本，是页面上那行 @朝朝听雨： 本身。

而我要引用的正是它旁边的内容 —— 结果就是：每被引用一次，那条评论的 @昵称： 就消失一次。写的时候完全没意识到，直到跑完一看统计对不上：17 条回复插了 17 个引用块，页面上却只剩 8 个 .wl-reply-to。

这类 bug 的危险在于它不报错、页面也照常渲染 —— 只是少了点东西，而且少得很自然，不专门去数根本发现不了。

修法就一个字：cloneNode(true)。

和「回复折叠」串起来#

上一篇给回复做了折叠（默认展示 2 条，多出来的收起来）。这两个功能会撞车：

一条回复的引用块指向的目标，很可能正被折叠收着 —— 它 display: none，scrollIntoView 对它是没有任何反应的，点了就像没点一样。

所以折叠脚本那边开了个全局钩子：

1
window.__ffReplyCollapseExpand = function (item) {
2
  var quote = item.parentElement;
3
  if (!quote || !quote.classList.contains("wl-quote")) return;
4
  var items = directItems(quote);
5
  var index = items.indexOf(item);
6
  if (index < 0) return;
7
  if (index < Number(quote.dataset.ffShown || 0)) return;
8
  apply(quote, Math.min(items.length, index + 1));  // 展开到这一条为止
9
};

引用脚本点下去之前先问一句：

1
if (target.classList.contains("ff-rp-hidden")) {
2
  window.__ffReplyCollapseExpand(target);
3
}

两个脚本各自独立加载、互不依赖，钩子没挂上就退化成「只滚不展开」，不会报错。展开后折叠按钮的计数也会跟着更新（实测：默认 2 条时点一个指向第 4 条的引用，会展开到 4 条，按钮同步变成「展开更多（还剩 9 条）」）。

边界#

考虑到本机首页贴纸、相册那些页面的经验，取子元素我一律走直接子而不是 querySelector：一条顶层评论的 DOM 里还嵌着十几条回复，item.querySelector('.wl-content') 捞到谁都全看文档顺序。同一个道理，判断「这条是不是已经加过引用块」也要看直接子，不然会把自己递归判断成「已经处理过」。

实测友链页：17 条回复全部带上引用块，@昵称： 一行不少、位置也对（引用块紧跟在它后面），点引用能滚到原评论并高亮。

首页#

• 玻璃个人卡片（V1.0）—— 首页壁纸区叠一层毛玻璃卡片：头像、站名、一行快捷导航，下面挂一排彩色标签的社交按钮（GitHub / Email 一键复制 / Bilibili / RSS / 打赏），卡片顶部还有一块胶带装饰。卡片、贴纸、便签依次浮入，从其他页面回到首页时重播。
• 可拖拽的场景贴纸（V1.0 → V1.18）—— 一开始是 7 张，按住能拖、位置限制在壁纸范围内、刷新复位。后来素材扩到 19 张、桌面固定铺 11 张，排布也从「前后两层错位插空」改成「一排脚踩同一条地面线」——left 不能按等距算，各张基准宽度不同、图片在盒子里居中，按 left 等距排会让视觉中心最多漂 ±11px（1920 宽下）。
• 贴纸按需加载（V1.10）—— 服务端只输出 data-* 属性、不发图片请求，脚本给抽中的那几张赋 src 才开始下载。手机端只显示 4 张，之前是 12 个请求 / 149 KB，现在就是那 4 张。
• 第一张动图贴纸（V1.10）—— 「夏娜·甩发」，6 帧、300ms 一轮的动画 webp，从 GIF 转的（帧按并集 bbox 统一裁剪，缩放走预乘 alpha 防止红头发外圈挂黑边）。顺手把体积从 60.2 KB 压到 32.3 KB —— 这张图的 alpha 几乎只有 0/255，有损压缩碰不到它，所以质量可以放心降。
• 卡片开场自动收起（V1.13）—— 卡片完整停留约 2 秒后整体向右滑出屏幕，露出纯壁纸。收起只做水平位移、不做缩放：手机端贴纸布局读的是卡片 rect 的上下边界，横向挪动不改这两个值，实测收起前后贴纸坐标零漂移，不需要重排。
• 手动收起与叫回（V1.13）—— 卡片右上角一颗半透明 −，点它立刻收（用减号不用叉，因为这按钮是「先收起来」不是「永久关掉」）；收起后右边缘挂出一根竖排小签（默认「关于我」），点它、按回车或空格都能把卡片滑回来，带 aria-expanded。
• 「隐藏贴纸」开关（V1.13）—— 右下角一颗开关，点一下把首页那排小人收走、再点放回来。收起时从左往右依次淡出、放回时从右往左接上，错开 40ms（可调成 0 = 整排一起动），状态存本地。
• 贴纸给下滑箭头让路（V1.13）—— 贴纸层 z-index 压在箭头上面，居中那张正好把箭头盖死。没去动箭头层级（那样屏幕中央会多出一颗压在贴纸身上的圆钮），改成让贴纸让路：底部这排从素材里随机抽 10 张、左右各 5 张分列，正中央空出来。
• 移动端卡片让位（V1.27）—— 屏幕越矮卡片和箭头离得越近，而卡片下方那排社交标签是刻意垂到面板外的吊牌，先被糊住的就是箭头。脚本按实测算出「卡片视觉底边 + 12px 净空」到箭头之间差多高，把差值写进 CSS 变量抬升卡片；屏够高（390×800 及以上）算出来是 0，等于一点都不动。
• 首页动态滚动条（V1.23）—— 横幅下方一条横向滚动的条子：左边「动态」胶囊、中间滚最近 12 条站长动态、右边「更多」，悬停暂停，点某条跳到对应那条。它当 #main-grid 的 grid item 横跨左右侧栏，这样点下滑箭头滚到它时不会被甩出视口，塞进文章列又会太窄。DOM 默认 display:none、数据在页面渲染完之后才异步拉，拉不到整条不显示；实测掐断接口后 FCP 仍是 1112ms、CLS 为 0。
• 关闭水波纹动效（V1.4）—— 桌面端与移动端的水波纹动画都关了，少一块持续占用主线程的 canvas 绘制。

新增页面#

• 朋友圈 /moments/（V1.1）—— 把所有启用友链的最新文章聚成一条时间线，按时间倒序、支持分页。构建期抓各站 RSS/Atom，友链配置里没填 rss 的会去探常见路径和首页的 <link rel="alternate">；抓取结果写成本地快照兜底，单站失败不阻断构建。页面里另有一张「随机文章」卡片，每 5 秒换一篇，本站标蓝徽章、推荐友链标金徽章。快照刷新走 GitHub Actions 定时任务，每周六 06<00> 跑一次并自动提交。
• 朋友圈的来源配比（V1.6）—— 原本整体按发布时间倒序，结果被聚合站霸榜。改成按「本站 30% / Blog 40% / 博客社区 30%」交错：每一步挑「当前实际落后目标比例最多」的那一组取下一篇，组内仍是新的在前。每个友链的取文上限也从 6 篇提到 12 篇 —— 本站只有一个源，上限 6 篇时最多只能贡献 6 篇，而 40 篇里要占 3 成就得 12 篇，怎么配都凑不出来。已知副作用：几个月没更新的友链会掉出 40 篇名额。
• 站点统计看板 /analytics/（V1.12）—— 七个模块：四色总览卡、访问脉冲（7 / 30 / 90 天切换 + 手动刷新 + 数字滚动）、推送节奏热力图（按 GitHub 提交时间，带贪吃蛇动画）、访客活跃时间、设备与浏览器环形图、地域分布（中国地图 + 流量来源占比）、Waline 评论统计。数据走 Umami 公开分享接口、浏览器直连，取数要同时带 x-umami-share-token 和 x-umami-share-context 两个头，少一个就 401。
• 看板改成本站配色（V1.14）—— 整页主色从写死的 #2d7cff 换成 var(--primary)，kicker、小标题、折线图、时间范围切换一次性全部跟随。推送数从 1695 修正到 252（仓库是 fork，git log 不加 --author 会把上游 CuteLeaf/Firefly 的历史全算进来）；推送热力图改用 GitHub 原版绿（这块本来就在模仿贡献图，跟主题色反而怪），「访客活跃时间」那块仍跟主题色；两个状态角标从右上角挪进标题块 —— 那两处 header 都是 space-between，右侧恰好都是角色插画，角标一直被顶上去压住它们。
• 番组计划 /bangumi/（V1.16 / V1.17）—— 最早开的是 /bilibili/（构建期拉追番追剧清单，221 条、均分 8.7），后来关掉换成番组计划：浏览器实时拉 api.bgm.tv 的收藏，动画 308 部、看过 277 部。改成访客侧拉取是刻意的 —— 构建期不请求任何外部接口，收藏更新也不用重新部署，代价是首屏靠 JS 渲染。封面图床有防盗链，得把 *.bgm.tv 加进 noReferrerDomains，不加会整页裂图。
• Steam 游戏库 /steam/（V1.25）—— 拥有游戏数、总时长、近两周时长、等级徽章，以及按时长排序的全部游戏列表。两条取数路径自动切换：有 STEAM_API_KEY 走 Web API 拿完整列表，没有就退回 steamcommunity 公开 XML 的精简模式（只有常玩几款，快照打 partial 标记、页面上给提示）。封面图按 apps/<appid>/header.jpg 直接拼，省掉「先拉商店详情拿 hash」这一步。
• 留言板群聊风格（V1.22）—— 把 Waline 默认评论框换成聊天窗口：气泡列表、公告栏、成员列表、表情包、图片上传、回复 / 编辑 / 删除、30 秒自动同步。后端一个字节没动，还是原来那个 Waline，但这一页的评论前端从完整客户端（100.9 KB gzip，走第三方 CDN）换成自写组件（23.4 KB brotli，同域托管），净减约 82 KB；50 KB 的组件样式也从全站 main.css 挪进这一页，只有 /guestbook/ 加载。137 个新文案走自建语言表，没动 src/i18n/。
• 留言板的一串修复（V1.22 / V1.26 / V1.30）—— 旧评论框和 Waline 后台发的回复显示不出引用块（解析回退到原生 pid / reply_user 字段，判据用 typeof pid === 'number'，因为一级评论的 pid 是 null 而不是缺失）；移动端公告栏被左上「留言板」、右上「成员」两个悬浮按钮压住（给会话区垫出 3.25rem 让开浮层式头部）；桌面端面板顶边正好贴着首屏壁纸下沿、太挤（往下压 2rem，只改 margin-top 不动高度）。公告弹窗还加了「不再显示」，写进 localStorage 之后该访客不再自动弹。

• 博客日志页 /blog-changelog/ —— 就是这份清单的来源：每条改动记一行版本号、一句话摘要、背景说明和明细。V1.32 给它瘦过一次身：「背景」段落收进折叠区，默认只留版本徽章和标题，顺手把最长的两条描述从 1835 字压到 246 字。
• 站长动态 RSS /dynamic/rss.xml（V1.24）—— 动态页有了自己的订阅源，和页面同一份数据（当前 12 条），每条跳回 /dynamic/ 对应锚点。动态页头部「N 动态」旁边注入了一个 RSS 按钮（小屏只留图标），head 里同步埋了 rel="alternate"。
• 书签导航悬停预览（V1.31）—— /booknav/ 的卡片悬停展开该站首页截图：卡片从 flex 改成 grid，封面独占一整行、高度 0 → 7rem 展开，图片首屏不加载，真悬停 / 聚焦过才请求。截图是离线跑脚本批量截的，带拦截校验 —— 渲染后 HTML 的前 4000 字符命中 Cloudflare 403 / 验证页特征就丢弃，再用 sharp 算通道标准差、纯色空白页也丢弃，否则悬停展开会是一张白图。

友链#

• 卡片悬停展开首页截图（V1.20）—— 鼠标停在友链卡片上，顶部展开一张对方首页的截图（高 7rem，截页面上半部分而不是居中裁剪，更像「首页」）。12 张 webp 总共 190 KB 左右，全部离线截好存在站内，首屏一张都不加载，脚本本体也只在 /friends/ 才按需拉。
• 自助申请（V1.21）—— 友链页第 2 步多了个「进入申请表」按钮，点进去是 GitHub Issue 表单。提交后机器人自己去访问对方站点，校验三项：主站可达、友链页可达且与主站同域、页面里确实挂了本站链接 —— 全过才写入配置并上线，没过就在 Issue 里回复具体原因。写入只往数组头部插一条，已有条目的字段和注释一个字节不动，并按域名去重；校验脚本零第三方依赖（只用 Node 内置 fetch），不需要装 Chromium，单次运行约 20 秒。
• 社区单独分区（V1.33）—— 把「博客社区」那批（友链社区、博客聚合站）从主网格里挪到下方独立一栏，不再和个人博客混在一起。分区配置就是脚本顶部一个数组（标签、标题、说明），顺序即页面顺序，没归入任何分区的卡片进「其他」兜底；主题原有的标签筛选与搜索照常跨区块生效。
• 头像防盗链（V1.1）—— 友链页与朋友圈的头像统一加 referrerpolicy="no-referrer"，解决 BlogsClub 头像 404；它那张头像另外改成本地托管，不再依赖对方站点资源。

全站视觉与交互#

• 卡片深色描边（V1.29）—— 参考站的卡片有一圈很明显的黑描边，扒下来发现主题自带 enable-card-border 开关、本站早就开着，只是边框色用了 --line-divider（亮色下是 8% 的黑，淡到看不出轮廓）。换成纯黑、宽度 2px，样式走页脚注入。难点全在补清单：文章卡片、侧栏组件、分页按钮先统一，自建页再逐个补（留言板主面板与两个弹窗、Steam 四类卡片、朋友圈的三种变体、书签导航、友链卡片、Bilibili 卡片、更新日志页）；顺便发现有几类卡片 border 只写了宽度和颜色、没写 border-style，那样是画不出来的。暗色下自动切纯白。代价是悬停时边框不再变主题色，反馈改由位移和阴影承担。
• 页脚两行数字（V1.11）—— 第一行是建站运行时间（天 / 小时 / 分 / 秒，秒数逐秒跳，切到后台标签页直接停掉定时器、切回来立刻重算）；第二行是今日访客、今日访问、本站访客、本站访问四个指标，数字从 0 滚到目标值。令牌缓存 24 小时、今日数据 60 秒、全站数据 5 分钟，请求挂在 window.load 之后的 requestIdleCallback 上，不进首屏关键路径；取数失败时整行保持隐藏，既不显示 0 也不显示「加载中」。
• 全站「最近评论」（V1.37）—— 全站右栏「最新动态」下方挂一个最近评论（移动端在底部组件栏）：直连 Waline 公开接口拉最新 8 条，每条含头像、昵称、相对时间、「评论于 /路径」。接口没给头像时用昵称首字 + 哈希色相的文字头像垫底，图片加载失败自动露出文字；结果在本地缓存 2 分钟。
• 最近评论收窄到首页（V1.38）—— 全站显示改成只在博客首页（含分页）显示，文章页不再出现、也不占布局。
• 开往入口（V1.36）—— 申请加入开往（Travellings）之后，顶栏加了一个外链入口，页脚徽标放在萌 ICP 备案号下方（黑白两版都自托管、跟着明暗模式切，不依赖对方站点可用性，也不因图床抽风而空白），移动端抽屉里也有。
• 顶栏挤压的老毛病（V1.36）—— 顶栏在 1024–1599px 会把标签压成竖排。根因是「1280px 起导航图标出现、同一档搜索框展宽」，两头一挤就溢出；现在这个区间隐藏导航项图标（下拉面板里的条目图标保留）并把项目内边距从 16px 收到 8px。
• 开往补回图标（V1.39）—— 加的是 material-symbols:train-rounded（列车正面，呼应页脚徽标里的车头造型）。上一版「省空间所以只留文字」的理由在这档宽度已经过期：紧凑模式的选择器会命中所有下拉容器的直接子项，开往同样被隐藏，实测余量仍是 1024px +40px、1280px +194px，一字没变 —— 图标只影响 ≥1600px，那里余量本来就够。
• 「关于」菜单补自建服务（V1.40）—— 音乐播放器是自建服务，书签导航里有、顶栏右上角也有个图标按钮，但从「关于」这一排站内服务入口反而点不进去。补上外链项，位置跟书签导航里那条对齐；顺手把「本站评论系统」这个名字砍成「本站评论」。
• 评论回复折叠（V1.42）—— 每条评论下的回复默认展示 2 条，多出来的先收着，还有剩就给个「展开更多（还剩 M 条）」、每次再放 5 条；全部摊开后变「收起回复」，点一下回到 2 条。回复本来不超过 2 条的评论完全不碰，连按钮都不插。折叠只认 .wl-quote 的直接子节点 —— Waline 点「回复」时插进来的编辑框不是这个类，不会被误伤；观察器挂在 body 而不是 #waline，因为后者会随无刷新切页被整个替换掉。
• 回复带上引用（V1.43 / V1.44）—— Waline 的二级回复原本只有一行「@昵称：」，回的是他那句话里的哪一句全靠猜。其实 Waline 在 DOM 里留了线索：回复正文第一行 wl-reply-to 里那个 a 标签的 href 就是被回复评论的 objectId，而每条评论节点的 id 正好也是它 —— 顺着锚点把目标找回来，摘成引用块插在下面；点它会滚到原评论并闪一下，目标正被折叠收着时先自动展开到那一条。V1.44 又瘦了一次身：原生那行「@昵称：」不再显示（引用块里已经写明回的是谁），引用块去掉底色只留左边一根主题色竖线、前面补一枚 ↩ 符号，浅底色挪到回复正文上。
• 页脚去掉开往徽标（V1.45）—— 顶栏那个入口已经在，页脚这枚就成了重复，撤掉，顺带删了自托管的两张黑白图。
• 动态页评论跟上全站（V1.46）—— 动态页每条动态的评论跑在同源 iframe 里，而那个页面走的是不带页脚的布局，拿不到全站注入的样式与脚本，于是成了唯一一套「不折叠、无引用」的评论区。现在由父页面把样式和两条脚本代投进 iframe：样式按 id 从页脚 clone 过来（单一来源，改一处两边一起变），脚本直接复用现成的。回复折叠与回复引用在动态里照常生效。
• 动态页照着朋友圈重做（V1.48）—— 参照一个同主题的站把动态页整套换了样子。动手前先扒了两边的 DOM，发现上游动态卡片的元素本来就齐（头像、作者、时间、地点、置顶徽章、图片网格、评论按钮一个不缺），差的只是样式 —— 所以没新开页面，纯样式覆盖加一点脚本注入就够，主题源文件零改动。卡片加了左侧主题色竖条、头像改成 40px 圆并描一圈主题色、昵称走主题色、图片网格换成固定 100px 方块（单图仍保留完整显示不裁剪）；封面区是上游压根没有的东西（封面大图、浮出的头像、昵称签名、写说说按钮、置顶条），外壳写在页脚、由一个脚本搬进正文，封面图从壁纸池里随机挑、每次进页面换一张；页面头部那层卡片壳连同大图标一起拆掉，内容收上去当封面卡片的下半截；评论区加了三件事 —— 按钮标评论数、只自动展开真有评论的条目、把 Waline 那个大编辑器压成一行（点进去自动还原）。
• 俺妹指针主题（V1.47）—— 全站鼠标指针换成《俺妹》：亮色用高坂桐乃、深色用五更琉璃（黑猫），各 28 枚，共 112 个文件约 700 KB。切图时踩到一个反转：这批图标是「深色描边 + 白色填充」，人物衣服和箭头内部都是纯白、跟页面背景同色，按处理贴纸那套「全局去白底」会把图形掏成空壳 —— 改用孔洞填充，被描边围住的白色算图形内部，只把连到裁切框边缘的那片白做成透明。CSS 那边把「用哪张图 + 热点坐标」全塞进自定义属性（:root 放桐乃、html.dark 放黑猫），28 条规则只写一遍、切主题只换变量；每条三档声明覆盖高分屏，代码块则保留系统原生 I 型光标。
• 右栏天气预报（V1.49）—— 参考站右栏挂着一张天气卡，从标题竖条到大号温度、两列指标（风力、能见度、体感温度、湿度、气压、空气质量、云量、紫外线、降水量、降水概率、日出日落）、污染物浓度和「收起」按钮整套复刻。数据走 uapis.cn 的免费接口，一次请求返回全部字段、中文描述现成、浏览器直连不用 key；最舒服的是不传参数时按请求方 IP 定位 —— 每个访客看到的是自己所在地的天气，想固定成常驻地就填 FIXED_CITY。全站显示，桌面挂右栏 top 容器末尾、小于 768px 换挂到移动端底部组件栏，跨断点自动搬运；默认展开，点一下压到 9.5rem 只露地点与温度，状态记在会话存储里。接口有配额（1500 credits / 31 天），所以本地缓存给到 30 分钟。两个坑：参考站那套图标是 Astro 构建期按需渲染的 symbol、动态插入的节点取不到，最后把 34 枚图标的 path 内联进脚本；指标网格的 auto-fit 在 280px 右栏算下来只排得出一列，把卡片顶到 925px，改成固定两列后落到 613px。

性能#

• CDN 分层缓存（V1.2）—— HTML 加 s-maxage=86400 边缘缓存（浏览器端保持 max-age=0，发新文章立即可见）；/_astro/ 哈希资源缓存一年并标 immutable，重新部署自动换哈希无需手动刷新；/assets/、/pagefind/、/pio/ 缓存 30 天；/api/ 边缘缓存 1 小时、浏览器不缓存。另加一个部署后自动从 sitemap 提取全站 URL 预热边缘缓存的工作流。
• 壁纸瘦身（V1.3）—— 桌面 4 张 + 移动 3 张全部转 WebP q90：14.3 MB → 1.0 MB，首屏图片加载量减 93%。配套写了个一键压缩脚本，支持强制重跑，以后换壁纸跑一遍就行。同期给 HTML 缓存加了 stale-while-revalidate=604800：CDN 缓存过期后先给访客旧页面秒开，后台同时拉新页面更新缓存。
• 首屏提速（V1.4）—— 贴纸图压到实际显示尺寸（源图 360×480，被 CSS 的 max-height: 104px 夹到约 78×104），8 张从 331 KB 降到 127 KB；修掉「装饰层入场动画要等 9 张图全部加载完才开始」的阻塞（改成只等卡片自身的图，兜底超时从 1400ms 收到 400ms）；favicon 从 88 KB 换成 8.9 KB —— 原来那个 .ico 其实是一张 221×183 的 PNG 改名的，重新生成了真多尺寸 ICO。首屏合计少传 283 KB。
• 预取刹车（V1.45）—— 把 Lighthouse 抓的逐帧截图导出来一张张看才发现，首屏最大的那笔流量根本不是图片：Swup 视口预取会让链接只要露出 20% 面积并停留 500ms 就被提前下载，而首页第一屏正好有 7 个链接满足条件（卡片导航 5 个 + RSS / 打赏），一次抓回 483 KB 的页面 HTML，占移动端总流量的 34%。关掉之后首屏少发起 14 个请求。
• 标题不再姗姗来迟（V1.5）—— 之前一直以为拖慢首屏的是壁纸或毛玻璃卡片，读了 trace 才确认最大元素是卡片里那行标题文字：它借用了通用内容关键帧、起点是全透明，而浏览器不把全透明的元素算作「已经画出来」，最大元素的计时就被硬生生推迟；更绕的是这个 0.36 秒的起点还得先等卡片里的小图加载完。换成专属关键帧（起点 opacity: 1，只保留 12px 的位移）后延迟从 0.36 秒砍到 0.08 秒，入场逻辑也拆成两段 —— 文字动画不再等图片。
• 壁纸请求为什么晚（V1.45）—— 那张 89 KB 的壁纸请求直到 638ms 才发出：它藏在 <template> 标签里，浏览器解析 HTML 时根本看不到它，必须等内联脚本把它克隆进 DOM 才开始下载。
• 别让小图抢带宽（V1.45）—— 侧栏头像改成懒加载并去掉 fetchpriority=high：一个小头像被标成高优先级，而真正的首屏标题和壁纸反而只有默认优先级。同时给 /images/ 和 /favicon/ 补上 30 天缓存头，这两类之前落在默认规则上、响应头是 max-age=0, must-revalidate，等于每次访问都要重新校验一遍。
• 站内搜索提速（V1.41）—— 搜索一直有种说不清的「慢」：敲完字要等好几秒。两件事叠在一起。一是资源链太深 —— pagefind.js、worker、wasm、索引分片严格串行依赖，而它只在用户碰到搜索框时才开始加载，几跳的等待全落在输入之后；二是取数请求数和结果条数同阶，主题对全部结果逐个调 data()，而每个 data() 就是一次 fragment 请求，搜个常见词命中 45 条就是 45 个请求。现在新增一个预热脚本：首屏空闲或鼠标碰到搜索框时就把 worker 起来、wasm 编译好、索引读进内存；再用一层 Proxy 只让前 6 条真拉正文（面板本来就只显示 5 条），实测 45 → 6，结果数组长度不变所以「查看更多 N 条」的计数仍然准确。顺带补上「回车 = 进第一条结果」（isComposing 为真时放行，不干扰中文输入法）。移动网络与省流模式下跳过预热，不抢带宽。

素材与相册#

• 贴纸素材的抠底与压缩（V1.9 / V1.18）—— 白底原图用「亮度 + 低饱和度谓词 + 四角洪水填充」抠底：靠连通性保住角色内部的白衬衫，同时吃掉落地灰影。画笔感强、浅色部件直接贴背景的那 6 张，本地抠图会咬掉剑刃和衣领，改用云端前景提取后再本地收边；云端抠图会把日期和画师签名当成前景留下，用「只保留面积 ≥ 最大连通域 5% 的块」一次清掉。
• 相册「首页贴纸原图」（V1.8）—— 12 张全分辨率原稿：9 张 1440~2048px 的原始 PNG，加上 3 张只有 192px 版本的早期素材（那就是现存最清晰的形态）。相册索引自动收录，封面手动指定为桐乃那张欢呼。
• 相册「夏娜表情」（V1.10）—— 9 张表情画稿：发怒、叹气、大哭、慌乱、懵圈、挥手、星星眼、脸红、蜜瓜包，原图不压缩存档。
• 相册「统计页插画」（V1.15）—— 把 /analytics/ 页面里的 7 张插画归档成新相册：页首横幅、两张角色立绘（保留透明通道）、四张概览卡片插画。三张 PNG 转 webp（质量 90、不放大、保留透明通道），四张本来就是 webp 的原样字节拷贝，避免二次有损压缩。
• 壁纸池扩充（V1.7 / V1.18）—— 桌面池加了夏娜横版（1920×1005）、黑猫夏装横图（1920×1080），移动池加了夏娜竖版（1080×1920）和一张抠掉品红底、保留透明通道的黑猫（1080 宽，背后露的是页面底色，浅色 / 深色模式各自适应）。V1.4 起开启多张壁纸自动轮播，每 5 秒切一张。
• 相册清理（V1.19）—— 「移动壁纸」相册删掉品红底的那张原图，「贴纸」相册删掉与单张高清版重复的九宫格源。
• 相册「俺妹指针主题」（V1.47）—— 两张指针主题总览图（桐乃 / 黑猫各 28 枚）原图字节一致、零压缩归档，站点实际加载的是据此切出的 public/images/cursors/。这类原样直出的相册不另建 gallery-originals/ 副本 —— 那个目录只给压过 webp 的相册用。

工程与基础设施#

• 内容与主题分离（V1.28）—— 文章搬进独立的私有仓库，主仓库 src/site-content/ 进 .gitignore，从此合并上游不用再为文章目录解冲突。构建前脚本从 CONTENT_REPO_URL 浅克隆内容（--depth=1），本地已有内容时自动跳过；本地开发走 CONTENT_DIR 加增量同步脚本，dev.sh / dev.bat 一键完成「同步 → 后台」。
• 内容推送自动部署（V1.28）—— 内容仓库加了一个 workflow：push 之后调用 Vercel Deploy Hook 和 Cloudflare 部署挂链，文章推上去就自动重新构建上线。平台只监听主仓库，内容仓库推它感知不到，这一步是必需的。
• Tailwind 扫不到内容目录（V1.34）—— 友链页的申请模板本该一条字段一行，实际挤成一整段。查下来不是 CSS 写错：内容目录在 .gitignore 里，而 Tailwind v4 的自动内容探测会跳过被 git 忽略的路径 —— 于是「只出现在内容文件、主题源码从没用过」的工具类永远不会生成，类名照旧挂在 HTML 上、规则却不存在。解法是加一个登记表：同步脚本顺带扫内容里出现的 class 名、写进一个没被忽略的文件，内容仓那边一个字都没改。
• 构建不再被接口拖垮（V1.35）—— 有一轮推了改动、等了十几分钟线上还是旧页面，翻日志才发现部署根本没成功：站长动态的 RSS 在构建期拉 Memos，实例解析到国内 IP、构建机在海外，直连必然超时；落到回退分支后又踩了个 bug —— processor.render() 是异步的、返回 { code, metadata }，之前把 Promise 当 HTML 字符串往下传，走到剥标签那步就抛 html.replace is not a function。更麻烦的是上游适配器里那句 promise.finally() 派生出的 promise 没人接管，fetch 一失败就是未处理的 Promise 拒绝，在 Node 24 下直接把构建进程带走，调用方的 try/catch 拦不住。现在构建期先做一次带 4 秒超时的可达性探测，连不上就完全不调接口；另外对 Memos 请求失败产生的未处理拒绝加了窄范围兜底，只忽略超时、连接重置这类网络错误并打印告警，其它拒绝照旧抛出。
• 给悬停封面做体检（V1.31）—— 书签导航的悬停封面走「构建期生成一份静态 JSON」，清单里没有对应条目时前端是 if (coverUrl) 直接跳过，静默不展开、零报错。所以把体检塞进那个静态 JSON 路由：比对配置与清单，缺了就 console.warn 列出来并附补图命令，零联网、零耗时。

写在最后#

这五十一版几乎全部落在 src/config/**、public/** 素材和新增的独立文件上 —— 跟上游的实际差异是 522 个新增文件加 66 个改动，而真正落进组件和页面目录的只有 5 个（CoverImage / WallpaperSection / Profile / friends.astro 加了 1 行 / guestbook.astro），剩下的全是数据文件（github-card-data.json / lqips.json）。原因很实际：上游更新勤，改动挂在外面才好合并，出问题也能整段摘掉。

这套「挂外面」的做法最近又救了一次场：动态页那条链路要补的是全站评论增强，而动态的评论跑在 iframe 里、那个页面没有页脚 —— 换作直接改页面或组件，就得跟上游的 comments.astro、DynamicInlineComments.astro、dynamic-inline-comments.ts 三个文件纠缠；挂在页脚注入上，只多了一个新脚本就解决了。

逐条的完整明细还是看更新日志页。

Folia 是什么#

项目叫 Folia，AGPL-3.0。卖点不是曲库，是全屏歌词——歌词动画在这个项目里是主角，不是附属的滚动条。

它有几个东西挺戳我：

我走的是 Web 版。界面就是一个封面网格，登录之后能直接看到自己网易云那边的歌单，卡片展开是播放和加入队列：

点开一首，网格中间会浮出播放面板，歌词在封面下方跟着走，再点一下就是上面那张全屏歌词：

Web 版要自备一个网易云 API#

这是整件事里最容易被忽略的一点。官方文档写得很直白：Web 版至少要有两样东西——一个放前端的地方，和一个可用的网易云 API 地址。

桌面端内置了前后端所以开箱能用，Web 版没有，你得自己准备。所以这次实际上是两段部署。

1
ENABLE_GENERAL_UNBLOCK=false

1
https://wyyapi.9ll.uk

1
{
2
  "name": "folia-major",
3
  "main": "./worker/index.ts",
4
  "compatibility_date": "2026-04-02",
5
  "assets": {
6
    "directory": "./dist",
7
    "binding": "ASSETS",
8
    "not_found_handling": "single-page-application",
9
    "run_worker_first": ["/api/*"]
10
  }
11
}

1
VITE_NETEASE_API_BASE=https://wyyapi.9ll.uk

踩坑：Cloudflare 的「变量」和「构建变量」是两回事#

这个坑我差点踩进去。

Folia 仓库里有个 runtime-config.js，看名字像是”运行时才读配置”，那种思路下环境变量填在 Worker 的运行时变量里就够了。但我把它抓下来看了一眼，内容是这样的：

1
// 当前文件：非 Docker Web 部署的空运行时配置，具体值继续由 Vite 环境变量提供。
2
window.__FOLIA_RUNTIME_CONFIG__ = window.__FOLIA_RUNTIME_CONFIG__ || {};

空壳。真正的值还是 import.meta.env.VITE_* 那一套，走 Vite 构建期注入。

也就是说 VITE_NETEASE_API_BASE 必须填在 Cloudflare 的构建变量（Settings → 构建 → 变量和机密）里。Cloudflare 自己的文档也写得很清楚：构建变量只在构建期可见，运行时读不到；反过来，运行时变量构建期也读不到。

怎么验证填对了：打开线上页面，看它实际请求的是不是你自己那个 API 域名。我这边在 music.9ll.uk 上抓到的请求是 https://wyyapi.9ll.uk/...，这才算真的通了。

第三段：绑域名#

Worker 建好之后在「域」标签页里加 music.9ll.uk。因为 9ll.uk 本来就在同一个 Cloudflare 账号里，DNS 记录是自动建的，证书也一起下来了，没等多久。

用之前先知道这几件事#

第一，不登录只能试听 30 秒。 Folia 的在线播放要登录网易云才完整，未登录状态下部分歌曲只能试听 30s，歌单、收藏、电台这些也看不到。

第二，AI 主题现在是用不了的。 它要另外一组 key：

1
VITE_AI_PROVIDER=google        # 或者 openai
2
GEMINI_API_KEY=你的_key

我这次没配，所以 AI 主题那个入口点了没用。想用的话把这几个变量加进构建变量再重新部署一次就行。

第三，QQ 音乐和酷狗这两条线有额外门槛。

• QQ 音乐 API 需要常驻 Node 进程（扫码登录依赖 MQTT over WebSocket 长连接），跑不了 Vercel Serverless 或者 Cloudflare Workers，得另找一台机器或 Docker 环境，再把地址填进 VITE_QQ_API_BASE。
• 酷狗那边是播放节点默认 HTTP + CDN 证书错配，HTTPS 页面里混不进 HTTP，有时候会播放失败，属于上游的老问题。

我这两个都没接，现在能用的是网易云在线 + 本地音乐库。

第四，构建令牌那条告警可以先放着。 Cloudflare 的构建设置里有一条「提取 GitHub 用户或组织详细信息时出错」。这次构建是正常的，先记一笔，真出问题再回头查。

写在最后#

代码都是原作者的，AGPL-3.0，我做的是 fork 一份、拆成前后端两段部署、再挂到自己域名下。许可证和署名都在仓库里留着。

部署过程这次同样是丢给 AI agent 用浏览器点完的，流程和前面那篇把浏览器交给 AI 之后一样，就不重复了。区别是这次多了「网易云 API 得自己先搭」这一段，比纯静态项目麻烦一档。

地址再放一次：https://music.9ll.uk/

这个站是开放给大家用的，谁都能来听 —— 不是自用测试实例，也不是搭完摆着看的。

配套的网易云 API 单独挂了个域名：https://wyyapi.9ll.uk/

它能干什么#

一共五个工具，共用同一个页面外壳，顶上胶囊标签直接切，不刷新页面：

关键点是：压缩走 WASM 编解码器，放大和抠图走浏览器里的 ONNX Runtime。也就是说计算全在你自己的设备上，图片从头到尾没离开过本机，服务器那边只是发静态文件。

我实测过一遍，抠图的边缘处理比不少在线站干净，尤其头发丝那种，BiRefNet 那一档能看出来是认真调过的。放大的速度看你有没有 WebGPU，有的话几秒出图，没有的话降级单线程 WASM，会慢好几倍。

部署：从 Pages 改成 Workers#

项目本身是给 Cloudflare Pages 准备的，仓库里的 wrangler.toml 写的是 pages_build_output_dir，README 的推荐路线也是连 Git 建 Pages。

我要求部署到 Worker 里，所以这里得改一手。

fork 到我自己仓库之后，配置改成 Workers 静态资源那套：

1
name = "image-tools"
2
compatibility_date = "2026-09-21"
3

4
[assets]
5
directory = "./dist"
6
not_found_handling = "404-page"

package.json 里的 deploy 脚本从 wrangler pages deploy dist --project-name=image-tools 换成 wrangler deploy。然后 Cloudflare 后台建 Worker、连仓库、构建命令 npm run build、部署命令 npx wrangler deploy，环境变量加一个 NODE_VERSION=22（Vite 8 要 Node 22.12+）。

用之前先知道三件事#

第一，第一次用 AI 功能要等模型下载。 权重是运行时从 HuggingFace 拉的，我钉了 revision，缓存之后就好了。第一次点放大或者抠图，会看到进度条在下载，别以为卡死了。

第二，你的设备决定速度。 有 WebGPU 的浏览器（Chrome / Edge 新版）最快；没有的话会自动降级，能用，就是慢。手机也能跑，但别拿它处理几十兆的图。

第三，别拿它当全功能修图软件。 它只干「压缩、转格式、放大、抠图、切图」这五件事，没有图层、没有调色、没有画笔。想干这些还是得开 PS。

写在最后#

代码是原作者的，MIT 协议，我做的只是 fork 一份、把部署目标从 Pages 换成 Workers、再挂到自己域名下。署名和许可证都在仓库里留着，放大和抠图用的权重版权归各自作者。

地址再放一次：https://img.9ll.uk/

压缩、转格式、放大、抠图、切图，五个功能都能用，不用注册、不用登录、不传图。有需要直接用，有什么问题留言告诉我。

先说结果#

我总共只说了四句话#

把聊天记录翻出来数了一下，从头到尾我提的需求就这么几句：

1. 帮我在我的 cf worker 部署这个玩意
2. 别本地上传，先去 fork 一份，然后链接 GitHub 创建
3. 域名用 hunxi.9ll.uk，去用路由，别直接绑定域名，然后解析 CNAME 和 9ll.uk 一样就行
4. 在我博客的书签里面添加这个网站，然后在关于子选项里面也添加这个网站

就这些。

剩下的全在它那边：开浏览器、翻 Cloudflare 后台、fork 仓库、写提交、点部署、等构建、加 DNS、加路由、再回头改我博客的两个配置文件。

它自己都干了什么#

二、自己去 fork#

它一开始想走 GitHub 的 API 直接 fork，结果吃了一个 403：

1
POST https://api.github.com/repos/gascy37/grimenc/forks: 403 Resource not accessible by integration

那个连接器的 token 权限不够，fork 和建文件都不给干。

它没卡在这儿，直接转头去开浏览器，自己找到 fork 页面，填好 owner，点了「Create fork」。

1
hunxi.9ll.uk  CNAME  1.cloudflare.182682.xyz   仅 DNS
2
hunxi.9ll.uk/*  →  grimenc

懒的代价#

写到这里得说实话，这事儿没有上面看着那么爽。

第一，我事后才知道为什么。 为什么 fork 完还得补 wrangler.jsonc、为什么要走灰云——这些我都是看它做完之后才反应过来的。过程我是”看着的”，但不是”懂的”。

第二，这次所有弯路都是它自己绕过去的，我一个都没帮上忙。 这句话听着像夸奖，其实是隐患：能力判断完全建立在我自己的感觉上，我没有一次能验证它到底是在解决问题还是在瞎试。

第三，如果哪天它绕不过去，我可能连问题都描述不清。 那些报错和后台的页面结构，我要是自己没上手做过一遍，出问题时连去哪查都不知道。

所以我现在给自己划了三条线，这三类事我不放手：

• 涉及钱的操作
• 有公开可见后果的（发帖、评论、对外通知）
• 删数据

其它的，包括这次的部署，我确实懒得自己动手了。

如果你也想这么懒#

前提只有两个：

1. 浏览器是通的。AI 得能操作你真实的 Chrome，带着登录态。这一步不解决，后面全是空谈。
2. 心态上接受”先跑起来再说”。它会在过程中撞墙、退回去换方案，你要能容忍那几分钟的不确定。

工具限制这块提前知道两个能少走弯路：连接器要看一下是不是只有读权限；本机浏览器工具如果配了工作区白名单，文件上传和截图这类要落盘的功能可能直接用不了。

写在最后#

这次最让我有感觉的不是”它能干活”，而是它干活的过程里撞了墙、自己找路绕开，而且一次都没回头问我。

我唯一的作用是划边界和提需求。剩下的它自己找路。

省下来的那点时间，说实话我也没拿去干什么正经事。这大概就是这篇最诚实的结论了。

参考站长什么样#

拿来的参考图是一个标准的右栏小组件：顶部一行小字眉题加一枚「Waline · 最新 8 条」徽章，大标题「最近评论」，右边一个「去留言板」链接；下面是评论列表，每条 = 圆形头像 + 昵称 + 相对时间 + 「评论于 /某路径」+ 两行摘要；卡片底部一行小字「已展示 8 条公开评论 · 内容来自 Waline」。

我的版本把眉题和徽章去掉（跟本站其它侧栏组件对齐，只留标题条 + 右侧链接），列表结构和参考基本一致。

我的做法：只动两个文件#

要挂载的页面是上游文件，侧栏的 SideBar.astro 也是 —— 它的 componentMap 写死了支持的组件类型，想加一种新 widget 就得改它。所以还是走本站用惯了的页脚注入：

页脚本身就在 #swup-container 之外，整页加载才跑一次，正好用来挂 swup:page:view。PAGE_SCRIPTS 是页脚里现成的机制：一个 pathname 正则数组，匹配上了才去 document.head 插对应脚本。其它条目都锚定具体页面（友链页、书签页），我这条要全站生效，正则直接放开：

1
{
2
  // 「最近评论」：全站加载 —— 桌面挂右栏、移动端挂底部栏，挂载逻辑在 js 里
3
  path: /.*/,
4
  id: "ff-recent-comments-js",
5
  src: "/assets/js/recent-comments.js?v=2",
6
},

脚本第一个页面进来就装上，之后切页不重跑；每次 swup:page:view 只重新决策挂载点。

挂载点按视口分两套，这也是主题自己的布局规则：≥768px 进右栏 top 组件容器，插在「最新动态」（widget-layout[data-id="latest-dynamics"]）之后；<768px 主题会把左右侧栏整块隐藏、改用页面底部的 #mobile-bottom-sidebar，组件就挂进里面的 #bottom-sidebar。两类容器都在 swup 的替换范围外，搬一次就永久有效，切页不会丢；再挂一个 matchMedia("(max-width: 767px)") 的 change 监听，跨断点时把节点搬到另一侧，缩放窗口也不会丢。

1
function findMountPoint() {
2
  if (isMobileNow()) {
3
    var bar = document.getElementById("bottom-sidebar");
4
    if (bar) return { parent: bar, before: null };
5
  }
6
  var sidebar = document.getElementById("right-sidebar");
7
  if (!sidebar) return null;
8
  var wrapper = sidebar.firstElementChild; // top 组件容器（flex flex-col gap-4）
9
  if (!wrapper) return null;
10
  var latest = sidebar.querySelector('widget-layout[data-id="latest-dynamics"]');
11
  return { parent: wrapper, before: latest ? latest.nextSibling : null };
12
}

核心机制#

数据：Waline 自带一个「最近评论」公开接口，前端直连即可：

1
GET https://waline.9ll.uk/api/comment?type=recent&count=8
2
→ { errno: 0, data: [{ nick, avatar, comment, orig, url, time, status, ... }] }

响应头带 Access-Control-Allow-Origin: *，CORS 是放开的，不需要代理。url 就是评论所在页面的路径（/guestbook/、/friends/、/posts/...），正好当「评论于」和跳转目标。拿到的数据按 status === "approved" 再过滤一遍，宁滥毋缺。

渲染：头像用接口返回的 avatar；字段为空时垫一个「昵称首字 + 哈希色相」的文字头像，img 的 error 事件一到就移除图片露出文字。时间显示成相对时间（N 分钟前 / N 小时前 / N 天前）。摘要统一截到 120 字，CSS 再 -webkit-line-clamp: 2 收两行。

缓存：localStorage 存 2 分钟。全站任何页面之间来回跳都不会重复请求，停留超过 2 分钟再打开才重新拉。

样式：全部写在页脚的 <style> 里，只用主题 CSS 变量（--primary、--content-meta、--btn-plain-bg-hover）和 card-base，不碰 Tailwind 工具类 —— 注入 HTML 里的工具类一旦没被内容探测扫到就是静默失效，这个坑本站以前踩过。几何复刻 WidgetLayout：标题条 ml-8/mt-4/mb-2 + 主题色竖条、内容区 px-4/pt-4、卡片 pb-4，视觉上和其它侧栏组件完全一致。

必要的技术坑#

一、orig 字段不是纯文本。 Waline 返回里有两个内容字段：comment 是渲染后的 HTML，orig 是渲染前的原始 HTML —— 名字看着像「原文」，实际含 <span class="wl-badge">AI</span> 这种标签。直接把 orig 当文本塞进去，摘要里就会露出一排 HTML 标签。正解是用渲染后的 comment，过一遍 DOM 取 textContent：

1
function htmlToText(html) {
2
  var box = document.createElement("div");
3
  box.innerHTML = String(html || "");
4
  return box.textContent || "";
5
}

只借 innerHTML 解析、马上读 textContent，不把用户内容插回页面，没有 XSS 面。

二、类名撞车，白吃 32px 内边距。 条目里的文字容器图省事叫了 ff-rc-body，跟组件内容外包装同一个类 —— 外包装那条 padding: 1rem 规则把每条评论的正文区也吃了，meta 行从 194px 缩到 162px，昵称被挤得只剩一个字。改名 ff-rc-main 隔离。注入样式和 JS 生成的类名在同一个命名空间里，下手前先 grep 一遍。

三、窄栏 flex：不设 grow，宽度就按 max-content 算。 摘要是两行 clamp 的段落，但它的 max-content 是一整行不换刀的宽（含长 URL，轻松 600px+）。文字容器没有 flex-grow 时，flex 基准取这个值，行内怎么分都不对。补 flex: 1 1 auto; min-width: 0 让容器稳定吃掉剩余宽度。另外meta 行里昵称设 flex: 0 0 auto 永不收缩 —— 窄栏放不下时截断「评论于 /路径」，身份比路径重要。

四、内联脚本一个语法错误，整个增强静默失效。 调试中途 PAGE_SCRIPTS 整段没执行，脚本压根没被请求，查了半天才发现是编辑工具把数组某行的缩排弄坏了，var PAGE_SCRIPTS = [...] 语法错误 → 整个 IIFE 不跑 → 既没有报错也没有任何效果。改完 FooterConfig.html 先用 new Function(scriptText) 把所有内联脚本校验一遍再验证，这个文件里已经躺着四段脚本，坏任何一段都可能连带一片。

上手步骤#

• 换 Waline 地址或显示条数：改 recent-comments.js 顶部的 API_URL。
• 改外观：样式全在 FooterConfig.html 末尾的 .ff-rc-* 段，标题文案和「去留言板」链接在外壳 HTML 里。
• 改了 JS 记得把 ?v= 往上加：vercel.json 给 /assets/* 配了 30 天强缓存，不加版本号老访客拿到的还是旧文件。
• 验证：astro dev 起服务，用 puppeteer 量 clientWidth/scrollWidth 判断截断（肉眼会漏），再分别验亮/暗主题、1280px 窄栏、桌面/移动端两种挂载点、swup 往返，以及「每个页面类型都有」。

最后是落地效果，亮色和暗色都跟着主题走：

移动端（375px）挂在页面底部的组件栏里，卡片拉满内容宽，meta 行空间充裕，「评论于」不再需要截断：

三条路线，先说结论#

能让 AI 碰到真实 Chrome 的路线我试出来三条：

结论：想要”能操作真实标签页”，目前只有第二条路走得通。 但它的代价是那个弹窗，下面细说。

第一条路的坑更隐蔽，我最后会讲。

路线一：chrome-devtools-mcp 接上真实 Chrome#

这是 Google 官方的 MCP 服务器，工具很全：点击、填表、导航、截图、看控制台报错、抓网络请求、跑性能 trace，一共 30 个工具。

1
chrome://inspect/#remote-debugging

1
npm install -g chrome-devtools-mcp@latest

1
{
2
  "mcpServers": {
3
    "chrome-devtools": {
4
      "command": "C:\\Users\\你的用户名\\.workbuddy-ai\\binaries\\node\\versions\\22.22.2-3\\node.exe",
5
      "args": [
6
        "C:\\Users\\你的用户名\\.workbuddy-ai\\binaries\\node\\versions\\22.22.2-3\\node_modules\\chrome-devtools-mcp\\build\\src\\bin\\chrome-devtools-mcp.js",
7
        "--autoConnect",
8
        "--no-usage-statistics",
9
        "--no-performance-crux"
10
      ]
11
    }
12
  }
13
}

1
{
2
  "content": [
3
    {
4
      "type": "text",
5
      "text": "## Pages\n1: https://www.bilibili.com/video/BV1GHHn6NEnZ/ [selected]\n2: 首页-个性推荐-哔哩哔哩\n3: [74%][50%] SamplerCustomAdvanced (http://127.0.0.1:8188/)"
6
    }
7
  ]
8
}

踩坑记录#

1
PLAYWRIGHT_GROUP_TITLE = "Playwright"
2
PLAYWRIGHT_GROUP_TITLE_PREFIX = `${PLAYWRIGHT_GROUP_TITLE} · `
3
// 只列出该组内的标签
4
tabs.query({ groupId: g.id })

1
export PLAYWRIGHT_MCP_EXTENSION_TOKEN=你的token

1
curl -s -D - -o /dev/null --noproxy '*' http://127.0.0.1:9222/json/version

1
curl -s --noproxy '*' "https://dns.google/resolve?name=www.example.com&type=CNAME"

1
playwright-cli attach --extension=chrome && playwright-cli -s=chrome tab-list

安全边界，说清楚#

这条路等于把你整个浏览器交给 AI——包括所有登录态。

我自己的判断标准是：

• 日常浏览器和调试浏览器分开。我现在是拿日常这个 Chrome 在连，所以只在我盯着的时候开调试开关，用完就关
• 别在有敏感后台登录态的时候开（网银、公司内部系统）
• 那个 --no-performance-crux 记得加上，不然你访问的 URL 会外流
• 自定义连接器在客户端里的定位就是”访问范围完全由你的配置决定”，没有预设边界

极简流程#

如果你只想快点跑通：

1. Chrome 打开 chrome://inspect/#remote-debugging，开启开关
2. npm install -g chrome-devtools-mcp@latest
3. 写 mcp.json，命令加 --autoConnect --no-usage-statistics --no-performance-crux
4. 重启客户端，去连接器管理页点「信任」
5. 让它 list_pages，能看到你的标签页就成功了

写在最后#

三条路线试下来，chrome-devtools-mcp 是唯一能真正操作到真实标签页的，代价是那个躲不掉的授权弹窗——但只要你让客户端托管进程、保持长连接，它一辈子只弹一次。

Playwright 扩展那条路看起来更干净，但”只共享 Playwright 标签组内的标签”这个限制，加上那个会绕过挑标签步骤的 token，实际用起来比看起来麻烦。

这套流怎么走#

四段，从出图到放大（组名就是 Fast Groups Bypasser 里显示的名字）：

SeedVR2 用 3B 还是 7B#

这是这套流里最需要说清楚的一点。

工作流里 UNETLoader 默认挂的是 7B（seedvr2_7b_int8_convrot.safetensors）。但别无脑上 7B。

• 3B：适合 2K 以下的图。
• 7B：适合 2K 以上的再放大。2K 以下的图硬上 7B，很容易出色块、画面变杂乱。

我的用法很简单：先看要处理的图长边——不到 2K 就用 3B，到了 2K 以上再换 7B。

切换只动一个地方：UNETLoader 的模型下拉框换成 seedvr2_3b_int8_convrot.safetensors 就行，其他连线一根都不用动，VAE 还是共用的 seedvr2_ema_vae_fp16.safetensors。

模型下载#

工作流一共用到下面这些模型：

关于主模型补一句：这套挂的是社区调的 Moody Mix premium 写实人像版，黑鹤001 的网盘里就有；如果只是想把流跑通，把 UNETLoader 换成官方 Krea2 turbo int8（同一张表里「官方 Krea2」那一栏）也完全可以，CLIPLoader 和 VAE 都不用动。

插件依赖#

自定义节点不算多，但缺一个就是一片红：

图像工具箱这个包 Manager 里搜不到，作者发在夸克网盘，这期视频里有说明，下载后解压丢进 custom_nodes 重启即可。它管的是最后那步批量保存和压缩，不需要的话绕过这一段就行。

剩下那批节点——SeedVR2Preprocess、SeedVR2Conditioning、SeedVR2PostProcessing、ResolutionSelector、ResizeImageMaskNode、LatentUpscaleBy——在工作流 JSON 里记的都是 comfy-core，属于 ComfyUI 内置，不用装插件。但这也意味着你的主程序得够新：ConvRot int8 是 ComfyUI v0.27 才原生支持的，老版本打开要么红要么加载不了量化权重。先把主程序更新到最新再导入工作流。

参数怎么调#

要动的东西基本就三个数字：

一采尺寸在 ResolutionSelector 里改（比例 / MP / 倍数），二采的 latent 放大倍数在 LatentUpscaleBy 里改。

踩坑记录#

写在最后#

这套流把「出图」和「放大」拆得很干净：Krea2 两段采样负责把画面结构定稳，UltimateSDUpscale 和 SeedVR2 负责把尺寸和细节顶上去。每一段都能单独 bypass，想快就只跑前面两段，要成品就把后面两道打开。

SeedVR2 那句再强调一遍：3B 管 2K 以下，7B 管 2K 以上，别无脑上 7B。

有更好的参数组合或者踩到别的坑，评论区交流。

我这边跑出来什么效果#

先给数据。我这边是 32G 内存加 12G 显存，单图参考：

两次加起来大概 700 秒，十一分多钟能拿到一条 15 秒的 720p 片子。

参考图我基本都是拿 Krea2 出的角色图来喂的，之前写过一篇 Krea2 四视图生成，四个角度和脸型一次交代清楚，现在还在用，单图参考正好吃这一套。

0.2 MP 换算过来就是 608 × 352，肉眼看着确实糊。但一采本来也不是拿去交付的，它的任务是快速定下构图、动作和运镜，真正出片的是二采。

0.2 对动漫基本够用。真人我玩得少，就不乱下结论了——动漫角色线条干净、背景相对简单，一采丢掉的信息二采大多能补回来；真人那些皮肤质感、发丝、细微光影，估计得把一采提到 0.4 甚至 0.6 才稳，这个留给常跑真人的朋友自己试。

和上次那套的区别#

上次那套（H3-3.0）是单段的：采样一轮，直接出你想要的尺寸。

这套是两段：

1. 一采：由 ResolutionSelector 定一个很低的尺寸。15 秒配 0.2 MP，只出 608 × 352。步数上工作流把整条 sigma 表拆成两段——SplitSigmas 在第 8 步切开，前 8 步给一采，后 4 步留给二采；总数 12 是用 a + b 自动算出来喂给 BasicScheduler 的。latent token 少，这一步很快。
2. 二采：先用 LTXVSeparateAVLatent 把一采出来的音视频 latent 拆开，交给 MinimaxH3LatentUpscaler3D 在 latent 空间里放大（工作流里给的是 2 倍，608 × 352 翻一倍，差不多就是 720p 这一档），再 LTXVConcatAVLatent 拼回去，最后交给 MMH3UltimateUpscale 按时间分块重采样。

关键在第二步没走「解码成像素 → 放大图片 → 再编码回 latent」那条路。H3 的 VAE 有 50 亿参数，解码再编码非常贵，直接在 latent 上放大，省掉的就是这一段。

工作流里还挂了个 VRGDG Video Compare Slider，一采和二采的结果叠在一起，拖滑块就能对比。这个细节挺贴心，能直观看出二采到底补回来了什么。

模型下载#

工作流里一共用到六个模型文件：

模型组里还有个 MiniMax H3 Sigma Shift，视频偏移 12、音频偏移 3，工作流已经把值给好了，一般不用动。

插件依赖#

这套工作流的自定义节点比上次那套多，缺一个就是一片红。按 ComfyUI Manager 里显示的包名整理了一遍：

Manager 里搜不到后两个，直接 clone：

1
cd ComfyUI/custom_nodes
2
git clone https://github.com/PlagueKind/ComfyUI-PlagueKind-Nodes.git
3
git clone https://github.com/LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler.git

剩下那批节点——MiniMaxH3ReferenceToVideo、MiniMaxH3SigmaShift、ModelAttentionBackend、ResolutionSelector、ComfyMathExpression、LTXVConcatAVLatent——在工作流 JSON 里记的是 comfy-core，属于 ComfyUI 内置，不用装插件。但这也意味着你的 ComfyUI 得够新：老版本打开，这些节点一样是红的。先把主程序更新到最新再导入工作流。

设置面板怎么调#

工作流把要调的东西全圈在「设置」那一组里，用 ▼ 标签标出来，照着改就行：

边跑边看：采样预览#

这套工作流还内置了一个可视化节点，KJNodes 的 Model Preview Override（节点上写着「采样预览」）。跑采样的时候它会在旁边实时渲染一版低清画面，能大致看出构图、动作和人脸有没有崩。

这个功能挺关键的。一采加二采跑一趟十几分钟，要是等全部跑完才发现手画成六根指头、或者角色整个人歪了，那十几分钟就白扔了。有预览就能在中途看出来，直接中断，改个种子重开，省下的是整轮的时间。

要让它出画面，得把 taeh3.safetensors 放进 ComfyUI/models/vae_approx/。这个目录 KJNodes 是写死的（源码里就是 folder_paths.get_full_path("vae_approx", name)），放错地方节点里的 tiny_vae 下拉框就选不到它，预览区只会一直显示 waiting for sample…。

节点上这几个值是工作流里给好的：

节点下半部分还有个曲线区，右边直接给每一步的耗时（step time (ms)）。想让整体时间降下来，盯着这个数调步数最直观。

踩坑记录#

1
max(5, round(a * 24)) + (5 - (max(5, round(a * 24)) % 17)) % 17

写在最后#

这套工作流我会一直留着用。它把「快」和「清楚」拆成两步：低分辨率那一步不心疼，高清那一步也不用担心一步到位把显存榨干。32G 内存加 12G 显存能跑到 15 秒 720p，对家用机器来说已经很够意思了。

有更好的参数组合或者踩到别的坑，评论区交流。

他那边是怎么做的#

顺手把他的仓库扒了一遍。他的站也是 fork 的 Firefly，仓库公开，qwc-ch/Firefly。

实现全在 .github/ 下面，一共三个文件：

流程是这样的：申请人在 Issue 表单里填站点名、主站链接、友链页地址；workflow 监听到 issues: [opened] 就启动，跑脚本去访问那个友链页，确认页面上确实有他的站，然后改 friendsConfig.ts 并提交。

还有个细节我觉得挺聪明：触发条件里还带了 issue_comment: [created]，而且只有 Issue 作者本人的回复才会重新跑一遍。申请人第一次没挂链接被拒了，改完自己回一句，机器人重新验一次，不用关掉重开。

入口也不是什么站内表单，就是一条链接：

1
https://github.com/qwc-ch/Firefly/issues/new?template=friend-request.yml

一个反直觉的点：这事不需要服务端#

搜「自动友链」的时候翻到一篇写得很细的文章，讲的是把友链数据抽成 links.json、把站切成 SSR、再加一个 API 接口负责校验和写文件。看完我一度以为得动构建模式。

扒完他的仓库才发现，他压根没上 SSR。站还是纯静态的，部署在 GitHub Pages（deploy.yml 里就是 on: push: branches: [master]）。

关键在于：校验和写入不发生在访客访问的时候，而是发生在 GitHub Actions 的容器里。

• 机器人跑在 GitHub 的机器上，改文件、提交、推送，都是它干的
• 推送触发平台重新构建，新友链就出现在页面上了

所以静态站完全够用。那篇文章里的 SSR 是作者自己站的部署方式，不是这件事的必要条件。

但他的脚本不能直接抄#

有三处我这边过不去。

1
const friendBlocks = [...listMatch[1].matchAll(/\{([\s\S]*?)\n\t\},?/g)].map((item) => item[1]);
2
return friendBlocks.map((block) => ({
3
  title: extractString(block, 'title'),
4
  imgurl: extractString(block, 'imgurl'),
5
  desc: extractString(block, 'desc'),
6
  siteurl: extractString(block, 'siteurl'),
7
  tags: extractTags(block),
8
  weight: extractNumber(block, 'weight', 10),
9
  enabled: extractBoolean(block, 'enabled', true),
10
  issue_id: extractNumber(block, 'issue_id', 0),
11
}));

1
const anchor = 'export const friendsConfig: FriendLink[] = [';
2
const at = raw.indexOf(anchor);
3
const updated =
4
  raw.slice(0, at + anchor.length) + eol + entry + raw.slice(at + anchor.length);

1
- run: pnpm install --frozen-lockfile
2
- run: pnpm exec playwright install --with-deps chromium

1
- name: Setup Node.js
2
  uses: actions/setup-node@v4
3
  with:
4
    node-version: "22"
5

6
- name: Process friend request
7
  uses: actions/github-script@v7
8
  with:
9
    github-token: ${{ secrets.GITHUB_TOKEN }}
10
    script: |
11
      const path = require('node:path');
12
      const handler = require(path.join(process.env.GITHUB_WORKSPACE, '.github/scripts/auto-friend-link.cjs'));
13
      await handler({ github, context, core });

我的三件套#

同样是三个新增文件，职责划得很清楚：

友链页那边的入口做成这样：

原来的「发评论区 / 发邮件」那条路我没删，压缩成一行小字留在按钮下面。用 GitHub 的门槛确实有，得给人留个后路。

校验的三项#

另外做了两个防呆。

字段里的换行和引号会压平转义。有人手打 Issue 的时候如果在「网站名称」里塞一段 "]; 加换行，不处理就会把 friendsConfig.ts 撕成语法错误。

还有 label 不存在时不能让整个 job 挂掉。GitHub API 对不存在的 label 直接返回 422，流程会当场炸掉，所以 addLabels 外面包了 try/catch，workflow 里也顺手 gh label create ... || true 先建一遍。

### 网站名称 读不出来#

Issue 表单提交之后，正文长这样：

1
### 网站名称
2

3
测试小站
4

5
### 网站链接
6

7
https://example.com

我一开始按 \n### 切分，每块的第一行当字段名。写完跑单元测试，发现第一个字段永远解析不出来。

原因挺蠢的：正文开头就是 ### 网站名称，它前面没有换行，所以没被切走，留在了第一块里，字段名变成带 ### 前缀的字符串，怎么都匹配不上。

修法是在清洗字段名时补一句：

1
String(label).replace(/^#+\s*/, '')   // split 后第一块的 label 会带 "### " 前缀

还有个更值得记的教训：测试得走生产路径。

我第一版测试是自己在测试里手动拼了个对象塞进去测的，跑得干干净净——因为它压根没碰真正解析 Issue 正文的那段代码。后来把字段整理抽成 buildForm()，测试和主流程共用同一个函数，上面那个 bug 才浮出来。

极简流程#

要复刻的话，需要动的就四处：

1. .github/ISSUE_TEMPLATE/friend-request.yml —— 申请表，字段按自己的站点信息改
2. .github/scripts/auto-friend-link.cjs —— 校验和写入，改开头 SITE_INFO 里的域名
3. .github/workflows/auto-friend-link.yml —— 触发
4. 友链页加一个入口按钮

然后两个仓库设置：

1
Settings → General → Features → 勾上 Issues
2
Settings → Actions → General → Workflow permissions → Read and write

第一条必须开——fork 出来的仓库 GitHub 默认把 Issues 关着，不开的话申请链接直接 404，模板文件在不在都一样。

第二条是给机器人 push 配置用的，默认就是 Read and write，但如果之前手动收紧过，这里不放开提交会失败。

前置条件就这些。零依赖、零服务器，整套东西三个文件。

先把友链那套抄一遍#

友链那套实现上次已经写过一篇（给友链页加了悬停预览），这里只列一下文件对应关系：

数据源从 friendsConfig 换成 booknavConfig，匹配的字段从友链的 siteurl 换成书签的 item.url，其余逻辑一行没改。

截出来大概是这样，一张 640 宽的 webp：

到这里为止都很顺。下面三个坑全是「书签和友链不一样」的地方。

坑一：同一个域名挂了好几条书签#

友链基本一站一个域名，文件名直接用域名扫就行：

1
blog.cuteleaf.cn  →  blog-cuteleaf-cn.webp

书签不是。我这边 github.com 底下挂了 7 个仓库 —— Firefly 上游、我自己的 fork、CC Switch、BewlyCat 之类的，全都在同一个域名下。

按域名取文件名，这 7 条会互相覆盖，最后只剩一张，而且还不确定剩的是哪张。

改法是把路径也编进文件名：

1
github.com                              →  github-com.webp
2
github.com/keleus/BewlyCat              →  github-com-keleus-bewlycat.webp
3
github.com/hy4962/Firefly               →  github-com-hy4962-firefly.webp

万一连路径都一样，再补 -2、-3。清单里的 key 还是原始 URL，所以文件名怎么变都不影响匹配。

坑二：403 页伪装成一张正常的截图#

这个是最阴的。

第一轮跑完我随手翻产物，发现 deviantart 那张是 Cloudflare 的 403 页。

截出来是一张白底黑字、排版很规整的页面：

1
403 ERROR
2
The request could not be satisfied.
3
Request blocked.

问题在于 —— 它长得跟一张正常截图没有任何区别。文件大小正常（21 KB），宽高正常，打开是张像模像样的图。光看产物根本发现不了，得悬停展开才知道是个报错页。

所以必须在截图那一步就把它筛掉。

好在 chrome 的 --dump-dom 和 --screenshot 可以在同一次调用里同时用 —— 一个把渲染后的 HTML 打到 stdout，一个写图片文件，一次请求两样都拿到，不用多跑一遍：

1
--screenshot=<png 路径> --dump-dom <url>

拿到 HTML 之后，只看前 4000 个字符，命中这些特征就当失败：

1
const BLOCKED_MARKERS = [
2
  /the request could not be satisfied/i,
3
  /\b403\s+error\b/i,
4
  /you have been blocked/i,
5
  /attention required/i,
6
  /just a moment\.\.\./i,
7
  /enable javascript and cookies to continue/i,
8
  /checking your browser before accessing/i,
9
  /verify you are human/i,
10
];

只看开头是有意的：正文里偶尔出现「access denied」不算，标题和首屏出现才算。

另外还补了一道，用 sharp 算一下三个通道的标准差，整页一个颜色的空白图直接丢：

1
const stats = await sharp(pngPath).stats();
2
if (stats.channels.every((channel) => channel.stdev < 3)) {
3
  throw new Error("截图几乎是纯色空白页，已丢弃");
4
}

这一道抓的是另一种情况：站点还在渲染，图就先截下来了，出来是张纯白的。后来查失败清单，動漫花園、TouchGal 那几个就是栽在这。

坑三：headless 的 UA 会被直接拒#

chrome-headless-shell 的默认 UA 里带 HeadlessChrome 字样，Cloudflare 那批站点认得出来，直接回验证页。

换成正常的 Chrome UA 之后通过率明显上来：

1
--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36

卡片得改成网格才装得下封面#

前面都是截图的事，这一步是布局。

书签卡片原来是个横向 flex：左边 14×14 的图标，右边标题和描述。要让顶部能展开一条通栏封面，得把布局改成两列网格：

1
.booknav-grid .booknav-card {
2
  display: grid;
3
  grid-template-columns: auto minmax(0, 1fr);
4
  column-gap: 0.75rem;
5
  row-gap: 0;
6
}
7
.booknav-grid .booknav-card > .ff-booknav-cover {
8
  grid-column: 1 / -1; /* 占满整行 */
9
}

三个细节和友链不一样：

row-gap 要显式归零。 卡片上原本有 Tailwind 的 gap-3，在 flex 下只影响横向间距，改成 grid 之后它会同时变成行间距，封面和下面那行之间会凭空多出 0.75rem。所以得单独写 row-gap: 0。

负边距的数值跟着卡片 padding 走。 封面要顶到卡片边缘靠的是负边距，这个值必须等于卡片的 padding。友链那边是 p-2.5（0.625rem），书签这边是 p-3（0.75rem），照抄友链的会露一圈边。

网格要 align-items: start。 默认是 stretch，一张卡片展开会把同一行的邻居一起拉高。

「.booknav-card 是 flex」这件事本身是写在 Tailwind 类里的，我的样式是运行时注入的 <link>，未分层，压得过 @layer utilities，所以直接覆写就行，不用加 !important。

脚本怎么进到页面上#

这部分和友链完全一样，顺手做了个小整理。

页脚（src/config/FooterConfig.html）里原本挂着一段友链专用的加载器，只在 /friends/ 才去拉真正的脚本。这次要再加一个书签的，与其复制一段，不如改成数组：

1
var PREVIEW_SCRIPTS = [
2
  { path: /^\/friends\/?$/, id: "ff-friend-covers-js", src: "/assets/js/friends-covers.js" },
3
  { path: /^\/booknav\/?$/, id: "ff-booknav-covers-js", src: "/assets/js/booknav-covers.js" },
4
];

按 pathname 正则匹配，命中的才插 <script>。以后哪页还要加同款预览，往数组里补一条就行。

映射表走 src/pages/api/booknav-covers.json.ts，加了 export const prerender = true，构建时生成一份静态 JSON，访客拿到的是文件不是接口。

封面图首屏一张都不加载 —— 脚本给 img 挂的是 data-src，卡片真被悬停或聚焦过才写进 src。

结果#

64 个书签，56 个拿到了能看的封面，加起来 812 KB。

失败的 8 个：

没有封面的书签卡片保持原样，悬停不展开，也不会留个破图。

全量跑一遍大概 9 分钟，主要是等每个站加载。已经截过的会跳过，所以加完新书签再跑一次，只补新的那几张，两三分钟的事。

以后加书签#

1
npx tsx scripts/generate-booknav-covers.ts

想单独补某一条：

1
npx tsx scripts/generate-booknav-covers.ts --only=touchgal

全量重来加 --force，只想试水加 --limit=5。

总结#

• 书签和友链最大的区别是域名会重复，文件名必须带路径段，不然多条书签会共用一张封面。
• 截图脚本一定要校验产物。Cloudflare 那种 403 页截出来就是一张「看起来很正常」的白底黑字图，不主动筛就会混进线上。
• --dump-dom 和 --screenshot 能一次调用同时拿 DOM 和图片，校验几乎零成本。
• 卡片布局从 flex 改 grid 是让封面独占一整行的最省事做法，但记得把 row-gap 归零、负边距对齐卡片 padding。

先看别人是怎么做的#

动手之前先去翻了翻别人怎么实现的。

有个博客主题叫 Shirone，它的文档里专门有一章讲内容分离，讲得挺细。看完发现它的做法跟我一开始想的完全不一样——我本来以为要用 git submodule，结果它压根没用。

它的思路是「构建时同步」：

• 主仓库（主题代码）里完全不含内容
• 内容放在另一个仓库，靠一个配置文件声明位置：

1
{
2
  "source": {
3
    "type": "git",
4
    "url": "https://github.com/OWNER/shirone-content.git",
5
    "ref": "main"
6
  },
7
  "mounts": {
8
    "content": "src/content",
9
    "data": "src/data",
10
    "assets": "src/assets",
11
    "public": "public"
12
  }
13
}