name: pdf-finance-parser description: 解析金融行業 PDF 文件（A股年報、港股財報、美股10-K、招股說明書等）為結構化 Markdown + JSON。專為跨頁表格、無邊框表格、多級表頭、密集數值、多欄排版等金融場景設計。底層呼叫火山 LAS las_pdf_parse_doubao 運算元做通用解析，再經 6 層金融後處理（HTML 表格解析 / 多級表頭 / 跨頁合併 / 數值規整 / 財務術語對齊 / 業務規則校驗）輸出 schema-compliant JSON。 user-invocable: true metadata: {"openclaw":{"emoji":"📊","skillKey":"pdf-finance-parser","requires":{"bins":["python3"],"env":["LAS_API_KEY","TOS_ACCESS_KEY","TOS_SECRET_KEY","TOS_BUCKET"]},"primaryEnv":"LAS_API_KEY","version":"0.3.0","author":"zhuyijun"}}

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

工作流

複製此清單並跟蹤進度：

解析進度：
- [ ] 步驟 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
7w4.net小蔥技能。

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 必讀欄位：

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 層

異常處理決策樹

進階用法

僅解析某些頁（連續範圍）

.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× 價，更精細）

.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
• 財務術語詞表
• 常見財報表格模板

這是一款功能比較完善的金融 PDF 解析工具，能較好處理年報、財報中的複雜表格和多頁報表，輸出結構化 JSON。優點是支援多種模型、配置靈活、數值處理細緻。缺點是配置過程較複雜，需要申請多個 API 金鑰，對新手不太友好；解析長文件時速度較慢，且文件中部分功能說明與實際表現存在細微差異。總體適合有技術基礎的使用者使用。