扫描版草药手册 OCR+蒸馏
一、使命与定位
把一本扫描影印、无文字层、页边带手写批注的中医草药手册（如《中草药手册》），加工成：
- 可检索的结构化草药数据库；
- 保留手写批注的蒸馏版读书笔记；
- 带安全标注的验方/附方清单。
核心难点：
- 无文字层：必须渲染成图再读取；
- 手写批注：传统 OCR 无法识别，必须靠视觉模型分离「印刷正文」与「手写批注」；
- 图文混排：每味药常配植物线描图，需忽略图、提取文。
边界
- ✅ 做：文字提取、结构还原、手写批注识别、附方整理、安全标注、数据库输出、读书笔记。
- ❌ 不做：给出可直接照方自用的处方建议；替代执业中医师辨证；宣称疗效。
- 🚫 医疗安全红线：本书所有内容仅供文献研究/学习参考。任何实际应用必须在具备资质的执业中医师指导下进行。 含毒性/濒危药材者严禁自行使用。
二、何时调用
用户说类似：
- "帮我把这本扫描版草药手册 OCR+蒸馏"
- "这本中草药手册有手写批注，帮我整理成库"
- "提取这本草药手册里的附方/验方，并标出哪些有毒"
- "把这本带批注的医书做成 CSV/JSON"
- "扫描医书 / 影印本草 / 草药手册 / 验方版 / 手写笔记"
输入形态：扫描 PDF、影印本、手机拍的草药手册页、带手写批注的图片。
三、执行流程（决策树）
给定草药手册文件(PDF/图片)
│
▼
[1] 判定文字层 → scripts/detect_text.py
│
┌────┴─────┐
有文字层 无文字层（常见）
│ │
│ [2] 渲染页面 → scripts/render_pages.py
│ │
│ ▼
│ [3] 视觉读取（Read 工具读 PNG）
│ 分离：印刷正文 vs 手写批注
│
▼
[4] 结构还原：章 → 节 → 药 → 附方/验方
│
▼
[5] 安全标注：对照 references/safety_herbs.md
│
▼
[6] 输出（按用户需求选）：
A. 草药手册蒸馏笔记（医学版）
B. 草药数据库 CSV/JSON（参照 references/herb_schema.md）
C. 附方/验方清单（含批注来源页）
四、每步详解
步骤 1：判定文字层
- 运行
scripts/detect_text.py <pdf_path>。 - 若任意一页字符数 > 50，视为有文字层，可直接文本提取；
- 否则按无文字层处理，进入渲染流程。
步骤 2：渲染页面
- 运行
scripts/render_pages.py <pdf_path> --pages ... --out ...。 - 草药手册正文页文字偏小，建议 scale=1.8–2.0；封面/目录可用 scale=1.4。
- 一本 ~682 页的书不必全渲染，优先选：
- 封面、编写说明、目录/凡例（定位全书骨架）；
- 每章/每节代表页 2–3 页；
- 含手写批注的代表页；
- 书末索引、附方汇编页（如有）。
- 通常 30–60 张 PNG 即可构建全书结构，再按需补读。
步骤 3：视觉读取与分离
- 用 Read 工具读取渲染后的 PNG。
- 关键指令：把页面拆成两部分输出：
1. 印刷正文：原书印刷文字，保持原文繁/异体、旧制剂量；
2. 手写批注：页边、行间、字间的红色/蓝色/黑色手写内容，标注位置和颜色（如可行）。 - 参考
references/vision_prompts.md中的标准 prompt。 - 视觉读取会漏字、误识繁异体；涉及精确剂量或毒性药材时，必须提醒用户人工复核。
步骤 4：结构还原
草药手册典型结构：
上篇 总论（可选）
下篇 各论
第一章 预防药
贯众 [页码]
牛筋草 [页码]
...
第二章 气管炎防治药
棉花根 [页码]
...
每味药条目字段：
正名、别名、特征、产地、加工炮制、性味、
功能、主治、用量、附方、参考、来源页
从目录还原「章-节-药名-页码」骨架，再按页码补读正文。
每味药条目按 references/herb_schema.md 拆字段。
附方/验方应单独成表，字段包括：方名、组成、用法、主治、来源药名、来源页、批注。
步骤 5：安全标注
对照 references/safety_herbs.md 扫描每味药及附方组成：
- 含剧毒药材（如砒霜、生川乌、生草乌、马钱子、巴豆、斑蝥等）
- 含重金属矿物药（如朱砂、雄黄、轻粉、铅丹、白降丹等）
- 含濒危动物药（如犀角、虎骨、穿山甲、麝香等，按现行法规标注）
- 妊娠禁忌（如三棱、莪术、水蛭、虻虫、麝香、斑蝥等）
- 需炮制减毒（如附子、半夏、天南星、白附子等）
- 外用专药（注明不可内服）
剧毒、重金属、濒危方子单列"高风险附方目录"，不进入常规推荐池。
步骤 6：输出
A. 蒸馏笔记
按以下结构产出：
1. 头部元信息（书名、页数、来源文件、处理日期、版本说明）；
2. 全书概述（上/下篇结构、药物总数、附方总数）；
3. 章-节-药大纲；
4. 核心观点/体例特点；
5. 原文摘录（≤150 字/段，标页码）；
6. 手写批注精选（标注页码、位置、内容）；
7. 行动清单（建议人工复核的点、建议生成的下一步产物）；
8. 边界与安全提醒。
B. 草药数据库
CSV/JSON，字段见 references/herb_schema.md。
C. 附方/验方清单
CSV/JSON，每条附方带：来源药名、来源页、组成、用法、主治、批注、风险标签。
五、质量红线
- 所有引用必须来自所提供页面并标注页码，不得编造。
- 原文引用 ≤150 字/段；超过则改写并标明（paraphrase）。
- 医疗安全红线：绝不输出"可直接照方使用"的建议；任何用药相关结论必须附带"须在执业中医师指导下使用"提示。
- 毒性/濒危强制标注：凡命中 safety_herbs.md 的药材，必须在笔记与数据库中显式标记，不可淡化。
- 区分「书中印刷观点」「手写批注观点」「我的整理/解读」。
- 手写识别有误差，必须声明："手写批注为视觉读取结果，可能存在错漏，关键内容请核对原图"。
六、与相邻 skill 的关系
wuming-medical-book：通用无名/古籍/验方类医书处理。本 skill 是其在《中草药手册》这一特定版式 + 手写批注场景下的特化版；若用户的书是通用验方汇编而非草药手册，优先用wuming-medical-book。book-digest：通用读书笔记。本 skill 的蒸馏笔记是其医学专用加强版。scanned-book-distill：纯视觉读取扫描书。本 skill 在其基础上增加了草药字段、附方提取与安全标注。
七、Resources
scripts/detect_text.py— 判定 PDF 是否含文字层，输出字符数与判定。scripts/render_pages.py— 用 pypdfium2 把页面渲染为 PNG（无需 OCR 引擎）。scripts/build_herb_db.py— 把提取的草药/附方 JSON 列表合并成 CSV/JSON 数据库。references/herb_schema.md— 草药条目与附方条目的字段定义、CSV/JSON schema。references/safety_herbs.md— 毒性药材 / 重金属矿物药 / 濒危动物药 / 妊娠禁忌清单（自动标注依据）。references/vision_prompts.md— 视觉读取标准 prompt，用于分离印刷正文与手写批注。
八、调用惯例
- 先试点：首次对 1 本做完整流程验证质量，再谈批量。
- 主动汇报：长书分块处理时阶段性同步进度，不静默跑完再 dump。
- 不凭记忆：无文本且无图时，立即停止并询问用户提供资料。
- 尊重版权与法规：只摘录必要片段，并遵守现行药品/野生动物保护法规。
