PDF Finance Parser Skill#

金融场景 PDF → 结构化 Markdown + JSON。底层调用火山方舟 LAS 算子 las_pdf_parse_doubao 做通用解析，再经 6 层金融后处理 还原为符合 assets/output_schema.json 的业务 JSON（含 value/unit/source_page/validation）。

设计模式#

• Engine + Post-process 解耦：LAS 是通用解析引擎（黑盒），金融业务规则是独立后处理层，引擎可替换、业务可独立迭代
• Pipeline： 输入归一化 → LAS submit/poll → HTML 表解析 → 多级表头 → 跨页合并 → 数值规整 → 财务术语对齐 → 业务校验 → schema-compliant 输出
• Inversion：调用前先与用户确认解析模式（normal / detail）；不私自决定
• Best-effort 校验：业务规则违反时标 warning 而非修改原值；保留可追溯性

Gotchas#

• 必须配置 LAS_API_KEY（火山方舟 LAS）
• 本地 PDF 上传 LAS 必须先经过 TOS（火山对象存储），所以也必须配置 TOS_ACCESS_KEY / TOS_SECRET_KEY / TOS_BUCKET
• 若 TOS 桶 region 不是 cn-beijing（LAS 默认 region），需要 export TOS_REGION="<region>" 单独指定（tos:// 协议跨 region 由 LAS 解析）
• TOS 对象 key 不能含中文字符（LAS 后端 URL parser 不接受），本 skill 已在 tos_uploader.py 做 ASCII sanitize
• LAS 并发限制 1 QPM，多文档批跑会自动退避；不要并行 spawn 多个进程
• 长报告（>200 页）建议用 --pages 1-50 分段
• 财报跨页表格（"(续)" 标志）由后处理层 cross_page_merger.py 自动合并；想关掉后处理传 --no-postprocess

工作流#

复制此清单并跟踪进度：

text

解析进度：
- [ ] 步骤 0：确认解析模式（normal / detail）
- [ ] 步骤 1：环境就绪（venv + env.sh 凭证）
- [ ] 步骤 2：执行 parse-las
- [ ] 步骤 3：检查 meta.json.postprocess + output.json.validation
- [ ] 步骤 4：按"结果回复模板"汇报

第 0 步：确认解析模式（必须先执行）#

text

请选择 PDF 解析模式：

| 模式   | 说明                                          | 价格      |
|--------|-----------------------------------------------|-----------|
| normal | 默认，单次推理，速度更快，适用于结构清晰的文档 | 0.02 元/页 |
| detail | 深度分析，对复杂表格/扫描件/印章精度更高       | 0.04 元/页 |

推荐：A股/港股标准年报选 normal；财报附注、合并报表跨页、扫描合同选 detail。

• 用户未明确指定 → 默认 normal

第 1 步：环境就绪（仅首次）#

bash

cd {skill_directory} && \
  (test -d .venv || (python3 -m venv .venv && \
   .venv/bin/pip install -r ../../requirements.txt)) && \
  .venv/bin/python3 scripts/skill.py info

info 命令验证 VLM 配置（仍用于 v0.2 fallback 路径的健康检查）。

首次使用必须先填好 env.sh —— 把 LAS_API_KEY / TOS 凭证替换成你自己的值。 框架会在 skill 目录自动加载 env.sh，无需手动 source。

第 2 步：执行解析#

bash

.venv/bin/python3 scripts/skill.py parse-las \
  --input <pdf_path | http(s)://... | tos://bucket/key> \
  --output <output_dir> \
  --parse-mode normal

• stdout 输出一行 JSON： {"status":"COMPLETED","task_id":"...","page_count":N,"table_count":N,"postprocess":{...},"preview":"..."}
• stderr 输出过程日志（TOS 上传、LAS submit/poll、后处理进度、validator warnings）
• 默认开启金融后处理；传 --no-postprocess 跳过（通用文档场景）

第 3 步：检查 meta.json + output.json.validation#

meta.json 必读字段：

字段含义处理statusCOMPLETED / FAILEDFAILED 时看 error_msg``page_count / table_countLAS 解析的页数 / 表格数对比 GT 检查漏抽postprocess.merged_table_count跨页合并后的表数通常 < raw_table_count 表示有合并postprocess.validation_warning_count业务规则不一致计数> 0 时看 output.json 的 tables[].validation``wall_time_seconds端到端耗时评测对比用

output.json 关键 sub-field（v0.3 新增）：

• tables[].statement_type： balance_sheet / income_statement / cash_flow / equity_change
• tables[].declared_unit：从表头声明文本中识别的单位（如 "百万元"）
• tables[].column_paths：每列多级表头展平的 path（如 "本集团 / 2026年3月31日(未经审计)"）
• tables[].source_pages：跨页合并后的源页号数组
• tables[].validation：业务规则校验结果（warnings 列表）

