docs(readme): 修正校验脚本调用方式,标注跨机器产物不可复现 (#2)

- 三个代码块补 `cd ../_tooling`:脚本不在仓库里,按 README 原来的写法
  (在仓库根目录直接 `node _sp_logo_export.js`)会 MODULE_NOT_FOUND
- 标注 docs/logo 的 PNG 与 docs 截图跨机器不可复现:Windows 重跑与已提交
  版本逐字节相同(10/10 一致),WSL 重跑则 10/10 全变、阴影版最大通道差 255,
  判据两边都是 95/95。先写清楚,免得下次当成脚本坏了去"修"
- 顺带记录 _sp_logo_export.js 改为按 __dirname 定位仓库(支持 SP_REPO 覆盖),
  不再写死 D:/ 或 /home/ 绝对路径
This commit is contained in:
2026-10-29 14:59:52 +08:00
parent e09943fefb
commit 9ca33a0328
+17 -4
View File
@@ -81,14 +81,22 @@ docs/ README 用的界面截图
`docs/logo/` 里的图**只进仓库、不部署到站点**(`_sp_deploy.sh` 只覆盖 `index.html`),
所以线上访问 `https://password.yangyq.net/docs/logo/logo-1024.png` 会 404 —— 这是预期行为。
重新导出 logo(脚本在仓库外的 `_tooling/`,需要 `playwright` + `Pillow`):
重新导出 logo(脚本在仓库外的 `_tooling/`,需要 `playwright` + `Pillow`)。
**先 `cd _tooling/` 再跑**,脚本按 `__dirname/../simple_password` 定位仓库:
```bash
node _sp_logo_export.js # 输出到 docs/logo/:logo-{64,128,256,512,1024}[-flat].png
python3 _sp_logo_verify.py # 像素判据 95 项:白边比例 / 主体居中 / 阴影朝向 / 圆角
python3 _sp_logo_verify_falsify.py # 反证 6 条:证明上面那套判据抓得住 bug
cd ../_tooling
node _sp_logo_export.js # 输出到 docs/logo/:logo-{64,128,256,512,1024}[-flat].png
python3 _sp_logo_verify.py # 像素判据 95 项:白边比例 / 主体居中 / 阴影朝向 / 圆角
python3 _sp_logo_verify_falsify.py # 反证 6 条:证明上面那套判据抓得住 bug
```
> ⚠️ **不要在不同机器上重跑覆盖仓库里的 PNG**。仓库里这 10 张是在 Windows 侧生成的,
> 换到 WSL(或另一台机器)重跑,字体度量与阴影模糊实现不同,产物**逐字节全不一样**
> —— 实测 10/10 文件 md5 全变,阴影版最大通道差到 255。判据仍是 95/95 通过、
> 几何关系一致,但 diff 会是一大堆无法 review 的二进制变更。真要重跑就接受这一点,
> 别把它当成"脚本坏了"。
尺寸是 64/128/256/512/1024 五档,每档两版:`logo-N.png` 带品牌阴影(用于展示场合)、
`logo-N-flat.png` 无阴影(用于 favicon、深色底、贴边摆放)。画布是正方形,
白边控制在 shadow 8% / flat 3%(旧版 41%)。
@@ -98,6 +106,7 @@ python3 _sp_logo_verify_falsify.py # 反证 6 条:证明上面那套判据
改完 `index.html` 后建议跑一遍(脚本在仓库外的 `_tooling/`,配合 `jsdom` 与 `playwright`):
```bash
cd ../_tooling
node _sp_test.js # 功能判据(jsdom,78 条)
node _sp_visual.js # 真实浏览器几何 / 对比度 / 多视口(114 条)
node _sp_clip.js # 真实剪贴板端到端(19 条)
@@ -113,10 +122,14 @@ node _sp_visual_falsify.js # 反向注入,证明几何判据有牙齿(6
重拍 README 截图:
```bash
cd ../_tooling
node _sp_shots.js # 输出到仓库 docs/:dark.png / light.png / mobile.png
node _sp_shot_verify.js # 断言被截图的那个页面状态是对的(26 条)
```
> ⚠️ 截图同样是**跨机器不可复现**的:手机视口实测 Windows 780×2490、WSL 780×2510,
> 字体度量差异导致高度不同。判据只断言几何关系,别断言绝对页高,也别拿另一侧的图覆盖仓库。
> 截图脚本与判据脚本分开,是因为判据脚本的截图(`_sp_shots` 目录)尺寸与时机跟着判据走,
> 会带 toast、焦点框、320px 极端视口;README 需要的是干净的产品图。混在一起改判据就会把图搞脏。