AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
docs(technical-design): add route, dataflow, invariant, and boundary references
hugohe34e71ac85e29f
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex cb6ed652..ec1c785c 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -63,6 +63,27 @@ Direct PPTX workflows intentionally bypass this SVG route:---+## Route Decision Quick Reference++Use this table before reasoning about implementation details. Most failed runs start with the wrong route, not the wrong command.++| Request shape | Route | Boundary |+|---|---|---|+| Topic only, no source file or substantive source text | `topic-research` first, then main pipeline | web/source collection is a pre-pipeline step |+| Source files or conversation text, deck structure may be rethought | main SVG pipeline | Strategist may split, merge, drop, reorder, and redesign |+| PPTX as source material, user allows a new story/page structure | `ppt_to_md` + `pptx_intake`, then main SVG pipeline | PPTX identity/geometry are facts and candidates, not replica constraints |+| Raw PPTX template plus new material/topic | `template-fill-pptx` | clone/fill native slides; no SVG generation |+| Existing PPTX, preserve page count/order/wording 1:1, improve layout | `beautify-pptx` | regenerate through SVG; content and pagination are locked |+| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | `native-enhance-pptx` | direct OOXML patch; no design regeneration |+| User wants a reusable template package from a PPTX or design reference | `create-template` or `create-brand` | outputs a directory that later triggers Step 3 |+| User supplies an explicit `templates/.../<id>/` directory with `kind: brand/layout/deck` | main SVG pipeline Step 3 | template segment ownership and fusion rules apply |+| User asks to tune object-level animation order/effect/timing | `customize-animations` | optional export policy via `animations.json` |+| User asks to preview, select, annotate, or re-export browser edits | `live-preview` | browser workflow; annotations apply only at defined handoff points |++Ambiguous "optimize this PPT" requests reduce to one discriminator: preserve the original page count/order/wording, or treat the deck as source material and rebuild the story. Preserve means `beautify-pptx`; restructure means the main pipeline.++---+## Technical Pipeline**The pipeline: AI generates SVG → post-processing converts to DrawingML (PPTX).**@@ -80,6 +101,33 @@ Post-processing scripts convert SVG to DrawingML. Every shape becomes a real nat---+## Artifact Flow++The workflow is easier to maintain if the artifacts are read as a dataflow rather than as folders that happen to exist:++```text+sources/<stem>.md ──────────────┐+analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spec_lock.md+analysis/image_analysis.csv ────┘++spec_lock.md + images/ + icons/ + templates/+ └─> Executor -> svg_output/+ ├─> svg_quality_checker.py+ ├─> finalize_svg.py -> svg_final/+ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx+ backup/<ts>/svg_output/++Direct OOXML routes:+analysis/<stem>.slide_library.json + source PPTX + fill_plan.json+ └─> template_fill_pptx.py -> exports/*.pptx+source PPTX project copy + enhancement plan + notes/audio/timing assets+ └─> native_enhance_pptx.py -> exports/*.pptx+```++The critical split is that `svg_output/` is authored state, while `svg_final/`, `exports/`, and `backup/` are derived delivery or archival state. Deleting that distinction makes validation, re-export, and manual repair much harder to reason about.++---+## Why SVG?SVG sits at the center of this pipeline. The choice was made by elimination.@@ -152,6 +200,25 @@ The CLI still supports three source-import modes: `--move`, `--copy`, and an aut---+## Architecture Invariants++These invariants are stronger than ordinary implementation preferences. If a change violates one, it is probably changing the architecture rather than refactoring it.++| Invariant | Practical consequence |+|---|---|+| `sources/<stem>.md` is the main-pipeline content contract | text, tables, and chart values come from Markdown in the main SVG route |+| `analysis/` stores machine facts, not design contracts | `source_profile.json` and intake artifacts inform Strategist; they do not lock page count/order except in workflows that say so |+| `design_spec.md` explains the design; `spec_lock.md` executes it | Executor reads locked values from `spec_lock.md`, not from prose memory |+| `spec_lock.md` is re-read before every page | colors, fonts, icons, images, rhythm, layouts, and chart choices stay stable across long decks |+| `svg_output/` is the only hand-authored SVG directory | quality checks, manual edits, re-export, and `update_spec.py` target authored source |+| `svg_final/` is derived | it can be regenerated from `svg_output/` and should not become the native export source of truth |+| Native PPTX export reads `svg_output/` by default | converter preserves icons, `preserveAspectRatio`, rounded rects, and native image crop metadata before finalization rewrites them |+| Direct OOXML routes do not enter the SVG pipeline | preservation workflows patch native PPTX parts directly |+| Image facts come from regenerated metadata | `analysis/image_analysis.csv` is re-derived from the live `images/` folder; agents do not inspect image pixels directly |+| Raw PPTX templates are not Step 3 templates | Step 3 consumes reusable template directories only |++---+## Canvas Format SystemPPT Master is not PPT-only — the same SVG → DrawingML pipeline produces square posters, 9:16 stories, A4 prints. Format-specific conventions (ratios, safe zones, brand areas) live in [`references/canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md).@@ -366,6 +433,25 @@ The interesting design choice is the animation **anchor**, not the effect list.---+## Maintenance Boundaries: What Not To Collapse++The tempting simplifications below have explicit costs. Treat them as negative contracts unless the surrounding architecture is deliberately redesigned.++| Do not collapse or add | Why |+|---|---|+| Do not fuzzy-match template names or style phrases to library paths | Step 3 must be deterministic; wrong template selection is harder to recover from than free design |+| Do not treat a raw PPTX template as a Step 3 template | raw PPTX template requests expect native slide cloning/filling, not SVG synthesis |+| Do not merge `template-fill-pptx`, `beautify-pptx`, and `native-enhance-pptx` into one "PPTX optimization" route | their preservation contracts differ: native fill, 1:1 redesign, and direct enhancement are separate operations |+| Do not script-generate batches of Executor SVG pages | cross-page design judgment depends on sequential main-agent authoring |+| Do not make `image_analysis.csv` a durable cache | `images/` is a live folder; facts must be regenerated on use |+| Do not make `svg_final/` the default native PPTX input | `svg_final/` is rewritten for self-contained preview, while native conversion needs high-fidelity `svg_output/` semantics |+| Do not auto-enable object-level entrance animations | page transitions are default; object builds are an explicit export policy |+| Do not default visual review, narration, chart verification, or animation customization into every run | these workflows have narrow triggers and extra dependencies |+| Do not replace `finalize_svg.py` with a file copy | finalization embeds icons/images, flattens special text, and prepares preview artifacts |+| Do not use `analysis/<stem>.slide_library.json` as a second source of chart values in the main pipeline | Markdown owns content values; intake chart/table entries are structural digests unless a direct-PPTX workflow owns them |++---+## Standalone WorkflowsStandalone workflows are route definitions, not optional decorations. They exist when a capability has a different contract from the main pipeline or is too sparse to justify loading by default.diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex f720d2d5..b1b6b2aa 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -63,6 +63,27 @@---+## 路线判定速查表++先用这张表判定路线,再讨论实现细节。大多数失败执行不是命令错了,而是一开始就走错了路线。++| 请求形态 | 路线 | 边界 |+|---|---|---|+| 只有主题,没有源文件或足够源文本 | 先走 `topic-research`,再进入主流水线 | 网络 / 来源收集是前置步骤 |+| 有源文件或对话文本,deck 结构可以重想 | 主 SVG 流水线 | Strategist 可以拆分、合并、删除、重排和重设计 |+| PPTX 作为源材料,用户允许重构故事和页结构 | `ppt_to_md` + `pptx_intake`,再走主 SVG 流水线 | PPTX 身份和几何是事实与候选,不是复刻约束 |+| 原生 PPTX 模板 + 新材料 / 新主题 | `template-fill-pptx` | 克隆并填充原生页面;不生成 SVG |+| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | `beautify-pptx` | 通过 SVG 重新生成;内容和分页锁定 |+| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | `native-enhance-pptx` | 直接 OOXML patch;不重新设计 |+| 用户想从 PPTX 或设计参考构建可复用模板包 | `create-template` 或 `create-brand` | 输出后续能触发 Step 3 的目录 |+| 用户提供明确的 `templates/.../<id>/` 目录且声明 `kind: brand/layout/deck` | 主 SVG 流水线 Step 3 | 应用模板片段所有权和融合规则 |+| 用户要求调整对象级动画顺序 / 效果 / 计时 | `customize-animations` | 通过 `animations.json` 控制可选导出策略 |+| 用户要求预览、选择、注解或重导出浏览器编辑 | `live-preview` | 浏览器工作流;注解只在规定交接点应用 |++“优化这份 PPT”这类含糊请求归约为一个判定点:是否保留原始页数、页序和逐页措辞。保留就是 `beautify-pptx`;允许重构就是主流水线。++---+## 技术流程**核心流程:AI 生成 SVG → 后处理转换为 DrawingML(PPTX)。**@@ -80,6 +101,33 @@ Executor 角色逐页生成演示文稿的视觉内容,输出为 SVG 文件。---+## 产物流++维护这套系统时,把文件夹理解成数据流会比“这些目录刚好存在”更清楚:++```text+sources/<stem>.md ──────────────┐+analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spec_lock.md+analysis/image_analysis.csv ────┘++spec_lock.md + images/ + icons/ + templates/+ └─> Executor -> svg_output/+ ├─> svg_quality_checker.py+ ├─> finalize_svg.py -> svg_final/+ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx+ backup/<ts>/svg_output/++直接 OOXML 路由:+analysis/<stem>.slide_library.json + 源 PPTX + fill_plan.json+ └─> template_fill_pptx.py -> exports/*.pptx+源 PPTX 项目归档副本 + 增强计划 + 讲稿/音频/计时资产+ └─> native_enhance_pptx.py -> exports/*.pptx+```++关键切分是:`svg_output/` 是作者状态,`svg_final/`、`exports/` 和 `backup/` 是派生的交付或归档状态。模糊这条线,会让校验、重导出和人工修复都更难推理。++---+## 为什么是 SVG?SVG 是这套流程的核心枢纽。这个选择是通过逐一排除其他方案得出的。@@ -152,6 +200,25 @@ CLI 仍支持三种导入模式:`--move`、`--copy`,以及“仓库内文件---+## 架构不变量++这些不变量强于普通实现偏好。如果某个改动破坏了其中一条,它很可能是在改变架构,而不是做重构。++| 不变量 | 实际后果 |+|---|---|+| `sources/<stem>.md` 是主流水线内容契约 | 主 SVG 路线中的文本、表格和图表数值来自 Markdown |+| `analysis/` 存机器事实,不存设计契约 | `source_profile.json` 和 intake artifact 辅助 Strategist;除非工作流明确规定,否则不锁定页数 / 页序 |+| `design_spec.md` 解释设计;`spec_lock.md` 执行设计 | Executor 从 `spec_lock.md` 取锁定值,而不是从叙述记忆里取 |+| 每页生成前重读 `spec_lock.md` | 长 deck 中的颜色、字体、图标、图片、节奏、布局和图表选择保持稳定 |+| `svg_output/` 是唯一手写 SVG 目录 | 质量检查、手工编辑、重导出和 `update_spec.py` 都面向作者源 |+| `svg_final/` 是派生产物 | 它可以从 `svg_output/` 重建,不应成为 native 导出的事实源 |+| native PPTX 默认读取 `svg_output/` | 转换器要在 finalize 重写前保留图标、`preserveAspectRatio`、圆角矩形和原生图片裁剪语义 |+| 直接 OOXML 路由不进入 SVG 流水线 | 保留型工作流直接 patch 原生 PPTX parts |+| 图片事实来自重算元数据 | `analysis/image_analysis.csv` 从实时 `images/` 目录重算;agent 不直接看图片像素 |+| 原生 PPTX 模板不是 Step 3 模板 | Step 3 只消费可复用模板目录 |++---+## Canvas 格式系统PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产出方形海报、9:16 故事、A4 印刷品。各格式特定的约定(比例、安全区、品牌区等)住在 [`references/canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md)。@@ -366,6 +433,25 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份---+## 维护边界:不要合并什么++下面这些“简化”都有明确代价。除非要有意识地重新设计周边架构,否则应把它们视作反向契约。++| 不要合并或新增 | 原因 |+|---|---|+| 不要把模板名或风格短语模糊匹配到库路径 | Step 3 必须确定性触发;选错模板比自由设计更难恢复 |+| 不要把原生 PPTX 模板当作 Step 3 模板 | 原生 PPTX 模板请求期待的是克隆 / 填充原生页面,不是 SVG 合成 |+| 不要把 `template-fill-pptx`、`beautify-pptx`、`native-enhance-pptx` 合成一个“PPTX 优化”路线 | 三者的保留契约不同:原生填充、1:1 重排、直接增强是三种操作 |+| 不要用脚本批量生成 Executor SVG 页面 | 跨页设计判断依赖主代理逐页连续创作 |+| 不要把 `image_analysis.csv` 当持久缓存 | `images/` 是实时工作目录;事实必须按需重算 |+| 不要让 `svg_final/` 成为 native PPTX 默认输入 | `svg_final/` 为自包含预览而重写,native 转换需要 `svg_output/` 的高保真语义 |+| 不要默认开启对象级入场动画 | 页面转场是默认;对象 build 是显式导出策略 |+| 不要把 visual review、旁白、图表校准或动画定制默认塞进每次运行 | 这些工作流触发范围窄,且有额外依赖 |+| 不要用文件复制替代 `finalize_svg.py` | finalize 会嵌入图标 / 图片、展开特殊文本并准备预览产物 |+| 不要在主流水线里把 `analysis/<stem>.slide_library.json` 当作第二份图表数值来源 | Markdown 拥有内容数值;除非直接 PPTX 工作流接管,否则 intake 图表 / 表格条目只是结构摘要 |++---+## Standalone Workflows(独立工作流)独立工作流是路线定义,不是可有可无的装饰。只有当某个能力与主流水线契约不同,或触发频率太低、不值得默认加载时,才会独立成 `workflows/<name>.md`。