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(sources): define content-type read policy across authority docs
hugohe387877a3f94fd
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 45e6bb48..1f5dc5b3 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -18,7 +18,7 @@ The generated PPTX is a **design draft**, not a finished product. Think of it liUser Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)↓[Source Content Conversion] → source_to_md/pdf_to_md.py / doc_to_md.py / excel_to_md.py / ppt_to_md.py / web_to_md.py- ├── Markdown is the content contract+ ├── Content-type files in sources/ are the content contract└── PPTX intake writes analysis/<stem>.identity.json, <stem>.slide_library.json, source_profile.json↓[Create Project] → project_manager.py init <project_name> --format <format>@@ -110,7 +110,7 @@ Artifact source/derived ownership is authoritative in [`artifact-ownership.md`](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 ──────────────┐+sources/<content files> ────────┐analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spec_lock.mdanalysis/image_analysis.csv ────┘@@ -167,7 +167,7 @@ Source documents (PDF / DOCX / EPUB / XLSX / PPTX / web pages) are normalized be| Channel | Artifact | Owner | Used for ||---|---|---|---|-| Content contract | `sources/<stem>.md` | `source_to_md/*` converters | text, tables, chart values, citations, and source narrative |+| Content contract | `sources/` content-type files (primarily `<stem>.md`) | `source_to_md/*` converters + `import-sources` | text, tables, chart values, citations, and source narrative || Structured analysis | `analysis/*.json` / `analysis/*.csv` | intake and analysis tools | PPTX identity, slide geometry, native tables/charts, image dimensions/colors/subjects |For PPTX sources, `project_manager.py import-sources` runs both `ppt_to_md.py` and `pptx_intake.py`. The Markdown remains the content source for the main generation pipeline. The intake bundle writes `<stem>.identity.json`, `<stem>.slide_library.json`, and merges a compact multi-deck index into `analysis/source_profile.json`. Strategist reads the compact index for source facts and opens raw per-deck artifacts only when a workflow needs them. That distinction matters: the main pipeline may rethink page count and story, while `template-fill` and `beautify` promote parts of the same intake facts into stronger constraints.@@ -212,7 +212,7 @@ These invariants are stronger than ordinary implementation preferences. If a cha| 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 |+| `sources/` content-type files are the main-pipeline content contract | text, tables, and chart values come from content-type files in `sources/` (Markdown is primary, but `.txt` / `.csv` / `.json` / `.yaml` / … count too); known sidecars (`*.conversion_profile.json`, `*_files/image_manifest.json`) are excluded || `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 |diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex b05d8448..05a3d3bb 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -18,7 +18,7 @@用户输入 (PDF/DOCX/XLSX/PPTX/URL/Markdown/主题文本)↓[源内容转换] → source_to_md/pdf_to_md.py / doc_to_md.py / excel_to_md.py / ppt_to_md.py / web_to_md.py- ├── Markdown 是内容契约+ ├── sources/ 内容型文件是内容契约└── PPTX intake 写入 analysis/<stem>.identity.json、<stem>.slide_library.json、source_profile.json↓[创建项目] → project_manager.py init <项目名> --format <格式>@@ -110,7 +110,7 @@ Artifact 的来源 / 派生所有权以 [`artifact-ownership.md`](../../skills/p维护这套系统时,把文件夹理解成数据流会比“这些目录刚好存在”更清楚:```text-sources/<stem>.md ──────────────┐+sources/<content files> ────────┐analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spec_lock.mdanalysis/image_analysis.csv ────┘@@ -167,7 +167,7 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可| 通道 | 产物 | 所有者 | 用途 ||---|---|---|---|-| 内容契约 | `sources/<stem>.md` | `source_to_md/*` 转换器 | 文本、表格、图表数值、引用和源材料叙事 |+| 内容契约 | `sources/` 内容型文件(以 `<stem>.md` 为主) | `source_to_md/*` 转换器 + `import-sources` | 文本、表格、图表数值、引用和源材料叙事 || 结构化分析 | `analysis/*.json` / `analysis/*.csv` | intake 与分析工具 | PPTX 身份信息、页面几何、原生表格/图表、图片尺寸/色彩/主体 |对 PPTX 源文件,`project_manager.py import-sources` 会同时运行 `ppt_to_md.py` 和 `pptx_intake.py`。Markdown 仍然是主生成流水线的内容源;intake bundle 会写出 `<stem>.identity.json`、`<stem>.slide_library.json`,并把紧凑的多 deck 索引合并到 `analysis/source_profile.json`。Strategist 默认读取这个紧凑索引来获取源事实;只有特定工作流需要原始细节时,才打开单个 deck 的原始 artifact。这个边界很重要:主流水线可以重构页数和叙事,而 `template-fill` 与 `beautify` 会把同一批 intake 事实中的一部分提升为更强约束。@@ -212,7 +212,7 @@ CLI 仍支持三种导入模式:`--move`、`--copy`,以及“仓库内文件| 不变量 | 实际后果 ||---|---|-| `sources/<stem>.md` 是主流水线内容契约 | 主 SVG 路线中的文本、表格和图表数值来自 Markdown |+| `sources/` 内容型文件是主流水线内容契约 | 主 SVG 路线中的文本、表格和图表数值来自 `sources/` 内容型文件(Markdown 为主,`.txt` / `.csv` / `.json` / `.yaml` 等同样计入);已知 sidecar(`*.conversion_profile.json`、`*_files/image_manifest.json`)排除在外 || `analysis/` 存机器事实,不存设计契约 | `source_profile.json` 和 intake artifact 辅助 Strategist;除非工作流明确规定,否则不锁定页数 / 页序 || `design_spec.md` 解释设计;`spec_lock.md` 执行设计 | Executor 从 `spec_lock.md` 取锁定值,而不是从叙述记忆里取 || 每页生成前重读 `spec_lock.md` | 长 deck 中的颜色、字体、图标、图片、节奏、布局和图表选择保持稳定 |diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 8fda3bf7..3d859fe1 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -335,7 +335,7 @@ Read references/strategist.md**`<project_path>/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `<stem>.identity.json` / `<stem>.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Eight Confirmations, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table entries per source deck), then open a specific deck's `<stem>.identity.json` / `<stem>.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.)-**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the Markdown** (`sources/<stem>.md`): text, tables, and chart data values all come from there (`ppt_to_md` now transcribes native chart data into Markdown tables). The `analysis/` chart / table entries are a **structural digest** for outline decisions (which slides carried charts, type, series names) — not a second copy of the values; do NOT also pull chart values from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract; beautify uses it for native chart / table data while keeping slide text from the Markdown.+**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the content-type files in `sources/`** — primarily `<stem>.md`, but also any user-supplied content the import archived there: `.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml` (a `metrics.json` or `data.csv` may carry core content — judge by what the file holds). Text, tables, and chart data values come from these (`ppt_to_md` now transcribes native chart data into Markdown tables). **Do NOT read pipeline sidecars in `sources/` as content**: `*.conversion_profile.json` (conversion audit) and `*_files/image_manifest.json` (asset index) are process metadata — open them only to audit a conversion or resolve assets, never as slide content. Converted-source originals archived in `sources/` (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) are read via their converted `<stem>.md`, not scanned directly in the main pipeline. The `analysis/` chart / table entries are a **structural digest** for outline decisions (which slides carried charts, type, series names) — not a second copy of the values; do NOT also pull chart values from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract; beautify uses it for native chart / table data while keeping slide text from the Markdown.**Eight Confirmations** (full template: `templates/design_spec_reference.md`):diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex fb51ae3c..b0b8009f 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -10,8 +10,9 @@ Global artifact ownership rules for PPT Master projects.| Artifact | Owner | Role | Read/write contract ||---|---|---|---|-| `sources/<stem>.md` | Content contract | Main pipeline source for text, tables, and chart data values | Strategist reads for content; do not replace values with PPTX geometry JSON in the main pipeline |-| `sources/` originals | Source archive | Imported source files and source-adjacent extracted assets | Project manager imports here; downstream reads by route |+| `sources/` content-type files | Content contract | Main pipeline source for text, tables, and chart data values | Strategist reads content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judges by content; do not replace values with PPTX geometry JSON in the main pipeline |+| `sources/` converted-source originals | Source archive | Imported source files that have a converted content contract (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) and source-adjacent extracted assets | Read via the converted `<stem>.md` in the main pipeline; direct-PPTX workflows read the `.pptx` by route |+| `sources/*.conversion_profile.json`, `sources/*_files/image_manifest.json` | Pipeline sidecar | Conversion audit record / asset index | NOT read as slide content; open only to audit a conversion or resolve assets || `analysis/source_profile.json` | Machine fact index | Compact Strategist-facing PPTX intake digest | Main pipeline reads as factual context and recommendation candidates || `analysis/<stem>.identity.json` | Native deck identity facts | Canvas, theme palette/fonts, observed usage | Read selectively when detailed identity facts are needed || `analysis/<stem>.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches | Direct PPTX workflows use as native fill/structure contract |@@ -37,7 +38,8 @@ Global artifact ownership rules for PPT Master projects.| Invariant | Rule ||---|---|-| Content values | Main pipeline text, tables, and chart values come from `sources/<stem>.md`, not from `slide_library.json`. |+| Content values | Main pipeline text, tables, and chart values come from content-type files in `sources/` (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`), not from `slide_library.json`. |+| Sources read policy | In `sources/`, read content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judge by content — a `.json` / `.csv` may be core content or just data. Exclude known sidecars: `*.conversion_profile.json` and `*_files/image_manifest.json`. `analysis/` facts (`source_profile.json`, `<stem>.slide_library.json`) are read per Step 4 / direct-PPTX workflow, not in the `sources/` content scan. || PPTX structure | `slide_library.json` owns native geometry and slot facts for direct PPTX workflows. || Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. || Image facts | `images/` is live state; `analysis/image_analysis.csv` is a regenerated view, not a durable cache. |