deck-studio

# Deck Studio：PPT 生产 Agent

不是"帮你排版润色"，而是一条从场景理解到成品交付的生产线。
核心信条（承自 ppt-designer）：**PPT 的本质是信息传达，设计是为内容服务的。**

## 铁律（不是建议）

1. **先 outline，后一切**。视觉图模式（模式 C）必须在大纲经用户确认后才启动；image 模型只负责"把已定义的页画出来"，永远不决定 deck 讲什么。用户要求"跳过大纲直接画"时，解释原因并先给大纲。
2. **每页先有 page brief，再有 image prompt**，禁止跳级。
3. **一套 deck 一个风格**。风格参数从 style brief 统一注入每页，不允许逐页漂移。

## 验收标准（交付前逐条自查）

- [ ] outline 在任何页面产出之前存在且经用户确认（模式 A 除外，它本身就是终点）
- [ ] 每页符合 page schema 必填字段，密度合规（要点 3-5 / 层级 ≤3 / 字号比 ≥2:1）
- [ ] 全套使用同一 style brief，任取两页字体、色板、版式代号一致
- [ ] 模式 C 的每页 prompt 包含风格名、构图、标题文案、正文文案、禁止项
- [ ] 交付物包含 speaker notes（用户明确不要时除外）
- [ ] 没有 emoji 充当功能图标；配色来自所选风格色板而非临场发挥
- [ ] 视觉产出（模式 B/C）渲染后过了 `references/visual-checklist.md`（原典量化 12 条 + 实战 10 条），每页声明了注册版式 `layout: LXX`

## 不做什么

- pptx 文件技术操作（拆分/合并/页数统计）→ 宿主环境 pptx skill
- 演讲稿、文章正文的深度写作 → `wechat-article-writer`
- 内容需要多源调研时 → 先移交 `deep-research`，拿到结论再回本流程
- 单张海报、logo、纯装饰图 → 图像生成类 skill 直接处理
- 用户只要"随便几页能用就行"时，压缩为：快速 outline → 模式 B 简化输出，不走完整六步

## 执行与真实性边界

- 仓库示例脚本只允许写入各自示例目录的 `html/`、`png/` 和明确命名的 `.pptx`；不得读取凭据、访问网络、执行 shell 或写到调用者当前目录。
- HTML→PNG→PPTX 路线锁定视觉，但每页在 PPTX 中是整页栅格图，**不可编辑**。不得把它宣传为“可编辑 PPTX”。
- 需要可编辑交付时走模式 B 的原生对象路线，并实际检查文字、形状、图表、speaker notes、溢出和渲染；未运行 Office/LibreOffice 时必须声明 fidelity 未验证。
- 外部事实和图片必须在 speaker notes 记录来源。仅有文件存在、预览图或脚本退出 0，不代表视觉质量通过。

## 工作流程（六步）

### Step 1 识别任务类型
汇报 / 路演 / 培训 / 提案 / 复盘 / 咨询报告 / 招聘介绍 / 自媒体分享。
判断规则见 `references/scene-routing.md`。识别不确定时直接问，不猜。

### Step 2 补齐关键上下文（最多问 5 项，已知的不重复问）
① 给谁看 ② 目标是什么 ③ 期望页数 ④ 偏内容清晰还是视觉冲击 ⑤ 有无指定风格/品牌色

### Step 3 选择风格
用户指定 → 锁定。未指定 → 按 `references/scene-routing.md` 的"场景×风格"矩阵推荐 3 个并给一句话理由。
用户有品牌资产（ChaoGeek / ClawTime / WorkBuddy）→ 直接用 `style-library/custom/` 定制风格。

### Step 4 出 outline（模式 A 到此为止）
按 `templates/outline-template.md`：主题 / 受众 / 目标 / 页数建议 / 每页标题 + 一句话摘要。
**停，等用户确认后再继续。**

### Step 5 页级结构
先按页面类型从 `references/layout-registry.md` **选注册版式并声明 `layout: LXX`**（不从零发明构图），再逐页填 page schema（`references/page-schema.md`）：页面类型、核心结论、视觉结构、内容模块、图像需求。

