name: bzdocparser
description: 当用户希望上传文件、解析文件、转换为 Markdown、查看解析状态、下载解析结果、通过 MCP 处理 HTTP 文件 URL，或调用 bzdocparser OpenAPI 文档接口时使用此技能。调用任何 OpenAPI 接口前，都需要先确认已经拿到有效的 API Key。

bzdocparser 技能

目标

当用户提到上传文件、解析文件、转换为 Markdown、查看解析状态或进度、下载解析后的 Markdown 或其他结果文件、通过 MCP 处理 HTTP 文件 URL，或者需要通过 HTTP API 直接操作 bzdocparser，而不是只做高层介绍时，应使用这个技能。

在 MCP 场景下，优先使用以下工具：

• docparse_get_doc_upload_url：为本地文件申请 10 分钟有效的签名上传地址；单个文档最多 200 页
• docparse_parse：提交远程文件 URL 并触发解析；单个文档最多 200 页，超过会被拒绝
• docparse_get_parse_result：根据 document_id 查询解析状态或读取解析结果

这个技能主要帮助 Agent 完成以下三类工作：

• 将本地文档上传到 bzdocparser
• 查询解析状态，或查看某个具体文档的详情
• 在解析完成后下载生成的 Markdown 或其他结果对象

何时使用

当用户有以下任一需求时，应该使用这个技能：

• 上传文件进行解析
• 解析已有文件或文档
• 将受支持的文件转换成 Markdown 或其他解析结果
• 查询文档解析状态，或根据状态判断当前进度
• 下载解析后的 Markdown、预览文件或其他生成结果
• 通过 MCP 的 docparse_get_doc_upload_url 工具上传本地文件
• 通过 MCP 的 docparse_parse 工具提交一个 HTTP 或 HTTPS 文件 URL 进行解析
• 通过 MCP 的 docparse_get_parse_result 工具按 document_id 查询解析状态或结果
• 将 bzdocparser 集成到 Agent、IDE 助手、工作流工具或自动化脚本中
• 直接调用 OpenAPI 文档接口
• 了解上传、查询、下载的正确调用顺序
• 生成 bzdocparser 文档接口的请求示例

何时不要使用

在以下情况下，不应该使用这个技能：

• 用户只想手动使用 Web 控制台，不需要任何 Agent 自动化能力
• 用户只需要 MCP 接入，而且现有 MCP 客户端配置已经可以正常工作

鉴权要求

在调用任何 OpenAPI 接口前，Agent 必须先确认自己已经拥有有效的 bzdocparser API Key。这个 Key 可以来自技能本身已内置的真实配置，也可以来自用户在当前对话中提供的信息。

如果技能本身已经包含真实可用的 API Key，就直接使用，不要再向用户重复索取。

如果技能本身没有真实 API Key，且用户也尚未提供，那么必须明确向用户询问 API Key，并等待用户提供后再继续。

所有 OpenAPI 请求都必须带上这个请求头：

~~~text

Authorization: Bearer <your-api-key>

~~~

推荐调用顺序

建议按以下顺序操作：

提交前先确认单个文档不超过 200 页，超过时不要上传或解析。

1. 如果用户给的是本地文件，先调用 MCP 的 docparse_get_doc_upload_url，拿到 10 分钟有效的 upload_url。
2. 使用 HTTP PUT 把本地文件上传到 upload_url。
3. 将返回的 url 传给 MCP 的 docparse_parse。
4. 使用 MCP 的 docparse_get_parse_result 查询状态，直到文档状态变为 parsed。
5. 如果当前场景不是 MCP，而是直接调用 HTTP API，再使用 POST /openapi/v1/documents、GET /openapi/v1/documents 和 GET /openapi/v1/documents/{id}/proxy/{key} 这一套 OpenAPI 流程。

接口说明

POST /openapi/v1/documents

#### 用途

上传本地文件到 bzdocparser，并将其放入解析队列。

#### 参数

• Header: Authorization = Bearer <your-api-key>
• Content-Type: multipart/form-data
• Form field: file = the local file to upload
• Supported filename extensions: .jpg, .jpeg, .png, .pdf, .doc, .docx, .xls, .xlsx
• Page limit: 单个文档最多 200 页，超过会返回错误

#### 返回内容

成功时，接口返回一个 JSON 包装结构，其中 code = 0，data 为已创建的文档记录。

#### curl 示例

~~~bash

curl -X POST "<BZDOCPARSER_ADDRESS>/openapi/v1/documents" \

-H "Authorization: Bearer <your-api-key>" \

-F "file=@./example.pdf"

~~~

GET /openapi/v1/documents

#### 用途

列出当前 API Key 所属用户的文档，支持筛选，并可用于查看当前解析进度。

#### 参数

• Header: Authorization = Bearer <your-api-key>
• Query parameter: status = empty, uploaded, parsing, parsed, or failed
• Query parameter: source = empty, api, or online
• Query parameter: search = free-text search string
• Query parameter: limit = positive integer, default 20
• Query parameter: page = positive integer, default 1

