封面图加载中

PPT Master Skill 差异对比报告

本文详细对比了 ppt-master-enhanced 与上游 ppt-master skill 的差异，重点总结了前者在流程、审查、执行环境等方面的改善与优化。
  • 本文作者
  • 文章发布日期 2026-04-27 12:47
  • 热度 1
  • 天气 晴 20°
  • 作者心情 有点愉快
  • 地点 奥林匹克森林公园
  • 本文共计
  • 预计阅读

前言

  • 生成时间：2026-04-26 22:16:39（Asia/Shanghai）

  • 本项目仓库：https://github.com/MorningStar0709/ppt-master-enhanced

  • 上游项目仓库：https://github.com/hugohe3/ppt-master

  • 对比目的：全面比较当前仓库中的 ppt-master-enhanced skill 与上游 ppt-master skill 包差异，重点总结本项目 skill 的改善、加固和优化。

1. 总体结论

本项目的 ppt-master-enhanced skill 相比上游仓库 https://github.com/hugohe3/ppt-master 中的 ppt-master skill，核心方向不是简单增加模板或扩展导出功能，而是把原本偏「自动生成后直接后处理导出」的流程，升级为一个更严格、更可复查、更适合 Windows/Trae 环境长期执行的 PPT 生产工作流。

最关键的改善可以概括为：

  1. 从 7 步流程升级为 8 步流程：本项目把原原skill 的 Step 7 「Post-processing & Export」 拆开，在导出前新增独立的 Step 7 SVG Review Gate，导出被推迟到 Step 8。

  2. 导出前必须有人类批准：本项目明确要求 Step 7 使用 review/preview_finalized/ 和 review/preview_deck.html 作为最终审查依据，并要求用户显式确认后才能运行 total_md_split.py、finalize_svg.py、svg_to_pptx.py。

  3. 新增完整 review/revision 机制：本项目新增 review_manager.py、review_utils.py、revision_manager.py、revision_utils.py，把页面审查、修复队列、下一步判断、批准记录、修订轮次全部结构化。

  4. 新增多类自动校验器：本项目新增图标引用校验、布局几何校验、文本容器溢出校验、整 deck HTML 预览生成，使问题更早暴露。

  5. 强化 Windows/Trae 可执行性：本项目把 conda run --no-capture-output -n ppt-master、PYTHONIOENCODING=utf-8、CONDA_NO_PLUGINS=true、从 repo root 运行、禁止 PowerShell 重定向写关键产物等规则写成硬约束。

  6. 强化项目路径和源文件稳定性：本项目要求英文 slug、稳定项目路径 projects/<project_name>_<format>，导入源文件默认 --copy 并归档到 sources/，避免原skill 中带日期路径和默认移动源文件造成的路径漂移、原始文件丢失风险。

  7. 强化交互检查点一致性：本项目新增 references/interactive-checkpoint-guidelines.md，把模板选择、8 项确认、最终 SVG 审批的交互文案固定，减少不同 agent/不同轮次之间的提问风格漂移。

  8. 强化主 agent 串行生成与逐页自检：本项目不仅禁止子 agent 生成 SVG，还要求页面必须逐页生成、生成后立即用诊断模板自检，不能批量糊过去。

如果用一句话总结：原 skill 更偏「轻量自动生成导出」，本项目 ppt-master-enhanced 更偏「可控、可审、可批准、可恢复的生产级 PPT 工作流」。

2. 目录与体量差异

指标

本项目 skill

原skill

说明

总文件数

7154

7039

包含模板图标、缓存等全部文件

去除 __pycache__ / .pyc 后文件数

7058

7039

本项目仍多 19 个有效文件

仅本项目存在的文件

136

-

含 .runtime、review/revision/checker/test 文件和 pycache

去缓存后仅本项目存在的文件

40

-

主要是 review gate、revision、检查器、测试、文档

仅原skill 存在的文件

-

21

主要是 update_spec.py、OpenRouter 后端、若干新模板/图表

总字节数

9,218,270

7,767,781

本项目更重，主要重在 review 体系和测试

共同文件但内容不同

80

80

SKILL.md、核心脚本、references、模板索引均有改动

目录级别体量：

目录

本项目文件数 / 字节

外部文件数 / 字节

主要差异

.runtime

6 / 3,847

不存在

本项目新增命令回执目录

references

20 / 190,737

11 / 157,421

本项目新增交互、审查、架构页、逐页诊断等规则

scripts

186 / 2,643,334

73 / 794,561

本项目新增 review/revision/checker/test/runtime 工具

templates

6939 / 6,317,120

6952 / 6,775,897

原skill 多了部分图表和中国电信模板

workflows

2 / 20,375

2 / 19,834

两边都有创建模板/主题研究流程，但内容有调整

