wm-report-extract

财报提取

对财报 PDF（年报/半年报/季报）做内容理解：先产出可提取性 meta 文件（这份财报有什么、在哪、质量如何），再根据用户需求做数据提取——要特定内容就提特定内容，要全量就全量提取。无预定义模式，需求驱动；每个提取值可溯源到 PDF 页码与原文。

何时使用

• 「从 XX 年报里提取货币资金、前十大股东」
• 「把这份年报的核心数据全量提取出来」
• 「XX 年报第 N 页说了什么」
• 「深入解读这家公司的年报，需要的数据都拿出来」

不要用本技能

依赖与预期

• 转换阶段需 docling+pymupdf（约 1-2GB，Python 3.10+，实测 docling 2.120.2 / PyMuPDF 1.24.14）；scan/locate/cache 无需。解释器选择：优先 WM_REPORT_PYTHON 指定的解释器，未设置时用 PATH 上的 python3；执行与依赖安装须用同一个已装 docling/pymupdf 的解释器，勿用 managed venv。
• 转换为双轨混合：Docling FAST 全档（版面/叙述/无框线表）+ PyMuPDF find_tables 接管有框线页表格（零幻觉、带单元格 bbox）+ ACCURATE 精修无框线报表页（约 10-24 页）。300 页年报约 6-12 分钟——建议后台运行；--accurate 可全档 ACCURATE（约 30-35 分钟，最高精度档）；sha256 缓存幂等，二次提取秒级命中。
• darwin 上默认 CPU（--device cpu），规避 MPS 内核崩溃。
• 本地已有 docling 模型缓存时默认离线运行（自动设 HF_HUB_OFFLINE，避免 HuggingFace revision 在线检查在网络波动时卡死转换；需更新模型时 unset HF_HUB_OFFLINE TRANSFORMERS_OFFLINE）。

七步流程（必须按序，产物落缓存可审计）

脚本门面（路径按已安装 pack，下同）：

python3 /wm-report-extract/scripts/wm_report.py 

① 获取 + 转换（fetch / convert）

# 经 WinMale 平台查链接并下载（symbol 模式，可选；未接平台请用 --pdf-url 直链）
python3 …/wm_report.py fetch --symbol 601633 --filing-type annual [--report-date 2025-12-31]
# 或直链 / 本地路径
python3 …/wm_report.py fetch --pdf-url https://…/report.pdf
python3 …/wm_report.py convert    # 建议后台：耗时 8-20 分钟

产物：report.md（每个 PDF 页起始处 <!-- page:N --> 标记，表格已转 markdown，文本 NFKC 归一化）、pages.json（含每页竖线/横线统计）、fitz_tables.json（fitz 轨道表格的页内顺序与 bbox）、convert_meta.json。缓存 ~/.cache/wm-report-extract/{sha12}/。

表格来源双轨仲裁（convert 内自动）：有框线页（竖线网格 + fitz 检出 ≥3 行）用 PyMuPDF 表格（数值全部来自页面文本，零幻觉，带 bbox）；无框线/三线表页用 Docling，其中报表页（资产负债/利润/现金流量表）自动 ACCURATE 精修；同页文本相似的纯文本表保留 docling 版（语义结构更好，fitz 版去重抑制）。meta.json 的 tables[].track 标注来源；跨页续表类型只从本合并链链头继承（防类型传染），同类型多条独立物理链各自成表不混源拼接（canonical 给结构分最高链）。

② 内容理解 meta（scan）

python3 …/wm_report.py scan  --summary

meta.json 是后续一切的依据：

• industry_hint：行业探测（bank/automobile/…，特征词+置信度）→ 决定覆盖清单行业扩展组
• document_profile：market/script/accounting/convert_health/novelty 画像；低置信行业保持 industry=null
• filing_kind：annual / q1 / semi / q3 / quarter / prospectus
• chapters 章节树（正文锚点→目录回退）/ sections 子节锚点（from_toc:true 需复核）
• tables[] 全表 schema：headers/单位/期间列/科目样本/续表合并（continued）/类型——类型是提示，headers 才是证据
• priority 优先指引：按 coverage-checklist 通用层+行业层分组给出入口（结构性三表 > 特异签名表 > 锚点区间 > 关键词）
• anomalies[] 异常与降级（异常不中断，是处置依据，见下表）

②½ 方案适配（adapt-plan）

python3 …/wm_report.py adapt-plan  [--result ]

产物：result-*/adapt_plan.json。以报告正文（章节/表标题/行标签）为最高优先级信号，行业组为先验：

• observed_signals / promote_priority / expected_but_missing：内容锚定覆盖与晋升顺序
• coverage_groups：先验 A–I + 行业 X 组（industry=null 时仅通用层）
• q1/q3：完整 MD&A 叙述标 not_applicable
• low_text_page / garbled：给出 --ocr / --accurate 建议

③ 全表 records 确定性预提取（extract-tables）——应提尽提的机制保证

python3 …/wm_report.py extract-tables           # → records.json（秒级）
python3 …/wm_report.py locate  "存货" --records # 按科目行检索（含断词归一匹配）

records.json：每张表每个数据行 → {table, page, type, row_label, label_norm, values[{value,period,header}], unit, headers}。数百页年报产出数千条行级记录，每条可溯源到表+页。三表/摘要等已定型；续表自动继承类型；跨页续表已合并。

④ 结构化分表（materialize-tables）

