| name | document-parse |
| version | 1.0.0 |
| description | 文档→Markdown 解析入口（输入侧基础设施）——把用户上传的 PDF、图片、Word、PPT 解析为结构化 Markdown，供本套件所有需要读取上传文件的技能调用。支持多解析后端（PARSE.to_markdown 能力槽）并内置降级链。与法律核验对称：法律核验守"出"，文档解析守"入"。触发词：文档解析、解析文档、解析PDF、转Markdown、提取文档内容、OCR、扫描件。 |
文档解析（document-parse）· 输入侧解析入口
本技能是本套件读取上传文件的统一前门。任何需要把用户提供的 PDF/图片/Word/PPT 转成可分析文本的技能，在拿到上传文件后、进入分析或起草之前，先经本技能解析为 Markdown，再把结构化文本交回原技能。
与 /legal-verification（输出侧必过闸门）对称：/legal-verification 守"出"，/document-parse 守"入"。
本技能只负责"把文件变成可读的 md"，不做法律分析、不做内容删改、不臆造文档内容。
0 | 两种调用模式
模式一：自动入口（其他技能调用，默认）
收到上传文件 → 【document-parse入口】→ 选定后端 → 解析为 Markdown
├─ 成功 → 把 md（含表格/公式/正文）交回原技能继续分析/起草
└─ 失败 → 按降级链逐级回退；全部失败则停下报告，不静默兜底
入口为默认、不可静默跳过（与 profile.md「共享护栏 #3」「标准管线」一致）。
模式二：独立解析（用户直接调用）
用户给出文件路径或上传文件并要求"解析/转 Markdown/提取内容"，执行完整解析流程并返回结果，不进入后续法律分析。
MCP 预检
本技能使用 PARSE.* 能力。
执行前读取 profile.md「外部能力后端 / document-parse」的首选配置，并用 MCP.list_tools 探测已连接的解析后端：
- 已配置且可用 → 直接采用
- 未配置但探测到可用后端 → 用 AskUserQuestion 让用户选择，选定后写回 profile.md
- 无外部后端 → 走内置降级链，提示"如需更高精度可配置文档解析后端"
1 | 文件合法性检查
- 类型合法：仅 PDF / 图片(.png/.jpg/.jpeg/.webp/.tiff) / Word(.doc/.docx) / PPT(.ppt/.pptx)
- 文件存在且可访问：本地路径真实存在、指向具体文件
- 不支持的类型直接告知并给替代建议（Excel 另存 PDF / txt 直接读取等）
- 多文件按顺序逐个解析，最后汇总
2 | 按选定后端解析
2A | 外部后端（PARSE.to_markdown）
严格按对应后端 MCP/技能规范调用：
- 上传文件 → 提交解析任务 → 轮询/等待结果（≤2分钟）→ 取解析结果
- 全文取 markdown/text；表格取 blocks.type==table；公式取 type==formula 的 latex；正文取 is_body==true（排除 header/footer/page_number）
- 工具失败即标注降级并进入下一后端
2B | 内置降级（无外部后端时）
| 文件类型 | 降级方案 |
|---|
| 纯文字 PDF | pypdf 提取文字 |
| 扫描件/图片 PDF | fitz 渲染 PNG（dpi=200，横置先 set_rotation(270)）→ Read 多模态识读 |
| 图片 | 宿主 Agent 内置 Read/文件读取工具 |
| Word(.docx) | 宿主 Agent 内置 Read / python-docx 提取 |
| Word(.doc, macOS) | textutil 转 txt 后读取 |
| PPT | 宿主 Agent 内置 Read/文件读取工具 |
走 fitz 视觉降级时，输出必须标注 [视觉降级-待人工复核]。
3 | 按意图提取并交回
| 用户/原技能需要 | 提取方式 |
|---|
| 完整内容 | 全文 markdown，不摘要 |
| 表格 | 仅表格块，还原为标准 Markdown 表格 |
| 公式 | 仅公式块，输出 LaTeX |
| 正文 | 排除页眉页脚页码 |
- 自动入口模式：解析结果落到工作目录（
parsed/<原文件名>.md），交回调用技能
- 解析内容一律来自工具结果，不得用主观总结替代
4 | 降级链
首选外部后端（profile.md 配置）
├─ 失败 → 其他已连接后端（MCP.list_tools 探测）
├─ 失败 → 内置降级：
│ ├─ pypdf（纯文字 PDF）
│ ├─ fitz 视觉（扫描件，标 [视觉降级-待人工复核]）
│ └─ Read 直接读取（图片/Word/PPT）
└─ 全部失败 → 停止，展示错误，请用户提供文本版本
每次降级在输出中标注：[降级提示] {后端}不可用：已回退到 {下一后端}。
执行规则
- 不臆造内容 —— 解析结果只来自工具；无法解析时如实说明
- 不静默兜底 —— 后端失败先按降级链回退并标注，全部失败则停下
- 类型守门 —— 仅 PDF/图片/Word/PPT
- 首选可复用 —— 读 profile.md 首选解析器，未配置问一次并持久化
- 入口不可跳过 —— 其他技能收到上传文件时默认先走本入口（标准管线）
- 保密 —— 解析产物属案件材料，不跨案件泄露
