SDTTTTT

2026-10-06

维护记录

完成的工作

  • 标定左下角粒子徽标的密度 / 清晰度上限,并按实测结果调参 $cfg ✅
    • 改动文件:themes/sdttttt-paper/layouts/partials/bg.html($cfg 数值 + 上方新增实测标定注释)、themes/sdttttt-paper/assets/js/page-bg.js(GRAIN 的说明注释,逻辑未动)
    • 参数变化:pitchCss 2 → 1.2、maxParticles 60000 → 200000、sizeRatio 0.85 → 0.95、grain true → false、dprCap 1.5 → 2
    • 效果:step 5 → 3(每 3 个源像素采一颗),粒子数 19,849 → 55,103(×2.8),覆盖率 24.6% → 38.4%
    • 只改 $cfg,没有重跑 deno task build-wasm —— 所有参数都是运行时传进 wasm 的,themes/sdttttt-paper/assets/wasm/particles.wasm 不需要重建
  • 测试台(/tmp/pt-lab/,跑完已删):用 Deno 直接驱动 particles.wasm(alloc → 写 rgba → build → settle,读 fb_ptr 存 PNG),跑了 1344 组参数矩阵 × 3 张 bg 图 × 5 种视口宽度 × 3 种 dpr,输出 particle_count / sample_step / particle_size / 覆盖率 / wasm 内存 / build 与 settle 耗时

实测出的三条机制(都验证过)

  1. step = round(pitchCss × 源图宽 / 画布CSS宽),与 dpr 完全无关 —— dpr 在 scale 与 pitchDev 里同时出现被约掉了。pitchCss 2 在 800px 源图 / 320px 画布下就是 round(2 × 800/320) = 5。pitchCss 实际被量化成阶梯:0.5–0.9→step2、1.0–1.3→step3、1.5–1.7→step4、1.8–2.2→step5
  2. dprCap 不参与密度计算,只决定 sizePx 的取整粒度与光栅锐度:size_css ≈ step × 0.4 × ratio,dpr 只影响它被 floor / round 到哪个整数。所以把 dprCap 从 1.5 提到 2(其余不动)时 step 和粒子数完全不变,只是 size 从 2 变 3 → 覆盖率 24.6% → 31.2%
  3. 真正的密度硬上限在 Rust 侧:wasm/particles/src/lib.rs 里 let cap = max_particles.clamp(200, 400_000)。首图 F_tZfZBbwAALItU.png 在 step1 需要 496,142 个不透明源像素 > 400,000,所以最少只能到 step 2。用 pitchCss 0.2 配 maxParticles 400k / 500k / 900k 各跑一遍都仍然卡在 step2 / 124,008 粒子

关键实测数据(单进程独立跑,避免 wasm 堆高水位污染)

配置stepsizePx粒子数覆盖率wasm 内存buildsettle
改前(pitch2/r.85/dpr1.5)52 (1.33css)19,84924.6%9.88MB1.3ms0.5ms
仅 dprCap→253 (1.50css)19,84931.2%10.88MB1.3ms0.6ms
改后(本次采用)32 (1.00css)55,10338.4%12.13MB1.9ms1.2ms
密度极限(pitch0.9)22 (1.00css)124,00855.7%14.31MB2.8ms2.5ms
  • 换图 / 换视口的稳定性(改后配置,dpr 2 下 170–320px 全宽度 size 恒为 1.00 CSS px):
    • F_tZfZBbwAALItU.png step3 / 55,103 粒子 / 覆盖率 38.4%
    • FxC7q1YaUAE8SOL.png step3 / 35,891 粒子 / 覆盖率 25.0%
    • GiG69PDa8AAvoeS.png step3 / 25,666 粒子 / 覆盖率 33.9%
  • 触发浏览器里的真实参数(hugo --minify 产物 public/index.html 里 #pt-bg-config)已核对为 {"dprCap":2,"fitH":1,"fitW":1,"grain":false,"maxParticles":2e5,"pitchCss":1.2,"sizeRatio":0.95}
  • 验证:hugo --minify 通过(265 页)、deno task test 通过(28/28)

遇到的问题

  • grain: true(原来的值)在低 dpr 下会自己把画面搞虚 ⚠️ - 源码里 grain 为真走 floor,会把 size 压到 1 设备像素,也就是 0.5 CSS px,浏览器把画布下采样到 CSS 尺寸后这些点会被摊薄、整块发白。实测 pitchCss 0.9 + ratio 0.85 + grain true → size 1(0.50css)、覆盖率只有 21.6%;同参数换成 ratio 0.95 + grain false(走 round)就能稳定拿到 1.00 CSS px、覆盖率 55.7%。这是本次把 grain 改成 false 的直接原因
  • 原配置在窄视口会塌方 ⚠️ - ratio 0.85 + grain true 在 cssW 220px 时 size 掉到 1 设备像素(0.50css),覆盖率只剩 11.4%。改成 0.95 + round 后 170–320px 全宽度都守住 1.00 CSS px
  • dprCap 不是越大越好 ⚠️ - dpr3 下同样是 step2,但 size 仍被 round 到 2 → 0.67 CSS px,覆盖率反而从 55.7% 掉回 38.4%。2 才是最优点,所以 dprCap 定在 2
  • 另外两张 bg 图其实能到 step1 ⚠️ - FxC7q1YaUAE8SOL.png 323,022 / GiG69PDa8AAvoeS.png 230,964 个不透明像素都没超过 400,000 硬上限,step1 可达;但那时 size 只能给到 1 设备像素(0.50css),视觉上反而比 step2 更虚,所以没有为了这两张图去改 Rust 里的 clamp(200, 400_000)
  • 测试台里 sharp 返回的 Buffer 必须显式拷贝(new Uint8Array(raw.byteLength) 再 set(new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength))),直接把 raw.buffer 交给 wasm 会报 RuntimeError: memory access out of bounds ⚠️ - sharp 用的是池化内存(byteOffset != 0),必须按 offset/length 重新拷一份

下次建议

  • 想再往上加密度只剩「改 Rust 硬上限 + 重建 wasm」一条路,而且 step1 的 size 会掉到 0.5 CSS px,性价比很低;当前 step3 已经是「保留颗粒缝隙」前提下的实用最优
  • 粒子密度旋钮以后只动 pitchCss(阶梯量化成 step),清晰度只动 dprCap(上限 2),别指望 maxParticles 能改密度 —— 它只是 step 搜索的上限
  • 若要给不同视口都锁定同一个 step,可以在 page-bg.js 里把 pitch 改成视口相对量(pitchCss = step × cssW / iw),现在是固定的 CSS px,所以 step 会随宽度在 3–6 之间漂
  • 本次只改了 $cfg 与注释,没有 commit / push;下次若要上线记得写进 commit message(建议 feat(bg): 提高徽标粒子密度与清晰度)

维护记录(续)

完成的工作

  • 按用户要求把粒子数压到 3w–4w 量级:maxParticles 200000 → 40000 ✅
    • 只动了 themes/sdttttt-paper/layouts/partials/bg.html 的一个数字 + 对应的注释(pitchCss / sizeRatio / grain / dprCap 都不变)
    • 机制:maxParticles 是粒子预算 —— Rust 侧 count_opaque(step) > 预算 就把 step 往上推一位。首图 step3 是 55,103 > 40,000,所以被推到 step4 = 31,025 粒子
    • 实测(首图 F_tZfZBbwAALItU.png,dpr2 / cssW 320 / 单进程独立跑):
maxParticlesstepsizePx粒子数覆盖率buildsettlewasm 内存
200000(改前)32 (1.00css)55,10338.4%1.50ms1.26ms12.13MB
40000(改后)43 (1.50css)31,02548.7%1.25ms0.91ms11.00MB
  • 换图后粒子数(dpr2 / cssW 320):F_tZfZBbwAALItU 31,025 / FxC7q1YaUAE8SOL 35,891 / GiG69PDa8AAvoeS 25,666,都落在 3w–4w 量级 ✅
  • 验证:hugo --minify 通过、deno task test 通过(28/28)、产物 #pt-bg-config 里 "maxParticles":4e4 已核对
  • 对比图(源图 / 55k / 31k)出在 /tmp/pt-lab2/out/cmp-zoom.png,看完随测试台一起删

遇到的问题

  • maxParticles 不能设太小 ⚠️ - 设成 30000 时 step 会从 3 直接跳到 5(step4 是 31,025 > 30,000),粒子数反而掉到 19,849、size 涨到 2.00 CSS px,比 40000 更差。安全下限是 31,025(也就是刚好容下 step4),取 40000 留一点余量
  • 压粒子数必然让粒子变大 ⚠️ - size 是 step × scale × sizeRatio,step 从 3 涨到 4 就意味着网格变粗、边长从 1.00 涨到 1.50 CSS px;想「粒子变少但边长不变」只能把 sizeRatio 降到 0.6,实测覆盖率会掉到 21.6%、画面明显发虚,所以没走这条路
  • 收益其实很小(1.1MB 内存、build 1.5ms → 1.25ms),视觉损失却很明显(细网格 → 粗块状)⚠️ - 如果之后觉得画面变糙了,把 maxParticles 改回 100000 以上就能回到 step3 / 55,103 粒子的细网格

