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(sources): define content-type read policy across authority docs

hugohe387877a3f94fd
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 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 li
User 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.md
analysis/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.md
index 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.md
analysis/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.md
index 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.md
index 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. |