guizang-ppt-skill 如何锁死瑞士风？validate-swiss-deck.mjs 版式校验系统深度拆解-平芜编程栈

guizang-ppt-skill 如何锁死瑞士风？validate-swiss-deck.mjs 版式校验系统深度拆解

【免费下载链接】guizang-ppt-skillAI-agent Skill for generating polished HTML slide decks: editorial magazine and Swiss layouts, image prompts, social covers, and a WebGL/low-power presentation runtime.项目地址: https://gitcode.com/gh_mirrors/gu/guizang-ppt-skill

guizang-ppt-skill 是一个生成单文件 HTML 网页 PPT 的 AI Agent 技能，内置「电子杂志风」与「瑞士国际主义风」两套视觉系统。其中瑞士风的版式最讲究，也最容易在 AI 生成时走样。为此项目内置了版式校验脚本 validate-swiss-deck.mjs，通过静态结构检查 + 真实渲染测量两条腿，把瑞士风 PPT 的每一页锁回 22 个登记版式。本文深度拆解这套版式校验系统的三层设计、测量指标与使用方法，帮你理解 AI 生成的瑞士风网页 PPT 为什么能"稳定好看"。

初印象：guizang-ppt-skill 生成的网页 PPT 长什么样

这个技能的核心能力是让 AI Agent 一次产出单文件 HTML 的横向翻页 PPT：CSS、WebGL 背景、翻页逻辑、演讲者模式全部内置，浏览器直接打开就能演示，不需要服务器，也不需要构建工具。

两套风格分工明确：

风格	视觉特征	适合场景
风格 A · 电子杂志 × 电子墨水	衬线大标题 + WebGL 流体背景 + 暖色	人文分享、行业观察
风格 B · 瑞士国际主义	全程无衬线、12 列网格、直角纯色、1px 发丝线、极致字号对比	科技产品、数据汇报、方法论

风格 B 只允许从 4 套高饱和锚点色中四选一：克莱因蓝 IKB、柠檬黄、柠檬绿、安全橙。仓库里自带的assets/screenshot-backgrounds/style-b/目录中就有对应主题的背景资产，可以直观感受瑞士风的网格与点阵语言：

为什么要"锁死"瑞士风？三类版式走样坑

瑞士国际主义的美是"结构化的美"：左对齐、吸附网格、单一锚点色。AI 生成时很容易出现"看起来像瑞士风，其实已经偏离原始模板"的情况，典型症状有三类：

发明未登记版式：模板只登记了 S01–S22 共 22 个正文版式（详见 references/swiss-layout-lock.md），但 AI 可能顺手写出P23、Swiss Image Split这类"自创页面"，破坏还原度。
排版习惯入侵：中文 PPT 常见的"大标题居中"、SVG 里写<text>标签，都是瑞士风的禁忌——正文标题必须左对齐、SVG 只允许画几何线条。
图片脱离槽位：21:9 的主图被塞进固定高度的短槽、object-position: top center把人脸裁掉、同组图片比例混用……图文页是最容易崩的地方。

光靠文档约束（"生成前硬规则"）还不够——AI 会遗忘。所以项目把规则做成了可执行的校验器：交付前跑一遍脚本，不合规的页面直接报错。

validate-swiss-deck.mjs 版式校验系统：三层防线

校验脚本位于 scripts/validate-swiss-deck.mjs，整体分成三层：静态结构检查 → Playwright 真实渲染测量 → 量化修正阶梯。

第一层：静态结构校验——22 个登记版式白名单

脚本先读取 HTML 文件、剥掉注释，再用正则提取所有<section class="slide">页面，逐页执行以下检查（违规记为 error，拿不准的记为 warning）：

检查项	规则	级别
版式登记	每页必须有`data-layout="Sxx"`，且只能是 S01–S22 或封面/尾页专用版式`SWISS-COVER-ASCII`/`SWISS-CLOSING-ASCII`	error
实验结构拦截	出现`P23/P24`、`Swiss Image Split`、`Evidence Grid`等未登记结构直接报错（加`--allow-experimental`可放行）	error
标题左对齐	顶部标题区域出现`text-align:center`或`align-self:center`报错；statement 类版式（S03/S09/S10、封面/尾页）豁免	error
SVG 禁文字	SVG 中出现可见`<text>`报错，标签必须用 HTML 网格/卡片承载	error
图片槽位绑定	每张`images/`本地图片必须写`data-image-slot`（如`s22-hero-21x9`）	error
S15/S16 图片格	重生成图片必须用`.frame-img.r-21x9`铺满槽位，禁止`fit-contain`和固定`vh`高度	error
S22 主图	必须使用`s22-hero-21x9`槽位；禁止`object-position: top center`（会裁脸），推荐`center 35%`	error

