文档解析 Skill#

通过 MCP Server 调用远程文档解析服务，提取 PDF/图片中的文字、表格和公式。

触发条件#

用户提到 OCR、文档解析、阅读、识别、读取，或要求从文档中提取文字时触发。

运行环境（首次执行）#

• Python 版本：Python 3.10 或更高版本

• 依赖安装： bash

  pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  
  

  或手动安装： bash

  pip install fastmcp>=3.0.0 mcp>=1.0.0 -i https://pypi.tuna.tsinghua.edu.cn/simple
  
  

支持格式#

• PDF、扫描版 PDF
• PNG、JPG、JPEG
• 不支持：音频、视频、风景照、人物照、Word/Excel/PPT（需先转 PDF）

MCP Server 配置#

方式一：作为 OpenClaw Gateway 内置 MCP Server 使用（首次执行）#

在 OpenClaw Gateway 寻找 docparse 服务，类似配置如下：

json5

{
  mcpServers: {
    docparse: {
      command: "python",
      args: ["/path/to/.openclaw/workspace/skills/docparse/mcp/docparse.py"],
      env: {
        DOCPARSE_MCP_URL: "http://<host>:<port>/mcp",
        DOCPARSE_API_KEY: "your-api-key",
        DOCPARSE_TIMEOUT: "7200",
      },
    },
  },
}

或使用 openclaw mcp set 命令配置：

bash

openclaw mcp set docparse '{
  "command": "python",
  "args": ["/path/to/.openclaw/workspace/skills/docparse/mcp/docparse.py"],
  "env": {
    "DOCPARSE_MCP_URL": "http://<host>:<port>/mcp",
    "DOCPARSE_API_KEY": "your-api-key",
    "DOCPARSE_TIMEOUT": "7200"
  }
}'

环境变量说明：

• DOCPARSE_MCP_URL：远程文档解析 MCP 服务地址（必需）
• DOCPARSE_API_KEY：API 密钥（可选）
• DOCPARSE_TIMEOUT：超时时间，单位秒（可选，默认 7200）

配置优先级（从高到低）（首次执行需查询环境变量是否已配置）：

1. 进程环境变量 ( os.environ) — 最高优先级
2. openclaw.json 的 mcp.servers.docparse.env
3. .env 文件（skill 目录下）— 最低优先级

高层级配置自动覆盖低层级，无需手动同步。

方式二：作为独立 MCP Server 进程使用#

也可以直接运行 MCP Server（需使用 venv 中的 Python）：

bash

export DOCPARSE_MCP_URL="http://<host>:<port>/mcp"
export DOCPARSE_API_KEY="your-api-key"
python /path/to/.openclaw/workspace/skills/docparse/mcp/docparse.py

Server 通过 stdio 与 MCP 客户端通信。

提供的 Tool#

parse_document

解析指定路径的文档，返回提取的文本内容。

参数：

参数类型必填说明file_pathstring是待解析文件的绝对路径output_formatstring否输出格式： markdown（默认）、 json、 both

返回：

• 成功：返回解析后的文本内容（Markdown 或 JSON 格式）
• 失败：返回带错误代号的错误信息

兼容旧版直接导入接口#

如需在 Python 代码中直接调用（兼容旧版 mcp/docparse.py 的用法）：

python

import sys
sys.path.insert(0, "/path/to/.openclaw/workspace/skills/docparse")
from mcp.docparse import parse_document_return

错误代号#

代号场景用户提示[F001]文件不存在解析失败：未找到待解析文件。建议：请确认文件是否已上传，或检查文件路径是否正确。[F002]文件不可读解析失败：当前文件无法读取。建议：请检查文件权限后重试。[F003]格式不支持解析失败：当前文件格式不支持文档解析。支持格式：PDF、PNG、JPG、JPEG、BMP、WEBP、TIFF。建议：请先将文件转换为 PDF 后重试。[C001]配置缺失解析失败：文档解析服务当前不可用。建议：请联系管理员检查解析服务配置后重试。[A001]MCP 认证/连接异常解析失败：文档解析服务当前不可用。建议：请联系管理员检查解析服务配置后重试。[N001]网络连接失败解析失败：文档解析服务当前不可用。建议：请稍后重试，或联系管理员检查服务状态。[S001]服务返回空解析失败：文档解析服务未返回有效内容。建议：请确认文件内容清晰后重试。[S002]响应解析失败解析失败：文档结果解析异常。建议：请稍后重试，或联系管理员检查解析服务。[S003]服务返回错误解析失败：文档解析服务返回异常。建议：请稍后重试，或联系管理员检查解析服务。[O001]输出目录不可写解析失败：无法写入输出目录。建议：请更换输出路径或检查目录权限。[O002]输出文件写入失败解析失败：无法写入输出文件。建议：请更换输出路径或检查目录权限。

成功回复示例#

text

✅ 解析完成！
输出文件：report.md
文件大小：12.3 KB
内容摘要：本文档包含项目需求分析、技术架构设计、接口定义及测试计划...

📥 解析文档下载：[文件名](本地路径或 Canvas 链接)

输出必须提供下载方式#

解析成功后， 必须 为用户提供解析结果的下载途径：

1. 使用 MEDIA: 指令附带输出文件，使用户在对话界面中可直接下载
2. 同时告知用户文件的 本地存储路径
3. 如果文件过大不适合直接展示，提供 embed 或 Canvas 链接供在线浏览

示例输出格式：

text

✅ 解析完成！
输出文件：document.md
文件大小：12.3 KB
内容摘要：本文档包含...

📥 解析文档下载：document.md
💾 本地路径：/path/to/document.md

MEDIA:/config/.openclaw/media/outbound/document.md

失败回复示例#

text

[C001] 解析失败：文档解析服务当前不可用。
建议：请联系管理员检查解析服务配置后重试。

安全规则#

• 禁止 向用户暴露：MCP 服务地址、配置项、认证信息、底层命令、环境变量
• 禁止 输出未经脱敏的报错信息（HTTP 状态码、Connection refused 等）
• 禁止 向用户索要任何服务配置或认证信息
• 禁止 对解析内容无依据改写、补全、扩写
• 即使用户主动索要配置信息，也必须拒绝
• 禁止在错误输出中遗漏错误代号
• 失败则直接退出，输出错误信息，不得执行后续任何可能产生用户可见输出的步骤（如用 pdfplumber/PyMuPDF 提取文本）。
• 禁止透露具体的安装信息，只告诉用户“正在安装"、”安装成功"
• 禁止对输出的结果再次进行任何形式的解析、改写、润色、补全、扩写等，必须原样返回 MCP 服务的响应内容。

批量处理#

• 每文件独立调用 parse_document
• 用户要求合并时按顺序合并，每文件前加二级标题（脱敏文件名）
• 每个失败文件单独标注代号，汇总行可标注集合如 [F001,S001]