#### 返回内容

成功时，接口返回一个 JSON 包装结构，其中 code = 0，data = { items, total, page, limit }。

其中每个 item 都是一条文档记录，包含 ID、OriginalName、PreviewKeys、MimeType、SizeBytes、PageCount、Status、Source、ResultKeys、ErrorMessage、CreatedAt、UpdatedAt 等字段。

#### curl 示例

~~~bash

curl "<BZDOCPARSER_ADDRESS>/openapi/v1/documents?status=parsed&source=api&search=invoice&page=1&limit=20" \

-H "Authorization: Bearer <your-api-key>"

~~~

GET /openapi/v1/documents/{id}

#### 用途

在已知文档 ID 的前提下，获取单个文档的详细信息。

#### 参数

• Header: Authorization = Bearer <your-api-key>
• Path parameter: id = the target document ID

#### 返回内容

成功时，接口返回一个 JSON 包装结构，其中 code = 0，data = { document }。

当 Agent 需要获取某个已知文档的最新状态、预览文件 key、结果文件 key 或其他元数据时，应使用这个接口。

#### curl 示例

~~~bash

curl "<BZDOCPARSER_ADDRESS>/openapi/v1/documents/<document-id>" \

-H "Authorization: Bearer <your-api-key>"

~~~

GET /openapi/v1/documents/{id}/proxy/{key}

#### 用途

下载某个生成后的对象或派生对象，例如最终 Markdown、预览 PDF，或被引用的资源文件。

#### 参数

• Header: Authorization = Bearer <your-api-key>
• Path parameter: id = the target document ID
• Path parameter: key = the exact object key to download

#### 如何选择 key

• 如果要下载生成后的 Markdown，使用 ResultKeys。
• 如果要下载预览文件，使用 PreviewKeys。
• 如果 Markdown 中引用了图片或附件对象，则使用对应资源的 object key。

这个 key 必须来自之前的列表接口或详情接口返回结果，不能自己猜。

#### 返回内容

这个接口返回的是文件流字节，而不是 JSON 包装结构。

响应中通常会带有 Content-Type、Content-Length、Content-Disposition 等文件相关响应头。

#### curl 示例

~~~bash

curl -L "<BZDOCPARSER_ADDRESS>/openapi/v1/documents/<document-id>/proxy/<key-from-ResultKeys-or-PreviewKeys>" \

-H "Authorization: Bearer <your-api-key>" \

-o document-result.md

~~~

返回结构与结果处理

• 成功的 REST 响应统一使用 { "code": 0, "data": ... } 这样的包装结构
• 失败的 REST 响应会返回非零 code，并在 data 中给出可读错误信息
• 代理下载类接口返回的是文件流，以及 Content-Type、Content-Disposition 等文件响应头
• 列表和详情接口中的解析失败信息可能会被脱敏，不要向用户承诺能看到原始后端堆栈或内部错误细节

Agent 使用规则

• 没有真实 API Key 时，不要调用 OpenAPI 接口
• 如果技能本身已经包含真实 API Key，就直接使用，不要再次向用户索取
• 如果技能和当前对话里都没有 API Key，要明确要求用户提供，而不是简单告诉用户无法继续
• 如果用户给的是本地文件，在 MCP 场景下优先使用 docparse_get_doc_upload_url，而不是要求用户自己构造 multipart 请求
• 如果文档超过 200 页，要明确提示用户不要调用 docparse_get_doc_upload_url 或 docparse_parse
• 上传前，要再次和用户确认目标文件与目标地址
• 下载前，要再次和用户确认目标结果文件与下载地址
• 如果用户给的是 HTTP 或 HTTPS 文件地址，而不是本地文件，应优先使用 MCP 的 docparse_parse 工具
• 通过 docparse_get_doc_upload_url 拿到 upload_url 后，应使用 HTTP PUT 上传原始文件
• 当用户已经拿到 document_id 并希望查看结果时，优先使用 MCP 的 docparse_get_parse_result 工具
• 在文档状态变成 parsed 之前，不要尝试读取 Markdown 结果
• 在 MCP 场景下，如果需要直接拿到解析后的 Markdown，优先使用 docparse_get_parse_result 工具
• 在 HTTP API 场景下，下载生成的 Markdown 或相关资源时，优先使用 proxy 接口作为标准入口
• 如果解析仍在进行中，要明确告诉用户当前在等待什么
• 保持请求流程简洁，不要引入与当前任务无关的 bzdocparser 功能

预期输出

使用这个技能时，Agent 应帮助用户达成以下结果之一：

• 一次成功的上传请求
• 一次清晰的文档状态查询
• 一次成功的 Markdown 或结果文件下载
• 对“为什么缺少 API Key”或“为什么还没有解析完成”的简洁说明