下次建议

  • maxParticles 现在是「粒子预算」而不是「保险丝」,改它会直接改视觉密度:< 31,025 会跳到 step5(更粗),≥ 55,103 才回到 step3(更细);中间是 step4 的死区
  • 配套的可视化测试台已在 /tmp/pt-lab2/(sweep2.ts 驱动 wasm、montage2.ts 拼对比图),需要时可以直接重建

互动特效(方案 6:飞入 → 落地 → 呼吸)

完成的工作

  • 给左下角徽标接上「活过来」的三段动效,并完成实测标定与接线 ✅
    • wasm/particles/src/lib.rs — 新增交互力区:burst(x, y, radius, power)(一次性径向冲量,线性衰减到半径处归零)、pulse(amount)(绕画布中心的整体缩放冲量)、max_offset()(诊断用:全体粒子离目标位置的最大距离)
    • themes/sdttttt-paper/assets/js/page-bg.js — 新增 rAF 状态机 land → thump → idle:land 靠 tick() 的弹簧阻尼把 build() 随机撒开的粒子收拢(飞入);落定瞬间 burst(canvas.width/2, canvas.height/2, max(w,h), 1.4)(落地顿一下);之后长期用正弦包络驱动 pulse()(待机呼吸)。同时拆出 blit()(贴帧)/ draw()(立刻吸附,用于 resize / 减少动态效果 / 双击切回)
    • themes/sdttttt-paper/layouts/partials/bg.html — $cfg 新增三个旋钮 thumpPower 1.4 / breathPeak 0.5 / breathPeriod 4000,并把标定结论写进注释
  • 动效三重闸(motionAllowed()):html.at-bottom(徽标已揭示)+ 文档在前台 + 没切成真实图片;prefers-reduced-motion: reduce 时直接 settle() 出成品,一帧都不动;旧 wasm 缺 tick/burst/pulse 时退化成静态粒子而不是报错
  • 实测数据(首图 F_tZfZBbwAALItU.png,dpr2 / cssW 320 / pitch 2.4 / cap 40000,与线上完全同参):
阶段帧数耗时峰值位移备注
land961.60s1226px → 0px弹簧自动收拢,无需参数
thump400.67s3.45px(≈1.4css)burst power 1.4
idle长期周期4s±5.7px(≈1% 缩放)pulse peak 0.5,0.90ms/帧
  • wasm 体积:23011 → 24706 字节(+1.7KB,含 burst / pulse / max_offset),仍在「滚到页底才下载」的按需范围内

遇到的问题

  • 竖直行波会把粒子格子拍成摩尔纹 ⚠️ - 最初用 breathe(amount, phase_step) 做「沿 y 的行波」,在降采样总览图上看到严重横条纹。1:1(不降采样)复核后发现条纹是 sharp 用 nearest 做 640→200 的非整数降采样自己造出来的假象,行波本身在 1px 静位移下是干净的 —— 但继续加大到 5px 后 1:1 下头发上真的浮出横竖条纹,而 1px 时又完全看不出来,可用区间近乎为零。根因是格子间距 3.2px 与粒子边长 3px 几乎相等(已经快拼满),任何让相邻两行产生相对位移的力都会干涉。改成绕中心整体缩放的 pulse() 后彻底解决 —— 仿射变换下格子只被等比放大缩小,结构上不可能出干涉纹。顺带删掉了 breathe 与为它写的 Bhaskara fast_sin(省回 711 字节)
  • land → thump → idle 换档那一帧循环会自停 ⚠️ - 原写法在 phase = 'idle' 的同时把 busy 留成 false,于是 requestAnimationFrame 不再排下一帧,呼吸一帧都跑不出来。把 tick() 收敛成「每帧只调一次」,换档移到帧尾,并让 idle 档在 BREATH_PEAK > 0 时无条件 busy = true
  • 没有 Chromium / Playwright,没法直接开浏览器验收 ⚠️ - 改为把生产用的 page-bg.js 原文放进 Deno 的 DOM stub(document / canvas.getContext / Image / ImageData / rAF 全打桩)+ 真 particles.wasm + 从 public/index.html 里抓的真 $cfg 跑端到端:实测 burst(320,448,896,1.4) @tick96、pulse 从 @tick136 起、240 帧恰好 240 次 pulse(4s 周期正确)、滚离页底 / 切后台 / 双击切图三条路径都能把 rAF 停到 0。上面那个自停 bug 就是它抓出来的

下次建议

  • 动效参数都已进 $cfg,现场调只需改 bg.html(不需要重跑 deno task build-wasm);只有改 wasm/particles/src/lib.rs 才要重建并提交产物
  • 呼吸是常驻 rAF(约 0.90ms/帧 wasm 计算 + 一次 putImageData)。如果觉得费电,可把 breathPeriod 调大或让呼吸只在「刚到底的若干秒内」跑;prefers-reduced-motion 已经默认关掉了它
  • 后续若想加新的徽标交互力(点击爆散等),先确认它是仿射的;非仿射的力先在 1:1(绝不降采样)逐帧对比图上验一遍再落地
  • 验证:hugo --minify 通过、deno task test 通过、#pt-bg-config 产物已核对、DOM stub 端到端通过;测试台 /tmp/pt-motion/ 用完已删

互动特效 v2:消除白线 + 常驻漂浮

上一版的「飞入 → 落地 → 呼吸」被用户驳回(「这个效果不太好,试试其他的」,追问后确认不好之处是有明显的白色线条,想换成常驻轻微漂浮)。

完成的工作

  • 定位并修掉徽标上那层白色网格 ✅
    • 根因:wasm/particles/src/lib.rs 的 rasterize() 把每颗粒子居中吸附到整数设备像素((px[i]+ox).round()),而采样间距换算到设备像素后不是整数(旧参数 3.2px),于是相邻方块中心距在 floor / ceil 之间跳变 —— 跳到 4 而边长只有 3 时中间就裂出 1px 白线。静态就有,只是常驻呼吸让网格爬行才被注意到。扫描线证据:############.###############.###############.###########
    • 修法:make() 里的尺寸模式从 grain: bool 改成 size_mode: u32,新增 2 = 无缝:size = ceil(间距) + round(ratio)。⚠️ 此模式下 sizeRatio 的含义从「比例」变成「额外出血量(设备 px)」
    • 以源图 alpha 为真值的剪影内孔洞实测(首图 F_tZfZBbwAALItU.png,dpr2 / cssW 320 / step4 / spacing 3.2px):
配置size剪影内孔洞最长连续孔洞
旧 ratio 0.95 + round3px15.97%630px(一条贯穿到底的白线)
新 mode 2 + 出血 15px3.17%62px(剪影边缘的固有毛边,非线条)
  • 待机动效从「相干缩放」换成「非相干漂浮」 ✅
    • 删掉 pulse(amount),新增 float_on(amp, period) / float_off();Engine 新增 fx/fy/fvx/fvy 与 f_amp / f_wx / f_wy,漂浮偏移与目标位置分开存储 —— 弹簧只把 px/py 收拢到 tx/ty,漂浮在 rasterize() 里叠加,弹簧永远不去追会动的目标
    • 每颗粒子的相位与振幅都独立(振幅 0.55–1.0 倍随机,x/y 周期比 1.37),用拒绝采样求单位圆随机点避免 sin/cos;初值取在半径 a 的圆上(简谐精确解)→ 振幅恒定不衰减
    • tick() 结尾改成 if max_v > 0.05 || floating { 1 } else { 0 }:只要漂浮开着就永不返回 0,调用方的 rAF 链天然常驻
    • themes/sdttttt-paper/layouts/partials/bg.html:$cfg 改成 pitchCss 1.4 / maxParticles 60000 / gapFree true / sizeRatio 1 / dprCap 2 / thumpPower 1.4 / floatAmp 0.4 / floatPeriod 5200(去掉 grain / breathPeak / breathPeriod)
    • themes/sdttttt-paper/assets/js/page-bg.js:SIZE_MODE = cfg.gapFree ? 2 : cfg.grain === false ? 1 : 0;idle 档第一次进入时调一次 float_on(FLOAT_AMP × lastDpr, FLOAT_PERIOD / avgDt) 并常驻 busy = true;周期以实测帧间隔换算成帧数,60Hz / 120Hz 屏墙钟周期一致;draw()(resize / 减少动态效果 / 双击切回)会先 float_off()
  • 密度取舍由用户拍板:pitchCss 1.2(step3,糊成照片)/ 1.4(step4,采用) / 1.8(step5,像素马赛克)三档对比后选了 step4 —— 无白线和「看得出是粒子」是互斥的,step4 是折中 ✅
  • wasm 体积 24706 → 27705 字节(+3KB,漂浮相位表 + 无缝分支)
  • 验证:hugo --minify 通过(269 页)、deno task test 通过(28/28)、产物 #pt-bg-config 已核对、DOM stub 端到端通过

实测数据(首图,dpr2 / cssW 320 / step4 / 31,025 粒子 / spacing 3.2px / size 5px)

阶段帧数耗时位移备注
land(飞入)95–961.6s1226px → 0弹簧自动收拢,无参数
thump(落地)400.67s峰值 3.45pxburst(320,448,896,1.4)
idle(漂浮)常驻周期 5.2s每粒子 ≤0.8 设备 pxfloat_on 一次,300 帧后 10.16% 的 framebuffer 字节发生变化
  • 漂浮振幅安全性(剪影内孔洞,跑满一个完整周期 320 帧取最差帧):
