---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/guide/llms-integration/skill-install/index.md
description: 说明如何下载、导入、验证 PingPong Checkout Skill，并完成安装后的测试和上线前检查。
---
# Skill 安装

本页是 `pingpong-checkout.skill` 的安装与使用指南，帮助您在支持自定义 Skill 的 AI 工具中集成 PingPong Checkout 支付接入能力。

## 什么时候安装 Skill

如果您只是希望 AI 能读取最新文档和接口定义，优先接入 [LLM 文档集成](/notes/zh/guide/llms-integration/)。  
如果您希望 AI 进一步按 PingPong Checkout 的接入流程审查方案、提醒关键风险并输出检查清单，再安装 `pingpong-checkout.skill`。

## 快速开始

::: tip 三步完成安装
1. **下载**：[点击下载 Skill 包](/skills/pingpong-checkout.skill)
2. **导入**：在您的 AI 工具中导入 `pingpong-checkout.skill`
3. **使用**：开启新会话，明确说明您的接入需求
:::

```text
请使用 pingpong-checkout skill 帮我审查这个 PingPong Checkout 接入方案。
```

## Skill 功能

| 功能 | 说明 |
|------|------|
| **接入协助** | 支持 PingPong Checkout 和 Direct API 两种集成方式 |
| **方案审查** | 基于最新文档和规则收敛接入方案，避免常见陷阱 |
| **风险识别** | 识别签名、异步通知、状态幂等关键风险点 |
| **验收支持** | 生成上线前验证清单，辅助联调验收 |

## Skill 不替代什么

- 不替代真实下单、通知回调、退款等链路联调
- 不替代人工代码审核和安全审查
- 不替代生产环境参数开通、支付方式开通和验收测试

::: warning 重要声明
**Skill 生成的所有代码均为 AI 辅助生成，仅供参考：**

- ⚠️ **非官方代码**：代码不由 PingPong 官方提供或维护
- ⚠️ **需人工审核**：开发者必须仔细审查、测试并验证所有代码
- ⚠️ **自行承担责任**：使用生成代码产生的任何问题由使用者自行负责
- ⚠️ **遵循最佳实践**：确保代码符合您项目的安全规范和编码标准

**建议：** 将 Skill 生成的代码作为参考模板，结合实际项目需求进行适配和优化。
:::

## 安装前检查

- [ ] AI 工具支持自定义 Skill 导入或本地目录加载
- [ ] 已准备好待接入的工程代码
- [ ] 已获取沙箱商户参数和目标支付方式清单
- [ ] AI 工具能够访问 PingPongCheckout 文档站

::: warning 目录结构要求
如果需要手动解压 Skill，请保留 `pingpong-checkout/` 目录结构，不要修改或删除 `scripts/`、`references/`、`SKILL.md` 等文件。
:::

## 安装方式

### 方式一：直接导入（推荐）

适用于支持 `.skill` 文件直接导入的 AI 工具。

1. 下载 `pingpong-checkout.skill`
2. 在工具中选择导入 Skill
3. 选择下载的文件完成导入

### 方式二：目录加载

适用于需要从本地目录加载 Skill 的 AI 工具。

1. 解压 `pingpong-checkout.skill`
2. 将 `pingpong-checkout/` 目录放入工具约定的 Skills 目录
3. 重启工具或开启新会话

## 使用指南

### 基本用法

Skill 按以下流程推进工作：

```
Research → Ideate → Plan → Execute → Optimize → Review
```

### 首次使用建议

提供以下信息可帮助 Skill 更快收敛结论：

- **集成方式**：PingPong Checkout / Direct API
- **产品类型**：一次性支付 / Auth+Capture / Tokenization
- **支付方式**：Visa、Klarna、Google Pay 等
- **行业类型**：实物 / 游戏虚拟 / 其他虚拟

### 最佳实践

- ✅ **面向真实工程**：让 Skill 直接审查您的实际代码，而非脱离上下文的伪代码
- ✅ **明确当前阶段**：说明是在沙箱联调还是生产上线准备
- ✅ **全面审查**：一次性让 Skill 审查支付、回调、退款等所有相关逻辑
- ✅ **冲突确认**：当本地实现与文档冲突时，先停下来确认而非直接推进
- ⚠️ **代码审核**：所有 AI 生成的代码必须经过人工审查、测试和验证
- ⚠️ **安全优先**：确保生成代码符合您的安全规范和编码标准

## 安装验证

安装完成后，建议验证以下能力：

- [ ] Skill 能识别工程结构并区分前后端职责
- [ ] Skill 能基于文档和 OpenAPI 给出接入建议
- [ ] Skill 能指出签名、异步通知、幂等性等关键风险
- [ ] Skill 能根据支付方式提醒兼容性和前置条件

## 上线前检查清单

::: danger 重要提示
**安装 Skill ≠ 可以直接上线。**

1. **Skill 只能辅助收敛方案**，不能替代真实联调和测试
2. **所有 AI 生成的代码必须人工审核**，确保安全性和正确性
3. **所有接入方案在发布前必须完成全量测试**
:::

### 必测场景

| 场景类别 | 测试项 |
|---------|-------|
| **基础链路** | 正常支付、失败支付、用户取消、超时未支付 |
| **异步通知** | 验签、幂等处理、重复通知、乱序通知 |
| **结果处理** | 结果页展示、后端查单兜底 |
| **支付方式** | 真实下单、失败回退路径 |

### 按产品类型验证

- **Auth+Capture**：授权、确认、撤销边界
- **Tokenization**：签约、令牌支付、取消授权流程
- **退款业务**：时效、全额退款、部分退款、异常回退

### 环境检查

- [ ] 沙箱与生产的域名、密钥、脚本地址配置正确
- [ ] 生产环境支付方式已开通
- [ ] HTTPS、日志脱敏、私钥存储安全
- [ ] 异步通知地址可达

## 常见误区

| 误区 | 正确做法 |
|------|---------|
| 只验证 Happy Path | 测试所有异常分支和边界场景 |
| 以前端成功页为凭证 | 以后端查单和异步通知为准 |
| 忽略通知验签 | 必须验证签名并处理幂等 |
| 不确认生产环境 | 上线前确认支付方式已开通 |
| 复用旧方案 | 重新核对文档和 Skill 版本 |
| **直接使用 AI 代码** | **必须人工审核、测试并验证所有生成代码** |

## 相关文档

- [LLM 文档集成](/notes/zh/guide/llms-integration/)
- [API 调用规范](/notes/zh/onlinePayment/developer/APIUsage/)
- [签名规约](/notes/zh/onlinePayment/developer/sign/)
- [支付结果通知](/notes/zh/onlinePayment/developer/paymentNotify/)
- [交易状态与幂等](/notes/zh/guide/paystatus/)