Audit Report Checker

审计报告核查

作者：nigo（公众号：逆行的狗） 版本：1.0.0

检查审计报告（财务报表 + 附注），发现勾稽错误、加总错误、文本格式问题。Claude 是主控——负责语义理解（定位报表、理解附注章节、判断列含义、标注表格结构），代码负责确定性算术（求和、核对、reconcile）。两者分工，消除旧工具"硬拆分 + 关键词匹配"导致的系统性误报。

最重要的一条原则：算术绝不手算

LLM 直接做数值加减会算错，且无法复现——审计核查中算错等于致命。所有数值计算，哪怕只是三个数相加，都调用 scripts/calculator.py。AI 只决定"传哪些数""哪个等于哪个"，代码算出结果。

正确做法：

# 从报表/附注提取出数字后，调 calculator 验算
python3 scripts/calculator.py check "113,157,711.68" "113,157,711.68"   # 核对相等
python3 scripts/calculator.py sum "1,234.56 5,678.90 100.00"            # 求和
python3 scripts/calculator.py reconcile "100" "50" "30" "120"           # 期初+增-减=期末

错误做法：

# 心算"流动资产合计 = 货币资金 + 应收账款 + ..."  ← 会算错，且别人无法核验

calculator 支持千分位逗号、括号负数、横线（=0）、全角字符、万元单位，容差默认 0.01，用 round(diff, 6) 避免浮点边界误判。这是上一版已验证有效的原则，保留。

工作流

Step 0 — 选检查深度（scope）

开始前用 question 工具问用户两件事：检查深度（单选）+ 检查类型（多选，可空则按深度档执行）。

三档深度：

用户不选就默认标准。选深度检查时先提示 token 消耗较大让用户确认（128 页报告深度检查可能消耗很多）。

检查类型多选：勾稽 / 横加竖加 / 表注 / 文本 / 格式。用户可自由组合覆盖深度档（多选全部 ≈ 深度检查）。

为什么要分档：审计师多数时候只需快速验证勾稽，无差别深度检查既慢又费 token。scope 让用户知情选择，按需触发。

附注-only 自动调整：若识别到文档只有附注、无四表（如盛屯/博达新材的纯附注 Word），自动跳过报表间/表注勾稽，聚焦附注内勾稽 + 横加竖加 + 文本格式，并告知用户调整了范围。详见后文"附注-only"。

DeepSeek 模型选择（启用 AI 时执行）：标准/深度检查默认启用 DeepSeek 加速（文本错别字、附注表结构标注、warning 二次复核）。涉及 AI 时，问完深度+类型后先选模型，避免 reasoning 模型拖垮批处理：

1. 检查 key 有效性：python3 scripts/ai_worker.py --test-check-key（读 ~/.deepseek/config.json；无 key 则全程走 --no-ai 纯代码）
2. 查可用模型：python3 scripts/ai_worker.py --test-list-models（DeepSeek 503 服务繁忙时可能查不到，可跳过用默认）
3. 用 question 让用户选模型，默认推荐 flash 类模型（非 reasoning，单请求延迟低，适合大批量并发；reasoning 类如 v4-flash 单请求 25s+ 会拖垮批处理）。用户无偏好直接用 flash。
4. 选定后 run_check 加 --model <选定> 传入，或写入 ~/.deepseek/config.json 的 model 字段持久化。

降级原则：DeepSeek API 服务繁忙(503)/限流属外部问题。多次失败时降级 --no-ai（纯代码 L1+scan+词库），文本/标注/warning 复核由 Claude 终审兜底（Step 5 本就要求 Claude 复核，不完全依赖 API）。

Step 1 — 解析文档

python3 scripts/parse_report.py "<文件或目录>" -o <输出目录>

脚本四路自动分流，按文档类型和内容特征选最佳提取路径：

• PDF 文本型（首页文本 > 50 字）→ pdfplumber，数字 100% 精确
• PDF 扫描型 → mineru 云端 API（extract --model vlm），数字需人工复核
• Word 文本表格为主 → python-docx，精确
• Word 图片报表（inline_shapes 偏多）→ mineru 云端 API

Word/PDF 双路（重要）：实际场景大部分是 Word 报告。parse 对同 basename 的 .docx/.pdf 优先 .docx（去重，Word 表格精确无断字）；无 Word 才用 PDF。两路分开处理：

• Word 路（.docx）：python-docx 提取 table 对象→markdown（实测金星90/博达87表全成功）+ 段落文本；章节定位（附注五-N 科目，Word 无固定页码）；table 自动归属 chapter（Heading1 大章节 + Heading2/短文本明细）。伪表格（非 table 对象的制表位排版，少数）AI 兜底。
• PDF 路（.pdf）：pdfplumber + 页码定位（page=N，超链接可点击）。

