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(roadmap): add public roadmap (EN/ZH) with capability evolution, P0/P1 focus, and non-goals

hugohe3535f5784a5e8
diff --git a/README.md b/README.md
index 4d58f619..85ecaf3c 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ English | [中文](./README_CN.md)
<a href="https://www.hehugo.com/"><strong>About Hugo He</strong></a> ·
<a href="./examples/"><strong>Examples</strong></a> ·
<a href="./docs/faq.md"><strong>FAQ</strong></a> ·
+ <a href="./docs/roadmap.md"><strong>Roadmap</strong></a> ·
<a href="mailto:[email protected]"><strong>Contact</strong></a>
</p>
diff --git a/README_CN.md b/README_CN.md
index a61be109..49bae24c 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -23,6 +23,7 @@
<a href="https://www.hehugo.com/"><strong>关于何雨果</strong></a> ·
<a href="./examples/"><strong>示例下载</strong></a> ·
<a href="./docs/zh/faq.md"><strong>常见问题</strong></a> ·
+ <a href="./docs/zh/roadmap.md"><strong>路线图</strong></a> ·
<a href="mailto:[email protected]"><strong>联系我</strong></a>
</p>
diff --git a/docs/roadmap.md b/docs/roadmap.md
new file mode 100644
index 00000000..fc871936
--- /dev/null
+++ b/docs/roadmap.md
@@ -0,0 +1,145 @@
+# Roadmap
+
+[English](./roadmap.md) | [中文](./zh/roadmap.md)
+
+---
+
+> PPT Master is a solo-maintained open source project, driven by **priority rather than fixed timelines**. This roadmap is here to align expectations: what's being worked on, what's planned, and what's intentionally out of scope. Priorities shift with user feedback and real usage signals — no committed delivery windows.
+>
+> **Where we are**: AI generates SVG from scratch → converts to DrawingML for natively editable PPTX. The core axis is **pixel-fidelity across four renderers** (PowerPoint / Keynote / LibreOffice / WPS) **+ real native shapes**. Every direction below serves that axis.
+
+---
+
+## Recent capability evolution
+
+The past two months' structural capability growth. Single flags / incremental polish go to the commit log.
+
+### 2026-03 — Native PPTX route takes shape
+
+- **Direct export to natively editable PPTX** — `svg_to_pptx` adds glow / rotate / text-decoration / stroke-linejoin; the full SVG → DrawingML chain becomes usable
+- Chart / layout template JSON indexes ship, AI selection path connected
+
+### 2026-04 — Pipeline at scale
+
+- **Source-less generation**: `topic-research` workflow supports "topic only, no source files"
+- **PPTX export step-change**: SVG clipPath → DrawingML picture geometry, marker → native arrows, output consolidated to `exports/`
+- **Chart library expands to 70 templates + three icon libraries** (simple-icons / phosphor-duotone / brand-logo)
+- **`spec_lock.md` machine-readable contract**: Strategist locks the spec, Executor re-reads it before every page — cross-page consistency gets a real guarantee
+- **Per-element animation on by default** + recorded narration / video export ([`workflows/generate-audio.md`](../skills/ppt-master/workflows/generate-audio.md))
+
+### 2026-05 — Visual editing + AI image systematization
+
+- **Live Preview enters the main pipeline** ([`workflows/live-preview.md`](../skills/ppt-master/workflows/live-preview.md)) — browser preview, click elements to write annotations, say "apply my annotations" and the AI rewrites that region (built on [@WodenJay](https://github.com/WodenJay)'s [PR #85](https://github.com/hugohe3/ppt-master/pull/85))
+- **Replicate any PPTX as a template** ([`workflows/create-template.md`](../skills/ppt-master/workflows/create-template.md)) — PPTX → SVG reverse + OOXML theme / master / layout / asset extraction
+- **AI image three-dimension system** rendering × palette × type + Strategist h.5 lock, downstream consumes a fixed contract
+- **AI image `hero_page` dual-track** — local insert + full-canvas hero image coexist
+- **Brand identity preset subsystem** ([`workflows/create-brand.md`](../skills/ppt-master/workflows/create-brand.md)) — extract and reuse brand palette / typography / logo / voice
+- **Visual self-review workflow** ([`workflows/visual-review.md`](../skills/ppt-master/workflows/visual-review.md)) — rubric-based per-page check of AI-generated SVGs
+
+---
+
+## P0 — Active focus
+
+Strong rationale, work in progress.
+
+### 1. AI image: Font as an independent dimension
+
+The current three-dimension system is rendering × palette × type. **Font has no independent dimension**, so AI-generated images use model-default typefaces, missing the typographic conversation with the deck.
+
+Plan: add 4 Font tiers (clean / handwritten / serif / display), Strategist locks `deck_font` alongside other lock-ins at h.5, Image_Generator references the matching font description when embedding text.
+
+### 2. AI image: Type de-bloat
+
+There are currently 15 types (hero / background / portrait / typography / matrix / cycle / funnel / pyramid / map / scene / infographic / metaphor / flowchart / comparison / framework, etc.) mixing "internal composition" and "PPT role" — hard for the AI to pick correctly.
+
+Plan: collapse to ~6 core types (infographic / scene / flowchart / comparison / framework / timeline); hero / background / portrait / typography move into the `page_role` dimension; matrix / cycle / funnel / pyramid become framework sub-types; map becomes a scene sub-type.
+
+Large blast radius (13 type files + manifest schema), will land in stages.
+
+### 3. Capability-backing example decks (Style demo P0)
+
+As the community enters its growth phase, example decks shift from "show visual contrast" to "prove the capability bar" — making it obvious why Gamma / Manus-style tools can't replace PPT Master.
+
+P0 three picks each stress-test a core capability:
+
+- **Dashboard / data-dense report** — stress-tests real native shapes + complex chart structure. A page with 6-10 charts is where shape-vs-Excel-native paths diverge the most
+- **Brutalist newsprint / extreme information density** — stress-tests text position precision + cross-page consistency. Wall-to-wall small type with irregular columns only survives later editing because shapes are real
+- **Blueprint / isometric technical drawing** — stress-tests geometric shape generalization + chart structure extensibility. Whitepaper / product architecture / industrial design scenarios
+
+---
+
+## P1 — Planned, not scheduled
+
+### 1. Template architecture consolidation
+
+SKILL.md Step 3 (Template Option) has known inconsistencies (defaults to not reading `layouts_index.json` but issues soft prompts based on its contents, bare name resolution is ambiguous, `design_spec.md` fields are unstandardized). These are **intentional transitional state** — to be addressed in one pass when the architecture firms up, not as scattered fixes.
+
+Pre-requisites: `layouts_index.json` field convention, template naming convention, `design_spec.md` standard field set, brand-and-layout composition rules.
+
+### 2. AI image: Mood as an independent dimension
+
+Palette files currently carry "hue", "saturation" and "contrast/temperament" all together, making them long. Plan: extract an independent Mood dimension (subtle / balanced / bold), slim down palette files.
+
+### 3. P1 example decks
+
+- **Academic / IEEE style** — Times/Computer Modern serif + dual-column + formulae + numbered references. Editable PPTX academic papers are a real gap in the market
+- **Maximalism / Y2K cyber** — extreme palette + mixed renderings is the hardest combination to keep consistent, the cleanest evidence that Strategist h.5 lock-in works
+
+### 4. Model compatibility matrix doc
+
+"What can Claude / Codex / Gemini / domestic models actually produce" gets answered case-by-case in issues. Plan: a comparison doc covering minimum runnable model, recommended config, and measured performance per axis (alignment / cross-page consistency / chart structure).
+
+---
+
+## Non-goals
+
+The directions below come up repeatedly and have been evaluated as **not on the path**. Listing them is not a value judgment on the underlying need — they simply don't fit this project's main route. If you specifically need these capabilities, consider other tools or forking.
+
+### Read arbitrary PPTX templates → fill text only
+
+**Issues**: [#53](https://github.com/hugohe3/ppt-master/issues/53), [#118](https://github.com/hugohe3/ppt-master/issues/118)
+
+PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. "Parse existing PPTX placeholders + only refill text" is a different product shape requiring handling of arbitrary master / theme / placeholder systems — orthogonal to where this architecture invests.
+
+**The basic need is actually simple**: if you just need "replace Excel data into fixed positions in a PPT template", have the AI write a few lines of `python-pptx`. You don't need this pipeline.
+
+### Switch to native PowerPoint charts (Excel-native chart)
+
+**Issues**: [#99](https://github.com/hugohe3/ppt-master/issues/99), [#100](https://github.com/hugohe3/ppt-master/issues/100)-class
+
+Pixel-fidelity across the four renderers (PowerPoint / Keynote / LibreOffice / WPS) is the project's spine. Switching to native PowerPoint charts breaks that — the same PPTX renders different chart layouts across renderers. Charts as SVG is **by design**, not a capability gap.
+
+If you need data-driven native Excel charts, pick a different tool or manually replace charts in PowerPoint post-export — this project won't build that path in.
+
+### uv as default / required dependency
+
+**Issue**: [#111](https://github.com/hugohe3/ppt-master/issues/111)
+
+`pip + requirements.txt` is the only official install path because it works in every Python environment with no extra learning cost. uv is a fine tool, but making it default raises the bar for new users. If you personally prefer uv, use it in your fork — it won't affect the main line.
+
+### Pure speed optimization
+
+**Issue**: [#97](https://github.com/hugohe3/ppt-master/issues/97)
+
+In the cost / speed / quality triangle this project picks **quality**. ~20 minutes for a high-quality PPTX is the current reasonable point.
+
+Will do: indirect improvements via prompt slimming / cache hit rate.
+Won't do: trading quality for "throw a few pages together" speed.
+
+If speed-sensitive and quality-tolerant, Gamma / similar AI tools are a better fit.
+
+### CLI / SaaS / desktop app form factors
+
+The product form is firmly **chat-driven AI IDE skill** (Claude Code / Cursor / VS Code + Copilot / Codebuddy).
+
+Won't do: standalone CLI (`ppm`-style), SaaS web service, Electron shell. Any "make it run independently of chat" proposal will be declined. Chat is the interaction core, not a wrapper.
+
+---
+
+## Feedback channels
+
+- **Issues**: [github.com/hugohe3/ppt-master/issues](https://github.com/hugohe3/ppt-master/issues) — bugs / proposals
+- **Discussions**: [github.com/hugohe3/ppt-master/discussions](https://github.com/hugohe3/ppt-master/discussions) — usage / experience sharing
+- **Email**: [email protected]
+
+Before proposing a new direction, scan the **Non-goals** above. If your request falls there, it's unlikely to land — but we're happy to discuss other paths to your underlying need.
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
new file mode 100644
index 00000000..782da38a
--- /dev/null
+++ b/docs/zh/roadmap.md
@@ -0,0 +1,145 @@
+# Roadmap
+
+[English](../roadmap.md) | [中文](./roadmap.md)
+
+---
+
+> PPT Master 是单人维护的开源项目,按**优先级**而非时间表推进。这份 roadmap 用来统一对外预期:正在做什么、想做什么、暂时不打算做什么。优先级会随用户反馈和实际使用信号调整,不承诺时间窗口。
+>
+> 项目当前定位:**AI 从零生成 SVG → DrawingML 原生可编辑 PPTX**。这条路线的核心是「跨四渲染器的位置保真 + 真原生形状」,所有方向都围绕这条主轴展开。
+
+---
+
+## 近期能力演进
+
+近两个月的能力面扩张。只列结构性的,单 flag / 增量优化看 commit log。
+
+### 2026-03(真原生 PPTX 路线成型)
+
+- **直接导出原生可编辑 PPTX** — `svg_to_pptx` 补齐 glow / rotate / text-decoration / stroke-linejoin,整条 SVG → DrawingML 链路开始可用
+- 图表 / 布局模板 JSON 索引上线,AI 选型路径打通
+
+### 2026-04(管线规模化)
+
+- **无源生成**:`topic-research` 工作流支持「只给主题、不给源文件」
+- **PPTX 导出质变**:SVG clipPath → DrawingML picture geometry、marker → 原生箭头、输出归集到 `exports/`
+- **图表库 70 个 + 图标三库**(simple-icons / phosphor-duotone / brand-logo)
+- **`spec_lock.md` 机器可读契约**:Strategist 锁定后 Executor 每页强制重读,跨页一致性有了保证
+- **元素级动画默认开启** + 旁白音频 / 视频导出([`workflows/generate-audio.md`](../../skills/ppt-master/workflows/generate-audio.md))
+
+### 2026-05(视觉编辑 + AI 图系统化)
+
+- **Live Preview 进入主流程**([`workflows/live-preview.md`](../../skills/ppt-master/workflows/live-preview.md)) — 浏览器实时预览 + 点选元素写要求 + 「apply my annotations」让 AI 重做该区域(基于 [@WodenJay](https://github.com/WodenJay) [PR #85](https://github.com/hugohe3/ppt-master/pull/85))
+- **任意 PPTX 复刻为模板**([`workflows/create-template.md`](../../skills/ppt-master/workflows/create-template.md)) — PPTX → SVG 逆向 + OOXML 主题 / 母版 / 版式 / 资源提取
+- **AI 图三维系统** rendering × palette × type + Strategist h.5 锁定,下游消费固定契约
+- **AI 图 `hero_page` 双档** — 局部插图 + 整页主角图共存
+- **品牌身份预设子系统**([`workflows/create-brand.md`](../../skills/ppt-master/workflows/create-brand.md)) — 提取并复用品牌色板 / 字体 / Logo / 语调
+- **视觉自检工作流**([`workflows/visual-review.md`](../../skills/ppt-master/workflows/visual-review.md)) — 按 rubric 逐页自查 AI 生成的 SVG
+
+---
+
+## P0 — 正在推进
+
+立项依据强、近期会动手的方向。
+
+### 1. AI 图能力扩展:Font 独立维度
+
+现在的 AI 图三维系统是 rendering × palette × type。**字体(Font)目前没有独立维度**,导致 AI 在图里写文字时只能用模型默认字体,缺少与 deck 整体字体语言的呼应。
+
+计划:新增 4 档 Font(clean / handwritten / serif / display),Strategist 在 h.5 一并锁定 `deck_font`,Image_Generator 在图内嵌入文字时引用对应字体描述。
+
+### 2. AI 图 Type 反膨胀
+
+现有 15 个 type(hero / background / portrait / typography / matrix / cycle / funnel / pyramid / map / scene / infographic / metaphor / flowchart / comparison / framework 等),其中一部分是「内部构图」描述,一部分是「PPT 用途」描述,两类混在一起 AI 不好选。
+
+计划:折叠到约 6 个核心 type(infographic / scene / flowchart / comparison / framework / timeline);hero / background / portrait / typography 归入 `page_role` 维度;matrix / cycle / funnel / pyramid 作为 framework 子类;map 作为 scene 子类。
+
+影响面较大(13 个 type 文件 + manifest schema),会分阶段做。
+
+### 3. 能力背书型示例 deck(Style demo P0 三档)
+
+社区进入增长期后,示例 deck 的作用从「展示视觉反差」切换到「证明能力门槛」—— 让用户一眼看懂为什么 Gamma / 美图 / Manus 这条线替代不了 PPT Master。
+
+P0 三档选择都对应一项核心能力压测:
+
+- **Dashboard 仪表盘 / 数据密集报告** — 压测真原生形状 + 复杂图表结构。一页 6-10 个图表是 shape-vs-Excel-native 路径差异最大的地方
+- **Brutalist 报章 / 信息超密** — 压测文字位置精度 + 跨页一致性。满版小字 + 不规则栏宽,只有真原生形状才扛得住后期编辑
+- **Blueprint 工程图纸 / Isometric 等距** — 压测几何形状泛化 + chart 结构扩展。技术白皮书 / 产品架构 / 工业设计场景
+
+---
+
+## P1 — 想做但未排期
+
+### 1. Template architecture 整体收口
+
+SKILL.md Step 3(模板选择)当前的几处不自洽(默认不读 `layouts_index.json` 却基于库内容做软提示、bare 名称识别歧义、`design_spec.md` 字段未标准化)是**已知的过渡形态**,等模板架构整体定型后一次性收口,而不是散点修复。
+
+需要先定的:`layouts_index.json` 字段约定、模板命名规范、`design_spec.md` 标准字段集、品牌与版式的合成规则。
+
+### 2. AI 图 Mood 独立维度
+
+当前 palette 文件里同时承担「色相」「饱和度」「对比度」三类属性,文件偏长。计划抽出独立 Mood 维度(subtle / balanced / bold),palette 文件瘦身。
+
+### 3. P1 示例 deck
+
+- **学术 IEEE 风** — Times/Computer Modern 衬线 + 双栏 + 公式 + 编号引用。可编辑的 PPTX 学术稿是真稀缺品
+- **Maximalism / Y2K 赛博** — 极端 palette + 多 rendering 混搭最容易翻车,能正面证明 Strategist h.5 锁定有效
+
+### 4. 模型兼容性矩阵文档
+
+「Claude / Codex / Gemini / 国产模型分别能跑到什么水准」目前每次都在 issue 里答一遍。计划整理成一份对照文档,覆盖:能跑通的最低模型、推荐配置、不同模型在「对齐 / 跨页一致性 / 图表结构」各项的实测表现。
+
+---
+
+## 明确不做(Non-goals)
+
+下面这些方向被多次提过,已经评估并决定**不做**。列出来不是否定需求价值,而是说明它们与本项目主路线不匹配;如果你刚好需要这些能力,建议看其他工具或 fork 本项目走自己的路。
+
+### 读取任意 PPTX 模板 → 仅填充文字
+
+**对应 Issue**:[#53](https://github.com/hugohe3/ppt-master/issues/53)、[#118](https://github.com/hugohe3/ppt-master/issues/118)
+
+PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围绕完全可控的形状/文字/版式构建。「解析既有 PPTX 占位符 + 仅回填文字」是另一种产品形态,需要处理任意来源的母版 / 主题 / 占位符体系,与现有架构发力点正交。
+
+**基础诉求其实很简单**:如果只是「固定位置替换 Excel 数据到 PPT 模板」,直接让 AI 写一段 `python-pptx` 脚本即可,几行代码搞定,不需要本项目这套管线。
+
+### 改用原生 PowerPoint 图表(Excel-native chart)
+
+**对应 Issue**:[#99](https://github.com/hugohe3/ppt-master/issues/99)、[#100](https://github.com/hugohe3/ppt-master/issues/100) 类
+
+跨四渲染器(PowerPoint / Keynote / LibreOffice / WPS)的位置保真是项目主轴。改用 PowerPoint 原生图表会让「像素级一致性」破功——同一个 PPTX 在不同渲染器里图表会显示不同布局。图表用 SVG 是 **by design**,不是能力缺失。
+
+如果需要数据驱动的原生 Excel 图表,建议另选工具或在导出后用 PowerPoint 手动替换;本项目不会内置这条路径。
+
+### uv 作为默认 / 必需依赖
+
+**对应 Issue**:[#111](https://github.com/hugohe3/ppt-master/issues/111)
+
+`pip + requirements.txt` 是唯一官方安装路径,因为它在所有 Python 环境下都可用、不需要额外学习成本。uv 是好工具,但「让 uv 成为默认」会抬高新用户的入门门槛。如果你个人偏好 uv,完全可以在 fork 里用,不影响主线。
+
+### 纯速度优化
+
+**对应 Issue**:[#97](https://github.com/hugohe3/ppt-master/issues/97)
+
+成本 / 速度 / 质量三角下,本项目选择**质量优先**。20 分钟生成一个高质量 PPTX 是当前的合理点。
+
+会做:通过 prompt 精简 / 缓存命中率提升带来的间接改善;
+不会做:以牺牲质量为代价的「随便几页应付交差」式提速。
+
+如果对速度敏感且能接受质量下降,Gamma / 美图 AI 等竞品更合适。
+
+### CLI / SaaS / 桌面 App 形态
+
+产品形态明确为 **chat-driven AI IDE skill**(Claude Code / Cursor / VS Code + Copilot / Codebuddy)。
+
+不会做:独立 CLI(`ppm` 之类)、SaaS Web 服务、Electron 桌面壳。所有「让它脱离 chat 独立运行」的提案都会被拒。chat 是交互核心,不是包装层。
+
+---
+
+## 反馈渠道
+
+- **Issues**:[github.com/hugohe3/ppt-master/issues](https://github.com/hugohe3/ppt-master/issues) — 报告 Bug / 提建议
+- **Discussions**:[github.com/hugohe3/ppt-master/discussions](https://github.com/hugohe3/ppt-master/discussions) — 用法讨论 / 经验分享
+- **邮箱**:[email protected]
+
+提需求前先扫一眼上面的 **Non-goals**;如果你的需求落在那一节,多半不会被采纳,但欢迎讨论是否还有别的路径解决你的真实问题。