minimal-agent 0.8.2 → 0.10.0

package/skills/pptx/SKILL.md

@@ -1,18 +1,60 @@
 ---
 name: pptx
-description: "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill."
+description: "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill. This skill is a four-stage navigator (design → graphics → file ops → QA): it establishes a design system by bridging the ui-design skill, draws editable graphics (native vector shapes for diagrams, embedded SVG with PNG fallback for art that ungroups in PowerPoint), and enforces OPC compliance — not just a PptxGenJS/OPC file-operation manual."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
 # PPTX Skill
 
-## Quick Reference
+## 这是什么 skill
 
-| Task | Guide |
-|------|-------|
-| Read/analyze content | `python -m markitdown presentation.pptx` |
-| Edit or create from template | Read [editing.md](editing.md) |
-| Create from scratch | Read [pptxgenjs.md](pptxgenjs.md) |
+做 PPT 的本质是「前端/平面设计 + 内容 + 文件操作」三件事，不是把 API 堆出来。本 skill 是一个**向导**：
+按「设计 → 图形 → 落盘 → QA」四阶段牵着走 —— 既会用 PptxGenJS/OPC 操作文件，也会按设计系统排版、用矢量做可编辑配图。
+
+> 📍 **寻址说明**：本 skill 内的 `[x](x)` / `scripts/x` 链接相对**本技能目录**（即系统提示「可用技能」列表里本卡片给出的 `技能目录:` 绝对路径），**不是相对当前工作目录(cwd)**——用该绝对目录拼成绝对路径再 Read/执行。引用同仓的 `ui-design` 技能时同理：用列表里 **ui-design 自己卡片**的绝对目录，别用 `../ui-design/`（详见 [design.md](design.md) 顶部）。
+
+## 四阶段向导（按序走）
+
+**阶段 0 · 路由** —— 先判断要干嘛：
+- 读内容 / 抽文本 → `python -m markitdown x.pptx`（到此为止，不进后续阶段）。
+- 拿已有 pptx 当模板改 → 读 [editing.md](editing.md)（unpack→改→pack）；设计判断仍走阶段 1。
+- 从零创建 → 往下走阶段 1–4。
+
+**阶段 1 · 设计**（除非用户明确只要纯文本草稿/不要排版，否则**必做**）—— 先立设计系统，别直接画：
+> ⛔ **最高优先级·强制**：**一切样式与设计**——配色 / VI / 字体配对 / 字阶 / 版式 / 视觉节奏 / 避免 AI 味——**必须借同仓 `ui-design` skill 来定**，不要自己拍脑袋，也不要靠本文里现成的零碎素材（已删，原因见「样式与设计」节）。页面好不好看由这一步决定。
+
+读 [design.md](design.md)：它会带你用 ui-design 卡片的**绝对目录**读 `ui-design/SKILL.md` 立设计系统，并把 web 设计翻译到 PPT 的英寸/pt 画布。PPT 落地的尺寸/间距/避坑等 **PPT 特有硬约束**也在 design.md（ui-design 是 web 语境给不了）。
+
+**阶段 2 · 图形** —— 按下面「图形决策规则」选路线：结构图用 [pptxgenjs.md](pptxgenjs.md) + `scripts/deck_helpers.mjs`；美术配图用 SVG，读 [svg.md](svg.md)。
+
+**阶段 3 · 落盘** —— PptxGenJS 生成（**Node 跑，不要 Bun**，见 pptxgenjs.md 文首铁律）。
+**用了 SVG 就必跑** `node scripts/svg_fallback.mjs deck.pptx`（补真 PNG 兜底 + OPC 合规重打包）。
+
+**阶段 4 · QA** —— `python scripts/opc_check.py deck.pptx`（硬门槛）→ markitdown 内容核对 → 视觉 QA（见下）。
+
+### 图形决策规则（阶段 2 的核心）
+
+| 内容 | 用什么 | 备注 |
+|------|--------|------|
+| 标题 / 正文 / 项目符号 / 表格 —— **任何文字** | 原生 `addText` | 可编辑可重排；**绝不**烤进图片 |
+| 框图 / 流程图 / 时序 / 色块布局 | 原生 `addShape` | 原生对象，点选即改；复用 `scripts/deck_helpers.mjs`。**拿不准时的默认** |
+| 背景 / 渐变 / 插画 / 图标 / 曲线 / Logo | **SVG** + `svg_fallback.mjs` | 矢量丰富，PowerPoint 365 可「转换为形状」编辑；见 [svg.md](svg.md) |
+| 真实照片 / 已有位图 | `addImage(png/jpg)` | 封面/封底装饰 ≤2 张为宜 |
+
+一句话：**文字 addText，结构 addShape，美术 SVG，照片 addImage。**
+
+### 能力地图（要细节读哪份）
+
+| 你要做 | 读这份 |
+|--------|--------|
+| 立设计系统（配色/VI/字阶/版式） | [design.md](design.md)（桥接 `ui-design`） |
+| SVG 可编辑配图 + 兜底管线 | [svg.md](svg.md) |
+| 复用矢量原语（卡片/节点/箭头/标题/页脚） | `scripts/deck_helpers.mjs` |
+| PptxGenJS API（文字/形状/图表/表格） | [pptxgenjs.md](pptxgenjs.md) |
+| 改模板（unpack/pack） | [editing.md](editing.md) |
+| OPC 合规校验/重打包（硬门槛） | `scripts/opc_check.py` |
+| SVG 兜底修复 + 合规重打包 | `scripts/svg_fallback.mjs` |
+| 端到端范例（3 页混合） | `examples/hybrid_example.mjs` + `examples/README.md` |
 
 ---
 