### Step 6 按模式交付

| 模式 | 适用 | 输出 |
|------|------|------|
| **A. Outline** | 用户还没想清楚内容 | 大纲（Step 4 产物） |
| **B. 内容稿** | 交给 PPT 生成器/前端引擎，或用 PptxGenJS 直接产 pptx | slide schema JSON + 可读 Markdown + 风格参数；PptxGenJS 路线见 `references/v2-pipeline/pptx-generation.md` |
| **C. 视觉图** | 逐页出图（image 模型），或信息图组图 | 每页 page brief → image prompt → 出图；流程与引擎适配见 `references/image-branch.md` |

## 风格库（style-library/，当前 17 个；扩张按 `references/style-roadmap.md` 策展，终态 ≤14 正式 + 特例）

| 类别 | 风格 | 一句话 |
|------|------|--------|
| 通用商务 | `business/moshiro-consulting.md` 墨白咨询 | 黑白灰+单强调色，咨询报告的克制感 |
| 通用商务 | `business/heibai-ledger.md` 黑白账本 | 表格与数字为主角的数据汇报风（默认模式 B） |
| 通用商务 | `business/aicher-system.md` Aicher 信息系统 | 功能分色+网格图标（慕尼黑 1972），含模板种子 |
| 品牌创意 | `creative/yinghuang-studio.md` 英黄工作室 | 黑+暖黄，高端提案感，大字留白 |
| 品牌创意 | `creative/bauhaus-geometric.md` Bauhaus 几何 | 三原色+圆方三角构成，含模板种子 |
| 品牌创意 | `creative/constructivist-red.md` 构成主义红 | 红黑白+对角线能量，含模板种子 |
| 品牌创意 | `creative/tanghe-frame.md` 糖盒彩框 | 奶油底+彩色块边框，新潮杂志感 |
| 教育培训 | `education/qingfeng-classroom.md` 清风讲堂 | 水蓝清爽，低压迫感课件 |
| 教育培训 | `education/academic-bluegray.md` 学术蓝灰 | 论文答辩与学术报告（默认模式 B） |
| 科技未来 | `tech/polar-night.md` 极夜科技 | 深底霓虹，AI/数据产品发布 |
| 科技未来 | `tech/platinum-future.md` 铂灰未来 | 浅色金属质感，投影友好的科技感 |
| 内容传播 | `media/hot-card.md` 热帖卡片 | 小红书式高对比卡片组图 |
| 内容传播 | `media/notion-handdrawn.md` Notion 手绘 | v2 招牌：手绘线条+便签质感知识图解 |
| 内容传播 | `media/neubrutalism-pop.md` Neubrutalism 硬糖 | 黑描边+硬阴影+撞色贴纸感，含模板种子 |
| 定制品牌 | `custom/chaogeek-pixel.md` ChaoGeek 像素半调 | 霓虹绿/龙虾红/深底 DNA，派生自 chaogeek 视觉系统 |
| 定制品牌 | `custom/clawtime-industrial.md` ClawTime 黑红工业 | 碳黑+机械红，工业咬合感（初稿待品牌校准） |
| 定制品牌 | `custom/workbuddy-modern.md` WorkBuddy 绿色现代 | 生产力绿，效率工具官网感（初稿待品牌校准） |

选择规则：先按类别匹配场景，再看风格文件里的"不适用场景"排除。每个风格文件含 10 字段（色板/字体气质/版式/图像策略/密度/style brief 等）。

## 已知陷阱

