dsh-ppt-studio 1.1.0

package/skills/ppt-studio-copy/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: ppt-studio-copy
+description: PPT 工作室的中文文案手册——标题写成结论、要点写成证据、去 AI 味（套话/排比/破折号揭示/三段式/虚词堆叠）、中英混排与术语处理、讲稿怎么写。要写或改页面文案、用户说"太 AI 了/像机器写的/再自然点/去掉套话"时加载。
+whenToUse: 为页面写标题、要点、注释或讲稿；用户反馈文案"太 AI/太官方/不像人话"；或需要压缩页面文字量。
+---
+
+# PPT 工作室 · 文案手册
+
+> **优先级**：用户指令 > 本手册经验值 > 工具默认。用户明确给了语气、字数或既有定稿 → 一律照用户的。
+> **范围**：只谈"怎么写人话"。**不定义字数下限/上限等门禁数值**——页面放不放得下由 `ppt_verify` 的溢出判定说了算。
+> **互操作**：技能目录里若有 humanizer / 去 AI 味类技能，**优先用那一本**，本手册作为兜底与"页面文案专用"的补充。
+> **标签约定**：`经验值（可覆盖）`＝参考，可被内容或用户要求推翻；不带标签的祈使句才是要遵守的做法。
+
+## 1. 先判断要不要动笔
+
+```
+你要做的是？
+├─ 写新页面文案 → §3 定型，再按 §4–§6 过一遍
+├─ 用户说"太 AI 了" → §4 成组信号逐条比对，只改命中的（别整页重写）
+├─ 只是页面放不下 → 先砍信息（§3），不要先缩字号
+├─ 讲稿（写进页面 `notes:` → 导出成 pptx 备注页，见 §7）→ §7
+└─ 用户给了明确语气或已有定稿文案 → 照用户的；不要"顺手润色"已定稿
+```
+
+## 2. 铁边界：只改文风，不动事实
+
+改写**不得**新增、删除或修改任何数字、来源、时间、人名、机构、术语。
+需要新增证据时，回去问数据来源，不要为了句子顺而编一个。
+
+```
+✗ 原文「试点 6 组，闭环率 94%」 → 改写后「多家试点团队闭环率超过 90%」   （把精确事实改成了模糊表述）
+✓ 原文「试点 6 组，闭环率 94%」 → 改写后「6 组试点，闭环率 94%」          （保留全部事实）
+```
+
+## 3. 页面文案的三种角色（写法各不相同）
+
+| 位置 | 任务 | 写法 |
+|---|---|---|
+| 标题 | 说出结论 | 主谓完整、可读、带数字或判断；不用名词堆 |
+| 要点 | 给证据碎片 | 数字/事实/对比；一条一个点；不写形容词 |
+| 注释 | 交代口径与条件 | 来源、范围、单位、假设；不发表感想 |
+
+**解释与推理进讲稿**（§7）。页面文字是"结论 + 证据"，不是"文章"。
+
+**给既有稿补文案时**：先读该册已定页的称呼、术语、数字写法与语气，沿用同册习惯；
+不要在一个已经定稿的册子里引入另一套风格（一致性优先于你更喜欢的写法）。
+
+## 4. 成组信号清单（**同一段里成组出现才改**，单个词不算）
+
+改写判据是"信号**成组**出现"：单独一个「此外」不用动，一段里同时有夸张意义 + 三段式 + 破折号揭示，就必须改。
+（**"成组"的口径 = 同一段里命中下表的 ≥2 类信号**；上面那串例子列了 3 类，不是说 2 类不算。）
+
+| # | 信号 | 诊断 | 改法 |
+|---|---|---|---|
+| 1 | 作为/标志着/见证了/是…的体现/里程碑 | 给事实加了仪式感 | 直接写事实与幅度 |
+| 2 | 突出/彰显/确保/赋能/助力（-ing 式收尾） | 用动词代替结论 | 写"改了什么、结果如何" |
+| 3 | 充满活力/坐落于/令人瞩目/业界领先 | 宣传腔 | 换成可核验的描述或删掉 |
+| 4 | 行业报告显示/专家认为/普遍认为 | 模糊归因 | 说出具体来源与样本，或删 |
+| 5 | 「挑战与展望」「机遇与挑战」式小节 | 公式化收尾 | 写具体的未解问题与下一步动作 |
+| 6 | 此外/与此同时/值得注意的是/深入探讨/格局 | 填充与膨胀 | 大部分可直接删；连接词不超过必要 |
+| 7 | 作为/代表/充当/拥有…（回避"是/有"） | 系动词回避 | 用「是」「有」 |
+| 8 | 不仅…更是…／不是…而是…／既不…也不… | 否定式排比 | 拆成两句，直陈事实 |
+| 9 | 三项并列凑成一组（尤其三词同构） | 凑数三段式 | 删到真实项数；两项就写两项 |
+| 10 | 从…到…（并非真的范围） | 虚假范围 | 写明确的两端或改为举例 |
+| 11 | 同一意思换词重复（提升/优化/改善轮着用） | 同义词循环 | 一个概念固定一个词 |
+| 12 | ——（破折号揭示）、粗体标签+emoji 装饰 | 修辞代替结构 | 用分句与层级代替标点花活 |
+
+## 5. 结构级信号（比用词更容易被识破）
+
+- **通用积极结尾**：「未来可期」「持续向好」「迈上新台阶」→ 换成下一步动作与负责人/时间。
+- **三段式套路**（背景—问题—方案—优势—规划—总结 每份都长一样）→ 按内容真实结构排页（页序判据见 `ppt-studio-craft` §3）。
+- **空转的过渡段**：「让我们来看一下…」→ 页面不需要过渡句，直接给内容。
+- **形容词密度 > 事实密度**：一句里形容词超过两个（经验值（可覆盖）），通常该删。
+
+## 6. 节奏六问（改完通读一遍）
+
+1. 连续三句都是同样长度？→ 打散长短。
+2. 是否用一句"金句"收尾？→ 换成具体动作或数字。
+3. 破折号是不是用来制造"揭示感"？→ 改成两个短句。
+4. 有没有比喻被解释了？→ 删掉解释，或删掉比喻。
+5. 段首是否都是「此外/然而/因此」？→ 删连接词，让内容自己衔接。
+6. 是否凑了三项？→ 删到真实项数。
+
+## 7. 讲稿怎么写（写进 `notes:`，会随导出成为 pptx 备注页）
+
+**交付通道（2026-09-14 起）**：页面写 `notes: "…"`（多行用 YAML 块标量 `notes: |`），`ppt_export` 会给这些页生成**标准备注页**
+（notesSlide + notesMaster，PowerPoint"备注"区可见、可编辑）；**没有 `notes:` 的页不生成任何备注部件**（这类工程产物与旧版逐字节一致）。
+配套：`ppt_import` 会把原稿备注读回 `notes:`；`ppt_splice` 替换某页时**保留源文件该页既有的备注关系**（deck 里新写的 notes 不会塞进被替换的源页）。
+
+页面放"结论 + 证据"，讲稿放"推理 + 过渡 + 被砍掉的细节"。
+讲稿用口语短句，允许不完整句；一页讲稿对应页面上的一条论证线，不重复页面文字。
+
+**结构化写法**（四段，缺哪段就补哪段）：
+
+1. **本页目的**：这一页要听众得到什么（一句话）。
+2. **讲述要点**：3–5 条（经验值（可覆盖））**提词卡式**短句——写"讲什么"，不写逐字稿（逐字稿会让人念稿）。
+3. **转场**：为什么下一页紧接出现（一句因果，不是"接下来我们看…"）。
+4. **现场提示**：停顿点、要互动的问题、翻页时机、万一被追问的备用说法。
+
+**两个容易混的东西要分开写**：讲述计划时长（你打算讲多久）与自动翻页秒数（放映设置）不是一回事——
+**后者不在本插件范围**（DSL 里没有翻页/计时字段），需要时由用户在 PowerPoint 里自己设。
+**讲稿按页挂**（写在该页的 `notes:` 里，随页走）——不要按页码另存一份清单：中间插页或重排后，按页码挂的讲稿会串页。
+
+## 8. 中英混排与术语
+
+- 术语全册统一（同一概念别一半中文一半英文）；产品名/缩写按用户给的写法保留，不要自行翻译。
+- 中英之间加空格与否，跟随该册已有页面；不要同一册两种写法。
+- 数字与单位之间、百分号前的空格同样跟随既有页面。
+
+## 9. 五组 before → after（可直接对照学习）
+
+| # | 改前 | 改后 |
+|---|---|---|
+| 1 | 本次更新作为团队创新的有力证明，不仅优化了性能，更重塑了协作格局。 | 导出从 40 秒降到 6 秒，并加入批量替换。 |
+| 2 | 方案坐落于行业前沿，拥有丰富的应用场景与令人印象深刻的扩展能力。 | 支持 3 种输入格式，单次约 1 万页；更多格式下一版。 |
+| 3 | 这不仅仅是模板替换，而是对演示逻辑的重新思考——确保每页高效传达。 | 换了模板，并按「问题→证据→结论」重排页面。 |
+| 4 | 专家认为该方法在复杂场景下具有关键作用。 | 我们在 12 组真实稿上试跑，9 组一次通过门禁。 |
+| 5 | 尽管面临诸多挑战，项目仍持续蓬勃发展，未来可期。 | 还有两处几何门禁未清零，计划本周修完。 |
+
+## 10. 交付前自检（每条都能"数出来"或"对照原文"）
+
+| # | 检查 | 怎么核对 |
+|---|---|---|
+| 1 | 标题能读出结论 | 只读标题抄成一行；读不出来的标题数 = 0（改不出来 → `ppt-studio-craft` §4） |
+| 2 | 事实零改动 | **逐句回读**：把改后文字与原句并排看——数字、单位、时间、来源、限定条件（"多数""试点")有没有为了顺口被改掉 |
+| 3 | 成组信号已清 | 按 §4 的 12 类逐段扫：同一段里命中 ≥2 类的段落数 = 0 |
+| 4 | 结构级信号已清 | 通读一遍回答 §6 的六个问题，任何一问命中就回去改 |
+| 5 | 页面/讲稿分工 | 页面上还有解释性长句（本该进讲稿）= 0；文字溢出以 `ppt_verify` 输出为准，不靠猜 |
+| 6 | 全册一致 | 术语、中英空格、数字格式：抽查首尾各两页对比，不一致 = 0 |
+| 7 | 讲稿四段齐、且写在对的地方 | 每页讲稿：目的/要点/转场/现场提示四段都在；**写在页面 `notes:` 里**（导出即成 pptx 备注页，导入可读回、可编辑），不要另存"按页码"的清单 |
+
+> 第 2、7 条是"红线"——改文风绝不动事实；这两条不过不交付。
+
+## 11. 什么时候不要用本手册
+
+- 版式与页序问题（那是 `ppt-studio-craft`）。
+- 图表/数据呈现（`ppt-studio-data`）。
+- 用户已定稿或明确语气要求 → 照用户的，不做"顺手润色"。
+- 技能目录里有 humanizer 类技能且任务就是整体去 AI 味 → 用那一本，本手册只处理页面结构相关部分。

