| name | document-parsing |
| description | 当用户提供原始文档（PDF/扫描件/图片/Word/Excel）需要提取信息或结构化处理时，必须使用本技能。 本技能是 OCR MCP 的上层编排者：不要直接调用 paddleOCR-mcp，应先按本技能完成类型识别、格式路由、schema 提取、质量评估、版本写入。 本技能只产出 raw/parsed/*.json，必要时产出 raw/ocr_output/*.json；不创建 EV 节点、本体实体或关系。
|
| origin | efio |
文档结构化解析
把 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"）以便下游和复核工具核对。
相关资料
references/ocr-mcp-integration.md：OCR MCP 上传、调用参数和错误处理；执行 OCR 路径前必须读取。../../schemas/document-types/：文档类型 schema。../../docs/document-parsing-design.md：完整 parsed 格式、版本管理和复核设计。../../config-templates/config-loader.md：配置加载规则。../../config-templates/ocr-backend.md：OCR 后端配置模板。../evidence-management/SKILL.md：消费 parsed 创建 EV 节点。../ontology/SKILL.md：消费 parsed 判断实体类型并创建本体对象。
