单文件网页构建器
概述
产出一个自包含的单 HTML 文件：CSS、JS、图片（base64）全部内联，双击即可打开，
通过聊天/邮件/网盘分享都不会破图。附带一套经过真实交付验证的工具链，
把"素材 → 页面 → 自检 → 截图验收"串成可重复的流水线。
配套的完整设计系统（深色电竞风）与端到端经验都沉淀在 references/ 与 assets/ 里。
何时使用
- 用户要求做网页 / 个人主页 / 人物介绍页 / 作品集 / 落地页 / 宣传页
- 用户给了 docx、pdf、或一堆图片，要求"做成网页"
- 用户给了一个模板 HTML，要求照着做一版自己的
- 已有页面出现破图、区块嵌套错乱、多张卡片共用同一张图、体积过大等问题
- 需要把已有网页改成自包含单文件（图片内联）以便分享
不适用：需要后端、需要多页路由、需要真实接口交互的项目。
核心原则（先读这四条）
- 单文件 + base64 内联。不要产出
HTML + assets/目录结构——相对路径在预览面板、
聊天分享、邮件附件里都会失效。图片先压到 400px 宽 / q82 webp 再内联。 - 先写带
__IMG_x__占位符的模板，再用脚本注入图片。
绝不让模型直接输出含 base64 的巨型 HTML——既容易截断，也无法复核。 - 内容只取自用户给的素材。不编事实；衍生数字必须标口径（如"不完全统计"）；
缺图先用占位封面，并在脚注说明。 - 改完必须跑三项自检并真的看截图。静态检查全绿≠页面没问题。
快速开始
SK=~/.workbuddy/skills/single-file-page-builder
# 0) 首次准备环境（AVIF 素材与截图验收都需要）
python -m venv ~/.workbuddy/binaries/python/envs/default
<venv>/Scripts/pip install pillow pillow-avif-plugin playwright
<venv>/Scripts/python -m playwright install chromium
# 1) 图片素材压缩成网页用 webp（--mode avatar 用于圆形头像）
python $SK/scripts/prepare_images.py --src ./图片 --out ./_build/webp
python $SK/scripts/prepare_images.py --src ./队友 --out ./_build/webp --mode avatar
# 2) 基于骨架模板写自己的文案（图片保持占位符）
cp $SK/assets/template.html ./page.tpl.html
# 3) 注入图片产出终稿（先 --check 干跑）
python $SK/scripts/build_page.py --template page.tpl.html --img-dir ./_build/webp --check
python $SK/scripts/build_page.py --template page.tpl.html --img-dir ./_build/webp --out index.html --backup
# 4) 给已有页面增量补图（幂等，可重跑）
python $SK/scripts/inject_images.py array --html index.html --array HONORS \
--map champ.json --img-dir _build/webp --carry y --key-fields t --require r=冠军
python $SK/scripts/inject_images.py dom --html index.html --map mates.json \
--img-dir 队友 --avatar-class av --heading h4 --avatar-radius
# 5) 发布前自检（三项互补，都要跑）
python $SK/scripts/validate_page.py --html index.html # 标签配平/占位符/JS语法/资源
python $SK/scripts/audit_images.py --html index.html --src 图片 --src _build/webp --label
python $SK/scripts/shoot_page.py --html index.html --out _shots --selectors "#honorGrid,.moments"
脚本速查
| 脚本 | 作用 | 关键参数 |
|---|---|---|
prepare_images.py |
素材 → 压缩 webp + base64 体积清单；自动报"内容相同的素材" | --src --out --max-width --quality --mode card\|avatar |
build_page.py |
占位符 → base64 注入，产出单文件；缺素材会中止 | --template --out --img-dir --map --check |
inject_images.py |
已有页面增量补图，幂等 | array 模式：--array --map --carry --key-fields --require；dom 模式：--map --avatar-class --heading --avatar-radius |
validate_page.py |
标签配平 / 占位符残留 / 内联 JS 语法 / 本地资源 / 体积 | --html --template --json |
audit_images.py |
每张内联图 md5 溯源，抓"一图多用"与素材重名 | --html --src（可重复）--label |
shoot_page.py |
无头渲染：控制台报错、破图、区块截图、整页长图 | --html --out --selectors --click --full |
validate_page.py 与 shoot_page.py 有问题时返回退出码 1，可直接串进流程判断。
工作流
完整的 7 步流程、决策点、以及"修改既有页面"的规范见 references/workflow.md。
开工前至少读一遍第 3 步（写占位符模板）与第 6 步（三项自检）。
资源
assets/template.html— 88KB 骨架模板：一套完整跑通的设计系统（导航/首屏/简介/数据/
时间轴/荣誉列表/表格/队友/评价/页脚 + 11 类动效），图片位置是 23 个__IMG_x__占位符。
改造指南、占位符清单、逐区块行号对照表见references/template-guide.md。assets/demo/donk-homepage.html— 完整成品（780KB 自包含，CS 选手介绍页）。
想知道"最终应该长什么样"就打开它；需要抄具体写法时看它。references/design-system.md— 设计 token、区块架构、动效清单、换配色方案、响应式断点。references/workflow.md— 端到端 7 步流程与工程规范。references/pitfalls.md— 踩坑清单。做图片相关操作前务必读第 1 节（素材重名、
文件名与内容不符、头像取景、低清混入）。
交付检查清单
- [ ]
validate_page.py全部通过（无占位符残留、无标签错配、JS 语法正确） - [ ]
audit_images.py无"一图多用"，素材目录无内容重复的文件 - [ ]
shoot_page.py无控制台报错、无破图，且已人工查看关键区块截图 - [ ] 页面总大小合理（23 张图的量级约 780KB；超 3MB 需重新压图）
- [ ] 移动端（≤560px）区块不溢出、导航抽屉可用
- [ ] 交付说明里列出：包含哪些区块、未使用的素材、待补项
- [ ] 告知用户改文案的方式：直接改标签之间的文字，base64 只出现在
src="data:image/..."与url(data:image/...)内部