python3 …/wm_report.py materialize-tables  [--force]

产物：result-{ts}/manifest.json + tables/*.json + gaps.json + promote_candidates.json。Python 只做高置信定型；其余进 generic。表格数据必须优先消费分表文件。

⑤ Agent 定型晋升（type_promote）

读 promote_candidates.json（每张 generic 的 title/headers/前 8 行/type_hint/filing_kind），对照 coverage-checklist 分析意图 决定是否晋升。只输出 confidence=high 的项：

python3 …/wm_report.py apply-promotions  --file promotions.json [--result result-…]

• 按「这张表回答哪个分析问题」晋升，禁止写死品牌/公司名
• 混两类或低置信 → 保持 generic
• 季报不要硬升年报才有的组
• 同类型多张物理表：第一张用稳定 table_id，其余为 {type}_p{page}_i{index}，禁止静默合并

⑥ 质量门（qa-tables，给下游前必跑）

python3 …/wm_report.py qa-tables  [--result result-…] [--verdicts qa-verdicts.json]

• Python：列错位、缺单位、垃圾表头
• Python v2 质量门（对照 PDF 原文）：
  • 勾稽校验：资产=负债+权益恒等、合计=Σ分项（减:项为负、其中:项跳过）、期初+增减=期末、同比%用金额重算——失败记 identity/subtotal/roll/yoy_mismatch（degraded，不删行）
  • 数值存在性：表内每个数字必须真实出现在溯源页 PDF 文本（value_not_on_page；超 30% 整表 demote）
  • quote 回验：行 quote 逐字（NFKC 归一化）存在于溯源页（quote_unverified）
• Agent：语义复核 typed 表（会议议程冒充激励表、利润变动原因冒充海外经营等）→ demote 或 split
• 产物 quality.json；无此文件或未跑 QA，禁止把 typed 表交给分析角色
• status=fail 表示发生过 demote/split；下游仍只消费 verdict=pass 的 typed 表；suspect 数值/quote 进 gaps.json 供复核

⑥½ 独立审核（review-extract）

python3 …/wm_report.py review-extract  [--result ]

• 审核与提取角色分离：审核不改表，只读产物打分
• 硬门：quality.json 存在、叙述 found 必须有 quote+page、required_gaps 必须终态、quote 可回验、画像一致性、年报/半年报三表定型（statement_signature_gap）
• 软门：一季报/三季报三表缺一、demote/split、未 promote 的非噪声 type_hint
• QA：三表行标签须命中科目词；假利润表（公司名当 item）→ demote
• novelty / hard fail 时写 derived/evolution_proposal.json（含 actions、missing_type_signatures、noise_type_hints）；只产 proposal，不自动改规则库

⑥¾ HTML 阅览（render-html，可选）

python3 …/wm_report.py render-html  [--result ] [--out report.html]

• 产物默认：result-*/report.html（单文件自包含，系统字体，可离线打开）
• 只嵌入 quality.json 中 verdict=pass 的表 + gaps / review / QA findings；只读，不在页面改数
• 侧栏按覆盖组导航；三表切换；行点击展开 quote+页码抽屉

质量门不可取消。后续计划 auto-heal（规则化 auto-promote + 行业 gaps 针库 text_scan + 再 qa/review）减少人工 close_*.py，不放宽硬门。

⑦ 按用户需求制定方案 + 执行提取

固定覆盖按 coverage-checklist。清单外 / 定型表覆盖不到的项走 个性化抽取：

python3 …/wm_report.py resolve  --need "合同负债" --need "存货" --write-fields

产物（L2 首选）：result-{ts}/fields/.json + result-{ts}/fields/_batch.json，并回填 result-{ts}/manifest.json -> catalog.fields[]（提供可枚举的 FieldRecord 证据索引；每个数值带页码与 quote，可复核）。0.6.0 起港股 IFRS 三大报表已可定型（简繁签名）；非报表港式表仍可空，convert + resolve 照跑。

L2 传统备选（legacy）：extract-query 仍可用，但它把 value 留空给 Agent（禁止写入 PDF 之外数字），用于需要更复杂“切片级”语义时。

第三方（东财/现货网站）数字 不得 写入 adhoc.json——PDF 没有就是 not_in_pdf；研究包用 L3 Web 另记。

输出形态

• 给人：正文结论 + 关键数字表（每行带页码角标）+ 来源 footer。
• 给 Agent：result-{ts}/manifest.json + adapt_plan.json + quality.json + review.json + 仅 verdict=pass 的 tables/*.json + narratives/*.json + gaps.json。

禁止

• 无 quality.json 就把 typed 表交给下游分析。
• 把 Python type_hint 或未晋升的 generic 当成稳定 table_id。
• 全量提取时跳过 D_mda / C_segments，或把变动原因表只抽成金额。
• 把具体公司品牌名、口号写进 plan 或覆盖清单。
• 编造数值/页码；quote 必须逐字（NFKC 归一化后）来自该页。
• 用第三方数据源（东财/同花顺等）补 PDF 里没有的数——not_found 就是 not_found；不得写入 adhoc.json。
• macOS 上用 --device mps（Metal 内核崩溃）；默认 cpu。
• 港股报告：0.6.0 起三大报表签名/章节锚/行业词已简繁适配；仍定不出的表（港式非报表版式）不要跳过 convert / locate / resolve，改走 L2 个性化抽取。美股/英文报告：锚点库未适配，同样走 L2。

深入参考