package/skills/ppt-studio-craft/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ppt-studio-craft
+description: PPT 工作室的叙事与版式手册——怎么把一个题材排成有主张的页序、每页一个论点、标题写成结论、按内容量选构图、避免"每页都是三张卡片"的模板感。要定纲/定版式、或用户说"这页怎么排/太挤/太像模板了"时加载。
+whenToUse: 正在定大纲、排页序、定版式；用户反馈"排版不好看/太模板/重点不突出"；或需要判断某页该用哪种构图。
+---
+
+# PPT 工作室 · 叙事与版式手册
+
+> **优先级**：用户指令 > 本手册经验值 > 工具默认。本手册给的是启发式与反例，**不定义任何门禁数值**；
+> 门禁以 `ppt_verify` 输出为准，字段语法以 `ppt_schema` 为准（别凭记忆写字段）。
+> 与工作流铁律冲突时以铁律为准；与用户风格要求冲突时以用户为准。
+> **标签约定**：`经验值（可覆盖）`＝参考，可被内容或用户要求推翻；不带标签的祈使句才是本手册要你遵守的做法。
+> 工具自己能报的错（字段非法/溢出/重叠）不在本手册复述——直接看 `ppt_verify`/`ppt_check` 的输出。
+
+## 0. 一句话原则
+
+**一页一个论点，标题就是那个论点。** 读者只看标题也能读出你的推理链，正文只是证据。
+如果删掉某页不影响结论，那页就该删或合并。
+
+## 1. 先判断你在做哪种活（决定顺序）
+
+```
+任务类型？
+├─ 从头做 → 先定叙事（§2）→ 再定页序（§3）→ 再选构图（§5）→ 最后落坐标
+├─ 补完（已有部分页）→ 先读已定页的 claim 序列，缺口在哪补哪；不要重排已定稿的页
+├─ 只改某几页 → 只动那几页；版式沿用同册既有规则（一致性 > 你更喜欢的另一种排法）
+└─ 总结/提炼（把长内容压成几页）→ 先砍事实（留支撑结论的），再排页；别把"删减"做成"缩小字号"
+```
+
+不确定就少改：**改动范围越小，用户越容易接受**。
+
+**确认面：这些事不要替用户决定**（提问节奏仍按工作流铁律——S0 一次问全、`pause-after` 控制暂停点；快速模式按最小确认原则）：
+
+- 主题/受众/场合在材料里**没有**，且会影响后面所有页 → 问一次（把要问的一次问完，不要连环追问）。
+- 模板 vs 从零、"沿用同册风格 vs 换一套" → 给两三个候选让用户挑，不要自己拍。
+- 改动范围模糊（"美化一下"到底动几页）→ 先复述你理解的边界，再动手。
+- 唯一例外：用户明确说"你决定 / 随便 / 快点"——那就按默认基线做，并在交付说明里写清你替他定了什么。
+- **只认已提交的确认**：你在提问后没有得到答复（用户沉默、换了话题、只丢来一个文件）都不构成确认——要么再问一次，要么按最保守的假设往下做并标注"待确认"。
+
+## 2. 叙事 spine：七个问题定骨架
+
+依次回答（答不出就先问用户一句，别猜）：
+
+1. 听众是谁、他们已经知道什么？
+2. 一句话结论是什么（若只能留一张纸，写什么）？
+3. 支撑它的若干理由是什么（经验值（可覆盖）：2–4 个）？
+4. 每个理由的证据是什么（数字/案例/引文）？
+5. 听众可能怎么反驳？哪一页先挡掉？
+6. 需要他们做什么（决策/批准/行动）？
+7. 哪些内容**必须**放进讲稿而不是页面？
+
+把答案写成"结论 → 理由 → 证据 → 行动"的页序，再考虑美观。顺序错了，排版救不回来。
+
+## 3. 页序：让标题连起来像一段话
+
+排完页后，只读标题，看是否是一段连贯的论证：
+
+```
+✗ 背景 / 现状 / 问题 / 方案 / 优势 / 规划 / 总结        （名词堆，读者不知道你要说什么）
+✓ 交付周期从 32 天压到 19 天 / 卡点在两处人工交接 / 我们改了三件事 / 试点 6 组的结果 / 下一步：全线推广
+```
+
+经验值（可覆盖）：封面 + 目录（可选）+ 正文 + 结论/行动。**目录页只在页数多、结构复杂时才值得占一页**。
+
+## 4. 标题与正文的写法
+
+**页标题 = 结论**（其余文案的写法见 `ppt-studio-copy`：要点=证据碎片、注释=口径与条件、解释进讲稿）。
+
+正文里的长句在语义断点显式换行（`\n`）——**断行位置是你可控的排版手段**（验证器用自己的排版估算，
+按字号 × 行高与容器宽度断行，你写的 `\n` 会被尊重）。
+
+**标题放不下时的决策顺序（只适用于标题）**：**改短标题 > 降到下一档字号档 > 拆成两页 > 压缩正文**——不要靠"标题缩到和正文一样大"硬塞
+（中文方块字的视觉面积比同字号西文大，同样字数更占宽，标题尤其容易挤掉正文）。
+标题能"降一档"是因为主题通常有 2–3 级标题档；**正文字号不适用这个顺序**——正文放不下时按 §6 的"删内容 > 拆页 > 调容器 > 最后才动字号"。
+
+## 5. 按"内容量"选构图（而不是按模板库存）
+
+**反向判据（先于选型）**：**先看清内容是什么形状，再挑构图**——内容形状对不上就换一种呈现方式，
+**不要把内容塞进一个现成的构图里**（典型的坏例子：内容只有并列的概念，却画成有刻度的条形图——那是编数据）。
+
+```
+这页的核心是什么？
+├─ 一个结论 + 一句支撑 → 「一句话页」：大字号 + 大量留白（最有力，也最常被忽略）
+├─ 2–4 个并列项，每项一两行 → 卡片/四宫格（经验值（可覆盖）：超过 4 项先合并，或改表格）
+├─ 两个对象的逐项对比 → 左右对比，逐行对齐（对齐是说服力的一部分）
+├─ 有先后/因果的若干步（经验值（可覆盖）：3–6 步）→ 流程/时间线，一条主轴 + 节点
+├─ 数据 → 图表页（选型与标签补齐见 `ppt-studio-data`，别只搬一个 chart 元素上去）
+├─ 多维/多列文本 → 表格（不要硬塞进卡片）
+├─ 多个单元其实属于**同一件事** → 「一块大面 + 分区」：用一个大面（色块/图/边框）把几个区划开，而不是每个单元发一张卡
+└─ 分节过渡 → 章节页：一句话 + 页码进度即可，别放内容
+```
+
+**页面可用的表达手法**（挑着用，别每页同一种）：开场句（kicker）/ 引语 / 主数字（hero number）/ 结论条 / 口径脚注（**仅按需**，见 `ppt-studio-data` §3：读者不需要知道口径就不写）/
+分栏正文 / 单栏大段 / 全出血图 / 图文并置 / 时间轴 / 对比表。
+
+**视觉角色分配**（先定"眼睛的第一落点"）：经验值（可覆盖）——一页 1 个主视觉（hero：面积最大、对比最强的那块）
++ 若干支撑块 + 少量最小标注（需要时才写：来源、单位、页码）。**标注不是每页必备项**：没有要交代的口径就不放，别把"来源/依据/脱敏声明"做成逐页横条。
+
+**构图签名（把"该不该换排法"从感觉变成动作）**：每页动笔前写一行签名——`页任务 → 构图手法 → 轮廓/边界语言`
+（例："三个卖点并列 → 三栏等分 → 直角卡片 + 细描边"）。做下一页前跟上一页对一眼：
+**页任务不同、签名却相同 → 换一种手法**；**页任务相同 → 沿用同一套**（一致不是重复，成套的并列页本来就该长得一样）。
+
+**节奏靠密度与构图，不靠改底色**：全册的底色/主色/字体是**主题的一部分**——统一才是常态（也才过得了 `theme-conformance`），
+不要为了"有变化"中途换基调。真正的节奏手段是：重页与轻页交替（信息量）、章节页做呼吸（模板通常自带分区页）、
+同一页内的主次对比。**深/浅切换只在一件事上成立**：模板或用户本来就设计了分区（例如封面/章节/结尾用深底），
+那就沿用它的规则，而不是自己发明第二条。
+
+**图文混排按"图片的角色"分派**（先定角色，再定版式）：
+
+- **证据类图**（截图 / 界面 / 代码 / 图表截图）：保真优先——关键信息不能裁掉、不能压暗、不能缩小到读不出；旁边留给它足够的宽度。
+- **照片类**：统一比例与高度（一页多图时不要一张 contain 一张 cover）；裁切位置自己定，主体不能切到；图注与来源写在图外。
+- **装饰类/背景图**：允许出血与压暗，但**文字压图前先确认图上有一块足够干净的区域**能放下这段文字（判据是"文字要落的那块地方细节多不多"，不是一个面积比例）；
+  没有就换图或改成"图在一侧、文字独占一栏"——不要整页蒙一层半透明遮罩来硬压。
+- 任何情况下：`text` 压 `image` 属于需要声明的重叠，且**说不清意图就该分开**（见铁律 2 的声明制）。
+
+## 6. 版式卫生（不需要审美天赋，只需要守规矩）
+
+- **对齐有锚**：所有块的左边界、基线、间距从同一套栅格来（主题里的安全区与栅格就是锚）。肉眼"差不多"的对齐，在真渲染里会露馅。
+- **先定焦点，再定对称与否**：一页要有一个主视觉（面积/对比最强）。**对等的两个对象 → 对分**（对称才是它们的正确形式）；
+  **不对等就别硬凑成均分**（主视觉占大头、注解靠边）。模板或用户本来就是对称版式时跟随它——别为了"设计感"把对称拆成单边。
+- **解读不得比证据更响**：结论条/注解的字号、颜色强度，不要盖过它要解释的数据本身。
+- **留白是设计**：一页塞满说明你不会删。优先删内容，其次拆页——但**页数由用户指令决定**：页数已经定了就靠"删内容 / 换构图 / 分栏"腾地方，不要靠加页解决。
+- **字号是层级工具，不是塞字的工具**：用主题 `textStyles` 的阶梯建立"标题 → 要点 → 注释"三层对比；
+  内容放不下时的决策顺序是 **删内容 > 拆页 > 调容器 > 最后才动字号**（页数被用户定死时跳过"拆页"这一档），且字号下限由用户指令决定（见 §8）。
+- **图片先问"看清了吗"**：插入图片要保证主体可辨（裁切别切到关键信息），尺寸与页面栅格对齐；
+  图片与文字并置时，让文字区域独立成块（不要压在图上——`text` 压 `image` 属于需要声明的重叠，说不清意图就该分开）。
+- **跨页一致**：页眉、页脚、页码、章节标记全册一致；颜色语义固定（同一个含义永远同一个颜色）。
+- **安全区**：模板的页眉/页脚带由 `theme.safeArea`（或页面级 `safeArea`）定义，落在带上的元素会被判出界。
+  有意放在带上的 logo/角标/水印，**逐个元素手工**写进 `expectedOutOfSafeArea`（不批量、id 必须存在、必须确认有意）；
+  超出**页面**边界永远不可声明，只能改布局。拿不准就把元素移进安全区（先读 theme 里的 safeArea 值再定位）。
+
+## 7. 三种"像模板生成"的典型症状与改法
+
+| 症状 | 改法 |
+|---|---|
+| 每页都是"三张卡片 + 图标" | 按内容量重选构图（§5）；把其中一页做成"一句话页"做节奏变化 |
+| 每页都满、都同等密度 | 交替重页/轻页；把次要证据移到讲稿与附录 |
+| 标题都是名词短语 | 全部改成结论句（§4）；改不动说明这页没有论点，考虑删或合 |
+
+## 8. 数值纪律（这一节请逐字遵守）
+
+- 页面尺寸、页数、字号下限：**一律以用户指令为准**；用户没给就按工具的当前默认走——
+  **字号下限：插件没有默认下限**（不设 `theme.minFontSize` 就不强制；导出 auto-fit 只做防荒谬保底，见 `ppt_verify`/`ppt_export` 输出）、
+  页面尺寸取项目 `size`、**标准模式**页数不设配额（快速模式的页数参考由工作流提示段给出，不在本手册里写死数值）。
+- **密度不是你能设的**：`density`/`hotspot` 是插件里固定的**建议级**阈值（出的是 `[~]` 警告、不入门禁），没有可配置项——
+  它只提示"这页东西太多了"。"页数/字号下限/尺寸"这类**规范性的**值才以用户指令为准。
+- 不要在本手册之外自造数字规则（历史上把某次任务的具体要求固化成默认，出过事故）。
+- 任何"经验值"都写成"经验值（可覆盖）"，并且当用户给了风格要求时**立刻让位**。
+- 不确定某个值是否合规：`ppt_verify` 的输出就是答案，不要靠猜。
+
+## 9. 交付前自检（每条都能"数出来"或"对照工具输出"，不靠感觉）
+
+| # | 检查 | 怎么核对 |
+|---|---|---|
+| 1 | 标题能连成论证链 | 把各页标题单独抄成一行读一遍：读不出结论 → 回去改标题（§4） |
+| 2 | 没有"名词标题" | 数一遍：标题里带数字或判断句的比例，明显偏少就是问题 |
+| 3 | 构图不重复（按任务判） | 数各页的构图签名（§5）：**页任务不同而签名相同**的对数 = 0；页任务相同则**应当**相同 |
+| 4 | 密度有节奏，底色统一 | 逐页看信息量：连续多页都是"满页"→ 把其中一页拆轻；同时确认**底色/主色/字体全册一致**（中途换基调 = 颜色出板，strict 档下 `theme-conformance` 直接判 `[✗]`） |
+| 5 | 图文关系已判角色 | 逐页确认：证据类图未被裁/未被压；装饰类图上的文字有干净区 |
+| 6 | 页眉/页脚/页码/字体/颜色语义 | 全册一致（抽查首尾各两页对比）——**这几项工具基本不管**：`theme-conformance` 只管"颜色是否出自 theme.colors"、`aesthetic-*` 只逐页提建议，**跨页一致性没有断言**，只能自己对；别指望工具替你发现页脚页码漂了 |
+| 7 | 门禁与审阅 | `ppt_verify` 的错误 `[✗]` 计数 = 0；含 table/chart/image/custGeom 的页做过真渲染抽检（**有 Office/可读图时**；否则退化为结构自检并在交付说明标注"未经视觉审阅"，不要谎报已看） |
+| 8 | 出问题改在"拥有它的那一层" | 单页问题改那一页；页序/母版问题改大纲或模板；工具报错先查输入（数据/字段/媒体）——**不要在输出上打补丁**（导出后手改 pptx、绕过声明都算打补丁） |
+
+> 第 1–6 条是自查项（自己数）；第 7 条以工具输出为准，**不过不交付**（没有 Office/读图能力时走第 7 条括号里的降级路径，并在交付说明标注"未经视觉审阅"）；第 8 条是"改在哪一层"的纪律，不是交付闸门。
+
+## 10. 什么时候不要用本手册
+
+- 具体字段、声明、安全区语法 → `ppt_schema`（权威且随版本更新）。
+- 图表/数字怎么呈现 → `ppt-studio-data`。
+- 文案措辞与"去 AI 味" → `ppt-studio-copy`。
+- 用户已经有明确版式要求 → 照做；本手册只在"未指定"时给参考。