定位差异：Word 用章节（"附注五-3 应收账款"），PDF 用页码（"第N页"）。result 的 chapter（Word）/ page（PDF）字段区分，export 自动适配。

输出两个文件：

• report.md：全文 markdown，每段用 <!-- SOURCE file="..." page=N method=... --> 标注来源页码和提取路径
• extracted_tables.json：原始二维表格（headers + rows），不做列映射、不做报表分类、不做续表合并

解析层只输出原始数据，报表定位、附注识别、列含义判断全部由 Claude 在后续步骤用语义完成。这是消除旧工具"拆分匹配错误"的核心——parse 层不越界做本该人做的事。提取策略原理见 references/extraction.md。

mineru 是云端 API，数据会上传 mineru.net。审计报告含敏感财务数据，首次走 mineru 路径前要告知用户并获得知情同意。详见 references/mineru_usage.md。

Step 2 — 理解文档结构（语义，不靠关键词）

读 report.md，理解整体结构：

• 编制单位、会计期间
• 报告类型：合并报告（含合并 + 母公司共 8 张表）还是单体（4 张）？通过看是否有"母公司"字样和报表数量判断，不靠硬编码关键词字典
• 四张报表的位置（合并资产负债表/利润表/现金流量表/所有者权益变动表，及母公司版本）及其页码范围
• 合并报告同名报表会重复：合并报告里"资产负债表""所有者权益变动表"等标题通常出现两次——第一次是合并口径、第二次是母公司口径，表头往往都不带"合并"/"母公司"前缀，靠出现顺序（先合并后母公司）和编制单位行区分。两套都要提取，漏掉母公司 4 张表会让母公司层面的勾稽完全缺失。判断方法：同名报表在 report.md 中出现 ≥2 次 → 合并报告，按顺序分别归为合并/母公司。
• 附注章节结构——每章讲哪个科目（如"附注三、货币资金"讲货币资金）
• 是否附注-only（无四表）→ 走附注-only 分支
• 图片报表页检测（重要）：读 report.md 时留意是否有连续多页文本为空白。审计报告中四表（资产负债表等）常被做成图片嵌入 PDF，pdfplumber 对这些页提取为空白（实测盛屯 page 7-16 共10页空白=四表全是图片）。若 parse_report 的 report.md 已标注 <!-- WARNING: ... 为图片/扫描页 -->，直接据此处理；否则自己扫描各页文本量。发现四表区域空白时：
  1. 对该页范围用 mineru 云端 OCR 重新提取：mineru-open-api extract "<报告.pdf>" --pages 7-16 -o <目录> --model vlm --language ch（需先 mineru-open-api auth 配 token，见 references/mineru_usage.md，含数据上传云端隐私提示）
  2. OCR 结果（md）合并回 statements 提取
  3. mineru 不可用时，在报告中明确标注"四表为图片，pdfplumber 未能提取，本次未执行报表间勾稽，建议人工复核或配 mineru token 重跑"——不要假装做了

识别同义科目变体靠语义理解，不做映射表：股东权益 = 所有者权益、股本 = 实收资本、股东权益变动表 = 所有者权益变动表。为什么用语义而不是关键词字典：每遇到一个新报告格式就要加规则，关键词爆炸不可持续；Claude 一次调用就能理解，且能处理变体。

生成 note_map.json（表注勾稽的定位基石，Step 2 必做）：理解附注结构时，一次性生成「科目→附注明细表」精确映射 note_map.json（写入 parse 输出目录）。这是三层分工架构的定位层——Claude 语义定位（准、只做一次、低 token），取数/算术交给代码（DeepSeek locate + calculator）。

为什么定位必须 Claude 做：旧工具靠正则匹配标题 + 页码邻近定位，在①标题格式多样 ②同页多科目 ③续表跨页 上系统性失败（详见 旧报告检查工具_定位研究.md 的 4 大根因）。Claude 一次语义理解就能准确定位到表级别。

格式（{科目: {...}}）：

{"货币资金": {"table_ids": [220], "pages": [16], "field": "期末余额", "formula": "期末余额", "note": "报表数=附注期末余额"},
 "应收账款": {"table_ids": [221,222], "pages": [18,19], "field": "账面价值", "formula": "账面余额-坏账准备=账面价值", "note": "报表数=附注账面价值"}}

