laiye-adp-document-processing

---
name: laiye-adp-document-processing
description: "通过来也 ADP MCP 处理本地文件、HTTP(S) 文件 URL 或 Base64：上传文件，解析 PDF、图片和 Office 文档，抽取中国票据、海外发票、采购订单及中国卡证字段，运行自定义抽取，并查询用户已有的异步任务。用户要求 OCR、文档结构化、票据或证件识别、发票验真、批量抽取，或需要将本地文件转换为可处理 URL 时使用；文档类型明确时直接使用专用抽取工具，不要默认先做通用解析。处理调用默认使用同步模式；只有用户明确指定异步时才创建异步任务。"
---

# 来也 ADP 文档处理

将 `Laiye-ADP` MCP 工具作为唯一执行内核。此 Skill 负责选择工具、控制费用、管理文件和解释结果；不要自行复刻 HTTP 请求、认证、隐藏的 OOTB `app_id` 或服务端处理逻辑。

本协议按 `@laiye-adp/mcp` v0.1.4 的 22 个真实工具编写。实际 `tools/list`、当前服务响应和控制台配置始终高于本文件中的静态说明；如果工具面发生变化，停止并报告版本差异，不要猜测工具名或参数。

## 不可违反的规则

1. **只走 MCP。** 不要绕过 Connector 直接调用 ADP OpenAPI，也不要把 `ADP_API_KEY` 写入提示词、工具参数、日志或回答。
2. **只执行最小充分工具链。** 文档类型明确时直接调用对应专用抽取工具；不要为了“先看看”而默认先调用 `parse_document`，再调用另一个计费工具。
3. **本地文件必须先上传。** 本地路径、`file://` 和 WorkBuddy 暴露的本地附件路径必须先调用 `upload_temporary_file`，再把成功响应中的 `data.download_url` 传给解析或抽取工具。
4. **远程 URL 不重复上传。** 可访问的 `http://` 或 `https://` 地址直接作为 `file`；绝不要把远程 URL 传给 `upload_temporary_file.chunk`，当前实现会把它误当作 Base64。
5. **认证不等于无限消费许可。** 用户明确要求处理某个文件或批次时，视为授权每个文件执行一次最小必要的处理调用；新增第二种计费处理、扩大批次或重跑结果不明的任务前，必须说明原因并取得确认。
6. **保留可追踪状态。** 保存每个文件的 `data.id`、`data.download_url`、`data.task_id`、`accept_language` 和最后状态。批量部分失败时逐文件报告，不能宣称整批成功。
7. **以响应事实为准。** 同时检查 MCP 错误、顶层 `code/message/tips` 和 `data.status`。HTTP 成功不代表业务成功，也不要根据自然语言错误消息臆造结果。
8. **默认同步。** 解析和抽取默认传 `wait=true`；只有用户明确要求异步处理时才传 `wait=false`。大文件、复杂文档或批量任务本身不构成切换异步的授权。
9. **结果完整保真。** 默认逐项输出 MCP 在目标结果载荷中实际返回的全部字段、数组项和嵌套值，不得按“重要性”筛选，不得省略空值，不得合并同名或相似字段，也不得改名、翻译、归一化或推导新值。只有用户明确指定字段子集或要求摘要时才可缩减。

## 调用前决策顺序

在第一次工具调用前依次确定：

1. 用户需要全文/版面，还是明确字段。
2. 输入是本地路径、`file://`、HTTP(S) URL 还是 Base64。
3. 文档类型和地区是否足以选择一个专用工具。
4. 是单文件还是批量，账户套餐是否已知。
5. 用户是否明确指定异步；未指定时使用同步，并确认最多会触发多少次计费处理。
6. 用户是否明确限定字段子集或要求摘要；若没有，按 MCP 结果完整输出，并保留原始字段名、顺序与层级。

如果文档类型歧义会改变工具、价格或结果，不要通过两个计费工具试错；先用已有上下文判断，仍无法判断时向用户提出一个简短问题。用户本来就要求完整阅读或类型未知时，才使用 `parse_document`。

## 文件输入路由

