PPTX 批注与章节读取器
Overview
把"读 PPT →（按需）按颜色提取批注框 → 按章节归类"这套在控规/用地论证类汇报材料
复核中反复出现的流程固化为可复用能力。核心是一个零依赖的 Python 脚本
（scripts/extract.py），直接解析 .pptx 内部的 XML，提取每页文本、按填充色识别
彩色"批注/意见框"，并把幻灯片按页眉小标签归并为章节。
关键设计：是否读取批注框由用户的提示词决定（见下方"批注框开关"），
不做无谓的彩色框扫描；且完全不依赖 python-pptx（避免联网装库卡死）。
何时使用
- 用户发来一份（普兰宁/城市规划类）.pptx，要求"通读/整理/归纳内容"或"按章节梳理大纲"。
- 用户要求"提取领导意见/批注/橙色方框里的修改意见"。
- 用户要求"把某章节（如必要性、可行性）的每页意见汇总成文字大纲"。
- 需要快速掌握一份几十页汇报材料的章节结构（章节映射）。
批注框开关（按用户提示词决定）
第一步先看用户提示词，再决定是否开启批注框识别：
- 开启（默认，不加
--no-comments）：用户提示词出现「批注 / 意见 / 橙色 /
领导意见 / 审稿 / 修改意见 / 校审 / annotation / comment」等，或明确要求
"提取批注框""看领导改了什么"。开启后脚本会在彩色框文本后标⚠批注框(#颜色)
（命中目标色）或·彩色框(#颜色)（其他颜色，供你甄别非批注的色块，如地图图例）。 - 关闭（加
--no-comments）：用户只要求"整理正文 / 做大纲 / 归纳内容 /
读一遍"，未提及任何批注或意见。关闭后仅输出纯文本与章节，正文更干净。
> 规则：用户没提批注，就不要扫描批注框——既快又避免把地图图例等彩色块误当意见。
使用方法
用任意 Python 3.8+ 运行脚本（本环境可用受管解释器）：
C:/Users/Administrator/.workbuddy/binaries/python/versions/3.13.12/python.exe
基本命令：
# 开启批注框（默认），目标色橙红 #D25A35，容差 60
python scripts/extract.py 文件.pptx
# 仅纯读正文与章节（关闭批注框扫描）
python scripts/extract.py 文件.pptx --no-comments
# 写入文件 + 同时产出 JSON（便于程序化后处理）
python scripts/extract.py 文件.pptx --out 报告.txt --json
# 指定章节关键词（最稳的章节判定方式，覆盖启发式）
python scripts/extract.py 文件.pptx --chapter-keywords 项目背景及现状,上位规划,调整必要性,调整可行性,综合结论
# 目标色/容差自定义（如领导用蓝色批注 #0000FF）
python scripts/extract.py 文件.pptx --color 0000FF --tol 50
输出结构（stdout 或 --out 文件）：
# PPTX 提取报告：...
# 总页数：60 ｜ 批注框识别：开 ｜ 目标色 #D25A35 容差 60
## 章节映射
- 项目背景及现状 → 页 3–10
- 调整必要性 → 页 14–17
...
SLIDE 14 [调整必要性]
TEXT: 一桥两山的图老了... ⚠批注框(#D25A35)
TEXT: 落实"一桥两山"...
读取后的常见后续动作
- 章节边界确认：先看"章节映射"，确认目标章节（如"调整必要性"）对应哪些页；
启发式无法识别的整版图页会标(未识别)，此时用--chapter-keywords重跑以锁定边界。 - 批注汇总成大纲：开启批注框后，把目标章节内所有
⚠批注框文本按页摘录，
据此重构精准的一句话副标题与正文要点（见本项目的"必要性章节文字大纲"做法）。 - 回填/整理：将整理结果写入 Markdown 大纲，或按需回填进 PPT 对应页面。
实现要点与边界
- 零依赖：PPTX = zip + XML，直接用
zipfile+ElementTree解析，无需 python-pptx。 - 颜色识别：取形状的
solidFill/srgbClr；主题色schemeClr经theme1.xml
解析为实际 RGB。"彩色框"= 非中性灰、非近白的填充；命中目标色（带容差）即判为批注框。 - 容差：默认 RGB 欧氏距离 60，可覆盖颜色相近的意见框（如 #D25A35 与 #E97132）。
- 章节判定优先级：
--chapter-keywords>--chapter-pattern> 启发式
（取页面最上方、短文本、非彩色框的形状作为页眉）。 - 局限：仅识别"填充色"批注框；若批注用纯文字（无底色）或线条框而非填充框，
会漏判——此时可结合纯文本阅读人工补全。详见references/usage.md。
Resources
scripts/extract.py— 核心提取脚本（零依赖，见上）。references/usage.md— 颜色/容差、章节判定、字段含义等细节与排错。