package/skills/ppt-studio-data/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: ppt-studio-data
+description: PPT 工作室的图与数据手册——图表选型、成品里图表为什么没有标签、怎么补才不触发内容互压、口径与数据来源标注、跨页数字一致、结论句写法。页面要放图表/数字/对比时加载；用户问"这个数据怎么呈现/图表怎么读不出来"时加载。
+whenToUse: 正在给页面安排图表、表格、关键数字；或用户反馈"图表看不出数值/数据对不上/这个饼图不合适"。纯文字页不需要本手册。
+---
+
+# PPT 工作室 · 图与数据手册
+
+> **优先级**：用户指令 > 本手册经验值 > 工具默认。本手册只给启发式与反例，**不定义任何门禁数值**；
+> 门禁以 `ppt_verify` 的实际输出为准，语法细节以 `ppt_schema` 为准（不要凭记忆写字段）。
+> 本手册与工作流铁律冲突时，以铁律为准。
+> **标签约定**：`经验值（可覆盖）`＝参考，可被内容或用户要求推翻；不带标签的祈使句才是要遵守的做法。
+> 工具自己能报的错（字段非法/数值全零/溢出）不在本手册复述。
+
+## 0. 先分清"这张图是证据还是装饰"
+
+**先判断用途，再决定要不要标签**——这一步比标签本身重要：
+
+| 用途 | 要不要标签 | 怎么做 |
+|---|---|---|
+| **图表承载数据结论**（读者要读出值/趋势/对比） | 要 | 分类名、数值、单位、一句结论句缺一不可（§2 给两种补法） |
+| **图表作装饰 / 示意 / 版式衬底**（不承载结论） | **不必** | 让它纯几何即可；**别让它假装承载数据**（要么标注"示意"，要么干脆用形状） |
+| 介于两者之间 | 按"读者是否需要读出值"判 | 拿不准就至少给单位与一句"读图结论"——结论句写在**图外**（§2 路径 A），不是往图里塞标签 |
+
+**成品层（交付物）**：导出的 .pptx 里 `chart` 元素**只画几何**——柱/折线/饼形，
+**没有**分类名、数值、单位、坐标轴、图例（实测：导出包里没有任何 chart 部件，slide XML 里只有你自己写的 text 元素）。
+
+**预览层（`ppt_render` 的 HTML）也不是"什么都画"**：bar/line 会画分类名（**超过 8 字截断**）+ 5 条网格线与**数值刻度**（那个 y 轴是按最大值归一化的，不代表真实量纲）；
+**pie 不画分类名，却照样画那套 y 轴刻度**（对饼图毫无意义）；**每个数据点的具体值只在悬停提示里**。
+所以"预览里看着能懂"对饼图根本不成立，对 bar/line 也仅是分类名与相对刻度可读。
+
+→ **预览是定版参考，交付物是 pptx**：只按预览确认"图表能看懂"，交付出去可能就是一张没有标注的图形。
+
+→ **承载数据的图表** = 图表元素（几何）+ 你自己补的文本（分类名/数值/单位/图例/结论）。
+→ **装饰性图表** 可以不带标签，但交付说明里加一句"该图仅作示意"（本手册的补充建议，不在铁律 7 的必含项里），并且不要用它去支撑页面结论。
+
+## 1. 选型：先问"读者要读到什么"
+
+**前置红线（先于选型）**：**手上没有可比数据时，不要用图表或任何带刻度的数值视觉**。
+概念列举画成条形、没有基数的百分比画成柱、随手写个"约 60%"——这些是**门禁测不出来的失真**（`ppt_verify` 管几何，不管真假）。
+没有数就老老实实写文字或用并列卡片；需要数就先去要数据。
+
+**数据拥有图形（不许反向）**：图上的每一个量化标记（柱长/折线点/扇区角度/色阶）都必须来自**权威值 + 一个显式的比例换算**：
+不许目测摆位置、不许为了画面好看改数据、**非零基线的坐标轴必须在图上写明**（否则读者会按面积误读倍数）。
+
+```
+读者要读到…
+├─ 一个数的大小/趋势 → 图表（bar 比大小 / line 看趋势）
+├─ 精确到个位的具体值 → 表格（table）或大字数字 + 一行注释
+├─ 两三个数 → 不要图表：大字数字块（shape 衬底 + text）最有力
+├─ 占比 → pie 只在类别很少时才读得出（经验值（可覆盖）：约 4~5 类以内）；类别多 → 横向条或表格
+├─ 多维/多列文本型数据 → 表格；不要硬塞进图表
+└─ 只是"意思一下"的装饰 → 不要用图表假装有数据（`chartIssue` 只拦"空数据/全零"，编造的非零值**没有任何工具会拦**——要么标注"示意"，要么干脆用形状）
+```
+
+经验值（可覆盖）：一张图只表达一个结论；同一页不要放两张互相抢注意力的图；
+饼图类别越少越好（多了人眼比不出角度）；柱形从 0 起，折线可以不从 0 起但要在注释里说明。
+
+**图表配色与主题**：`chart.colors` 不写 → 用**内置调色板**（它**不在 `theme.colors` 里**，`ppt_verify` 不会报，但成品会带主题外颜色）；
+要与主题一致就显式写 `colors: ["$primary", "$accent"]`（`$ref` 在**预览与成品两层**都会被解析成 hex）。
+**显式**写了不在 `theme.colors` 里的颜色 → 会出一条 `[·] aesthetic-theme` 建议（**建议级，不是门禁**）——逐条斟酌，别当成错误去清。
+
+## 2. 补齐标签的路径（含门禁语义）
+
+`role` 推断是固定规则：**text / table / chart 都算 content**，shape / image 算 background，line 单独一类。
+所以"文本压在图表上"= **content×content = 永远错误、不可声明**：
+
+- ✗ `[✗] content-collision｜元素 "label" 与 "chart" 重叠（交叠 N×Mpx）—— 内容互压（文字/表格/图表相互遮挡），不可声明豁免，请调整布局`（真实报告的措辞，N×M 是实测交叠尺寸）
+
+**先按图的角色选路径（这一步决定你能用哪条）**：
+
+- **图承载结论**（读者要从它读出值）→ **只有 A 一条路**：标签移出图框。这种情况不存在"合法的压上去"。
+- **图是衬底 / 纯装饰**（不承载结论、页面结论不依赖它）→ 可以用 B 或 C，把"这张图就是底"写成显式声明。
+
+| 做法 | 怎么写 | 代价 |
+|---|---|---|
+| **A. 标签放图表框外**（默认，永远可用） | 图表 bounds 缩小，分类名/数值/图例排在图框上/下/左/右的空白区 | 需要预留空间（图表别占满整页） |
+| **B. 图当衬底**（仅衬底类图） | 给 chart 加 `role: background`，再把这组重叠写进该页 `expectedOverlaps` | 声明的是"这张图是承载文字的底"——语义变了，且**文字压在图形上仍然难读**，声明不会替你解决可读性 |
+| **C. 图纯装饰**（仅纯装饰图） | 给 chart 加 `role: decoration`，**完全退出重叠报告**（不用写声明） | `decoration` 的语义是"此元素不承载信息"；只豁免**重叠**，不豁免超页面/超安全区/文本溢出 |
+
+**`role` 不是消错开关**：把承载数据的图标成 `background`/`decoration` 去让 `content-collision` 消失，
+是"在输出上打补丁"（craft §9 第 8 条明令禁止）——报错在告诉你文字和图互相盖住了，不是在告诉你改个字段。
+判据只有一句：**这张图到底承不承载结论**。承载 → A；不承载 → 才轮到 B/C，而且这是设计决定，不是消错手段。
+`role: decoration` 还可能掩盖别的读者问题（图看不懂、图与结论无关），所以用它之前先确认"这张图本来就不需要被看懂"。
+
+## 3. 口径三件套：值、单位、基准
+
+任何数字页，读者必须能回答三个问题：**这个数是多少 / 单位是什么 / 跟什么比**。
+
+- 单位与量级写在标题或就近的标注里（"销售额（万元）"），不要只放在页脚。
+- 对比要有基准：同比/环比/目标值/同业——没有基准的百分比等于没信息。
+- 精度按决策需要给：金额到万就不必到元；比率一位小数通常足够。
+- 图表页把依据写进页面 `source:`（制度/报告/口径）。**它是一个 YAML 字段，不进成品**——导出的 pptx 上看不到它，它是给复核的人留的作者自述。
+- **不要在页面上逐页挂"来源/依据/脱敏声明"横条。** 该不该在版面上写来源，判据是**读者是否需要知道口径**：
+  引用了外部数据、口径有歧义、一页并列多个口径 → 在该页留一行小字（风格全册统一，别每页长不一样）；
+  自己编的演示数据、一目了然的通用数字 → 不写。模板母版里也不预置这类占位块（2026-09-18 起）。
+- 交付前的数据核查走 `ppt_crosscheck`：它生成**审阅材料包**（全页正文 + 工作区实扫素材清单 + 审阅协议），**工具本身不做任何判定、不构成门禁**——
+  判定（一致 / 冲突 / 无来源支撑 / 无法核实）由审阅者按协议给出，默认用独立子代理（**用户明确禁止子代理时改自审并标注**）。
+  **没有外部素材时只能判"无法核实"**，不得报绿；也**不要求"全册每页都标 `source:`"**（封面/章节/纯文字页本来就没有数据来源可标）。
+
+## 4. 跨页数字必须同口径
+
+同一个指标在多页出现时，值、单位、时间范围、口径必须一致（`ppt_crosscheck` 的材料包按阅读顺序列出全部页面正文，审阅时逐项对照；**要抓的是"同指标不同值"，不是"数字相同"**——数字必须放回整句语境才有含义）。
+常见事故：第 3 页写"增速 12%"，第 9 页同一指标写"13%"——读者只会记住"这人不严谨"。
+改口径就改全部出现处，或在页面上显式说明两个口径的差别。
+
+## 5. 表格（最容易被低估的可读路径）
+
+`table` 的字段是**元素级**的（不要写到 `chart:` 里）：
+
+```yaml
+- elementId: tbl
+  elementType: table
+  bounds: [60, 420, 840, 120]
+  cols: ["指标", "本期", "同比"]
+  rows: [["任务闭环率", "94%", "+33pt"], ["按时交付率", "91%", "+19pt"]]
+  header: true
+```
+
+经验值（可覆盖）：列在 5 列、行在 7 行左右开始难读；表格不是"信息仓库"，一页表格只服务一个结论；
+超过可视面积就拆页，不要靠缩字号硬塞。**2026-09-18 起表格有了自己的溢出断言**：`[✗] table-overflow`
+（按列宽换行估算内容高 vs 表格高，与正文同一保守度量）——处置是**扩大表格高度 / 加宽列 / 精简单元格文案**。
+但 **`ppt_verify` 仍不检查图表的溢出**（溢出断言只覆盖 `text` 与 `table`；`density` 只是元素计数的 `[~]` 警告）：
+图表放不放得下仍需靠 `ppt_render`/真渲染目检。
+注意：table 只有 `cols / rows / header` 三个字段（**没有逐列对齐字段**，以 `ppt_schema` 为准）——
+要靠列宽、表头写单位、把关键值拆成大字数字块来建立层级，而不是指望"右对齐"。
+
+## 6. 结论句：图表必须有人替它说话
+
+每个数据页写一句"读图结论"，放在图旁（不是图里），句式：
+**主语 + 变化 + 幅度 + 含义**，例如"任务闭环率从 61% 抬到 94%——流程改造的收益主要落在执行环节"。
+
+- 结论句里出现数字时，必须与图上/表上的数字**逐字一致**。
+- 不写"显著提升/大幅改善"这种没有量级的形容（那等于没结论）。
+- 图上有异常值就解释它，不能假装没看见。
+
+**放进页面的图，不要自带"页面零件"**：用来配图/示意的图片（含导入素材、生成的示意图）不该自带页眉、页脚、页码、标题栏、角标、署名或装饰边框——
+那些是 deck（主题/母版）的职责。自带 chrome 的图一旦入 .pptx 就是**不可拆的重复元素**，而且门禁不会报错，只能靠你在选图时看一眼。
+
+## 7. 常见坑（逐条对应工具输出）
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| 导出报告提示图表数据解析为全零或无效 | `chartIssue` 命中：检查 `chart.data.cols/rows` 映射；单列 pairs 兼容但**建议宽表** `cols: [分类, 值]` + `rows: [[类, 值], …]` |
+| 多系列只画出一条 | 宽表只给 `cols` 时按第一组取值；多系列要显式写 `series:` 映射——`series: [{name: "本期", x: "分类列名", y: "数值列名"}]`（`ppt_schema` 只有一句提示、没有样例，形状见 `svgCharts.js` 的 `chartData`） |
+| 预览能看懂、成品看不懂 | 若这张图是**承载结论**的（§0 判据），就是标签没补；若它只是装饰/示意，属于正常，交付说明里注明即可 |
+| 图表页报 `content-collision` | 先判图的角色（§2）：**承载结论 → 只能 A**（标签移出图框）；**纯衬底/纯装饰 → B/C**（改 `role` 是设计决定，不是消错开关）。这是"改布局"还是"改声明"的分叉，不是措辞问题 |
+| 数据页报**未声明重叠**（非 content-collision） | 属于声明制范畴：确认是有意叠层 → 补 `expectedOverlaps`；说不清意图 → 改布局 |
+| 数据页出现 `density`（`[~]` 警告）或 `aesthetic-text`（`[·]` 建议） | 都不是门禁；但一页塞两组数据 + 三条结论确实读不动，拆页更好 |
+
+> 分级术语对齐门禁输出：`[✗]` 错误必须清零、`[~]` 警告需处置/声明、`[·]` 建议斟酌采纳（`[⚠]` 只出现在 M2 实测交叉段，不是主清单标记）。
+
+## 8. 交付前自检（每条都能"数出来"或"对照工具输出"）
+
+| # | 检查 | 怎么核对 |
+|---|---|---|
+| 1 | 图表用途已逐页判定 | 每张图能说清是"证据"还是"装饰"（§0）；证据类 → 分类名/数值/单位/结论句**四件齐**，装饰类 → 交付说明加一句"仅作示意"且页面结论不依赖它；改过 `role` 的图要能答"这张图本来就不需要被看懂吗" |
+| 2 | 数字有来源、无编造 | 页面上每个数字都能指回材料或用户；重要数字页在 `source:` 写清依据（YAML 字段，不进成品，**不是页面上的横条**）；有外部素材时用 `ppt_crosscheck` 材料包逐条核"能否在其中找到依据"——找不到才是问题，没有素材只能标"无法核实" |
+| 3 | 跨页同口径 | 用 `ppt_crosscheck` 材料包按阅读顺序通读，逐项核对同一指标在多页的值/单位/时间范围一致（**重点抓"同指标不同值"**） |
+| 4 | 图形没有骗人 | 逐图检查：柱形从 0 起；折线非 0 基线已注明；没有按面积比较却没标基线的图 |
+| 5 | 配图无自带 chrome | 逐图看：没有图内页眉/页脚/页码/角标/边框 |
+| 6 | 门禁与真渲染 | `ppt_verify` 的 `[✗]` 计数 = 0；含 chart 的页用 `ppt_visual` 真渲染复核过（**没有 Office/读图能力时**退化为结构自检 + 导出 parity，并在交付说明标注"未经视觉审阅"，不要谎报已看） |
+| 7 | 交付说明 | 写明：哪些图仅作示意、数据口径与假设、未标注来源的项 |
+
+> 第 1–5 条自己数；第 6 条以工具输出为准，**不过不交付**。
+
+## 9. 什么时候不要用本手册
+
+- 纯文字/纯版式页（去 `ppt-studio-craft`）。
+- 文案本身的措辞与"去 AI 味"（去 `ppt-studio-copy`）。
+- 字段语法、声明写法、安全区配置：不要查手册，直接 `ppt_schema` / `ppt_check`（权威、随版本更新）。
+- 给既有稿**补一页或补一组标签**时：先读该册已定页的口径与标注习惯（单位写法、`source:` 写法、图表配色），
+  沿用同册规则，不要引入你自己更喜欢的另一套。