3. 主流程差异

3.1 Pipeline 定义

原skill 的核心链路是：

Source Document → Create Project → Template Option → Strategist → [Image_Generator] → Executor → Post-processing → Export

本项目 skill 的核心链路是：

Source Document → Create Project → Template Option → Strategist → [Image_Generator] → Executor → SVG Review Gate → Post-processing → Export

本项目新增的 SVG Review Gate 是最核心的结构性优化。它把「生成完成」和「可以导出」之间切出一个强制审查层，解决原skill 中容易出现的几个问题：

  • SVG 技术检查通过，但用户还没看过最终效果就被导出；

  • 图片、图标、占位区域在浏览器预览中不可靠；

  • 页面内容和 design_spec.md 大纲不一致；

  • 导出命令过早执行，导致修复成本被推迟到 PPTX 之后；

  • 后处理会改写 SVG，导致原始问题被遮蔽。

3.2 阻塞检查点数量

原skill 只有 Step 4 的 8 项确认是核心阻塞点，Step 3 默认自由设计，Step 7 直接进入后处理导出。

本项目明确有三个阻塞点：

  1. Step 3 模板选择；

  2. Step 4 8 项确认；

  3. Step 7 最终 SVG 审查批准。

这明显降低了 agent 代替用户做关键决策的风险。尤其是 Step 7：PPT 的最终视觉质量和素材适配属于用户判断，不应该只由脚本通过/失败决定。

3.3 Step 3 模板选择

原skill：

  • 默认自由设计，不询问用户；

  • 只有用户明确提模板、风格或询问模板时才读取 layouts_index.json；

  • 如果匹配强，可以给一句非阻塞提示；

  • 模板复制示例直接使用 cp。

本项目：

  • Step 3 是 DECISION REQUIRED；

  • 用户未明确表达模板意图时必须停下来确认；

  • 必须读取 references/interactive-checkpoint-guidelines.md；

  • 交互标题、prompt、选项固定为：

    • 模板选择

    • 请确认本次 PPT 是使用现有模板，还是采用自由设计。

    • 使用现有模板 / 自由设计

  • 在用户选择前，必须先列出相关模板候选并给出一个专业推荐；

  • 如果用户已经说过「不使用模板/自由设计」，可早退，不再浪费 token 查询模板索引。

改善点：

  • 避免 agent 静默选择自由设计，尤其适合企业汇报、政府材料、学术答辩等强模板场景；

  • 推荐和选择在同一个 checkpoint 内完成，减少用户来回；

  • 固定交互文案，降低不同执行环境的风格漂移；

  • 通过早退规则控制 token 成本。

代价：

  • 比原skill 多一个阻塞点；

  • 对快速草稿型任务来说会更慢。

3.4 Step 4 Strategist

原skill：

  • 读取 references/strategist.md；

  • 必须完成 8 项确认；

  • 输出 design_spec.md 和 spec_lock.md；

  • spec_lock.md 是执行锁，Executor 每页重读。

本项目：

  • 同样要求 8 项确认，但更强调「一个 bundled confirmation decision」；

  • 必须使用交互工具时，用统一的 8 项确认卡；

  • 固定标题、prompt 和选项：

    • 8项确认

    • 请确认以下 8 项设计参数（可直接使用推荐值）：

    • 确认全部推荐（推荐） / 我想调整部分参数

  • 不输出 spec_lock.md，而是围绕 design_spec.md 和后续 review gate 建立约束。

改善点：

  • 本项目把交互体验标准化，避免把 8 项确认拆成多个类别卡片，让用户误以为需要逐项填写；

  • 本项目强调 design_spec.md 必须保持英文模板结构，但内容可跟随用户语言；

  • 本项目更重视后续「内容大纲 vs SVG 实际页」的一致性验证，而不是只靠 spec_lock.md 防漂移。

需要注意：

  • 原skill 的 spec_lock.md / 每页重读机制，是一个值得本项目后续评估吸收的点。它对长 deck 防止颜色、字体、图标、节奏漂移很有价值。

3.5 Step 5 Image_Generator

原skill：

  • 如果设计方案包含 AI generation，生成提示词并尝试生成；

  • 失败时重试一次，再标记 Needs-Manual，不中断流程；

  • 命令使用 python3 ... image_gen.py，不强制显式 backend。

本项目：

  • 增加「能力优先」规则：只有后端真实配置可用时才允许自动 AI 生成；

  • 要求先确认是用户显式选择 AI 生成，还是作为资产 fallback；

  • 建议运行 image_gen.py --list-backends 或等效后端探测；

  • Windows/Trae 推荐显式传 --backend <provider>；

  • 明确 .env 只读取 repo root，不支持 .trae/.env；

  • 如果无可用后端，必须切换稳定 fallback，不能盲目尝试随机 provider；

  • 禁止因为图片能力缺失而让页面出现无解释空白区域；

  • 明确「图片生成完成」不等于「已经插入 SVG 且被用户认可」。

