SDTTTTT

2026-10-07

维护记录

完成的工作

  • 把 CI 从「一堆散落在 YAML 里的 shell」改成「薄 YAML + bin/*.sh」 ✅
    • 触发原因:用户认为当前工作流不健康(诊断结论:仓库有两个作者 —— 用户和 CI 里的 bot,根因是本地不跑 CI 会跑的 fixer,典型事故是 0a651bd 一次误改 230 个文件、b68a395 改名 225 篇后要 51aa901 补 25 篇 aliases)
    • 用户口径(原话):「将 github action 重写,CI 中运行的脚本后续以本地 shell 脚本的方式编写,除非是 CI 环境或者是 github 强制依赖的操作,否则都在本地的 shell 中完成」,随后澄清「脚本还是在 github action 上运行,不是本地运行,只是接触了 yaml 编写工作流的依赖」
    • 于是设计成:YAML 只声明触发条件 / permissions / environment / 第三方 action / 工具链安装 / concurrency,逻辑全部在 bin/*.sh,本地跑同一个脚本就复现 CI 的结果
  • 新增 bin/ 脚本层(11 个文件,bash 3.2 兼容 —— macOS 自带 bash 3.2 没有 **、关联数组、mapfile)✅
    • bin/lib.sh:被 source 的底座(定位仓库根、把 vendored 的 .tools/deno/bin 前置进 PATH、log/ok/warn/fail、run_step + CHECK_FAILED + report 的「失败不中断、最后汇总」累加器、shell_syntax_check、sha256_of)
    • bin/preflight.sh(--check 只读 / --fix 就地修 / --re-stage 修完重新入 index,五步:① 文章文件名 ② Markdown 格式 ③ front matter ④ 单测 ⑤ 构建产物新鲜度)、bin/validate-posts.sh、bin/test.sh(含全部 shell 文件的 bash -n 语法检查)、bin/build.sh、bin/build-wasm.sh、bin/artifacts.sh、bin/check-links.sh、bin/publish-autofix.sh(CI 专用,本地跑会被拒绝)
    • bin/hooks/pre-commit(preflight --fix --re-stage)与 bin/hooks/pre-push(preflight --check)+ bin/install-hooks.sh(写成 core.hooksPath=bin/hooks,所以 hooks 是版本化文件,升级 / 回滚不用重装)
  • 四个 workflow 全部瘦成壳 ✅
    • deploy.yml:checkout(去掉多余的 submodules: true,本仓库没有 .gitmodules)→ setup-deno(v2.x → 钉死 '2.9.5')→ deno install -g -A npm:prettier@3.9.6 → actions-hugo → ./bin/preflight.sh --fix → ./bin/build.sh → 上传 Pages → ./bin/publish-autofix.sh
    • test-scripts.yml / validate-posts.yml / check-dead-links.yml 同样只剩一行调用(./bin/test.sh / ./bin/validate-posts.sh / ./bin/check-links.sh),paths 里补上 bin/**
  • 新增「构建产物新鲜度」检查(本仓库最容易忘的两件事)✅
    • bin/artifacts.sh:图片侧检查 assets/src/bg/*.png → static/bg/*.avif(源图缺产物 = 硬失败并提示跑 deno task optimize-images;只比 mtime 才 warn,避免新克隆时误报),wasm 侧读指纹清单比对
    • 新产物 themes/sdttttt-paper/assets/wasm/particles.sha256:sha256sum 格式(故意不用 JSON,bash 3.2 里解析 JSON 不值当)记「产物 1 行 + 源文件 4 行」。CI 不装 Rust,所以靠这份指纹就能发现「改了 wasm/** 却忘了重建」;本地有 cargo 时 --rebuild 会重编译 + cmp 做最强校验
    • 实测指纹 cac4cbe7… particles.wasm,与独立验证的 sha256 完全一致(32062 字节);--rebuild 重编译 0.27s、逐字节一致 ⇒ 产物可复现
  • scripts/rename-posts.ts 新增 --check 只读门禁 ✅
    • 语义:一个字节都不许改,但「有待改文件」本身就是失败(退出码 1),用来在本地 / CI 断言「当前内容 == CI 会产出的内容」;deno.json 新增 rename-posts-check task
    • skipped 明细在 --check 下压成一行(否则每次刷 225 行「已是新格式」)
    • scripts/__tests__/rename-posts-execute.test.ts 新增 2 个 CLI 端到端测试(不合规范 → 退出码 1 且文件不动;已规范化 → 退出码 0)
  • 文档同步:AGENTS.md(新增 bin/ 目录说明与「CI 与本地检查」一节、提交规范指向 ./bin/preflight.sh、wasm 重建要连指纹一起提交)、README.md(常用命令加 ./bin/preflight.sh / ./bin/install-hooks.sh,补一句「workflow 只是壳,CI 跑的是 bin/*.sh」)✅
  • 验证:./bin/preflight.sh(只读)与 ./bin/preflight.sh --fix 都在 1.9s 内五步全绿,退出码 0;deno task test 31 passed (142 steps);hugo --minify 通过;./bin/publish-autofix.sh 在本地如设计般拒绝执行(退出码 2)

遇到的问题

  • bash 3.2 + set -u 下 $VAR 紧跟全角字符会被当成变量名的一部分 ⚠️ - ok "产物已更新:$WASM_ARTIFACT(…" 直接报 WASM_ARTIFACT(: unbound variable(bin/build-wasm.sh: line 23),因为 ( 的多字节序列被当成了名字里的字符。全仓库 grep 出 9 处(preflight.sh:35/55/58、check-links.sh:24、artifacts.sh:65/90/94/135、build-wasm.sh:23),统一改成 ${VAR}(。附注:位置参数 $1 后面跟全角是安全的(bash 只取一位数字),字母变量名才有这个坑
  • --check 第一版会真的改名 ⚠️ - 加了 --check 解析却忘了让它隐含 dry-run,于是 /tmp/checkprobe 里实测:打印「--check:需要重命名 1 篇文章」之后紧接着「✓ 重命名 1 篇文章成功」并 exit 0 —— 一个号称只读的门禁把文件改了。修法是 dryRun = --dry-run || --dryRun || --check,并补了「文件名必须一个都不动」的端到端测试守住它
  • 本机没有全局 deno ⚠️ - deno: command not found,但仓库里有 vendored 的 .tools/deno/bin/deno(2.9.5)。bin/lib.sh 因此负责把 .tools/deno/bin 前置进 PATH —— 顺带也解决了 prettier:.tools/deno/bin/prettier 是 deno 的 shim,自己要求 PATH 上有 deno
  • bash -n 只吃第一个文件 ⚠️ - bash -n bin/*.sh 静默只检查了第一个,语法错误会漏。shell_syntax_check() 改为逐个文件循环

下次建议

  • ./bin/install-hooks.sh 还没有执行:它会写用户的 git config core.hooksPath,属于动本地配置,等确认后再装
  • 尚未实跑的路径:bin/publish-autofix.sh(本地会拒绝,只能在 CI 里验)、bin/check-links.sh(要打外网)、bin/build.sh 单独跑、preflight --re-stage;lib.sh 的 sha256_stream 目前没人调用(疑似死代码,下次清理时确认)
  • 「工作流不健康」还剩四条没有落地也没有被否决的修法:① 文件名与正文 hash 解耦(现在改正文就会改 URL,只能靠 aliases 兜)② front matter 只留一份真相(文件与 Hugo 缓存 / 索引之间的重复)③ themes/sdttttt-paper/assets/js/*.js(1557 行)零测试 ④ 本地 git 身份是 github-actions[bot],用户自己的提交也挂在 bot 名下
  • 本次改动已随同一次提交推送:ci: 把 workflow 逻辑搬进 bin/ 脚本层

第二轮跟进(同日,用 gh 看过 CI 之后)

  • 先看线上跑得怎么样 ✅ - 440b746 上四个 workflow 全 success(Hugo on GitHub Pages / Check Dead Links / Validate Posts / Test Scripts);build 日志里 bin/preflight.sh 五步全绿(ok preflight 通过(fix))、hugo 建 270 页、Commit auto-fix results: ok 没有需要提交的改动 —— bin/publish-autofix.sh 正确 no-op,「两个作者」的问题第一次没有发作。唯一的告警是 Node 20 弃用(跑在 Node 24 上)和 ubuntu-latest 的迁移预告
  • 升 action 大版本(就是那条 Node 20 告警)✅ - 四个 workflow 里的 actions/checkout@v4→v7,加上 deploy 专用的 actions/configure-pages@v5→v6、actions/upload-pages-artifact@v3→v5、actions/deploy-pages@v4→v5。逐个核过 breaking change:checkout v6 只是把 persist-credentials 改存 $RUNNER_TEMP,v7 新增的 allow-unsafe-pr-checkout 只影响 pull_request_target / workflow_run 的 fork checkout;v4 的 upload-pages-artifact 不再打包 dotfiles —— 实测 find public -name '.*' 0 个,对我们无影响。setup-deno 与 peaceiris/actions-hugo 已是最新
  • 死链检查拆出「被服务器拦住」 ✅ - scripts/check-dead-links.ts 新增 BLOCKED_STATUSES = new Set([401, 403, 429, 451])、isBlockedStatus()、partitionByStatus(),先报死链(stderr、退出码 1)再报「N 个链接被服务器拦住、没能验证(不算死链)」;bin/check-links.sh 在「没有死链、但有被拦住」时也写一条 job summary。本地实跑:20 条告警 → 3 条真死链 + 17 条被拦住(13 条百度百科 ?fromModule=lemma_inlink 反爬、StackOverflow、2 条 github.com/user-attachments、1 条 451)
  • 反爬域名不参与判定 ✅ - 同一批百度百科链接在同一份代码上时而 403、时而 404(并发 6 个请求打到同一家站时偶发 404),于是「真死链」数量每次跑都不一样。新增 ANTI_CRAWL_HOSTS = {baike.baidu.com} + isAntiCrawlHost():这些域名下拿到的任何状态都归「没能验证」
  • 收掉最后一条真死链(归档允许清单) ✅ - scripts/check-dead-links.ts 新增 ARCHIVED_URLS + isArchived():已知失效、且正文里已注明「仅作存档」的链接连请求都不发,单列一栏「已归档」,不计入死链、不改退出码。清单自身也有测试守着 —— 每条都必须在正文里真的出现、且带一句说明,否则就成了「悄悄放行一条死链」
  • 日志噪声与死代码 ✅ - rename-posts 默认只打一行「跳过 N 篇(…加 –verbose 看明细)」(以前刷 229 行);删掉 bin/lib.sh 里从未被调用的 sha256_stream
  • 修两个站内 404(都是写在 changelog 正文里的历史 URL)✅ - content/changelog/_index.md 新建,用 aliases: ["/maintenance/"] 给旧地址留活路;content/posts/20260817-文章的变化-277.md 补全 5 条历史 alias(05hog4 → 03wwo2 → -jtc → -1e69 → -dqo → -277,用 YAML 块式写)
  • 顺手修掉 addAlias 的一个 latent bug ✅ - scripts/rename-posts.ts 里识别「aliases: + 缩进数组」的正则认不出 Prettier 把方括号也折成多行的写法([ 与 ] 各占一行),会落到块式分支、插出 aliases: + - "…" + [ … ] 这种非法 YAML —— 仓库里已经有 2 个文件是这个形态(content/posts/20230912-关于查找自己想要的软件的问题-pyx.md、content/posts/20250504-C中的指针运算-类型转换以及函数指针-dsq.md),下一次改名就会让 Hugo 构建失败。修法:正则的 (.*) 换成 ([\s\S]*?)、[ \t]+\[ 放宽成 [ \t]*\[;scripts/lib/frontmatter.ts 同步支持折行数组(并在 parseScalar 丢掉尾逗号产生的空项);两处各补测试
  • 验证:./bin/preflight.sh 五步全绿(33 passed / 150 steps,其中 --fix --re-stage 这条路 —— 正是 pre-commit hook 的命令 —— 也跑通了);hugo --minify → 270 页 / 250 aliases;public/maintenance/index.html 已生成且跳 /changelog/;./bin/check-links.sh → 2 条死链(就是本次刚修的两个站内 404,部署后即消失)+ 17 条没能验证 + 1 条已归档
  • 部署后复验 ✅ - de9b9ea 推上去后四个 workflow 全 success(Hugo on GitHub Pages 1m7s、Check Dead Links / Validate Posts / Test Scripts 均 ~13s);actions/checkout@v7 生效后 日志里再也找不到 Node 20 弃用字样;两个站内 URL 现在都返回 200(https://sdttttt.online/maintenance/、https://sdttttt.online/posts/20260817-文章的变化-1e69/);手动 gh workflow run check-dead-links.yml 重跑一次 → 0 条死链 + 17 条没能验证 + 1 条已归档,不再挂 ::warning::

遇到的问题(第二轮)

  • partitionByStatus 第一版把 200 的链接也算进死链 ⚠️ - 只按 isBlockedStatus(status) 分组、忘了原来那句 !statuses.get(url)!.ok,于是「能打开」的链接也进了 dead 组。新加的 3 个单测当场抓住(ok 的链接两组都不进 失败,actual 里混进了那个 ok.example 的链接),补一句 if (entry.ok) continue; 后全绿
  • 给 section 加 _index.md 会把标题清空 ⚠️ - 写完 content/changelog/_index.md(只为了 aliases)之后构建出的标题变成 <title>- 海边。把文件移开重建才确认:原本的 “Changelogs” 是 Hugo 按目录名生成的,一旦有了 _index.md 就改从文件取。所以必须在文件里显式写 title: "Changelogs" —— 这种「加了文件反而丢东西」的改动,只能靠改动前后各构建一次对比来发现
  • Prettier 会把长 alias 数组折成多行 ⚠️ - 5 条 alias 写成 inline 时 Prettier 会折成 [ / 各项 / ] 各占一行,而那正是上面那个 latent bug 的触发形态。改用 YAML 块式(aliases: + - "…")后 Prettier 保留原样,addAlias 与 parseFrontMatter 也都认
  • 同一批链接每次跑出来的死链数量不一样 ⚠️ - 第一次跑 3 死链 + 17 没能验证,第二次变成 2 + 16:变的是那条 baike.baidu.com/item/UDP/571511(并发 6 个请求打到同一家反爬站时它偶尔回 404;curl 与 deno 单独打都稳定 403)。这类看人下菜的回的码不能当成链接坏了 —— 所以有了 ANTI_CRAWL_HOSTS
  • 在 changelog 里写例子 URL 会被自己的死链检查抓 ⚠️ - 记录「新测试抓住了混进来的 ok.example 链接」之后,check-links 当场把那个 .example 域名报成死链(DNS 失败)。行内代码块拦不住(正则只是停在反引号前),要么反引号也不写 scheme,要么放进围栏代码块

下次建议(第二轮)

  • 两条站内 404 已在部署后复验为 200(Hugo 的 alias 页是 200 + meta refresh,死链脚本看的就是 200)
  • 剩下的都是「工作流不健康」那条线上的老账(见第一轮的下次建议):① 文件名与正文 hash 解耦(现在改正文就改 URL,只能靠 aliases 兜)② front matter 只留一份真相 ③ themes/sdttttt-paper/assets/js/*.js(1557 行)零测试 ④ 本地 git 身份是 github-actions[bot]。本次已与用户确认:四条都先不做,留档待议
  • check-dead-links.yml 的 push 触发保留(paths 收窄为 content/**、scripts/check-dead-links.ts、bin/check-links.sh、自身):内容改了顺手查一次外链,这次的两条站内 404 就是它抓出来的。只有每周 cron + 手动触发则为备选
  • ./bin/install-hooks.sh 按用户要求不装(不动本地 git config core.hooksPath);hooks 文件本身已在仓库里,需要时手动跑一次即可

第三轮(同日):把 themes/ 合并成单一主题

  • 触发:用户先纠正「我的主题是 themes/sdttttt-paper/ 不是 themes/hugo-paper/」,随后定调「@themes/ 只保留一个吧,我不打算和上游同步了」—— 即放弃「父主题 vendor-in + 子主题 override」的双层结构 ✅
  • 三个决定(ask_user_question 收敛):① 保留 sdttttt-paper 目录名(把 hugo-paper 独有文件 git mv 进来,7 个同名冲突留子主题现有版本);② 只搬站点真正需要的(layouts/ assets/ static/ i18n/ + theme.toml + LICENSE,丢掉 images/(2.5MB 截图) exampleSite/ bun.lock package.json postcss.config.mjs scripts/ go.mod 与父主题 README);③ 顺手清理全部选上(highlight.min.js + theme.png + 8 个社交图标 svg + custom.css 里失效的 @reference './app.css';)
  • 执行:git mv 31 个文件进 themes/sdttttt-paper/(assets/{app,main}.css、layouts/404.html、layouts/_default/single.html、layouts/partials/{head,math,mermaid}.html、layouts/shortcodes/collapse.html、static/theme.svg、LICENSE + 21 个 i18n/*.yaml),再 git rm -r themes/hugo-paper(54 个文件)→ themes/ 从 106 文件 / 3.06MB 变成 52 文件 / 384KB
  • 验证(这一步是整件事的关键):改动顺序刻意排成「先纯合并、验证零差异,再动注释和配置」——
    • 基线 hugo --minify -d /tmp/theme-refactor/before:608 个文件
    • 合并后 after-A:598 个文件,diff -r 只有 10 行 Only in before(就是那 10 个被授权的静态资源),没有任何一行 differ
    • 全部改完(模板注释 / 配置 / README / custom.css)后再构建 after-B,先剥 HTML 注释、再把 main.min.<64位hash>.css 与 integrity 归一化,diff 仍然只剩「10 个被删静态资源」+「CSS 文件名 hash 变了」两项。CSS 逐 token 比对过,差异只有 @reference './app.css'; 这一处
  • 配置与引用一次性收口:hugo.toml 的 theme = ["sdttttt-paper", "hugo-paper"] → theme = "sdttttt-paper";.prettierignore 删 themes/hugo-paper;deno.json 的 lint exclude 换成 themes/sdttttt-paper;AGENTS.md(开头段、子主题 bullet、themes/hugo-paper/ 目录条目、hugo.toml 描述、整节「主题同步分两部分」)、根 README.md、scripts/lib/frontmatter.ts、themes/sdttttt-paper/README.md(整篇重写成独立主题说明)、theme.toml 尾注、9 个模板文件头注释(统一改成 “upstream sync was dropped on 2026-10-07 … this file is now the only copy — edit it freely”)
  • 收益:部署体积 10,272KB → 10,180KB;删掉的 10 个静态资源合计 67,234 字节(highlight.min.js 48,833 / theme.png 7,991 / 8 个社交 svg 10,410);main.min.css 61,457 → 61,434 字节(少的就是那行 Tailwind 指令)
  • 构建:270 页 / 62 paginator / 11 static(原 21)/ 250 aliases,264ms,无 warning;./bin/preflight.sh 五步全绿

遇到的问题(第三轮)

  • 「sitemap 里 210 个 /posts/ loc」是自己数错的 ⚠️ - 一开始把 grep '/posts/' public/sitemap.xml | wc -l 得到的 210 当成文章数,据此去改 AGENTS.md 里那句「= 209 篇」。后来发现那 210 里有 1 条是 /posts/ 分区页本身;去掉它正好 209,与 public/searchindex.json(同一套 where site.RegularPages "Type" "in" site.Params.mainSections 过滤)的 209 条完全对上 → 原有的 209 是对的,改动已回滚。教训:同一个过滤条件在 sitemap / searchindex / 归档页三处都有产出,跨口径核对比盯着一个数字置信
  • theme list 是「叠加」不是「二选一」,引用父主题的路径不等于改了父主题 ⚠️ - 上一轮我引用 themes/hugo-paper/layouts/partials/head.html:99 说明 og:image 的管道,被读成「碰了不是你的主题」。实际上 theme = ["sdttttt-paper", "hugo-paper"] 让两个主题同时参与渲染,子主题没覆盖的文件本来就由父主题提供 —— 要改必须 fork 进子主题,我从没建议编辑父主题。教训:提到某个文件时要讲清它「由谁提供、渲染时归谁」,否则路径本身就会被当成所有权声明
  • @reference './app.css'; 是 Tailwind 的编译期指令,却混进了发布 CSS ⚠️ - Hugo 不跑 PostCSS(head.html 里没有 | postCSS),所以这行字面量一直躺在 main.min.css 里。删掉后 CSS 的 sha256 变了 → 所有 HTML 的 <link> 与 integrity 属性跟着变,做产物 diff 时必须把这两个都归一化,否则会看到 329 个「差异」
  • minify 后的 HTML 是一整行,diff 等于什么都看不见 ⚠️ - 第一次做规范化 diff 时 329 个文件全报「不同」,逐字节都看不出差在哪。解决办法是 perl -0pi -e 's/</\n</g' 先把标签拆成行再 diff —— 与上一轮「加 _index.md 会把标题清空」是同一类问题:只能靠改动前后各构建一次做对比
  • main.css 里还留着一处 url(./theme.png) ⚠️ - 来自非 monoDarkIcon 分支的 arbitrary utility .[background:url(./theme.png)_left_center/_auto_theme('spacing.6')_no-repeat];本站 monoDarkIcon = true,HTML 用的是 theme.svg 变体,这条规则永远匹配不到,所以删掉 theme.png 不会 404(已 grep 全部产物确认没有任何 HTML 引用它)

下次建议(第三轮)

  • themes/sdttttt-paper/assets/app.css 现在也成了「无人引用」的文件(它唯一的引用者就是刚删掉的 @reference 行)。它是 main.css 的 Tailwind 源码,留着能看出编译前的原貌;想更干净可以删
  • 上游 hugo-paper 的改动以后只能临时 clone 对比、手动挑(git clone --depth 1 … /tmp/hp-clone),不再有「sync 一次就够」的路径
  • 本次改动尚未提交(git status:31 rename + 54 delete + 16 modify),等确认后再推

第四轮(同日):主题改名 sdttttt-paper → self

  • 触发:用户说「主题的名字 不要叫做 sdttttt-paper 了,换成 “self”」✅
  • 执行:git mv themes/sdttttt-paper themes/self,然后把 19 个文件里的 sdttttt-paper 一律换成 self:
    • 目录与配置:hugo.toml(theme = "self" + 上面那段注释)、theme.toml(name / licenselink / description)、deno.json 的 lint exclude
    • 构建脚本:bin/lib.sh 的 WASM_ARTIFACT / WASM_MANIFEST 两行(bin/artifacts.sh 与 bin/build-wasm.sh 都靠它们,改路径只改这一处)、bin/build-wasm.sh 注释
    • 指纹文件:themes/self/assets/wasm/particles.sha256 第一行的路径 —— 产物哈希没变,所以不需要重编译 wasm
    • 文档:AGENTS.md(开头段 + 6 处路径)、根 README.md、themes/self/README.md、.gitignore 注释
    • 主题内注释:assets/custom.css、assets/js/search.js、layouts/index.json、layouts/_default/{baseof,list,search}.html、layouts/partials/{header,footer,bg}.html
  • 验证:改名前后各构建一次(598 文件 → 598 文件),diff -r 完全为空,产物逐字节一致。主题名不出现在任何发布产物里,理论上本就不该有差异;这一步是为了证明「没有哪个模板或资源是靠主题名拼路径的」。改名后全仓库(排除 content/changelog/ 的历史记录)已无 sdttttt-paper 残留
  • themes/self/README.md 的 History 节补了一行改名记录,并保留 2026-10-05 那行里的旧名(那是当时的历史事实)
  • theme.toml 的 description 从「sdttttt’s personal fork of hugo-paper」改成「The Hugo theme behind sdttttt.online (forked from hugo-paper)」
  • ./bin/preflight.sh 五步全绿、./bin/artifacts.sh check 通过

遇到的问题(第四轮)

  • themes/self/README.md 的表格又被 prettier 拦下 ⚠️ - 表头那一列从 `themes/sdttttt-paper/` 缩成 `themes/self/`,整列宽度跟着变,prettier 会重排对齐 → 跑一遍 format-markdown 即好。教训:这张表的列宽是 prettier 自动对齐的,改任何一个单元格都要跟着格式化一次
  • sdttttt-paper 有两类出现,不能无脑替换 ⚠️ - 一类是「当前的名字」(配置、注释、脚本变量),另一类是「历史记录」(content/changelog/* 里记录当时的状态、themes/self/README.md 的 History 节)。前者必须换,后者必须留 —— 所以替换时显式用 -g '!content/changelog/**' 排除整目录,README 的历史那行再手工改回

下次建议(第四轮)

  • themes/self/assets/app.css 依然是「无人引用」状态(见第三轮建议),要不要删仍未定
  • 主题现在叫 self(hugo.toml 里 theme = "self"),以后写文档提到它时统一用这个名字

第五轮(同日):砍掉不需要的功能(RSS / description / 死代码)

需求原文:「theme中有些我不需要的功能,就删除吧, 例如description, 还有RSS生成,我都不需要」。

完成的工作(第五轮)

  • RSS 全站关闭 ✅ — 关键点是只从 home 去掉 "RSS" 关不干净:Hugo 对 section / taxonomy / term 有自带的 RSS 默认值,/tags/*/index.xml、/changelog/index.xml 都是从那儿来的。所以 hugo.toml 的 [outputs] 现在写成 home = ["HTML", "JSON"] + 把 section / taxonomy / term 逐个钉成 ["HTML"]。效果:页面数 270 → 258(少掉的 12 个正好是 12 个 feed,线上那 ≈3.26MB 的订阅文件全部消失),find 确认产物里除 sitemap.xml 外没有任何 .xml
  • <meta name="description"> 删除 ✅ — 只删主题侧那两行(文章页取 .Summary、其余页取 site.Params.description)。225 篇 front matter 的 description 一个都没动:它喂的是 _internal/opengraph.html / twitter_cards.html / schema.html,实测产物里 og:description / twitter:description / itemprop=description 三处仍是那句手写描述,而 head.html 那行输出的才是 8162 字符的 .Summary。删掉 head 那两行后 .Summary 只剩搜索索引在用。head.html 与 hugo.toml 里都留了注释说明这件事,免得以后有人把 description 当成死字段一起删了
  • 评论 / 数学 / mermaid 删除 ✅ — single.html 的 Disqus / GraphComment / giscus / mermaid 四块(hugo.toml 里对应参数一个都没配过)、head.html 的 math partial 调用,以及 partials/math.html、partials/mermaid.html 两个文件。localKatex 分支引用的 katex.min.css / auto-render.min.js 本来就不在 static/ 里,等于这条路从来跑不通
  • highlight.js / shortcode / 死配置删除 ✅ — head.html 的 highlight.js loader(disableHLJS = true 一直关着它)、layouts/shortcodes/collapse.html(全站 0 次短代码调用,shortcodes/ 目录随之删空)、hugo.toml 的 enableInlineShortcodes 与 ignoreErrors
  • 社交图标导航整块删除 ✅ — 这一块从来就没能用过:baseof.html 的 social_params 列了 twitter / github / … 八个名字,header.html 按名字去拼 ./twitter.svg,但 themes/self/static/ 里只有 theme.svg,那些 SVG 一个都没 vendor 进来;而 hugo.toml 也没设过任何社交参数,所以它只会渲染成空盒子。它的 rss 分支还指向已经不存在的 /index.xml。删掉 social_list scratch + preload 循环 + nav
  • 瘦身 ✅ — i18n/ 从 21 个 yaml 砍到只剩 zh.yaml(站点是 zh-only,实际只查 prev_page / next_page 两个键);.prettierignore 删掉指向早就不存在的 themes/PaperMod 那行;scripts/validate-posts.ts 删掉 private 字段检查(0 篇在用,连测试一起删,单测 34 → 33 个)
  • 文档同步 ✅ — themes/self/README.md(把 head.html / single.html 补进「我们自己维护」的表、修掉那一行已经过期的「head.html is left untouched」、新增 2026-10-07 删除清单与「RSS 怎么恢复」两段)与 AGENTS.md(主题描述里的文件清单、hugo.toml 条目、front matter description 的说明)
  • 验证 ✅ — hugo --minify 258 页 / 62 paginator / 250 aliases,211ms;./bin/preflight.sh 五步全绿;deno task lint 干净;抽查产物 <head> 已无 meta description、无 RSS <link rel="alternate">,og:description / twitter:description / itemprop=description 仍在

