Document parsing

Skill sxd007/investigation-ontology/skills/document-parsing

文档结构化解析 — 当用户提供原始文档（PDF/扫描件/图片/Word/Excel）需要提取信息或结构化处理时使用本技能。OCR MCP 的上层编排者，完成类型识别、格式路由、schema 提取、质量评估和版本写入。产出 raw/parsed/*.json，不创建 EV 节点或本体实体。From its SKILL.md

Install

npx -y skills add sxd007/investigation-ontology --skill document-parsing

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

11.0 KB, as published. Nobody here has run it

文档结构化解析

把 raw 文档转换成按文档类型 schema 组织的 parsed JSON，供 evidence-management、ontology 和差异分析类 skill 消费。

激活条件

用户提供 PDF、扫描件、图片、Word、Excel、CSV、文本等原始文档并要求提取信息。
需要重解析低置信度 parsed 结果，或根据人工复核生成新版本。
其他 skill 请求解析某份 raw 文件。
用户通过 /efio:parse 或等价自然语言触发文档解析。

职责边界

只读取 raw 文件并写入 raw/parsed/*.json。
仅 OCR MCP 路径额外写入 raw/ocr_output/*.json，并在 parsed 中记录 source_ocr。
不自动创建 EV 证据节点。
不自动创建本体实体、关系或候选节点。
不在 parsed 中预设实体本体类型；只记录字段、主体名称、账号、角色等结构化事实。

前置检查

执行解析前检查配置：

读取 {配置路径}/team-profile.md。
如果文件不存在、含 [PLACEHOLDER] 或含 PAUSED 标记，先进入 /efio:cold-start 配置向导，完成后继续。
OCR 路径需要读取 {PLUGIN_CONFIG_DIR}/ocr-backend.md；不存在时按 config-templates/ocr-backend.md 的回退规则处理。

详细规则见 ../../config-templates/config-loader.md 和 ../../config-templates/ocr-backend.md。

运行流程

确定文档类型：优先使用调用方指定的 --type；否则按文件名关键词识别；仍无法识别时用 AI 判断；最后兜底为 GENERIC。
选择解析路径：按文件格式路由到 OCR MCP、AI 直接读取或 AI 视觉 fallback。
按 ../../schemas/document-types/ 中的 schema 提取结构化字段。
如果使用 OCR MCP，持久化原始 OCR 输出到 raw/ocr_output/。
做字段级质量评估，决定 parsed 状态。
按版本规则写入 raw/parsed/。
如果结果需要人工复核，打开复核工具；否则只输出可手动打开的复核 URL。

文档类型

支持的类型以 ../../schemas/document-types/ 为准：

类型	典型文档
`INVOICE`	发票、数电票、机动车/二手车发票
`CONTRACT`	采购、销售、服务、租赁、工程、代理合同
`BANK_RECEIPT`	银行转账回单、电子回单、代发回单
`BANK_STATEMENT`	银行流水、对账单、交易明细
`DELIVERY_NOTE`	送货单、签收单、发货单、运单
`PURCHASE_ORDER`	ERP 采购订单、手工采购单、请购单
`REIMBURSEMENT`	差旅、招待、办公、交通等报销单
`PAYROLL`	工资表、薪酬发放表、花名册、代发明细
`APPROVAL`	付款、采购、费用、用款等审批单
`GENERIC`	无预定义格式的兜底文本提取

常用文件名关键词：发票、合同、回单、付款凭证、流水、对账单、明细、签收、送货、发货、收货、订单、采购、PO、报销、费用、工资、薪酬、花名册、审批、申请单、用款。

路由规则

文件格式	解析路径	parsed_by
图片：`.jpg` `.jpeg` `.png` `.tiff` `.bmp`	OCR MCP	`ocr_mcp`
扫描 PDF	OCR MCP	`ocr_mcp`
数字 PDF	AI 直接读取	`ai_direct`
Word / Excel / CSV / 文本 / JSON / XML	AI 直接读取	`ai_direct`
未知格式或 OCR 不可用	AI 视觉 fallback	`ai_vision`

执行 OCR 路径前必须读取 references/ocr-mcp-integration.md。该文件是 OCR 投递、工具参数和错误处理的唯一权威来源。不要在本 skill 内自行发明 HTTP 上传脚本、临时服务器或替代调用方式。

提取要求

普通结构化文档：按 schema 提取字段，每个字段至少保留 value、confidence、raw_text。
CONTRACT：提取封面字段、parties[]、正文 sections[]、表格 tables[]；缺失的标准节写入 missing_sections_warnings[]，不阻断解析。
GENERIC：提取 raw_text 和必要的 raw_text_blocks[]。
不确定字段保留低置信度，不要编造。

CONTRACT 标准节匹配

合同正文按条款标题匹配 section_id；未匹配标题归为 other_clause，原文仍保留。

section_id	标题关键词
`subject`	合同标的、项目内容、服务范围、采购内容
`price_payment`	价格及支付、付款方式、费用与支付、合同价款
`delivery_acceptance`	交付、验收、交货、安装调试、运输
`quality`	质量标准、质保、售后、质量保证
`penalty`	违约、违约责任、赔偿
`dispute`	争议、管辖、仲裁、诉讼
`confidentiality`	保密、商业秘密、机密
`term`	期限、有效期、生效、合同期限
`termination`	解除、终止、提前终止
`force_majeure`	不可抗力
`intellectual_property`	知识产权、版权
`non_compete`	竞业限制、排他
`signature`	签署、签章、签字、盖章
`notices`	通知、送达

缺失检测至少覆盖 subject、price_payment、delivery_acceptance、penalty、dispute、signature。

OCR 输出持久化

仅 parsed_by: "ocr_mcp" 时执行：

从 MCP content blocks 提取完整文本；从末尾 Pages: N 解析页数。
写入 raw/ocr_output/{raw_id}_ocr_v{version}_{timestamp}.json。
OCR output 版本号与 parsed 版本号保持一致。
在 parsed JSON 中写入 source_ocr。
如果 OCR 返回 bbox、layout blocks、elements 或其他结构化坐标信息，必须完整保留到 OCR output；不要因为当前复核模板暂不消费而丢弃。

OCR output 最小结构：

{
  "ocr_id": "OCR-{raw_id}-v{version}",
  "source_raw": "raw/...",
  "engine": "pp_structurev3",
  "engine_endpoint": "<MCP URL>",
  "ocr_at": "<ISO 8601>",
  "output_mode": "detailed",
  "content": "<完整 OCR 文本或 HTML>",
  "page_count": 1,
  "supersedes": null,
  "superseded_by": null
}

质量规则

运行时阈值以本节为准；docs/document-parsing-design.md 仅作设计参考。
full：整体置信度 >= 0.90，且所有必填字段、关键字段置信度均 >= 0.90。
human_review_required：整体置信度在 0.70 ~ 0.89，或任一必填字段、关键字段置信度低于 0.90 但文档仍可读。
quality_too_low：整体置信度 < 0.70，或文档不可读、有效文本过少、重试/换路径后仍无法稳定提取。
金额、日期、主体名称、账号、合同主体等关键字段低于 0.80 时，标为高优先级人工复核；不要降级为自动通过。
合同标准节缺失是风险信号，不是解析失败；记录 warning 后继续写入。

版本规则

首次解析写入 raw/parsed/{DOCUMENT_TYPE}-{raw_id}_v1.json，supersedes: null。
重解析、置信度显著提升或人工修正时写入 v{latest+1}，并设置 supersedes。
被替代版本应更新 superseded_by。
如果新结果与旧版本无实质差异，不创建新版本。
人工复核版本使用 parsed_by: "human_review"，并记录 human_review.corrections[]。

parsed 顶层最小结构：

{
  "parsed_id": "PARSE-INVOICE-ev-010-v1",
  "document_type": "INVOICE",
  "source_raw": "raw/ev-010_invoice.pdf",
  "source_ocr": "raw/ocr_output/ev-010_ocr_v1.json",
  "parsed_by": "ocr_mcp",
  "parsed_status": "full",
  "parsed_at": "<ISO 8601>",
  "supersedes": null,
  "superseded_by": null,
  "fields": {},
  "human_review": null
}

完整格式的设计说明见 ../../docs/document-parsing-design.md；执行时以本 skill 和 schema 文件为准。

复核规则

human_review_required 或 quality_too_low：自动打开复核工具。
full：不自动打开，只在输出摘要中提供复核 URL；用户显式传 --review 时打开。
优先通过 canonical action open_review 打开；没有运行时工具时，操作员可手动运行 scripts/review-server.py。
复核工具默认模板在 templates/parsed-review.html，服务端实现见 scripts/review-server.py。

open_review 的运行时入口由工具或 scripts/review-server.py 提供；../../docs/document-parsing-design.md 仅作设计参考，不是执行前置条件。

输出给用户

解析完成后简要说明：

raw 文件路径。
parsed 文件路径。
OCR output 路径（如有）。
文档类型、解析路径和 parsed 状态。
关键低置信度字段或缺失警告。
下一步：需要时提示使用 evidence-management 注册 EV，或由 ontology 层处理实体/关系。

归档语义与自然语言意图

默认行为：当解析在案件上下文运行（调用时提供或检测到 case_root）时，所有产物视为该案件的产物并写入 ${CASE_ROOT}/raw/ocr_output/ 与 ${CASE_ROOT}/raw/parsed/。解析返回元数据应包含 archived: true、case_root 与写入路径列表 output_paths。
临时/仅查看：如果调用方在 instructions 字段中以自然语言明确表示“仅查看”“不归档”，或显式传入 archive=false / --no-archive，解析器应不归档，产物写入临时目录或 output_dir，并返回 archived: false。
自然语言解析：本 skill 支持可选的 instructions（自由文本）字段以便用户用一句话说明意图。解析器可用轻量关键词/正则映射三类意图：
- 归档到指定案件（从文本中提取 case id，如 “存到案件 C12345”）
- 归档到当前案件（如 “归档到本案”／“存到本案里”）
- 仅查看/不归档（如 “只看一下，不保存”）
优先级规则：显式参数（CLI flags 或 API 字段，如 --case-root / case_root / archive）优先于 instructions；instructions 优先于环境检测（检测到 raw/、meta.json 等案件标记）。若既无显式参数又无法检测到案件根，解析器应提示调用方确认 case_root 或是否仅查看，以避免误写仓库根目录。

解析器在返回结果中应始终包含 archived（bool）、case_root（string|null）、output_paths（array）、以及 inferred_from（"flag" | "instructions" | "env"）以便下游和复核工具核对。