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: add positioning charter, doc indexes, and align README framing

hugohe373a8e9d6dc22
diff --git a/README.md b/README.md
index b243652b..5d3b1369 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ Thanks to [Kimi](https://www.kimi.com/code/?aff=ppt-master) for sponsoring this
</details>
-> **AI generates your deck — it doesn't fill in a template.** PPT Master is a workflow that runs inside AI IDEs (Claude Code, Cursor, VS Code + Copilot, etc.): hand the AI your PDF / DOCX / web pages, and it produces a real PowerPoint on your machine — every element editable in PowerPoint, your data stays local, no platform or model lock-in. How it works and where the limits are → [Product Positioning](#product-positioning).
+> **AI generates your deck — it doesn't fill in a template.** PPT Master is a workflow that runs inside AI IDEs (Claude Code, Cursor, VS Code + Copilot, etc.): hand the AI a topic, your PDF / DOCX / web pages, design references, or an existing deck, and it produces a real PowerPoint on your machine — every element editable in PowerPoint, your data stays local, no platform or model lock-in. How it works and where the limits are → [Product Positioning](#product-positioning).
<p align="center">
<a href="https://hugohe3.github.io/ppt-master/"><strong>Live Demo</strong></a> ·
@@ -115,11 +115,15 @@ Drop in your source material, and the deck you get back is **more than just edit
In form, it's not a website or an app but a workflow (a "skill") that runs inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy: you tell the AI in the IDE's chat — "make a deck from this PDF" — and it follows the workflow to produce a genuinely editable `.pptx` on your machine. No coding on your side; you do exactly three things — install Python, install an AI IDE, drop in your material.
+Generating a new deck from source documents is the main pipeline, but not the only route. PPT Master can also distill reusable brand / layout / deck templates from your references, fill an existing `.pptx` with new content while preserving its design, and add native transitions, animations, and narration to a finished deck — each route with an explicit contract for what gets preserved.
+
This form buys three promises that other tools struggle to make at the same time:
-- **Transparent, predictable cost** — the tool is free and open source; the only cost is your AI model usage. You pay exactly what you consume — no separate PPT subscription added on top
-- **Data stays local** — your files shouldn't have to be uploaded to someone else's server just to make a presentation. Apart from AI model communication, the entire pipeline runs on your machine
-- **No platform lock-in** — your workflow shouldn't be held hostage by any single company. Works with Claude Code, Cursor, VS Code Copilot, and more; supports Claude, GPT, Gemini, Kimi, and other models
+- **Transparent, predictable cost** — free and open source; the only cost is your AI model usage, with no PPT subscription on top
+- **Data stays local** — apart from AI model communication, the entire pipeline runs on your machine
+- **No platform lock-in** — any agent-capable AI IDE can drive it; Claude, GPT, Gemini, Kimi, and other models all work
+
+How these promises compare against Gamma, Copilot, and other tools → [Why PPT Master](./docs/why-ppt-master.md); the long-term capability boundaries behind them → [Project Positioning](./docs/project-positioning.md).
> [!IMPORTANT]
> ### This is a tool, not a wishing well
@@ -354,6 +358,7 @@ PPT Master reads the current process environment first, then the first `.env` fo
|---|----------|-------------|
| 📘 | [Getting Started](./docs/getting-started.md) | First deck in 3 steps, plus how to use templates, live preview, animations, narration, voice cloning (**new users start here**) |
| 🆚 | [Why PPT Master](./docs/why-ppt-master.md) | How it compares to Gamma, Copilot, and other AI tools |
+| 🧭 | [Project Positioning](./docs/project-positioning.md) | Long-term positioning, product promises, and capability boundaries |
| 🪟 | [Windows Installation](./docs/windows-installation.md) | Step-by-step setup guide for Windows users |
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules |
| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |
@@ -362,6 +367,8 @@ PPT Master reads the current process environment first, then the first `.env` fo
| 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |
| ❓ | [FAQ](./docs/faq.md) | Model selection, cost, layout troubleshooting, custom templates |
+<sub>Full documentation index → [`docs/`](./docs/README.md)</sub>
+
---
## Contributing
diff --git a/README_CN.md b/README_CN.md
index fffdcddd..688b8fc3 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -46,7 +46,7 @@
</details>
-> **AI 生成 PPT,不是 AI 套模板。** PPT Master 是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot 等)里运行的工作流:把 PDF / DOCX / 网页等材料交给 AI,它在你本机生成一份真正的 PowerPoint——每个元素都能在 PowerPoint 里点开修改,数据不出本地,不锁定任何平台和模型。工作原理与能力边界 → [产品定位](#产品定位)。
+> **AI 生成 PPT,不是 AI 套模板。** PPT Master 是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot 等)里运行的工作流:把一个主题、PDF / DOCX / 网页等材料、设计参考,或一份已有的 PPT 交给 AI,它在你本机生成一份真正的 PowerPoint——每个元素都能在 PowerPoint 里点开修改,数据不出本地,不锁定任何平台和模型。工作原理与能力边界 → [产品定位](#产品定位)。
<p align="center">
<a href="https://hugohe3.github.io/ppt-master/"><strong>在线预览</strong></a> ·
@@ -119,11 +119,15 @@
形态上,它不是网站也不是 App,而是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot / Codebuddy 等)里运行的工作流(一个 "skill"):你在 IDE 的对话框里说"用这份 PDF 做一份 PPT",AI 按这套工作流在你本机生成真正可编辑的 `.pptx`。你不写任何代码,要做的只有三件事——装 Python、装一个 AI IDE、把资料放进来。
+从源材料生成新 deck 是主管线,但不是唯一路线:PPT Master 还能从你的参考资料中提炼可复用的品牌 / 版式 / 成品模板,把新内容填进你已有的 `.pptx` 并保留其设计,或为成品 deck 追加原生转场、动画和旁白——每条路线都有明确的保留契约。
+
这个形态换来三个别的工具很难同时给出的承诺:
-- **成本透明可控** — 工具免费开源,唯一成本是你自己的 AI 模型用量,你用多少付多少,不在此之外增加任何订阅费用
-- **数据不出本地** — 你的文件不应该为了做一份 PPT 就被上传到别人的服务器。除与 AI 模型的对话外,全流程在你的电脑上完成
-- **不锁定平台** — 你的工作流不应该被任何一家公司绑架。Claude Code、Cursor、VS Code Copilot 等均可驱动;Claude、GPT、Gemini、Kimi 等模型均可使用
+- **成本透明可控** — 工具免费开源,唯一成本是你自己的 AI 模型用量,不在此之外增加任何订阅费用
+- **数据不出本地** — 除与 AI 模型的对话外,全流程在你的电脑上完成
+- **不锁定平台** — 任何具备 agent 能力的 AI IDE 均可驱动;Claude、GPT、Gemini、Kimi 等模型均可使用
+
+这些承诺与 Gamma、Copilot 等工具的具体对比 → [为什么选 PPT Master](./docs/zh/why-ppt-master.md);承诺背后的长期能力边界 → [项目定位与能力边界](./docs/zh/project-positioning.md)。
> [!IMPORTANT]
> ### 这是一个工具,不是一个许愿池
@@ -364,6 +368,7 @@ PPT Master 会优先读取当前进程环境变量,然后按顺序读取第一
|---|------|------|
| 📘 | [快速入门](./docs/zh/getting-started.md) | 三步做出第一份 deck,外加模板、实时预览、动画、旁白、声音复刻的用法(**新用户从这里开始**) |
| 🆚 | [为什么选 PPT Master](./docs/zh/why-ppt-master.md) | 与 Gamma、Copilot 等工具的对比 |
+| 🧭 | [项目定位与能力边界](./docs/zh/project-positioning.md) | 长期定位、产品承诺与能力边界 |
| 🪟 | [Windows 安装指南](./docs/zh/windows-installation.md) | Windows 用户手把手安装教程 |
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | 核心流程与规则 |
| 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 |
@@ -372,6 +377,8 @@ PPT Master 会优先读取当前进程环境变量,然后按顺序读取第一
| 🏗️ | [技术路线](./docs/zh/technical-design.md) | 架构、设计哲学、为什么选 SVG |
| ❓ | [常见问题](./docs/zh/faq.md) | 模型选择、费用、排版问题排查、自定义模板 |
+<sub>完整文档索引 → [`docs/zh/`](./docs/zh/README.md)</sub>
+
---
## 贡献
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..6f56a465
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,44 @@
+# Documentation Index
+
+[English](./README.md) | [Chinese](./zh/README.md)
+
+---
+
+User-facing documentation lives in this directory: English files are the canonical source, with synchronized Chinese translations in [`zh/`](./zh/README.md). Workflow and technical references consumed by the AI itself live under [`skills/ppt-master/`](../skills/ppt-master/SKILL.md).
+
+## Getting Started
+
+| Document | Description |
+|---|---|
+| [Getting Started](./getting-started.md) | First deck in 3 steps, plus templates, live preview, animations, narration, voice cloning |
+| [Windows Installation](./windows-installation.md) | Step-by-step setup guide for Windows users |
+| [FAQ](./faq.md) | Model selection, cost, layout troubleshooting, custom templates — updated from real user reports |
+
+## Capabilities in Depth
+
+| Document | Description |
+|---|---|
+| [Audio Narration](./audio-narration.md) | Speaker notes to per-slide narration: providers, voice cloning, timing, PPTX embedding |
+| [Templates Guide](./templates-guide.md) | Creating and applying brand / layout / deck templates |
+
+## Architecture & Internals
+
+| Document | Description |
+|---|---|
+| [Technical Design](./technical-design.md) | Architecture, design philosophy, why SVG → DrawingML |
+| [PowerPoint–SVG Mapping](./powerpoint-svg-mapping.md) | Feature-by-feature mapping between PowerPoint constructs and the pipeline |
+| [Templates Architecture](./templates-architecture.md) | Design of the brand / layout / deck template system |
+
+## Project Direction
+
+| Document | Description |
+|---|---|
+| [Why PPT Master](./why-ppt-master.md) | User-facing comparison with Gamma, Copilot, and other AI tools |
+| [Project Positioning](./project-positioning.md) | Long-term positioning, product promises, capability boundaries, and admission criteria |
+| [Roadmap](./roadmap.md) | Delivered capabilities, current priorities, and explicitly deferred directions |
+
+## Contributor Rules
+
+| Document | Description |
+|---|---|
+| [Style Rules](./rules/README.md) | Repo-wide style rules for prompt files, Python, and prose |
diff --git a/docs/project-positioning.md b/docs/project-positioning.md
new file mode 100644
index 00000000..fe3cda0f
--- /dev/null
+++ b/docs/project-positioning.md
@@ -0,0 +1,165 @@
+# Project Positioning and Capability Boundary
+
+[English](./project-positioning.md) | [Chinese](./zh/project-positioning.md)
+
+---
+
+This document defines PPT Master's long-term product position and the decision framework for adding, retaining, or removing capabilities. It is not a feature list or an execution manual.
+
+This English file is the canonical policy source. The
+[Chinese version](./zh/project-positioning.md) is a synchronized translation,
+not an independent policy; update both in the same change.
+
+[`workflows/routing.md`](../skills/ppt-master/workflows/routing.md) remains authoritative for current route selection. This document answers a different question: whether a proposed direction belongs in PPT Master at all.
+
+## 1. Positioning
+
+> **PPT Master is an open-source, chat-driven presentation authoring framework for AI agents. It turns a topic, source material, design references, or an existing PowerPoint into high-quality, natively editable, locally owned PowerPoint artifacts through explicit authoring and preservation contracts.**
+
+PPT Master is not a model, a presentation SaaS, or a replacement for PowerPoint. It is the harness between a general-purpose AI agent and the presentation domain: workflows provide professional judgment and operating discipline, while deterministic tools handle conversion, validation, packaging, and repeatable file operations.
+
+The primary deliverable remains a PowerPoint file that the user can continue editing. Reusable template workspaces, project sources, design specifications, previews, and validation artifacts are first-class supporting products because they make the final deck controllable, reproducible, and reusable.
+
+## 2. The Problem PPT Master Solves
+
+Creating a useful presentation is not a single file-conversion operation. It requires several kinds of work that general AI systems and existing presentation tools rarely combine well.
+
+| Problem | PPT Master's response |
+|---|---|
+| General AI can understand material but does not reliably construct complex PowerPoint files | Give the agent presentation-specific planning, design, authoring, and validation contracts |
+| Visually ambitious AI outputs are often flattened images or browser documents | Compile a constrained visual authoring format into real PowerPoint objects instead of flattening whole slides |
+| Direct OOXML generation is too verbose and fragile for visual authoring | Let the agent author in a model-friendly visual language, then use deterministic compilers and package validators |
+| Source facts, narrative structure, visual design, assets, and delivery are usually disconnected steps | Maintain one project lifecycle with explicit artifact ownership and handoffs |
+| Existing decks may need redesign, content replacement, design reuse, or behavior-only enhancement | Select a mutation model whose preservation contract matches the user's intent |
+| Hosted presentation tools create cost, privacy, and platform lock-in | Keep the workflow open, local-first, model-independent, and agent-independent |
+
+The project's job is therefore not merely to “write a `.pptx`.” Its job is to make a general AI agent competent and reliable at presentation work while preserving the user's ability to inspect, edit, and own the result.
+
+## 3. Target Users and Usage Model
+
+PPT Master is primarily for people who:
+
+- Have a topic, documents, data, visual references, brand assets, or an existing deck that must become a presentation.
+- Care about design quality and native editability more than instant generation.
+- Need local project ownership, transparent costs, and freedom to choose an AI agent or model.
+- Are willing to review the direction and refine the generated deck in PowerPoint when needed.
+- Can use a chat-driven AI IDE and a local Python environment, even if they do not write code themselves.
+
+PPT Master is not optimized for users who primarily need zero-configuration browser generation, real-time team co-editing, or a guaranteed final deck with no human judgment or revision.
+
+## 4. Product Promises
+
+| Promise | Meaning | Boundary |
+|---|---|---|
+| Native editability | Preserve text, shapes, pictures, charts, tables, and presentation behaviors as real PowerPoint constructs where the selected route supports them | Do not use whole-slide screenshots as the canonical PPTX output; unsupported semantics must be explicit |
+| High-quality starting point | Remove most of the work of turning raw material into a coherent, designed deck | Do not promise a perfect one-shot final; the model and user judgment still determine the ceiling |
+| Source and intent fidelity | Keep sourced facts, user decisions, design recommendations, and derived artifacts distinguishable | Do not invent evidence or silently reinterpret a preservation request as redesign |
+| User ownership | Keep artifacts local, portable, and usable outside one vendor's product | External model, search, image, or speech calls may still follow the user's chosen provider |
+| Engineering reliability | Use explicit routes, contracts, validation gates, read-back checks, and recoverable project state | Do not hide failures behind silent fallbacks or publish an artifact that violates a required gate |
+| Quality over speed | Favor coherent design, editability, and delivery reliability over the fastest possible output | Improve efficiency where quality remains intact; do not make low-quality parallel generation the default |
+
+## 5. Product Capability Model
+
+The capability model is broader than one generation pipeline, but narrower than a general office agent.
+
+| Capability domain | Responsibility |
+|---|---|
+| Presentation understanding and planning | Convert a topic or source bundle into an audience-aware message, narrative structure, page plan, and explicit design direction |
+| New presentation authoring | Create new slide visuals and compile them into a natively editable PowerPoint deck |
+| Reusable presentation design systems | Create, combine, validate, and apply Brand, Layout, and Deck workspaces |
+| Existing-deck adaptation | Redesign an existing deck, fill native slide shells with new content, or append native behaviors under distinct preservation contracts |
+| Presentation expression | Use images, diagrams, charts, tables, formulas, notes, narration, transitions, and animation when they serve the communication goal |
+| Review and delivery | Preview, inspect, validate, repair, export, read back, and preserve enough project state for later refinement or re-export |
+
+These are product responsibilities, not a mandate to expose every responsibility as a top-level route or a separate workflow file. Routes exist only when inputs, mutation rules, invariants, or output lifecycles genuinely differ.
+
+## 6. What the Project Owns Versus What It Integrates
+
+PPT Master may rely on general-purpose capabilities without becoming a general-purpose platform for them.
+
+| Area | PPT Master owns | PPT Master does not own |
+|---|---|---|
+| Research | Determining what evidence a deck needs, preserving provenance, and turning findings into presentation content | A general web research engine for tasks unrelated to presentations |
+| Images | Deciding whether an image is needed, its role, style, source, placement, provenance, and readiness | A universal image-generation or photo-management platform |
+| Audio | Speaker notes, voice choice in presentation context, per-slide narration, timing, and PowerPoint embedding | A general audio studio, podcast platform, or speech-provider marketplace |
+| Data visualization | Choosing the visual form, preserving values, validating geometry, and selecting the editability/fidelity trade-off | A general business-intelligence or spreadsheet product |
+| Templates and brands | Explicit reusable presentation identity, layout, Master/Layout, slot, asset, and composition contracts | Recovering historical design intent that is absent from a source file |
+| PowerPoint editing | Presentation-specific generation, filling, redesign, and scoped native enhancement | Replacing the complete PowerPoint editing surface or supporting arbitrary OOXML mutation |
+
+Provider diversity may be bundled to preserve openness and practical usability, but provider-specific behavior should remain behind stable integration boundaries. The presentation workflow owns selection and output semantics; no individual provider should redefine the product boundary.
+
+## 7. Stable Technical Strategy
+
+The technical architecture serves the positioning; it is not the positioning itself.
+
+- **Constrained SVG to DrawingML** is the primary authoring and compilation path for newly designed slides.
+- **Direct OOXML operations** are preservation paths for cases where the existing PowerPoint package is the artifact to keep.
+- **Template workspaces** declare reusable design structure before new slides are authored; structure is not inferred after the fact.
+- **Project artifacts and validation gates** make the process inspectable, resumable, and testable.
+
+The implementation may evolve, but five invariants should remain stable:
+
+1. Do not flatten the canonical deck into one image per slide.
+2. Make editability, visual fidelity, and preservation trade-offs explicit.
+3. Select an authoring or mutation contract before changing the artifact.
+4. Keep source, author, derived, and delivery artifacts distinguishable.
+5. Fail closed when required semantics cannot be represented safely; do not claim unsupported fidelity.
+
+## 8. Non-goals
+
+PPT Master is not intended to become:
+
+- A fully autonomous replacement for human presentation judgment.
+- A general office assistant, research platform, image platform, or audio platform.
+- A complete PowerPoint clone, full browser-canvas editor, real-time collaboration service, or presentation SaaS.
+- An arbitrary SVG-to-PPTX or arbitrary OOXML conversion service.
+- A system that reconstructs missing historical Master/Layout intent from a finished PPTX or SVG.
+- An in-place upgrader that grafts inferred template structure onto existing files.
+- A speed-first generator that sacrifices deck coherence or output reliability.
+
+These non-goals do not forbid presentation-specific use of research, images, audio, native objects, or existing decks. They prevent supporting infrastructure from becoming an independent product with a different user promise.
+
+## 9. Capability Admission and Reduction Test
+
+Evaluate every proposed capability in this order:
+
+1. **User job** — What real presentation task does it complete?
+2. **Owned result** — What presentation artifact, decision, or quality property does it create or protect?
+3. **Invariant** — What must remain unchanged, and what is allowed to change?
+4. **Product layer** — Is it a core capability, an integrated presentation extension, a replaceable provider adapter, or repository maintenance?
+5. **Validation** — Can success and failure be checked without relying on a vague claim?
+6. **Evidence** — Is there a real user need, repeated workflow, or demonstrated failure that justifies the maintenance cost?
+
+| Decision | Use when |
+|---|---|
+| Add or retain as core | The capability directly completes a presentation job and requires presentation-specific contracts or validation |
+| Retain as an integrated extension | The capability is optional, but its planning and output semantics are specific to presentations |
+| Place behind a stable integration boundary | The underlying service is general-purpose or provider-specific, while PPT Master owns the presentation-specific selection and output contract |
+| Move to repository tooling | The capability maintains the repository, examples, installation, or contributor workflow rather than creating presentations |
+| Retire | It duplicates another authority, has no active consumer, makes an unverifiable promise, or adds more maintenance than presentation value |
+
+The number of files or workflows is not itself a reason to add or remove a capability. The deciding factor is whether ownership and product value are clear.
+
+## 10. North-Star Outcome
+
+A successful PPT Master session should look like this:
+
+> The user gives an AI agent a topic, source material, design references, a reusable template, or an existing PowerPoint; confirms the important content and design choices; and receives a coherent, natively editable, validated PowerPoint artifact plus enough local project state to review, refine, reuse, or re-export it.
+
+Future work should improve this outcome in the following priority order:
+
+1. Output correctness, native editability, and delivery reliability.
+2. Content reasoning, narrative quality, and visual coherence.
+3. Reuse of brands, layouts, decks, and existing PowerPoint assets.
+4. Human review, correction, and controlled iteration.
+5. Additional formats, providers, and convenience features that strengthen the first four priorities.
+
+## 11. Relationship to Other Documents
+
+| Document | Responsibility |
+|---|---|
+| This document | Long-term product position, promises, capability boundary, and admission test |
+| [`why-ppt-master.md`](./why-ppt-master.md) | User-facing differentiation and reasons to choose the project |
+| [`technical-design.md`](./technical-design.md) | Current architecture and implementation invariants |
+| [`workflows/routing.md`](../skills/ppt-master/workflows/routing.md) | Current executable route selection |
+| [`roadmap.md`](./roadmap.md) | Shipped work, active priorities, and explicitly deferred directions |
diff --git a/docs/why-ppt-master.md b/docs/why-ppt-master.md
index b2a22753..f64d82e6 100644
--- a/docs/why-ppt-master.md
+++ b/docs/why-ppt-master.md
@@ -8,6 +8,8 @@ There are dozens of AI presentation tools. This page explains what PPT Master do
I'm [Hugo He](https://www.hehugo.com/), an investment & finance professional who builds presentations every day. PPT Master is an open-source tool I've spent extensive time refining — because I'm its most demanding user.
+This page is the user-facing comparison. The project's long-term positioning, product promises, and capability boundaries live in [Project Positioning](./project-positioning.md).
+
## 1. Real PowerPoint Output — Not Images, Not Web Screenshots
**This is the core differentiator.**
diff --git a/docs/zh/README.md b/docs/zh/README.md
new file mode 100644
index 00000000..a86d3de1
--- /dev/null
+++ b/docs/zh/README.md
@@ -0,0 +1,45 @@
+# 文档索引
+
+[English](../README.md) | [中文](./README.md)
+
+---
+
+用户文档集中在 `docs/` 目录:英文文件为规范源,本目录(`docs/zh/`)是同步中文译本。AI 自身消费的工作流与技术参考位于 [`skills/ppt-master/`](../../skills/ppt-master/SKILL.md)。
+
+## 快速上手
+
+| 文档 | 说明 |
+|---|---|
+| [快速入门](./getting-started.md) | 三步做出第一份 deck,外加模板、实时预览、动画、旁白、声音复刻的用法 |
+| [Windows 安装指南](./windows-installation.md) | Windows 用户手把手安装教程 |
+| [常见问题](./faq.md) | 模型选择、费用、排版问题排查、自定义模板——基于真实用户反馈持续更新 |
+
+## 能力专题
+
+| 文档 | 说明 |
+|---|---|
+| [音频旁白](./audio-narration.md) | 从演讲者备注到逐页旁白:服务商、声音复刻、时序、PPTX 嵌入 |
+| [转场与动画](./animations.md) | 页间转场与页内元素动画的默认行为和自定义方式 |
+| [模板使用指南](./templates-guide.md) | 品牌 / 版式 / 成品模板的创建与套用 |
+
+## 架构与原理
+
+| 文档 | 说明 |
+|---|---|
+| [技术路线](./technical-design.md) | 架构、设计哲学、为什么选 SVG → DrawingML |
+| [PowerPoint–SVG 能力映射](./powerpoint-svg-mapping.md) | PowerPoint 构造与管线之间逐项能力映射 |
+| [模板体系架构](./templates-architecture.md) | 品牌 / 版式 / 成品模板体系的设计 |
+
+## 项目方向
+
+| 文档 | 说明 |
+|---|---|
+| [为什么选 PPT Master](./why-ppt-master.md) | 与 Gamma、Copilot 等 AI 工具的对比 |
+| [项目定位与能力边界](./project-positioning.md) | 长期定位、产品承诺、能力边界与准入判据 |
+| [路线图](./roadmap.md) | 已交付能力、当前优先级与明确推迟的方向 |
+
+## 贡献者规则
+
+| 文档 | 说明 |
+|---|---|
+| [风格规则](../rules/README.md)(英文) | 提示词文件、Python 与文档散文的仓库级风格规则 |
diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.md
index c954b2dc..8f200b43 100644
--- a/docs/zh/powerpoint-svg-mapping.md
+++ b/docs/zh/powerpoint-svg-mapping.md
@@ -210,7 +210,7 @@ PowerPoint 原生 Chart/Table 对象是可选功能。默认导出保留 SVG fal
| 批注或审阅线程 | 无 SVG 或生成侧映射 | 不编写 | 仅在其他路线明确拥有时为 `Direct preservation` | 不自动将审阅 metadata 转为可见 Slide 内容 |
| 不属于已映射功能的 relationship | 无通用 SVG 逃生口 | 不生成 | 适用时为 `Direct preservation` | 不支持任意 relationship 注入 |
-sidecar 工作流见 [`animations.md`](../../skills/ppt-master/references/animations.md) 与 [`audio-narration.md`](./audio-narration.md)。
+sidecar 工作流见[转场与动画](./animations.md)(技术规范源为 [`references/animations.md`](../../skills/ppt-master/references/animations.md))与 [`audio-narration.md`](./audio-narration.md)。
## 10. 其他 PowerPoint 原生功能
diff --git a/docs/zh/project-positioning.md b/docs/zh/project-positioning.md
new file mode 100644
index 00000000..083e8aec
--- /dev/null
+++ b/docs/zh/project-positioning.md
@@ -0,0 +1,165 @@
+# 项目定位与能力边界
+
+[English](../project-positioning.md) | [中文](./project-positioning.md)
+
+---
+
+本文定义 PPT Master 的长期产品定位,以及新增、保留或削减能力时使用的判断框架。它不是功能清单,也不是执行手册。
+
+本文是[英文规范源](../project-positioning.md)的同步中文译本,不形成第二套
+产品政策;定位变化必须在同一次修改中同步两种语言,如有歧义以英文规范
+源为准。
+
+当前具体如何选择路线,仍以 [`workflows/routing.md`](../../skills/ppt-master/workflows/routing.md) 为准。本文回答的是另一个问题:一个方向究竟是否应该属于 PPT Master。
+
+## 一、项目定位
+
+> **PPT Master 是一套面向 AI Agent、以对话驱动的开源演示文稿创作框架。它通过明确的创作与保留契约,把主题、源材料、设计参考或已有 PowerPoint,转化为高质量、原生可编辑且由用户本地持有的 PowerPoint 产物。**
+
+PPT Master 不是模型,不是演示 SaaS,也不是 PowerPoint 的替代品。它是通用 AI Agent 与演示文稿领域之间的 harness:工作流提供专业判断和执行纪律,确定性工具负责转换、校验、打包以及可重复的文件操作。
+
+最主要的交付物仍然是用户能够继续编辑的 PowerPoint 文件。可复用模板工作区、项目源材料、设计规范、预览和校验产物同样是一等支撑产物,因为它们让最终 deck 可控制、可重建、可复用。
+
+## 二、PPT Master 解决的问题
+
+制作一份真正有用的演示文稿,不是一次文件格式转换。它包含多种工作,而通用 AI 和现有演示工具通常无法同时把这些工作做好。
+
+| 问题 | PPT Master 的处理方式 |
+|---|---|
+| 通用 AI 能理解材料,却无法稳定构造复杂 PowerPoint 文件 | 为 Agent 提供演示文稿专用的策划、设计、创作和校验契约 |
+| 视觉效果较好的 AI 产物经常是整页图片或网页文档 | 使用受约束的视觉创作格式编译真实 PowerPoint 对象,不把整页压平 |
+| 直接生成 OOXML 过于冗长、脆弱,不适合作为 AI 的视觉创作语言 | 让 Agent 使用模型友好的视觉语言创作,再由确定性编译器和 package 校验器完成交付 |
+| 源事实、叙事结构、视觉设计、素材和最终交付通常彼此割裂 | 用统一项目生命周期和明确的产物所有权连接各阶段 |
+| 已有 deck 可能需要重新设计、替换内容、复用设计或只追加演示行为 | 根据用户意图选择具有相应保留契约的修改模型 |
+| 托管式演示工具带来成本、隐私和平台锁定 | 保持开源、本地优先、模型无关和 Agent 无关 |
+
+因此,项目的工作不只是“写出一个 `.pptx`”,而是让通用 AI Agent 具备可靠完成演示文稿工作的能力,同时保留用户检查、编辑和拥有结果的权利。
+
+## 三、目标用户与使用方式
+
+PPT Master 主要服务于以下用户:
+
+- 手上有主题、文档、数据、视觉参考、品牌资产或已有 deck,需要把它们转化为演示文稿。
+- 相比几秒钟出片,更重视设计质量和原生可编辑性。
+- 需要本地持有项目、透明控制成本,并保留选择 AI Agent 和模型的自由。
+- 愿意确认关键方向,并在必要时继续用 PowerPoint 精修生成结果。
+- 能够使用对话式 AI IDE 和本地 Python 环境,即使本人并不编写代码。
+
+PPT Master 不以零配置浏览器出片、实时团队共编,或完全不需要人类判断和修改的一次性完稿为主要目标。
+
+## 四、产品承诺
+
+| 承诺 | 含义 | 边界 |
+|---|---|---|
+| 原生可编辑 | 在所选路线支持的范围内,将文字、形状、图片、图表、表格和演示行为保留为真实 PowerPoint 构造 | 不把整页截图作为规范 PPTX 输出;无法表达的语义必须显式说明 |
+| 高质量起点 | 消除从原材料到结构清晰、经过设计的 deck 的大部分工作 | 不承诺一次生成完美终稿;模型能力和用户判断仍决定上限 |
+| 事实与意图保真 | 区分来源事实、用户决策、设计建议和派生产物 | 不编造依据,也不把保留型请求静默改成重新设计 |
+| 用户所有权 | 产物保持本地、可迁移,不依附单一厂商产品 | 用户选择的模型、搜索、生图或语音服务仍可能发生外部调用 |
+| 工程可靠性 | 使用明确路线、执行契约、质量门、回读校验和可恢复项目状态 | 不用静默降级掩盖失败,也不发布未通过必需 gate 的产物 |
+| 质量优先 | 优先保证整份 deck 的一致性、可编辑性和交付可靠性 | 可以在不损害质量时提效,但不默认采用低质量并行生成 |
+
+## 五、产品能力模型
+
+PPT Master 的能力范围应当比单一生成管线更宽,但比通用办公 Agent 更窄。
+
+| 能力领域 | 项目责任 |
+|---|---|
+| 演示理解与策划 | 把主题或材料包转化为面向受众的核心信息、叙事结构、页面规划和明确设计方向 |
+| 新演示文稿创作 | 创作新的页面视觉,并编译为原生可编辑 PowerPoint |
+| 可复用演示设计系统 | 创建、组合、校验并应用 Brand、Layout 和 Deck 工作区 |
+| 已有 deck 改编 | 在不同保留契约下重做已有 deck、向原生页面壳填入新内容,或追加原生演示行为 |
+| 演示表达 | 在沟通目标需要时使用图片、图示、图表、表格、公式、讲稿、旁白、转场和动画 |
+| 审阅与交付 | 预览、检查、校验、修复、导出、回读,并保留足够的项目状态供后续精修或重新导出 |
+
+这些是产品责任,不代表每项责任都必须暴露成顶层路线或单独的 workflow 文件。只有输入、修改规则、不变量或产物生命周期确实不同,才需要独立路线。
+
+## 六、项目拥有的责任与接入的能力
+
+PPT Master 可以依赖通用能力,但不因此成为这些通用能力的平台。
+
+| 领域 | PPT Master 负责 | PPT Master 不负责 |
+|---|---|---|
+| 研究 | 判断 deck 需要什么证据、保存来源,并把研究结果转化为演示内容 | 与演示任务无关的通用网络研究引擎 |
+| 图片 | 判断是否需要图片,以及图片的角色、风格、来源、位置、出处和就绪状态 | 通用图片生成或图片管理平台 |
+| 音频 | 演示语境中的讲稿、音色选择、逐页旁白、计时和 PowerPoint 嵌入 | 通用音频工作站、播客平台或语音供应商市场 |
+| 数据可视化 | 选择表达形式、保留数据、校验几何,并决定可编辑性与保真度之间的取舍 | 通用 BI 或电子表格产品 |
+| 模板与品牌 | 明确且可复用的演示身份、版式、Master/Layout、槽位、素材与组合契约 | 恢复来源文件中已经不存在的历史设计意图 |
+| PowerPoint 编辑 | 演示专用的生成、填充、重做和有边界的原生增强 | 替代 PowerPoint 的完整编辑界面,或支持任意 OOXML 修改 |
+
+仓库可以内置多个 provider,以保持开放性和实际可用性,但供应商特异行为应当位于稳定的接入边界之后。演示工作流负责选择逻辑和输出语义,任何单一 provider 都不应重新定义产品边界。
+
+## 七、稳定的技术策略
+
+技术架构服务于定位,但技术架构本身不是项目定位。
+
+- **受约束的 SVG → DrawingML** 是新设计页面的主要创作和编译路线。
+- **直接 OOXML 操作**用于必须保留已有 PowerPoint package 的场景。
+- **模板工作区**在新页面创作前声明可复用设计结构,而不是在成品形成后反向推断。
+- **项目产物和质量门**让过程可以检查、续跑和验证。
+
+具体实现可以演进,但以下五条不变量应保持稳定:
+
+1. 不把规范 deck 扁平化成每页一张图片。
+2. 明确说明可编辑性、视觉保真和保留程度之间的取舍。
+3. 修改产物前先确定创作或修改契约。
+4. 区分来源、作者状态、派生状态和交付状态。
+5. 必需语义无法安全表达时应当停止,不声称并不存在的保真度。
+
+## 八、明确不做
+
+PPT Master 不以成为以下产品为目标:
+
+- 完全替代人类演示判断的全自动系统。
+- 通用办公助手、通用研究平台、通用图片平台或通用音频平台。
+- 完整的 PowerPoint 克隆、完整浏览器自由画布编辑器、实时协作服务或演示 SaaS。
+- 任意 SVG 到 PPTX 或任意 OOXML 的转换服务。
+- 从完成态 PPTX 或 SVG 中恢复缺失的历史 Master/Layout 意图。
+- 把推断出的模板结构原地嫁接到已有文件上的升级器。
+- 以牺牲 deck 一致性或交付可靠性为代价的速度优先生成器。
+
+这些非目标并不排斥在演示任务中使用研究、图片、音频、原生对象或已有 deck。它们防止支撑能力脱离演示语境,发展成承诺完全不同的独立产品。
+
+## 九、能力准入与削减判据
+
+评估任何新增能力时,按以下顺序回答:
+
+1. **用户任务**:它完成了哪一个真实的演示文稿任务?
+2. **责任结果**:它创建或保护了什么演示产物、决策或质量属性?
+3. **不变量**:什么必须保持不变,什么允许改变?
+4. **产品层级**:它属于核心能力、演示专用扩展、可替换 provider adapter,还是仓库维护?
+5. **可验证性**:能否明确检查成功与失败,而不是依赖模糊承诺?
+6. **真实证据**:是否有真实用户需求、重复工作流或已经发生的失败,足以覆盖维护成本?
+
+| 决策 | 适用条件 |
+|---|---|
+| 作为核心能力新增或保留 | 直接完成演示任务,并需要演示专用契约或校验 |
+| 作为集成扩展保留 | 能力本身可选,但它的规划和输出语义是演示专用的 |
+| 放到稳定接入边界之后 | 底层服务具有通用性或供应商特异性,PPT Master 负责演示专用的选择逻辑和输出契约 |
+| 移到仓库工具层 | 服务于仓库、示例、安装或贡献者流程,而不是生产演示文稿 |
+| 退役 | 与另一权威重复、没有有效使用者、承诺无法验证,或维护成本高于演示价值 |
+
+文件或 workflow 的数量本身,不是新增或删除能力的理由。真正的判断标准是责任是否清晰,以及它是否创造明确的产品价值。
+
+## 十、北极星结果
+
+一次成功的 PPT Master 使用过程应当是:
+
+> 用户把主题、源材料、设计参考、可复用模板或已有 PowerPoint 交给 AI Agent,确认重要的内容和设计选择,最终获得一份结构连贯、原生可编辑、经过校验的 PowerPoint 产物,以及足够的本地项目状态,用于审阅、精修、复用或重新导出。
+
+未来工作应按以下顺序改善这一结果:
+
+1. 输出正确性、原生可编辑性和交付可靠性。
+2. 内容推理、叙事质量和视觉一致性。
+3. 品牌、版式、Deck 和已有 PowerPoint 资产的复用。
+4. 人工审阅、修正和可控迭代。
+5. 能够强化前四项的额外格式、provider 和便利能力。
+
+## 十一、与其他文档的关系
+
+| 文档 | 责任 |
+|---|---|
+| 本文 | 长期产品定位、产品承诺、能力边界和准入判据 |
+| [`why-ppt-master.md`](./why-ppt-master.md) | 面向用户的差异化和选择理由 |
+| [`technical-design.md`](./technical-design.md) | 当前技术架构和实现不变量 |
+| [`workflows/routing.md`](../../skills/ppt-master/workflows/routing.md) | 当前可执行路线选择 |
+| [`roadmap.md`](./roadmap.md) | 已交付能力、当前优先级和明确推迟的方向 |
diff --git a/docs/zh/why-ppt-master.md b/docs/zh/why-ppt-master.md
index 6d443e30..c5f15397 100644
--- a/docs/zh/why-ppt-master.md
+++ b/docs/zh/why-ppt-master.md
@@ -8,6 +8,8 @@
我是[何雨果](https://www.hehugo.com/),一个每天都在做 PPT 的投融资从业者。PPT Master 是我花了大量时间打磨的开源工具——因为我自己就是最挑剔的用户。
+本页回答"为什么选它"。项目的长期定位、产品承诺与能力边界见[项目定位与能力边界](./project-positioning.md)。
+
## 1. 生成真正的 PPT——不是图片,不是网页截图
**这是最核心的差异化。**