floatAmp最差孔洞相对静止
0.4 CSS px(采用)3.173%+0.000 ✅
0.6 CSS px3.173%+0.000 ✅
0.9 CSS px4.355%+1.182 ❌ 开始裂洞
  • 每帧成本:tick() 在 640×896 / 31,025 粒子下约 0.45ms(60fps 预算的 2.7%)

遇到的问题

  • resize() 会把漂浮静默关掉 ⚠️ - resize() 内部要重构 make(),如果不显式保留 f_amp / f_wx / f_wy 并重新 init_float(),一次窗口缩放之后漂浮就永远消失了(且 tick() 会开始返回 0,rAF 链自己停掉)。已修:resize() 先存后传
  • float_on() 不能每帧调 ⚠️ - 它内部会重建相位表,每帧调一次等于把漂浮钉死在初始相位上,粒子看起来一动不动。page-bg.js 里用 floatOn 标志保证只在第一次进 idle 时调一次
  • max_offset() 在漂浮开启后恒为 0 ⚠️ - 它量的是 px/py 到 tx/ty 的距离,而漂浮偏移存在独立的 fx/fy 里(刻意的设计:弹簧不该去追会动的目标),所以这个诊断量测不到漂浮幅度,要用 framebuffer 字节比对
  • #[no_mangle] 在一次编辑里被误删 ⚠️ - float_on 一度没被导出,JS 侧能力检测直接把它判成 NO_ANIM;编译不报错,只能靠列 WebAssembly.Module.exports() 抓
  • pitchCss 是阶梯量化的 ⚠️ - step = round(pitchCss × 源图宽 / 画布CSS宽),1.2→step3、1.4→step4、1.8→step5,中间是死区;「稍微调细一点」这种需求在这个粒度下做不到

下次建议

  • 现在的取舍关系记在 bg.html 的注释里了:pitchCss 越小越干净但越糊,sizeRatio 是出血量(同时决定漂浮振幅上限),maxParticles 是粒子预算(会间接推高 step)。改这三个前先看注释里的实测表
  • 若非要用相干动效(比如点击爆散),要么保证它是仿射的(整体平移 / 缩放 / 旋转),要么先把出血量加大到能容纳它的相对位移;burst() 目前是径向衰减、非仿射,power 1.4 下的 3.45px 峰值位移实测没有裂洞,但再大就不保证了
  • 验证用的 DOM stub 端到端(/tmp/pt-motion4/dom-e2e.ts)抓出过「换档那一帧 rAF 自停」这种纯静态检查抓不到的 bug,值得保留一份;本次测试台 /tmp/pt-motion3/、/tmp/pt-motion4/ 用完已删
  • 当次只改了文件、未提交;这些改动随后已随同日 feat(bg): 系列提交推送

互动特效 v3:待机换成水波荡漾

(v2 的漂浮版已作为 3791645 feat(bg): 粒子改用无缝边长消除白线,待机换成常驻漂浮 提交,但用户看过后觉得「整幅像像素点在闪」,于是把待机效果换成相干的水波。)

完成的工作

  • 推翻了一条旧结论 ✅ - v2 写下的「徽标的待机动效只能做成非相干运动(相干驱动必拍干涉纹)」只在旧参数(出血量 0.2 设备 px)下成立。改成无缝边长(size_mode = 2,出血 1.8 设备 px)后,只要把位移梯度压低,相干波重新可用,且比逐粒子随机漂浮自然得多
  • Rust 引擎新增水波通道 ✅ - ripple_on(amp_x, amp_y, wavelength, period, mode) / ripple_off();w_amp_x / w_amp_y / w_k / w_w / w_mode / w_phase 六个新字段;tick() 在弹簧段、漂浮段之后加一段确定性位移场(不做积分、无相位表,每帧从粒子位置重算),与漂浮共用 fx/fy(同一时刻只开一个)。两种模式:
    • mode 0 横向剪切:s = fast_sin(py*k + φ) + 0.45*fast_sin((py*k + φ)*0.61 + 1.3),位移只取决于 y ⇒ 同一行整体平移,行距分毫不变
    • mode 1 径向涟漪:以画布中心算 r,a = s/(1 + r/(fb_h*0.6)) 径向衰减,位移沿 (dx/r, dy/r) 方向
  • fast_sin() 近似 ✅ - Bhaskara I 有理近似 + 半周期折叠,只用 floor(wasm 原生指令)。直接调 f32::sin 会把整套 libm 拖进 wasm(23KB → 30KB),实测近似最大绝对误差 0.0016,代价可忽略。关键验证:WebAssembly.Module.imports() 仍为 []
  • 接线与配置 ✅ - page-bg.js 新增 IDLE_EFFECT('ripple' / 'float')、RIPPLE_MODE、RIPPLE_AMP、RIPPLE_LENGTH、RIPPLE_PERIOD;idle 分支改成两级分发;floatOn 改名 idleOn;剪切模式显式不给垂向振幅;能力检测按模式择一。bg.html 的 $cfg 换成 idleEffect: "ripple" / rippleMode: "radial" / rippleAmp: 4 / rippleLength: 60 / ripplePeriod: 3600
  • 体积与成本 ✅ - wasm 27,705 → 30,635 字节(+2,930);每帧 tick() 在 640×896 / 31,025 粒子下:静止 0.83ms、剪切 0.96ms、径向 1.07ms(60fps 预算的 6.4%)

实测数据

  • 剪影内孔洞(口径:源图 alpha > 128 但渲染 alpha == 0),静止基线 0.199% / 最长 17px:
配置孔洞最长连续
剪切 ampX 4 dev(2 css)1.01%17px
剪切 ampX 8 dev(4 css)2.33%24px
剪切 ampX 12 dev3.60%17px
剪切 ampX 16 dev4.81%17px
剪切 12 dev + ampY 33.77%59px ❌
径向 4 dev(2 css)0.51%59px
径向 8 dev(4 css)1.17%59px
径向 12 dev1.93%59px
  • 目视(1:1 裁切胶片条 + 整幅缩略):剪切 4dev 很轻微、8dev 明显且像水、12/16dev 已像「切片/融化」;λ60 是细密荡漾、λ240 是大涌;径向 amp 4 css / λ 60 css 最像水面
  • 端到端(DOM stub 注入生产用 page-bg.js 原文 + 真 wasm + 真 $cfg):burst(320,448,896,1.4) @tick96 ✅、ripple_on(8,8,120,215.6,1) @tick136 且只调一次 ✅、float_on 从未被调 ✅、滚离页底 / 切后台 / 双击切图三条路径 pending rAF 归零 ✅、resize 后水波按同参数恢复 ✅

遇到的问题

  • 相干动效的可用区间取决于出血量 ⚠️ - 上一轮用「相干性」当判据,结论就变成了「相干一律不行」。真正的判据是相邻粒子(一个采样间距)的相对位移要远小于出血量:径向涟漪的相对位移 ≈ amp·k·间距(λ=120 设备 px 时只有 0.05·amp),剪切模式则恒等于 0。出血量加大后同一组参数就从「必裂」变成「干净」
  • 剪切模式给垂向振幅真会裂 ⚠️ - 一旦 ampY != 0,位移不再只随 y 变化,相对位移立刻出现,最长连续孔洞 17px → 59px。JS 侧已显式传 0 并写进注释
  • resize() 里的初始化顺序 ⚠️ - init_ripple 在关闭时会把 fx/fy 清零(为省内存只清长度不清分配),若在 init_float 之后调用就会把漂浮的相位表擦掉。resize() 里必须先 init_ripple 后 init_float
  • 改注释也会改二进制哈希 ⚠️ - 同源重建字节完全相同(已验证),但注释行数变化会改变嵌入的 panic 行号常量,所以「同尺寸不同哈希」不是不可复现构建,而是源码真的变了
  • {...raw} 展开 wasm exports 会丢计数 ⚠️ - 测试台里想给 build 加计数就写成了 {...raw, build: ...} 之后再覆盖,calls.build 恒为 0;引擎本身是好的(engine=wasm 已证明),别被自己的 stub 骗到

下次建议

  • 想再调水波动效,只动 bg.html 的 $cfg 即可(rippleAmp / rippleLength / ripplePeriod / rippleMode),不需要重建 wasm;只有改 wasm/particles/src/lib.rs 才要 deno task build-wasm 并提交产物
  • 现阶段剪切模式的视觉不如径向(径向的轮廓起伏最像水面),暂时只作为「经典水中倒影」备选留着;如果要启用,记得顺手把 rippleAmp 调小
  • 上一轮那条「给徽标加新交互力前先确认非相干/仿射」的建议已更新为「非相干 / 仿射 / 梯度足够低,且必须在 1:1 逐帧图上验」
  • 当次只改了文件、未提交;这些改动随后已随同日 feat(bg): 系列提交推送

参数微调(同日晚)

用户反馈「水波太大了,而且频率有点高」,于是压幅度、降速度,并把波纹的疏密也一并做成候选:

候选rippleAmprippleLengthripplePeriod观感
原4603600太大、太快
B2.5606500半幅半速
C2426000波纹更细密
D(采用)2807500半幅、半速、再宽一号
  • 四个候选各跑一个周期的 4 个相位,实测剪影内最差孔洞 2.28%–2.98%(静止基线 2.28%,最长连续孔洞都停在 59–71px 的边缘固有毛边,内部无撕裂)——降幅之后安全余量只会更大
  • 用户看完静态对比图选了 D,page-bg.js 的兜底默认值同步改成 2 / 80 / 7500

待机效果再改:单向纵波、自下而上(同日更晚)

用户看完 D(径向)后要求「水波改成单向的试试,从下往上」。

  • rippleMode: 'rise' ✅ - 复用引擎里的模式 0(t = py*k + phase,位移只随 y 变化),只是把振幅从横向分量换到纵向分量:波前变成水平线,整幅像被一波波从底部抬起。Rust 无改动、wasm 产物不变(27,705 → 30,635 那次已经是最终版)
  • 行进方向 ✅ - t = py*k + φ、φ 递增 ⇒ 波峰 y = (π/2 − φ)/k 向 y 减小方向移动 ⇒ 自下而上。实测用「位移场剖面」验证(图像本身是形变、不是刚体平移,直接对图像做互相关得到的位移没意义):φ=π/2 与 φ=π 两帧相对 φ=0 的 d(y) 剖面互相关,平移量 d = +36 设备 px(正 = 朝 y 减小 = 向上;理论 λ/2 = 80,实测偏小是因为剖面是两个不可通约正弦的叠加)
  • 安全性 - 四个候选各跑一个周期的 4 个相位,剪影内最差孔洞 2.50%–3.16%(静止基线 2.28%,最长连续孔洞 59px → 71–82px,仍是边缘固有毛边),采用 amp 2 / λ 80 / 7.5s
  • JS 侧的分量分配 - 模式 0 只领一个分量:rise 给 ampY、shear 给 ampX,径向两个都给

待机动效回退:水波 → 逐粒子漂浮(同日最后)

用户看过单向纵波后决定「还是不要波纹效果了,回到最初的闪烁效果」。

  • idleEffect: 'float' ✅ - bg.html 的 $cfg 改回 "idleEffect" "float",并把 floatAmp 0.4 / floatPeriod 5200 加回去;page-bg.js 的默认值判定翻转成「只有显式写 'ripple' 才走水波,其他一律 float」,避免配置写错时静默变成水波
  • 引擎侧两个入口都留着 ✅ - float_on / ripple_on 都还在 wasm 里(产物不变,30,635 字节),rippleMode / rippleAmp / rippleLength / ripplePeriod 四个键也保留,注释里写明「只在 idleEffect: 'ripple' 时生效,想再看水波改这一个键即可」
  • 文档同步 ✅ - AGENTS.md 的徽标行、assets/js 行、以及「判据是位移梯度」那条 bullet 全部改成「当前默认 float,ripple_on 是备选」,并把「水波更好看但最终被否」的取舍记进去
  • 端到端复验 ✅ - DOM stub 注入生产 page-bg.js + 真 wasm + 真 $cfg:burst 在第 96 帧、float_on(0.8, 311.4) 在第 136 帧且整段只调一次(不逐帧调,否则相位被反复清零)、全程 ripple_on 一次没调、三条门控(滚离页底 / 切后台 / 双击切图)pending rAF 都归零、resize 后重新 settle 且不重放飞入、纯动效路径一次都不 settle()

徽标抽图推迟到「揭示」那一刻,且每次揭示都重抽(同日最后一改)

用户要求:「每当图片隐藏之后,下次显示时采用新的随机数。也就是图片的随机逻辑要延迟到滚动到底部的时候才会显示计算。」

  • 随机逻辑搬到揭示那一刻 ✅ - 原来 var SRC = IMAGES[Math.floor(Math.random() * IMAGES.length)] 在模块求值时就抽好了,一页一图。现在整条链(抽签 pickImage() → 换 <img> 的 src → sizeCanvas() + 采样 + build())都移进 showImage(),只由 syncGate() 在 html.at-bottom 从无到有的那一刻触发;start()(预热)缩成只拉 wasm,不再抽图、不再采样
  • 每次揭示都是新的一张 ✅ - 滚离页底时 discardFrame() 把画布抹干净并把 frame 置 null(startMotion() / 双击 / resize 都会自动让路),所以下一张图此刻还没抽,也不可能先看到上一张。pickImage() 会避开上一张:三张图里本来有 1/3 概率抽回原图,用户会以为「随机坏了」
  • 首次揭示才飞入 ✅ - 第一次出图保留引擎里「粒子撒在画布外」的初态去跑「飞入 → 落地顿一下」;之后每次揭示只 settle() 吸附成型(draw()),在页底上下滚不会反复播 1.6s 的飞入
  • 两个交互取舍先与用户确认 ✅ - ①再次显示时直接成型(不重放飞入)②只有「滚离页底」算隐藏,双击切真实照片 / 切后台标签都不重新随机
  • 状态机四个标志 ✅ - revealed(这段可见期是否已安排图)/ pending(揭示时引擎还没编译好 → 就绪后补)/ shownOnce(决定飞入还是直接成型)/ building(采样中别插队)。mark('pending') 的语义扩成「加载中或已加载完但还没揭示」
  • 端到端验收 ✅ - DOM stub 注入生产 page-bg.js + 真 wasm + 真 $cfg + 真 PNG 像素,41 项断言全绿:页首 deferred/0 build/0 抽签;预热 pending/0 build/0 抽签;揭示 → wasm/1 build/1 抽签/particle_count()=31025/不 settle/burst@tick 96/覆盖率 56.8%;隐藏 → clearRect + rAF 出队 + 不再 tick;再揭示 → build 2/换图(…Da8AAvoeS → …BbwAALItU)/settle 1 次/burst 仍只有 1 次;第三轮再换一张;切后台回来不重建只续动画(Δtick 20);双击来回切不重建不换图
  • 踩坑 ⚠️ - 只有我自己的两处断言写错:rnd=0.9 → idx 2(不是 0);以及 draw() 会先 float_off 再重开 float_on(重建粒子后相位表必须重建,floatOn 次数 = build 次数,不是 1)

徽标「淡出闸门」:淡出走完才重抽,没走完就复用原图(同日再晚)

用户要求:「等待图片隐去之后,动画大概1.5秒,完全隐去后再次显示时重新随机,如果在动画内又拉到底部了,就直接不随机,直接显示原有的图片。」

  • 旧帧不再在「滚离页底」时立刻抹掉 ✅ - 滚离页底只摘 html.at-bottom(CSS 开始淡出),旧帧先留着;改成 hideTimer = setTimeout(hideFadeDone, hideMs()),hideMs() 直接读 CSS(.page-bg__box 的 transitionDuration,window.getComputedStyle;实测 CSS 里是 0.8s,prefers-reduced-motion 下是 transition: none → 自动变 0),不在这里硬编码一份时长、日后跟 custom.css 走散
  • hideFadeDone() ✅ - 淡出真走完才 discardFrame() + needsPick = true,即「这一刻才算真的藏起来了」,下次揭示才重抽;若期间 revealed 又变 true 就直接返回(什么都不做)
  • 淡出中途滚回来 = 不重抽 ✅ - 揭示分支先 clearTimeout(hideTimer) 撤销那次「抹帧 + 重抽」,再走新的 revealShow():!needsPick && frame → 只 startMotion() 接着显示原来那张(粒子 / 图片 / 动效状态全在原位);否则才 showImage()。start() 的就绪回调也改成调 revealShow()
  • 计时器只在「这一轮」离开页底时起一次 ✅ - if (!hideTimer) 才 setTimeout。否则滚动期间每个 scroll 事件都会把计时器往后推,hideFadeDone 永远不会到
  • 第五个标志 needsPick ✅ - 只有「淡出已走完」或「还没出过图」才重抽;新增在 revealed 上方,hideTimer 紧邻;revealShow() 与 hideMs() / hideFadeDone() 一起放在 syncGate() 前面
  • 端到端验收 ✅ - DOM stub(含虚拟时钟:setTimeout / clearTimeout 换成可 advance(ms) 的队列)+ 生产 page-bg.js 原文 + 真 wasm + 真 $cfg,52 项断言全绿,计数 build=3 settle=2 tick=300 burst=1 floatOn=2 rippleOn=0 clearRect=2 srcSet=3 random=3:页首 deferred;预热只拉 wasm(0 build / 0 抽签);揭示后 1 build / 1 抽签 / particle_count()=31025 / 不 settle / burst@tick 96;滚离 400ms 时 clearRect 仍为 0;淡出中途滚回来 → 0 重建、0 抽签、图不变、tick 续上;再滚走并 advance(1400) 仍不抹帧、淡出期间反复滚动不推迟计时器、advance 到 1520ms 才 clearRect;完全隐去后再揭示 → build 2 / 换图 / settle 1 次 / burst 仍只有 1 次;第三轮三张互不相同;切后台与双击来回都不重建不换图
  • 时长按 CSS 走、按用户口径验 ✅ - 测试台故意把 transitionDuration 桩成 1.5s(用户的口径),证明时长确实是从 CSS 读出来的;真实值以 custom.css:70 的 transition: opacity 0.8s ease 为准
  • 踩坑 ⚠️ - 又是测试台自己的问题:classList.toggle(c) 不带第二个参数时我那个 stub 会去 delete 而不是 toggle(双击切图那条断言假失败);wasm 的 exports 对象是只读的,{ ...mod } 拷不动、得逐键拷一份;burst / float_on 分别在第 96 / ~130 帧才发生,断言必须放在 pump(220) 之后(原先只 pump 120 帧)

