歸藏 PPT Skill:两套锁定视觉系统 + 三个校验器的网页演讲 deck 工程规范
op7418/guizang-ppt-skill
歸藏(op7418)开源的网页演讲 deck skill,AGPL-3.0,主语言 HTML,26,809★。它不是「帮你写 PPT 文案的 prompt 模板」,而是一套让 agent 稳定产出可上台演讲的单文件 HTML 横向翻页 deck 的工程规范——README 首屏交代来历:这些规则从作者本人「一人公司:被 AI 折叠的组织」「一种新的工作方式」等线下分享里一轮轮踩坑沉淀,每个坑都进了 references/checklist.md。选 HTML 而非 PPTX 的关键理由是 HTML/CSS 是文本,agent 能直接读、改、验证:脚本可以量出「这一页溢出多少 px」,还能被 Playwright 真实渲染后做视觉核对。核心资产是两套类名互不通用、约束强度完全不同的视觉系统:Style A(电子杂志 × 电子墨水,10 种可粘贴布局骨架,5 套主题色,中文大标题 ≤5 字且 nowrap)、Style B(瑞士国际主义,22 个具名版式 S01–S22 锁定,正文页只能从中选并写 data-layout,4 套锚点色 IKB #002FA7 / #FFD500 / #C5E803 / #FF6B35,直角无渐变无阴影,大字字重必须 200)。最反直觉的一条决定是不允许自定义 hex:用户给任意颜色时 agent 要委婉拒绝并把预设摊开让选,SKILL.md 原话是「保护美学比给自由更重要」。区别于普通模板集合的是三个校验器 + 一条修正阶梯:validate-swiss-deck.mjs 静态查登记版式、图片槽位、SVG 内写字、标题对齐,有 Playwright 时再量 DOM 溢出 px、底部留白、导航安全线与标题间距;validate-presenter-mode.mjs 查页面 ID 重复、备注错位、时长超目标 90% 预算、控件缺失;check-presenter-runtime-sync.mjs 专拦两套模板之间演讲者运行时的漂移。并禁止凭感觉大改:溢出 1–40px 只微调、40–90px 局部压缩间距、90–160px 才压标题或拆页、160px 以上才允许换版式或删内容。内置全本地演讲者模式(按 P 进入,双窗口同步、结构化备注按 data-slide-id 存储而非页码、排练计时、激光笔与圈选、黑白屏与冻结观众屏,不依赖云端中继、手机遥控或 AI 教练),Codex 环境下还会主动问是否用 GPT-Image 2.0 配图并出公众号 21:9、小红书 3:4 等多平台封面。它自己写明了不适合的场景:大段表格数据、培训课件、多人协作编辑,也不能导出 PPTX。我们未实际安装跑出成品 deck,记为待复现。
我们的判断把网页 PPT 做成脚本可校验的工程规范:两套锁定版式系统 + 三个校验器 + 一条按 px 分级的修正阶梯(1–40 微调 / 40–90 压间距 / 90–160 拆页 / 160+ 才准删内容),再加全本地、带排练计时的演讲者模式。最值得抄走的是「不允许自定义 hex」这条产品约束——它把审美正确性当成不可协商的需求来管,而不是留给模型自由发挥。我们未实际跑出成品,记为待复现。
npx skills add https://github.com/op7418/guizang-ppt-skill --skill guizang-ppt-skill它解决的到底是什么问题
歸藏（op7418）做的这个 skill 不是「帮你写 PPT 文案的 prompt 模板」，而是一套让 agent 稳定产出可上台演讲的单文件 HTML 横向翻页 deck 的完整工程规范。AGPL-3.0，主语言 HTML，26,809 stars。它的来历写在 README 第一屏：这些规则是从歸藏本人在「一人公司：被 AI 折叠的组织」「一种新的工作方式」等线下分享里一轮轮踩坑沉淀出来的，每一个坑都进了 references/checklist.md。
为什么是 HTML 而不是 PPTX，README 给了四条理由，我们认为第二条才是关键：HTML / CSS 是文本，agent 能直接读、改、验证。PPTX 是二进制包，agent 改一页要靠库间接操作，改完无法自查渲染结果；HTML 可以用脚本量出「这一页溢出多少 px」，还能被 Playwright 真实渲染后做视觉核对。交付也更轻——单文件直接双击打开、演示、发送、截图，演讲者工具随文件一起交付。
两套互不通用的视觉系统
这个 skill 最容易误解的地方是：Style A 和 Style B 不是「换一套 CSS」，而是两套类名互不通用、约束强度完全不同的版式系统。SKILL.md 里反复强调——同名 class 在两个模板里视觉表现完全不同，例如 h-hero 在风格 A 是 Noto Serif SC 衬线，在风格 B 是 Inter 无衬线 weight 200。
| 维度 | Style A · 电子杂志 × 电子墨水 | Style B · 瑞士国际主义 |
|---|---|---|
| 模板 | assets/template.html | assets/template-swiss.html |
| 字体分工 | 衬线标题（Noto Serif SC + Playfair Display）+ 非衬线正文 + 等宽元数据 | 全程无衬线（Inter + Helvetica + Noto Sans SC），任何衬线都是错的 |
| 背景 | WebGL 流体 / 等高线 / 色散，只在 hero 页透出 | WebGL 极细网格 + 点阵，正文页保持纯净底色 |
| 版式 | 10 种布局骨架，可直接粘贴 | 22 个具名版式 S01–S22，正文页只能从中选，每页写 data-layout，不许临时发明结构 |
| 主题色 | 5 套预设：墨水经典 / 靛蓝瓷 / 森林墨 / 牛皮纸 / 沙丘 | 4 套锚点色：克莱因蓝 IKB #002FA7 / 柠檬黄 #FFD500 / 柠檬绿 #C5E803 / 安全橙 #FF6B35 |
| 硬约束 | 中文大标题 ≤5 字且 nowrap；图片网格只用 height:Nvh 不用 aspect-ratio | 直角、无渐变、无阴影、无圆角；1px hairline；主标题与正文字号比 ≥8:1；大字字重必须 200，禁止 600/700/800 大字；KPI 必须是屏宽 18–22% 的 Data Hero |
| 美学锚点 | 像 Monocle 杂志贴上了代码 | Massimo Vignelli / Helvetica Forever / Müller-Brockmann 网格系统 |
最反直觉的一条设计决定：不允许自定义 hex 值。用户给任意颜色时，agent 要委婉拒绝并把预设摊开让选，也不许混搭（ink 取一套、paper 取另一套）。SKILL.md 的原话是「颜色搭配错了画面瞬间变丑，保护美学比给自由更重要」。这不是偷懒，而是把「审美正确性」当成产品约束来管理——和我们看到的大多数「什么都能配」的模板系统正好相反。
把版式质量做成可测量的东西
这是它区别于普通 PPT prompt 集合的地方：三个校验器 + 一条修正阶梯。
| 脚本 | 拦什么 |
|---|---|
scripts/validate-swiss-deck.mjs | 静态检查登记版式、图片槽位、SVG 内写字、标题对齐、危险 SVG；可用 Playwright 时再量真实渲染指标：M1 DOM/visual overflow（具体超出多少 px、最低与最高问题元素）、M1 bottom whitespace、M1 nav-safe（内容是否侵入底部分页安全线）、M2 title gap |
scripts/validate-presenter-mode.mjs | 缺失或重复的页面 ID、备注与页面错位、必填字段缺失或可选字段类型错误、完整时间计划超出目标时长 90% 预算、计时/排练/自动翻页/标注/演前检查/观众屏恢复控件缺失。支持 --target-minutes 30 |
scripts/check-presenter-runtime-sync.mjs | 两套模板之间演讲者 CSS / JS 的漂移——同一个运行时被拷进两个模板，久了必然分叉，这条专门拦它 |
更值得学的是它禁止凭感觉大改。SKILL.md 的「先量后改」给了明确的修正阶梯：溢出 1–40px 只微调（上移内容组或收紧一个 gap，不许删内容）；40–90px 局部压缩间距；90–160px 才轻微压标题或拆页；160px 以上才允许换版式、合并模块或删内容。修完再跑一次，如果 bottom whitespace 反而变大，说明修过头了。同时明确写了「代码只能证明类名和结构存在，不能证明版式舒服」——必须打开网页逐页看，截图前等入场动效稳定 1–2 秒，别把动画中间态当版式问题。
Step 3.0 类名预检：所有生成问题的源头
SKILL.md 用「最重要」标注这一节。layouts 骨架里用了大量类名，如果模板 <style> 里没有对应定义，浏览器会 fallback 到默认样式——大标题字体错、卡片挤成一团、pipeline 糊成一行、图片堆到页面底部。规则是：写任何 slide 代码之前先读当前模板（至少读到 <style> 块末尾），对照 layouts 文件的 Pre-flight 清单确认每个类都存在；缺类就在模板的 <style> 里补上，不要在每个 slide 里 inline 重写；模板是类名的唯一来源，需要自定义用 style="..." inline，不要发明新类名。
紧跟着的 Step 3.0.5「主题节奏规划」被标成同等重要，而且是可以 grep 验证的硬规则：每页 <section> 必须带 light / dark / hero light / hero dark 之一（不许只写 hero）；连续 3 页以上同主题不允许；8 页以上必须有至少一个 hero dark 和一个 hero light；整份 deck 不能只有 light 正文页；每 3–4 页插一个 hero 页。生成后 grep 'class="slide' index.html 把节奏列出来人工确认再交付。
演讲者模式：全本地，没有云端中继
两套模板内置同一套演讲者运行时，打开 deck 后点右下角 P 进入。它不依赖实时字幕、云端中继、手机遥控或 AI 教练服务——双窗口同步、备注、计时、排练、自动翻页、标注全部在本地 HTML 与浏览器里完成。
能力清单比我们预期的长：当前页与下一页上下排列并始终保持 16:9（小屏整页等比缩放，不裁切不挤压）；宫格选页在预览区原位切换；结构化备注把标题、本页目的、讲述要点、转场设为必填，互动/语气/翻页时机/备用方案/读音只在大纲提供时才显示；底栏分别显示已进行、本页、剩余与超时时间；排练模式记录每页实际时长与整场汇总，数据存本地浏览器且明确不做 AI 评分；自动翻页默认关闭，只有大纲给出停留秒数或用户在设置里开启全局间隔才启用，且打开宫格/设置/圈选、页面隐藏或观众屏失步时自动暂停；激光笔与圈选同步到观众屏；一键黑屏白屏或冻结观众屏，恢复后自动追平当前页；观众窗口关闭或心跳超时显示「未连接」并可一键重开；退出演讲自动关观众窗，浏览器不允许自关时观众端显示「演示已结束」。快捷键：← → 翻页、Home/End 首尾、G 宫格、L 激光笔、C 圈选、B/W 黑屏白屏、F 冻结、? 全部快捷键。
备注的数据结构设计得很细：每个 <section> 必须有唯一稳定的 data-slide-id，SPEAKER_NOTES 按页面 ID 存储而不是数组下标或页码——否则页面重排后用户在演讲者视图里改过的备注会串页。内容分工也写死了：slide 只放观众此刻必须看见的结论与证据，purpose 说明这一页在整场叙事里的任务，talk 补背景与判断依据而不逐字复述 slide，transition 解释为什么下一页紧接着出现，minutes（讲述计划）与 autoAdvanceSeconds（播放行为）必须分开。没有来源支持的事实不能写进备注；影响正确性的缺失信息标「待补充」或问用户，不影响内容的可选信息直接省略。默认生成 3–5 条提词卡式要点而非逐字稿，总建议时长最多占用户时长的 90%，给停顿与意外留缓冲。
Codex 配图与多平台封面
在 Codex 环境里，deck 初稿完成后 skill 会主动问是否要用 GPT-Image 2.0 / GPT-M 2.0 生成配图——不默认生成。可选类型：人文纪实照片（富士/徕卡感的真实场景）、信息图与流程图与对比图与系统关系图、截图美化或截图再设计、数据大字报、多图拼贴（用于极宽槽位，避免把三张 16:9 硬塞进三列）。
四条配图硬规则值得单独抄下来：图片是嵌入素材，不许自带页脚、页底、标题、角标、页码或装饰边框；语言跟随 deck，中文 deck 的信息图用中文标签；比例先匹配落位，瑞士风主图 21:9、通用主图 16:9 / 16:10、截图再设计 16:10、网格统一高度；用户截图需要保真时先读 references/screenshot-framing.md，用 assets/screenshot-backgrounds/ 内置背景（style-a 5 套 / style-b 4 套）做 CleanShot X 式程序化缩放留边对齐，只有原图太乱太窄或需要概念化表达时才用生成模型重画。
同一套视觉规则还能出封面：公众号头图 21:9、公众号分享卡 1:1、小红书封面或轮播 3:4、视频号横版 16:9。原则和 PPT 一致——只用少量关键词，视觉重心落在大标题上，不堆正文。
工作流与文件加载顺序
Step 0 强制先检查上游更新（git fetch + rev-list --count HEAD..@{u}，大于 0 就问用户是否 pull --ff-only，不自动更新）。Step 1 是 7 问澄清清单，第一问必须先定风格 A 还是 B，因为那决定用哪个 template、layouts、themes 文件；其余六问覆盖受众与场景、分享时长（15 分钟约 10 页、30 分钟约 20 页、45 分钟约 25–30 页）、原始素材、图片与截图处理需求、主题色、硬约束。运行环境适配也写清了：Claude Code 用 Ask Question 逐项澄清，Codex 里不要假设这些工具可用，一次最多问 1–3 个最关键问题，信息缺口不影响开工就先做合理假设并说明。
没有大纲时用「叙事弧」搭骨架：钩子 1 页 → 定调 1–2 页 → 主体 3–5 页 → 转折 1 页 → 收束 1–2 页，然后叙事弧、页数规划、主题节奏表三张表对齐后才进 Step 2。正式演讲还要多一张表：页码 / 页面 ID / 章节 / 页面目的 / 观众可见信息 / 演讲者补充 / 建议时长 / 转场 / 可选现场信息。
资源按需加载，11 个 references 文件各管一段：components.md（字体色网格图标 callout stat pipeline 与动效）、layouts.md（风格 A 十种骨架）、swiss-layout-lock.md（风格 B 版式锁，正文页必须按它登记）、layouts-swiss.md（22P 骨架说明 + 少量明确标注的实验区）、swiss-map-component.md（S08 地图扩展，MapLibre 点位连线）、themes.md / themes-swiss.md、image-prompts.md、screenshot-framing.md、presenter-mode.md、checklist.md（P0/P1/P2/P3 分级）。动效方面 Motion One 的加载与 recipe 逻辑已内嵌在模板底部 module script，agent 只在 HTML 里加 data-anim / data-animate，不用改 JS；assets/motion.min.js（约 64KB）是离线兜底，断网自动降级为「无动画但内容可读」。
平台支持与适用边界
| 平台 | 状态 | 说明 |
|---|---|---|
| Claude Code | 支持 | 原生 Skill 工作流，适合生成与迭代 deck |
| Codex | 支持 | 适合生成 PPT、调用图片生成能力、做浏览器视觉检查 |
| Cursor / 其他本地 agent | 可用 | 需要能读写文件并执行 shell |
| WorkBuddy | 适配中 | 单独整理上架版本，去掉平台不需要的渠道差异 |
| 普通 chatbot | 不推荐 | 没有文件系统与浏览器预览时很难稳定生成完整 deck |
它自己写明了不适合的场景，这份坦率我们很欣赏：大段表格数据与图表叠加（用常规 PPT）、培训课件（信息密度不够）、多人协作编辑（这是静态 HTML）。也不能导出 PPTX——核心交付就是 HTML，可以浏览器演示、截图或录屏，需要 PPTX 时把 HTML 页面当视觉稿再转换，但那不是主流程。另外低功耗场景按 B 切到静态模式，关掉 WebGL / ASCII canvas 的 RAF 与 Motion 入场动画。
在 agientry 里的位置
我们把它收在 Agent Skills 的 documents（文档与办公）域，runtime 标 claude-code 与 codex——这是 README 明确「支持」的两档，Cursor 那档它自己写的是「可用」。它与 zarazhangrui/frontend-slides 是同一赛道的两种答案：frontend-slides 押注「让不会设计的人通过看预览发现自己的审美」，guizang 押注「把两套视觉系统的约束钉死到脚本可校验」。前者自由度高、模板池大（12 预设 + 34 个 bold 模板），后者一致性高、可验证性强（22 个锁定版式 + 三个校验器 + 修正阶梯）。做严肃的线下演讲、需要演讲者模式与排练计时的，选 guizang；需要快速试出视觉方向、或者要把既有 PPTX 转成网页的，选 frontend-slides。
诚实交代我们的验证边界：本篇全部结论来自通读 README.md（24.8KB）与 SKILL.md（632 行）原文，包括三个校验器的职责、修正阶梯的 px 阈值、演讲者模式的完整能力清单与快捷键、两套风格的类名清单与主题色 hex 值。我们没有实际安装并跑出一份 deck，因此「瑞士风 22 版式在真实内容下的还原度」「Playwright 度量项的实际拦截率」「演讲者模式在投影仪 + HDMI 现场的稳定性」均未经我们验证，记为待复现。