文档智能（Payskill）- Anspire

概述

Anspire Document Intelligence

计费方式：无需 API Key、无需注册，通过微信支付按次计费。

文档抽取、图片鉴真均按次收费（具体价格以 SkillHub 后台配置为准）。

首次调用返回 HTTP 402，系统自动检测响应头中的 WeixinPay-Required 并触发支付卡片，支付成功后重试获取结果。

付费前置检查（进入任何工具调用前必须先做）

命中本 Skill 且用户已提供待处理文件后，直接进入 SkillPay 请求流程，不要增加单独的“是否继续付费”确认轮次。支付授权确认由系统自动展示的 weixinpay 支付卡片完成。

调用本 Skill 前，必须检查当前 Agent 是否已安装支付能力（weixinpay 插件）：

• ✅ 已安装：直接请求 SkillPay 服务，收到 WeixinPay-Required 后自动进入微信支付流程
• ❌ 未安装：向用户提示「当前 Agent 暂不支持微信支付付费能力」，终止流程，不得先创建订单

服务与定价

价格以 SkillHub 后台配置为准。命中识别意图且用户已提供文件后，直接进入 SkillPay 请求流程；不得额外询问“是否确认继续付费”。首次请求返回 HTTP 402 后，由系统自动触发 weixinpay 支付卡片，等待用户在微信支付流程中确认。

工作流程

第一步：请求资源

使用 curl 直接调用 Anspire SkillPay 接口。必须保留原始 HTTP 状态码、响应头和响应 Body；使用 -D - 将响应头输出到 stdout 供系统检测，使用 -o 将响应 Body 保存到文件供后续解析。不得使用 Python 网络脚本、curl 包装器、shell 管道或其他中间层改写、吞掉或覆盖 HTTP 状态码；尤其不得把 HTTP 402 转换成 HTTP 200、普通异常、系统繁忙或仅返回 JSON Body。

文档抽取：

POST https://vlm.anspire.cn/skillpay/v1/document/extract
Body: multipart/form-data (file=文档文件, source, with_grounding, with_uncertainty, [schema])

curl -s -D - -o /tmp/anspire_payment.json 
  -X POST "https://vlm.anspire.cn/skillpay/v1/document/extract" 
  -H "Accept: application/json" 
  -H "X-Idempotency-Key: sp-$(openssl rand -hex 16)" 
  -F "file=@/path/to/document.pdf" 
  -F "source=" 
  -F "with_grounding=false" 
  -F "with_uncertainty=false"

图片鉴真：

POST https://vlm.anspire.cn/skillpay/v1/image/tamper-detect
Body: multipart/form-data (image=图片文件)

curl -s -D - -o /tmp/anspire_payment.json 
  -X POST "https://vlm.anspire.cn/skillpay/v1/image/tamper-detect" 
  -H "Accept: application/json" 
  -H "X-Idempotency-Key: sp-$(openssl rand -hex 16)" 
  -F "image=@/path/to/image.png"

第二步：处理 402 响应

服务端返回 HTTP 402（支付要求）。响应头中包含 WeixinPay-Required（支付码）和 X-Out-Trade-No（订单号），两者都必须保存。

系统自动检测响应头中的 WeixinPay-Required 并触发工程化支付卡片——无需智能体手动调用支付工具。首次用户可在支付卡片中同时完成绑卡 + 支付。

同时从 402 响应 Body（已保存到 /tmp/anspire_payment.json）中提取以下字段，用于第四步重试：

jq -r '.payment_required | "session_id=(.payment_session_id)nsession_token=(.payment_session_token)nout_trade_no=(.out_trade_no)namount=(.amount_cents / 100) (.currency)"' 
  /tmp/anspire_payment.json

⚠️ HTTP 402 且响应头包含 WeixinPay-Required 是标准的支付请求，不是普通系统错误。不得将该响应解释为"系统繁忙"或业务失败。向用户清楚展示本次金额、币种、能力和收款主体。

第三步：发起支付

系统自动触发支付卡片，用户完成支付（首次用户可同时完成绑卡 + 支付）。无需智能体手动调用支付工具。