可以看到，校验器的规则与 references/swiss-layout-lock.md 中的「禁止清单」一一对应——文档里的每条硬规则，脚本里都有对应的正则。黄金基准则是仓库内的 assets/template-swiss.html，S01–S22 即从作者原始参考 PPT 快照的版式登记。

第二层：Playwright 真实渲染测量——M1 溢出与 M2 标题间距

静态检查只能证明"结构合规"，证明不了"渲染出来不溢出"。当环境中能解析到 Playwright 时，脚本会额外启动 Chromium（1600×900 视口，软件渲染，无需 GPU），等待字体加载完成后，对每一页做一次"可见元素级"的量化测量：

📐M1 DOM/visual overflow：同时量scrollHeight溢出和"最低可见元素"越界量，并附带问题元素的类名与文案标签（如.kpi-hero "18%"），一眼定位是谁撑破了页面。
📐M1 bottom whitespace：底部空白超过 170px 且内容高度占比不足 74% 时警告——专治"为了修溢出删掉一大块内容，修出巨空"的过修。
📐M1 nav-safe：内容最低点进入 93% 高的分页安全线时警告，防止 caption、脚注碰到底部翻页组件。
📏M2 title gap：量出标题与下一块内容之间的实际距离，大标题小于 32px、局部标题小于 14px 即警告，防止标题和正文"贴脸"。

测量前有一步很讲究的"降噪"：装饰层（ASCII 画布、颗粒层、点阵矩阵）、fixed 定位元素、占页面 82% 以上的绝对定位背景都会被排除，只统计真正承载信息的文字、图片、线条和色块——所以测出来的是视觉溢出，不是 box model 的假阳性。若 Playwright 不可用，脚本会跳过这一层并给出 warning，静态检查照常执行，属于优雅降级。

第三层：Overflow 修正阶梯——先量后改、不过修

报错信息不只是"超了"，还会按超出的像素数给出分档处理建议，这是 references/checklist.md 中"后验测量"方法论的直接落地：

超出量	脚本给出的修正档位
1–40px	只微调：上移内容或收紧一处 gap/padding，不要删内容
40–90px	局部压缩间距或降低一个模块高度，仍优先保留内容
90–160px	轻微压标题或压缩一段正文，必要时拆页
160px 以上	才考虑换更高容量版式、合并或删内容

修完再跑一次脚本：如果M1 bottom whitespace变大，说明修过头了——恢复部分间距即可。这个"测量 → 单档修正 → 复测"的循环，把版式调整从"凭感觉改 margin"变成了可收敛的工程过程。

如何运行瑞士风 PPT 版式校验：一条命令

在 skill 根目录下执行（将index.html换成你的 deck 文件）：

node scripts/validate-swiss-deck.mjs path/to/index.html

✅ 全部通过：输出Swiss deck validation passed: 8 slide(s).
❌ 存在 error：逐条列出Slide 3 (S22): ...格式的问题并退出码 1，可直接接进 CI 或 Agent 的交付前自检
🧪 实验版式：追加--allow-experimental参数放行 P23/P24 结构

正式演讲 deck 建议再配合另一条校验线：

node scripts/validate-presenter-mode.mjs path/to/index.html

scripts/validate-presenter-mode.mjs 负责页面 ID 唯一性、演讲备注错位、时长预算等检查，两者一个管"版式"、一个管"演讲运行"，共同构成交付前质检。

文件	作用
scripts/validate-swiss-deck.mjs	本文主角：静态检查 + Playwright 渲染测量
references/swiss-layout-lock.md	版式锁文档：22 个登记版式、图片槽位规则、禁止清单
assets/template-swiss.html	瑞士风黄金模板（golden source）
references/layouts-swiss.md	22 个版式的骨架说明与类名速查
references/themes-swiss.md	4 套锚点色预设（只能选不能自定义）
references/checklist.md	P0–P3 质量清单，含 M1/M2 后验测量方法论
scripts/validate-presenter-mode.mjs	演讲者模式校验（页面 ID、备注、时长）
SKILL.md	Skill 主文件：完整工作流与瑞士风硬规则