Skip to content

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.md
index 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 System
PPT 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 Workflows
Standalone 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.md
index 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`。