• table_ids：该科目附注明细涉及的表 id（附注文件范围，绝不混入资产负债表/利润表等报表表，否则表注勾稽会"自己比自己"）
• field：报表数等于附注哪个字段（直接取，如"账面价值"/"期末余额"）
• formula：取数口径公式（field 取不到时按此运算，如"账面余额-坏账准备"）
• 定位方法（表 name 常为空，靠多重交叉）：科目章节 page 区间 + 该区间内表 page + headers 内容 + 章节实际文字
• 最低覆盖：标准检查至少 8 科目（货币资金/应收账款/应收票据/预付款项/存货/固定资产/营业收入/应付账款），深度检查覆盖全部报表列示科目。subjects_index.json（scan 生成的科目→候选表粗索引）可作为定位参考/校验，但精确定位以 Claude 生成的 note_map 为准

生成 manifest.json（四表提取的结构契约，Step 2 必做）：理解四表在文件里的位置/列布局后，写成 manifest.json（写入 parse 输出目录）。这是三层分工架构的结构契约层——Claude 语义识别结构（准、只做一次），抽数交给 apply_manifest 纯机械执行（零猜测、新格式改 JSON 不改代码）。

自动生成优先：run_check --auto-manifest --auto-note-map 时 DeepSeek 并发自动生成 manifest.json 和 note_map.json（看 sheet 表头/附注表内容判断列布局/科目归属），代码做结构性校验 + 回原文核对降错。自动生成失败或校验大量不过→回退 Claude 手写（有模板库）。

为什么用 manifest 不靠代码猜：天邑列布局(B/E/F) vs Macko(A/C/D) 不同、Macko 母公司 BS 主表/续表列布局不同、续表项目名带空格（"负 债 合 计"）、非标准名（"股东权益合计"）——每遇到一个新格式，代码猜列/猜 sheet/硬编码 ALIAS 都会崩。manifest 把这些差异声明在 JSON 里，apply_manifest 按声明抽数。

格式（详见 references/manifest_template.md，含 4 份报告的 manifest 样例）：

{
  "report_format": "merged_docx | split_xlsx | split_docx | split_pdf",
  "company": "...", "period": "...",
  "files": {"文件名": {"role": "statements|notes|opinion|cover", "loader": "xlsx|docx|pdf|doc"}},
  "statements_map": {
    "合并资产负债表": {
      "source": "文件名", "loader": "xlsx|docx|pdf",
      "sheets": ["sheet名"], "source_table": "表名(docx/pdf按此在extracted_tables定位)",
      "kind": "linear | matrix",
      "item_col": 0, "current_col": 2, "prior_col": 3,
      "field_aliases": {"股东权益合计": "所有者权益合计"},
      "merge_into": null
    }
  }
}

• files.role+loader：分体式文件角色（报表/附注/正文/封面）+ 读取器（xlsx=openpyxl / docx,pdf=读extracted_tables / doc=textutil转）
• item_col/current_col/prior_col：列布局（看 dump 确定，不猜）
• sheets+merge_into：BS 续表/分段合并（同表不同列布局时分两段，merge_into 合并）
• source_table：docx/pdf 时按表名/内容在 extracted_tables 定位四表（表 name 常为空，靠内容匹配"资产总计"+"流动资产合计"=BS）
• field_aliases：项目名标准化（"股东权益合计"→"所有者权益合计"）
• kind: linear|matrix：权益变动表矩阵结构（sheets_main/sheets_prior + value_col）

生成方法：Claude 看每个报表文件的 dump（xlsx 的 sheet 名+表头+前3行 / docx 的 extracted_tables 四表名+列）后手写 manifest（3-5 分钟）。Macko/天邑/巨东/清研的 manifest 已在各自 parse_output 目录，可作为模板。

Step 3 — 提取 statements.json（apply_manifest 机械执行）

用 Step 2 的 manifest.json，调 apply_manifest 纯机械抽数：

python3 scripts/apply_manifest.py <parse输出目录>/manifest.json -o statements.json

apply_manifest 读 manifest 的 statements_map，按声明的 source+loader（xlsx 读 sheet / docx,pdf 读 extracted_tables 按 source_table 定位）+ item_col/current_col/prior_col 抽数，套 field_aliases 标准化项目名，处理 merge_into 分段合并，产出 statements.json。零猜测、零改代码——所有格式差异已在 manifest 声明。

产物格式（与 calculator_rules 匹配）：

{
  "合并资产负债表": {"流动资产合计": {"current": "113,157,711.68", "prior": "..."}, "资产总计": {"current": "...", "prior": "..."}},
  "合并利润表": {...},
  "合并现金流量表": {...},
  "合并所有者权益变动表": {...},
  "母公司资产负债表": {...}, ...
}

字段名必须精确：calculator_rules 按字段名匹配（如 "期末现金及现金等价物余额"），字段名不一致会导致 L1 检查报"缺少必要项目"。提取前先查必需字段清单：