| 输入 | 必须执行的动作 |
|---|---|
| 本地绝对路径、以 `./`、`../`、`.\\`、`..\\`、`/` 或 `\\` 开头的路径 | 调用 `upload_temporary_file({chunk: <原路径>})`，读取 `data.download_url` |
| `file://` URL | 同上；不要直接传给解析/抽取工具 |
| 裸相对路径，如 `invoice.pdf` | 先解析成明确的本地路径再上传；当前 MCP 会把裸相对路径误当 Base64 |
| HTTP(S) URL | 直接作为目标处理工具的 `file`，不要上传 |
| Base64 或 data URL | 单次处理时直接作为目标工具的 `file`；需要复用时可上传一次，但上传后的文件名固定为 `chunk` |

调用 `upload_temporary_file` 时：

- 每次只传一个文件，并且**只传 `chunk`**；不要传 `application_id` 或 `sharing_scope`。
- 仅当 `code` 表示成功且 `data.download_url` 存在时继续；不要自行拼接 URL。
- 将返回地址视为任务中间产物，尽快处理，不承诺永久有效。
- 批量上传技术上可并发，但 MCP 和上传路由都没有独立并发 SLA。文档处理流水线默认最多 **10** 个并发；接近 50 MB 的文件保持 **1～2** 个上传并发，避免客户端和服务端整文件读入内存。

处理上传、格式和区域差异前，读取 [文件输入与上传协议](references/file-input-and-upload.md)。

## 工具选择

| 用户意图或文档类型 | 默认工具 | 选择规则 |
|---|---|---|
| 完整阅读、OCR、版面、表格、阅读顺序、坐标，或类型未知 | `parse_document` | 已知为票据、订单或卡证且只要字段时不要先解析 |
| 中国大陆发票、交通票、财政票据等 | `extract_china_invoice` | 支持多票据和可验真票种；只报告响应实际返回的验真结论 |
| 普通海外发票/收据，需要标准解析链或 OCR 中间结果 | `extract_global_invoice` | 标准版，默认用于非低延迟场景 |
| 海外发票/收据，重视低延迟或批量吞吐 | `extract_global_invoice_fast` | 跳过 OCR、直接 VLM；不要承诺 OCR 结果 |
| 泰国、越南、印尼等东南亚发票，尤其需要 WHT 字段 | `extract_sea_invoice_fast` | 东南亚高速版 |
| 采购订单；销售订单仅按工具当前描述尝试 | `extract_purchase_order` | 不要用于普通合同或装箱单，除非用户接受弱保证 |
| 明确的中国卡证 | 对应 `extract_*` 卡证工具 | 必须严格匹配证件类型，不要用相近证件试错 |
| 已知自定义应用 `app_id` | `execute_custom_extract_app` | 直接执行，不必先列举 |
| 只知道自定义应用名称 | `list_custom_extract_apps` 后再决定 | 当前 v0.1.4 存在过滤缺陷；必须验证返回项，不能猜 `app_id` |
| 已有异步 `task_id`，查询进度 | `query_task` | 仅状态 1/2 继续轮询；其他未知状态按协议漂移处理 |
| 已知任务成功但尚未取得完整结果 | `get_result` | 如果 `query_task` 已包含完整结果，不要重复调用 |

完整的 22 个工具、卡证映射、输入参数和已知 v0.1.4 契约边界见 [工具路由与契约](references/tool-routing-and-contracts.md)。

## 标准工作流

### 远程 URL 或 Base64 单文件

1. 选择一个最小充分的处理工具。
2. 将 URL 或 Base64 作为 `file`。
3. 默认使用 `wait=true`；直接校验并读取结果。
4. 用户未明确要求字段子集或摘要时，完整返回目标结果载荷，不做主观筛选或合并。

### 本地单文件

1. 调用 `upload_temporary_file`，只传 `chunk`。
2. 校验 `code` 和 `data.download_url`。
3. 将该 URL 传给一个目标处理工具。
4. 不要因后续处理失败而自动重新上传；已有 URL 仍可用时复用它。

### 大文件或批量任务