@@ -46,95 +88,19 @@ python scripts/office/unpack.py presentation.pptx unpacked/
 
 Use when no template or reference presentation is available.
 
+先按「图形决策规则」分路：**结构图用原生 `addShape`**（复用 `scripts/deck_helpers.mjs` 的卡片/节点/箭头/标题/页脚，省得重踩 PptxGenJS 坑），**美术配图用 SVG**（读 [svg.md](svg.md)，生成后必跑 `scripts/svg_fallback.mjs`），文字一律原生 `addText`。`examples/hybrid_example.mjs` 是 3 页混合的可临摹范例。
+
 ---
 
-## Design Ideas
-
-**Don't create boring slides.** Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.
-
-### Before Starting
-
-- **Pick a bold, content-informed color palette**: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
-- **Dominance over equality**: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
-- **Dark/light contrast**: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
-- **Commit to a visual motif**: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles, thick single-side borders. Carry it across every slide.
-
-### Color Palettes
-
-Choose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:
-
-| Theme | Primary | Secondary | Accent |
-|-------|---------|-----------|--------|
-| **Midnight Executive** | `1E2761` (navy) | `CADCFC` (ice blue) | `FFFFFF` (white) |
-| **Forest & Moss** | `2C5F2D` (forest) | `97BC62` (moss) | `F5F5F5` (cream) |
-| **Coral Energy** | `F96167` (coral) | `F9E795` (gold) | `2F3C7E` (navy) |
-| **Warm Terracotta** | `B85042` (terracotta) | `E7E8D1` (sand) | `A7BEAE` (sage) |
-| **Ocean Gradient** | `065A82` (deep blue) | `1C7293` (teal) | `21295C` (midnight) |
-| **Charcoal Minimal** | `36454F` (charcoal) | `F2F2F2` (off-white) | `212121` (black) |
-| **Teal Trust** | `028090` (teal) | `00A896` (seafoam) | `02C39A` (mint) |
-| **Berry & Cream** | `6D2E46` (berry) | `A26769` (dusty rose) | `ECE2D0` (cream) |
-| **Sage Calm** | `84B59F` (sage) | `69A297` (eucalyptus) | `50808E` (slate) |
-| **Cherry Bold** | `990011` (cherry) | `FCF6F5` (off-white) | `2F3C7E` (navy) |
-
-### For Each Slide
-
-**Every slide needs a visual element** — image, chart, icon, or shape. Text-only slides are forgettable.
-
-**Layout options:**
-- Two-column (text left, illustration on right)
-- Icon + text rows (icon in colored circle, bold header, description below)
-- 2x2 or 2x3 grid (image on one side, grid of content blocks on other)
-- Half-bleed image (full left or right side) with content overlay
-
-**Data display:**
-- Large stat callouts (big numbers 60-72pt with small labels below)
-- Comparison columns (before/after, pros/cons, side-by-side options)
-- Timeline or process flow (numbered steps, arrows)
-
-**Visual polish:**
-- Icons in small colored circles next to section headers
-- Italic accent text for key stats or taglines
-
-### Typography
-
-**Choose an interesting font pairing** — don't default to Arial. Pick a header font with personality and pair it with a clean body font.
-
-| Header Font | Body Font |
-|-------------|-----------|
-| Georgia | Calibri |
-| Arial Black | Arial |
-| Calibri | Calibri Light |
-| Cambria | Calibri |
-| Trebuchet MS | Calibri |
-| Impact | Arial |
-| Palatino | Garamond |
-| Consolas | Calibri |
-
-| Element | Size |
-|---------|------|
-| Slide title | 36-44pt bold |
-| Section header | 20-24pt bold |
-| Body text | 14-16pt |
-| Captions | 10-12pt muted |
-
-### Spacing
-
-- 0.5" minimum margins
-- 0.3-0.5" between content blocks
-- Leave breathing room—don't fill every inch
-
-### Avoid (Common Mistakes)
-
-- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
-- **Don't center body text** — left-align paragraphs and lists; center only titles
-- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
-- **Don't default to blue** — pick colors that reflect the specific topic
-- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
-- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
-- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
-- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
-- **Don't use low-contrast elements** — icons AND text need strong contrast against the background; avoid light text on light backgrounds or dark text on dark backgrounds
-- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
+## 样式与设计 = 一律走 ui-design（本节已删除内嵌设计素材）
+
+> ⛔ **最高优先级·强制**：配色 / VI / 字体配对 / 字阶 / 版式 / 视觉节奏 / 避免 AI 味——这些**「样式与设计」决策一律去 `ui-design` skill 立**（见 [design.md](design.md) 第一步，用系统提示「可用技能」列表里 **ui-design 卡片给的绝对目录** 读它，**别用相对 `../ui-design/`**——Read 锚 cwd 会解析错）。
+>
+> 这里**曾内嵌过配色表 / 字体配对表 / 版式清单，现已全部删除**。删除原因：内嵌一份"看着够用"的设计素材，会诱导你**就地取材、自满、跳过 ui-design**，做出千篇一律的 AI 味页面。设计智能只有**一个真相源**（ui-design），pptx 只负责"引用它 + 把 web 设计翻译到 PPT 画布"，不复制、不另存一份会漂移的副本。
+>
+> 兜底：万一在系统提示和 `Glob('**/ui-design/SKILL.md')` 里都定位不到 ui-design，**才**回退到通用设计常识自行决定（仅此一种例外）。
+
+**PPT 特有的硬约束**——尺寸（pt）/ 间距（英寸）/ PptxGenJS 避坑（ui-design 是 web 1920×1080 px 语境，给不了英寸+pt 这套）——见 **[design.md](design.md) 第三步及其后的「PPT 落地硬约束 / 避坑」**。那是 pptx 不可替代的增量，照它执行。
 
 ---
 
