2026-10-06
维护记录
完成的工作
- 标定左下角粒子徽标的密度 / 清晰度上限,并按实测结果调参
$cfg✅- 改动文件:
themes/sdttttt-paper/layouts/partials/bg.html($cfg数值 + 上方新增实测标定注释)、themes/sdttttt-paper/assets/js/page-bg.js(GRAIN的说明注释,逻辑未动) - 参数变化:
pitchCss2 → 1.2、maxParticles60000 → 200000、sizeRatio0.85 → 0.95、graintrue → false、dprCap1.5 → 2 - 效果:
step5 → 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 耗时
实测出的三条机制(都验证过)
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→step5dprCap不参与密度计算,只决定sizePx的取整粒度与光栅锐度:size_css ≈ step × 0.4 × ratio,dpr 只影响它被floor/round到哪个整数。所以把 dprCap 从 1.5 提到 2(其余不动)时 step 和粒子数完全不变,只是size从 2 变 3 → 覆盖率 24.6% → 31.2%- 真正的密度硬上限在 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配maxParticles400k / 500k / 900k 各跑一遍都仍然卡在 step2 / 124,008 粒子
关键实测数据(单进程独立跑,避免 wasm 堆高水位污染)
| 配置 | step | sizePx | 粒子数 | 覆盖率 | wasm 内存 | build | settle |
|---|---|---|---|---|---|---|---|
| 改前(pitch2/r.85/dpr1.5) | 5 | 2 (1.33css) | 19,849 | 24.6% | 9.88MB | 1.3ms | 0.5ms |
| 仅 dprCap→2 | 5 | 3 (1.50css) | 19,849 | 31.2% | 10.88MB | 1.3ms | 0.6ms |
| 改后(本次采用) | 3 | 2 (1.00css) | 55,103 | 38.4% | 12.13MB | 1.9ms | 1.2ms |
| 密度极限(pitch0.9) | 2 | 2 (1.00css) | 124,008 | 55.7% | 14.31MB | 2.8ms | 2.5ms |
- 换图 / 换视口的稳定性(改后配置,dpr 2 下 170–320px 全宽度
size恒为 1.00 CSS px):F_tZfZBbwAALItU.pngstep3 / 55,103 粒子 / 覆盖率 38.4%FxC7q1YaUAE8SOL.pngstep3 / 35,891 粒子 / 覆盖率 25.0%GiG69PDa8AAvoeS.pngstep3 / 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→size1(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.png323,022 /GiG69PDa8AAvoeS.png230,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 量级:
maxParticles200000 → 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 / 单进程独立跑):
- 只动了
| maxParticles | step | sizePx | 粒子数 | 覆盖率 | build | settle | wasm 内存 |
|---|---|---|---|---|---|---|---|
| 200000(改前) | 3 | 2 (1.00css) | 55,103 | 38.4% | 1.50ms | 1.26ms | 12.13MB |
| 40000(改后) | 4 | 3 (1.50css) | 31,025 | 48.7% | 1.25ms | 0.91ms | 11.00MB |
- 换图后粒子数(dpr2 / cssW 320):
F_tZfZBbwAALItU31,025 /FxC7q1YaUAE8SOL35,891 /GiG69PDa8AAvoeS25,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新增三个旋钮thumpPower1.4 /breathPeak0.5 /breathPeriod4000,并把标定结论写进注释
- 动效三重闸(
motionAllowed()):html.at-bottom(徽标已揭示)+ 文档在前台 + 没切成真实图片;prefers-reduced-motion: reduce时直接settle()出成品,一帧都不动;旧 wasm 缺tick/burst/pulse时退化成静态粒子而不是报错 - 实测数据(首图
F_tZfZBbwAALItU.png,dpr2 / cssW 320 / pitch 2.4 / cap 40000,与线上完全同参):
| 阶段 | 帧数 | 耗时 | 峰值位移 | 备注 |
|---|---|---|---|---|
| land | 96 | 1.60s | 1226px → 0px | 弹簧自动收拢,无需参数 |
| thump | 40 | 0.67s | 3.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与为它写的 Bhaskarafast_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 + round | 3px | 15.97% | 630px(一条贯穿到底的白线) |
新 mode 2 + 出血 1 | 5px | 3.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–96 | 1.6s | 1226px → 0 | 弹簧自动收拢,无参数 |
| thump(落地) | 40 | 0.67s | 峰值 3.45px | burst(320,448,896,1.4) |
| idle(漂浮) | 常驻 | 周期 5.2s | 每粒子 ≤0.8 设备 px | float_on 一次,300 帧后 10.16% 的 framebuffer 字节发生变化 |
- 漂浮振幅安全性(剪影内孔洞,跑满一个完整周期 320 帧取最差帧):
floatAmp | 最差孔洞 | 相对静止 |
|---|---|---|
| 0.4 CSS px(采用) | 3.173% | +0.000 ✅ |
| 0.6 CSS px | 3.173% | +0.000 ✅ |
| 0.9 CSS px | 4.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 dev | 3.60% | 17px |
| 剪切 ampX 16 dev | 4.81% | 17px |
| 剪切 12 dev + ampY 3 | 3.77% | 59px ❌ |
| 径向 4 dev(2 css) | 0.51% | 59px |
| 径向 8 dev(4 css) | 1.17% | 59px |
| 径向 12 dev | 1.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):系列提交推送
参数微调(同日晚)
用户反馈「水波太大了,而且频率有点高」,于是压幅度、降速度,并把波纹的疏密也一并做成候选:
| 候选 | rippleAmp | rippleLength | ripplePeriod | 观感 |
|---|---|---|---|---|
| 原 | 4 | 60 | 3600 | 太大、太快 |
| B | 2.5 | 60 | 6500 | 半幅半速 |
| C | 2 | 42 | 6000 | 波纹更细密 |
| D(采用) | 2 | 80 | 7500 | 半幅、半速、再宽一号 |
- 四个候选各跑一个周期的 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 / 换图 /settle1 次 /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 testAGENTS.md:命令块补deno task test-wasm,wasm/particles/与「WASM 引擎」两条 bullet 补上测试位置与跑法
- 覆盖度(实测,rustc 1.99 +
llvm-tools-preview):lib.rs836 regions / 30 个函数 / 530 行 = 100%;tests.rs1319 regions 只差 2 个(setup()里锁中毒恢复用的|e| e.into_inner()闭包,除非有测试持锁 panic 否则跑不到)。复现命令写在tests.rs文件头 themes/sdttttt-paper/assets/wasm/particles.wasm逐字节未变(sha2562425081c…,测试是#[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_mode0/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/PaperModhugo.toml的mainSections注释:claudelog → changelog(目录在99d262c已改名)scripts/lib/frontmatter.ts头注释:PaperMod → hugo-paperscripts/lib/paths.ts头注释:去掉COVERS_DIR/exists()/ claudelog 这些已删概念的卖点
- 验证:
deno task test27 passed / 0 failed(原 28,去掉getStrings那组);deno check scripts/*.ts10 个文件全通过;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 test26 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 lint0 报错 ✅
遇到的问题
- 「没 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 test30 passed / 0 failed(原 26;新增trimUrlTail6 例、checkTitleAndDate5 例、formatSizeDelta3 例、listPublishedImages3 例、CLI 端到端 1 例)✅deno task lint0 报错;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.sofetch 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 = 60CSS 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.wasm31,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 次 +settle1;resize →resize[640,896,2.8]+ 不重放显现;双击 / 切后台 / 回页首全部符合预期 deno task test30 passed / 0 failed;hugo --minify0 报错,产物#pt-bg-config实测含"wipeDrop":0,"wipeDuration":2400,"wipeBand":16✅- 同日追加:
thumpPower1.4 → 0(落定后的「弹一下」关掉)。显现结束后引擎会从画布中心补一记burst()径向冲量(原「落地顿一下」),用户反馈「图片出现之后还会突然弹一下」,于是把力度设为 0 ——step()里本来就是phase === 'land' && THUMP_POWER > 0才调burst(),力度 0 时直接转phase = 'idle'交给float_on(),不会卡住 rAF 链。JS 侧的默认值(cfg.thumpPower == null时)一并从 1.4 改成 0,这样少传这个键也不会冒出来 ✅ - 同日追加:
wipeDuration1200 → 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.md115 行 → 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通过 ✅