WorkBuddy 演示设计助手（workbuddy-aesthetic-decks）

把资料转成可编辑、可演示、可离线分发的单文件 bento/slides deck，内置 15 套
专家级设计风格模板，并附带完整的设计风格系统参考
（references/design-styles.md）。相比直接让大模型写 HTML，
它把包豪斯、原研哉等经典流派落为可直接套用的版式规范与配色/字体配对，
成品风格统一、稳定可离线分发，不必每次从零调排版。

> 30 秒上手：① 说清主题/受众/场景，或直接点名风格模板 → ② 我先出「模板选择卡 + 叙事方向」方案，你确认（说"直接生成"可跳过）→ ③ 我 extract/起草 JSON → build 成 .bento.html → 跑结构/Shell 校验 → 交付可离线打开的演示文稿。全程不需要账号、API 或联网。

Router Rules

• 触发：用户明确提到 bento、.bento.html、单文件 HTML 演示文稿、离线可编辑 deck，或点名 $workbuddy-aesthetic-decks（原 $gaiying-bento-ppt）。
• 近邻：只说"做 PPT"且未指定格式时，优先使用通用 PPT skill；先确认是否接受 bento 格式。
• 不触发：明确要求 .pptx、Keynote、Google Slides；开发 bento 平台源码；制作 bento/spaces、bento/dash 或 bento/vault。
• 编辑已有 deck 时保留 docId、未知字段、collab 数据和原始 HTML shell；只改 #bento-doc。
• 新建 deck 时只生成一次 docId。禁止把既有文档当"新文档"重新生成身份。
• 不发布、不部署、不签名，不读取 ~/.bento/release-key.json。

Required Sources

开始制作前读取 references/workflow.md、
references/upstream-contract.md 和
references/design-styles.md（风格决策中枢：
选定风格后严格套用其配色、字体配对、布局节奏、视觉层次与响应式规范，
禁止跨风格混用颜色与字体）。

本 skill 自带固定版本的官方资料，按顺序读取：

1. references/upstream/bento-official-skill.md
2. references/upstream/bento-agents.md
3. references/upstream/bento-format.md

当前固定 release、commit、文件来源与 SHA-256 记录在
upstream.lock.json 与 NOTICE.md。普通 deck 任务禁止临时联网换最新版；
只有用户明确提出维护/同步上游时，才手动从同一官方 GitHub release 重新拉取
shell 与三份规范，并更新 NOTICE.md 中的版本与哈希。

用下面的命令检查独立资产：

python3 scripts/bento_deck.py locate

正常结果必须包含 "standalone": true。原始 bento checkout 不是前置条件。

内置模板库

templates/ 下内置 15 套精美模板，每套都是可直接打开、编辑、演示的完整
.bento.html（template: true，每次打开自动 mint 新 docId）。每套对应
references/design-styles.md 中的一种专家
设计风格，包含独立的配色方案、字体配对、布局节奏与视觉层次规范：

广义主题先给模板选择卡 + 默认建议；用户说"直接生成/跳过确认"时按默认模板
继续。拿不准风格时查 design-styles.md 的「风格选择决策表」。以模板为起点：
extract 模板 JSON → 替换内容 → build 为新文档。

你可以直接这样说

• "用 workbuddy-aesthetic-decks 把这份报告做成 12 页离线演示文稿。"
• "修改这个 .bento.html，保留 docId，增加 morph 和演讲者备注。"
• "跳过确认，按商务汇报模板生成一个单文件 HTML 发布会 deck。"
• "把这些数据做成可交互图表，并在浏览器里验收。"
• "帮我把这页周报做成能直接演示的网页。"（口语触发）
• "把这个发布会 PPT 改成包豪斯风格重做一版。"（风格重做触发）

一个完整例子（端到端）

用户：「把 Q2 增长复盘做成 10 页离线演示，偏商务风，桌面手机都得好看。」