@@ -144,6 +110,63 @@ Choose colors that match your topic — don't default to generic blue. Use these
 
 Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
 
+### Compliance QA (硬门槛，先做)
+
+pptx 本质是 OPC zip 包。PowerPoint 打开时做**严格 OPC 校验**，包不合规会判「需要修复」、
+修复后内容丢失。**「某个库能 load/import ≠ PowerPoint 能干净打开」**——python-pptx 很宽容，
+会忽略目录条目等问题照样加载成功，**绝不要**拿「python-pptx 能否重新打开」当验证通过的判据
+（这正是损坏包溜过验收闸门的根因）。忠实校验用：
+
+```bash
+python scripts/opc_check.py output.pptx
+```
+
+退出码非 0 即不合规，按提示一步修回：`python scripts/opc_check.py output.pptx --repack output.fixed.pptx`。
+
+> 用 PptxGenJS「从零创建」时，**生成脚本必须用 Node 跑（`node x.mjs`），不要 `bun run`**——
+> Bun 下 JSZip 会产出非合规包（详见 [pptxgenjs.md](pptxgenjs.md) 文首铁律）。
+>
+> **用了 SVG 配图的，合规校验前先跑 `node scripts/svg_fallback.mjs deck.pptx`**：PptxGenJS 在 Node 下
+> 不栅格化 SVG 的 PNG 兜底（issue #401），不补的话下文 soffice 视觉 QA、旧版 PowerPoint、缩略图全破图。
+> 该脚本顺带做合规重打包（等价 `--repack`）。详见 [svg.md](svg.md)。
+>
+> 内容/视觉 QA（下文）是合规之后的补充，不能替代合规校验。
+
+### 第 6 项校验：Content_Types 孤儿 Override
+
+`opc_check.py` 现包含 6 项校验。第 6 项专门捕获「`[Content_Types].xml` 声明了
+zip 里不存在的 part」——OPC 规范允许这种「孤儿 Override」，python-pptx 也照常加载，
+但 PowerPoint 严格对账「声明 vs 实物」时会把数量严重不符的包判损坏。
+
+**典型症状**：PowerPoint 弹「找到无法读取的内容，是否要修复？」，
+但 `python scripts/opc_check.py xxx.pptx` 报 PASSED（旧版 5 项会误判通过）。
+
+**典型成因**：生成端把另一种 part 的数量当成这种 part 的数量，
+例如 18 张 slide 却声明了 18 个 `slideMaster{n}.xml`，实际只有 1 个母版。
+也见于「按模板复制后忘了同步删 Content_Types 行」。
+
+**触发后修复**：直接运行 `python scripts/opc_check.py bad.pptx --repack fixed.pptx`。
+`--repack` 会自动删除这些孤儿 `<Override>`，同时保留有效 Override、删除目录条目、
+强制 DEFLATE 并把 `[Content_Types].xml` 放回 zip 首位。
+
+### 布局/对比 确定性闸门（opc 之后、视觉 QA 之前）
+
+```bash
+python scripts/layout_lint.py deck.pptx
+```
+
+不依赖 soffice/截图，纯解析 slide XML，自动抓三类**可计算**的缺陷：
+
+- **残桩/过短连线**（< 0.2"）——无连接的短箭头是 AI 生成 PPT 的典型痕迹。
+- **形状叠加**——非背景、非包含的形状包围盒显著相交（内容互相压住）。
+- **低对比文字**——形状显式填充色 vs 其文字显式色，大字 < 3:1 / 正文 < 4.5:1（看不清）。
+
+退出码非 0 即有缺陷，按提示修。这是给**其他 agent / 弱模型**的防呆硬门槛——**不读文档也会被它拦下**。
+它**不替代**下面的视觉 QA（主题色继承、跨形状 z-order 层叠、文字截断等仍需眼睛），但先把可计算的挡掉。
+
+> 双保险：用 `scripts/deck_helpers.mjs` 的 `inkFor(bg)` / `assertReadable` / `connect(from,to)` 在
+> **生成期**就避开这三类缺陷（源头预防），本闸门在产物上兜底（模型无关、绕不过）。
+
 ### Content QA
 
 ```bash
@@ -227,6 +250,11 @@ pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed
 
 - `pip install "markitdown[pptx]"` - text extraction
 - `pip install Pillow` - thumbnail grids
-- `npm install -g pptxgenjs` - creating from scratch
+- `npm install -g pptxgenjs` - creating from scratch（**用 Node 运行，不要 `bun run`**）
+- `npm install sharp` - SVG → PNG 兜底栅格化（`scripts/svg_fallback.mjs` 用；本仓库已装）
+- `scripts/opc_check.py` - OPC 合规校验/重打包（仅依赖 Python 标准库，无需额外安装）
+- `scripts/layout_lint.py` - 布局/对比 确定性闸门：残桩连线 / 形状叠加 / 低对比文字（仅依赖 Python 标准库）
+- `scripts/svg_fallback.mjs` - SVG 配图兜底修复 + 合规重打包（Node + sharp + 调 opc_check.py）
+- `scripts/deck_helpers.mjs` - 可复用原生 addShape 矢量原语（结构图路线）
 - LibreOffice (`soffice`) - PDF conversion (auto-configured for sandboxed environments via `scripts/office/soffice.py`)
 - Poppler (`pdftoppm`) - PDF to images

package/skills/pptx/design.md

@@ -0,0 +1,82 @@
+# 设计先行：借 ui-design 的设计智能（阶段 1）
+
+做 PPT 的本质是**前端/平面设计 + 内容**，不是堆文字。动手画第一页之前，先立一套**设计系统**
+（配色 / VI / 字阶 / 版式 / 节奏），后面所有页照着落。这套设计智能不自己凭空想，**借同仓的
+`ui-design` skill**——它专门干「高质量视觉设计」。本文是「读它什么、提取什么、怎么翻译到 PPT、丢弃什么」的桥。
+
+> ⛔ **最高优先级·强制**：PPT 的一切**样式与设计**（配色/VI/字体/字阶/版式/节奏/避免 AI 味）**必须**借 ui-design 来定——这是不可跳过的第一步，别自己拍脑袋。pptx 自身已删除全部内嵌设计素材，**设计智能只有 ui-design 这一个真相源**。
+>
+> 何时跳过：仅当用户明确只要「快速草稿/纯文本大纲、不要排版」时可略过本阶段；正式 deck 一律必做。
+
+## 第一步：读 ui-design（只读，按需）
+
+> 🧭 **怎么定位 ui-design（重要，别用相对路径）**：`ui-design` 是**独立的同级技能**，它的**绝对目录已经在系统提示的「可用技能」列表里**（每张技能卡片都带 `技能目录:` 绝对路径）。读它时**用列表里 ui-design 卡片给的那个绝对目录**拼出绝对路径再 Read，例如 `<ui-design绝对目录>/SKILL.md`、`<ui-design绝对目录>/references/vi-aqua-glass.md`。**不要写相对的 `../ui-design/...`**——Read 工具把相对路径锚到当前工作目录(cwd)，cwd 通常不是 skills 的父目录，`../` 会解析到错误位置读不到。万一系统提示里拿不到该绝对目录，就用 `Glob('**/ui-design/SKILL.md')` 定位后再读。
+
+在 ui-design 目录下按需读这些（路径 = `<ui-design绝对目录>/` + 下面的相对名）：
+
+- `SKILL.md` —— 任务分流、关键约束、避免 AI 味清单。**必读**（它顶部还会指你按需读下列各 reference）。
+- `claude_design.md` —— 完整设计协议；看其中 **deck / 固定画布 / 字号尺度** 段落。
+- `references/vi-*.md` —— **VI 模板，按主题选一个读**（不要全读）：
+  - `references/vi-aqua-glass.md` —— 浅蓝白玻璃通透，**适合 AI 产品 / SaaS / 知识库 / PPT deck**（多数科技 deck 默认首选）。
+  - `references/vi-harbor-ledger.md` —— 克制运营型 VI，适合 B2B dashboard / 金融 / 物流 / 经营驾驶舱。
+  - `references/vi-obsidian-optics.md` —— 黑曜影像 VI，适合摄影器材 / 影像 / 创作者硬件。
+  - `references/vi-nebula-console.md` —— 深色科技半透明，适合科幻 UI / 云服务 / 开发者工具 / 安全。
+  - `references/vi-violet-meridian.md` —— 紫曜经线 VI，适合紫/蓝紫、AI 智能工作台 / 开发者工具的清爽方向。
+  - `references/vi-solar-relay.md` —— 日冕中继 VI，适合红橙多彩、网络加速 / 连接 / 移动端的活力科技方向。
+- **缺品牌、需求空、或没把握时**：读 `references/design-execution-playbook.md`（按它写一份「设计执行声明」再动手）+ `references/aesthetic-direction.md`（从零定审美方向）。这正是"脑袋空空"时的兜底。
+
+缺品牌上下文时，选一个匹配主题的 VI 取其「视觉 DNA」（不要照抄它的品牌名/示例内容）。
+
+## 第二步：提取这些「可迁移的设计智能」
+
+从 ui-design 提炼，落成本次 deck 的设计系统：
+
+- **配色系统**：内容相关、有主张的调色板（别默认蓝）；**主导 60–70% + 1–2 辅助 + 1 强调**，绝不等权。
+  深色用于封面/结论页、浅色用于内容页（三明治结构），或全程深色走高级感。
+- **VI 视觉 DNA**：选定模板的气质（玻璃通透 / 运营克制 / 影像冷光 / 深色科技），贯穿每页一个重复母题。
+- **字体配对 + 字阶**：标题字有个性、正文字干净；建立清晰的大小层级（见下「翻译」表）。
+- **版式网格**：统一边距、栅格、对齐；卡片/列保持一致。
+- **视觉节奏**：每页一个视觉主角，留白克制；变换版式（两栏 / 图标行 / 2×2 / 半幅图），别每页同一套。
+- **避免 AI 味清单**：紫色渐变、重复圆角卡堆叠、无意义假数据、占位假文、**标题下双下划线**、过度表情符号、装饰性堆砌——全避开。
+  - ⚠️ ui-design 清单里的「纯 SVG 假图」是 **web 语境**（别拿装饰 SVG 冒充真实产品页），与本 skill 用 SVG 做**真实可编辑美术配图**不冲突——见 [svg.md](svg.md) 的图形决策规则。
+
+## 第三步：翻译到 PPT 的固定画布（关键）
+
+ui-design 的载体是 **HTML（1920×1080 px / rem）**；PPT 是**固定英寸画布 + EMU**。把设计**翻译**过来，别照搬 web 机制：
+
+| ui-design（web） | PPT 落地 |
+|---|---|
+| 1920×1080 px 画布 | `LAYOUT_WIDE` 13.3"×7.5"（图多用它）或默认 10"×5.625" |
+| px / rem | **英寸**（PptxGenJS 坐标）；颜色 6 位 hex 不带 `#` |
+| 正文 ≥24px@1080 | PPT 正文 **14–16pt**、章节头 20–24pt、标题 **28–44pt**、注脚 10–12pt |
+| CSS 渐变 | SVG 配图承载（`addShape` 不支持渐变填充）——见 `svg.md` |
+| flex/grid 布局 | 手算坐标摆 `addShape`/`addText`；用统一边距(≥0.5")与间距(0.3–0.5") |
+
+**直接丢弃**（PPT 用不上、别引入）：Tweaks / React+Babel / `deck_stage.js` / `scrollIntoView` 禁令 /
+localStorage 持久化 / `check_ui_artifact.py` / 视口缩放 JS。这些是 HTML deck 的机制，PPT 由 PowerPoint 自己负责。
+
+## PPT 落地硬约束 / 避坑（ui-design 给不了的 PPT 特有部分）
+
+调色板 / VI / 字体**配对**的设计智能去 ui-design 取（上面第一步已说）；**落到 PPT** 的字号/字阶按上表。
+以下是 ui-design 顾不到的 PPT（英寸 + pt + PptxGenJS）机制硬约束，照此执行：
+
+- 正文**左对齐**，只有标题可居中；正文别居中。
+- 标题 36–44pt 与正文 14–16pt **拉开字号对比**，层级才立得住。
+- 文本框与形状对齐时给文本框设 `margin: 0`（否则默认内边距让对齐错位）。
+- **绝不在标题下加装饰下划线/强调线**——AI 生成 PPT 的典型标志，用留白或背景色区隔。
+- **文字对比 ≥ 4.5:1（大字/标题 ≥ 3:1）**，杜绝「浅底浅字 / 深底深字」（最常见的看不清根因）。
+  深色页的标题别用近黑默认色：给 `deck_helpers` 的 `drawTitle(s, …, { bg })` 传背景色，标题色会**按背景自动取可读色**（`inkFor(bg)`）；任何「文字配背景」都可用 `assertReadable(fg, bg)` 在生成期把关。
+- **连线只用来连两个真实形状，且 ≥ 0.25"**——别留很短、没明确连到东西的残桩箭头（AI PPT 典型缺陷）。
+  用 `deck_helpers` 的 `connect(s, fromRect, toRect)` 由两个形状边框**自动算边到边端点**，别手填易飘/易残桩的坐标。
+- **每页都要有视觉主角**（图 / 图标 / 图表 / 形状），别整页纯文字 + 项目符号。
+- **逐页变换版式**（两栏 / 图标行 / 2×2 / 半幅图），别每页同一套。
+- 间距统一选 0.3" 或 0.5"，别随机混用；最小边距 0.5"；**形状之间不要叠加**（卡内放文字 OK，部分压住不行）。
+
+> ✅ 这三类（对比 / 残桩连线 / 叠加）落盘后用 `python scripts/opc_check.py deck.pptx` 之后再跑
+> **`python scripts/layout_lint.py deck.pptx`** 做确定性兜底（详见 SKILL.md「布局/对比 确定性闸门」）——
+> 弱模型不读这段也会被闸门拦下。
+
+## 可选：复杂插画走「HTML 草稿 → 提取 SVG」
+
+需要复杂插画/信息图时，可先用 ui-design 在 HTML 里出视觉草稿，再把其中的 `<svg>` lift 出来，
+按 `svg.md` 的规则（分组、viewBox、文字回原生层）整理后走兜底管线嵌入 pptx。