python3 scripts/calculator_rules.py

报表原文项目名与清单不一致时，在 manifest 的 field_aliases 里声明映射（如"股东权益合计"→"所有者权益合计"、"负债和股东权益总计"→"负债和所有者权益总计"），不要改代码。

Step 4 — 代码侧检查（含 scan 代码验算）

python3 scripts/run_check.py <parse输出目录> \
  --statements <parse输出目录>/statements.json \
  --note-map <parse输出目录>/note_map.json \
  --scope <scope> --scan --use-ai -o <parse输出目录>/results.json

说明：

• --statements 和 --note-map 支持相对路径，脚本会优先相对于 <parse输出目录> 解析；如果找不到会给出明确报错。
• 建议命令中写绝对路径或 <parse输出目录> 前缀，避免不同工作目录下的路径歧义。

可选参数（用于提速/跳过已跑过的慢步骤）：

• --max-workers N：DeepSeek 并发数（默认 60）
• --skip-annotation：跳过 AI 结构标注（复用本地 annotations_cache.json）
• --skip-text-ai：跳过 AI 文本错别字/病句检查
• --skip-ai-review：跳过 DeepSeek 对 warning/error 的预复核（默认执行，最终终审仍由 Claude Step5 完成）

脚本执行确定性检查（不依赖 LLM），--scan 必加——它让代码分担横加竖加的粗活，大幅减轻你在 Step 5 的负担：

--use-ai 说明（默认启用）：

• 默认 --use-ai：启用 DeepSeek 并发（4 场景：①文本错别字 ②附注表结构标注 ③表注勾稽+附注reconcile（按 Step2 的 note_map 定位→locate 取数→calculator 比较）④warning 预复核；均批量化 + 并发默认 60）。需 DeepSeek API key + 选定 flash 类模型（见 Step 0）。文本检查（错别字/病句）和表注勾稽取数只有 --use-ai 能自动执行，纯代码扫描覆盖不到。--note-map 不传时默认读 <input_dir>/note_map.json（Step2 生成）。
• 可选 --no-ai：纯代码扫描（无文本 AI 检查），DeepSeek 服务繁忙/无 key 时降级用。此时文本检查只走内置词库，结构标注/warning 复核由 Claude 在 Step 5 手动完成。
  • 代码自动降级点：run_check.py 在 AI 结构标注（run_check.py:2368-2400）、表注勾稽（run_check.py:2533-2562）、文本错别字（run_check.py:2473-2510）、warning 二次复核（run_check.py:2640-2670）四个场景均捕获 API/取数异常，失败时跳过该场景并在 results.json 中生成降级提示，不会中断主流程。
• 模型选择：--model <name> 传入；不传则用 ~/.deepseek/config.json 的 model 字段。优先 flash 类（非 reasoning），详见 Step 0。

执行的检查（按 scope）：

• L1 报表间勾稽：调 calculator_rules.py 四函数，验资产=负债+权益等恒等式
• 页码连续性、公司名一致性、金额单位、错别字词库粗筛
• scan 代码验算（--scan）：
  • 竖加验算：含"合计/小计"行的附注表，代码 sum 明细=合计（排除所有合计/小计/总计行和"其中:"子项）。金星 301 张表能代码验算 64 张，通过的直接记 info（你不用再做这些表）
  • 横加验算：列名匹配已知模式（账面余额-坏账准备=账面价值、期初+增加-减少=期末、原价-折旧-减值=价值）
  • 通过记 info（减负），不平记 warning（可能特殊表结构，需你在 Step 5 用 AI 结构标注复核，区分真错 vs 特殊结构）
  • 额外输出 candidates.json（代码无法判断的变动表/复杂横加表清单，留给你在 Step 5 做 AI 结构标注）和 subjects_index.json（41 科目→附注候选表粗索引，供你在 Step 2 生成 note_map.json 时参考/校验，精确定位以 Claude 生成的 note_map 为准）

输出 results.json，每条结果含：check_type / rule_name / severity / passed / description / expected / actual / difference / source_location / target_location / evidence / page / context / source_file。

定位字段（审计师核对原文用，必填）：

• page：页码（纯数字，如 45）。从 report.md 的 <!-- SOURCE ... page=N --> 注释或附注章节位置获取。
• context：原文摘录（约50字，被检查的那行原文片段），审计师在 Excel 里直接看到原文，不用翻 PDF。
• source_file：由 run_check 自动回填原始报告路径，你写语义检查结果时无需手动填。
• rule_name：用有意义的科目名（如 货币资金年末竖加、存货-原材料横加），不要带 id=N 前缀（id 是解析时的表格序号，对审计师无意义）。