deck-design

name	deck-design
description	交付物生成工具：以假设驱动、证据分级和 Title Storyboard 为上游，使用统一 DeckSpec 与双引擎 Fusion 管线生成可审计的专业咨询 PPT；同时支持 Excel 测算底稿排版。 触发词：把这份分析做成PPT、出一份能直接汇报的演示文稿、产出ppt、帮我把测算结果整理成Excel、生成幻灯片。
allowed-tools	Read,Write,Bash

专业咨询 PPT 与 Excel 交付

目标是生成可直接用于高层决策的顶级咨询风演示：标题连读构成完整论证，每页只证明一个主张，正文证据能够证明标题，视觉节奏服务于内容。

品牌边界

• 只复制顶级咨询的结构化表达、克制视觉和质量标准。
• 不使用麦肯锡 Logo、品牌模板、专有定制字体或其他受保护品牌资产。
• 不声称、暗示或标注“麦肯锡出品”“McKinsey produced”。
• 默认使用本包统一主题与可用系统字体；品牌要求以用户合法提供的品牌规范为准。

视觉完成度硬标准

• “咨询风”不等于白底文字堆叠。无图片时封面也必须使用深海军蓝 Hero 构图、明确焦点和克制几何元素；章节页使用深色转场，内容页保持高留白与强对齐。
• 全篇必须形成封面 / Hero 关键结论 / Supporting 证据 / Transition 转场的层级变化，不允许连续三页使用同构等宽卡片。
• 每页只设置一个视觉锚点和一个主强调色；数据比较优先使用可编辑图表、矩阵、时间线、瀑布或表格，不用大段项目符号冒充分析。
• 禁止楷体、书法体、表情符号、彩虹配色、厚阴影、伪 3D、随机渐变和无意义装饰图标。中文默认使用现代无衬线 Office 兼容字体。
• 精美必须建立在信息层级、证据关系和精确网格上；不得以整页图片栅格化换取“好看”，文本、图表、表格和基础图形必须可编辑。

强制输入链路

PPT 请求不得从主题或原始材料直接跳到版式生成：

• 有完整材料：材料诊断 -> Deck Brief -> Governing Thought -> Title Storyboard。
• 只有主题：先用 hypothesis-framing，必要时用 evidence-analysis，形成 Day-1 假设、证据缺口和默认商务假设，再进入 Deck Brief。
• 信息不足时使用标记为 [A]/[E] 的专业默认假设推进，不得纯反问。
• 默认同一轮从骨架自动推进到成品。只有用户明确要求“先审大纲/故事线”时，才在 D2 Gate 后暂停。

D0-D7 端到端流程

D0 意图对齐与材料诊断

明确受众、决策、场景、页数、时限、已有材料、数据口径和敏感边界。识别事实、推断、假设、估算及证据缺口。输出 deck_brief.md。

D1 Governing Thought 与故事线

用金字塔原理组织唯一顶层结论；按 SCQA/SCR 或 Situation-Problem-Resolution 展开；分支必须 MECE。输出 storyline.md，包含 Executive Summary 草案与 Appendix 边界。

D2 Title Storyboard Gate

先只写行动标题，不写正文。标题连读必须让决策者理解完整论证；每个内容页标题是可被证据验证的完整主张，不是主题标签。未通过以下门禁不得选版式：

1. 顶层结论回答 Deck Brief 中的决策问题。
2. 标题链条呈现“背景/张力 -> 发现 -> 含义 -> 建议/行动”。
3. 相邻标题无跳步、重复或互相矛盾。
4. 每页只承载一个主张；Executive Summary 与正文标题一一对齐。
5. 事实与推断已映射到 claim_id，证据缺口显式标 [A]/[E]。

详见 references/storyline-system.md。

D3 Page Brief、Evidence Map 与视觉节奏

为每页确定：role、rhythm、visual_role、anti_pattern、density、objective、one_message、证据和来源。

• role：Hero / Supporting / Transition。Hero 建议占 20%-30%。
• rhythm：Peak / Valley / Transition，避免连续高密或连续过空。
• 非对称版式建议不少于 40%；相邻页面不重复同一版式，除非比较任务要求刻意一致。
• 版式由内容关系决定；图表由比较关系决定，并只突出一个信息。

D4 统一 DeckSpec 与 S3 内容门禁

把 Page Brief 写入唯一机器输入 deck_spec.json。禁止同时维护多套输入协议，禁止 Agent 手写 FusionDeck 调用代码。

统一字段和示例见 references/deck-spec.md。运行：

python3 scripts/gate_check_s3.py <project_dir>/deck_spec.json <project_dir>

gate_s3.json.passed 必须为 true。空 slides、页码不连续、未知版式、标签式标题、缺少页面语义字段、占位符、错误 evidence/source 结构均须失败。

D5 统一 Build CLI 生成

只允许使用统一 CLI：