package/skills/ppt-studio-manual/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: ppt-studio-manual
+description: PPT 工作室（dsh-ppt-studio）答疑手册——**只在用户提问时加载**：用户问"这个插件怎么用/XX 怎么写/为什么报错/怎么只改一页/有没有单页版"时，在这里找条款回答。**制作任务进行中不要加载本手册**（正在做 PPT 而只是自己不确定写法时，`ppt_schema` / `ppt_check` / `ppt_verify` 的输出才是权威）。
+whenToUse: 用户消息里出现用法、语法、报错、最佳实践一类的**提问**（或用户说"报错了/不生效/怎么用"需要定位原因）时加载。反之——正在定纲、写页面、审阅、导出，只是自己拿不准某个 DSL 写法或工具语义时，**不要加载**，改调 `ppt_schema`（DSL 速查）/ `ppt_check` / `ppt_verify`。
+---
+
+# PPT 工作室 · 提问式手册
+
+> **本手册只服务"用户提问"**：用户问怎么用 / 怎么写 / 为什么报错时读它。
+> **制作任务进行中不要读它**——正在做 PPT 而只是自己不确定写法时，直接调
+> `ppt_schema`（DSL 权威速查）/ `ppt_check` / `ppt_verify`，它们的输出比本手册更准（本手册可能落后于源码）。
+>
+> 本手册是对应 README 的"问答版"。回答用户问题前先在这里找到对应条款；
+> 拿不准细节（字段枚举、报错措辞）时，让用户/调用 `ppt_schema` 或 `ppt_check` 获得权威输出。
+
+## 1. 一句话定位
+
+DSH 上做 PPT 的工作区：说需求 → 四类任务工作流 → 「数字门禁 + 视觉审阅 + 真渲染复核」三轨保证质量 → 交付可编辑 .pptx + 中间层工程。核心不变量：**元素区块冲突（重叠/出界/溢出）必须被机器防住；设计意图用声明制表达。**
+
+**同级还有三本制作手册**（同样按需加载，都不改门禁与铁律）：`ppt-studio-craft`（叙事与版式：页序、结论式标题、按内容量选构图）、`ppt-studio-data`（图表与数据：选型、成品标签补齐、口径与来源）、`ppt-studio-copy`（中文文案：标题/要点写法、成组 AI 味信号、before→after）。本手册管"这个插件怎么用"，那三本管"怎么做好"。
+
+## 2. 用户常见问题速查
+
+| 用户问 | 答 |
+|---|---|
+| "先帮我做个 PPT" | 问一句主题+页数即可（工作流自动进入；"帮我做一个 5 页的产品介绍 PPT"这类带修饰语的说法也认得）；建议先 `ppt_new` 立骨架（**用户没提模板时按题材自己定风格，不要默认套内置模板**） |
+| "工作流怎么没自动进入 / 手册哪儿来的" | 进入靠语义判据（名词+任务动词邻近共现；只提一句 PPT 不激活），也可 `/ppt on` 强制；本手册由插件**内嵌注册**（跟着插件走，PPT 会话内即时生效）。**默认不镜像到 `<dshHome>/skills/`**（2026-09-18 起：那是跨预设可见的文件系统技能根，会让别的预设也看到这 4 本）——要让非 PPT 会话也能查阅，安装时显式加 `--mirror-skills`。确认通道：调 `ppt_state` 看 `manualSkill.visible` |
+| "你想看模板吗" | `ppt_templates` 展示。参考优先级：**用户给的模板/既有 ppt（只参考它，内置不参与）> 用户明确要求时的内置模板 > 按题材自己设计风格（默认路径）**；内置模板只有明显贴合题材时才参考 |
+| "我自己的模板想加进库 / 想删掉某个模板" | 入库：`ppt_template_add pptx=<绝对路径>`（写用户层 `<dshHome>/ppt-studio/templates`，**升级不丢**）；删除：`ppt_template_remove id=<id>`（**只能删自建的**，随包拒删）。`ppt_templates` 分"你的 / 随包的"两段列出。用户自攒的模板视同"用户给的模板"，优先级最高 |
+| "怎么装/怎么升级这个插件" | **一键（推荐）**：`dsh plugin --profile web add <Releases 页面上的资产 URL>`（profile 级，装完即挂载，**不需要 npm 账号**；装完重启 dsh web）。**升级必须换更新的 URL，但不需要先卸载**——资产名 = `版本-构建时间-构建戳`（页面保留历次构建，取**时间最新**那条），同一 URL 覆盖内容后包管理器不会重取（实测）。备选：`node scripts/install.mjs` + 预设行（会话级，带"PPT 工作室"预设）。**别同时用**：会挂两次（插件有防重、不会崩，但按纪律二选一）。排查：`dsh plugin --profile web list` → `dsh --profile web --dump-config` 找 `ppt-studio` 行 → 重启 |
+| "怎么只改原稿第 15 页" | `ppt_import` 读真身 → 改工作区页（verify 清零）→ `ppt_splice`（替换进源，其余页 SHA256 逐字节不变）→ 可选 `ppt_slice` 单页版 → `ppt_visual pages="15"` 抽查 |
+| "为什么报重叠错误，我明明想要这样" | design-intent 声明制：把有意重叠对加入该页 `expectedOverlaps`（流式 `[{pair: [a,b]}]` 或块式 `- pair: [a,b]`，每对一行），重验即 ✓；说不清意图的对子改布局；**内容互压（文字×文字）永远不能声明** |
+| "样式没生效" | 样式键必须在 `content` 内部（元素级 fontSize/color/bold/... 无效，`ppt_check` 现在会直接报错） |
+| "字号可以 11pt 吗" | **可以**（下限 = 用户指令）：用户给了下限（如"不得小于14号"）→ 写入 theme.minFontSize 并严格遵守；用户没给 → 不设任何强制下限（插件无默认）。 |
+| "为什么导出会缩字" | verify 已报溢出 → 先清零（扩容器/精简文案/显式 `\n`）；verify 通过 ⇒ 导出不缩字 |
+| "预览链接 404" | 路由在 PPT 工作室会话挂载时注册——确认当前是 PPT 工作室会话（不是默认会话） |
+| "图表能画什么" | bar/line/pie（矢量拼绘）；python-pptx 兜底引擎降级表格；复杂图表用图片或 Shape 拼 |
+| "用别人的模板做" | `ppt_import`（带参考层：source.pptx + 真渲染整页 + 全量色板）→ 先 read_image 看 `reference/previews/*.png` 真身再动手 |
+| "要 100% 像模板" | `ppt_patch`（手术模式：只换文字/表格内容，XML 原样） |
+| "网页预览对，打开 pptx 线条不对" | 旧引擎三个连线编码 bug（四个症状：斜线镜像 / × 少一笔 / 箭头消失 / 水平线变斜），**均已修复**——看 `ppt_export` 报告的"线方向 N/N"自证；修复前导出的产物重新 `ppt_export` |
+| "表格在 PowerPoint 里空白" | 旧引擎 graphicFrame 结构 bug，**已修复**；parity 回读（表 N/N）自证；旧产物重导 |
+| "`ppt_crosscheck` 是干嘛的 / 它替我查数字吗" | 它**不判断**：生成「审阅材料包」（全页正文按阅读顺序 + 工作区实扫素材清单 + 审阅协议），判定由**审阅者**给（默认独立子代理；**用户明确禁止子代理时改自审并标注**），四分类为一致 / 冲突 / 无来源支撑 / 无法核实。旧版"跨页数字分组 + grounded/unmapped"已于 **2026-09-18 废除**——数字必须放回整句语境才有含义，`source:` 是作者自述而非机器核实的证据 |
+
+## 3. DSL 快速参考（写页面时对照）
+
+- 工程：`deck.yaml` + `pages/*.yaml` + `media/`；1px=1pt，原点左上；默认 960×540。
+- `theme`：`colors {name: hex}`、`textStyles {name: {fontSize,color,bold,fontFamily,align,lineHeight,wrap}}`、`safeArea`、`minFontSize`（用户给出字号下限时设置；缺省无强制下限）、`themeConformance: strict|suggest|off`。
+- 元素通用：`elementId`（页内唯一）、`elementType: text|shape|line|image|table|chart`、`bounds: [x,y,w,h]`（line 可省，由 points 推导）、`role: background|content|decoration`。
+- text：`content: {text, style: "$name" 或内联样式键}`；**样式键必须在 content 内**。
+- shape：`kind: rect|roundRect|ellipse|triangle + prst(箭头/菱形/五边形/flowchart…) + custGeom path`；`fill #hex | {color,alpha} | {type: gradient, stops: [{pos,color,alpha}], angle}`；`line {color,width}`；`rotation`。
+- line：`points: [[x1,y1],[x2,y2]]`（**每条只有两点**，多点折线不支持——时间轴/折线拆成首尾相接的多条 line）；`arrow: true`（箭头在第二个点那一端）。
+- image：`src: "media/xx.png"`；`fit: cover|contain|fill`。
+- table：`cols: [列名...]`、`rows: [[..]]`、`header: true|false`。
+- chart：`chart: {type: bar|line|pie, data: {cols: [列名…], rows: [[…]]}, series: [{name,x,y}]（多系列时显式写）, colors}`。
+  **`data` 只认 `cols` + `rows` 两件**（写成 `data: [{label, value}]` 会被 schema 直接拒绝）；单列 pairs 兼容（`cols: [分类]` + `rows: [[类, 值]]` 自动补"值"列），**推荐宽表** `cols: [分类, 值]`。
+  chart 里**没有**分类名/数值/单位/图例字段——那些要自己用 `text` 元素补（见 `ppt-studio-data` §2）。
+- 页面级：`pageType`、`background`、`safeArea`（页面级覆盖主题）、`notes`（讲稿文本 → **导出为 pptx 备注页**；多行用 `notes: |` 块标量；没有 `notes` 的页不产生任何备注部件）。
+- 声明：`expectedOverlaps: [{pair: [a,b]}]`；出界：`expectedOutOfSafeArea: [idA]`；对比度豁免：`contrastExempt: [id]`；`source: "依据标注"`（作者自述出处，供审阅者核对；**不进成品**，不是机器核实的证据）；`overlapMode: declared|lenient`。
+
+## 4. 质量门禁（答复"为什么还要改"的依据）
+
+- ERROR 必须清零：`unexpected-overlap`（未声明重叠：修布局或补声明）、`content-collision`（文字/表格/图表互压，永远不可声明）、`out-of-page`（超**页面边界**：放映不可见，永远不可声明，必须改布局）、`out-of-safe-area`（超**安全区**但仍在页面内：可声明——有意落在模板页眉页脚带上的 logo/角标加入 `expectedOutOfSafeArea` 即可；与 out-of-page **是两个码**，因为处置完全不同）、`text-overflow`（扩容器/精简文案；缩字下限按用户指令，未给则 max(6pt, 60% 原字号) 保底防荒谬）、`table-overflow`（表格单元格文字按列宽换行后超出表格高度：**扩大表格高度 / 加宽列 / 精简单元格文案**——表格的杠杆是行列尺寸，不是文本框）、`theme-conformance`（strict 档默认开：元素颜色必须 ∈ `theme.colors` 或中性灰）、`measured-overflow`（M2 实测交叉：实测=终审，估算漏报也会报错）、`measured-unpaired`（M2 两档页号对不上：多为旧版 `measured.json` 或测量后又增删了页面——**重新跑一次 `ppt_measure` 即可**；契约破坏会报错而不是静默跳过）。
+- 声明命中显示为 ✓ 预期重叠/✓ 预期出界（确认，不算错误）。
+- 报告里的标记：`[✗]` 错误（进 `门禁：N 个错误` 计数）、`[~]` 警告（进页头"N 警告"，不入门禁）、`[·]` 建议（美学层）。`[⚠]` 不是主清单的警告标记——它只出现在 M2 实测交叉段和其它提示行。
+- `[·]` 建议（美学/对比度/孤字/长句/网格/贴边）**永不是门禁**，但逐条斟酌；`density`/`hotspot`/`near-align` 是 `[~]` 警告（同样不入门禁计数，但先看它们）。
+- 三层审阅节奏：`ppt_verify`（数）→ `ppt_shot`+读图（视）→ `ppt_visual`（Office 真，有条件时）；audit 档禁 autoDeclare、导出自动回读断言 + 自动真渲染。
+- 一键声明：`ppt_verify autoDeclare=true`——只处理警告级；写入后必须附"声明清单 + 每对一句意图"（说不清意图的对子改布局）。
+
+## 5. 交付路径（按场景）
+
+| 场景 | 路径 |
+|---|---|
+| 从头做 | 模板/定调 → 逐页 → export（缺省 pptd）→ 交付说明 |
+| 快速交付 | `/ppt quick`：≤8 页（用户指定除外）、文本 ≤40 字/块（用户要求可放宽）、跳视觉审阅（交付标注"未经视觉审阅"） |
+| 改整个原稿 | import 全稿 → 逐页改 → export（注意：近似稿整册重渲会伤其余页——若非全部重做，用下一行） |
+| 只改原稿某页 | import → 改该页 → `ppt_splice`（只替换这页进源）→ 可选 `ppt_slice` |
+| 贴模板 | `ppt_patch`（模板为底版，文本/表格槽替换） |
+| 加页 | 复制母版去 `_` + 注册 deck.pages，或新写页 |
+| 总结 | import 全稿 → 提炼重排 → export |
+
+交付说明必须含：素材来源、未经视觉审阅项（如有）、修改指引；有具体数字/事实主张的稿子，交付前用 `ppt_crosscheck` 生成**审阅材料包**并按协议做一次内容审阅（**默认独立子代理；用户禁止子代理时改自审并标注**），把逐条判定写进交付说明。
+
+## 6. 常见报错与解法
+
+| 报错 | 解法 |
+|---|---|
+| `Unexpected seq-item-ind token` | YAML 一行写了多个 `- {pair: ...}` → 每对一行 |
+| `样式键 ... 写在元素级` | 把 fontSize/color/bold 等移进 `content: {}` |
+| `"x" 不是本页元素 id`（声明/豁免类） | 防呆：声明必须指向真实元素（查 elementId 拼写、该页是否注册） |
+| `YAML 解析失败：...` | 常见笔误：flow 项拆行；缩进层面检查 |
+| `theme-conformance 颜色出板` | 颜色加入 theme.colors（或中性灰）；导入工程的全量色板已内置 |
+| `autoDeclare 被禁` | audit 质量档（C2 决定）：切回 standard，或逐对手工声明 |
+| `pptd 失败 + python-pptx 兜底失败` | 看新报告的 exit code/stderr；多半是环境（python 缺失/媒体占位）——有媒体缺失会提示 |
+| 预览 404 | 进 PPT 工作室会话（路由随会话挂载注册） |
+| Office 渲染"文件或目录损坏" | 产物经 zip 手术时校验 rels/Content_Types（splice/slice 已自证）；手工改过 OOXML 时用 `ppt_visual` 验证 |
+
+## 7. 开发维护（仅改插件时用）
+
+- 改码：`src/` → `node scripts/build.mjs` → **重启 host**（插件经 agent preset 会话装配；`dev_reload_package` 只覆盖注入器装配包，且注入器 junction 已存在时会指向旧安装根）。
+- 回归：`node scripts/smoke.mjs`（262 断言）→ `node scripts/preflight-1.0.mjs`（发布预检）→ `node scripts/regression-real.mjs`。
+- 跨层验证纪律：**预览层与成品层必须互相验证**——`ppt_render`+`ppt_verify` 只管 HTML/估算层，OOXML 层靠 `ppt_export` 的 parity 自证（表/图/线方向）+ `ppt_visual` 真渲染抽检；只跑单层会漏掉"预览对、成品错"（2026-09-14 连线方向事故）。
+- 文档链：改需求/决策 → docs/01；改机制 → docs/02；每次 → docs/03；验收 → docs/04；发布前 → docs/06。
+- 装配：**标准装法是 profile bundle 行**（`dsh plugin --profile <p> add <Releases 资产 URL>`，profile 级、随 profile 启动装配）；preset 插件行只用于"离线 junction / 不想动 profile"场景，且与前者**互斥**（`scripts/install.mjs` 按环境二选一，检测到 bundle 安装会主动删掉 preset 行——手工删行会被下次同步装回来，所以互斥逻辑在安装器里）。排查：`dsh plugin --profile web list` → `dsh --profile web --dump-config` 找 `ppt-studio` 行 → 重启 `dsh web`。
+- 宿主升级（DSH 换版本）：本手册 §开发维护 与 docs/05「宿主升级纪律」——契约逐项 Inspect 核对 + headless 覆盖层真进程验证，别只看单测。