package/skills/pptx/examples/README.md

@@ -0,0 +1,29 @@
+# pptx 范例
+
+脑袋空空的 AI 临摹这一份就懂「分层混合」全套路。
+
+## hybrid_example.mjs —— 3 页端到端范例
+
+```bash
+node skills/pptx/examples/hybrid_example.mjs
+```
+
+演示三条图形路线 + 原生文字，并在生成后自动跑 `svg_fallback.mjs`（补真 PNG 兜底 + OPC 合规重打包 + 自校验）：
+
+- **页1 封面**：真 SVG 满铺美术背景（`assets/cover-bg.svg`）+ pptx 原生文字标题。
+- **页2 架构图**：纯原生 `addShape` 框图 + 箭头 + 活文字（复用 `../scripts/deck_helpers.mjs`）。
+- **页3 内容**：原生项目符号文字 + SVG 图标（`assets/icon-spark.svg`）+ 原生 `addShape` 色块。
+
+产物 `hybrid_example.pptx`：OPC 校验全绿，含 2 张可在 PowerPoint 365「转换为形状」取消组合编辑的 SVG。
+
+## assets/
+
+- `cover-bg.svg` —— 满铺背景（渐变 + 有机色块 + 流线）；范例「美术配图用 SVG」。
+- `icon-spark.svg` —— 小图标；范例「图标用 SVG」。
+
+两份都遵守 `../svg.md`：一个语义元素一个 `<g>`、viewBox 对齐比例、文字不写进 SVG。
+
+## 铁律对照
+
+文字永远原生 `addText`（不烤进图片）· 结构图 `addShape` · 美术配图 SVG + `svg_fallback.mjs` · 真照片才 `addImage(png/jpg)`。
+生成脚本用 **Node** 跑，不要 Bun（见 `../pptxgenjs.md` 文首铁律）。