改善点：

  • 避免原skill 中「尝试生成失败但继续往下，最后页面有空洞」的问题；

  • 把 AI 图片从「尽力而为」改成「能力探测 + 明确 fallback」；

  • 降低 Windows 环境变量、旧 session 配置导致的 provider 混乱；

  • 把图片是否真正被用到延后纳入 Step 7 审查。

3.6 Step 6 Executor

原skill：

  • 主 agent 生成；

  • 顺序逐页；

  • 每页前重读 spec_lock.md；

  • 全部 SVG 生成后运行 svg_quality_checker.py；

  • 通过后生成 speaker notes。

本项目：

  • 主 agent 生成；

  • 顺序逐页；

  • 每页生成后必须立即自检；

  • 自检必须使用 references/page-diagnostic-output-template.md；

  • 可见症状和根因诊断要分开；

  • 如果页面仍有 blocking review issue，必须当页修完，不能带到下一页；

  • 架构页必须额外读取 references/architecture-slide-rules.md；

  • 使用图标前必须验证存在，只允许一次 exact check 和最多一次 3 关键词 semantic lookup；

  • 如果 Step 5 生成了 AI 图片，Executor 必须确认这些图片被实际引用，或记录生成但未使用的理由；

  • 图标占位符使用时，整体 sign-off 前运行 icon_reference_checker.py。