遇到的问题(第五轮)

  • 构建当场被自己的 changelog 文案搞挂了 ⚠️ - 日志里写了「全站 0 次」+ 短代码开始标记(双花括号加尖括号)这样一句,Hugo 会把它当 shortcode 开头解析,直接 ERROR error building site: ... unrecognized character in shortcode action: U+0060 '\’。**而 ./bin/preflight.sh五步全绿** —— 印证了第三轮就列出的那条:preflight 不跑hugo`,内容/模板层面的错要等到 CI 部署那一步才爆。在正文里提到 Hugo 短代码语法时别原样写那两个字符,或改用代码块 + 转义形式
  • site.Params.description 并不是死配置,差点误删 ⚠️ - 原本以为删了 head.html 那行后它就没用了,于是问卷里把「删 hugo.toml 的 description 参数」也打包进去了。实际一构建才发现:Hugo 内建的 _internal/opengraph.html / twitter_cards.html 会回退到 site.Params.description,首页 / 标签页 / 归档页这类没有 front matter description 的页面全靠它拿 og:description。删掉后对比旧产物:这三个页面从有描述变成完全没描述。已把参数加回来(它现在只喂分享卡片,不再生成 <meta name="description">),并在 hugo.toml 注释里写明原因。教训:「主题里没引用」≠「没人引用」 —— Hugo 的 _internal/* 模板也是消费者,删配置前要看产物 diff
  • 改 README 表格必然触发 prettier 重排 ⚠️ - 第四轮已经踩过一次,这次又踩:新插的两行单元格宽度和别的行不一样,prettier 会把整张表按最长单元格重排 → 跑一遍 deno task format-markdown 即好
  • grep 在产物里搜到 name=description / mermaid 不代表没删干净 ⚠️ - 命中的两处都在 content/changelog/ 的历史正文里(那些日志本身在讨论这件事),确认时要带上下文看,别只看 grep -l
  • 删 RSS 的连锁面比想象中广 ⚠️ - 除了 [outputs] 与 head.html 的 AlternativeOutputFormats 循环,还有 header.html 里 rss 社交项的 index.xml 硬编码。bin/*.sh、.github/workflows/*.yml、scripts/*.ts 里确实没有任何 index.xml 引用,所以脚本层不用动

下次建议(第五轮)

  • bin/preflight.sh 该加一步「hugo --minify -d <tmpdir>」—— 这一轮它拦不住的东西(短代码标记写法、模板语法错)只有构建能发现,而它现在跑到第五步全绿、下一步就是 CI 部署
  • themes/self/assets/app.css 还是「无人引用」的 Tailwind 源文件(连带 main.css 这份 61KB 构建产物也脱管),第五轮依然没结论 —— 删还是接回构建,需要明确决定
  • 剩下的优化项(探索时列过、这轮没做):pt-wasm.js:59 会把 rejected 的 compile promise 永久缓存住;徽标的待机 float 每帧都在整块 putImageData

第六轮(同日):徽标透明度 —— 只留一个旋钮,方向先做反了一次

完成的工作(第六轮)

  • 徽标透明度收成一个变量 ✅ —— 原先三处各写一遍:html.at-bottom .page-bg__box 的 opacity: 0.85、prefers-reduced-motion 块里的 0.7、无 JS 兜底的 0.85。现在 :root { --page-bg-opacity: 1 },html.at-bottom / html:not(.js) / prefers-reduced-motion 四处统一 opacity: var(--page-bg-opacity) —— 亮色暗色共用一份值(用户明确要求「亮色也降低,不需要维护两份」)✅
  • 删掉暗色专属的压亮滤镜 ✅ —— 修好死选择器之后它反而让暗色更淡,与诉求相反,直接删掉;暗色现在与亮色共用 .page-bg__box 的基础处理 ✅
  • 顺手修掉一条从来没生效过的暗色规则 ✅ —— [data-theme="dark"] .pt-stage { … } 是死代码:本主题的暗色是 partials/header.html:62 往 <html> 挂 dark 类(htmlClass[isDark ? 'add' : 'remove']('dark')),全仓库没有任何地方写过 data-theme 属性。改成 html.dark .pt-stage 后粒子演示页的暗色处理才第一次生效 ✅

遇到的问题(第六轮)

  • 「降低透明度」被我按 CSS opacity 的字面方向做反了 ⚠️ - 用户说的是「暗色下显示不太好,透明度降低一些」= 要更实(更不透明),我却把 opacity 从 0.85 降到 0.6,还给暗色叠了一层 brightness(0.9) saturate(0.85) blur(0.3px),结果用户一眼看出「更淡了」。教训:中文「透明度」是双向词(「提高」= 更透 / 「降低」= 更实),遇到它先确认「要更实还是更淡」再动手 —— 方向错一次就是整轮往返 ✅
  • 「按模式各写一份」是伪需求 ⚠️ - 第一版写了「暗色专属」的 opacity 规则,还顺手踩了优先级:html.dark .page-bg__box 与 html.at-bottom .page-bg__box 都是 (0,2,1),只能靠「写在后面」取胜,得显式写成 html.dark.at-bottom … 才稳。改用共享的 CSS 变量后这类跨档覆盖全都不需要了 ✅
  • [data-theme="dark"] 这种「看着合理」的选择器不会报错、只会静默失效 ⚠️ - 它既不在 linter 视野里,也不会在构建时报警;只能靠「谁在写这个属性」反查(rg data-theme 全仓库只有 CSS 自己两处命中)才能发现。写暗色规则前先确认本主题用的是类还是属性 ✅

验证结果(第六轮)

  • hugo --minify 0 报错;产物 CSS(head.html:34 是 main.css + custom.css → concat → minify → fingerprint)实测含 :root{…--page-bg-opacity:1}、opacity:var(--page-bg-opacity) ×4,html.dark.at-bottom 与 html.dark .page-bg__box{filter:…} 两条均已消失,html.dark .pt-stage{…} 生效 ✅
  • ./bin/preflight.sh 五步全绿(33 个单测)、bunx prettier@3.9.6 --check content/changelog/*.md 通过 ✅

第七轮(同日):顶栏加 Search 菜单

完成的工作(第七轮)

  • 顶栏加站内搜索入口 ✅ —— 只改 hugo.toml:新增一条 [[menu.main]](identifier = "search"、name = "Search"、url = "/search/"、weight = 3),原 Source 的 weight 从 3 顺延到 4,导航顺序变成 Posts → Archive → Search → Source → About。模板不用动:themes/self/layouts/partials/header.html 直接 range site.Menus.main(移动端弹的是同一份列表的全屏抽屉),所以加菜单项 = 加一条菜单配置 ✅
  • 标签统一用英文 Search,与既有的 Posts / Archive / Source / About 一致(页面内标题仍是 content/search.md 的中文「搜索」)✅
  • 实测首页 / /archives/ / /search/ / 文章页四类页面的 <nav> 都渲染出五条入口且顺序一致;/search/ 页本身的 autofocus 输入框、/searchindex.json(267,503 字节)均正常 ✅

遇到的问题(第七轮)

  • 「少了 12 页」虚惊一场 ⚠️ - 顺手对比构建摘要时发现 Pages 从 270 掉到 258(而 Aliases 反而 245 → 250),一度怀疑有文章丢了。实际上是这几轮之间的 c935ab8 refactor(theme): 删除 RSS 生成与一批死功能:[outputs] 不再给 home / section / taxonomy / term 出 RSS,270 − 258 = 12 正好就是那些 RSS 输出。文章数没变(content/posts 226 篇)✅ —— 教训:hugo 摘要里的 Pages 包含 RSS / 分页等输出,跨提交比数字前先看清中间有没有动过 [outputs]

验证结果(第七轮)

  • ./bin/build.sh 0 报错,Pages 258 / Aliases 250;./bin/preflight.sh 五步全绿(33 个单测 / 150 steps)✅
  • 顺手确认了 themes/self/layouts/robots.txt(Allow: /)与 public/sitemap.xml:/search/ 本来就在站点地图里,这次上导航不需要同步放宽任何抓取规则 ✅

第八轮(同日):把一篇私人文章从所有列表里摘出去

完成的工作(第八轮)

  • 「今天是二零二六年十月二日」(写爷爷那篇)转为「私密文章」 ✅ —— 按仓库既有惯例(意义 / 关于恋爱观 / 我所寄托的情感 / 自述-小学时期)在 front matter 加:
    1build:
    2  list: never
    3  render: true
    
    没选 draft: true:draft 会让整篇不构建、直接链接也 404;list: never + render: true 只把它从所有列表里摘掉(首页、分页、归档、标签、搜索索引、sitemap),知道链接的人仍能打开。改前专门问过用户,用户明确选后者 ✅
  • 实测(rm -rf public 后重建):页面本身仍在(public/posts/20260921-今天是二零二六年十月二日-141g/index.html,8,668 字节);首页 / page/2 / page/3 / /archives/ / /tags/ / searchindex.json / sitemap.xml 全部 0 命中;归档页计数 209 → 208 篇(线上 209、改后本地 208,对照确认)✅
  • 对照组「今天是二零二六年九月二十一日」(同一天发的另一篇,不含私事)仍在首页与搜索索引里,未被误伤 ✅
  • front matter 改了但文件名没变(hash 只取自正文):preflight ① 文章文件名 直接通过,没有触发改名、也没动 URL ✅

遇到的问题(第八轮)

  • 「草稿」有两种含义,仓库里两种用法都真实存在 ⚠️ - draft: true(AI编程 / Paxos算法 / 程序的内部分段 等)与 build.list: never(那几篇私人文章)都有人用,但效果差很远(前者链接 404、后者链接仍活)。先问清再动手,省掉一次「发布后才发现链接挂了 / 还挂着」的往返 ✅

验证结果(第八轮)

  • ./bin/build.sh 0 报错,Pages 258 / Aliases 250;./bin/preflight.sh 五步全绿(33 个单测 / 149 steps);deno task format-markdown-check 通过 ✅

下次建议(第八轮)

  • 以后再有「不想公开但想留档」的文章,照第八轮的做法加 build.list: never + render: true 即可,别用 draft(会连链接一起弄丢)✅

第九轮(同日):清掉 themes/self/assets/ 里指向已删页面的死 CSS

完成的工作(第九轮)

  • 扫描口径:写了一个一次性脚本(/tmp/scan_css.py,已删)—— 括号/引号感知地解析 themes/self/assets/main.css,抽出每个选择器的主类 token,再与语料(public/**/*.html|xml|json|txt + themes/self/layouts/** + content/** + assets/js/** + static/** + hugo.toml)比对,列出「CSS 里有、源码/产物里从不出现」的类 ✅
  • 删了 27 个选择器 + @keyframes spin + --animate-spin 变量声明(main.css 选择器 337 → 310,只减不增;:root 唯一变化就是少了 --animate-spin):
    • 11 个来自已删除的社交图标导航(header.html 那块在 c935ab8 被删):.lg\:mt-0、.ltr\:lg\:ml-14、.rtl\:lg\:mr-14、.h-7、.w-7、.lg\:h-6、.lg\:w-6、.\[\&_svg\]\:m-auto ... svg、.\[\&_svg\]\:block ... svg、.\[background\:var\(--url\)_center_center\/cover_no-repeat\]、.hover\:animate-spin;
    • 13 个来自上游 exampleSite / 已删内容:.invisible、.visible、.mx-6、.mt-24\!、.truncate、.border-\[0\.5px\]、.border-black\/10、.bg-black\/5\!、.bg-white\/50、.p-3、.outline、.dark\:bg-black\/80\!、.dark\:bg-white\/90\!(含 5 个连带清空的 @supports (color:color-mix(...)) 块)
  • monoDarkIcon 这条遗留开关整条清掉(用户问过、选「彻底清」)✅:header.html 硬编码 theme.svg 那套 class;head.html 的 $dark_icon 条件改成固定的 theme.svg preload;hugo.toml 删掉 [params] monoDarkIcon = true 与两行注释;themes/self/README.md 里那行说明改成「2026-10-07 起 monoDarkIcon 与 theme.png 已删除,这是唯一图标」。顺带删掉它的两条配套死规则 .\[background\:url(\.\/theme\.png)...\] 与 .\[transition\:_background-position_0\.4s_steps\(5\)\] —— theme.png(7,991 B)在合并进 themes/self/ 时已被删,开关又固定 true,else 分支永不渲染(已 grep 全部产物确认)
  • custom.css 与 5 个 JS 都是零死代码,未动 ✅:page-bg.js / pt-wasm.js / search.js 分别由 bg.html / search.html 引用,particles-wasm.js + particles.js 由 particles.html 引用(后者是运行时动态注入的 Canvas 2D 降级引擎,页面只是 draft: true 而非被删);JS 里所有 querySelector 目标(.page-bg__box/__canvas/__png、pt-bg-config、pt-config、pt-canvas、search-*)在 layouts 里都存在;giscus / comment / katex / mermaid / hljs / social / rss / disqus / twitter / mastodon 等关键词全库 0 命中
  • 收益:main.css 源文件 62,025 → 58,004 字节(-6.5%);hugo --minify 产物 61,447 → 57,922 字节(-3,525 B / -5.7%)

遇到的问题(第九轮)

  • 第一版删除脚本漏了开括号 ⚠️ - res += sel + body + '}' 写成了没有 '{',输出 436 个 } 却只有 1 个 {。教训:批量改 CSS 后必须校验括号数与「选择器集合只减不增」,光看字节数看不出来 ✅
  • .visible 差点漏掉 ⚠️ - 扫描语料里若混入 assets/js,particles*.js 里的局部变量 visible 会让「字符串包含」判据误判成「有用」。改成按 class token 集合比对后浮出水面,再用 ['\"]visible['\"] + classList.* 反查确认没有任何 JS 动态加这个类,才敢删 ✅
  • README.md 表格改措辞后 prettier 报错 ⚠️ - markdown 表格要按最长单元格重新对齐,直接 --write 会让整张表 23 行全被重排。改成把新单元格裁到原宽度(381 字符)再补空格 → 只动 1 行。preflight ② 当时就是这么红的 ✅

验证结果(第九轮)

  • ./bin/preflight.sh 五步全绿(33 passed / 149 steps)✅;hugo --minify exit 0(258 pages,无报错)
  • 产物核对:新的 main.min.*.css 里 theme.png / steps(5) / visibility:visible 全部 0 命中,theme.svg 规则仍在;public/index.html 渲出的深色按钮 class 与清理前逐字一致([background:url(./theme.svg)_left_center/cover_no-repeat] dark:invert dark:[background-position:right]),preload 仍是 theme.svg;全部非 changelog 页面里 theme.png 引用数 = 0(只有 10-05 / 10-07 两篇维护日志的正文文字提到它)
  • 0 个「改了样式却没同步」的漏网:扫描脚本重跑后 UNUSED: 0

下次建议(第九轮)

  • 再删主题里的整块功能时,顺手跑一遍这套 token 扫描(抽选择器主类 token → 与 public/**/*.html + layouts + content + assets/js 求差集),比逐个 grep 靠谱
  • assets/ 侧已确认无死代码。若要继续瘦身,下一个候选是 21 个无 var() 引用的 --tw-* 孤儿变量(--tw-ring-shadow / --tw-shadow-color / --tw-drop-shadow-* / --tw-outline-style / --tw-translate-z / --tw-duration …):它们是 Tailwind 的 @property + *,::before,::after,::backdrop 初始化层按组发射的,.prose kbd:has(kbd)(来自 app.css 的 @apply shadow-none)与 .filter 仍引用了一部分,收益只有几百字节、风险中等,本次未动