1. 默认将每个文件作为独立状态单元，记录文件名、URL、工具、`task_id`、语言和状态。
2. 用户未明确指定异步时，逐个使用 `wait=true` 完成处理；不要仅因文件大、复杂或数量多而自动切换异步。
3. 只有用户明确指定异步时，才使用 `wait=false` 创建任务，并从实际响应的 `data.task_id` 取值。
4. 异步模式下，以 2 秒开始，按 2、4、8、15 秒上限退避调用 `query_task`；遵守服务端 `Retry-After`，不要高频轮询。
5. 创建任务与查询任务时使用相同的 `accept_language`，否则可能切换到不同区域域名。
6. 状态 1/2 继续；状态 4 停止轮询并读取结果；状态 5/6 立即停止；状态 0 或其他未定义状态只做有限次数复查，持续异常时按协议漂移停止。
7. `query_task` 已返回完整 `data.extraction_result` 或 `data.doc_recognize_result` 时直接使用；否则状态 4 后调用一次 `get_result`。
8. 达到用户允许的等待时间仍未完成时，返回 `task_id` 和最后状态，不要把仍在运行写成失败，也不要重新创建任务。

### 自定义抽取

1. 用户已提供可信 `app_id` 时直接调用 `execute_custom_extract_app`。
2. 用户只提供应用名称时，调用一次 `list_custom_extract_apps`，要求名称或 ID 精确匹配，并检查返回的应用类型。
3. 当前 v0.1.4 的列表工具固定请求 `app_type=0`，后端定义该值为系统预设而非用户自定义。未找到明确的用户应用时，停止并请用户从 ADP 控制台提供 `app_id`；不要选取相似名称或隐藏 OOTB ID。

## 参数规则

- `file`：只传 HTTP(S) URL 或 Base64；不要传本地路径或 `file://`。
- `wait`：默认 `true`；只有用户明确指定异步时才传 `false`。
- `timeout_seconds`：同步调用限定在 1～900 秒，默认 300。它只是 MCP 客户端 HTTP 超时，不会取消已被服务端接受的处理任务。
- `with_rec_result`：仅抽取工具会转发。高速工具不返回 OCR 解析结果；`parse_document` 本身返回解析结果，不要依赖该参数改变行为。
- `file_name`：当前 v0.1.4 虽在 Schema 中公开，但没有被转发；不要依赖它保留扩展名或改变识别。
- `accept_language`：`zh` 使用中国区，`en` 使用全球区。异步创建、查询和取结果必须保持一致。
- 全球区本地文件是上传前置门：`upload_temporary_file` 不接收 `accept_language`，当前 Connector 默认也未注入 `ADP_ACCEPT_LANGUAGE=en`。只有已确认 Connector 进程配置该环境变量时才上传；否则停止并请用户配置全球区 Connector，或提供可直接传给目标工具的 HTTP(S)/Base64。不要试传，也不要给上传工具添加不存在的参数。
- 不传 Schema 未公开的参数。高速海外接口的 `enable_multi_ticket` 当前未由 MCP 暴露，不要发明该参数。

## 积分与权限边界

- 不要仅因一次明确的文档处理请求会消耗积分而重复询问；该请求已授权每个输入执行一次最小必要调用。
- 调用第二个处理工具、扩大用户未指定的批次、重跑成功任务，或重跑“请求可能已被服务端接受但响应丢失”的任务前，必须先确认。
- 不要把“已连接 API Key”解释为允许无限调用，也不要把新用户每月 100 免费积分换算成固定页数；不同工具每页费率不同。
- 当前 MCP 没有积分余额查询工具。不要调用或声称存在 `adp credit`，也不要推断当前余额；需要时引导用户在 ADP 控制台查看。
- 解释文档解析或国内票据费用前，读取下方计费说明：解析关闭印章识别为 0.5 积分/页，开启后合计 1 积分/页；票据抽取为 0.8 积分/页，发票验真成功另收 0.5 积分/次。不要把“没有独立验真 MCP 工具”理解为验真免费，也不要将一份多页发票按页重复计算验真次数。
- 费率、免费额度、处理并发和区域规则见 [积分、认证与服务限制](references/billing-auth-and-limits.md)。控制台和实际扣费记录优先。

## 输出协议