package/skills/pptx/examples/hybrid_example.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/* eslint-disable */
+// ============================================================================
+//  skills/pptx/examples/hybrid_example.mjs
+//  ----------------------------------------------------------------------------
+//  「分层混合」端到端范例（脑袋空空的 AI 临摹这一份就懂全套路）。3 页演示三条图形路线：
+//    页1 封面   —— 真 SVG 满铺美术背景（assets/cover-bg.svg）+ pptx 原生文字标题
+//    页2 架构图 —— 纯原生 addShape 框图 + 箭头 + 活文字（deck_helpers）
+//    页3 内容   —— 原生项目符号文字 + SVG 图标 + 原生 addShape 色块布局
+//  铁律对照：文字永远原生 addText（不烤进图片）；结构图 addShape；美术配图 SVG；真照片才 addImage(png/jpg)。
+//
+//  运行（Node，不要 Bun）：
+//    node skills/pptx/examples/hybrid_example.mjs
+//  产物：examples/hybrid_example.pptx（已自动跑 svg_fallback.mjs：补真 PNG 兜底 + OPC 合规重打包 + 自校验）
+// ============================================================================
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import PptxGenJS from 'pptxgenjs';
+import { drawTitle, drawNode, connect, drawCard, drawRect, drawFooter } from '../scripts/deck_helpers.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const asset = (f) => path.join(__dirname, 'assets', f);
+
+// 设计系统（阶段1 产物：本应来自 design.md 借 ui-design 定的 VI；此处直接给定）
+// 注：teal 用更深的 00786A（而非常见的 00A896）——后者配白字仅 2.98:1，过不了对比闸门；
+// 加深后白字 ≈5.4:1、teal 当强调文字落白底也 ≈5.4:1，均清晰可读（layout_lint 会把关）。
+const C = { navy: '1E2761', deep: '0F172A', ice: 'CADCFC', white: 'FFFFFF', teal: '00786A', card: 'F8FAFC', grayL: 'E2E8F0', grayD: '475569' };
+const F = { title: 'Consolas', body: 'Calibri' };
+
+const pres = new PptxGenJS();
+pres.layout = 'LAYOUT_WIDE'; // 13.3" × 7.5"
+pres.author = 'minimal-agent pptx skill';
+pres.title = '分层混合范例';
+
+// ---- 页1 封面：SVG 满铺背景 + 原生文字 ------------------------------------
+{
+  const s = pres.addSlide();
+  s.addImage({ path: asset('cover-bg.svg'), x: 0, y: 0, w: 13.3, h: 7.5 }); // 美术 → SVG
+  s.addText('分层混合 PPT', { x: 0.8, y: 2.7, w: 8, h: 1.0, fontFace: F.title, fontSize: 46, bold: true, color: C.white, margin: 0 });
+  s.addText('SVG 美术配图 · 原生矢量结构图 · 原生可编辑文字', { x: 0.82, y: 3.8, w: 9, h: 0.5, fontFace: F.body, fontSize: 16, color: C.ice, margin: 0 });
+}
+
+// ---- 页2 架构图：纯原生 addShape ------------------------------------------
+{
+  const s = pres.addSlide();
+  s.background = { color: C.white };
+  drawTitle(s, '§1', '三条图形路线（纯原生矢量框图）', { titleSize: 26, bg: C.white });
+  const nodes = [
+    { label: '原生文字\naddText', fill: C.navy },
+    { label: '结构图\naddShape', fill: C.teal },
+    { label: '美术配图\nSVG + 兜底', fill: C.ice, textColor: C.navy },
+    { label: '真照片\naddImage', fill: C.grayD },
+  ];
+  const w = 2.5, h = 1.5, gap = 0.6, y = 2.6;
+  const startX = (13.3 - (w * nodes.length + gap * (nodes.length - 1))) / 2;
+  nodes.forEach((n, i) => {
+    n.rect = { x: startX + i * (w + gap), y, w, h };
+    drawNode(s, n.rect.x, y, w, h, n.label, { fill: n.fill, textColor: n.textColor || C.white, fontFace: F.body, fontSize: 13 });
+  });
+  // 用 connect() 由两个节点矩形自动算边到边端点 —— 箭头永远贴住节点、绝不残桩/飘移。
+  for (let i = 0; i < nodes.length - 1; i++) {
+    connect(s, nodes[i].rect, nodes[i + 1].rect, { color: '94A3B8', width: 2 });
+  }
+  s.addText('每个方框都是 PowerPoint 原生对象：点一下就能选中、改色、移动、改字。', {
+    x: 0.5, y: 4.6, w: 12.3, h: 0.4, fontFace: F.body, fontSize: 13, italic: true, color: C.grayD, align: 'center', margin: 0,
+  });
+  drawFooter(s, '分层混合范例 · minimal-agent pptx skill', '2 / 3');
+}
+
+// ---- 页3 内容：原生文字 + SVG 图标 + 原生色块 -----------------------------
+{
+  const s = pres.addSlide();
+  s.background = { color: C.white };
+  drawTitle(s, '§2', '一页里如何混用', { titleSize: 26, bg: C.white });
+  s.addImage({ path: asset('icon-spark.svg'), x: 0.6, y: 2.0, w: 0.8, h: 0.8 }); // 图标 → SVG
+  s.addText([
+    { text: '文字', options: { bold: true, color: C.teal, breakLine: false } },
+    { text: ' 用原生 addText —— 可编辑、可重排，永不烤进图片', options: { breakLine: true } },
+    { text: '结构', options: { bold: true, color: C.teal, breakLine: false } },
+    { text: ' 用 addShape —— 框、箭头、色块都是原生对象', options: { breakLine: true } },
+    { text: '美术', options: { bold: true, color: C.teal, breakLine: false } },
+    { text: ' 用 SVG（图标/背景/渐变/插画）+ svg_fallback 补兜底', options: { breakLine: true } },
+  ], { x: 1.6, y: 1.95, w: 6.0, h: 2.2, fontFace: F.body, fontSize: 15, color: C.grayD, valign: 'top', margin: 0, paraSpaceAfter: 8 });
+
+  // 右侧三色块（原生 addShape 色块布局）
+  const blocks = [['设计', C.navy], ['图形', C.teal], ['落盘', C.deep]];
+  blocks.forEach(([t, color], i) => {
+    const x = 8.2 + i * 1.6;
+    drawCard(s, x, 2.0, 1.4, 2.4, { fill: color, border: color, radius: 0.08 });
+    s.addText(t, { x, y: 2.0, w: 1.4, h: 2.4, fontFace: F.title, fontSize: 18, bold: true, color: C.white, align: 'center', valign: 'middle', margin: 0 });
+  });
+  drawRect(s, 0.5, 5.2, 12.3, 0.04, { fill: C.grayL });
+  s.addText('SVG 区域在 PowerPoint 365 里右键「图形格式 → 转换为形状 → 取消组合」即可逐元素编辑。', {
+    x: 0.5, y: 5.4, w: 12.3, h: 0.5, fontFace: F.body, fontSize: 13, color: C.grayD, margin: 0,
+  });
+  drawFooter(s, '分层混合范例 · minimal-agent pptx skill', '3 / 3');
+}
+
+const out = path.join(__dirname, 'hybrid_example.pptx');
+await pres.writeFile({ fileName: out });
+console.log('[OK] wrote', out);
+
+// 生成后强制：补真 PNG 兜底 + OPC 合规重打包 + 自校验（in-place，留 .bak）
+const r = spawnSync('node', [path.join(__dirname, '..', 'scripts', 'svg_fallback.mjs'), out], { stdio: 'inherit' });
+process.exit(r.status ?? 0);