第十轮(同日):把 Tailwind 管线 vendor 回仓库,main.css 从「手删产物」换成「重编译产物」

完成的工作(第十轮)

  • 重编译跑通且可复现 ✅:上游的三个构建配置从我们自己的 git 历史里找回(git show e6f0a2e:themes/hugo-paper/{package.json,bun.lock,postcss.config.mjs},cf620fe 合并主题时删掉的)。本机 bun 1.3.14,bun install --frozen-lockfile 装出与当初完全一致的版本(tailwindcss 4.1.18 / @tailwindcss/postcss 4.1.18 / @tailwindcss/typography 0.5.19 / postcss 8.5.6 / postcss-cli 11.0.1 / postcss-preset-env 11.1.2 / autoprefixer 10.4.23,179 包),postcss assets/app.css -o assets/main.css(cwd = 主题根)产出 57,943 B / 1690 行 / 313 选择器,连跑两次逐字节一致(sha256 664872659995620d1e0aec658d5c015932c6c38d34c5fe41011eb69f5a2aefff)
  • 采纳重编译产物 ✅:themes/self/assets/main.css 从第九轮手删版(bd91385f…)换成重编译产物 —— 比 HEAD 少 30 条规则,其中 27 条正是第九轮手删的,另外 .container / .contents / .shrink / .table / :where(.space-x-10 > :not(:last-child)) 是上游 exampleSite 留下的自繁殖化石,也一并消失
  • 顺手补上两条真实缺失的规则 ✅:.mb-10(themes/self/layouts/_default/particles.html:39)与 .text-sm(同文件 :42)在模板里真的在用,却从来没有被编译进产物(HEAD 与第九轮手删版都缺);重编译后自动出现(该页 draft: true,只影响本地 hugo server -D)
  • 零回归验证 ✅:从 public/**/*.html 的 class="…" 与 assets/js 的 classList.* 抽出 202 个真实 class token,逐个查规则 —— 新产物里「缺规则」的 60 个全部由 assets/custom.css 提供(arch* / btn-dark / img-lost* / is-active / js / at-bottom / language-* …)或本来就不是 Tailwind 类;「重编译缺、HEAD 却有规则」= 空集
  • 管线 vendor 回仓库 ✅:themes/self/{package.json,bun.lock,postcss.config.mjs}(bun.lock 与 postcss.config.mjs 逐字照搬上游;package.json 只改 name/private/description 并把 scripts 收成一条 build:css,devDependencies 原样保留,因为 lockfile 里记着这一组、删掉就要重写 lockfile)+ deno task build-css(= bin/build-css.sh:bun install --frozen-lockfile → postcss → artifacts.sh stamp-css)+ 产物指纹 themes/self/assets/main.css.sha256(30 条 = 产物 + 主题内被扫描的 29 个文件)
  • bin/artifacts.sh 加了第 ③ 项 check_css ✅:与 wasm 同款(CI 不装 bun,靠指纹发现「改了源码没重编译」);check --rebuild 在有 bun + node_modules 时会把 CSS 重编译到临时目录逐字节比对;build-wasm.sh 改调新名 stamp-wasm(旧名 stamp 保留);CSS 路径集中在 bin/lib.sh
  • 实测扫描范围就是主题目录 ✅:往仓库根丢一个带 flex-row-reverse 的探针文件,产物里 0 命中;同一个类写进 themes/self/layouts/** 则立刻命中 —— 所以指纹取「整个 themes/self/」是正好够用的范围
  • 文档同步 ✅:AGENTS.md(主题清单加 Tailwind 管线那一行 + 扫描范围警告、命令表、bin/ 清单、preflight ⑤ 口径、编码规范、推送前检查)、themes/self/README.md 新增「The Tailwind pipeline」段与 History 一行

遇到的问题(第十轮)

  • 不钉死 lockfile 就编不出同一份产物 ⚠️ - 第一次图省事只装了 6 个直接依赖(166 包),产物 57,903 B,与钉住 lockfile 的 57,943 B 差 40 字节,diff 出来是 initial-value: 0 0 #0000 vs rgba(0,0,0,0)。原因:postcss-preset-env 的传递依赖 @csstools/* 被重新解析到了更新的 patch 版本。结论:bun.lock 必须原样 vendor + 永远 --frozen-lockfile,连用不上的 prettier devDeps 也一起留着 ✅
  • 「重编译」并不能自动洗掉历史沉积 ⚠️ - Tailwind v4 的扫描根就是编译时的 cwd(主题根),上一版 main.css 自己也在扫描范围内,所以旧产物里的类会被重新发射(exampleSite/ 删了那么久,它的类还活着就是这个机制);实测主题根之外(仓库根 _tw_probe.html)的文件不影响产物,主题内新增文件则立刻影响 —— 指纹范围因此取「整个 themes/self/ 减去 node_modules / assets/wasm / 产物自身 / 指纹自身」✅
  • 边扫边写会不会抖动 ⚠️ - postcss -o assets/main.css 的输出正是下一次的扫描输入,先验证过:就地连跑两次字节一致,且「就地编译」与「编译到 /tmp」结果相同,所以指纹里放产物自身是安全的 ✅
  • README 里写什么词会被编译进去 ⚠️ - 这轮自己踩了一次:themes/self/README.md 新写的说明里带上了字面量 dark-bg(app.css 里 @utility dark-bg 的名字),重编译后 main.css 从 57,943 → 58,801 字节,diff 只有一行 —— .dark-bg:where(.dark,.dark *) 多背了一层 :not(#\#) 特异性 bumpers(1 → 4)。把那句话改成「the dark-mode utility」后逐字节复原(sha256 回到 664872659995620d1e0aec658d5c015932c6c38d34c5fe41011eb69f5a2aefff)。同时验证过收敛性:在 README 里留着这个词连跑 3 次,输出稳定不变(不会每跑一次再涨一层)✅

验证结果(第十轮)

  • deno task build-css 在仓库里跑通,产物 sha256 与重编译前完全一致(幂等可反复跑)✅
  • ./bin/artifacts.sh check --rebuild 全绿:cargo 重编译 wasm 逐字节一致 + bun 重编译 CSS 逐字节一致 ✅
  • 负例都拦得住:往主题里塞一个新文件、或手改产物 → check 立刻报「Tailwind 产物与源码不一致」并提示跑 deno task build-css;恢复后转绿 ✅
  • ./bin/preflight.sh 五步全绿;hugo --minify exit 0 ✅
  • CI 侧无改动(deploy.yml 不装 bun):陈旧产物由 preflight ⑤ 的指纹检查拦住

下次建议(第十轮)

  • 以后改样式只改 themes/self/assets/app.css(站点自有样式仍写 assets/custom.css),别再手改 main.css;推送前 deno task build-css,产物与 main.css.sha256 一起提交
  • 真要升级 Tailwind(换 bun.lock)时必须当成一次「样式回归」来验:重编译后与旧产物对选择器集合 + 用真实 class token 查一遍规则
  • themes/self/node_modules/ 已被 .gitignore 覆盖(含 node_modules/ 通配),不必额外加规则