1. 读取原始 OpenAPI 包装体：顶层通常是 `code/message/tips`，结果位于 `data`；不要套用旧文档中的顶层 `task_id/status` 示例。
2. `parse_document` 读取 `data.doc_recognize_result`；抽取工具读取 `data.extraction_result`；异步 ID 读取 `data.task_id`。
3. 默认完整输出目标结果载荷中的每个字段和数组项。普通字段完整保留 `field_key`、`field_name`、`field_values` 及响应中存在的其他属性；表格字段完整保留 `table_values` 的所有行、列、单元格及其元数据；解析结果完整保留每页及其嵌套结构。
4. 保留 MCP 的原始字段名、字段顺序、数组顺序、嵌套层级、重复项、`null`、空字符串、空数组和空对象。不要把多个字段合成一个展示项，也不要因值为空、置信度低或看似不重要而删除。
5. 展示格式可以使用 JSON 或无损 Markdown，但不得改变结果语义。字段较多时分段或分批继续输出，不能用省略号、“其余字段略”或总结替代未展示内容。
6. 输出前核对源结果与最终展示：顶层字段数量、字段数组项数量、表格行列数量和分页数量必须分别一致。若 MCP 返回 25 个字段，最终回答必须可逐项核对到 25 个；无法完整展示时明确报告技术限制，不得宣称已完整输出。
7. 只有用户明确列出字段子集或明确要求摘要时才可缩减；缩减时说明这是按用户要求筛选，不要暗示它是 MCP 的完整结果。
8. 对每个文件标记 `成功`、`失败` 或 `结果不明`。部分成功必须列出失败项和观察到的 `message/tips/status`。
9. 文档、下载 URL、证件号和银行信息均按敏感数据处理。完整保真要求适用于目标解析/抽取结果，不要求额外回显临时下载 URL、认证信息或用户未要求的传输元数据。

## 错误、重试与停止

- 缺少 `ADP_API_KEY`、`Accessor not found`、401/403：停止，让用户在 Connector 中重新授权；不要在聊天中索要 Key。
- 400/422、格式不支持、文件超限或类型不匹配：修正输入或更换正确工具；不要原样重试。
- 状态 5/6：停止并返回服务端原因；不要继续轮询或自动新建任务。
- 429：遵守 `Retry-After`。只对明确未受理的调用做一次退避重试；批量仅重试失败项。
- 查询类 GET 出现临时网络或 5xx 错误：退避后最多额外重试一次。
- 上传失败：MCP 客户端不自动重试，后端内部已对部分异常最多尝试两次。Agent 额外重试最多一次，并说明可能生成新的文件 ID；不要整批重传。
- 解析/抽取 POST 超时、断连或 5xx 且没有拿到 `task_id`：将结果标为不明。接口没有幂等键，可能已经处理并扣费；不要盲目重提，先取得用户确认。
- 同一错误经过允许的有限重试仍失败时停止，不要静默切换到另一个计费工具。

处理失败或异步结果前，读取 [执行、结果与错误协议](references/execution-results-and-errors.md)。

## 明确停止条件

出现以下任一条件时停止调用并说明下一步：

- 缺少文件、URL/Base64 为空、远程 URL 不可访问。
- 文件加密、损坏、类型不支持，或超过当前区域公开限制。
- 文档类型歧义且继续会改变价格或触发额外处理。
- 自定义应用没有精确、可信的 `app_id`。
- Connector 认证失败、权限不足或积分不足。
- 处理请求是否被接受不明，重试可能重复扣费。
- 任务进入失败/取消状态，或有限重试已耗尽。
- 实际工具/schema 与本协议不一致，且无法从当前 `tools/list` 安全确定用法。

## 按需读取的参考资料

- 需要选择工具、核对全部 22 个工具或处理自定义应用时，读取 [工具路由与契约](references/tool-routing-and-contracts.md)。
- 遇到本地文件、Base64、格式/页数/大小或批量上传时，读取 [文件输入与上传协议](references/file-input-and-upload.md)。
- 选择同步/异步、解释结果、轮询或处理错误时，读取 [执行、结果与错误协议](references/execution-results-and-errors.md)。
- 估算积分、决定并发、处理授权或区域认证时，读取 [积分、认证与服务限制](references/billing-auth-and-limits.md)。