feat: 内置技能全量收录 presentation-forge (#83)

## 概述将 PPT 工作流技能 **presentation-forge**（原 codex-ppt-skill）以 **builtin 内置技能**形态全量收录进 DesireCore 官方市场。 > 注：本 PR 最初以 entry.json pointer 形态提交，现按仓库负责人意见改为 builtin 层全量 vendoring。分支保留两个提交（pointer → builtin 转换）。 ## 形态：builtin 全量 vendoring（遵循 guizang-ppt 先例） - 全量内容进 `skills/presentation-forge/`：`SKILL.md` + `SKILL.zh-CN.md` + `references/` + `scripts/` + `styles/`（9 套风格）+ `templates/` + `schemas/`。 - builtin frontmatter：`version/type/risk_level/status/tags` + `metadata.i18n`（zh-CN/en-US）+ `market.icon/category/maintainer`，`category: creative`。 - 列入 `builtin-skills.json`（33 项）。 - 附 `LICENSE`（MIT）+ `NOTICE.md` + `_desirecore/{frontmatter.yaml,upstream.json}` 溯源。 - 溯源 commit：`mashagua/presentation-forge@b7b1a9c`（MIT）。 - 排除非运行内容：`tests/` 夹具、未被任何 vendored 文件引用的 1.3MB 流程图、Codex `agents/` 绑定。 ## 变更 - 新增 `skills/presentation-forge/`（全量内容，约 440KB） - `builtin-skills.json`：新增 `presentation-forge`（32 → 33） - `manifest.json`：`stats.totalSkills` 60 → 61，`version` 1.2.26 → 1.2.27，`lastUpdated` → 2026-08-10 - `README.md`：built-in 32 → 33、external 29 → 28、total 61 不变，两处代码块同步 ## 验证 ``` uv run scripts/i18n/validate-i18n.py OK: no i18n issues found. ``` stats 公式核对：entry.json 目录 28 + SKILL.md 目录 33 = 61 = manifest.totalSkills ✓ --------- Co-authored-by: Yige <a@wyr.me> Co-authored-by: yige <yige@yigedeMacBook-Neo.local>
2026-09-05 20:43:46 +08:00 · 2026-08-23 23:31:26 +08:00
parent 5a0a80d31c
commit 98ffc8fe92
84 changed files with 11125 additions and 5 deletions
--- a/skills/presentation-forge/references/design-quality-workflow.md
+++ b/skills/presentation-forge/references/design-quality-workflow.md
@@ -0,0 +1,36 @@
+# Anti-AI-slop 设计质量门
+
+所有新生成页面在正式构建或全量生图前运行：
+
+```bash
+python scripts/validate_design_quality.py --session <session>
+```
+
+报告固定写入 `reports/design-quality.json`，统一质量门必须读取它。原生可编辑 Deck 构建器会在创建 PowerPoint 对象之前自动运行同一检查。
+
+## 硬错误
+
+- 正文出现设计说明、配图建议、讲者备注或 prompt 文本。
+- 默认启用阴影或渐变；只有带明确设计理由的例外才可进入 spec。
+- 可编辑模式使用覆盖 85% 以上页面的独立图片对象冒充背景或整页设计。
+
+硬错误使报告成为 `FAIL`，禁止继续生产构建。
+
+## 启发式警告
+
+- 同页超过 4 个卡片，存在无意义卡片化风险。
+- 同页超过 5 个圆角矩形。
+- 出现无语义的窄边强调条。
+- 形状上叠加独立文本框，而文字本可写入形状或通过留白分组。
+
+警告使报告成为 `WARN`。先修复；确有设计理由时，在 `native_deck_spec.json.design_exceptions` 记录 `code`、`slide_number` 和非空 `reason`。不要使用全局“全部忽略”。
+
+```json
+{
+  "design_exceptions": [
+    {"code": "shape-with-overlay-textbox", "slide_number": 4, "reason": "该文本需要独立动画与可访问性朗读顺序。"}
+  ]
+}
+```
+
+设计门只判断结构性坏味道，不替代逐页视觉检查。通过检查也不代表页面已经具有良好构图。
--- a/skills/presentation-forge/references/editor-ui-integration.md
+++ b/skills/presentation-forge/references/editor-ui-integration.md
@@ -0,0 +1,196 @@
+# 可视化 PPT 编辑器接入规范
+
+当外部 UI 需要像 Codex 一样展示任务状态、页面预览并允许修改可编辑 PPTX 时使用本规范。Skill 是生成与验证后端；UI 是 adapter。两者只通过 editor manifest、patch 和事件文件交互，不让 UI 直接改 OOXML。
+
+## 稳定 seam
+
+UI 只依赖两个命令：
+
+```bash
+python scripts/editor_bridge.py export --session <session>
+python scripts/editor_bridge.py apply --session <session> --patch <patch.json>
+python scripts/editor_bridge.py approve-export --session <session>
+```
+
+`export` 写入 `reports/editor-manifest.json`。v3 manifest 提供 session revision、文档 hash、画布 hash、页面缩略图、完整 scene element、当前风格和 24 个可选视觉预设。每个 element 自带 `capabilities`；UI 不自行猜测哪些字段可改。
+
+## 画布与 PPTX 同版合同
+
+canvas-first 不是示意界面。画布和最终 PPTX 必须使用同一份完整 scene 集合：
+
+- 用户要求 N 页时，`native_deck_spec.json.slides`、`scenes/`、editor manifest、画布缩略图和最终 PPTX 必须都是 N 页；不得用 4 页静态 Demo 代替。
+- 使用 `editor_bridge.py export` 的 `slides` 动态创建全部缩略图；不得在 HTML 中硬编码页面标题或页数。
+- 点击任一缩略图必须装载该页 `elements`，而不是只切换 active 边框。
+- 导出必须提交所有页面的 `slide_number`、`canvas` 和 `elements`。只提交封面状态视为导出失败。
+- 最终构建只读取当前 `scenes/`。画布已有而基础 archetype 没有的文本、形状与 connector，由构建器原生 materialize；禁止再写一个仅在导出后运行的封面后处理脚本。
+- 质量门前比较 `manifest.slide_count`、scene 文件数和 PPTX 页数；任一不一致即 `BLOCKED`。
+
+生成真实画布：
+
+```bash
+python scripts/editor_bridge.py export --session <session>
+cp assets/editor/render_editor_canvas.py <session>/analysis/render_editor_canvas.py
+python scripts/render_editor_canvas.py \
+  --manifest <session>/reports/editor-manifest.json \
+  --out <session>/reports/editor-canvas.html
+```
+
+对话中展示的是该 `editor-canvas.html`，不要手写固定 4 页的 HTML 示例。
+
+`apply` 接收 `schemas/editor-patch.schema.json` 约定的 patch。桥接脚本负责：
+
+- revision、文档 hash 与画布 hash 冲突检测；
+- 修改前自动 snapshot；
+- 更新原生 Deck spec；
+- 同步 scene 标题和消息；
+- 标记受影响页面缓存为 stale；
+- 写入 `reports/editor-events.jsonl`；
+- 返回新 manifest。
+
+## Canvas-first 工作流
+
+用户明确要求“先在画布编辑，确认后再输出 PPTX”时，建立 session 必须传入：
+
+```bash
+python scripts/init_deck_session.py ... --editor-workflow-mode canvas-first
+```
+
+该模式不是“先生成最终 PPTX 再打开”。正确顺序是：
+
+```text
+建立 slides_plan / native_deck_spec / scene
+-> export manifest
+-> 画布展示 24 个样式预设与逐页 scene
+-> 用户选择整套风格（style_selection_status=confirmed）
+-> 用户逐页编辑文字、位置和对象样式
+-> 预览构建只写 cache/editable/，不得写 final/
+-> 用户点击导出
+-> approve-export
+-> 构建、验证并写入 final/*.pptx
+```
+
+在 `editor_export_approval=approved` 之前，构建器会拒绝把文件写进 session 的 `final/`。UI 可以直接按 scene element 渲染画布，不需要先创建临时 PPTX；需要核对 PowerPoint 排版时，预览 PPTX 只能写到 `cache/editable/preview.pptx`。
+
+画布采用“主画布优先”的可折叠三栏结构：左侧页面缩略图默认窄栏，中间 16:9 可编辑 scene 占据主要可用空间，右侧对象属性与样式面板默认收起。当前页面不得因展示 24 个预设而缩小到文字不可读；页面显示尺寸不得小于约 `746×420` CSS 像素，空间不足时让中间区域滚动。顶部必须提供页面列表、对象编辑和专注画布开关，不显示 Markdown 按钮、标签页或编辑框。点击页面中的文字对象时展开右侧面板，宽度约 `320px`；样式预设在面板内滚动，不能永久挤占主画布，也不能只显示当前深蓝主题。用户没有选定样式时，应显示“待选择”，不能把推荐样式冒充用户选择。Markdown 仅保留为内部内容源和导出回写数据。
+
+首次打开画布前，先从已构建的原生 PPTX 同步 element：
+
+```bash
+python scripts/sync_canvas_scene.py --session <session> --pptx <session>/final/deck.pptx
+```
+
+该 adapter 不启动 PowerPoint。它通过 `python-pptx` 提取原生对象的 ID、位置、尺寸、旋转、图层、文字和基础样式，写入 scene element v2。
+
+## UI 运行循环
+
+```text
+打开 session
+-> export manifest
+-> 显示页面缩略图与可编辑字段
+-> 用户提交 patch
+-> apply patch
+-> build_native_editable_deck.py --scene-dir <session>/scenes --session <session>
+-> 更新 PNG 缩略图
+-> export 新 manifest
+-> 最终一次 PowerPoint 渲染
+```
+
+UI 可以轮询或 tail `reports/editor-events.jsonl` 展示 `planning`、`generating`、`rebuild_required`、`rendering`、`validated` 等状态。未来接入 WebSocket 时，只需写一个读取同一事件和 manifest 的 adapter，不改变 Skill interface。
+
+Markdown-first session 的 manifest 额外提供 `authoring.markdown`、`authoring.markdown_sha256` 和 round-trip capability。UI 必须把完整 Markdown 源显示在可编辑面板中；导出时同时提交完整 Markdown 和完整 scene。浏览器无法直接写本地文件时，由 follow-up 请求交给 Skill 写回并重新编译，不得只保存在页面内存。
+
+## Patch 示例
+
+```json
+{
+  "schema_version": 3,
+  "request_id": "ui-0001",
+  "base_revision": "r0003",
+  "document_sha256": "<manifest 中的值>",
+  "canvas_sha256": "<manifest 中的值>",
+  "operations": [
+    {
+      "op": "update-element",
+      "slide_number": 1,
+      "element_id": "s001_hero",
+      "changes": {
+        "bbox": [180, 220, 720, 190],
+        "text": "新的封面标题",
+        "style": {"font_size_pt": 30, "font_color": "C62828"},
+        "rotation": 0,
+        "z_index": 4
+      }
+    }
+  ]
+}
+```
+
+v3 支持 `replace`、`update-element` 和受保护的 `apply-style`。element 只接受自身 `capabilities` 允许的 `text/geometry/style/rotation/z-order`。禁止通过通用 `replace` 修改页码、archetype、风格、字体策略、视觉资产来源和安全状态。旧 revision、document hash 或 canvas hash 必须返回冲突，不覆盖新版本。
+
+### 风格切换
+
+UI 用三个标签呈现风格能力：`整套风格 / 本页变体 / 对象样式`。前两者使用 `apply-style`，对象样式继续使用 `update-element`。
+
+```json
+{
+  "schema_version": 3,
+  "request_id": "style-0001",
+  "base_revision": "r0003",
+  "document_sha256": "<manifest 中的值>",
+  "canvas_sha256": "<manifest 中的值>",
+  "operations": [{
+    "op": "apply-style",
+    "scope": "deck",
+    "style_id": "executive-minimal",
+    "variant_id": "charcoal-gold",
+    "mode": "preserve-layout"
+  }]
+}
+```
+
+- `scope=deck` 可以切换主风格家族和变体，并同步 typography/table profile。
+- `scope=slide` 只允许选择当前主风格家族内的变体，避免随机混搭。
+- `replace-theme` 清空目标页的手工 canvas override，按新主题完整重建。
+- `preserve-layout` 保留位置、尺寸、文字、旋转和层级，清除旧颜色/字体覆盖后换肤。
+- 风格卡片使用 manifest `style_catalog[].design_tokens` 生成预览；每张卡显示家族、变体名、主背景、主色、辅助色和文字色。
+- 推荐顺序不得等同于自动应用。AI、技术或售前主题可以把企业科技、咨询商务、极简高管列为候选，但必须等待画布选择后才能在 `canvas-first` 模式确认风格。
+
+## Scene element v2
+
+```json
+{
+  "id": "s001_hero",
+  "type": "text",
+  "bbox": [122.4, 194.4, 979.2, 208.8],
+  "rotation": 0,
+  "z_index": 1,
+  "editable": true,
+  "locked": false,
+  "capabilities": ["text", "geometry", "style", "rotation", "z-order"],
+  "role": "hero",
+  "text": "企业 AI 知识库",
+  "style": {"font_size_pt": 34, "font_color": "111827", "bold": true},
+  "source_binding": {"document": "analysis/native_deck_spec.json", "path": "/slides/0/title"}
+}
+```
+
+画布固定使用 `1920 × 1080 px` 逻辑坐标。UI 可以自由缩放显示，但提交 patch 时必须转换回逻辑坐标。文本 element 的 `source_binding` 让画布文字和 Deck spec 同步，避免两个事实源漂移。
+
+## PowerPoint GUI 策略
+
+默认 `gui_validation_mode: final-only`：
+
+- 中间冒烟只展示 PNG；
+- 中间预检不启动 PowerPoint；
+- UI 编辑后只重建页面与缩略图；
+- 最终 artifact 完成后才调用一次 `render_pptx.py --validation-stage final`；
+- `reports/final-render.json` 必须绑定最终 PPTX 和 PowerPoint 生成的 PDF。
+
+`eager` 允许中间真实渲染；`never` 完全禁止 GUI，但统一质量门只能给出带警告的结果。
+
+## v3 边界
+
+- v3 面向 `native-editable-deck`，支持文本对象移动、缩放、旋转、图层、基础字体/颜色样式和风格预设切换。
+- 图片、图表和表格支持几何、旋转和图层；内部数据编辑继续走 Deck spec，不直接拆 OOXML。
+- v3 还不支持组合/取消组合、自由曲线路径编辑、动画时间轴和图片裁剪手柄。
+- 真正的多人协作、评论和实时光标属于 UI/协作 adapter，不写进 PPT 生成 Skill。
--- a/skills/presentation-forge/references/limitations.md
+++ b/skills/presentation-forge/references/limitations.md
@@ -0,0 +1,35 @@
+# 局限性说明
+
+这个 skill 适合把图片型 PPT 工作流产品化，也适合把截图页、整页生图页重建成更可编辑的 PPTX。但它不是像素级还原工具，也不是把任意图片一键变成完全原生 PPT 的工具。
+
+## 整页生图 PPT 的局限性
+
+- 正文、图表和版式都在图片里，交付后的文字不能直接编辑。
+- imagegen 对中文长文本、密集表格、脚注和小字号仍有不稳定性，必须通过减字、放大字号和重抽修正。
+- 真实 Logo、二维码、证书、印章、监管披露等不能交给 imagegen 生成，必须用后处理叠加真实素材。
+- 对数字、标准、来源和事实性陈述没有天然校验能力，需要独立做资料核验。
+- PPTX 只是图片封装，适合讲解和视觉展示，不适合长期维护、频繁改字、财务留档或强模板一致性的材料。
+
+## 可编辑重组的局限性
+
+- 图片到可编辑 PPT 的重建本质是重新搭版，不是自动反编译。复杂页面通常只能做到实用级还原，不能承诺百分百一致。
+- 文本、卡片、线条、箭头、表格框架适合重建为原生 PPT 对象；复杂图标、3D 元素、插画和装饰件通常只能作为独立透明图片资产插入。
+- SVG 导入 PowerPoint 后经常是一个整体图形对象，不等于内部每条路径、每个图标都可稳定编辑。真正高可编辑性要优先用 PPT 原生对象重建。
+- 如果把图标强拆成大量 PPT 形状，在 PowerPoint、LibreOffice、WPS、Keynote 之间容易出现错位、层级丢失、组合失效和字体度量变化。
+- PowerPoint 与 LibreOffice 的字体渲染、自动换行、文本框高度和图标解释存在差异。最终验收应以目标用户实际打开的 PowerPoint 为准。
+- 未安装同名字体时，字号看起来会变大或变小，中文换行尤其容易漂移。建议使用目标环境可用的中文字体，并预留 10%-15% 文本余量。
+- 图表页、指标页和表格页应尽量从结构化数据重建，而不是从截图 OCR 后强行复刻。
+
+## 适合的验收口径
+
+- 对图片型 PPT：验收视觉一致性、文字可读性、Logo 正确性、页数完整性和敏感信息边界。
+- 对可编辑重组：验收文字可编辑、结构可拖拽、核心图标可替换、没有整页原图、没有私有素材泄漏。
+- 对高保真复制：需要明确可接受误差范围，并保留渲染对比、contact sheet、对象统计和已知限制。
+
+## 不应承诺的能力
+
+- 不承诺任意图片一键转成完全可编辑 PPT。
+- 不承诺复杂 SVG 导入后所有子路径都可在 PowerPoint 内稳定编辑。
+- 不承诺跨 PowerPoint、LibreOffice、WPS、Keynote 的完全一致。
+- 不承诺 imagegen 生成的中文、图标和排版一次正确。
+- 不承诺对私有客户材料自动完成公开脱敏，发布前必须人工确认边界。
--- a/skills/presentation-forge/references/markdown-canvas-workflow.md
+++ b/skills/presentation-forge/references/markdown-canvas-workflow.md
@@ -0,0 +1,111 @@
+# Markdown 画布与原生 PPTX 工作流
+
+从主题或文档新建演示时默认使用本规范。只有用户明确要求直接导出、不要画布或跳过预览时，才改用 `slides-plan + direct-build`。
+
+## 单一事实源
+
+`slides.md` 是人工编辑的内容源；`analysis/native_deck_spec.json` 与 `scenes/*.scene.json` 都是派生产物。画布读取 scene，PPTX 构建器也读取同一 scene。禁止让 HTML/CSS 和 PPTX 构建器分别计算布局。
+
+```text
+slides.md
+-> compile_slides_markdown.py
+-> native_deck_spec.json + scenes/
+-> editor manifest + SVG/DOM scene canvas
+-> editor patch 回写 spec、scene 和 slides.md
+-> approve-export
+-> build_native_editable_deck.py --scene-dir
+-> PPTX / PDF
+```
+
+## 初始化
+
+```bash
+python scripts/init_deck_session.py \
+  --title "企业 AI 知识库解决方案" \
+  --delivery-type editable-pptx \
+  --style-id consulting-blue-white \
+  --editor-workflow-mode canvas-first \
+  --authoring-mode markdown-canvas \
+  --out-root ./outputs
+```
+
+初始化会创建 `slides.md`。不要同时手工维护 `slides_plan.md`；编译器会从 `slides.md` 重建逐页计划和 prompts。
+
+## Markdown 语法
+
+- YAML frontmatter：`title`、`style`、`variant`、`ratio`、`fontCN`、`visualAssetPolicy`。
+- 使用单独一行 `---` 分隔页面。
+- 每页第一个 `#` 是页面标题。
+- `>` 是副标题或页面关键信息。
+- `::layout{type="..."}` 选择版式。
+- `##` 与其后的正文构成卡片、步骤、对比区或架构层。
+- 普通 `-` 列表用于行动项或普通内容。
+- Markdown 表格用于 `table` 页面。
+
+支持的布局映射：
+
+| Markdown layout | 原生 archetype |
+|---|---|
+| `cover`、`cover-left` | `cover` |
+| `content`、`cards`、`columns` | `content-structured` |
+| `timeline`、`process` | `process-flow` |
+| `comparison` | `comparison-two-zone` |
+| `data`、`metrics` | `data-callouts` |
+| `table` | `table` |
+| `architecture` | `architecture` |
+| `closing`、`action` | `closing-action` |
+
+不在语法内的任意 CSS、HTML、JavaScript 和浏览器滤镜不得进入生产画布。需要绝对定位时，通过 scene element 的稳定 ID 和 `bbox` 覆盖，不把像素坐标写进正文。
+
+## 编译并打开画布
+
+```bash
+python scripts/compile_slides_markdown.py \
+  --session <session> \
+  --build-preview \
+  --render-canvas
+```
+
+该命令：
+
+1. 解析 `slides.md`；
+2. 写入原生 deck spec、逐页计划、prompts 和完整 scene 集合；
+3. 只在 `cache/editable/preview.pptx` 构建结构预览；
+4. 将预览中的原生对象同步为 scene element；
+5. 导出 editor manifest；
+6. 生成 `reports/editor-canvas.html`。
+
+对话中必须展示生成的 HTML 画布，不得手写静态 4 页示意。用户要求 N 页时，Markdown 页面数、spec、scene、manifest、画布缩略图和最终 PPTX 都必须为 N 页。
+
+画布必须以可读编辑为首要布局目标：默认收起右侧检查器，让当前页面占据主要可用区域；页面不得小于约 `746×420` CSS 像素，空间不足时允许主区域滚动，不能继续缩小到文字不可读。顶部提供页面列表、对象编辑和专注画布按钮；点击页面中的文字对象时，展开约 `320px` 宽的对象属性栏。Markdown 仍作为内部内容源和导出回写数据，但不在画布界面暴露按钮、标签页或编辑框。样式预设不得永久占据主画布空间，应放在可收起检查器中。
+
+## 修改与回写
+
+- 用户直接编辑 `slides.md`：重新运行编译命令。
+- 用户在画布改字或对象样式：使用 `editor_bridge.py apply`；桥接器更新 spec 和 scene，并把受支持内容规范化回写 `slides.md`。
+- 用户拖动对象：只更新 scene `bbox`；Markdown 保留内容和结构，几何覆盖留在 scene。
+- 用户切换风格：同步 frontmatter、spec、scene、metadata 和 prompts。
+
+画布中的 Markdown 面板用于内容修改。浏览器不能直接写本地文件时，导出动作必须把完整 `slides_markdown` 与完整 scene 状态一起提交给 Skill，再由 Skill 落盘、编译和构建。
+
+## 导出
+
+用户点击导出后：
+
+```bash
+python scripts/editor_bridge.py approve-export --session <session>
+python scripts/build_native_editable_deck.py \
+  --spec <session>/analysis/native_deck_spec.json \
+  --scene-dir <session>/scenes \
+  --session <session> \
+  --out-pptx <session>/final/deck.pptx
+```
+
+随后执行字体、排版、可编辑性、最终 PowerPoint 渲染和统一质量门。不得在导出阶段重新选择模板或重新解释布局。
+
+## v1 边界
+
+- Markdown 负责内容、页面结构和组件；自由拖拽几何保存在 scene。
+- 画布可以实时修改已有页面内容；在浏览器中新增或删除整页后，需要重新编译 Markdown。
+- PPTX 与画布共享对象、文字、坐标、样式和层级，但浏览器与 PowerPoint 的字体抗锯齿可能存在轻微像素差异。
+- 复杂 image-2 视觉仍是独立图片对象，其内部不可编辑。
--- a/skills/presentation-forge/references/native-editable-workflow.md
+++ b/skills/presentation-forge/references/native-editable-workflow.md
@@ -0,0 +1,112 @@
+# 原生可编辑 Deck 工作流
+
+从主题、文档或逐页计划新建可编辑 PPTX 时使用本规范。该路线类似 AIPPT 的组件化生成：文字、形状、流程、表格和 Office 图表保持原生可编辑；image-2 负责高价值视觉资产，不生成整页底图。
+
+## 三档视觉资产策略
+
+在 request、`metadata.json` 和 `analysis/native_deck_spec.json` 中使用同一个 `visual_asset_policy`：
+
+| 策略 | 用途 | image-2 规则 |
+|---|---|---|
+| `native-only` | 财务、制度、密集数据、长期维护模板 | 不生成 image-2 资产；页面使用原生对象和用户提供素材 |
+| `native-image-assisted` | 默认；售前、技术方案、项目汇报 | 按页需要生成封面主视觉、插画、3D 元素或复杂装饰 |
+| `image-led-editable` | 强视觉发布、品牌故事、概念表达 | 至少包含一个 image-2 主视觉，但标题、正文、结构和数据仍必须原生可编辑 |
+
+不要把 `native-image-assisted` 理解为每页强制生图。数据页、表格页和普通流程页默认不用 image-2；封面、章节、产品场景和概念页优先评估视觉资产槽。
+
+## 内容与组件合同
+
+按 `outline_review_mode` 处理 `slides_plan.md`：`continuous` 写完即继续，`explicit` 等待用户批准。随后建立 `analysis/native_deck_spec.json`，结构遵循 `schemas/native-editable-deck.schema.json`。支持以下 v1 页面原型：
+
+- `cover`
+- `content-structured`
+- `process-flow`
+- `comparison-two-zone`
+- `data-callouts`
+- `table`
+- `architecture`
+- `closing-action`
+
+最小示例：
+
+```json
+{
+  "schema_version": 1,
+  "title": "企业 AI 知识库解决方案",
+  "style_id": "enterprise-tech-dark",
+  "style_variant": "tech-blue",
+  "typography_profile": "zh-business-present",
+  "table_profile": "presentation-data-table",
+  "visual_asset_policy": "native-image-assisted",
+  "slides": [
+    {
+      "slide_number": 1,
+      "archetype": "cover",
+      "title": "企业 AI 知识库解决方案",
+      "subtitle": "让可信知识进入业务工作流",
+      "visual_slot": {
+        "backend": "image-2",
+        "source_type": "imagegen_asset",
+        "status": "generated",
+        "asset_path": "../assets/generated/cover-hero.png",
+        "prompt_record": "../analysis/image-prompts/cover-hero.md"
+      }
+    }
+  ]
+}
+```
+
+## image-2 资产槽
+
+需要视觉资产时，先把 `visual_slot` 写入 spec，再使用 Codex `imagegen` 技能生成。提示词和结果必须满足：
+
+- 只生成主视觉、插画、3D 元素、装饰或场景图片，不生成整页 PPT。
+- 不在图片中生成标题、正文、真实数字、表格、页码、Logo、二维码或认证标识。
+- 记录 prompt 文件、输出文件、来源类型和生成状态。
+- `backend=image-2` 时，`source_type` 必须是 `imagegen_asset`，状态必须达到 `generated` 或 `validated`。
+- 非封面页如果使用视觉资产，显式填写 `bbox_in`，避免覆盖原生内容。
+- 生成失败时标记 `blocked`；不要用程序绘图、原图裁片或占位图冒充 image-2 正式资产。
+
+## 构建与验证
+
+构建前先运行 `validate_design_quality.py --session <session>`。构建器也会在创建 PowerPoint 对象前自动执行同一检查；`FAIL` 时停止，`WARN` 写入报告并要求人工复核或带理由豁免。
+
+执行：
+
+```bash
+python scripts/build_native_editable_deck.py \
+  --spec <session>/analysis/native_deck_spec.json \
+  --base-dir <session>/analysis \
+  --scene-dir <session>/scenes \
+  --session <session> \
+  --out-pptx <session>/final/deck.pptx \
+  --report <session>/reports/native-editable-build.json
+```
+
+构建器输出原生文本、形状、线条、表格、Office 图表和独立图片对象。完成后依次执行：
+
+首次构建后运行 `sync_canvas_scene.py`，将 PPTX 原生对象同步为 scene element v2。UI 修改 element 后，使用同一构建命令和 `--scene-dir` 重建；构建器按对象 ID 应用位置、尺寸、文字、样式、旋转与图层覆盖。
+
+1. `validate_pptx_fonts.py`
+2. `validate_pptx_typography.py`
+3. `audit_pptx_editability.py`
+4. 中间阶段只生成 PNG/结构预览，不打开 PPTX；最终 artifact 完成后运行一次 `render_pptx.py --validation-stage final --gui-validation-mode final-only`
+5. 人工检查逐页预览或 contact sheet
+6. `run_quality_gate.py`
+
+画布风格切换使用 editor v3 的 `apply-style`。整套切换可跨风格家族；单页切换只允许同一家族内的变体。`preserve-layout` 保留几何和文字并清除旧样式覆盖，`replace-theme` 清空目标页 canvas override 后完整重建。
+
+用户要求先画布后 PPTX 时使用 `editor_workflow_mode=canvas-first`。此时不要先把初稿写入 `final/`：直接从 scene manifest 渲染页面；需要构建中间预览时写入 `cache/editable/preview.pptx`。只有收到画布导出动作、风格已确认且 `editor_bridge.py approve-export` 成功后，才能执行最终构建和质量门。
+
+用户同时要求 Markdown 编辑时，设置 `authoring_mode=markdown-canvas` 并读取 [markdown-canvas-workflow.md](markdown-canvas-workflow.md)。先编译 `slides.md`，再在 `cache/editable/preview.pptx` 建立一次原生结构预览并同步对象 ID；后续画布和最终 PPTX 都使用同一 scene，不再从 Markdown 或 archetype 单独重算第二套布局。
+
+画布导出后不得重新解释布局。必须把画布提交的全部页面 scene 写回 session，再用同一 scene 构建 PPTX。禁止只读取 `cover` 字段、用临时脚本后处理封面，或让未在画布出现的模板布局覆盖画布对象。页数按用户要求建立；例如用户要求 10 页，画布必须先显示并可切换 10 页，然后才能批准导出 10 页 PPTX。
+
+`reports/native-editable-build.json` 必须记录原生形状、connector、表格、Office 图表、图片对象和 image-2 资产数量。`image-led-editable` 没有 image-2 资产时构建必须失败。
+
+## 能力边界
+
+- v1 不生成 SmartArt、对象级动画、音频和讲者备注。
+- Python figure、复杂研究图和照片可以作为独立图片插入，但不能宣称其内部可编辑。
+- Office 图表的数据和图表对象可编辑；复杂视觉优先保证表达质量，不强制全部原生化。
+- image-2 是视觉资产后端，不是事实、数字、Logo 或中文正文后端。
--- a/skills/presentation-forge/references/native-template-fill-workflow.md
+++ b/skills/presentation-forge/references/native-template-fill-workflow.md
@@ -0,0 +1,131 @@
+# 原生 PPTX 模板填充
+
+当用户提供原生 `.pptx` 模板和新内容，并要求保留 PowerPoint 设计、直接填字时使用。本路线直接修改 OOXML；不经过整页生图、SVG 或元素重组。
+
+## 能力边界
+
+v1 支持：
+
+- 分析原生文本框、占位符和表格单元格。
+- 根据几何尺寸与字号估算文本容量。
+- 选择、删除和重排源页面。
+- 替换文本框和普通表格单元格文字。
+- 为替换文字显式设置宋体等指定字体，并可选择作用于全部选中页面或同步主题字体。
+- 保留源主题、版式、图片、图表、SmartArt、动画和页面切换的原始包部件。
+
+v1 不支持：
+
+- 重复克隆同一源页面。
+- 替换图片、编辑图表数据、改写 SmartArt。
+- 改写对象级动画。
+- 自动缩小字体来容纳超长文字。
+
+遇到不支持的需求时返回 `BLOCKED` 或保留原对象；不要宣称已经编辑。
+
+## 固定目录
+
+在统一 session 内使用：
+
+```text
+sources/source-template.pptx
+analysis/slide-library.json
+analysis/fill_plan.json
+analysis/check_report.json
+final/filled-deck.pptx
+reports/native-template-validation.json
+reports/quality-gate.json
+```
+
+## 1. 分析模板
+
+```bash
+python3 scripts/native_template_fill.py analyze \
+  <session>/sources/source-template.pptx \
+  --out <session>/analysis/slide-library.json
+```
+
+把 `slide-library.json` 当作版式库读取。按页面的文本框角色、几何尺寸、容量和原有修辞结构选择页面，不按源页面顺序机械替换。
+
+## 2. 建立填充计划
+
+```bash
+python3 scripts/native_template_fill.py scaffold \
+  <session>/analysis/slide-library.json \
+  --slides 1,3,5 \
+  --out <session>/analysis/fill_plan.json
+```
+
+在 `fill_plan.json` 中为每页填写：
+
+- `purpose`：该页在目标故事中的作用。
+- `layout_rationale`：为什么源版式适合这段内容，以及主要风险。
+- `replacements`：使用分析结果中的精确 `slot_id` 和新文字。
+
+需要指定字体时，在计划顶层加入：
+
+```json
+"font_policy": {
+  "font_face": "宋体",
+  "scope": "replaced-text"
+}
+```
+
+`scope` 支持：
+
+- `replaced-text`：只给本次替换的新文字显式设置字体，最适合保留模板设计。
+- `all-selected-text`：给选中页面内全部中文 run 设置字体。
+- `theme-and-replaced`：设置替换文字，并同步 Theme major/minor 的东亚字体；可能影响模板中继承主题字体的其他文字。
+
+ substantive claim 必须来自用户材料。标题和短标签优先改写压缩，不默认缩小字号。
+
+## 3. 容量与目标校验
+
+```bash
+python3 scripts/native_template_fill.py check-plan \
+  <session>/analysis/slide-library.json \
+  <session>/analysis/fill_plan.json \
+  --out <session>/analysis/check_report.json
+```
+
+`error_count > 0` 时必须修复。`text_capacity` 是需要人工复核的警告；优先缩短、拆页或换版式。
+
+## 4. 用户确认门
+
+向用户展示目标页序、删除页面、内容到版式的映射和容量警告。只有用户确认后，才把计划顶层 `status` 从 `draft` 改为 `confirmed`。
+
+不得使用调试参数绕过确认门。
+
+## 5. 原生填充
+
+```bash
+python3 scripts/native_template_fill.py apply \
+  <session>/sources/source-template.pptx \
+  <session>/analysis/slide-library.json \
+  <session>/analysis/fill_plan.json \
+  --out <session>/final/filled-deck.pptx \
+  --font 宋体 \
+  --font-scope replaced-text
+```
+
+禁止覆盖源 PPTX。脚本会保留源包并修改页面顺序与目标文本节点。
+
+## 6. 回读与统一质量门
+
+```bash
+python3 scripts/native_template_fill.py validate \
+  <session>/final/filled-deck.pptx \
+  <session>/analysis/fill_plan.json \
+  --out <session>/reports/native-template-validation.json
+
+python3 scripts/validate_ooxml_namespaces.py \
+  <session>/final/filled-deck.pptx \
+  --out <session>/reports/ooxml-namespace-validation.json
+
+python3 scripts/run_quality_gate.py \
+  --session <session> \
+  --artifact <session>/final/filled-deck.pptx
+```
+
+只有 `reports/quality-gate.json.status=PASS` 才能宣称正式完成。视觉渲染仍按 `scripts/render_pptx.py` 的 PowerPoint/LibreOffice 等级执行；回读通过不等于视觉溢出已人工确认。
+
+禁止使用 `xml.etree.ElementTree` round-trip 模板中的 slide、presentation、theme 或 layout XML。它会把 `p14`、`a14` 等命名空间改成 `ns*`，但不会同步 `mc:Choice Requires` 等属性值，PowerPoint 会提示修复文件。统一质量门必须检查这些兼容性前缀。
--- a/skills/presentation-forge/references/planning-workflow.md
+++ b/skills/presentation-forge/references/planning-workflow.md
@@ -0,0 +1,184 @@
+# 新 PPT 的计划、Session 与 Prompt 规范
+
+新做 PPT 时使用本规范。目标是让内容可审阅、生成过程可追踪、失败页面可单独重做。
+
+## 执行顺序
+
+```text
+确认 PPTX 可编辑性与最低简报
+-> 建立 session
+-> 运行确定性路由并锁定唯一 authority
+-> 编写 slides_plan.md
+-> 按 outline_review_mode 连续执行或显式等待确认
+-> 编译 prompts.json
+-> 生成单页视觉冒烟
+-> 用户确认视觉冒烟
+-> 生成全量
+-> 打包与 QA
+```
+
+大纲默认不构成阻塞门：没有明确审阅意图时记录 `outline_review_mode: continuous` 和 `outline_approval: auto-proceed`，写完计划后直接继续。用户明确说“先输出大纲”“等我确认”“确认后再生成”“暂时不要制作”等表达时，记录 `outline_review_mode: explicit` 和 `outline_approval: pending`，展示大纲并暂停；确认后改为 `approved`。用户明确要求跳过已经触发的确认门时记录 `outline_approval: waived`。冒烟仍是独立确认门；用户明确要求跳过时记录 `smoke_approval: waived`。
+
+## Session 目录
+
+使用：
+
+```bash
+python scripts/init_deck_session.py \
+  --title "企业 AI 知识库解决方案" \
+  --delivery-type image-pptx \
+  --outline-review-mode continuous \
+  --gui-validation-mode final-only \
+  --style-id enterprise-tech-dark \
+  --out-root ./outputs
+```
+
+目录结构：
+
+```text
+outputs/<session-id>/
+├── slides_plan.md
+├── slides_plan.json       # 可选；Markdown 计划稳定后再派生
+├── prompts.json
+├── metadata.json
+├── sources/
+├── analysis/
+├── scenes/
+├── versions/
+├── cache/image/
+├── cache/editable/
+├── references/
+├── generated/
+├── assets/
+├── final/
+├── render/
+├── compare/
+└── reports/
+```
+
+`slides_plan.json` 是可选派生文件；只有脚本明确需要时才生成。不要手改派生 JSON。
+
+用户选择 Markdown-first Canvas 时，session 额外包含 `slides.md`，并将 `metadata.authoring_mode` 设为 `markdown-canvas`、`metadata.content_source` 设为 `slides.md`。此时 `slides_plan.md` 与 `prompts.json` 都由 `compile_slides_markdown.py` 派生；人工只编辑 `slides.md`。完整规则见 [markdown-canvas-workflow.md](markdown-canvas-workflow.md)。
+
+建立 session 后按 [routing-workflow.md](routing-workflow.md) 生成 `reports/route-decision.json`。路线未达到 `PASS` 前，不得编译 scene、生成图片或填充 PPTX。
+
+`continuous` 模式写完 `slides_plan.md` 和 `prompts.json` 后直接运行 `scripts/compile_scenes.py`；`explicit` 模式等待大纲批准后再运行。后续图片版与可编辑版都使用这些 scene；详细规则见 [scene-workflow.md](scene-workflow.md)。
+
+## slides_plan.md
+
+Markdown 是内容 source of truth。推荐格式：
+
+```markdown
+---
+title: 企业 AI 知识库解决方案
+delivery_type: image-pptx
+style_id: enterprise-tech-dark
+typography_profile: zh-business-present
+table_profile: presentation-data-table
+visual_asset_policy: native-image-assisted
+audience: CIO、IT 负责人、知识管理负责人
+goal: 同意开展四周 PoC
+---
+
+## 1. [cover] 企业 AI 知识库解决方案
+
+布局：cover-hero
+
+页面目标：建立方案定位并提出 PoC 行动。
+
+核心信息：
+- 让企业知识真正可用
+- 四周验证价值与落地条件
+
+事实边界：
+- 不使用客户案例、准确率或 ROI 数据
+
+素材：
+- 无真实 Logo，右上角预留区域
+
+布局意图：左文右图的企业科技封面
+```
+
+每页必须包含：
+
+- 页码与 `page_type`：`cover`、`agenda`、`section`、`content`、`data`、`architecture`、`process`、`closing` 或 `other`。
+- `layout_id`：从所选风格的 `layouts.json` 选择；若没有完全匹配，选最接近的布局并在“布局意图”说明调整。
+- 标题、页面目标和 2-4 组核心信息。
+- 事实边界：禁止虚构、待确认信息、不可生成内容。
+- 素材：真实图片、Logo、截图、图表或“无素材”。
+- 布局意图：一句话说明页面形态，不写像素坐标。
+
+## prompts.json
+
+`prompts.json` 是逐页生成记录，不是内容源。最小结构：
+
+```json
+{
+  "schema_version": 1,
+  "session_id": "20260809-083000-enterprise-ai-knowledge-base",
+  "delivery_type": "image-pptx",
+  "style_id": "enterprise-tech-dark",
+  "typography_profile": "zh-business-present",
+  "table_profile": "presentation-data-table",
+  "visual_asset_policy": "native-image-assisted",
+  "slides": [
+    {
+      "slide_number": 1,
+      "page_type": "cover",
+      "style_id": "enterprise-tech-dark",
+      "layout_id": "cover-hero",
+      "layout_intent": "左文右图的企业科技封面",
+      "prompt": "完整的逐页生成提示词",
+      "reference_images": [],
+      "asset_reference_images": [],
+      "status": "planned",
+      "output_image": null,
+      "qa": {
+        "status": "pending",
+        "notes": []
+      }
+    }
+  ]
+}
+```
+
+生成前检查页码连续且与 `slides_plan.md` 一致。生成后更新 `status`、`output_image` 和 `qa`；不要删除失败记录。
+
+## 单页视觉冒烟
+
+- 默认选择封面；封面不能验证主体风格或信息密度时，选择风险最高的代表页。
+- 冒烟页必须使用正式风格、正式提示词和正式尺寸，不能用低质量占位稿冒充。
+- 向用户展示样张，并明确询问是否继续全量生成。
+- 用户要求修改时，只重编译和重生成该页；确认前不生成其他页面。
+- 用户确认后，在 `metadata.json` 记录页码、时间和 `smoke_approval: approved`。
+
+## metadata.json 状态
+
+至少记录：
+
+```json
+{
+  "session_id": "...",
+  "title": "...",
+  "delivery_type": "image-pptx",
+  "style_id": "enterprise-tech-dark",
+  "typography_profile": "zh-business-present",
+  "table_profile": "presentation-data-table",
+  "visual_asset_policy": "native-image-assisted",
+  "editability_confirmed": true,
+  "route": "image-generation",
+  "route_status": "PASS",
+  "status": "planning",
+  "outline_review_mode": "continuous",
+  "outline_approval": "auto-proceed",
+  "gui_validation_mode": "final-only",
+  "final_powerpoint_validation": "pending",
+  "smoke_slide": null,
+  "smoke_approval": "pending",
+  "final_qa": "pending"
+}
+```
+
+`delivery_type` 只允许：`image-pptx`、`editable-pptx`、`pdf`、`png`、`svg`。用户只说 PPTX 时，先询问，不得写入模糊值。
+
+正式交付前运行 `scripts/run_quality_gate.py`；该脚本负责把 `final_qa` 更新为 `pass`、`warn` 或 `blocked`。
--- a/skills/presentation-forge/references/prompt-patterns.md
+++ b/skills/presentation-forge/references/prompt-patterns.md
@@ -0,0 +1,159 @@
+# 生图提示词模式
+
+本文件用于生成逐页提示词。提示词要足够具体，能指导 imagegen 生成完整幻灯片；但不要把文字塞得过密，避免小字不可读。
+
+## 逐页提示词结构
+
+```text
+页面标题：
+{精确标题}
+
+页面目标：
+{这一页要让受众理解什么}
+
+核心文字：
+- {短要点1}
+- {短要点2}
+- {短要点3}
+
+版式结构：
+{选择一种清晰构图：链路图、场景地图、矩阵、飞轮、左右对照、路线图、证据墙、仪表盘、架构图、结束卡片等}
+
+视觉元素：
+{希望 imagegen 画出的具体元素：控制台、系统节点、文档墙、风险告警、流程箭头、产品界面、抽象平台等}
+
+风格提示词：
+16:9 整页 PPT 图片，{配色}，{气质}，{背景}，中文文字清晰，层级专业，不要像普通模板页。
+
+Logo 规则：
+预留真实 Logo 后叠区域。不要生成 Logo、伪 Logo、品牌标识、水印、二维码或印章。
+
+负向约束：
+不要水印、二维码、长 URL、伪 Logo、乱码、虚假数据、未经确认的信息、内部敏感内容、拥挤脚注、不可读小字。
+```
+
+## 全局风格块
+
+在逐页提示词前可以先写一个全局风格块：
+
+```text
+使用 16:9 横版演示文稿构图，目标 1920x1080 或更高。
+使用选定配色：主色 {primary}，辅助色 {secondary}，强调色 {accent}，强调色只小面积使用。
+页面适合现场讲解：标题强、层级清晰、中文可读、留白充足。
+避免所有页面都变成同一种卡片网格，整套 PPT 要有节奏变化。
+不要绘制任何真实 Logo，给后处理叠加真实 Logo 留出干净区域。
+```
+
+## 常用版式
+
+- **封面**：左侧标题区 + 右侧沉浸式主题视觉 + 底部 Logo 区。
+- **目录**：大编号 + 错落章节条 + 简单视觉锚点。
+- **核心结论**：三段结论链、升级路径或主张堆栈。
+- **场景地图**：分层地图、泳道或节点网络。
+- **证据墙**：资料卡、趋势线、时间轴和短结论。
+- **风险升级**：从左到右的风险演进链路，最后状态用强调色。
+- **优先级矩阵**：高/中/低区域热力图或象限图。
+- **方案架构**：顶部接入层、中间控制面、左右链路、底部审计运营。
+- **能力映射**：风险节点连接到能力模块。
+- **评测体系**：题集、攻击、执行、指标的流水线。
+- **闭环飞轮**：发现、分析、优化、验证、上线的循环。
+- **路线图**：阶段化路径和能力里程碑。
+- **结束页**：2-3 个行动建议卡片、验收指标和下一步建议。
+
+## 中文文字控制
+
+- 优先使用短标题和短要点。
+- 每页只保留一个中心主张。
+- 使用 2-4 组主要文字，不要写成长段落。
+- 只要求 imagegen 精确生成关键标题和要点，非关键信息宁可少写。
+- 如果中文错字或乱码，减少文字量、放大文字块后重抽。
+- 真实 Logo、法律标识和合规印章一律后处理叠加，不交给 imagegen。
+
+## 语义资产网格提示词
+
+当目标是把图片页重建为可编辑 PPT 时，不要让 imagegen 生成整页截图，也不要直接裁原图当最终资产。应生成可透明化的 isolated asset grid：
+
+```text
+Create an isolated asset grid for a PowerPoint visual replica.
+Use the reference slide for style only. Create standalone assets, not slide crops.
+
+Objects in order:
+1. {generic_icon_01}
+2. {generic_icon_02}
+3. {workflow_arrow_01}
+4. {decorative_asset_01}
+
+Grid:
+{rows}x{cols}, generous margin, equal cells, each object centered.
+
+Background:
+uniform chroma key #00ff00 for later transparent cutout.
+
+Style:
+clean business presentation asset, consistent lighting, no surrounding card, no slide background.
+
+Negative constraints:
+no readable text, no numbers, no labels, no watermark, no logo, no QR code, no card frame, no rectangular crop border, no neighboring object fragments.
+```
+
+生成后用 `scripts/grid_cut.py` 切成一个语义单元一个 PNG，再插入 PPT。
+
+## 通用示例：风险升级路径页
+
+这个示例来自一次真实生图 PPT 流程，但已去除具体品牌、客户和内部信息，可作为“链路型说明页”的提示词参考。
+
+```text
+16:9 中文安全趋势页，白底，目标 1920x1080。
+主标题必须清晰：“风险升级路径：从误答到真实环境副作用”。
+
+核心文字必须清晰：
+- 普通问答：幻觉、误导、违规回答
+- RAG / 外部内容：间接提示注入、上下文污染
+- Agent / 工具调用：越权操作、数据外发、环境副作用
+
+版式结构：
+中间是一条横向升级路径，不要表格：
+普通聊天机器人 → RAG / 网页文档 → 工具调用 Agent → 插件 / 能力扩展 → 真实环境执行。
+每一站下方有短标签：幻觉误导、间接提示注入、上下文污染、计划漂移、越权操作、数据外发。
+最后两站使用少量风险红强调。
+
+视觉元素：
+淡蓝执行链路、API 图标、文件图标、网络图标、Shell / 命令图标、风险告警三角、审计日志线条。
+底部短句：“Agent 化之后，风险不只发生在文本输出，还会落到环境动作。”
+
+风格提示词：
+专业企业汇报风，白底，主色为深蓝和浅蓝，红色只用于高危风险；信息图化，有空间层次，适合现场讲解。
+
+Logo 规则：
+右上角预留真实 Logo 区，不要生成任何 Logo 或伪标识。
+
+负向约束：
+无水印、无二维码、无长 URL、无乱码、无内部客户名、无真实攻击步骤、无虚假数据。
+```
+
+## 通用示例：优先级矩阵页
+
+```text
+16:9 中文商务 PPT 页面，白底，目标 1920x1080。
+主标题必须清晰：“风险优先级矩阵”。
+
+核心文字：
+- 高优先级：数据泄露、越权动作、合规红线
+- 中优先级：幻觉误导、上下文污染、工具供应链
+- 低优先级：格式错误、低影响输出偏差
+
+版式结构：
+做成热力矩阵，不要做普通表格。纵轴是影响程度，横轴是治理优先级。高风险区域用红色，中风险区域用蓝色，低风险区域用浅灰。
+
+视觉元素：
+风险图标、小型盾牌、治理闭环、淡色科技网格。
+
+风格提示词：
+专业企业演示风，白底商务，主色深蓝，辅助浅蓝，少量红色强调，中文文字清晰，留白充足。
+
+Logo 规则：
+右上角留出空白 Logo 区。不要生成任何 Logo 或伪标识。
+
+负向约束：
+不要水印、二维码、长 URL、乱码、伪品牌标识、虚构统计数据、密集脚注或不可读小字。
+```
--- a/skills/presentation-forge/references/publication-boundaries.md
+++ b/skills/presentation-forge/references/publication-boundaries.md
@@ -0,0 +1,33 @@
+# 公开发布边界
+
+把项目沉淀成公开 skill 时，只保留通用流程、抽象规则、脚本和 synthetic 示例。不要把客户交付物或真实项目中间产物放进仓库。
+
+## 可以公开
+
+- 通用工作流：需求澄清、逐页提示词、图片封装、语义拆解、渲染 QA。
+- 通用脚本：图片裁切、PPTX 封装、可编辑性审计、资产网格切分、公开发布扫描。
+- 抽象示例：不包含客户名、真实 Logo、真实数据和真实 badcase 的示例图。
+- 参数化配置：示例品牌色、占位 Logo 路径、示例字体名、示例输出目录。
+- 局限性说明和适配边界。
+
+## 不应公开
+
+- 客户成品 PPT、PDF、PNG、contact sheet、渲染预览和交付说明。
+- 真实 Logo、客户模板、内部图标库、品牌素材和源文件。
+- 逐页详细提示词、证据清单、QA 记录、会议材料、投标材料和内部评审记录。
+- 真实客户名、真实场景名、内部产品名、报价、合同、SLA、指标、QPS、模型版本和参数。
+- 私有路径、账号、token、cookie、API key、内部域名和可访问链接。
+- 未脱敏 badcase、真实攻击样本、客户数据、用户数据和日志。
+
+## 发布前检查
+
+1. 运行敏感扫描：
+
+```bash
+python scripts/audit_public_skill.py --root .
+```
+
+2. 检查 git 状态，只提交 skill 本身需要的文件。
+3. 打开 README 和 SKILL.md，确认没有客户名、私有路径和内部项目口径。
+4. 确认示例图确实是可公开的 synthetic demo。
+5. 如果来源不确定，默认不公开。
--- a/skills/presentation-forge/references/routing-workflow.md
+++ b/skills/presentation-forge/references/routing-workflow.md
@@ -0,0 +1,67 @@
+# 确定性路由
+
+本文件是路线选择的唯一权威。先把用户意图写成结构化 request JSON，再运行 `scripts/route_deck_workflow.py`。一旦得到 `PASS`，本次任务只能读取和执行 `authority` 指向的路线；不得把多条生产链混在一起。
+
+## 路由矩阵
+
+| 路线 | 触发条件 | 必要输入 | 输出承诺 |
+|---|---|---|---|
+| `image-generation` | 图片型 PPTX、PDF、PNG，且不要求对象级编辑 | 内容简报 | 整页图片、图片型 PPTX/PDF |
+| `native-editable-deck` | 从主题或文档新建演示；默认先进入 Markdown 可编辑画布 | 内容简报 | `slides.md`、完整画布、原生文本/形状/表格/Office 图表与可选 image-2 视觉资产 |
+| `element-rebuild` | 把已有图片页或截图重建为可编辑对象 | 参考页图片 | 原生文本/形状与独立视觉资产组成的 PPTX |
+| `svg-redraw` | 明确要求 SVG | 参考页图片 | SVG 与预览，不承诺 PowerPoint 对象级编辑 |
+| `native-template-fill` | 原生 PPTX 模板加新内容，要求保留模板设计并填充 | 源 PPTX、新内容 | 直接修改 OOXML 的新 PPTX，不经过整页生图或 SVG |
+
+`operation=enhance`（备注、音频、动画增强）当前必须返回 `BLOCKED`，留给后续阶段实现。
+
+## Request JSON
+
+```json
+{
+  "delivery_type": "editable-pptx",
+  "operation": "fill",
+  "input_kind": "pptx-template",
+  "editability": "editable",
+  "authoring_mode": "markdown-canvas",
+  "editor_workflow_mode": "canvas-first",
+  "has_source_pptx": true,
+  "has_new_content": true,
+  "has_reference_slides": false,
+  "preserve_native_design": true,
+  "explicit_template_fill": true
+}
+```
+
+允许的核心值：
+
+- `delivery_type`: `image-pptx`、`editable-pptx`、`pdf`、`png`、`svg`、`pptx`、`unspecified`
+- `operation`: `create`、`fill`、`rebuild`、`enhance`
+- `input_kind`: `topic`、`document`、`pptx-template`、`pptx-finished`、`slide-images`、`mixed`
+- `editability`: `image`、`editable`、`unspecified`
+- `visual_asset_policy`: `native-only`、`native-image-assisted`、`image-led-editable`
+- `authoring_mode`: `markdown-canvas`、`slides-plan`
+- `editor_workflow_mode`: `canvas-first`、`direct-build`
+
+从零创建演示或可编辑 PPTX 时，默认 `authoring_mode=markdown-canvas`、`editor_workflow_mode=canvas-first`、`visual_asset_policy=native-image-assisted`。先生成并展示完整画布，不写入 `final/`；用户批准导出后再构建 PPTX。只有用户明确要求直接导出、不要画布或跳过预览时，才使用 `slides-plan + direct-build`。已有图片页重建仍走 `element-rebuild`。
+
+用户只说 `PPTX` 时保留 `delivery_type=pptx`，脚本会返回 `NEEDS_INPUT` 和唯一问题。不要在脚本外自行猜测。
+
+用户只说“制作演示”“根据文档做汇报”而没有指定交付格式时，记录 `delivery_type=unspecified`、`operation=create`；默认路由到 `native-editable-deck + markdown-canvas + canvas-first`。这与只说 `PPTX` 不同：后者仍需确认图片型还是可编辑型。
+
+## 命令
+
+```bash
+python3 scripts/route_deck_workflow.py \
+  --request <session>/route-request.json \
+  --session <session>
+```
+
+结果写入 `reports/route-decision.json` 并同步到 `metadata.json`：
+
+- `PASS`：进入且只进入所选路线。
+- `NEEDS_INPUT`：只询问 `blocking_question`，不得开始生产。
+- `BLOCKED`：报告 `missing_prerequisites`，不得静默降级。
+
+## 失败恢复
+
+修复结构化 request 或补齐必要输入后重新运行路由。不要通过手改 `metadata.json.route` 绕过路由报告；统一质量门会校验两者一致。
--- a/skills/presentation-forge/references/scene-workflow.md
+++ b/skills/presentation-forge/references/scene-workflow.md
@@ -0,0 +1,61 @@
+# Scene、局部重建与版本工作流
+
+Scene 是每页唯一的结构化渲染事实源。普通模式由 `slides_plan.md` 决定内容；Markdown-first 模式由 `slides.md` 决定内容。scene 固化页面语义、对象和几何，图片版、画布和可编辑版都从 scene 派生，不再各自维护一套页面描述。
+
+## Session v2
+
+```text
+session/
+├── slides_plan.md
+├── prompts.json
+├── metadata.json
+├── scenes/slide-001.scene.json
+├── versions/r0001/
+├── cache/image/slide-001/
+├── cache/editable/slide-001/
+├── generated/
+├── assets/
+├── final/
+├── render/
+└── reports/
+```
+
+`metadata.json` 只保存共享身份、当前 revision、环境报告和两个交付 variant 的状态。逐页细节留在 scene，构建报告留在 `reports/`。
+
+## 执行顺序
+
+```text
+slides_plan.md + prompts.json
+-> compile_scenes.py
+-> validate_scene.py
+-> preflight_ppt_environment.py
+-> revision_session.py snapshot
+-> rebuild_slide.py prepare
+-> imagegen 或 editable builder 生成目标页
+-> rebuild_slide.py commit
+-> 重新封装整套 PPTX
+```
+
+局部重建只让目标页的昂贵依赖失效。最终 PPTX 可以整套快速封装，不直接修改 OOXML 中的单页关系。
+
+`prepare` 会生成后端输入：图片版写入 `cache/image/slide-NNN/prompt.json`；可编辑版写入 `cache/editable/slide-NNN/visual_inventory.json`。其中未解析的 `semantic_visual` 会被标成 `unresolved`，必须完成资产绑定后才能进入正式可编辑构建。
+
+全套可编辑构建使用 `compile_scenes.py --emit-editable-inventory` 生成 `cache/editable/visual_inventory.json`，再交给现有 semantic builder。该派生文件不会覆盖旧项目手工维护的根目录 `visual_inventory.json`。
+
+## Scene 规则
+
+- `slide_id` 永久稳定，使用 `slide-001` 格式；改标题不能改 ID。
+- 每个 element ID 在页内唯一，bbox 使用像素坐标 `[x, y, width, height]`。
+- `semantic_visual` 是尚未绑定来源的语义视觉；进入可编辑正式构建前转换为 `imagegen_asset` 或有来源记录的 `provided_asset`。
+- `scene_hash` 排除自身和构建状态后计算；它决定页面是否失效。
+- 普通版使用 `generation.prompt` 生成整页图；可编辑版读取 `elements` 生成原生文字、容器和独立资产。
+
+## Revision 规则
+
+- snapshot 保存 metadata、计划、prompts、scenes 和核心 manifest，不复制大体积生成图。
+- revision manifest 保存所有被追踪文件的 SHA-256，资产继续由 session 中的稳定路径或内容 hash 引用。
+- rollback 先自动 snapshot 当前状态，再恢复目标 revision，并创建新的 rollback revision；不得删除历史 revision。
+
+## 向后兼容
+
+旧 session 首次运行 `compile_scenes.py` 时自动把 metadata 提升为 schema v2，并从 `slides_plan.md`、`prompts.json` 生成 scene。旧的 `visual_inventory.json`、`asset_manifest.json` 仍可被现有 builder 使用，但新项目应逐步改为从 scene 派生。
--- a/skills/presentation-forge/references/semantic-replica-workflow.md
+++ b/skills/presentation-forge/references/semantic-replica-workflow.md
@@ -0,0 +1,337 @@
+# Semantic Editable Replica Workflow
+
+Use this reference when an image-only slide, screenshot, rendered PPT page, or generated page must become a practical editable PPTX.
+
+## Contents
+
+- [Required Flow](#required-flow)
+- [Reusable Project Layout](#reusable-project-layout)
+- [Object Classes](#object-classes)
+- [Minimum Semantic Unit](#minimum-semantic-unit)
+- [Asset Generation Rules](#asset-generation-rules)
+- [Grid vs Standalone Assets](#grid-vs-standalone-assets)
+- [Required Manifests](#required-manifests)
+- [Text Fit, Collision, And Visual Regression](#text-fit-collision-and-visual-regression)
+- [Build Rules](#build-rules)
+- [v4/v5 Gates](#v4v5-gates)
+- [QA Rules](#qa-rules)
+- [Practical Limits](#practical-limits)
+
+## Required Flow
+
+Element rebuild is a reference-driven asset workflow:
+
+```text
+reference
+-> visual_inventory
+-> asset_anchors
+-> layout_rules
+-> reference crops / residual redboxes
+-> imagegen or API asset grid
+-> grid_cut and alpha cleanup
+-> asset_manifest
+-> semantic input preflight
+-> build_semantic_deck
+-> text-fit and layout QA report
+-> render compare
+-> validation
+```
+
+If this flow is skipped, the result is only an editable draft or structure preview. Do not call it a completed element rebuild.
+
+## Reusable Project Layout
+
+Use the same artifact layout for every production reconstruction:
+
+```text
+reference/
+reference_crops/
+generated/
+assets/
+render/
+compare/
+reports/
+prompts/assets_cycle_1.jsonl
+visual_inventory.json
+asset_anchors.json
+asset_manifest.json
+layout_rules.json
+conversion_report.md
+```
+
+Run `scripts/init_semantic_project.py` to create the layout. The v4/v5 lesson is that project-local scripts can be temporary, but these ledgers must stay stable across pages:
+
+- `visual_inventory.json`: every text, native layout object, and semantic visual placement.
+- `asset_anchors.json`: target bboxes, z-order, fitted bboxes, and placement rules for semantic visuals.
+- `asset_manifest.json`: one final transparent asset file per semantic unit, including source grid and cell.
+- `layout_rules.json`: font policy, image-fit policy, forbidden media, source-type whitelist, and comparison thresholds.
+
+## Object Classes
+
+Classify every visible element before building:
+
+- `text`: editable PPT text boxes.
+- `layout_native`: page background, panels, cards, dividers, frames, tables, simple containers, and ordinary straight connectors.
+- `imagegen_asset`: semantic non-text visuals such as icons, pictograms, 3D objects, chart symbols, badges, decorative UI renders, screenshots, devices, network diagrams, illustrations, and stylized arrows.
+- `provided_asset`: user-supplied or approved transparent assets with documented source.
+- `unresolved`: anything that still needs a decision.
+
+If a visual carries meaning beyond being a border, divider, plain container, or text box, classify it as `imagegen_asset`. Complex arrows with gradients, curves, shadows, dashed returns, 3D depth, or brand-like styling are semantic assets, not native PPT arrows.
+
+## Minimum Semantic Unit
+
+The final PPT should expose the smallest useful selectable unit:
+
+- one icon = one asset;
+- one badge or risk marker = one asset;
+- one decorative UI render = one asset;
+- one 3D object or illustration = one asset;
+- one stylized arrow = one asset;
+- one text block = one text box;
+- one card, panel, table frame, divider, or simple connector = one native PPT object.
+
+Generated grids are extraction sheets only. Cut them into one transparent asset file per semantic unit before inserting anything into PPT.
+
+## Asset Generation Rules
+
+Every production image asset must be generated with Codex's `imagegen` skill. Use the full reference plus the relevant crop or residual crop as visual context when the tool supports references. Text-only generation is acceptable only for synthetic fixtures or generic demos, not for reference-matched production reconstruction.
+
+Do not use LibreOffice, PowerPoint, SVG redraws, programmatic icon drawing, generic icon libraries, or browser screenshots as substitutes for image generation. LibreOffice / PowerPoint / soffice may be used only after the deck is built to render PPTX into PDF/PNG for QA. Label that step as render QA, not image generation.
+
+`api_generated_asset` remains in the schema for compatibility, but do not choose it unless the user explicitly asks for an external image API. `provided_asset` is valid only for user-supplied or licensed assets and synthetic tests; it is not a production replacement for Codex `imagegen`.
+
+Prompt each grid like this:
+
+```text
+Create an isolated asset grid for a PowerPoint visual replica.
+Use the full reference for style and the supplied crops/residuals for object identity.
+Objects in order: {object list}.
+Grid: {rows}x{cols}, generous margins and equal cells.
+Background: uniform chroma key #00ff00 or clean white.
+Style: {short style guide}.
+Text: no readable text, no numbers, no labels, no watermark.
+Do not include card frames, slide fragments, fake logos, QR codes, crop borders, or surrounding context.
+```
+
+After generation:
+
+- cut with declared grid geometry;
+- remove white/chroma background to alpha;
+- trim transparent borders;
+- reject assets with readable text, residual card frames, hard crop edges, neighboring objects, or one-axis distortion;
+- reject any grid-cut asset whose visible alpha touches the cell boundary, contains green/chroma spill, is clipped, or includes multiple semantic objects;
+- record every final asset in `asset_manifest.json`.
+
+The generated grid is never a final slide asset. It is only an extraction sheet. A production-grade v4/v5-style page should normally have:
+
+- `prompts/assets_cycle_*.jsonl`;
+- one or more files under `generated/`;
+- transparent files under `assets/`;
+- `asset_manifest.json` records with `source_type: imagegen_asset` or `api_generated_asset`;
+- `asset_anchors.json` records for every placement.
+
+If the manifest contains only synthetic `provided_asset` entries, the run proves the build chain but not visual replica quality.
+
+## Grid vs Standalone Assets
+
+Asset grids are a convenience, not the default for every visual. Use grids only for small, similarly sized, low-risk icons where each object is unlikely to cross cell boundaries.
+
+Use standalone Codex `imagegen` calls for:
+
+- central hero visuals and large 3D objects;
+- shields, devices, dashboards, platform bases, and decorated scenes;
+- complex arrows with shadows or gradients;
+- assets that must preserve exact silhouette or visual weight;
+- any asset that failed grid cutting because it was clipped, attached to neighbors, or left chroma spill.
+
+If a grid asset fails, do not "fix" it by resizing or hiding the problem in PPT. Regenerate that semantic unit as a standalone `imagegen_asset`, remove chroma to alpha, and update `asset_manifest.json`.
+
+For public examples, keep object names generic, for example `domain_icon_01`, `workflow_arrow_01`, `decorative_asset_01`.
+
+## Required Manifests
+
+`visual_inventory.json` should describe the page-level decomposition:
+
+```json
+{
+  "slide_size_px": [1920, 1080],
+  "final_deck_type": "semantic_editable_replica",
+  "source_image_policy": "reference only; do not embed the full source image in the final PPTX",
+  "items": [
+    {
+      "id": "title_main",
+      "class": "text",
+      "text": "Example title",
+      "bbox_px": [80, 60, 900, 80]
+    },
+    {
+      "id": "domain_icon_01",
+      "class": "imagegen_asset",
+      "bbox_px": [120, 220, 120, 120],
+      "semantic_unit_count": 1
+    }
+  ]
+}
+```
+
+`asset_manifest.json` should record final asset files:
+
+```json
+[
+  {
+    "semantic_unit_id": "domain_icon_01",
+    "source_type": "imagegen_asset",
+    "asset_path": "assets/domain_icon_01.png",
+    "semantic_unit_count": 1,
+    "generated_grid": "generated/domain_icons_grid.png",
+    "grid_cell": [0, 0],
+    "placement_rule": "uniform contain scaling; no one-axis stretch"
+  }
+]
+```
+
+Acceptable source types are `imagegen_asset`, `api_generated_asset`, and documented `provided_asset`. `raw_crop`, `reference_crop`, `screenshot_crop`, `placeholder`, and `prompt_only_asset` are not acceptable final sources.
+
+`asset_anchors.json` should record placements independently from asset provenance:
+
+```json
+[
+  {
+    "semantic_unit_id": "domain_icon_01",
+    "slide": 1,
+    "target_bbox_px": [120, 220, 120, 120],
+    "z_index": 20,
+    "placement_rule": "uniform contain scaling; no one-axis stretch"
+  }
+]
+```
+
+`layout_rules.json` should be executable enough for QA:
+
+```json
+{
+  "slide_size_px": [1920, 1080],
+  "font_policy": {
+    "default_font_face": "Microsoft YaHei",
+    "text_box_extra_room_pct": 12
+  },
+  "image_fit": "uniform_contain_only",
+  "allowed_source_types": ["imagegen_asset", "api_generated_asset", "provided_asset"],
+  "forbidden_media": ["full_slide_reference_image", "near_full_slide_reference_image", "svg_media", "raw_crop_asset"],
+  "comparison": {
+    "diff_threshold": 18,
+    "changed_pixel_pct_target": 0.25
+  }
+}
+```
+
+## Text Fit, Collision, And Visual Regression
+
+The builder must not only count editable objects. It must record layout facts
+that can be inspected after the PPTX is built:
+
+- every text box: `slide`, `id`, `bbox_in`, `font_size`,
+  `effective_font_size`, `text_role`, `fit_mode`, `line_spacing_pt`,
+  `overflow_height_ratio`, `overflow_width_ratio`, `estimated_text_bbox_in`,
+  `parent_id`, and `z_index`;
+- every image asset: semantic unit id, source path, placement slot, fitted bbox,
+  and uniform contain rule;
+- layout QA: text overflow, text-text collision, text on non-decorative images,
+  out-of-slide bounds, and parent containment warnings.
+- text-on-image is an error by default. Allow it only when the inventory item
+  explicitly sets `text_overlay_allowed: true`, for example intentional white
+  text on a clean shield, badge, or button asset.
+
+Default text behavior:
+
+- `fit_mode=shrink` unless explicitly disabled.
+- Titles, subtitles, headers, pills, chips, tags, and badges default to
+  no-wrap; they should shrink before accidental one-character wrapping.
+- Body text may wrap, but must report overflow when estimated content exceeds
+  the inner text box.
+- Micro labels may go below the ordinary body font floor, but this must remain
+  visible in the build report as a warning or consciously accepted exception.
+
+Validation should pass `--build-report` to `validate_semantic_deck.py`. A deck
+with a clean media check but missing build-report layout QA is only a structure
+draft.
+
+Visual regression is a gate, not decoration:
+
+- run `validate_pptx_fonts.py` to confirm explicit East Asian typefaces;
+- render the editable PPTX through `render_pptx.py`; PowerPoint is target fidelity and LibreOffice is approximate QA only;
+- run `compare_render.py` against the reference pages;
+- inspect the contact sheet for title wrapping, card text overflow, icon/text
+  collisions, lost decorative assets, and broken z-order;
+- if the compare status is `REVIEW`, update the inventory/layout rules and
+  rebuild rather than accepting the first PPTX.
+
+## Build Rules
+
+- Use native PPT text for all readable text.
+- Keep line counts deliberate; do not let PowerPoint create accidental one-character wraps.
+- Use `fit_mode=shrink` and role-aware font floors for dense pages; avoid
+  solving overflow by silently shrinking ordinary body text into unreadability.
+- Use native shapes for cards, panels, frames, shadows, tables, dividers, and simple connectors.
+- Insert semantic visuals as independent PNG assets.
+- Fit images with uniform contain scaling.
+- Never stretch images on one axis.
+- Use `scripts/build_semantic_deck.py` for manifest-driven PPTX construction when the inventory fits the public schema.
+- Use `scripts/validate_semantic_inputs.py` before build; do not wait for PPTX validation to discover missing assets or raw crops.
+- Use `build_report.json` as the source of truth for text fitting, collision
+  checks, and fitted image positions.
+- Never insert SVG media in a path B final PPTX.
+- Never insert the full reference image or near-full-slide reference media in the final deck.
+- Do not use generic hand-drawn icons or low-fidelity native shapes as replacements for semantic visuals.
+
+## v4/v5 Gates
+
+The v4/v5 trial succeeded because it passed these gates:
+
+- Generated visual assets were created from reference-aware grids, not drawn as generic placeholders.
+- Grids were cut into one transparent PNG per semantic unit.
+- Dirty assets were cleaned before insertion.
+- Semantic placements were recorded separately from source provenance.
+- Text/card/container layers were rebuilt as native PPT objects.
+- Render comparison produced contact sheets and diff heatmaps.
+- Validation rejected full-slide references, raw crops, SVG media, and manifest/object mismatches.
+
+Do not certify a page as `semantic visual-replica` unless the same gates exist for the page being delivered.
+
+## QA Rules
+
+Validate before handoff:
+
+- PPTX opens and renders.
+- Slide count matches the reference.
+- No full-slide or near-full-slide reference bitmap is embedded.
+- Reference image hashes do not appear in PPTX media.
+- No SVG media exists in the final path B PPTX.
+- Every semantic image object has a manifest record.
+- Every `imagegen_asset` or `provided_asset` in inventory has a real asset file.
+- Picture objects in PPTX are at least enough to cover manifest placements.
+- Text items have visible native PPT text boxes; hidden transparent text over a screenshot is not a completed element rebuild.
+- Render previews, contact sheet, and diff heatmaps exist when reference render is available.
+- Report lists unresolved regions, retained bitmap exceptions, and known limits.
+
+Use `scripts/build_semantic_deck.py`, `scripts/validate_semantic_deck.py`, `scripts/compare_render.py`, and `scripts/audit_pptx_editability.py` together. Any failed gate means the result is not a certified element rebuild.
+
+For a reusable run, add:
+
+```bash
+python scripts/validate_semantic_inputs.py --inventory visual_inventory.json --manifest asset_manifest.json --anchors asset_anchors.json --stage build
+python scripts/build_semantic_deck.py --inventory visual_inventory.json --manifest asset_manifest.json --out-pptx final/reconstructed.pptx --report reports/build_report.json
+python scripts/validate_pptx_fonts.py final/reconstructed.pptx --out reports/font-validation.json
+python scripts/audit_pptx_editability.py final/reconstructed.pptx --json reports/editability-audit.json
+python scripts/validate_semantic_deck.py --pptx final/reconstructed.pptx --reference reference/page-01.png --manifest asset_manifest.json --inventory visual_inventory.json --build-report reports/build_report.json --out reports/semantic-validation.md
+python scripts/run_quality_gate.py --session <session> --artifact <session>/final/reconstructed.pptx
+```
+
+## Practical Limits
+
+- Use native PPT shapes for text, cards, tables, lines, connectors, and simple arrows.
+- Use independent transparent assets for complex icons, pictograms, illustrations, 3D visuals, UI renders, and stylized arrows.
+- Do not promise that SVG imports will remain internally editable in PowerPoint.
+- Avoid decomposing one complex icon into many ungrouped shapes unless the user explicitly needs that tradeoff and accepts fragility.
+- Keep 10%-15% extra room inside text boxes to absorb PowerPoint font and line-height differences.
+- Open the PPTX in the target PowerPoint environment when possible. LibreOffice render is useful for fast iteration, but it is not the final source of truth for Chinese font metrics.
--- a/skills/presentation-forge/references/style-library.md
+++ b/skills/presentation-forge/references/style-library.md
@@ -0,0 +1,51 @@
+# 中文商业风格库
+
+风格库用于新做 PPT 的视觉定向，不替代用户提供的品牌规范或模板。用户有真实模板、品牌色、字体和 Logo 规范时，以用户材料为最高优先级。
+
+## 选择流程
+
+1. 根据受众、沟通目标、行业和使用场合，从 `styles/catalog.json` 推荐 1–2 套风格家族，并在家族内选择一个视觉变体。
+2. 用户没有指定且选择不影响方向时，可以采用最匹配的一套，但须在大纲的假设中明确标注。
+   - `direct-build` 可以采用该假设并继续。
+   - `canvas-first` 只能把候选排序展示给用户，不得自动确认第一项；选择前记录 `style_selection_status: pending`。
+3. 选择后完整读取 `styles/<style_id>/STYLE.md` 和 `layouts.json`。
+4. 将 `style_id` 和 `style_variant` 写入 `slides_plan.md` frontmatter、`prompts.json`、`metadata.json`。
+5. 从 `styles/catalog.json` 读取该风格绑定的 `typography_profile` 与 `table_profile`，写入同一组计划和 session 元数据；详细规则见 [typography-workflow.md](typography-workflow.md)。
+6. 每页从该风格的布局库选择一个 `layout_id`。布局只约束信息组织，不是固定模板截图。
+7. 冒烟页必须使用正式 `style_id`、`style_variant`、`layout_id`、正式文案和正式尺寸。
+
+当前风格库包含 8 个家族、每个家族 3 个变体，共 24 个可选视觉预设。家族定义信息组织语言，变体定义配色和视觉气质；不要为每个变体复制一套布局文件。
+
+“24 个预设”表示可选择的视觉系统，不表示一套 PPT 同时混用 24 种样式，也不表示系统会随机选一种。默认仍只使用一个主风格；需要用户可见选择时必须进入 `canvas-first`。
+
+## 快速匹配
+
+| 风格 | 优先场景 | 主要气质 |
+|---|---|---|
+| 企业科技深蓝 | AI、数字化、技术架构、售前 | 深色、克制光效、可信科技 |
+| 蓝白咨询商务 | 咨询建议、管理层方案 | 明亮、清晰、理性、留白 |
+| 制造工业 | 制造、工程、能源、供应链 | 硬朗、网格、材质感、秩序 |
+| 政府正式 | 政府、国企、政策、专项汇报 | 稳重、规范、权威、克制 |
+| 极简高管汇报 | 董事会、经营决策、行动建议 | 一页一结论、强层级、大留白 |
+| 数据咨询 | 数据战略、洞察、指标、架构 | 深色咨询、图形化、分析感 |
+| 品牌发布 | 新品、品牌升级、创意提案 | 高对比、强节奏、发布感 |
+| 培训插画 | 培训、课程、科普、宣导 | 友好、易懂、统一插画语言 |
+
+具体变体以 `styles/catalog.json` 为准。画布从 editor manifest 的 `style_catalog` 读取扁平化预设，不自行维护另一份样式清单。
+
+## 使用约束
+
+- 不从参考风格复制客户名、品牌标识、案例、数字或图片素材。
+- 不因风格需要而虚构参数、准确率、ROI、排名或政策结论。
+- 同一套 PPT 默认只选一套主风格；章节可改变布局和背景明暗，但不得随意混搭视觉语言。
+- 单页只能切换当前主风格家族内的变体；跨家族切换必须作用于整套。
+- 封面和结束页可以使用不可复用的强构图；内容页优先使用 `reuse_friendly: true` 的布局。
+- 连续页面避免重复完全相同的布局；内容密度超出 `content_capacity` 时，应拆页而不是缩小字体。
+- 内置字体建议只是方向；交付前应检查目标设备的中文字体可用性并准备回退字体。
+- 宋体和小字号只用于正式阅读型 profile；会议投屏与高管演讲不得机械套用。
+
+修改或新增风格后运行：
+
+```bash
+python scripts/validate_style_library.py
+```
--- a/skills/presentation-forge/references/typography-workflow.md
+++ b/skills/presentation-forge/references/typography-workflow.md
@@ -0,0 +1,57 @@
+# 中文排版与表格策略
+
+新做可编辑 PPTX、原生模板填充或检查正式中文汇报时读取本规范。目标是把字体、字号、段落和表格对齐变成可执行策略，而不是依赖页面级临时判断。
+
+## 选择 Profile
+
+内置配置位于 `styles/typography-profiles.json`。风格在 `styles/catalog.json` 中绑定默认 `typography_profile` 与 `table_profile`；用户模板、品牌规范或明确指定字体始终优先。
+
+| Profile | 适用场景 | 主要特点 |
+|---|---|---|
+| `zh-formal-reading` | 研报、政府专项材料、邮件阅读型正式汇报 | 标题黑体、正文宋体、西文 Times New Roman；正文和表格密度较高 |
+| `zh-business-present` | 售前、项目汇报、技术说明、会议投屏 | 中文无衬线；正文与表格字号适合会议屏幕 |
+| `zh-executive-stage` | 高管演讲、董事会重点页、品牌发布 | 更大字号、低密度、强页面节奏 |
+
+宋体、12pt 和 1.5 倍行距不是全局默认值，只属于正式阅读型 profile。存在模板真实字号系统时，以模板为准并把例外写入 review note。
+
+## Token 纪律
+
+构建前在 `metadata.json` 锁定 `typography_profile` 和 `table_profile`。文本对象使用语义角色，不直接发明任意字号：
+
+- `hero`、`section_title`、`page_title`
+- `subtitle`、`minor_title`
+- `body`、`label`、`caption`
+- `table`
+
+字号使用 `0.5pt` 网格。超出容量时优先精简、扩大文本框或拆页；不要把正文持续缩到 profile token 以下。用户确有模板或品牌字号要求时允许偏离，但必须记录原因。
+
+构建器会把语义角色写入 shape name 的 `[pf-role=<role>]` 标记，供 `validate_pptx_typography.py` 回读。手工或模板对象缺少标记时，验证器只能根据 placeholder、名称和内容做有限推断；无法判断必须报告 `NOT_CHECKED`，不能算作通过。
+
+## 表格策略
+
+- 单元格默认上下居中。
+- 表头居中；索引或类目列居左；普通文本列居左；数值列居右。
+- 表格段前段后为 0、单倍行距、无首行缩进或异常层级。
+- 百分比、单位、负数和小数位数在同列保持一致；单位优先写入表头。
+- 无法可靠识别列语义时记录 `NOT_CHECKED`，不要猜测后强制改写。
+
+## 验证
+
+先运行字体声明检查，再运行语义排版检查：
+
+```bash
+python scripts/validate_pptx_fonts.py final/deck.pptx --font "微软雅黑"
+python scripts/validate_pptx_typography.py final/deck.pptx \
+  --profile zh-business-present \
+  --table-profile presentation-data-table \
+  --out reports/typography-validation.json
+```
+
+结果语义：
+
+- `PASS`：已检查项符合策略。
+- `WARN`：可交付但应修复或解释，例如字号偏离 token、表格对齐不一致。
+- `NOT_CHECKED`：没有足够的角色或格式信息完成判断。
+- `FAIL`：配置、文件或检查过程无效。
+
+统一质量门把 `WARN` 和 `NOT_CHECKED` 作为显式警告，把 `FAIL` 作为阻断项。