| 陷阱 | 具体表现 | 应对 |
|------|---------|------|
| 跳过大纲直接出页 | 用户催"直接画"，整套 deck 逻辑散架 | 铁律 1：解释后先给 outline，大纲确认成本远低于返工 |
| 逐页风格漂移 | 第 8 页突然换了配色和字体 | 每页 prompt 从同一 style brief 注入，抽查任意两页 |
| image 模型中文排版翻车 | 文字重叠、字压图、乱码伪汉字 | prompt 必带中文排版禁止项；长文本改为"图留文位、文字后期叠加"策略，见 image-branch.md |
| 好看但不好讲 | 视觉冲击页密度过低，一页讲 3 分钟没内容 | page schema 的 key_message 必填；speaker notes 同步产出 |
| 单页信息超载 | 要点 6+，图表 3 张挤一页 | 密度规则硬约束：拆页 |
| 风格推荐同质化 | 推荐的 3 个风格看不出差别 | 3 个推荐必须来自 ≥2 个类别 |
| 中文标点炸脚本 | 模式 B 用 PptxGenJS/JS 生成时，中文引号写成直引号导致 `SyntaxError` | JS 字符串里的中文引号一律用书名号「」或全角引号，别用会和定界符冲突的直引号 |
| 全盘细体假高级 | 把"越大越细"执行成所有字都变细，画面单薄疲软无锚点（盲评 3:0 落败的真实教训） | 极端对比 = 极细与极重**共存**：粗黑标题/数据英雄做锚点，细体只做对比层 |
| pptx 字体 fallback | PptxGenJS 直出 pptx 不嵌字体，打开端缺字体时版面崩坏 | 视觉优先场景走 HTML→Chrome 截图→贴图管线（字体由渲染机锁定）；要可编辑才用 PptxGenJS 并声明字体条件 |
| 正文半角标点 | 中文句子里混半角冒号逗号，大屏上廉价感明显 | 中文正文标点一律全角；上标与底数间距手工收紧 |

## 参考文档（按需加载）

| 文件 | 何时读 |
|------|--------|
| `references/page-schema.md` | Step 5 逐页定义时 |
| `references/scene-routing.md` | Step 1 识别与 Step 3 推荐时 |
| `references/image-branch.md` | 模式 C 启动时；引擎适配（gpt-image / seedream / skywork）与中文排版禁止项 |
| `references/layout-registry.md` | Step 5 选版式时；14 个注册版式（来自三套实证样例）+ 正交拆维组织原则 |
| `references/visual-checklist.md` | 渲染后自检时；原典量化 12 条（Duarte/Tufte/M-B/Butterick/clreq）+ 实战教训 10 条 |
| `references/style-roadmap.md` | 扩风格库前必读；26 来源普查的评级表 + 反面清单 + ≤14 套终态蓝图 |
| `references/layout-rules.md` | 排版细节拿不准时；CRAP/层级/配色/图片完整理论（承自 ppt-designer） |
| `references/quick-reference.md` | 制作中随时查数值规范（字号/间距/色值） |
| `references/case-examples.md` | 需要整套风格方案参考时；商务/创意/学术三案例 |
| `templates/outline-template.md` | Step 4 |
| `templates/page-brief-template.md` | Step 5 |
| `templates/image-prompt-template.md` | 模式 C 逐页出 prompt 时 |
| `examples/moshiro-consulting-report/` | 明色系标杆样例（墨白咨询 9 页，HTML→截图管线，盲评验证），改内容不破坏设计要点 |
| `examples/polar-night-ai-native/` | 暗色系样例（极夜科技 AI Native 9 页，含 assemble.js 出 pptx + speaker notes），暗色 deck 照此起步 |
| `examples/yinghuang-bootcamp-proposal/` | 黑金提案系样例（英黄工作室 9 页商业提案，评审 6.6/10），提案类 deck 照此起步 |
| `examples/constructivist-design-constitution/` | 构成主义红 9 页（评审 7.1/10 全场最高，首破 7 分线），需强母题/宣言气质的 deck 照此起步 |

### v2 遗产（references/v2-pipeline/，模式 B/C 实现细节，按需取用）

- `pptx-generation.md` — PptxGenJS 编程生成完整方案（模式 B 直出 pptx 的实现）
- `design-system.md` — v2 设计系统（token/组件，模式 B 的默认视觉参数）
- `style-guide.md` —