1. 方案：默认给「商务汇报（Glassmorphism）」模板 + 2b 决策型叙事（现状→选项→权衡→建议→下一步），列出逐页结构，等你确认。
2. 出稿：extract 商务汇报模板 JSON → 替换为你提供的数据与结论 → build --new-document 生成 growth-q2.bento.html。
3. 校验：validate 结构无 error + Shell gate 通过；逐页核对无越界、无空 notes、关键文字 ≥18px。
4. 交付：给出 .bento.html、deck-plan.md、deck.json、校验报告；浏览器未实测处标 missing evidence。

整个流程不依赖任何外部服务，生成的文件可双击离线打开。

对话层异常处理

用户表达不清、选错模板或越界请求时，不要直接给方案，按定位 → 原因 → 方案三步引导。详细 FAQ 与反模式见 references/faq.md。

前置条件

• 运行时 Python 3.10+（python3 --version）
• 现代浏览器（Chrome / Edge）打开 .bento.html
• 如用外链图片或视频，自行保证网络可用性与版权

正常生成不需要 API key、账号、bento checkout 或云服务。

Compact Workflow

1. 判定交付物：确认新建还是编辑、语言、受众、场景、时长、比例、是否必须完全离线，以及用户是否明确要求跳过方案确认。
2. 先做方案：广义主题先给模板选择卡和 1a / 2b / 3c 叙事方向；形成 source-grounded deck-plan.md。用户说"直接生成/跳过确认"时可继续。
3. 读取官方规范：使用 skill 内置的官方 bento skill/agent/format 快照，禁止凭记忆发明字段。
4. 提取或起草 JSON：
   - 编辑：python3 scripts/bento_deck.py extract input.bento.html --output deck.json
   - 新建：从官方最小文档骨架起草；不带 collab、template、readonly。
   - 基于模板：extract 对应模板后替换内容，保留版式与动效。
5. 内容映射：数字→chart，规格/对比→table，连续变化→morph，展开细节→state slide，主视觉→image+scrim+ken-burns，流程→path/dash-march，关键数字→countUp。
6. 构建新文件：默认不覆盖任何输入。

python3 scripts/bento_deck.py build deck.json \
  --output result.bento.html \
  --new-document \
  --report reports/deck-validation.json

编辑已有 deck 时去掉 --new-document，用原文件同时锚定身份和 shell：

python3 scripts/bento_deck.py build deck.json \
  --identity-source input.bento.html \
  --output input.updated.bento.html \
  --report reports/deck-validation.json

脚本会拒绝 deck.json 与原文件 docId 不一致的构建。只有用户明确要求时
才加 --overwrite。

7. 验证：结构校验、bento shell gate、真实浏览器打开、编辑态与演示态检查。视觉任务不能只以脚本通过作为完成证据。
8. 交付：给出 .bento.html、deck-plan.md、可选 deck.json、验证结果和仍属 missing evidence 的项目。

Authoring Rules

• 默认 1280×720；遵循实际 doc.size。常规内容保留约 96px 侧边距（留白风格 120–150px）。
• 每页一个视觉主语；画面与字幕/正文不要完整复读同一句。
• 一套主色、最多两套字体。不要用左侧彩色竖线、默认网格或施工线制造廉价层级。
• 遵循 design-styles.md 的通用排版公理：字号阶梯 ≥3 级（相邻层级 ≥1.4 倍差）、卡片内边距 ≥28px、元素间距 ≥20px、正文行高 1.5–1.7、每页元素 ≤8 个、装饰面积 ≤15%。
• 响应式底线：任何文字 ≥18px（页码 13px 除外）、正文对比度 ≥4.5:1、内容在 x∈[96,1184] 安全区内、封面/结尾核心信息保持在垂直中段 60% 区域。
• 使用真实图片、图标和数据；外部 URL 媒体会破坏离线承诺，必须明确说明。
• 同一对象跨页变化时使用稳定、确定性的 id；同一页的有效 morph key 不得重复。
• 每页写 speaker notes。控制文字密度，数字能图表化时不要堆文字。
• chart option 必须是纯 JSON；bar/line 数据用纯数字；禁止函数 formatter。
• 写入文档块时所有 < 转义为 \u003c，文档块中不得出现字面 script 结束标签。

