mcpField
A
antom-integration

antom-integration

github.com/ant-intl开发163148 次安装3 周前更新
代码仓库

关于 antom-integration

antom-integration 是用于查找 Antom 支付集成资料、编写集成代码和排查问题的 Skill，面向支付集成开发者。它按产品、集成模式和技术栈路由文档，并规定了代码安全、日志和验证要求。

主要功能

  1. 01按产品与集成模式查找文档
  2. 02按技术栈选择 SDK 和示例代码
  3. 03编写或修改支付集成代码
  4. 04根据错误信息路由故障排查
  5. 05遵循通知验证与密钥安全要求

适用场景

  1. 01为选定的 Antom 产品准备集成代码
  2. 02根据 API 错误码或日志诊断问题
  3. 03检查异步通知验证和密钥处理
  4. 04按清单准备沙盒测试与上线

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ant-intl/antom-ai-tools --skill antom-integration

安装后在 Claude Code 中输入/antom-integration确认已加载。

详细介绍

范围

使用此技能来：

  • 查找相关的 Antom 产品、集成、SDK、通知、检查清单和故障排除知识
  • 为所选产品、集成模式和技术栈编写或修改 Antom 支付集成代码
  • 根据结果码、API 名称、请求 ID、日志、异步通知以及沙盒或正式上线问题，诊断集成问题

文档访问指南

使用 curl 获取 Antom 在线文档：

curl -sL "https://****/****.md"

获取集成文档

将本节用作产品建议、问答、代码实现和故障排除的通用知识查询入口。

SDK 选择

如果涉及服务端 SDK，且需要选择语言、确认公开版本或安装方式、配置 API 域名或准备后端代码，请阅读 SDK Description。产品专属示例代码应从匹配的产品文档中选择。

产品选择

如需产品或集成模式建议，请阅读 Product Decision。仅在需要时使用其中的澄清模板。

打开任何产品概览或选择集成模式之前，先通过 Product Decision 选择产品。

选择产品后，如果用户希望快速集成并覆盖多种支付方式，且 Checkout Page (CKP) 适用于所选产品和场景，则优先选择它。

集成文档选择

根据用户选择的产品和集成模式，查找相应的产品集成文档：

阅读匹配产品文档中最具体的可用章节。

  • 选择产品后，除非用户要求比较或迁移，否则不要加载其他产品文档。对于 Billing，请遵循其 Router，仅加载所选场景、功能、路径和操作所需的内容。
  • 对于问答或产品建议：根据已有信息进行判断，阅读最相关的文档，并在适当时说明假设。
  • 对于故障排除：优先根据 resultCode/resultMessage、API 名称、requestId、调试日志或错误文本进行分类。

编写代码

在编写或修改代码之前，先确认用户选择的产品和技术栈。仅当所选流程涉及支付路径或 UI 选择时，才确认集成模式。

编码前的阻断清单：

在完成以下所有适用项之前，不要编写或修改集成代码。

  • 阅读 Product Decision，确认产品类别和集成模式，即使用户的请求看起来很具体也不例外。仅当用户明确要求跳过产品选择时，才可跳过。
  • 涉及后端语言或 SDK 时，阅读 SDK Description。
  • 阅读 Integration Documentation Select 中匹配的产品概览：
    • 一次性付款
    • 令牌化付款
    • 订阅付款
    • 计费产品系列
  • 根据匹配的产品概览，在适用时按集成模式选择路径，并且只阅读该流程所需的实现文档，例如集成指南、快速入门、API 列表、前端 SDK、原生 SDK、Element、Checkout Page 或仅限 API 的指南。
  • 对于编码任务，按请求的语言或平台选择路径，并在编写代码前阅读同一产品概览中匹配的产品示例代码文档。快速入门、API 参考或集成指南中的内嵌示例可作为有用参考，但不能替代产品示例代码文档。
  • 如果请求的操作没有完全匹配的示例代码，请阅读其 API 契约以及所选 SDK 的文档或源代码。不要根据 API 字段名称推断 SDK 类或方法；说明任何无法确认的符号。
  • 根据匹配的产品概览，阅读与所选产品以及（在适用时）集成模式相匹配的异步通知文档或章节。
  • 阅读 FAQ (Coding)，浏览与所选产品、集成模式、支付方式和市场匹配的条目。

生成的代码必须：

  • 将签名和私钥保留在服务器端
  • 在信任异步通知之前先验证通知
  • 不将客户端重定向结果视为最终支付状态
  • 通过异步通知或查询 API 确认不确定的支付状态
  • 在有用时提供开发调试日志指南，并对卡号、CVV、私钥和密钥进行脱敏处理
  • 包含简短的 FAQ 合规说明，确认如何处理每个适用条目，例如 gateway=correct region、settlementCurrency=omitted 或 subscriptionExpiryTime=default
  • 简要说明所依据的文档和验证假设
  • 当用户构建完整集成时，提供有关凭据、沙盒测试、自检和正式上线准备的后续步骤指南

调试日志

除控制台输出外，将日志写入项目根目录中名为 antom_debug.log 的文件。所有生成的集成代码都必须记录每次 API 调用的 API 端点、完整请求和响应。对敏感字段（卡号、CVV、私钥）进行脱敏处理。

严格使用以下格式：

  • 发出的请求/响应：[Antom][{timestamp}][{API endpoint}] {request/response body}
  • 收到的异步通知：[Antom][{timestamp}][{API name}] {notification body}

日志代码仅供开发和调试使用；集成稳定后应将其移除或减少。

验证与代码完成后的指导

在最终确定代码或提供上线准备指导前，请阅读 集成检查清单。

指导用户配置凭据和配置项时，请说明凭据的获取位置：

  • API 域名、Client ID 和 Antom 公钥可在 快速入门中找到。
  • 商户私钥可在 iKeys中生成或管理；请将其保存在服务端，绝不要记录、公开或提交该私钥。

代码编写完成后，不要只说“代码已完成”。请指导用户完成以下事项：

如果用户在任何时候询问凭据、注册、沙盒测试、检查清单、自检或上线准备，请阅读对应的配套文档，并在回复中直接解答。

故障排查

  • 错误诊断（必须）：当 Antom API 调用失败或用户报告集成问题时，必须先阅读 故障排查指南，再进行诊断。绝不要跳过此步骤，直接使用诊断 CLI、Dashboard 或联系支持团队。

    请按照指南中的顺序操作：

    1. 收集证据 → 从用户输入、控制台输出、antom_debug.log，以及可查看的本地集成代码、配置和环境变量文件中收集证据，并对密钥和私钥进行脱敏。
    2. 查询 API 错误 → 查找 API Result/Error 代码并运行本地自检。
    3. 验证修复 → 在将问题视为已解决之前，验证所有修复。
    4. 升级处理 → 仅在指南诊断门槛允许的顺序和条件下，升级至诊断 CLI、Dashboard 或支持团队。
    5. 诊断记录 → 返回指南中定义的简明诊断记录。

  • 按需触发：如果用户在任何时候询问集成错误、API 调用失败、请求/响应问题、结果代码、Dashboard 诊断、诊断 CLI 或故障排查，请阅读故障排查指南，并在回复中直接解答。

安全红线

  • 绝不能将私钥存储在客户端、记录私钥或将私钥提交到公共代码仓库。
  • 必须先验证异步通知的签名，再信任其内容。
  • 客户端重定向结果不能作为最终支付状态。
  • 在通过异步通知或查询 API 确认支付状态之前，不要要求用户再次付款。

评论

支持 Markdown