catomy/ppt_analysis_opt_skill README 风格项目教程

catomy/ppt_analysis_opt_skill 是一个面向 PPT 逻辑分析和优化的 Agent Skill，适合拿已有 .pptx 检查标题是否结论先行、论点是否符合 MECE、断言是否有数据支撑、字号和留白是否稳定。它的产物不是单纯的评分，而是结构化 suggestions JSON、可读分析报告，以及可选的 presentation_optimized.pptx。

项目的核心分工很清楚：代码负责提取 PPT 文本和把修改落回文件，语义判断交给 Claude 或 OpenCode Agent。这样做的好处是不用在本地塞一套复杂 NLP 规则，也能让 Agent 按 SKILL.md 里的金字塔原理、商务表达和版式标准逐页分析。

一分钟看效果：从原稿到优化版文件

本地最小路径只需要 Python 和 python-pptx。如果只是试流程，先准备一份 presentation.pptx，再执行文本提取：

git clone https://github.com/catomy/ppt_analysis_opt_skill.git
cd ppt_analysis_opt_skill
pip install "python-pptx>=0.6.21"
python scripts/extract_ppt_text.py presentation.pptx extracted.json

extracted.json 会包含总页数、每页标题、正文段落、表格、备注、shape 索引等信息。接下来把这些结构化内容交给 Agent，并使用 SKILL.md 内置的分析规范，让 Agent 返回 theme、total_issues、high_priority_issues、suggestions 和 report。

当 suggestions 已经拿到后，可以通过仓库里的 helper 转成修改格式，再写回优化版 PPTX：

python scripts/modify_ppt.py presentation.pptx modifications.json presentation_optimized.pptx

如果你在 Agent 脚本里调用 Python，也可以用 README 里的方式组合：PPTXTextExtractor 提取内容，convert_suggestions_to_modifications() 转换建议，apply_modifications() 应用修改，最后保存为 presentation_optimized.pptx。

为什么它比人工翻页检查稳

人工看 PPT 时，最容易只盯标题或视觉样式，忽略正文论点是否支撑标题。这个 skill 把检查维度写得很细：逻辑结构看结论先行、以上统下、归类分组和逻辑递进；语言表达看完整句、简洁度、专业语气；内容组织看每页 2 到 5 个论点、并列结构和段落完整性；数据支撑看断言是否有具体数字和来源；视觉设计看颜色、对齐、留白和字号梯度。

核心功能拆开看

• PPT 内容提取：utils/text_extraction.py 提供 PPTXTextExtractor，能把标题、正文段落、表格、备注和 shape 元信息整理成 JSON。
• 内置分析规范：SKILL.md 写好了分析任务、问题类型、优先级、输出字段和修改建议质量要求，Agent 按这套规范返回结果。
• 建议格式转换：utils/prompt_template.py 提供 convert_suggestions_to_modifications()，把分析建议转成修改器可读格式。
• PPT 修改落稿：scripts/modify_ppt.py 支持按页码、标题、内容段落、shape 和段落索引替换文本，并默认做样式归一化。
• 稳定定位：修改格式推荐带上 shape_index、paragraph_index_in_shape、nonempty_index_in_shape 和 old_text，减少误替换。

工作原理：Agent 判断，代码落稿

这个项目没有把“好 PPT”的判断硬编码成几个 if 规则。它先把 PPTX 拆成结构化数据，再让 Agent 根据 SKILL.md 的完整规范识别问题。返回的每条建议会带上 problem_type、页码、位置、原文、分析、修改文本、理由、优先级和置信度。

修改阶段更偏工程化。modify_ppt.py 会按建议里的定位信息替换标题或正文段落，同时保留原有格式并执行样式归一化，例如默认字体、标题字号范围、标题单行约束和可选标题颜色统一。对已有完整 suggestions 的场景，Refine Mode 允许只改 modification_suggestion 文本，保留页码和索引字段，避免重新识别问题时把定位弄乱。

仓库结构和开发者接手点

ppt_analysis_opt_skill/
├── README.md
├── SKILL.md
├── references/
│   └── pyramid_principle.md
├── scripts/
│   ├── extract_ppt_text.py
│   ├── modify_ppt.py
│   └── requirements.txt
├── utils/
│   ├── text_extraction.py
│   └── prompt_template.py
└── tests/

开发者接手时，重点看三处：SKILL.md 规定 Agent 怎么分析，utils/text_extraction.py 决定提取出的 JSON 是否足够稳定，scripts/modify_ppt.py 决定修改能不能准确落回 PPT。references/pyramid_principle.md 则是金字塔原理说明材料，适合用来校准分析口径。

推荐使用流程和常用命令

1. 先用 extract_ppt_text.py 把原稿导出成 JSON，确认标题、正文、表格和备注都被提取。
2. 把 JSON 填入 SKILL.md 的 PPT 内容占位位置，让 Agent 输出完整分析 JSON。
3. 检查 suggestions 是否有页码、location、paragraph_index、shape_index 和 old_text。
4. 将 suggestions 转成 modifications，再用 modify_ppt.py 写出优化版 PPTX。
5. 打开 presentation_optimized.pptx，核对标题是否单行、替换是否命中原段落、样式是否统一。

python scripts/extract_ppt_text.py presentation.pptx extracted.json
python scripts/extract_ppt_text.py presentation.pptx - > extracted.json
python scripts/modify_ppt.py input.pptx modifications.json output.pptx

catomy/ppt_analysis_opt_skill 更像一条“先拆稿、再审逻辑、再写回 PPT”的小型流水线。它把金字塔原理、段落定位和 PPTX 修改拆成清楚的接口，让 Agent 负责判断，让脚本负责执行；只要先拿小文件跑通提取和修改，再接入正式演示稿，就能把 PPT 审稿从零散意见变成可追踪、可复用的优化流程。