package/skills/pptx/pptxgenjs.md

@@ -1,5 +1,17 @@
 # PptxGenJS Tutorial
 
+## ⚠️ 运行时铁律：必须用 Node 跑，不要用 Bun
+
+PptxGenJS 底层用 JSZip 打包 pptx。**Bun 下的 JSZip 会产出不合规的 OPC 包**
+（含 ZIP 目录条目 + STORE 无压缩 + `[Content_Types].xml` 不在首位），
+PowerPoint 严格 OPC 校验会因此判「需要修复」、修复后内容丢失。Node 下的
+JSZip 不会有这个问题。
+
+- ✅ 生成脚本一律用 **Node** 运行：`node make_deck.mjs` 或 `npx tsx make_deck.ts`
+- ❌ **不要用 `bun run`** 跑 PptxGenJS 生成脚本（即便项目主体是 Bun）
+- 生成完成后，**必须跑一步 OPC 合规校验**（见本文末「生成后强制：OPC 合规校验」），
+  这是硬门槛——「能被 python-pptx 重新打开」不等于「PowerPoint 能干净打开」。
+
 ## Setup & Basic Structure
 
 ```javascript
@@ -16,6 +28,8 @@ slide.addText("Hello World!", { x: 0.5, y: 0.5, fontSize: 36, color: "363636" })
 pres.writeFile({ fileName: "Presentation.pptx" });
 ```
 