第四步：支付成功后获取资源（⚠️ 必须执行）

只有支付明确成功后，使用第二步保存的会话信息调用 execute 端点：

POST https://vlm.anspire.cn/skillpay/v1/payment-sessions/{payment_session_id}/execute
Headers: SkillPaySession + X-Out-Trade-No（第二步保存的值）
Body: 无（execute 端点复用首次请求时已上传的文件）

curl -s -o /tmp/anspire_result.json 
  -X POST "https://vlm.anspire.cn/skillpay/v1/payment-sessions/{payment_session_id}/execute" 
  -H "Accept: application/json" 
  -H "SkillPaySession: {payment_session_token}" 
  -H "X-Out-Trade-No: {out_trade_no}"

⚠️ 第四步是最容易被 Agent 遗漏的一步：不携带 X-Out-Trade-No Header 重试，就永远拿不到付费内容。支付成功后必须重新请求，不得把支付工具成功误报为业务完成，只有返回已履约结果后才能向用户交付结果。

图片鉴真履约在服务端内部采用异步任务协议：先创建鉴真任务，再查询任务状态，状态成功后获取任务结果。上述异步步骤由 SkillPay 服务端完成，Agent 不得直接调用后端的公开鉴真任务接口，不得自行创建第二个鉴真任务，也不得重复上传文件。

如果 execute 返回 HTTP 202，或响应 JSON 的 status 为 processing，等待 2 秒后轮询同一个支付会话的 result 端点：

curl -s -o /tmp/anspire_result.json 
  "https://vlm.anspire.cn/skillpay/v1/payment-sessions/{payment_session_id}/result" 
  -H "Accept: application/json" 
  -H "SkillPaySession: {payment_session_token}" 
  -H "X-Out-Trade-No: {out_trade_no}"

重复轮询直到 HTTP 200 且响应 JSON 中 status 为 fulfilled。如果状态为 retryable_failed，使用同一支付会话再次调用 execute 重试履约，不得重新支付或创建新的支付会话。

安全与执行前检查

1. 用户只需要描述业务目标并提供文件或 URL，不需要也不应在提示词中提及 SkillPay、支付模式、API Key、支付工具或履约步骤。
2. 支付方式属于 Skill 内部执行策略。Agent 不得询问用户选择计费模式，也不得要求用户补充"请使用 SkillPay"等技术指令。
3. 正常调用始终使用 SkillPay 端点（/skillpay/v1/），不得切换到 API Key 模式。
4. 只有在用户允许将文件上传到 Anspire 服务时才调用 API。
5. 不要把 API Key、SkillPay 会话令牌或支付凭证写入 Skill 包、日志或最终回复。Skill 包不包含真实凭证。
6. scripts/anspire_api.py 仅用于图片鉴真结果的本地后处理，不发起 API 或支付请求。
7. 输入是身份证、护照、合同、财务票据或其他个人信息时，提醒用户文件会发送到第三方服务。

支付异常处理

1. HTTP 402 且响应头包含 WeixinPay-Required 时，表示支付尚未完成：等待系统自动触发支付卡片，不得重新运行原始业务请求来代替支付。
2. HTTP 202 或响应 JSON 中 status 为 processing 时，表示已支付且履约仍在处理中：不要再次调用支付工具，稍后轮询同一支付会话的 result 端点。
3. 响应 JSON 中 status 为 retryable_failed 时，表示本次业务履约可重试：使用同一支付会话再次调用 execute，不得重复支付或创建新订单。
4. 响应 JSON 中 status 为 payment_expired/cancelled/payment_failed/terminal_failed 时，表示原会话已失效：清理本地保存的会话信息，从第一步重新开始。
5. 不得对 terminal_failed 或金额校验失败自动发起第二次收费。支付返回系统繁忙、超时、网络错误或状态不明确时，不得直接重新支付或创建新订单；保留原订单号并轮询 result 端点查询原订单状态，只有明确为未支付且原会话已过期或取消后才能创建新订单。
6. 一旦用户完成支付，无论履约成功、仍在处理、网络失败还是服务端/业务执行失败，结束输出都必须包含订单编号。从第二步保存的 out_trade_no 中获取订单编号，在最终回复中展示 订单编号：<out_trade_no>，便于客户咨询和后台排查。订单编号可以展示，但不得展示支付码、支付会话令牌或完整订单凭证。

