name: pdf-finance-parser
description: 解析金融行业 PDF 文档（A股年报、港股财报、美股10-K、招股说明书等）为结构化 Markdown + JSON。专为跨页表格、无边框表格、多级表头、密集数值、多栏排版等金融场景设计。底层调用火山 LAS laspdfparse_doubao 算子做通用解析，再经 6 层金融后处理（HTML 表格解析 / 多级表头 / 跨页合并 / 数值规整 / 财务术语对齐 / 业务规则校验）输出 schema-compliant JSON。
user-invocable: true
metadata: {"openclaw":{"emoji":"📊","skillKey":"pdf-finance-parser","requires":{"bins":["python3"],"env":["LASAPIKEY","TOSACCESSKEY","TOSSECRETKEY","TOSBUCKET"]},"primaryEnv":"LASAPI_KEY","version":"0.3.0","author":"zhuyijun"}}

PDF Finance Parser Skill

金融场景 PDF → 结构化 Markdown + JSON。底层调用火山方舟 LAS 算子 las_pdf_parse_doubao 做通用解析，再经 6 层金融后处理还原为符合 assets/output<em>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

工作流

复制此清单并跟踪进度：

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

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

请选择 PDF 解析模式：

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

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

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

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

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 步：执行解析

.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 必读字段：

| 字段 | 含义 | 处理 |
|------|------|------|
| status | COMPLETED / FAILED | FAILED 时看 error_msg |
| page_count / table_count | LAS 解析的页数 / 表格数 | 对比 GT 检查漏抽 |
| postprocess.merged_table_count | 跨页合并后的表数 | 通常 < rawtablecount 表示有合并 |
| 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 步：结果回复模板

✅ 解析完成

📄 文档信息
- 文件：{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

输出目录结构

{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 层

| 层 | 模块 | 职责 |
|---|---|---|
| 1 | html<em>table</em>parser.py | BS4 解析 LAS 的 <table>，rowspan/colspan 展开为网格 |
| 2 | multi<em>header</em>detector.py | 数 headerrows + 计算每列 columnpath |
| 3 | cross<em>page</em>merger.py | (续) 关键词 + 列结构匹配 → 多张分页表合一 |
| 4 | numeric<em>normalizer.py | 千分位 / (负数) / 万/亿/百万元 / percent / -→null |
| 5 | finance<em>terms</em>aligner.py | statementtype 识别 + group / subtotal / grandtotal 关键词 |
| 6 | finance<em>validator.py | 资产 = 负债 + 权益、Σ明细 = subtotal（best-effort，标 warning 不修值）|

异常处理决策树

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

进阶用法

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

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

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

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

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

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

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

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

与评测脚本对接

# 批量预测（仓库内 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
• 财务术语词表
• 常见财报表格模板