python3 scripts/build_fusion_deck.py \
  --spec <project_dir>/deck_spec.json \
  --output <project_dir>/<name>.pptx \
  --result <project_dir>/build_result.json

CLI 同时支持 mck_ppt 主引擎和 mckinsey_pptx 补充引擎。任何一页失败、未知引擎/版式、实际页数不等于声明页数，整次构建必须失败，不得跳页或交付部分文件。

D6 S4 机读门禁、真实渲染与视觉 QC

先运行机读门禁，再执行渲染探测：

python3 scripts/gate_check.py <project_dir>/<name>.pptx <project_dir>
python3 scripts/render_preview.py <project_dir>/<name>.pptx <project_dir>

render_preview.py 优先使用 LibreOffice + pdftoppm 全量渲染；不可用时显式降级为 macOS Quick Look 首屏预览；若 Quick Look 也不可用，则只输出逐页结构报告并标记 mode=structure_only。所有模式都会写出 render_result.json。随后逐页执行 references/visual-qc.md：三秒测试、标题/正文证据、网格、字体、颜色、图表、Source、页码、占位符、数字一致性和可编辑性。

• 有 LibreOffice/PowerPoint 等真实渲染能力：必须全量逐页预览并记录视觉结论。
• 真实渲染不可用：允许用 macOS qlmanage 生成首屏预览，并按逐页结构报告审阅内容；Quick Look 也不可用时只能标记为 structure_only。两种情况都必须在交付说明中写明“视觉门禁已降级，未完成全量真实渲染”，不得声称全量渲染通过。
• gate_result.json.passed != true 或视觉 QC 有阻断项时，返回 D3-D5 修复。

D7 正式交付与质量审计

正式交付前必须加载 quality-audit，覆盖 Storyline、标题、证据、视觉和完整性。交付：最终 .pptx、门禁结果摘要、渲染状态、关键假设和待补证据。未经质量审计不得称为正式版。

统一项目产物

每个 PPT 项目目录必须保持以下契约：

<project_dir>/
  deck_brief.md
  storyline.md
  deck_spec.json
  gate_s3.json
  build_result.json
  gate_result.json
  render_result.json
  preview/
  <final-name>.pptx

不得用 content.json、outline.json 或 Agent 临时 Python 代码替代 deck_spec.json。最终文件默认落到 deliverables/consulting/ 下的独立项目目录。

双引擎选型

• 主引擎 mck_ppt：结构页、摘要、KPI、表格、流程、对比、矩阵、常规图表等。
• 补充引擎 mckinsey_pptx：甘特图、增长-份额矩阵、增强气泡图、历史/预测柱图等。
• 主引擎完整签名见 references/mck/framework/engine-api.md；补充版式见 mckinsey_pptx/agent/CATALOG.md。
• process_chevron 统一为 2-5 步，超过 5 步必须合并或拆页。

图表纪律

1. 时间趋势 -> 折线图；类别比较 -> 条形/柱形；构成 -> 堆叠或环形；增量归因 -> 瀑布图；双变量定位 -> 散点/气泡/矩阵。
2. 每张图只强调一个信息，用标题和单一强调色指出结论。
3. 图表必须由真实数据驱动；缺数据时用 [A]/[E] 明示，不得伪造。
4. Source 是结构化数组，在生成时统一渲染为页脚来源；Footnote 解释口径，不替代来源。

⚠️ deck_spec.json 数据格式（最高频失败点，必读）

铁律：data 字段中所有复合数据一律使用数组/元组格式，绝不传字典/对象。

引擎内部通过 Python 解包获取值。传入 {"key": "value"} 格式会导致页面显示 key 名称而非实际数据。

核心规则：

1. 所有复合字段用数组 [[a, b, c]]，不用 [{key: val}]
2. label/编号 ≤3 字符（推荐 "01"-"05"）
3. detail_items 是单个 \n 拼接的字符串，不是数组
4. col_widths 永远不传（传数字=列宽为零=文字竖排）
5. grouped_bar / horizontal_bar / swot 需要 RGBColor，JSON 无法用，改用替代版式
6. desc ≤50 字符

完整版式数据格式参考： 详见 references/layout-data-format.md（生成 deck_spec.json 前必须查阅）。

速查对照（最高频错误）：

版式	关键字段	✅ 正确	❌ 错误
two_stat/three_stat	stats	[["449亿", "标签", true]]	[{value, label}]
side_by_side	options	[["标题", "内容\n内容"]]	[{heading, points}]
process_chevron	steps	[["01", "标题", "描述≤50字"]]	[{label, detail}]
executive_summary	items	[["01", "标题", "描述"]]	["纯字符串"]
data_table	col_widths	不传	[8, 15, 22]

Excel 测算底稿

数据区与结论区物理分离：Sheet1 假设参数与来源；Sheet2 计算过程，公式引用 Sheet1；Sheet3 结果汇总。关键数字与 PPT 使用同一口径和 claim_id。