dsh-ppt-studio 1.1.0

package/docs/00-/350/256/276/350/256/241/346/272/220.md

@@ -0,0 +1,537 @@
+# PPT 插件设计文档（头脑风暴成果 · 持续更新）
+
+> 状态：讨论推进中，主干已定；待细化项见文末清单。
+> 愿景：**该插件能应用到复杂场景中，实现其他工具做不好的 PPT 制作。**
+> 差异化 = 四类任务全兼容 + 布局工程（元素冲突防治）+ 跨页整体性 +
+> 协作模式光谱 + 引擎可插拔 + 双通道控制 + 质检门禁。
+> **复杂场景定义（已拍板）**：长 deck（50+ 页）+ 多源内容整合 + 高认知负荷
+> 内容（对忠实度/严谨性要求极高）——设计重心向审计门禁、证据链、
+> 整体一致性倾斜。
+> 目标：在 dsh 上做一个专门用于制作 PPT 的插件（agent preset + 工作流），
+> 包含标准模式（Standard）全部功能；用户提出 PPT 制作类任务时进入专门工作流，
+> 非 PPT 任务行为与标准模式完全一致。
+
+---
+
+## 1. 定位与形态
+
+- **一个 agent preset**（从 `standard` copy，标准模式全部功能零删减）
+  + **路由/工作流行**（借鉴 `router-standard` 已验证模式：消息分类 → 注入工作流）
+  + **PPT 专用工具集**（见 §10）。
+- 部署位置：`${DSH_HOME:-$HOME/.dsh}/.agent-presets/<preset-id>/`，
+  从 shipped `standard` 通过 `agentPresets.copy()` 复制开始，保证可加载。
+- **分发（已拍板）**：官方 bundle 装配通道（`dsh plugin add` + 预设复制，
+  重启生效，**不依赖注入器**）+ 开源发布（GitHub Release + npm 包，
+  参照现有生态 dsh-external 模式）；插件 = npm 包 + preset 目录两部分。
+- 标准模式 = shipped `presets/standard/agent.cordis.yml`（persona / shell /
+  文件系统 / jobs / skills / goals / plan mode / compaction / 委托
+  （subagent、spawn、fork、workflow、ralph）/ ask-user / todo / web）。
+  新预设 = 该文件全量 + 增量行。
+
+### 生命周期与路由（双通道控制：语义 + 斜杠命令）
+
+**关键前提**：PPT 工作流是"状态/语境"而非"能力切换"——预设 = 标准模式
+全功能 + 工作流提示词，进入/退出只切换提示词语境，不改变能力。因此
+语义误判/漏判代价近零，路由可宽松设计；命令 > 语义。
+
+- **进入**：① 语义——消息含**明确 PPT 任务意图**（制作/修改/补完/总结/
+  做 slides 等）才进入；纯提及（"我看过那个 PPT 文档…"）不触发；
+  **弱信号不切换**。② 命令——`/ppt on` 强制进入。
+- **退出**：① 语义——消息与 PPT **明确无关**才退出；模棱两可保持
+  （代价低）。② 命令——`/ppt off` 强制退出。
+- 生命周期内所有动作视为工作流内：中途改需求（"第 3 页改成…"）、
+  换风格、修 bug。
+- 复用 router 实测经验：分类信号 + 固定"近距离引导"（每轮几行提示），
+  router-standard 实测路由准确率 96%。
+- **非 PPT 任务 → 不进入工作流，行为与标准模式完全一致。**
+
+### 主要规则
+
+- 命令 > 语义；语义推断仅作为"初始倾向"，最终默认档以"一次轻量确认"落地。
+- 命令写入 `spec.hardConstraints`（用户明确要求，任何档位都严格遵循）；
+  `/ppt free` 后询问环节可跳过。
+- 命令可"预设定"：任务开始前直接 `/ppt strict` 等效于说明本次开工要确认。
+
+### 斜杠命令面（决策：全量子命令首版）
+
+| 命令 | 作用 |
+|---|---|
+| `/ppt` | 状态查询（工作流状态/档位/引擎/质量模式/暂停点） |
+| `/ppt on` `/ppt off` | 强制进入/退出（覆盖语义判断） |
+| `/ppt free` `/ppt mid` `/ppt strict` | 强制三档协作模式（自由/中间/严格） |
+| `/ppt fidelity strict\|auto\|free` | 强制内容忠实度（支持 `--page N` 页级） |
+| `/ppt style ...` | 风格参数（如 `/ppt style blue-toned texty aligned`） |
+| `/ppt review none\|points\|every` | 审阅频率（不打扰/关键点/每页） |
+| `/ppt engine pptd\|python-pptx\|pptxgenjs` | 强制引擎（可用性探测展示于状态查询） |
+| `/ppt quality quick\|standard\|audit` | 强制质量模式 |
+| `/ppt pause-after outline\|layout\|pages\|overall` | 追加/覆盖暂停点 |
+| `/ppt help` | 帮助与当前状态 |
+
+实现载体参考 dsh 既有 command 机制（command-goal/command-compact），
+preset 内注册命令行 + 会话级状态存储（工作流状态/档位配置写 spec 上下文）；
+精确机制实现时用 Inspect 确认。
+
+---
+
+## 2. 任务形态（差异化亮点）
+
+封闭四类 + 回退通用：
+
+| 入口 | 用户给了什么 | 产出 | 工作流起始点 |
+|---|---|---|---|
+| **从头制作** | 主题/内容；可选内置模板或参考模板 | 新 deck | 路由 → 规格 → 全流程 |
+| **补完** | 已有 PPT + 增页需求 | 原 PPT + 新增页 | 解析 → 理解风格/结构 → 从大纲后插入，不重做已有页 |
+| **修改** | 初版 PPT + 某几页修改要求 | 修改后 PPT | 解析 → 定位目标页 → 只对目标页走页级工作流 |
+| **总结** | PPT + 总结要求 | 报告内容/文件（可能不是 pptx） | 解析 → 内容抽取 → 直接生成报告 |
+| 其他/判不出 | — | — | **回退通用标准模式能力**（预设本就含全部功能） |
+
+- **已有 PPT 格式**（决策）：.pptx 为主 + 降级重建（解析不动时拆页成图 →
+  模型看图重建）。
+- **还原保真度**（决策）：**内容保真、版式可从新**——导入器只需抽取
+  **内容层**（文字/结构/数据/素材）与**风格层**（字体/配色/版式比例/母版特征），
+  不做"布局逆推"；新页/改后页在内容保真 + 风格参照基础上重新设计。
+
+---
+
+## 3. 模型配置（决策：与标准模式同款读图方案）
+
+预设**不自带、不强制**任何读图通道：用户在自己的 dsh 里怎么配
+（主模型多模态直读 / 其他模型辅助 / MCP 外接 / 不能读），PPT 预设沿用同一套。
+模型路由、MCP、插件装配都在 host 层、由用户偏好决定；预设只做
+**能力探测 + 流程适配**：
+
+- **能力探测**：运行时读当前会话的读图能力（主模型是否多模态、工具目录中
+  是否有读图工具、是否有可派发的视觉子代理通道），不硬编码模型元数据。
+- **软步骤（审美/一致性评审）**：有视觉 → 截图回看；无视觉 →
+  自动降级**结构 Lint**（数值断言：溢出、重叠 box、字号层级、颜色对比度、
+  图片比例、字体缺失），并标注"未经视觉审阅"。
+- **硬步骤（必须看到，如读懂用户参考图）**：无视觉 → 工作流提示模型
+  "本会话无视觉通道，请自选其他方式"（OCR/图像描述/问用户/跳过并标注），
+  **不阻止流程**，将"哪些内容未经视觉确认"写入交付说明。
+- 读图通道示例（探测到才用，不绑定）：
+  - 主模型多模态直读；
+  - 外接插件读图（如本机 dsh-vision-toolkit：Image Q&A / OCR / pixel diff）；
+  - 视觉子代理（tool-subagent 的 modelSelectionSettings，实现时用 Inspect
+    确认精确形态）——适合"审美评审"：派评审子代理读截图出报告，多页并发。
+
+---
+
+## 4. 工作流：loop + 两档审核 + 可配置暂停点
+
+```
+      ┌──────────────────────────────────────┐
+      │  ① 内容大纲确认（含素材准备）         │
+      ▼                                      │
+   ② 页面布局设计 ──► ③ 各页制作 ──► ④ 各页审核
+                                        │(页级不过→回到③修该页)
+      ▲                                ▼
+      │                         ⑤ 整体审核 ──► ⑥ 修改完善
+      │                          (整体不过/修改建议 → 回到相应阶段)
+      └──────────────────────────────────────┘
+                 循环直到符合要求 → 交付
+```
+
+- **④ 页审**：每页做完即时审（渲染→截图→评审/Lint，页级门禁）。
+- **⑤ 整体审**：全 deck 一致性/叙事/风格统一。
+- **暂停点由用户事先指定**（如 `pauseAfter: [大纲, 布局, 每页, 整体]`）：
+  用户可只卡关键点，也可全自动一条龙、最后一次性看成品。
+  配置在 S0 规格澄清时收集进 spec（"哪些步骤做完要给你看"），允许中途改。
+- **交互确认点**（决策：三处默认）：S0 规格、S2 样例页、S5 交付前预览；
+  页审/循环自动跑不打扰。
+- **预览交互（已拍板）**：dsh 网页 UI 内嵌预览——client 插件在对话中直接
+  渲染每页/总览图（可翻页、可确认），用户不离开对话；与渲染器共用
+  PPTD→HTML 输出。
+
+### 阶段细节（从头制作主线；其他任务从对应点插入）
+
+| 阶段 | 做什么 | 产物 |
+|---|---|---|
+| S0 规格澄清 | 受众/场景/时长/页数/风格参考/素材/必须内容 → ask_user 补齐 | `spec` |
+| S1 大纲故事线 | 叙事结构（开场-问题-方案-证据-行动），页级规划；**内含素材准备**（见 §5） | `outline` + 素材 manifest |
+| S2 视觉定调 | 从零 + 可选模板：字体/配色/网格/图表风格 → 先做 1 张"模板页"并先行评审一轮 | `theme` + 样例页 |
+| S3 逐页量产 | 主 agent 调度：先串行 2-3 页确认稳定，再并行（subagent/workflow）摊开 | 全部页面 |
+| S4 渲染审阅循环 | 逐页渲染 → 截图 → 视觉评审/Lint → 修正，循环到门禁通过（自动，不打扰） | 通过的页面 |
+| S5 一致性校验 | 全 deck：风格 token 一致、术语一致、图表数据一致、页码导航 | QA 报告 |
+| S6 导出交付 | 导出 .pptx + 预览 + 交付说明（未经视觉审阅项、素材来源、修改指引） | 交付物 |
+
+### 量产形态（决策：主 agent 调度 + 并行量产）
+
+- 主 agent 主导阶段间调度；S3 用量产引擎（subagent / workflow）并行每页；
+  先串行 2-3 页定调，稳定后并行摊开。
+
+### 门禁机制（决策：产物 + 校验文件）
+
+- 门禁 = 产物存在 + schema 校验 + 质量报告硬验证；
+- 状态写入中间层项目的 page 状态：`draft → rendered → reviewed → approved`；
+- S4 未通过不允许 S6 导出；通过与否记录在状态文件，agent 可读可写；
+- 不依赖强状态机插件（保留 agent 自由度）。
+
+---
+
+## 4.5 协作模式（用户参与光谱，非两种硬编码模式）
+
+用户描述的两类极端（"自由发挥" / "严格把控"）是一个**参数化光谱**的两端，
+不同用户/不同任务/不同倾向落在光谱任意位置（如：开工前全确认但工作中不审阅）。
+
+### 五维参数
+
+| 维度 | 自由发挥端 | 严格把控端 |
+|---|---|---|
+| A 开工前确认深度 | 0 轮（说开干就开干） | 多轮 grill（逐项确认） |
+| B 制作中审阅频率 | 0（做完直接交成品） | 每页/关键点积极审阅 |
+| C 内容忠实度 | 自由发挥补充 | 严格忠实（**支持页级**：前述 strict，后段 free） |
+| D 风格遵从度 | 自由发挥 | 严格跟模板/参考（粒度弹性：用户可只指定配色，其余自决） |
+| E 未决事项处置 | 全由模型自决 | 必须用户拍板 |
+
+### 档位感知与适配（采用：情境自适应 + 轻量确认 + 会话内记忆）
+
+1. **推断**：任务路由时从用户措辞/任务情境推出默认档位
+   （"你直接做吧"→A0B0；"我们仔细确认下"→多轮；学术/正式→严谨倾向；
+   轻松展示→自由倾向；无法判→中间档）；
+2. **一次轻量确认**：S0 开头给出推断档位让用户一句话确认/纠正，
+   不做问卷轰炸；
+3. **grill-me 机制（严格档）**：**分层问题清单，按档位选择问哪些**——
+   L1 影响交付物实质（受众/用途/忠实度/规模/风格基调）→
+   L2 细节参数（配色/图文比/对齐/模板遵从度）→ L3 可选（素材偏好等）；
+   一次一问（或至多一小簇）；每问用户可答"你决定"即跳给模型自决；
+   答案全部写入 spec；
+4. **硬约束/自决分账**：`spec.hardConstraints`（用户明确给出的要求 =
+   任何档位都严格遵循，包括"自由发挥"模式）+ `spec.freeParameters`
+   （未指定，模型自决）；
+5. **记忆（会话内）**：同会话内多次 PPT 任务复用上次档位，每次仍可覆盖；
+   跨会话不自动继承，避免误用。
+6. **命令强制**：任意档位参数均可用斜杠命令强制（`/ppt free|mid|strict`、
+   `/ppt fidelity ...`、`/ppt review ...` 等，见 §1.2 命令面）；命令写入
+   hardConstraints，优先于语义推断与会话记忆。
+
+### S0 规格字段扩展
+
+- `fidelity`：strict / auto / free（支持 `pages[].fidelity` 页级覆盖）；
+- `styleStrictness`：一组**可选参数**（配色色系/素花/图文比/对齐/模板遵从度），
+  每项允许"用户未指定 → 模型自决"；
+- `collaboration`：confirmDepth / reviewPoints / fidelity / styleStrictness /
+  unresolved（五维档位）。
+
+---
+
+## 5. 素材准备（S1 大纲确认的内含步骤）
+
+**目标**：明确需要什么素材 → 按用户偏好渠道搜集 → 充分理解 → 明确如何用。
+
+### 素材来源与优先级
+
+- 来源四类：① 用户直接提供；② 从用户内容提取（Word 文档内图片、
+  网页链接→界面截图、文档图表导出等）；③ 插件自生成（流程图/架构图/
+  示意图等；暂不含 AI 生图）；④ 上网搜索（首版靠标准模式现有
+  web_search/web_fetch 能力，不单独建素材库）。
+- 默认优先级：**① > ② > ③（④ 含于生成/补充）**；用户可事先通过指令
+  指定偏好（如"优先搜网上的"，或某类素材禁用某种渠道）。
+- 策略存为 spec 配置 `materialPolicy`，允许用户按次修改。
+
+### 流程
+
+1. **素材需求清单**：从大纲推导每页需要的素材（类型/用途/规格要求），
+   明确"哪些可以不做素材"（如纯文字排版）。
+2. **搜集**：按优先级逐渠道补足；记录每项来源与获取方式
+   （用户提供路径 / 提取位置 / 生成命令 / 搜索 URL）。
+3. **理解（分层）**：
+   - **物理层**（程序化，无需视觉）：图片宽高/比例/格式/透明底等元数据
+     可机器读取——供布局计算引用；
+   - **语义层**：能读图 → 视觉理解；不能读图 → 请求用户给出具体描述，
+     **把语义描述写入素材 manifest**（一次确认，后续阶段直接引用，
+     不反复打扰）。
+4. **素材使用计划**：每个素材明确用于哪页哪个位置/用途；无法满足需求的
+   素材要记录"缺口"并决定替代方案。
+
+### 产物：素材 manifest
+
+```
+素材 manifest：{ id, 路径/URL, 来源(用户/提取/生成/搜索),
+                物理规格(尺寸/比例/格式), 语义理解(文本), 使用计划, 状态 }
+```
+
+状态：`pending → collected → understood → assigned`；素材清单中
+"待确认项"（如无视觉需用户描述的图）在 S0 暂停点一次性向用户问清。
+
+---
+
+## 6. 布局工程：元素区块冲突防治（核心亮点）
+
+### 定义与冲突模式
+
+**元素区块** = 一页中占据页面空间的一切：图形、文本框、图片、表格等。
+
+冲突模式（驱动性分类）：
+- **重叠**：元素区块相互叠压（文本戳进图片等）；
+- **出界**：超出页面 / 超出背景块（放映不可见/跑出设计区）；
+- **文本溢出**：文字超出文本框（随后诱发重叠/出界）；
+- **对齐失准**：应相对对齐的元素位置偏移、间距不均、难看。
+
+### 三层防线（决策：实验融入渲染验证）
+
+```
+① 设计蓝图（模型）: 布局意图 + 预估计算 → 数字预校验
+        ↓ 渲染
+② 渲染/产物回读（机器）: 布局快照 + 空间断言（精确数字审阅）
+        ↓ 截图
+③ 视觉审阅（模型/子代理）: 审美 + 重点区确认（兜底）
+```
+
+- **① 设计阶段**：输出"布局蓝图"——每个元素的**布局意图**（锚点/对齐关系/
+  间距/网格，而非纯绝对坐标）+ 预估 bounds（基于字体度量表的文本面积估算、
+  换行模拟）。**文本区分"框"与"文字实际面积"**：预估文字占位，声明溢出
+  预留。特殊形状（箭头/三角/圆）以真实碰撞体建模（圆=圆碰撞、三角/箭头=
+  多边形 SAT、矩形=AABB），把握不足时标记"待视觉确认"。
+  **实验 = 蓝图的临时渲染验证**（渲染→断言→视觉，通过后蓝图定稿），
+  不另建独立实验页体系。
+- **② 数字审阅（引擎无关，关键修正）**：空间断言**不依赖渲染器**——
+  .pptx 的 XML 坐标就是 PowerPoint/WPS 的权威渲染坐标，重叠/出界/对齐/
+  间距断言可直接从产物几何读取。统一契约：**每引擎适配器实现
+  `layout-snapshot` 提取接口**（元素几何 + 文本 metrics 估算），断言引擎
+  只消费快照，快照带**精度档位**（实测/估算；估算档文本溢出用保守缓冲
+  ×1.1~1.15）。两个首版引擎的快照来源：
+  - PPTD 引擎：PPTD→HTML 渲染器回读（**高精度实测档**——同时是视觉审阅
+    的截图来源与用户预览形态；渲染器失效时自动落回契约档，多重保险）；
+  - python-pptx 引擎：产物 .pptx XML 几何（精确）+ 字体度量估算（估算档）；
+    若探测到 LibreOffice，可选无头渲染（pptx→PDF→PNG）做像素级核实。
+  - 未来引入第三引擎 = 再写一个 snapshot 适配器，断言/审阅系统不变。
+  **多重保险**：实测档（渲染回读）→ 契约档（XML 几何+估算）→ 视觉审阅，
+  任一环节失效不空转（标注精度档位）。
+  输出**冲突报告**：类型、元素对、度量、建议。
+- **③ 重点区审阅**：元素密度聚类自动圈出密集区 → 该区裁剪截图做视觉审阅 +
+  该区涉及元素的数字审阅。
+
+### 修正协议（防"按下葫芦起个瓢"）
+
+- 冲突修复 = **修改布局意图重新求解**（重新生成蓝图 → 渲染 → 断言通过），
+  而不是局部挪动单个坐标；
+- 修改时输出"重新验证计划"：受影响元素及其关联断言；验证必须跑全页，确认
+  无新冲突；
+- 频繁冲突/多次迭代不过 → 回退设计（改蓝图/换版式），不硬调。
+
+### 断言 vs 视觉分工
+
+| 检查项 | 机器断言（可靠） | 视觉审阅（审美） |
+|---|---|---|
+| 重叠/出界/溢出 | ✓ 精确 | ✓ 辅助确认 |
+| 对齐/间距/网格 | ✓ 精确 | ✓ 观感 |
+| 美观/风格协调/图文一致 | — | ✓ |
+| 特殊形状视觉观感 | 近似判定 | ✓ 主判 |
+
+---
+
+## 6.5 整体性：跨页一致性（重点；补完/修改任务格外重要）
+
+单页合格 ≠ 整体合格。整体性分两层，两层都可跨引擎：
+
+- **结构层（机器断言）**：全局 `theme`（字体/字号层级/配色/网格/组件样式）
+  为唯一风格源，页面**只允许引用 theme token**，不得出现主题外颜色/字体/
+  字号（允许显式豁免并记录）。断言 = 逐页检查元素样式与 theme token 的
+  符合性；跨页相同概念（标题、页码、页眉页脚、导航）必须同款。
+- **观感层（视觉审阅）**：**整 deck 拼接总览图**（每页缩略拼图）一次审阅
+  （参考 open-kimi-ppt 的 export_images 总览图做法），检查节奏连贯、
+  风格无割裂感、深浅页切换突兀等。
+- **数据连贯（机器断言）**：跨页数字/术语对账（参考 claude-office-skills
+  的 ib-check-deck 的 cross-slide reconciliation）：同一指标在不同页出现
+  必须一致；数字标记**证据状态**（unmapped/candidate/grounded/conflicted/
+  missing，参照 ultimate-ppt-master-skill），防止虚构数据。
+- **"统一 XX 页风格"任务变体**：S2 风格抽取（从目标页/参考页提取 theme
+  特征）→ 应用到指定页 → 结构断言 + 总览图审阅验证，形成
+  "抽取-应用-验证"闭环；补完/修改任务新页默认从旧 deck 的 theme 继承，
+  不重新定调。
+
+---
+
+## 6.6 质量模式（调研借鉴，待确认）
+
+参照 ultimate-ppt-master-skill 的 quick/standard/audit 分级，质量门槛
+可按任务场景调节，与"用户指定暂停点"协同：
+
+| 模式 | 适用 | 门禁 |
+|---|---|---|
+| quick | 草稿/内部讨论/内容验证 | 结构/文件有效性不过才 fail；视觉证据 warning |
+| standard（默认） | 正式汇报/常规产出 | 结构 + 布局断言通过；视觉评审建议 |
+| audit | 董事会/政府/金融合规/外部发布 | 缺预览 PNG/设计报告/空白页风险即 fail |
+
+---
+
+## 6.7 视觉默认与叙事节奏（调研借鉴，待确认）
+
+- **视觉默认值**（默认浅色封面、深色封面仅限用户要求/品牌/图片主视觉等），
+  作为 S2 从零定调时的默认基线，避免极端化（如默认全黑封面）。
+- **叙事节奏模板**：极端薄提示（"做份 PPT"无任何上下文）时的默认页节奏
+  （封面→问题/背景→证据→对比/流程→风险/行动→结尾），内置多套按情境
+  （汇报/方案/教学/路演/学术），S1 大纲优先套用再按内容调整。
+
+---
+
+## 7. 技术路线与引擎（决策：PPTD 中间层 + 首版双引擎）
+
+### 背景：PPTD（PPT-DSL）
+
+PPTD 是基于 YAML 的演示文稿 DSL，OOXML 之上的简化抽象层：保留主题、
+页面布局、元素位置等核心信息，每页自包含；与 .pptx 双向转换。
+参考实现 open-kimi-ppt-skill 为**逆向 Kimi Slides 的非官方产物，已被要求
+下架**（LINUX DO / cocoloop 均有记录；git 仓库暂仍可访问，但不可作为长期
+依赖）。规范文档公开，格式本身可独立实现。
+
+### 中间层选型
+
+- **PPTD 为唯一中间层**（替代早先讨论的自造 deck.json 布局树）：
+  - 元素模型成熟：text/shape/line/image/icon/table/chart，含主题继承链、
+    图表系列、动画；已有公开规范与 checker 概念可参考；
+  - 天然支持四类任务：从头（直接生成）、补完/修改（PPTX→PPTD→改→PPTD→PPTX）、
+    总结（解析文本/图表）；
+  - "内容保真、版式可从新"语义 = PPTX→PPTD→改写→PPTX。
+- 自研工具链（初版实现范围子集，见 §12 待细化）：
+  - `pptd → pptx` 转换器（主引擎）
+  - `pptx → pptd` 导入器（内容层 + 风格层抽取）
+  - `pptd checker`（结构与数值校验，配合 Lint 清单）
+  - `pptd → html` 预览渲染器（视觉审阅闭环 + 布局回读断言用，
+    Edge/Chrome headless 截图）
+  - `pptd serve` 可选：本地浏览器预览/编辑（后期）
+- 合规：**自行实现格式，不依赖、不分发任何 Kimi 逆向产物**；格式兼容
+  采用公开规范子集 + 自研渲染，遇复杂特性明确降级语义。
+
+### 引擎可插拔（决策：首版双引擎）
+
+引擎位解耦，工作流参数 `engine: auto | pptd | python-pptx`（默认 auto，
+按任务类型自动挑）：
+
+| 引擎 | 说明 | 状态 |
+|---|---|---|
+| **pptd 转换器（主）** | 自研：PPTD→PPTX；覆盖全部四类任务 | 首版 |
+| **python-pptx（兜底）** | 多方验证的成熟方案：自研适配器把中间层/内容映射为 python-pptx 脚本（subprocess 调用，**探测到 python 环境才可用**）；作为自研转换器有质量问题时兜底 | 首版 |
+| **pptxgenjs（第二兜底）** | Node 内置（npm 依赖随插件自带）：**无 python 环境时的第二兜底**；对象模型直写，几何已知 | 首版 |
+
+**运行时依赖策略（已拍板：三引擎 + 浏览器降级）**：
+- python 缺失 → python-pptx 引擎自动不可用（明示），pptxgenjs 兜底；
+- headless 浏览器缺失 → 预览/视觉闭环降级：估算档断言 + 产物文件/PNG
+  供用户本地打开；视觉评审自动降级 Lint（见 §3）；
+- 引擎可用性在 `/ppt` 状态查询与 S0 规格中明确向用户展示。
+
+- 每个引擎 = 一个"中间层/内容 → 引擎调用"的适配器 + 一个
+  `layout-snapshot` 实现；适配器数量收敛。
+- 渲染/审阅闭环与引擎无关：预览一律走 `pptd → html` 渲染器 + 截图，
+  不依赖引擎本身的可视化能力（python-pptx 引擎同此，先经中间层渲染预览）。
+
+---
+
+## 8. 视觉系统（决策：从零 + 可选模板）
+
+- 默认 S2 从零设计一套视觉系统；
+- **可选模板库**：风格种子（主题 token + 版式模板）；用户可导入模板作为种子
+  （文件格式与加载方式待细化，§12.4）；
+- 内置成熟设计原则/checklist（版本层级、留白、对比度、信息密度）作为
+  评审标准的一部分，避免纯靠模型审美漂移。
+
+---
+
+## 9. 图表与素材策略（决策：自动生成 + 用户素材可覆盖）
+
+- 默认自动生成图表（中间层 chart 模型 → 转换器出真实图表）；
+- 用户提供的素材（图片/图表/数据）可覆盖自动生成；
+- 首版实现图表**子集**（bar/line/pie/table 等常见类型），其余类型降级
+  为表格/图片或预留标注（待细化，§12.1）。
+
+---
+
+## 10. 工具集草案（无重依赖原则）
+
+| 能力 | 方案 | 依赖 |
+|---|---|---|
+| **material 工具** | 素材需求清单/搜集/manifest 管理/物理规格读取（图像元数据） | 零 |
+| **layout-blueprint 工具** | 布局蓝图（意图 + 预估 bounds + 断言清单）生成与校验 | 零 |
+| **layout-snapshot 适配器**（每引擎一个） | 从引擎产物提取"布局快照"（几何 + 文本 metrics 估算 + 精度档位） | 每引擎各自依赖 |
+| **layout-verify 工具** | 快照断言 + 冲突报告 + 密集区检测（重点审阅区） | 零（依赖快照） |
+| 中间层工具链 | 自研 pptd checker / 导入 / 导出（DSL 解析 + XML 生成） | npm 包（zip/xml） |
+| 导出引擎 A（主） | 自研 PPTD→PPTX | 同上 |
+| 导出引擎 B（兜底） | python-pptx 适配器 | python 环境（探测） |
+| 渲染预览 | PPTD→HTML + Edge/Chrome headless 截图 | 零（系统自带） |
+| 视觉评审 | 复用被探测到的读图通道（vision-toolkit 等） | 零 |
+| 页面状态/门禁 | 中间层项目内的 page 状态 + 校验脚本 | 零 |
+| 并行量产 | 复用标准预设 tool-workflow / subagent | 零（已有） |
+
+---
+
+## 11. 质量保障
+
+- **双轨验证**：结构 Lint（渲染回读断言：重叠/出界/溢出/对齐/间距）+
+  视觉评审（有视觉能力时）；重点区单独审阅。
+- **门禁**：产物 + schema 校验 + QA 报告；页面状态
+  `draft → rendered → reviewed → approved`；S4 不过不出货。
+- **明示透明**：交付说明标注"未经视觉审阅项"、素材来源（含版权标注）、
+  修改指引、降级重建的页面清单。
+
+---
+
+## 12. 生态调研结论（持续补充）
+
+| 项目 | 性质 | 借鉴点 |
+|---|---|---|
+| [pipitmk](https://github.com/quzichun785-byte/pipitmk)（MIT） | 自研 Deck DSL + python-pptx 编译器 + 校验器 + 截图目检 | **python-pptx 兜底引擎的参考实现**：校验器先行（error 拒编）、文本溢出/遮挡启发式、LibreOffice→PDF→PNG 目检、原生图表 vs 矢量拼绘双轨、Font Awesome 矢量图标（不依赖查看端字体）、customFonts 自动安装、每页自包含哲学；v1 明确不做"编辑已有 pptx"——正是我们的差异化 |
+| [ultimate-ppt-master-skill](https://github.com/kdnsna/ultimate-ppt-master-skill) | 工作流策略化 skill（contracts 生成政策） | 路由政策 + 最多 3 个聚焦问题、quality modes（quick/standard/audit）、证据状态（grounded 需 claim 级源绑定）、视觉默认值、薄提示页节奏、preserve-edit 引擎概念、可追踪链 |
+| [claude-office-skills](https://github.com/fivetaku/claude-office-skills)（Anthropic 官方 skills 重建） | Office 域 skill 包 | deck-refresh（已有 deck 数据刷新）、ib-check-deck（数字一致性/叙事对齐/格式 QC + 跨页数字对账 extract_numbers.py） |
+| open-kimi-ppt-skill（已下架，参考） | 逆向 Kimi Slides | PPTD 格式规范公开、视觉质检总览图做法、主题/动画模型概念；仅作格式参考，不作依赖 |
+
+## 13. 待细化清单
+
+1. **路由细节**：触发词清单、误触发/漏触发处理、退出 PPT 工作流的边界条件。
+2. **PPTD 首版子集**：元素/图表/动画的实现范围界定；不支持特性的降级语义。
+3. **pptx 导入器细则**：内容层/风格层的抽取规则；降级重建的判定标准。
+4. **模板库格式**：可选模板（风格种子）文件结构与加载方式。
+5. **python-pptx 适配器**：调用形态（subprocess 脚本）、内容映射规则、
+   与中间层的对应关系。
+6. **Lint 规则集与阈值**：重叠容差、出界容差、溢出判定、对齐误差（≤1px）、
+   间距/网格符合性等具体数值；文本面积估算的字体度量表建设。
+7. **碰撞几何库**：AABB/圆/多边形（SAT）实现的选取（自写 vs 小库）。
+8. **评审 prompt 标准**：视觉评审子代理任务书模板（含审核 checklist）。
+9. **异常路径**：无视觉时各阶段降级剧本、渲染失败、转换失败、python 缺失回退。
+10. **pptx 对齐/保真方案**：字体度量近似、网格换算、导出差异控制。
+11. **素材搜索质量**：互联网素材的筛选/版权标注规范（首版靠 web 工具时的边界）。
+12. **质量模式**：quick/standard/audit 三档是否采用及各自门禁细则。
+13. **证据状态**：数据/事实的证据状态机（unmapped→grounded 等）应用范围。
+14. **图标/字体资产**：内置矢量图标库选择（Font Awesome 免费版等）、
+    customFonts 自动下载安装的落地。
+15. **图表双轨**：原生图表（可改数据）与矢量拼绘（不可改数据）的覆盖划分与降级。
+
+---
+
+## 14. 关键决策记录
+
+| 决策点 | 结论 |
+|---|---|
+| 插件形态 | agent preset（copy standard）+ 路由工作流行 + 工具集 |
+| 任务形态 | 封闭四类（从头/补完/修改/总结）+ 回退通用 |
+| 已有 PPT 格式 | .pptx 为主 + 降级重建 |
+| 还原保真度 | 内容保真、版式可从新 |
+| 模型读图 | 与标准模式同款（探测 + 适配，不绑定通道） |
+| 审阅门禁 | 有视觉必审；无视觉结构 Lint 兜底并明示 |
+| 素材来源 | 首版三源（用户提供/内容提取/自生成）+ 搜索靠标准模式现有工具；优先级可配 |
+| 素材理解 | 物理层程序化 + 语义层（视觉/用户描述，写入 manifest） |
+| 冲突防治 | 三层防线：设计蓝图（意图+预估）→ 渲染回读（机器断言）→ 视觉审阅；实验融入渲染验证 |
+| 数字审阅 | **引擎无关**：每引擎 `layout-snapshot` 适配器（几何+文本估算+精度档位）；pptx XML 坐标即权威，断言不依赖渲染器 |
+| 修正协议 | 修改布局意图重新求解；验证跑全页；频败回退设计 |
+| 整体性 | 结构层（theme token 符合性断言）+ 观感层（总览图视觉审阅）+ 数据连贯（跨页数字对账/证据状态） |
+| 技术路线 | **PPTD（YAML DSL）为唯一中间层，自研工具链**（open-kimi-ppt-skill 已下架，不作依赖） |
+| 引擎 | 首版双引擎：自研 PPTD→PPTX（主）+ python-pptx（兜底） |
+| 交付物 | 中间层项目 + .pptx（可编辑）；总结任务可产出报告文件 |
+| 量产形态 | 主 agent 调度 + 并行量产 |
+| 门禁机制 | 产物 + 校验文件（非完整状态机插件） |
+| 交互确认点 | S0 规格 / S2 样例页 / S5 交付前预览；暂停点用户可事先指定 |
+| 设计系统 | 从零 + 可选模板 |
+| 图表策略 | 自动生成 + 用户素材可覆盖；首版实现常见类型子集 |
+| 质量模式 | 三级 quick/standard/audit（audit 含硬门禁：预览图/设计报告/空白页风险） |
+| pipitmk 借力 | 参考其思路（校验器/编译/目检/图表双轨/矢量图标），按自研契约重写 |
+| 数据对账 | 首版纳入基础版：跨页数字/术语对账 + 证据状态（unmapped→grounded） |
+| 协作模式 | 参数化五维光谱（确认深度/审阅频率/忠实度/遵从度/未决处置）；**情境自适应默认 + 一次轻量确认 + 会话内记忆**；问卷分层按档位选问；hardConstraints 任何档位都严格遵循 |
+| 路由控制 | **双通道**：语义（明确意图才进、明确无关才退、弱信号不切）+ 斜杠命令（`/ppt` 命令面全量子命令首版，命令>语义，命令写入 hardConstraints） |
+| 愿景/复杂场景 | 长 deck + 多源整合 + 严谨内容；向审计门禁/证据链/整体一致性倾斜 |
+| 运行时依赖 | 三引擎：自研 PPTD（主）+ python-pptx（有 python 则启用）+ pptxgenjs（无 python 第二兜底）；浏览器缺失→估算档+文件预览 |
+| 分发形态 | 官方 bundle 装配（不依赖注入器）+ 开源发布（GitHub Release + npm） |
+| 预览形态 | dsh 网页 UI 内嵌预览（client 插件渲染 + 总览图，对话内确认） |
+| PPTD 格式 | 独立自定义（参考公开规范理念，字段/语义自洽优先；不绑定 Kimi 逆向生态） |
+| 生态协同 | 与现有 paper2ppt/PaperSpine 等独立共存，各管一段；不改造不耦合 |
+| 验收评测 | 评测集（四类任务+复杂场景样例含陷阱）+ 自动断言评分 + 人工评分 |
+| 总结产出 | markdown 默认 + docx/pdf 可选导出 |
+| 语言字体 | 中英混排度量表（CJK+Latin）；采纳 customFonts 自动下载用户级安装 |