PDF 公式增强识别技能
概述
PDF 文本层在复制/通用抽取时，常把公式的上下标压平（x_i→x）、打乱下标字形（i→;）、误认希腊字母与符号（γ→y、φ→cp、θ→0），直接摧毁计算的准确性。本技能用「几何定位 + 知识库身份恢复 + 规范公式模板恢复」，把原料修复为可计算形式。
何时使用
- 从知识库中的 PDF 提取/调用公式，用于计算、出题、判卷、校验等分析场景。
- 发现 PDF 复制出的公式丢失上下标、希腊字母或数字时。
- 建立「某领域 PDF 公式可计算源」的复用管线。
快速开始
# 安装依赖（仅需 PyMuPDF）
pip install pymupdf
# 对一本 PDF 跑增强，输出 output/clean_formulas.md + confidence_report.json
python scripts/run.py "<pdf路径>" --keywords "关键词1,关键词2" --out output
run() 也可作为库调用（需先把 scripts/ 加入 sys.path）：
from run import run
run(pdf_path, kb="auto", pages=None, keywords=["...", ...], out_dir="output")
恢复机制（三层）
- 几何检测（Tier A）：fitz 取字符级字号与坐标；字号 < 0.9×行字号 或 垂直偏移 > 0.45×行字号 → 判为下标/上标，包裹为
_x/_{xy}/^x。 - 符号归一 + 下标身份恢复：套用 OCR 纠错映射；对被包裹的下标，用
symbol_db以「基符号 + 是否含-」推断真实下标。多候选时标?（宁缺毋错），置信度相应下调。 - 规范公式模板恢复：对乱码度 ≥ 10% 的公式行，用
formula_templates按基符号集合匹配，替换为 KB 中的规范公式。正常文本行不会被误替换。
输入 / 输出
- 输入：PDF 路径；（可选）页码范围
pages、关键词keywords用于自动定位公式页、指定kb（语料 id 或"auto"）。 - 输出：
clean_formulas.md（修复后的公式源）+confidence_report.json（下标置信度、未知下标清单）。计算流程改读此文件而非原始 PDF 复制文本。
置信度与学习闭环
- 每次运行输出
confidence_report.json：未知下标 / 歧义下标 / 模板替换行 / 综合置信度（0.30~1.00，未知每项 -0.10、歧义额外 -0.05）。 - 运行时学习：未知下标自动写入该语料
pending_subscripts.json（去重累积）；人工确认后并入symbol_db/subscript_whitelist，下次即自动命中——形成「调用 → 学习 → 更准」的闭环，能力随知识库增长而提升。
目录结构
pdf-formula-repair/
SKILL.md
corpus_registry.json # 语料注册表（pdf <-> kb_dir 映射）
requirements.txt # 依赖：pymupdf
scripts/
engine.py # Tier A：抽取/检测/重建（通用）
knowledge.py # KB 加载 / 归一化 / 下标身份恢复 / 模板恢复 / 校验
run.py # 编排入口
bootstrap.py # 从 MD 自动建 KB
references/
new_corpus_guide.md # 新语料建库指南
knowledge_bases/<corpus_id>/ # 语料知识库（bootstrap 或手动创建）
symbol_db.json # 标准符号 -> 含义（驱动下标身份恢复）
ocr_errors.json # OCR 易混映射（通用基线 + 领域扩展）
subscript_whitelist.json # 合法下标白名单
formula_templates.json # 规范公式模板（图形式公式的精确恢复）
meta.json
pending_subscripts.json # 运行时自动累积的未知下标（学习闭环）
output/ # 运行产出（首次运行自动生成）
扩充语料（自成长）
新增 PDF 及其（可选）MD 基准 → 用 bootstrap.py 从 MD 起草 KB，或手动编写 knowledge_bases/<id>/* → 在 corpus_registry.json 增加一条 → 此后对该 PDF 使用 kb="auto" 即自动选用新 KB。
详细步骤见 references/new_corpus_guide.md。
