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.mdindex 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 editIn 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>+---## Contributingdiff --git a/README_CN.md b/README_CN.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 doI'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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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——不是图片,不是网页截图**这是最核心的差异化。**