ahang1598 来也 ADP 文档处理
将 Laiye-ADP MCP 工具作为唯一执行内核。此 Skill 负责选择工具、控制费用、管理文件和解释结果；不要自行复刻 HTTP 请求、认证、隐藏的 OOTB app_id 或服务端处理逻辑。
本协议按 @laiye-adp/mcp v0.1.4 的 22 个真实工具编写。实际 tools/list、当前服务响应和控制台配置始终高于本文件中的静态说明；如果工具面发生变化，停止并报告版本差异，不要猜测工具名或参数。
不可违反的规则
- 只走 MCP。 不要绕过 Connector 直接调用 ADP OpenAPI，也不要把
ADP_API_KEY写入提示词、工具参数、日志或回答。 - 只执行最小充分工具链。 文档类型明确时直接调用对应专用抽取工具；不要为了“先看看”而默认先调用
parse_document，再调用另一个计费工具。 - 本地文件必须先上传。 本地路径、
file://和 WorkBuddy 暴露的本地附件路径必须先调用upload_temporary_file，再把成功响应中的data.download_url传给解析或抽取工具。 - 远程 URL 不重复上传。 可访问的
http://或https://地址直接作为file；绝不要把远程 URL 传给upload_temporary_file.chunk，当前实现会把它误当作 Base64。 - 认证不等于无限消费许可。 用户明确要求处理某个文件或批次时，视为授权每个文件执行一次最小必要的处理调用；新增第二种计费处理、扩大批次或重跑结果不明的任务前，必须说明原因并取得确认。
- 保留可追踪状态。 保存每个文件的
data.id、data.download_url、data.task_id、accept_language和最后状态。批量部分失败时逐文件报告，不能宣称整批成功。 - 以响应事实为准。 同时检查 MCP 错误、顶层
code/message/tips和data.status。HTTP 成功不代表业务成功，也不要根据自然语言错误消息臆造结果。 - 默认同步。 解析和抽取默认传
wait=true；只有用户明确要求异步处理时才传wait=false。大文件、复杂文档或批量任务本身不构成切换异步的授权。 - 结果完整保真。 默认逐项输出 MCP 在目标结果载荷中实际返回的全部字段、数组项和嵌套值，不得按“重要性”筛选，不得省略空值，不得合并同名或相似字段，也不得改名、翻译、归一化或推导新值。只有用户明确指定字段子集或要求摘要时才可缩减。
调用前决策顺序
在第一次工具调用前依次确定：
- 用户需要全文/版面，还是明确字段。
- 输入是本地路径、
file://、HTTP(S) URL 还是 Base64。 - 文档类型和地区是否足以选择一个专用工具。
- 是单文件还是批量，账户套餐是否已知。
- 用户是否明确指定异步；未指定时使用同步，并确认最多会触发多少次计费处理。
- 用户是否明确限定字段子集或要求摘要；若没有，按 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 个上传并发，避免客户端和服务端整文件读入内存。
处理上传、格式和区域差异前，读取 文件输入与上传协议。
工具选择
| 用户意图或文档类型 | 默认工具 | 选择规则 |
|---|---|---|
| 完整阅读、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 契约边界见 工具路由与契约。
标准工作流
远程 URL 或 Base64 单文件
- 选择一个最小充分的处理工具。
- 将 URL 或 Base64 作为
file。 - 默认使用
wait=true；直接校验并读取结果。 - 用户未明确要求字段子集或摘要时，完整返回目标结果载荷，不做主观筛选或合并。
本地单文件
- 调用
upload_temporary_file，只传chunk。 - 校验
code和data.download_url。 - 将该 URL 传给一个目标处理工具。
- 不要因后续处理失败而自动重新上传；已有 URL 仍可用时复用它。
大文件或批量任务
- 默认将每个文件作为独立状态单元，记录文件名、URL、工具、
task_id、语言和状态。 - 用户未明确指定异步时，逐个使用
wait=true完成处理；不要仅因文件大、复杂或数量多而自动切换异步。 - 只有用户明确指定异步时，才使用
wait=false创建任务，并从实际响应的data.task_id取值。 - 异步模式下，以 2 秒开始，按 2、4、8、15 秒上限退避调用
query_task；遵守服务端Retry-After，不要高频轮询。 - 创建任务与查询任务时使用相同的
accept_language，否则可能切换到不同区域域名。 - 状态 1/2 继续；状态 4 停止轮询并读取结果；状态 5/6 立即停止；状态 0 或其他未定义状态只做有限次数复查，持续异常时按协议漂移停止。
query_task已返回完整data.extraction_result或data.doc_recognize_result时直接使用；否则状态 4 后调用一次get_result。- 达到用户允许的等待时间仍未完成时，返回
task_id和最后状态，不要把仍在运行写成失败，也不要重新创建任务。
自定义抽取
- 用户已提供可信
app_id时直接调用execute_custom_extract_app。 - 用户只提供应用名称时，调用一次
list_custom_extract_apps，要求名称或 ID 精确匹配，并检查返回的应用类型。 - 当前 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 工具”理解为验真免费，也不要将一份多页发票按页重复计算验真次数。
- 费率、免费额度、处理并发和区域规则见 积分、认证与服务限制。控制台和实际扣费记录优先。
输出协议
- 读取原始 OpenAPI 包装体：顶层通常是
code/message/tips，结果位于data；不要套用旧文档中的顶层task_id/status示例。 parse_document读取data.doc_recognize_result；抽取工具读取data.extraction_result；异步 ID 读取data.task_id。- 默认完整输出目标结果载荷中的每个字段和数组项。普通字段完整保留
field_key、field_name、field_values及响应中存在的其他属性；表格字段完整保留table_values的所有行、列、单元格及其元数据；解析结果完整保留每页及其嵌套结构。 - 保留 MCP 的原始字段名、字段顺序、数组顺序、嵌套层级、重复项、
null、空字符串、空数组和空对象。不要把多个字段合成一个展示项，也不要因值为空、置信度低或看似不重要而删除。 - 展示格式可以使用 JSON 或无损 Markdown，但不得改变结果语义。字段较多时分段或分批继续输出，不能用省略号、“其余字段略”或总结替代未展示内容。
- 输出前核对源结果与最终展示：顶层字段数量、字段数组项数量、表格行列数量和分页数量必须分别一致。若 MCP 返回 25 个字段，最终回答必须可逐项核对到 25 个；无法完整展示时明确报告技术限制，不得宣称已完整输出。
- 只有用户明确列出字段子集或明确要求摘要时才可缩减；缩减时说明这是按用户要求筛选，不要暗示它是 MCP 的完整结果。
- 对每个文件标记
成功、失败或结果不明。部分成功必须列出失败项和观察到的message/tips/status。 - 文档、下载 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：将结果标为不明。接口没有幂等键，可能已经处理并扣费；不要盲目重提，先取得用户确认。 - 同一错误经过允许的有限重试仍失败时停止，不要静默切换到另一个计费工具。
处理失败或异步结果前，读取 执行、结果与错误协议。
明确停止条件
出现以下任一条件时停止调用并说明下一步：
- 缺少文件、URL/Base64 为空、远程 URL 不可访问。
- 文件加密、损坏、类型不支持，或超过当前区域公开限制。
- 文档类型歧义且继续会改变价格或触发额外处理。
- 自定义应用没有精确、可信的
app_id。 - Connector 认证失败、权限不足或积分不足。
- 处理请求是否被接受不明，重试可能重复扣费。
- 任务进入失败/取消状态，或有限重试已耗尽。
- 实际工具/schema 与本协议不一致，且无法从当前
tools/list安全确定用法。
按需读取的参考资料
- 需要选择工具、核对全部 22 个工具或处理自定义应用时，读取 工具路由与契约。
- 遇到本地文件、Base64、格式/页数/大小或批量上传时，读取 文件输入与上传协议。
- 选择同步/异步、解释结果、轮询或处理错误时，读取 执行、结果与错误协议。
- 估算积分、决定并发、处理授权或区域认证时，读取 积分、认证与服务限制。