改善点：

  • 原skill 的质量门槛集中在「全部生成后检查」，本项目把质量控制提前到「每页生成当下」；

  • 避免一口气生成很多页后发现共同错误，返工巨大；

  • 针对架构图、图标、图片引用这些高风险区域增加专项规则；

  • 对 AI 图片从「生成文件」延伸到「实际插入和可见」负责；

  • 明确禁止 PowerShell 重定向写 svg_output/*.svg、notes/*.md、review/*.md，减少编码、换行、截断和不可追踪写入问题。

3.7 Step 7 审查门禁

这是本项目最重要的新增能力。

原skill：

  • Step 7 是 Post-processing & Export；

  • 只要求 Step 6 已完成；

  • 直接依次运行：

    • total_md_split.py

    • finalize_svg.py

    • svg_to_pptx.py

  • 禁止 --only，但没有用户最终 SVG 审批层。

本项目：

  • Step 7 是独立的 SVG Review Gate；

  • 运行统一审查入口：

    • review_manager.py verify <project_path> --compact

  • verify 同时覆盖：

    • review 证据；

    • review/preview_finalized/ 预览源准备；

    • design_spec.md Section IX 与 svg_output/ 实际页一致性；

    • SVG 技术合规；

    • 布局几何；

    • 文本容器溢出；

    • 本地图标引用；

    • 浏览器预览生成；

    • AI 生成图片是否被引用；

    • review/preview_deck.html 生成。

  • 审查结果必须呈现给用户；

  • 用户必须显式批准，才可进入 Step 8；

  • 审批时必须基于 review/preview_finalized/ 和 review/preview_deck.html。

改善点：

  • 把「脚本检查通过」和「用户视觉认可」分开；

  • 把 preview 可靠性作为审批前置条件，而不是让用户看可能缺图/缺图标的预览；

  • 避免 Step 8 的后处理结果被误当成 Step 7 审查源；

  • 技术检查仍锚定 svg_output/ 原始 SVG，防止后处理遮蔽原始问题；

  • 用户审批内容不只是「是否导出」，还包括图片、图标、空白/占位区域是否可接受。

3.8 Step 8 后处理与导出

原skill：

  • Step 7.1/7.2/7.3 直接执行；

  • 命令为 python3 ...；

  • 不允许加 --only。

本项目：

  • Step 8 只有在 Step 7 用户批准后才能开始；

  • 三个命令仍必须单独执行：

    • total_md_split.py

    • finalize_svg.py

    • svg_to_pptx.py -s final

  • 明确 total_md_split.py、finalize_svg.py、svg_to_pptx.py 都会强制检查 SVG Review Gate；

  • 如果失败，必须修 review evidence，而不是绕过门禁；

  • 在主流程中不允许调试用 --only，除非用户明确要求。

改善点：

  • 审查门禁不仅写在文档里，也在导出相关脚本层执行；

  • 降低 agent 忘记等待用户批准就导出的概率；

  • 保持后处理命令的串行可观察性。

4. 执行环境与命令规范优化

4.1 Python 环境

原skill 命令基本使用：

python3 ${SKILL_DIR}/scripts/...

本项目统一要求：

conda run -n ppt-master python ...

Windows/Trae 中进一步要求：

conda run --no-capture-output -n ppt-master python ...

并在首个 Python 命令前设置：

  • $env:PYTHONIOENCODING='utf-8'

  • $env:CONDA_NO_PLUGINS='true'

改善点：

  • 避免 Windows 控制台编码导致中文路径、中文内容、JSON 输出乱码；

  • 避免 conda plugin 在某些环境下干扰启动；

  • 避免 conda activate 在非交互 shell 中状态不稳定；

  • --no-capture-output 能减少 Trae/Windows 中命令输出被吞、被截断的问题。

4.2 工作目录与路径

原skill：

  • 命令常以 ${SKILL_DIR}/scripts/... 或 scripts/... 表达；

  • 项目初始化默认会把日期写入项目目录；

  • 模板复制示例使用 cp。

本项目：

  • 主流程命令必须从 repo root 运行；

  • 使用 repo-relative path；

  • 不切入 skills/ppt-master-enhanced/scripts/；

  • project_manager.py init 后必须复用脚本打印出的真实 project_path；

  • 不允许手动创建 svg_output/、notes/、review/ 等标准目录；

  • 禁止在 Windows/Trae 中使用类 Unix 习惯如 mkdir -p。

改善点：

  • 降低跨平台命令失败；

  • 降低路径猜测导致的导入/导出写错目录；

  • 避免多个日期目录让后续轮次找错项目。

4.3 文件写入方式

本项目明确禁止在 Step 6/7 使用 shell 重定向或 PowerShell 文件写命令写关键产物：

  • >

  • >>

  • Out-File

  • Set-Content

  • Add-Content

  • New-Item

影响范围：

  • svg_output/*.svg

  • notes/*.md

  • review/*.md

改善点：

  • 避免 PowerShell 默认编码、BOM、换行、截断和 escaping 问题；

  • 推动使用 IDE/native edit 或仓库 helper，使改动更可控；

  • review 类文件由结构化状态渲染，不靠手工拼 Markdown。

5. 项目管理与源文件导入优化

5.1 项目命名

原skill 的 project_manager.py 会生成：

<project_name>_<format>_<date>

本项目改成：

projects/<project_name>_<format>

并要求：

  • project_name 必须是英文 slug；

  • 不支持把中文/非 ASCII 作为机器主路径；

  • 创建时间写入 metadata/README，不写入项目路径；

  • 如果项目目录已存在，不猜新路径，必须复用或显式换 slug。

改善点：

  • 稳定路径便于多轮对话、失败重试和 review gate 状态复用；

  • 避免同一项目因为日期或重试产生多个近似目录；

  • 避免中文路径在脚本、PPT 导出、图片引用、浏览器预览中引发兼容问题。

5.2 源文件导入

原skill：

  • 默认要求 import-sources --move；

  • 执行后原文件不再在原位置。

本项目：

  • 默认要求 import-sources --copy；

  • 用户明确要求搬迁时才用 --move；

  • sources/ 是 workflow snapshot；

  • 原始用户文件通常保留；

  • 导入到 sources/ 的文件名必须英文规范化。

改善点：

  • 更安全，不会意外移动用户原始文件；

  • 便于保留原始材料和项目快照两份语义；

  • 英文化归档文件名提升下游引用稳定性。

5.3 命令回执

本项目新增：

  • .runtime/README.md

  • .runtime/command_reports/project_manager_init_last.json

  • .runtime/command_reports/project_manager_import-sources_last.json

  • .runtime/command_reports/project_manager_validate_last.json

  • .runtime/command_reports/project_manager_apply-template_last.json

  • .runtime/command_reports/asset_lookup_last.json

改善点：

  • 如果终端输出被截断或吞掉，可以读取最近一次 JSON 回执；

  • project path 不靠记忆或猜测；

  • 自动化 agent 可以读取结构化结果继续执行；

  • Windows/Trae 输出不稳定时尤其有价值。

6. 新增审查体系

6.1 新增核心文件

本项目独有的审查相关文件：

  • scripts/review_manager.py

  • scripts/review_utils.py

  • scripts/revision_manager.py

  • scripts/revision_utils.py

  • scripts/docs/svg-review.md

  • references/svg-review/README.md

  • references/svg-review/standards.md

  • references/svg-review/playbook.md

  • references/svg-review/quick-reference.md

  • references/svg-review/priority-rules.md

  • references/svg-review/page-type-matrix.md

  • templates/review/review_log_template.md

  • templates/review/fix_task_template.md

  • templates/review/user_confirmation_template.md

  • templates/review/revision_tasks_template.json

  • templates/review/review_index.md

原skill 中没有这一整套 review/revision 体系。

6.2 review_manager.py

本项目 review_manager.py 约 1290 行，提供：

  • init：初始化 review artifacts；

  • sync：同步 review 状态；

  • render：从结构化状态渲染 Markdown；

  • set-page：记录单页审查状态；

  • set-pages：批量记录页面审查；

  • status：查看 gate 状态；

  • repair-focus：输出最短修复队列；

  • next-action：给 agent 最小下一步决策面；

  • verify：统一整 deck 审查入口；

  • approve：记录用户批准并刷新 verify report。

其中 verify 是本项目的关键统一入口，覆盖技术检查、布局检查、图标检查、预览生成、内容大纲一致性、图片引用问责和 review gate 状态。

改善点：

  • 审查状态从零散 Markdown 变成机器可读 review_state.json；

  • Markdown 报告只是展示层，不再作为门禁权威输入；

  • agent 不需要反复重新理解长报告，可直接看 next-action --json；

  • repair-focus 降低修复噪声；

  • approve 自动刷新 verify_report.json，减少批准后状态不一致。

6.3 revision_manager.py

本项目新增结构化修订轮次：

  • create-round

  • scaffold-tasks

  • status

  • set-page

  • prepare-verify

  • close-round

改善点：

  • 用户在最终审查时提出多页修改意见后，agent 不会直接混乱地回到整 deck verify；

  • 修订任务被记录到 review/revision_round.json；

  • 只有当列出的页面不再是 todo / in_progress 时，才允许恢复整 deck verify；

  • ready_for_review 和 approved 被视为 agent 侧已解决状态；

  • prepare-verify 是可选 bookkeeping，不把用户拖进内部流程。

这对实际 PPT 项目很重要，因为最终审查经常不是「通过/不通过」，而是「第 3、6、8 页分别改一点」。原skill 缺少这种结构化修订状态，容易出现漏改、重复改或提前导出的风险。

6.4 P0/P1/P2 规则

本项目明确：

  • P0、P1 阻塞导出；

  • P2 是非阻塞备注；

  • 审批记录后，P2 不阻止导出。

改善点：

  • 避免所有小问题都无限阻塞；

  • 能区分「必须修」和「可记录后放行」；

  • 更符合真实交付节奏。

7. 新增校验器与预览工具

7.1 icon_reference_checker.py

本项目新增图标引用校验器，约 325 行。

能力：

  • 检查 SVG 文件、项目目录或 svg_output/；

  • 支持 --summary-only；

  • 支持 --json；

  • 验证 <use data-icon="library/name" .../> 是否真的存在于本地图标库。

改善点：

  • 原skill 只建议用 ls templates/icons/<library>/ | grep <keyword>；

  • 本项目把「图标存在性」变成可自动验证的门禁；

  • 避免 final/export 时才发现图标缺失或 <use> 不可解析；

  • 配合「一套 deck 只能使用一个 icon library」的规则，减少风格混乱。

7.2 svg_layout_checker.py

本项目新增布局几何校验器，约 350 行。

能力：

  • 检查明显越界、坐标系统异常、布局元素超出画布等问题；

  • 支持 project/file target；

  • 支持 --summary-only 和 --json。

改善点：

  • svg_quality_checker.py 主要看 SVG 技术合规，无法判断很多视觉布局问题；

  • layout checker 提供轻量几何护栏；

  • 与 browser preview 结合，能更早发现卡片、标签、面板出界。

7.3 svg_text_container_checker.py

本项目新增文本容器溢出校验器，约 404 行。

能力：

  • 推断文本和邻近容器/card/background 的关系；

  • 检查文本是否超出容器或过于贴边；

  • 支持 --summary-only 和 --json。

改善点：

  • PPT 转换中最常见的问题之一是文字在 SVG 或 PPT 中溢出；

  • 原skill 仅靠人工和通用 quality checker 不容易捕捉；

  • 本项目把「文字是否装得下」独立成可复查规则。

7.4 preview_svg_deck.py

本项目新增整 deck 浏览器预览生成工具。

改善点：

  • 支持 Step 7 生成 review/preview_deck.html；

  • 用户审批基于统一 HTML，而不是逐个打开 SVG；

  • 结合 review/preview_finalized/，能让图片、图标等预览更可信。

8. 脚本层门禁强化

8.1 finalize_svg.py

原skill 的 finalize_svg.py 主要负责从 svg_output/ 生成 svg_final/，执行图标嵌入、图片裁剪、图片嵌入、文本 flatten、圆角矩形转 path 等。

本项目在此基础上增加：

  • review gate 检查；

  • 如果未批准或存在 blocker，直接阻止后处理；

  • 支持 review-only preview mode；

  • 可输出到 review/preview_finalized/；

  • 复制 SVG 到新目录时，会对本地 asset href 做 rebase，保证换目录后图片路径仍可用；

  • 对 preview mode 和正式 export path 做边界区分。

改善点：

  • 后处理命令不会绕过审查批准；

  • Step 7 的预览不污染 svg_final/；

  • review/preview_finalized/ 是审查用稳定表面，不被误认为最终导出产物；

  • 本地图片引用在复制目录后仍能显示，减少「预览缺图但导出可能没事/或相反」的不确定性。

8.2 total_md_split.py

两边都有 speaker notes 拆分能力。

本项目增加了与 review gate 的配合：在正式 Step 8 前，脚本层会阻止未通过审查/未批准的项目继续拆分导出链路。

改善点：

  • 防止 agent 把 notes split 当成「无害步骤」提前执行；

  • 保持 Step 8 三个子步骤都在审批之后。

8.3 svg_to_pptx.py

两边都有 PPTX 导出入口。

本项目把导出命令纳入 review gate 强制边界：只有审批后才允许 export。

改善点：

  • 最终产物不会早于用户视觉批准产生；

  • 导出失败时能回到 review 状态修复，而不是绕过 gate。

8.4 svg_quality_checker.py

两边都有该脚本，但本项目增加了与图标校验的集成：

  • --check-icons

  • --summary-only

  • --json

  • 可将 quality summary 与 icon summary 组合输出。

改善点：

  • 技术检查和图标引用检查可合并；

  • JSON 输出利于 review_manager.py verify 统一消费；

  • issue 分类更适合 agent 定位。

9. 交互 checkpoint 标准化

本项目新增 references/interactive-checkpoint-guidelines.md，原skill 没有。

它定义了：

  • blocking checkpoint 是「决策确认」，不是开放问卷；

  • Step 3、Step 4、Step 7 固定标题、prompt、选项；

  • 8 项确认必须是一个 bundled confirmation；

  • 其他补充 不能替代主决策；

  • Step 7 审批文案必须覆盖图片、图标、空白区域等实际资产条件。

改善点：

  • 降低 agent 每次临场改写 checkpoint 的不一致；

  • 避免把单一确认拆成多个伪多选，增加用户负担；

  • 用户看到的审批语义更清晰；

  • 方便 AGENTS.md 强制引用 checkpoint wording。

10. 页面生成质量规范优化

本项目新增或强化了多个 reference：

  • references/page-diagnostic-output-template.md

  • references/architecture-slide-rules.md

  • references/svg-review/*

  • references/interactive-checkpoint-guidelines.md

特别是：

10.1 逐页诊断模板

本项目要求每页 SVG 生成后立即 self-review，并区分：

  • 可见症状；

  • 根因诊断；

  • 是否通过；

  • 是否需要当页修复。

改善点：

  • 防止只给「看起来不错」的泛泛自评；

  • 错误不能累积到整 deck 后才爆发；

  • 更适合长 deck 生成。

10.2 架构页规则

本项目要求系统/分层/网络/协同架构页读取 architecture-slide-rules.md。

改善点：

  • 架构图是 PPT 中最容易过密、线条乱、关系不清的页型；

  • 单独规则能约束密度、关系表达和平衡；

  • 适合技术方案、专利方案、系统汇报类 deck。

10.3 SVG Review 标准库

本项目把 SVG 审查拆成：

  • standards；

  • playbook；

  • quick reference；

  • priority rules；

  • page type matrix。

改善点：

  • 不同页型适用不同审查重点；

  • 优先级和修复策略统一；

  • review 不再依赖 agent 记忆。

11. 测试覆盖

原skill 没有 scripts/tests 目录。

本项目新增 8 个测试文件：

  • test_icon_contract.py

  • test_project_manager_apply_template.py

  • test_project_manager_cli.py

  • test_review_gate_status.py

  • test_review_manager_next_action.py

  • test_review_manager_verify.py

  • test_revision_round.py

  • test_runtime_paths.py

改善点：

  • 对图标契约、项目初始化、模板应用、review gate、next-action、revision round、runtime path 都有回归保护；

  • 说明本项目的改进不是只停留在文档规则，而是部分落到了脚本行为；

  • 修改 gate/checker 逻辑时可以先跑小测试，再跑整 deck verify，降低迭代成本。

12. 文档体系优化

本项目新增或强化：

  • scripts/docs/svg-review.md

  • scripts/docs/troubleshooting.md

  • scripts/docs/project.md

  • scripts/docs/svg-pipeline.md

  • scripts/README.md

  • references/svg-review/*

尤其 scripts/docs/svg-review.md 详细说明：

  • per-page self-review；

  • whole-deck review gate；

  • review artifacts；

  • review_manager.py verify 的统一职责；

  • structured revision loop；

  • validation cadence；

  • layout warning 解释；

  • Step 7 preview basis；

  • export gate rule；

  • artifact write rule；

  • svg_quality_checker.py 与 review gate 的边界。

改善点：

  • 把「怎么审」和「怎么修」写清楚；

  • 把 agent 操作和用户操作分离；

  • 把哪些 warning 应修、哪些可能是 checker heuristic 误报写清楚；

  • 降低过度修 SVG 或忽视真实溢出的风险。

13. 模板与资产差异

13.1 本项目的模板侧优化

本项目在模板使用规则上更严格：

  • 图标必须使用 <use data-icon="library/name" .../>；

  • 一个 deck 必须使用一个 icon library；

  • 本地图标使用前要 exact check；

  • asset_lookup.py 提供 chart/icon 定向检索；

  • 模板选择需要先列候选并给专业推荐。

这些改善重点在「模板/图标使用的可靠性」，而不是单纯增加模板数量。

13.2 原skill 独有的模板/图表

原skill 中存在但本项目没有的文件包括：

  • templates/charts/client_server_flow.svg

  • templates/charts/hub_with_described_spokes.svg

  • templates/charts/layered_architecture.svg

  • templates/charts/module_composition.svg

  • templates/charts/pipeline_with_stages.svg

  • templates/layouts/china_telecom_template/*

  • templates/spec_lock_reference.md

这说明原skill 在「模板资产新增」方面有一些本项目尚未吸收的内容，尤其：

  • 中国电信模板；

  • 架构/流程类 chart SVG 模板；

  • spec_lock_reference.md。

建议后续可考虑把这些资产迁入本项目，但要按本项目的 review gate、icon contract、template index 规则重新登记和验证。

14. 原skill 中值得本项目评估吸收的能力

虽然本报告重点总结本项目改善，但原skill 也有几个值得保留或吸收的点：

14.1 spec_lock.md 机制

原skill 要求 Strategist 输出：

  • design_spec.md

  • spec_lock.md

Executor 每页生成前必须重读 spec_lock.md，并按 page_rhythm 应用布局节奏。

价值：

  • 对长 deck 防止上下文压缩导致的颜色、字体、图标、图片策略漂移；

  • page_rhythm 可以抑制每页都变成同一种卡片网格；

  • update_spec.py 可以传播颜色/字体改动到已生成 SVG。

本项目当前用 review gate 和 design_spec accountability 解决很多一致性问题，但 spec_lock 这种执行锁仍可能是有价值的补充。

14.2 update_spec.py

原skill 独有：

  • scripts/update_spec.py

  • scripts/docs/update_spec.md

它用于把 spec_lock.md 中颜色或字体变更传播到已生成 SVG。

价值：

  • 当用户最终要求「整体换色/换字体」时，可以减少手工改 SVG；

  • 适合统一视觉系统的批量修订。

注意：

  • 如果迁入本项目，需要接入 review/revision gate，避免它绕过逐页审查。

14.3 OpenRouter 图片后端

原skill 独有：

  • scripts/image_backends/backend_openrouter.py

价值：

  • 扩展 AI 图片生成 provider；

  • 可丰富 fallback 选择。

注意：

  • 本项目的图片生成规则要求先做能力探测和显式 backend 选择，因此迁入后也应接入 --list-backends / capability check。

15. 风险与取舍

15.1 本项目 skill 的优势

本项目更适合：

  • 企业汇报、正式交付、专利/技术方案、政府/高校材料；

  • 需要用户最终视觉确认的 PPT；

  • 长 deck、多页修订、多轮反馈；

  • Windows/Trae 本地执行；

  • 对图片、图标、布局、文字溢出容忍度低的场景；

  • 多轮对话中需要稳定路径和状态恢复的项目。

15.2 本项目 skill 的成本

本项目也会带来：

  • 流程更重；

  • 阻塞点更多；

  • agent 需要读更多 reference；

  • review artifacts 更多；

  • 小型草稿 PPT 的执行速度可能慢于原skill；

  • 目录中包含 .runtime 和 pycache，体量更大，后续可考虑清理缓存类文件。

15.3 原skill 的优势

原skill 更适合：

  • 快速生成草稿；

  • 默认自由设计不希望被模板选择打断；

  • 依赖 spec_lock.md 做执行锁；

  • 使用新增图表模板或中国电信模板；

  • 需要 update_spec.py 批量改色/改字体。

16. 分模块详细改善清单

16.1 SKILL.md

本项目 SKILL.md 约 427 行，原skill 约 245 行。

本项目新增/强化：

  • Conda 环境硬约束；

  • Windows/PowerShell 执行预设；

  • 英文文件名规则；

  • 稳定项目命名规则；

  • rule semantics；

  • interactive checkpoint source of truth；

  • Step 3 阻塞模板选择；

  • Step 4 交互式 8 项确认；

  • Step 5 图片后端能力预检；

  • Step 6 逐页自检、架构页规则、图标 fallback 规则、图片使用问责；

  • Step 7 独立 SVG Review Gate；

  • Step 8 导出门禁；

  • review preview 依据；

  • P0/P1/P2 export 语义；

  • runtime command reports；

  • next-action / approve 建议。

16.2 project_manager.py

本项目约 907 行，外部约 632 行。

本项目新增/强化：

  • ASCII slug 校验；

  • 英文化导入文件名；

  • 稳定项目目录，不加日期；

  • repo-relative dir 解析；

  • command report 输出；

  • apply-template 子命令；

  • --copy 优先导入；

  • README 中说明 review/source/export 语义；

  • 错误 hint 和 JSON report。

改善点：

  • 更适合多轮 workflow；

  • 避免源文件移动风险；

  • 避免路径漂移；

  • 便于 agent 从回执恢复。

16.3 review_manager.py / review_utils.py

本项目独有，总计约 2500 行级别。

核心改善：

  • review state schema；

  • review log / fix tasks / user confirmation 渲染；

  • page priority；

  • gate blockers；

  • whole-deck verify；

  • preview source build；

  • outline accountability；

  • image accountability；

  • repair focus；

  • next action；

  • approval refresh。

这是本项目从「生成器」变成「交付工作流」的主要原因。

16.4 revision_manager.py / revision_utils.py

本项目独有，总计约 580 行。

核心改善：

  • 多页修订任务结构化；

  • 避免未解决页面进入整 deck verify；

  • 把用户反馈转换成 agent 侧任务；

  • 允许 prepare-verify 作为可选 bookkeeping；

  • 成功 verify 后可自动关闭修订轮。

16.5 asset_lookup.py

本项目独有。

核心改善：

  • chart/icon 搜索走统一脚本；

  • 支持 exact icon check；

  • 支持 JSON report；

  • 限制盲目搜索循环；

  • 比原skill 的 ls | grep 更跨平台、更可追踪。

16.6 notes_manager.py

本项目独有。

核心改善：

  • 支持 upsert-total；

  • 当只更新某页 speaker note 时，不需要手写 PowerShell 或 python -c；

  • 避免破坏 notes/total.md 格式。

16.7 runtime_utils.py

本项目独有。

核心改善：

  • UTF-8 stdio 配置；

  • safe print；

  • JSON report 写入；

  • skill dir / repo root / command reports dir 解析；

  • 跨脚本复用 Windows/Trae 兼容逻辑。

16.8 image_gen.py

本项目约 489 行，外部约 387 行。

本项目新增/强化：

  • 多 .env 加载/拒绝 legacy env path；

  • backend alias；

  • backend probe；

  • --list-backends / capability check 语义；

  • 显式 backend context；

  • provider credential hint。

改善点：

  • 图片生成失败时更可诊断；

  • 避免凭空假设 provider 可用；

  • 更适合多 provider 本地环境。

17. 迁移建议

如果目标是把原skill 的有益内容合并进本项目，建议顺序如下：

  1. 先迁移模板资产：把外部独有的 chart SVG 和 china_telecom_template 放入本项目模板目录，更新 charts_index.json / layouts_index.json，再跑 icon/layout/preview 检查。

  2. 评估引入 spec_lock.md：不要直接替换本项目 review gate，而是把 spec_lock 作为 Step 4 的可选机器执行锁，并让 Step 7 verify 检查它与 design_spec.md / SVG 的一致性。

  3. 迁移 update_spec.py 时接入门禁：批量改色/字体后必须进入 revision loop 或重新 verify，不能直接导出。

  4. 评估 OpenRouter backend：迁入后要接入本项目的 backend capability check 和 .env 规则。

  5. 清理缓存类文件：本项目目录中存在大量 .pyc / __pycache__，如果要作为可发布 skill 包，建议排除缓存，只保留源码、模板、文档和必要 runtime README。

18. 最终判断

本项目 skill 的主要改善不是「多了几个脚本」，而是形成了一个更完整的 PPT 交付控制系统：

  • 前面用模板选择和 8 项确认锁定用户意图；

  • 中间用主 agent 串行逐页生成和当页自检控制质量；

  • 后面用 review gate、preview_finalized、preview_deck、P0/P1/P2、revision round 控制交付风险；

  • 最后用脚本级 gate 防止未经批准的后处理和导出。

因此，如果项目目标是正式 PPT 生产，尤其是需要审查、修订、用户批准和可复现导出的场景，本项目 skill 明显优于原skill。

如果项目目标是快速草稿或模板资产数量，本项目可以继续吸收原skill 的 spec_lock、update_spec.py、OpenRouter backend 和新增模板资产，但应保留本项目已经建立的审查门禁和 Windows/Trae 执行纪律。