第 4 步：结果回复模板#

text

✅ 解析完成

📄 文档信息
- 文件：{filename}
- 页数：{page_count} | 表格：{table_count}（合并后 {postprocess.merged_table_count}）
- 模式：{parse_mode} | 耗时：{wall_time}s

📁 输出
- 业务 JSON：{output_dir}/output.json（符合 assets/output_schema.json）
- 整篇 Markdown：{output_dir}/output.md
- LAS 原始响应：{output_dir}/result.full.json
- 单页 markdown：{output_dir}/pages/p{N}.md

⚠️ 注意（若有）
- 业务规则 {N} 处不一致：查看 output.json.tables[].validation.warnings

输出目录结构#

text

{output_dir}/
├── output.json          # ★ 金融业务 JSON（cells 含 value/unit/source_page/validation）
├── output.md            # 整篇 markdown（≈ result.md）
├── meta.json            # task_id / wall_time / postprocess 摘要
├── result.md            # LAS 原始 markdown（表格为 HTML <table>）
├── result.full.json     # LAS 完整响应（含 detail[].text_blocks / bbox）
└── pages/
    ├── p1.md            # 单页 markdown（评测 / 对比用）
    ├── p2.md
    └── ...

金融后处理 6 层#

层模块职责1html_table_parser.pyBS4 解析 LAS 的 <table>，rowspan/colspan 展开为网格2multi_header_detector.py数 header_rows + 计算每列 column_path3cross_page_merger.py(续) 关键词 + 列结构匹配 → 多张分页表合一4numeric_normalizer.py千分位 / (负数) / 万/亿/百万元 / percent / - →null5finance_terms_aligner.pystatement_type 识别 + group / subtotal / grand_total 关键词6finance_validator.py资产 = 负债 + 权益、Σ明细 = subtotal（best-effort，标 warning 不修值）

异常处理决策树#

现象来源处理LAS_API_KEY 未配置env.sh 缺失或未加载检查 skill 目录下 env.sh 是否存在、值是否非占位符TOS_BUCKET 未配置TOS 凭证缺失同上；如桶在非 LAS region，再 export TOS_REGIONNoSuchBucket / 404桶名拼错 / region 不一致用 clawhub auth whoami 或 TOS 控制台确认桶 region，更新 TOS_REGIONUrl.InvalidTOS key 含特殊字符 / 跨 region 拉不到tos_uploader.py 已 sanitize；若仍出现，检查 TOS 桶是否在 LAS regionLAS task 持续 RUNNING 不返回单次大文档已自动退避；超过 max-poll-attempts (60×30s) 仍未返回 → 拆分页范围validation_warning_count > 0业务规则不一致看 output.json.tables[].validation.warnings；不阻塞流程，best-effortUrl.Invalid: invalid url tos://... 含中文中文路径未 sanitize已修，若复现请上报

进阶用法#

仅解析某些页（连续范围）#

bash

.venv/bin/python3 scripts/skill.py parse-las \
  --input <pdf> --output <dir> --pages 1-10

LAS 仅支持连续页范围（start_page + num_pages），不支持 1,3,5 离散页。

强制使用 detail 模式（2× 价，更精细）#

bash

.venv/bin/python3 scripts/skill.py parse-las \
  --input <pdf> --output <dir> --parse-mode detail

跳过金融后处理（通用文档场景）#

bash

.venv/bin/python3 scripts/skill.py parse-las \
  --input <pdf> --output <dir> --no-postprocess

只生成 result.md / result.full.json / pages/，不生成 output.json。适合非金融场景或想观察 LAS 原始输出。

与评测脚本对接#

bash

# 批量预测（仓库内 evaluation/scripts/）
python3 evaluation/scripts/run_lasbench_predictions.py \
  --images-dir <dataset>/images --out-dir <pred_dir>

# 一键算指标
python3 evaluation/scripts/run_omnidocbench_eval.py \
  --gt <gt.json> --pred-dir <pred_dir> --out <report.json>

# 渲染 HTML 报告
python3 evaluation/scripts/render_omnidocbench_report.py \
  --input <report.json> --output <report.html>

重要约束#

1. 业务层与解析层解耦：金融后处理只接受 LAS 已结构化的输入；不要在后处理里塞 VLM 提示词 / 渲染逻辑
2. 不修改原始 PDF：只读，TOS 上传也是只读复制
3. 不做数值"创意修正"：原文 1,234 → value=1234（去千分位 + 按声明单位归一化到 yuan），但不做上下文猜测
4. 保留可追溯性：每个 cell 带 source_page，跨页合并表带 source_pages[]
5. 业务规则 best-effort：不一致只标 warning，不改写 value；评测层负责打分

参考资料#

• 命令参数详解
• API 与提示词约定
• 配置说明
• 常见问题 FAQ
• 输出 JSON Schema
• 财务术语词表
• 常见财报表格模板