PDF Finance Parser Skill

金融场景 PDF/扫描件 → 结构化 Markdown + JSON。本 Skill 本身不做规则解析，能力全部委托给多模态视觉大模型（Doubao Vision / Qwen-VL 等 OpenAI 兼容端点）；脚本只做调度、IO、结果落盘与评测对接。

设计模式

参考 byted-las-document-parse 的工程范式：

• Tool Wrapper：用多模态 VLM 作为唯一解析引擎，本地代码只是它的 IO 外壳
• Pipeline：渲染 → 调模型 → 解析响应 → 落盘 → 打包
• Inversion：在调用前先与用户确认解析模式（normal/detail）；不私自决定
• 本地无规则：本仓库 scripts/ 下没有版面分析、表格抽取、数值规整规则——这些都让模型做

老版规则代码保留在 _legacy/ 作参考，不在生产路径上调用。

Gotchas

• 必须配置 ARK_API_KEY（火山方舟）或 OPENAI_API_KEY（任意 OpenAI 兼容端点）
• 长报告（>200 页）建议用 --pages 1-50 分段，避免单次调用过长
• 财报表格多为复杂多级表头/跨页延续；遇到不满意结果，先升档到 --parse-mode detail，再考虑改 Prompt
• 扫描件/印章/手写：交给模型 detail 模式，不要本地做 OCR 预处理
• API QPM 有限，多页文档脚本会自动退避重试；不要并行 spawn 多个进程

工作流

复制此清单并跟踪进度：

解析进度：
- [ ] 步骤 0：确认解析模式（normal / detail）
- [ ] 步骤 1：确认虚拟环境就绪
- [ ] 步骤 2：调用 parse（一次到底）或 submit + check-and-notify（异步分离）
- [ ] 步骤 3：检查 meta.json.failed_pages
- [ ] 步骤 4：按"结果回复模板"汇报

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

向用户展示并询问：

请选择 PDF 解析模式：

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

推荐：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 命令验证：API Key 是否就绪、调用哪个 endpoint、用哪个模型。后续命令复用 .venv/bin/python3。

第 2 步：执行解析

同步模式（推荐，单文档/小批量）：

.venv/bin/python3 scripts/skill.py parse \
  --input \x3Cpdf_or_image_path> \
  --output \x3Coutput_dir> \
  --parse-mode normal

• stdout 输出一行 JSON：{"status":"COMPLETED","task_id":"...","output_dir":"...","page_count":N,"table_count":N,"preview":"..."}
• stderr 输出过程日志（渲染进度、模型调用、重试等）

异步分离模式（长文档/Agent 不阻塞）：

# 提交
.venv/bin/python3 scripts/skill.py submit --input \x3Cpdf> --parse-mode detail
# 返回 {"task_id":"...","eta":"..."}

# 检查（自动轮询直到终态）
.venv/bin/python3 scripts/skill.py check-and-notify --task-id \x3Cid> --output \x3Cdir> --poll

异步模式下，每页解析结果落入 \x3Coutput_dir>/pages/p{N}.json，可以增量恢复。

第 3 步：检查 failed_pages

meta.json 必读字段：

第 4 步：结果回复模板

✅ 解析完成

📄 文档信息
- 文件：{filename}
- 页数：{page_count} | 表格：{table_count}
- 模式：{parse_mode} | 耗时：{wall_time}s

📁 输出
- Markdown：{output_dir}/output.md
- JSON：{output_dir}/output.json
- 每页结果：{output_dir}/pages/
- 评测可用：{output_dir}/output.json（符合 assets/output_schema.json）

⚠️ 注意（若有）
- 第 X 页解析失败：{reason} → 建议 `--parse-mode detail --pages X` 单独重跑

输出目录结构

{output_dir}/
├── output.md                # 合并后的 Markdown（按页拼接）
├── output.json              # 结构化 JSON（评测脚本读取此文件）
├── meta.json                # 元信息（耗时、模式、失败页、模型版本）
├── pages/                   # 每页独立结果（断点恢复用）
│   ├── p1.json
│   ├── p1.md
│   └── ...
├── images/                  # 渲染出的页图（可选，--save-images）
└── run.log                  # 详细日志

异常处理决策树

进阶用法

仅解析某些页

.venv/bin/python3 scripts/skill.py parse --input \x3Cpdf> --output \x3Cdir> --pages 1-10,15,20-25

强制使用 detail 模式

.venv/bin/python3 scripts/skill.py parse --input \x3Cpdf> --output \x3Cdir> --parse-mode detail

切换模型

.venv/bin/python3 scripts/skill.py parse --input \x3Cpdf> --output \x3Cdir> --model doubao-1.5-vision-pro
# 或 qwen-vl-max / qwen2.5-vl-72b-instruct

与评测脚本对接

# 1. 把多份样本跑过去
for pdf in samples/documents/*.pdf; do
  doc_id=$(basename "$pdf" .pdf)
  .venv/bin/python3 scripts/skill.py parse \
    --input "$pdf" --output "samples/outputs/$doc_id" --parse-mode normal
done

# 2. 一键评测对比 GT
python3 ../../evaluation/scripts/run_eval.py \
  --pred_dir samples/outputs \
  --gt_dir ../../evaluation/gt_templates/annotated \
  --report_dir ../../evaluation/reports

重要约束

1. 不要在本 Skill 写规则解析代码 — 表格/版面/数值识别全部交给模型；本仓库 scripts/ 只允许出现：CLI / API client / IO / Prompt 模板
2. 不要修改原始 PDF：只读
3. 不要做数值"创意修正"：原文 1,234 → 输出 1234（去千分位），但不要根据上下文猜测
4. 保留可追溯性：每个 cell/block 必须带 source_page；坐标信息可选，依模型是否返回

参考资料

• 命令参数详解
• API 与提示词约定
• Prompt 模板说明
• 配置说明
• 常见问题 FAQ
• 输出 JSON Schema