遗留与下次建议

  • 想彻底不要水波引擎时把 float_on 之外那几个导出摘掉,wasm 能从 30,635 字节缩回 27,705
  • 每次揭示都重新采样 + 建帧(约 5–10ms,图片已被浏览器缓存),如果哪天觉得在页底反复滚不如「同一张图只建一次」,把 discardFrame() 去掉、在 revealed 复位时只置一个 dirty 标志即可

WASM 粒子引擎补单元测试(同日最后)

用户要求:给 wasm/particles/src/lib.rs 补单元测试,「最好确保全覆盖」。

完成的工作

  • 新增 wasm/particles/src/tests.rs(31 个 #[test],约 1030 行)✅
    • wasm/particles/src/lib.rs 末尾只加了 #[cfg(test)] mod tests;(+9 行),引擎本体一行没动(897 行)
    • deno.json 新增 test-wasm: cd wasm/particles && cargo test
    • AGENTS.md:命令块补 deno task test-wasm,wasm/particles/ 与「WASM 引擎」两条 bullet 补上测试位置与跑法
  • 覆盖度(实测,rustc 1.99 + llvm-tools-preview):lib.rs 836 regions / 30 个函数 / 530 行 = 100%;tests.rs 1319 regions 只差 2 个(setup() 里锁中毒恢复用的 |e| e.into_inner() 闭包,除非有测试持锁 panic 否则跑不到)。复现命令写在 tests.rs 文件头
  • themes/sdttttt-paper/assets/wasm/particles.wasm 逐字节未变(sha256 2425081c…,测试是 #[cfg(test)]、不进 wasm 产物)——已跑 deno task build-wasm 复验 ✅
  • 覆盖到的行为:rnd(取值范围 / 复位后可复现)、unit_circle(两条拒绝分支:种子 7966 要 8 次抽样、种子 1 要 4 次)、fast_sin(|x|≤20 最大误差 1.63e-3 < 2e-3、折点处为 0)、alloc/dealloc、count_opaque(alpha > 128 阈值 + step)、pick_step(scale ≤ 0、取整、clamp 1/24、40 万粒子的安全阀、全透明)、fit(宽 / 高两分支 + 恰好填满)、build(非法参数不覆盖旧引擎、RGBA 打包小端序、设备像素落点、size_mode 0/1/2 三档与 ratio 上夹)、tick(0.05 速度阈值、弹簧、相位回绕)、rasterize(四角裁剪、没有相位表时不索引 fx/fy)、burst(参数校验、命中范围、正中命中退化方向、半径外)、float_on / ripple_on(非法值与 clamp、模式映射、剪切同行刚性、径向 r.max(1.0) 兜底、两者互斥且可逆)、resize(重排 + 非法尺寸 + idle 设置存活 + init_ripple → init_float 顺序)、无引擎时 19 个入口全部兜底、max_offset

遇到的问题

  • rnd() 返回的是 [0,1) 而不是 [-1,1) ⚠️ - 我一开始把它当成 unit_circle 的 u/v 直接断言,报出 r² = 0.5014 与预期 4.5e-5 差了三个数量级,查了半天以为是并发污染了全局 SEED。根因是 *2 - 1 在 unit_circle 内部做,测试里得自己换算
  • tick() 的「静止」判据只看速度,会提前报 0 ⚠️ - 判据是 max|vx| + |vy| <= 0.05,而阻尼振子(spring 0.08 / damp 0.86,包络每帧 ×0.927)的速度每 ~7 帧过一次零点:第一个过零点就报静止,此时位置还剩初始偏移的 ~40%(实测 5.63 / 13.89)。而且报 0 不「粘住」——下一帧速度又爬回阈值以上。测试按这个真实口径写(run_until_still() + 文件头注释),想位置对齐得显式 settle()
  • floatAmp 0.4 设备 px 在 framebuffer 上一个字节都不动 ⚠️ - rasterize() 取 (px + ox).round(),整格坐标 + 亚像素偏移恒等于原格。测试里要验「真的挪了像素」得把幅值提到 > 0.5(用了 2.0)。线上靠 dpr 换算成设备像素后能过 0.5,所以不受影响
  • init_ripple() 的开启分支不清 fx/fy ⚠️ - 只有关闭分支才清零(省内存,长度留着)。从漂浮切到水波时相位表里还是旧的漂浮相位,由下一帧 tick() 全量覆盖 —— 行为没问题,但不能断言「切换后立刻全 0」
  • 数像素不能数「非零字节」 ⚠️ - 测试图颜色是 (x%251, y%241, 0x33),g 通道常常为 0,一个不透明像素只贡献 3 个非零字节。要按 alpha != 0 数像素
  • 覆盖度工具:CLT 自带的 llvm-profdata 版本太老 ⚠️ - xcrun llvm-profdata 是 LLVM 15,rustc 1.99 产出的 raw profile 是 v11、它期望 v10,直接报 raw profile version mismatch 合并失败。正解是 rustup component add llvm-tools-preview(约 100MB,已装),用 ~/.rustup/toolchains/*/lib/rustlib/*/bin/ 里那套
  • src/lib.rs 本身不是 rustfmt-clean ⚠️ - cargo fmt 会顺手改掉引擎里的 init_float(344 行)与 tick(549 行)两处,为了不混进无关 diff,只对新增的 src/tests.rs 单独跑了 rustfmt,lib.rs 保持原样

下次建议

  • 没有往 CI 加 cargo test:.github/workflows/ 里现有的 4 个 workflow 都故意不装 Rust。要加得新开一个 job(dtolnay/rust-toolchain + cargo test,无需 wasm32 target),代价是每次 push 多几十秒
  • 测试用「一把全局 Mutex 串行 + 直接读写 Engine 私有字段」的写法(引擎挂在 static mut ENGINE 上,cargo test 默认多线程)。新增测试务必以 let _g = setup(); 开头,否则会和别的测试抢 ENGINE / SEED
  • 以后改 wasm/particles/src/lib.rs 的流程变成:deno task test-wasm → deno task build-wasm → 提交 .wasm
  • 当次未提交;随后由用户确认,提交为 7dc5b24 并推送(同日)

清理 scripts/ 的死代码与 PaperMod / claudelog 残留

用户问「@scripts/ 有些脚本我觉得是多余的」,评估后决定只删零引用的死代码(约 -64 行),脚本本身一个没删。

完成的工作

  • 删掉零引用代码(10 个文件,+11 / -75)✅
    • scripts/lib/fs.ts 的 walkFiles() —— 零引用,scripts/optimize-images.ts 早已自带 collectSources() + 局部 walk(),而注释里那句「optimize-images.ts 用」是过时描述
    • scripts/lib/paths.ts 的 THEME_DIR = 'themes/PaperMod'(PaperMod 早被 hugo-paper + sdttttt-paper 取代)与 exists()(零引用),顺带去掉只为 exists() 存在的 import { stat } from 'node:fs/promises'
    • scripts/lib/args.ts 的 getStrings() —— 零生产引用,只有 args.test.ts 在测它(连同那 3 条测试一起删)
    • scripts/lib/git.ts 的 gitHasChanges() —— 零引用
    • scripts/check-dead-links.ts 的 export { walkMarkdown }; —— 纯粹为了给测试 re-export,测试改成 import { walkMarkdown } from '../lib/fs.js'
  • 清掉旧主题 / 旧目录名的残留 ✅
    • deno.json 的 exclude 去掉已不存在的 themes/PaperMod
    • hugo.toml 的 mainSections 注释:claudelog → changelog(目录在 99d262c 已改名)
    • scripts/lib/frontmatter.ts 头注释:PaperMod → hugo-paper
    • scripts/lib/paths.ts 头注释:去掉 COVERS_DIR / exists() / claudelog 这些已删概念的卖点
  • 验证:deno task test 27 passed / 0 failed(原 28,去掉 getStrings 那组);deno check scripts/*.ts 10 个文件全通过;deno task validate-posts ✓;deno task check-dead-links --dry-run 跑到「✓ 未发现死链」(确认 walkMarkdown 仍能加载);deno task format-markdown-check 通过

遇到的问题

  • edit 工具在 scripts/lib/fs.ts 上匹配失败 ⚠️ - 改 walkFiles 那块时 oldText 死活对不上(同一次调用里另外 8 个文件都成功,整个调用按原子回滚,该文件一行没改)。解法:fs.ts 与 paths.ts 这种小文件直接整体 write 重写,比抠 oldText 省事
  • macOS 没有 timeout 命令 ⚠️ - 想给冒烟测试加超时,报 timeout: command not found(GNU coreutils 的那套要 gtimeout)。改用工具自带的超时

下次建议

  • 评估里「薄包装」那类用户暂不动手:scripts/format-markdown.ts(47 行 + 31 行测试)本质就是 prettier --write|--check '**/*.md',可以压成 deno.json 两行 task;scripts/lib/fs.ts 整个文件只服务 check-dead-links.ts
  • 真要瘦身时最大的一块肌肉是 scripts/git-commit-push.ts:197 行里大半是 commit message 自动分类(另有 214 行测试),核心流程(add -A → commit → pull --rebase → push)4 行 shell 就够
  • 别删:validate-posts(Hugo 对缺 title/date、slug 重复是静默容忍)、check-dead-links(外链腐烂静默,2026-10-05 就被 || true 吞过 9 张失效图)、rename-posts(文件名带正文 hash + 自动写 aliases 保旧 URL)、optimize-images(assets/src → static 唯一可复现路径)
  • 当次未提交;随后由用户确认,提交为 1caf6b9 并推送(同日)

瘦身 scripts/:薄包装合并进 deno.json 与调用方

完成的工作

  • deno task format-markdown / format-markdown-check 不再包一层脚本,deno.json 里直接写 prettier --write '**/*.md' / prettier --check '**/*.md';删掉 scripts/format-markdown.ts(47 行)与 scripts/__tests__/format-markdown.test.ts ✅
  • walkMarkdown() 从 scripts/lib/fs.ts 内联进 scripts/check-dead-links.ts(它唯一的使用者),删掉 scripts/lib/fs.ts;测试改从 ../check-dead-links.js 导入 ✅
  • AGENTS.md / README.md 里的 lib/ 目录说明同步(修正了 fs 与 paths / image-plan 的漂移)✅
  • 顺手把本文件里 4 处已过时的「本次只改了文件,没有 commit / push」改成实际结果(v2 → 3791645、v3 → b598b1d、WASM 测试 → 7dc5b24、死代码清理 → 1caf6b9)✅

遇到的问题

  • task 名保持不变(format-markdown / format-markdown-check),所以 deploy.yml 的调用、.github/workflows/ 与文档都不用动 ⚠️ - 刻意只替换实现、不动接口,避免破坏 CI
  • glob 必须用单引号包住('**/*.md')⚠️ - 不加引号会被 sh 先展开,且 ** 在 sh 下退化成 *,prettier 收到的文件集会变;加引号后交由 prettier 自己按 glob 展开,与旧 wrapper(spawn('prettier', [..., '**/*.md'], { shell: false }))行为一致,退出码也照原样透传
  • prettier 得在 PATH 里(~/.deno/bin),否则报 prettier: command not found(退出码 127)⚠️ - 与旧 wrapper 报 prettier 启动失败: spawn prettier ENOENT 同样是 127,CI 里 deno install -g 装完就在 PATH 上,不受影响

下次建议

  • scripts/git-commit-push.ts 仍是最大的一块肌肉(197 行 + 214 行测试),核心流程(add -A → commit → pull --rebase → push)其实 4 行 shell 就够;commit message 自动分类(chore(rename) / chore(format) / chore(fm) / chore(posts))是唯一真正的增值点,要砍得先确认 deploy.yml 传的 --message 语义能否被固定信息替代
  • 删掉 format-markdown.ts 后 deno task test 少一组测试(27 → 26),这是有意的:那组测的是 wrapper 拼命令,现在没有 wrapper 了

继续瘦身 scripts/:删掉 git-commit-push.ts,CI 的自动提交改成内联 shell

完成的工作

  • 删掉 scripts/git-commit-push.ts(197 行)、scripts/__tests__/git-commit-push.test.ts(214 行)、scripts/lib/git.ts(78 行,四个导出只服务这个脚本)✅
  • deploy.yml 的 Commit auto-fix results 改成内联 shell:git config 两个身份字段 → git add -A → git diff --cached --quiet 判断有无改动 → git commit -m "chore: auto-fix content" → git pull --rebase → git push ✅
  • deno.json 去掉 git-commit-push / git-commit-push-dry 两个 task;AGENTS.md(命令块、lib/ 说明、操作需确认)与 README.md(目录树、维护命令、CI/CD 说明)同步 ✅

遇到的问题

  • 分类逻辑(chore(rename) / chore(format) / chore(fm) / chore(posts))随之取消,CI bot 的 auto-fix 提交信息统一成 chore: auto-fix content ⚠️ - 想区分只能看 diff;这是用户权衡后选的路,换来 410 行脚本 + 测试的删除
  • scripts/lib/git.ts 是连带死代码:gitExec / gitExecArgs / gitHasStagedChanges / setupBotIdentity 四个导出只有 git-commit-push.ts 在用 ⚠️ - 一并删掉;getString 还被 optimize-images.ts 用,保留
  • 「无改动就退出」必须显式写 ⚠️ - git diff --cached --quiet(有改动时退出码 1),漏掉它 CI 在没产生 auto-fix 的日常部署里会以 non-zero 直接失败

下次建议

  • 「必删不得」清单不变:validate-posts / check-dead-links / rename-posts / optimize-images
  • 如果以后想在提交信息里恢复分类信息,最省的做法是在 shell 里按 git diff --cached --name-status 判断,而不是再长出一个近 200 行的脚本

再瘦一轮 scripts/:修 3 个 bug 级问题 + 去重

完成的工作

  • scripts/lib/frontmatter.ts:两处重复的正则合成一个 FRONT_MATTER_REGEX;块式数组(aliases: + - /a/,正是 addAlias 写出来的格式)以前被解析成 {}(回读全靠字符串匹配),现在正确解析成 string[];新增 toYyyymmdd()(Date.UTC 真实日历校验)✅
  • 日期判据统一:validate-posts.ts 的 isValidDate(Date.parse)与 rename-posts.ts 的 normalizeDate 各写一份且不一致,现在都改用 lib 的 toYyyymmdd。Date.parse 既接受 2026/01/01(于是「校验通过」),也接受 2026-02-31(JS 滚到 3/3)✅
  • scripts/lib/args.ts:--key=value 不再被静默解析成 { "format=webp": true };不再收集位置参数 _.(getString 里永不可达的数组分支随之消失)✅
  • scripts/lib/paths.ts:新增 listPostFiles(),rename-posts 与 validate-posts 的 posts 清单口径合并到一处 ✅
  • scripts/rename-posts.ts:新增 findBlockingCollisions() —— 目标名撞上「本次不挪走的现存文件」或两篇互换名字时直接报错退出(detectCollisions 只比对 plans 之间,漏掉这两类;执行顺序不利时 git mv 会因目标已存在而失败,降级到覆盖式 fs.rename 就把另一篇静默吃掉);顺手删掉 printPlan() 里从未使用的 prefix 参数 ✅
  • scripts/check-dead-links.ts:checkUrl(HEAD) 与 checkUrlGet(GET) 两个逐行重复的函数合并成私有 fetchStatus(url, method, ms),clearTimeout 移进 finally(原来异常路径不清理定时器);405 换 GET 重试沿用同一个超时值(原来新请求吃默认 timeout)✅
  • 测试同步:新增 toYyyymmdd(含闰年 2/29、2026-02-31、2026/01/01)与块式数组断言、findBlockingCollisions(4 例,含「互换名字」与「不算自撞」)、2026-02-31 校验用例;args.test.ts 按新解析语义重写;async 无 await、mock 未用参数两处 lint 报错修掉 ✅

遇到的问题

  • description 必填校验加上又撤掉 ⚠️ - 审计时只查了「有没有 description 键」,实际有 4 篇是 description: ""(20260826-回顾过去看过的番-1d3e.md、20260901-期望-156i.md、20260921-今天是二零二六年九月二十一日-4r2.md、20260921-今天是二零二六年十月二日-141g.md),加校验会让 CI 的 Validate Posts 直接挂;用户选择撤销校验而不是补摘要,所以本轮不引入这项检查
  • 判据不一致的隐藏后果 ⚠️ - validate-posts 用 Date.parse 说合法、rename-posts 用 normalizeDate 静默跳过,两边都没报错;合并成 toYyyymmdd 后只剩一个口径
  • hash 后缀实测是 3–4 位(16-bit base36 + padStart(3),46656 以上到 4 位;169 篇 3 位 / 56 篇 4 位)⚠️ - rename-posts.ts 的 doc 与 AGENTS.md 的「末尾 4 位 hash 短码」都改成 3–4 位
  • deno lint scripts/ 的 3 条真问题清零,只剩 27 条 no-sloppy-imports('./x.js' 指向 .ts 的正常 TS 写法)⚠️ - 想接进 CI 得先给 deno.json 配 exclude

验证结果

  • deno task test 26 passed / 0 failed;deno check scripts/**/*.ts 全通过;deno task validate-posts 通过(未加 description 校验);deno task rename-posts-dry 打印「✓ 0 篇文章需要重命名」(findBlockingCollisions 不在真实仓库误报);deno task format-markdown-check 通过;deno lint scripts/ 只剩 27 条 no-sloppy-imports ✅

下次建议

  • 本轮用户未选的可选项:把 deno lint 接进 CI(先配 no-sloppy-imports 的 exclude);check-dead-links 的 HEAD/GET 并发化;「边扫边打 ✗、最后又整列一遍」的重复输出(属行为改动)
  • 那 4 篇空 description 迟早要补,等哪天顺手写;校验可以先不加

再瘦一轮 scripts/:修 bug 级问题 + 死链检查并发化(同日最后)

完成的工作

  • scripts/rename-posts.ts:runGit() 修掉一个真 bug —— spawn('git', …) 找不到可执行文件时是以 ’error’ 事件失败的,旧版只监听 ‘close’ 且外层 try/catch 拦不住,于是「没装 git / 不在 git 仓库」直接变成 Uncaught Error: spawn git ENOENT 终止进程,与 moveFile() 注释声明的降级(fs.rename)正好相反;现在补 child.on('error', () => resolve(-1)),并 resume() 掉两个孩子管道(不读会把 git 堵在写缓冲上)。顺手删掉永远不生效的 getBoolean(args, 'v') 别名(parseArgs 只认 --)✅
  • scripts/check-dead-links.ts:链接正则会把紧跟 URL 的中文与 ( 一起吞掉 —— 用真 extractor 扫 content/,44 个唯一外链里 3 个是垃圾(…/Actions-immortalwrt的固件,不使用Lean…、…/gfwlist就可以基本覆盖…、…-1e69/(后缀,每次都变成假 404 警告)。新增 trimUrlTail():先在第一处「前一字符既不是 /、- 也不是 CJK」的 CJK 字符处截断,再循环剥末尾标点与没配对的左括号;不能简单「遇中文即截断」,站内 slug 本身就含中文(…-jtc/ 必须原样保留)。改完 3 个假链接全部消失、其余 41 个一字未改(抽尾后与已有条目去重,剩 43 个唯一外链)✅
  • 请求并发化:checkAll() 用工作池(CONCURRENCY = 6)替换串行循环,真实跑从 26–29s 降到 6.3s;同时删掉「边扫边打 ✗」那行(末尾本来就会整列一遍,CI workflow 也只把整段输出写进 job summary)✅
  • scripts/optimize-images.ts:孤儿产物提示以前只看 static/bg/(static/avatar.webp 从源图删了也不提醒),改成 listPublishedImages()(static/bg/*.avif|*.webp + 存在时的 static/avatar.webp,不递归 static/,否则会把文章配图误报成孤儿);体积百分比抽成 formatSizeDelta(),产物比源图大时不再打成 -(-12)% ✅
  • 去重:validate-posts.ts 与 rename-posts.ts 各写一份 title/date 检查(措辞还不一样),合并成 lib/frontmatter.ts 的 checkTitleAndDate();checkUrlGet()(生产代码已无引用)删掉;main() 里的 Map<string, { ok; status }> 改用已有的 LinkStatus ✅
  • deno.json:新增 deno task lint,并配 "lint": { "rules": { "exclude": ["no-sloppy-imports"] } }(否则 27 条全是这条规则的噪音)→ 现在 deno task lint 0 报错 ✅

遇到的问题

  • 「没 git 就降级」的回归测试一开始是空测试 ⚠️ - 第一版用 Deno.env.set('PATH', '/nonexistent-bin') 在同进程里跑,把 error 监听删掉后测试照样通过。逐层排查:spawn 的 ENOENT 在 deno run 里是 uncaught error(进程 exit 1),但在 node:test 的 shim 里会被吞掉(同进程怎么写都测不出来);PATH 改动本身生效、也没有缓存解析结果。最终改成整条 CLI 跑子进程(Deno.Command(Deno.execPath(), { args: ['run','--unstable-sloppy-imports','--no-lock','-A', <script>, '--execute'], cwd: <临时目录>, env: { PATH: '/nonexistent-bin' } })),断言 exit 0 + 改名成功 + aliases 写入;把 error 监听删掉后该测试确实会失败(stderr 里出现 Uncaught Error: spawn git ENOENT),回归测试这才有效力 ✅
  • 那 3 个假死链其实一直让 CI 的 Check Dead Links 每次多写一条 ::warning:: ⚠️ - CI 里是 set +e … exit 0,不阻塞,所以一直没人注意到
  • content/changelog/2026-08-17.md 里那条 …/posts/20260817-文章的变化-1e69/ 抽尾后仍然 404 ⚠️ - 这是真死链(历史日志里写的是旧 URL),不是正则的锅,保持报告

验证结果

  • deno task test 30 passed / 0 failed(原 26;新增 trimUrlTail 6 例、checkTitleAndDate 5 例、formatSizeDelta 3 例、listPublishedImages 3 例、CLI 端到端 1 例)✅
  • deno task lint 0 报错;deno check scripts/**/*.ts 全通过 ✅
  • deno task validate-posts ✓;deno task rename-posts-dry 打印「✓ 0 篇文章需要重命名」;deno task format-markdown-check 通过 ✅
  • deno task check-dead-links(真跑)43 个唯一外链、21 个死链(都是既有结果:baidu 百科整段 403、https://www.notion.so fetch failed 等),耗时 6.3s ✅

下次建议

  • deno task lint 目前只加进了 deno.json,要不要接进 CI(单独一个 lint workflow,或在 Test Scripts 里加一步)待定
  • check-dead-links 的 21 个既有死链可以排一次;baidu 百科这类反爬 403 建议加域名白名单,否则警告长期是噪音
  • content/changelog/2026-08-17.md 与 content/changelog/2026-03-31.md 里的 sdttttt.online 旧 URL 可以改成现行 URL(或删掉)
  • 那 4 篇 description: "" 仍未补(见上一节)

徽标首次入场改成「自上而下一层层显现」(同日最后一改)

完成的工作

  • 需求(两轮):先把入场从「从四周随机撒进来再弹回」改成分层聚合,再改成真正的逐行渲染。用户最终口径是——① 未放行的粒子必须根本不画(不是整幅画好了、只是被整体挪了位置)② 波前方向自上而下,③ 保留最后一层落定后的落地顿挫,④ 每行出现时不带下落位移(wipeDrop = 0)✅
  • 必须改 Rust 才做得到:弹簧 v = (v + (target-p)*0.08) * 0.86 的收敛时间只由阻尼决定、与起始距离无关(起点放多远落定时刻几乎一样),所以「分层」只能靠显式放行闸门;纯 JS 没有后门(fx/fy 每帧被 float/ripple 公式整体覆写,settle() 是全量吸附)✅
  • wasm/particles/src/lib.rs:
    • 新增 fn hash01(i: usize) -> f32(索引整数哈希 (i as u32).wrapping_mul(2654435761) >> 8)给波前边缘做抖动 —— 逐帧稳定(同一索引每帧同值,否则边缘会沸腾),且不占内存(12.4 万粒子存一份 f32 抖动要 500KB)✅
    • Engine 加五个字段 wipe_step / wipe_front / wipe_band / wipe_drop / wipe_gate ✅
    • 新增 fn Engine::init_wipe(drop, frames, band):wipe_front = -wipe_band(起手在画布上缘之上,先留几帧全空)、wipe_step = (fb_h + 2*wipe_band)/frames、每颗粒子 px = tx / py = ty - drop(只沿 y 平移 ⇒ 相对位移恒 0 ⇒ 零摩尔纹)、速度清零;drop 允许 0(纯逐行渲染)✅
    • 放行判据 ty[i] + (hash01(i) - 0.5) * band > front ⇒ 跳过,tick() 与 rasterize() 共用同一条 —— 前者让粒子不动、后者让它不画。rasterize() 里那句 continue 才是「逐行渲染」与「整幅被挪了位置」的分水岭 ✅
    • tick() 开头推进波前(wipe_front += wipe_step,越过 fb_h + band 自关),返回判据改成 if rising || max_v > 0.05 || floating || rippling { 1 } ✅
    • 新增导出 wipe_on(drop, frames, band) -> i32 / wipe_off() -> i32;settle() 顺手清掉闸门;resize() 重建后闸门自动关(拖窗口不会重放)✅
    • build() 的 11 个参数一个都没动(零回归面)✅
  • wasm/particles/src/tests.rs:新增 framebuffer 探针 fn alpha_at(x, y) -> u8(读第 (y*fb_width()+x)*4+3 字节),5 条测试重写为 wipe 版 —— hash01 稳定性、wipe_on 参数校验与起始位(drop = 0 合法、负值 / 非有限 / frames <= 0 拒绝)、wipe_gate_freezes_the_unreached_layers_and_keeps_tick_reporting_motion(第一帧全冻、max_v = 0 但 tick() 必须返回 1)、wipe_reveals_rows_top_down_and_hides_the_ones_not_reached_yet(走 20 帧后 alpha_at(2,2) != 0 而 alpha_at(2,36) == 0)、自上而下放行顺序 + 弹簧接管后的残余位移(released[0] == 1、released[n-1] == 36、残余 max_offset() < 0.5)、抖动带让同一行错开(跨度 ≤ band/speed);「无引擎兜底」里补 wipe_on × 2 / wipe_off ✅
  • themes/sdttttt-paper/layouts/partials/bg.html:$cfg 加 wipeDrop: 0 / wipeDuration: 2400 / wipeBand: 16,长注释把「开场自下而上一层聚合」整段改写成「自上而下一层层显现」(含 wipeDrop 各档观感、为什么必须动引擎、为什么未放行的一律不画)✅
  • themes/sdttttt-paper/assets/js/page-bg.js:新增 WIPE_DROP / WIPE_DURATION / WIPE_BAND 三个配置;showImage() 里 build() 成功后、第一帧 tick() 之前,仅首次揭示(first === true)调一次 wipe_on(WIPE_DROP*lastDpr, WIPE_DURATION/avgDt, WIPE_BAND*lastDpr);draw() 里补 wipe_off();旧 wasm 没有 wipe_on → 静默退回随机散布飞入,不算错误(所以没动 NO_ANIM 的能力检测)✅
  • AGENTS.md:徽标行改成「自上而下一层层显现 → 落地顿一下 → 待机漂浮」+ 旋钮换成 wipeDrop / wipeDuration / wipeBand;assets/js/ 行改成「逐行显现/落地/漂浮」;入场那段整条重写(含「未放行的一律不画」这条分水岭 + rise_on 前身被否的教训);wasm 体积更新为 32,062 字节、单测数更新为约 37 个 ✅

遇到的问题

  • 第一版「自下而上一层聚合」被用户当场否掉 ⚠️ - 那一版是把粒子整体悬在目标位下方(riseTravel = 60 CSS px)再由下往上逐行放行,观感是「整幅图已经渲染好了、只是被挪了位置」,用户要的是「粒子逐渐渲染」+ 自上而下。教训:入场动效的第一判据是未放行的像素到底画不画,其次才是波前方向 ✅
  • tick() 的返回判据漏了 rising 会让落地顿挫抢跑 ⚠️ - 波前扫动的第一帧可能一个粒子都没动过(max_v = 0),旧判据会让 tick() 返回 0、JS 当场以为落定、把落地顿挫提前放掉;单测 wipe_gate_freezes_the_unreached_layers_and_keeps_tick_reporting_motion 专门守这一条 ✅
  • build() 之后的 framebuffer 是空的 ⚠️ - rasterize() 只在 tick() 里跑,标定脚本第一版在 build() 后直接取帧,拿到的是空白;生产侧无影响(step() 总是先 mod.tick() 再 blit())✅
  • 「引擎报静止」比「看着完成」晚得多(只在 wipeDrop > 0 时) ⚠️ - 早先那版(粒子悬在目标位下方 riseTravel = 60)波前 1.2s 扫完、最后一层约 1.8s 归位,但 tick() == 0 要等到 f≈135–180(2.3–3.0s),那一截尾巴是 ≤0.2 设备 px 的亚像素蠕动(弹簧振幅每帧 ×0.927)。最终版 wipeDrop = 0 没有这段尾巴:粒子一出现就在目标位,弹簧没有活干,实测覆盖顶到 56.7% 在 f=138(2.30s)、tick() 归零在 f=145(2.42s),wipeDuration 因此可以近似当作总时长 ✅
  • await WebAssembly.instantiate() 的返回值是 { module, instance } ⚠️ - 标定脚本写成 inst.exports 会 TypeError: Cannot read properties of undefined (reading 'alloc') ✅
  • sharp().composite() 只接受已 resolve 的 Buffer ⚠️ - 传 sharp 实例(thenable)会在构造函数里报 Error: Invalid input,必须 await sharp(png).resize(...).png().toBuffer() ✅
  • edit 工具一次调用是原子的 ⚠️ - 多条目里只要一条 oldText 不匹配,整个调用不生效(且不告诉你改到第几条之前的部分)。长块(含多行中文注释)极易差一个词 —— 本轮 page-bg.js 的配置块就这样失败过一次,改成 python 的 assert s.count(old) == 1 + replace 逐块替换 ✅
  • DOM 验收台三个自伤 bug ⚠️ - ①ex.resize = raw.resize 会把计数包装覆盖掉(resize 计数恒 0)②makeEl({ get src(){…} }) 的对象字面量展开会提前触发 getter → ReferenceError: Cannot access 'photo' before initialization,改用 Object.defineProperty(photo, "src", {…}) ③我直接给 win.scrollY 赋值而没有派发 scroll 事件,syncGate() 根本没跑(两条断言假失败);另外 pump(30) 这种批量推进会让揭示落在批次中间,量到的覆盖率已经跑过头 → 改成 while (calls.wipe_on.length === 0) await pump(1) 逐帧停在揭示那一拍 ✅
  • 图像顶部本身就是透明的 ⚠️ - 揭示后第 3 帧覆盖率仍是 0.00%,一开始以为闸门没生效:插画顶部(canvas y < ~25 设备 px)没有不透明像素,所以波前扫过那段时确实没有东西可画 —— 断言改成「覆盖率随时间单调增长 + 第 12 帧仍 < 30%」✅

验证结果

  • deno task test-wasm(cargo test)37 passed / 0 failed ✅
  • deno task build-wasm:themes/sdttttt-paper/assets/wasm/particles.wasm 31,818 → 32,062 字节(+244,rasterize() 多一句闸门判断),WebAssembly.Module.imports() 仍为 [] ✅
  • 1:1 胶片条标定(/tmp/pt-wipe/wipe.ts + wipe2.ts,真 wasm,画布 640×896 设备 px、n = 31,025):四档 wipeDrop 的 f = 0 覆盖率都是 0.00%(画布从全空开始),波前自上而下推进(f=12 覆盖 3.1–3.9%、f=28 约 18–20%、静息 56.7%),四档最终都收敛到同一张图,全程无白线、无摩尔纹;drop = 0 边界干净、像素 100% 在最终位置,6/12/24 的边界能看到下落中的粒子(重影带)。用户选 wipeDrop = 0 ✅
  • DOM 端到端(/tmp/pt-wipe/dom-e2e.ts,注入生产 page-bg.js 原文 + 真 wasm + 虚拟时钟)53 项全绿 ✅ 关键几条:页首 deferred / 不 build / 不抽签;预热只拉 wasm;「揭示后立刻滚走」到货也不建帧;首次揭示 wipe_on[0, 71.856, 32](= 0×dpr2 / 1200ms÷16.7 帧 / 16×dpr2)+ 不 settle + 第 55 帧 burst 仍为 0(落地顿挫不抢跑)+ 覆盖随时间增长而第 12 帧仍 < 30%(自上而下);淡出没走完就滚回 → 不重建 / 不重抽 / 不重放显现 / 图不变 / 动画续上;淡出走完(0.8s)再回来 → build 2 + 换图 + wipe_on 仍只有 1 次 + settle 1;resize → resize[640,896,2.8] + 不重放显现;双击 / 切后台 / 回页首全部符合预期
  • deno task test 30 passed / 0 failed;hugo --minify 0 报错,产物 #pt-bg-config 实测含 "wipeDrop":0,"wipeDuration":2400,"wipeBand":16 ✅
  • 同日追加:thumpPower 1.4 → 0(落定后的「弹一下」关掉)。显现结束后引擎会从画布中心补一记 burst() 径向冲量(原「落地顿一下」),用户反馈「图片出现之后还会突然弹一下」,于是把力度设为 0 —— step() 里本来就是 phase === 'land' && THUMP_POWER > 0 才调 burst(),力度 0 时直接转 phase = 'idle' 交给 float_on(),不会卡住 rAF 链。JS 侧的默认值(cfg.thumpPower == null 时)一并从 1.4 改成 0,这样少传这个键也不会冒出来 ✅
  • 同日追加:wipeDuration 1200 → 2400(用户反馈偏快,慢一倍)。用生产参数直接喂真 wasm 复核时间线:wipe_on(0, 2400/16.7 = 143.71, 32) 返回 1,覆盖在 f≈12(200ms,插画顶部本身透明)开始出现、f=138(2.30s)顶到 56.7%、f=145(2.42s)tick() 归零 —— 总时长正好是从前的一倍,落地顿挫随后触发 ✅

下次建议

  • wipeDrop 与 wipeBand 会乘 lastDpr,但不随画布尺寸变化:手机窄屏(--page-bg-w 降到 min(170px, 46vw))时 16 CSS px 抖动带会占更大的相对高度 —— 若日后收到反馈,可把它改成按 cssH 的百分比
  • 波前扫完后的那 0.6–1.2s 亚像素蠕动用肉眼看不出来,但 tick() 仍在跑;若在意 CPU,可在 wipe_front 归零后加一个更粗的静止阈值(如 max_v < 0.2 直接停帧)
  • wipe_on 目前只作用于首次揭示;如果以后想让「换图」也带上场,只需把 showImage() 里的 first 条件去掉,但要注意与淡出闸门的 needsPick 交互

README 精简重写

完成的工作

  • README.md 115 行 → 27 行:这是个人博客,不是开源项目,原先那份像项目说明书的 README(仓库结构树、CI/CD 表格、主题同步步骤、命名约定、发布流程)是过重的重复 ✅
  • 只留:一句话定位(Hugo + sdttttt-paper 子主题)+ 线上地址 + 本地预览两条命令 + 写文章一句话 + 四条 deno task 常用命令,其余全部指向 AGENTS.md ✅
  • 顺手纠正了旧 README 里已经过时的两处:content/claudelog/ 早在 99d262c 已改名 content/changelog/、测试写的是 node:test 而实际是 Deno 内置 Deno.test ✅

遇到的问题

  • 无 ⚠️

验证结果

  • bunx prettier@3.9.6 --check README.md 通过 ✅