能力选择

• 用户提供 PDF、Word、扫描件或文档图片，并要求 OCR、文字识别、图片转文字、读取或解析文档、提取全文或表格，或按字段、Schema、JSON 结构化提取信息：使用 extract
• 用户提供图片，并要判断是否经过 PS、P 图、修图、涂改、拼接、合成、局部篡改或伪造，是否由 AI/AIGC 生成，或要求图片鉴真、图片真实性检测、真假图片或真假照片判定：使用 tamper-detect
• 用户只提及票据、合同、简历、证件等文档类型，但没有要求识别、读取、解析或提取内容时，不要调用本 Skill
• 用户要求商品、新闻、账号、文本、音频或视频等非图片对象的真伪核验或 AIGC 检测时，不要调用本 Skill
• 用户没有提供本地文件或 URL：要求补充输入
• 用户要求本 Skill 不支持的能力：说明本 Skill 只支持以上两个端点

复杂 Schema、完整响应字段、错误结构和接口变更信息，按需读取references/api_reference.md。

文档抽取

默认使用 curl 直接调用 SkillPay 端点，用户提示词不得包含支付模式指令。当前 SkillPay 仅支持单页文件：图片按单页处理，PDF 和 Word 文档转换后的页数必须为 1。首次调用返回 HTTP 402 后，按上方「工作流程」第二至第四步执行支付和重试，不得把支付码已返回解释为"系统繁忙"；支付成功后再调用 execute 端点获取结果。

默认提取全部内容时，禁止构建或传递 Schema：

curl -s -D - -o /tmp/anspire_payment.json 
  -X POST "https://vlm.anspire.cn/skillpay/v1/document/extract" 
  -H "Accept: application/json" 
  -H "X-Idempotency-Key: sp-$(openssl rand -hex 16)" 
  -F "file=@/path/to/document.pdf" 
  -F "source=" 
  -F "with_grounding=false" 
  -F "with_uncertainty=false"

只有当用户在提示词中明确列出要提取的字段时，才根据这些字段构建标准 JSON Schema 并通过 schema 字段传递：

curl -s -D - -o /tmp/anspire_payment.json 
  -X POST "https://vlm.anspire.cn/skillpay/v1/document/extract" 
  -H "Accept: application/json" 
  -H "X-Idempotency-Key: sp-$(openssl rand -hex 16)" 
  -F "file=@/path/to/document.pdf" 
  -F "source=" 
  -F "with_grounding=false" 
  -F "with_uncertainty=false" 
  -F 'schema={"type":"object","properties":{"发票号码":{"type":"string"},"金额":{"type":"number"},"开票日期":{"type":"string"}}}'

规则：

1. -F "file=@本地文件路径" 为必填，curl 模式当前仅支持本地文件上传。
2. schema 为可选参数。用户只说"提取文档内容""识别这个文件""读取全部内容"或没有指定字段时，必须省略该字段。
3. 禁止 Agent 或 Python 根据文档类型、文件名、图片内容、历史经验或常见模板自主推测字段并构建 Schema，也禁止为了获得结构化输出而传递空 Schema。
4. 只有用户明确指定一个或多个目标字段时，才允许构建 Schema；Schema 只能包含用户明确要求的字段，不得擅自补充字段。字段类型无法从用户要求确定时优先使用 string，不要读取文档后再动态扩展 Schema。
5. 常规抽取不要启用 with_grounding=true；只有用户要求字段溯源、原文定位或坐标时才设为 true。
6. 用户只需要结果内容时，从 /tmp/anspire_result.json 中提取 result 字段展示。
7. 最终回复不要直接倾倒完整原始 JSON。
8. 无 Schema 时按服务端返回的全部内容组织结果；有 Schema 时按用户指定的字段顺序展示。不要主动附加识别质量评价、复核建议或字段置信度分析，除非用户明确要求。
9. SkillPay 返回单页限制错误（HTTP 400/422，错误消息含"当前版本仅支持单页文件处理"）时，直接告知用户：