+> 跑这个脚本用 `node make_deck.mjs`，**不要** `bun run make_deck.mjs`（见文首铁律）。
+
 ## Layout Dimensions
 
 Slide dimensions (coordinates in inches):
@@ -418,3 +432,30 @@ titleSlide.addText("My Title", { placeholder: "title" });
 - **Layouts**: LAYOUT_16x9 (10"×5.625"), LAYOUT_16x10, LAYOUT_4x3, LAYOUT_WIDE
 - **Alignment**: "left", "center", "right"
 - **Chart data labels**: "outEnd", "inEnd", "center"
+
+---
+
+## 生成后强制：OPC 合规校验（硬门槛）
+
+写出 pptx 后**必须**跑一次忠实的 OPC 合规校验。这才是「PowerPoint 能否干净打开」的真实
+判据——**不要**只用 python-pptx 能否 load 来判断通过（python-pptx 很宽容，会忽略目录条目
+等问题照样加载成功，导致损坏的包误报通过、溜过验收）。
+
+```bash
+python scripts/opc_check.py output.pptx
+```
+
+- 退出码 0 + 打印 PASSED → 合规，可交付。
+- 退出码非 0 → 打印具体不合规项（目录条目 / Content_Types 不在首位 / 悬空关系 /
+  0 字节媒体 / 坏 XML）。**一步修回合规：**
+
+```bash
+python scripts/opc_check.py output.pptx --repack output.fixed.pptx
+# 重打包后用合规的 output.fixed.pptx 交付
+```
+
+校验项见 `scripts/opc_check.py` 头注。它只依赖 Python 标准库，可对任意 pptx/docx/xlsx 直接
+`python scripts/opc_check.py <file>` 跑。
+
+> 内容/视觉 QA（markitdown 抽文本、转图片人工核对）仍要做（见 SKILL.md 的 QA 章节），
+> 但**合规校验是先决硬门槛**：包不合规，内容再对也会被 PowerPoint 判损坏。