Gate Ladder

• Structure gate：scripts/bento_deck.py validate 无 error。
• Shell gate：生成文件必须通过内部 gate。
• Identity gate：编辑时 docId 与源文件一致；新建时只 mint 一次。
• Quality gate：无越界、关键文字过小、空 notes、断链、无动效等未解释 warning。
• Browser gate：真实打开后检查封面、至少一页内容页、演示模式、字体/图片/图表和无横向溢出。
• Rollback boundary：默认写新文件；源 .bento.html 与源资料保持不变。
• 缺少浏览器、人工审阅、外部媒体可用性或发布安装证明时标为 missing evidence，不得写成"已验证"。

Output Contract

1. deck-plan.md：受众、目标、叙事弧、逐页结构、素材映射、视觉方向、证据来源。
2. deck.json：纯 bento/slides 文档数据；编辑场景保留身份和未知字段。
3. <title>.bento.html：可独立打开、编辑和演示的单文件交付物。
4. reports/deck-validation.json：errors、warnings、shell gate 和身份结果。
5. 简短交付说明：路径、页数、离线边界、已验证项、missing evidence。

Permissions And Exclusions

• 允许：读取用户指定资料和 skill 内置 shell/规范；在任务输出目录写计划、JSON、报告和新 deck；运行 Python 校验与本地浏览器。
• 需用户明确授权：手动联网更新 shell/规范、覆盖既有 deck、把大型媒体改成外链、修改 bento 项目源码。
• 禁止：发布/部署/release、触碰签名密钥、向 main 直接推送、把 token/cookie/账号写入 deck 或报告。

可选配置

风险与限制

• 默认写入计划、JSON、报告和新的 .bento.html；默认拒绝覆盖已有输出，明确需要时才加 --overwrite。
• 外链媒体会破坏完全离线承诺。
• 固定 shell 不自动升级；上游更新需手动重新拉取并做兼容性验证。
• 脚本通过不等于视觉正确；未实际打开浏览器时，标记 missing evidence: browser visual review。
• 本 skill 不执行 bento release、签名或部署，也不读取签名密钥。

反模式与常见问题速查

遇到卡点按「现象」查，详细解答与完整 FAQ 见 references/faq.md。

继续禁止的行为：跨风格混用配色/字体；堆文字、塞外链媒体；跳过方案确认直接出成品；编辑既有 deck 不传 --identity-source。

交付前质量自检清单

交付前逐条确认，任一不满足则标 missing evidence 而非「已验证」：

• [ ] 结构校验（validate）无 error；Shell gate 通过。
• [ ] 每页有演讲者备注（notes 非空）。
• [ ] 关键文字 ≥18px（页码 13px 除外），正文对比度 ≥4.5:1。
• [ ] 内容在 x∈[96,1184] 安全区内，无横向溢出。
• [ ] 数字已图表化，未堆成文字墙；每页元素 ≤8、装饰面积 ≤15%。
• [ ] 配色/字体严格来自选定风格，未跨风格混用。
• [ ] 外链媒体已显式标注联网依赖；离线内容无任何外链。
• [ ] 浏览器实测：封面、至少一页内容页、演示模式、字体/图片/图表正常。

致谢与许可

• nyblnet/bento：bento/slides shell、官方 skill、文档模型和格式规范。固定版本与 SHA-256 见 NOTICE.md。
• 本 skill 代码 MIT 许可，Copyright (c) 该影。
• 内置 bento 资产仍为 MIT 许可，Copyright (c) 2026 The Bento authors。见 NOTICE.md 与 THIRD_PARTY_LICENSES/bento-MIT.txt。

版权与联系：Copyright (c) 该影