"当前版本仅支持单页文件处理。检测到上传文件包含多个页面，暂无法处理；多页文件处理能力将在后续版本中提供。"

1. 遇到单页限制时，不要继续重试，不要引导用户支付，也不要声称已创建支付会话。请用户提供单页文件后重新提交；未经用户明确同意，不要自行拆分、裁剪或转换原文件。

文档抽取展示模板

使用 Markdown 表格或分组列表展示服务端返回的内容；存在用户指定 Schema 时保持字段顺序：

## 文档抽取结果

| 字段 | 识别结果 |
|---|---|
| 字段 A | 值 A |
| 字段 B | 值 B |

结果文件：`/tmp/anspire_result.json`
订单编号：`SP...`

展示要求：

• string、number、boolean 直接展示值。
• array 使用换行列表展示，不要压成难读的单行 JSON。
• object 使用字段嵌套表格或折叠列表展示。
• null、空字符串和未识别字段必须如实展示为"未识别"，不得自行补值。
• 默认不展示 task_id、耗时、request ID、uncertainty 和 aigc 等技术元数据。
• 只有用户明确要求溯源时才展示 grounding。实际接口可能返回

字段名: [[x1,y1,x2,y2], ...]，按原字段对应坐标展示，不要虚构页码。

图片篡改与 AIGC 检测

图片鉴真默认使用 curl 直接调用 SkillPay 端点。首次调用必须原样保留 HTTP 402、响应头和响应 Body，按上方「工作流程」第二至第四步执行支付和重试；服务端会从 TOS 读取已上传的原图，execute 端点复用首次请求的文件。不得使用 Python 网络脚本包装下单请求或覆盖 HTTP 状态码。

curl -s -D - -o /tmp/anspire_payment.json 
  -X POST "https://vlm.anspire.cn/skillpay/v1/image/tamper-detect" 
  -H "Accept: application/json" 
  -H "X-Idempotency-Key: sp-$(openssl rand -hex 16)" 
  -F "image=@/path/to/image.png"

支付成功并获取结果后（/tmp/anspire_result.json），使用脚本进行后处理（生成融合图、对比 HTML），不涉及 API 调用和支付：

python3 /path/to/skill/scripts/anspire_api.py post-process 
  --file /path/to/image.png 
  --result /tmp/anspire_result.json 
  --capability image.tamper-detect 
  --quiet

规则：

1. 图片来源按以下优先级处理：
   • 优先使用 Work Buddy 当前消息中用户实际上传的原始图片附件，以及运行环境为该附件提供的临时文件路径。
   • 只有用户明确提供本地文件路径时，才读取该本地文件。
   • 用户明确提供图片 URL 时，只有运行环境支持下载并且已将图片保存为本地文件后才能处理；当前 curl 流程最终必须使用本地文件上传。
   • 不要根据文件名、历史路径或工作区内容自行寻找、匹配或替代图片。
   • 如果当前运行环境无法访问对话附件，应明确告知用户，不能擅自改用本地同名图片。
   • 对可访问的原始图片文件，优先使用原始内容，不要默认使用可能经过 JPEG 重编码的剪贴板副本。
   • 脚本会校验 magic bytes；扩展名与真实格式不一致时按真实 MIME 上传并提示。
   • 用户要求左右对比时使用 --compare，并报告生成的 HTML 路径。### 图片鉴真展示模板

必须先给出单一、明确的主结论，再展示技术细节：

## 图片鉴真结果

**结论：发现疑似篡改**

| 项目 | 结果 |
|---|---|
| 图片类型 | 真实图片 |
| 篡改检测 | 是 |
| 篡改分数 | 0.9416 |
| 判定阈值 | 0.8 |
| 疑似区域 | 1 个 |

### 本地融合图

![篡改区域标注图](/path/to/image_fused.png)

结果文件：`/tmp/anspire_result.json`
融合图文件：`/path/to/image_fused.png`
订单编号：`SP...`

