---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/guide/llms-integration/index.md
description: 说明如何通过 llms.txt、llms-full.txt 兼容入口、OpenAPI 和 Skill 将文档接入 AI 工具或 Agent 工作流。
---
# LLM 文档集成

PingPong Checkout 文档站已经提供面向 AI 工具的结构化入口，既支持通过 `llms.txt` / `llms-full.txt` 兼容入口 / OpenAPI 做文档发现，也支持通过 Skill 把接入约束和工作流一起交给 AI 工具。

## 先选哪一种方式

| 目标 | 推荐方式 |
|------|------|
| 让 AI 读取最新文档、接口描述和页面链接 | 优先接入 `llms.txt` + `/api/openapi.json` |
| 需要兼容仍会读取 `llms-full.txt` 的工具 | 使用 `llms-full.txt`，其会返回中英文 `llms.txt` 发现入口 |
| 让 AI 按 PingPong Checkout 的接入流程、检查项和最佳实践执行 | 安装 `pingpong-checkout.skill` |

## 文档发现入口

| 文件 | 路径 | 用途 |
|------|------|------|
| llms.txt | `/llms.txt` | 根入口，返回中英文文档发现文件索引 |
| 中文 llms.txt | `/zh/llms.txt` | 中文文档目录索引，适合按页面按需抓取 |
| 英文 llms.txt | `/en/llms.txt` | 英文文档目录索引 |
| llms-full.txt | `/llms-full.txt` | 兼容入口，返回中英文文档发现文件索引 |
| OpenAPI 规范 | `/api/openapi.json` | OpenAPI 3.1.0 规范，适合类型约束和接口参数校验 |
| API 索引 | `/api/index.json` | 当前可导出的 API 清单与文档跳转索引 |

## 推荐访问顺序

1. 优先读取目标语言的 `llms.txt`
2. 再读取 `/api/openapi.json` 获取接口约束
3. 如果工具固定读取 `llms-full.txt`，按其返回的语言索引继续读取对应 `llms.txt`
4. 根据 `llms.txt` 或 `api/index.json` 中的链接继续抓取具体文档页

## AI 工具接入示例

### Cursor

在项目根目录创建 `.cursorrules` 文件：

```text
当需要调用 PingPong Checkout API 时，请优先参考以下文档：
- 中文文档索引：https://acquirer-api-docs-v4-en.pingpongx.com/zh/llms.txt
- OpenAPI 规范：https://acquirer-api-docs-v4-en.pingpongx.com/api/openapi.json
```

### Windsurf

在 `.windsurfrules` 中添加：

```text
PingPong Checkout API 文档：
- https://acquirer-api-docs-v4-en.pingpongx.com/zh/llms.txt
- https://acquirer-api-docs-v4-en.pingpongx.com/api/openapi.json
```

### Claude Code

在 `CLAUDE.md` 中配置：

```markdown
## PingPong Checkout 文档参考

查阅 PingPong Checkout API 时：
1. 优先读取 /zh/llms.txt 获取中文文档目录
2. 读取 /api/openapi.json 获取接口结构和字段约束
3. 根据目录中的页面链接继续获取详细文档
```

### 通用 HTTP 访问

任何支持 HTTP 请求的 AI 工具都可以直接获取：

```bash
# 获取语言索引
curl https://acquirer-api-docs-v4-en.pingpongx.com/llms.txt

# 获取中文文档目录
curl https://acquirer-api-docs-v4-en.pingpongx.com/zh/llms.txt

# 获取 llms-full 兼容入口
curl https://acquirer-api-docs-v4-en.pingpongx.com/llms-full.txt

# 获取 OpenAPI 规范
curl https://acquirer-api-docs-v4-en.pingpongx.com/api/openapi.json

# 获取 API 索引
curl https://acquirer-api-docs-v4-en.pingpongx.com/api/index.json
```

## API 索引里能拿到什么

`/api/index.json` 会返回当前导出的 API 文档索引，常用字段包括：

| 字段 | 说明 |
|------|------|
| `version` | 索引格式版本 |
| `generated` | 索引生成时间 |
| `count` | 当前收录 API 数量，会随文档更新动态变化 |
| `apis[].path` | 接口路径，例如 `/v4/payment/prePay` |
| `apis[].method` | HTTP 方法 |
| `apis[].jsonUrl` | 对应的结构化 JSON 描述地址 |
| `apis[].mdUrl` | 对应的 Markdown 文档地址 |
| `apis[].permalink` | 站内文档页面地址 |

## Skill 和文档发现的关系

`llms.txt` / `llms-full.txt` / OpenAPI 解决的是“让 AI 找到文档”的问题；`pingpong-checkout.skill` 解决的是“让 AI 按 PingPong Checkout 的方式工作”的问题。

如果您需要：

- 让 AI 自动发现 API、字段和文档链接，优先用文档发现入口
- 让 AI 审查接入方案、提醒风控与通知风险、输出上线前检查项，再配合 Skill 使用

## 相关文档

- [Skill 安装](/notes/zh/guide/llms-integration/skill-install/)
- [API 调用规范](/notes/zh/onlinePayment/developer/APIUsage/)
- [签名规约](/notes/zh/onlinePayment/developer/sign/)
- [支付结果通知](/notes/zh/onlinePayment/developer/paymentNotify/)