结论规则：

• 先读取外层 aigc.image_type。aigc.image_type == "ai_generated" 时，结论是 AI 生成图片，不能视为真实图片；即使 result.tamper_detection.is_tampered 缺失或为 null，也不能解释成真实或未篡改。
• aigc.image_type == "real_image" 时，再读取 result.tamper_detection 或其归一化字段：
  • result.tamper_detection.is_tampered == true 或 result.is_tampered == true：结论为发现疑似篡改。
  • result.tamper_detection.is_tampered == false 或 result.is_tampered == false：结论为未发现达到判定阈值的篡改。
  • 值为 null、字段缺失或状态不是 completed：结论为无法完成可靠判定，不得自行推断。
• 主结论优先根据 result.decision 和 result.reason 组织；result.tamper_detection.evidence_score、result.tamper_detection.decision_threshold 或归一化后的 result.tamper_score、result.threshold 仅作为技术细节展示。

展示要求：

• result.tamper_regions 是后端归一化后的区域列表，优先展示 id 或 region_id、bbox、score；原始明细也可能位于 result.tamper_detection.regions。
• bbox 通常为 [x1, y1, x2, y2]；如果返回对象格式，只有字段明确表示边界坐标时才能绘制，不得把不完整的 x、y 等字段自行推断成矩形。
• 如果返回 result.tamper_regions 坐标信息，必须执行 Pillow 本地绘制，生成带红色区域和边框的 {原图名}_fused.png，并在最终回复中展示该本地图片或提供可预览的本地文件路径。
• 如果 result.artifacts 中存在远端 URL 或其他远端资源，禁止访问、下载、打开或展示；篡改区域标注只能使用本地原图和本地结果数据生成。
• 不默认展示完整响应 JSON；用户明确要求原始响应时才提供已清理敏感信息和远端 URL 的本地结果文件。

输出与错误处理

1. curl 调用时使用 -s -D - -o /tmp/anspire_result.json，响应头和 HTTP 状态码原样输出到 stdout 供系统检测，响应 Body 保存到文件供后续解析；禁止使用 Python 网络脚本或 shell 包装器覆盖 HTTP 状态码。
2. 需要管道处理时，从 /tmp/anspire_result.json 中提取 result 字段；图片鉴真结果不要假设 result 只有 is_tampered 和 tamper_score 两个字段。
3. 成功时只展示识别结果和输出路径；不要把请求头、API Key 或完整调试日志放入最终回复。SkillPay 用户完成支付后，无论任务成功还是失败，最终回复都必须展示订单编号（从第二步 402 响应的 out_trade_no 获取）。
4. 失败时根据 HTTP 状态码说明原因：
   • HTTP 400/422：参数/Schema/文件格式/文件大小错误，检查输入参数
   • HTTP 401：鉴权失败（SkillPay 模式一般不会出现）
   • HTTP 403：权限或配额不足，联系管理员
   • HTTP 429：限流，稍后重试
   • HTTP 500+：服务端错误，稍后重试
   • 网络错误：检查网络后重试
   • HTTP 402 支付要求不是错误：响应头包含 WeixinPay-Required（支付码）和 X-Out-Trade-No（订单号）时，按「工作流程」第二至第四步执行支付和重试
5. SkillPay 单页限制（HTTP 400/422，错误消息含"当前版本仅支持单页文件处理"）属于参数错误，该场景未创建支付会话，不应按支付失败或服务异常处理。
6. 输出文件已存在时不要无提示覆盖；改用新的输出路径或先征得用户同意。

远端融合图禁止使用

如果响应的 result.artifacts 或其他字段包含远端 URL，绝对禁止访问、下载、打开或展示这些远端资源。篡改区域标注必须由脚本使用 Pillow 根据本地原图和 result.tamper_regions 在用户本地生成。

参考文件

• references/api_reference.md：完整 API 字段、请求响应示例和 Schema 进阶用法。
• scripts/anspire_api.py：仅包含 post-process 子命令，用于本地生成融合图和可选对比 HTML；不发起网络或支付请求。