matija2209/payload-plugin-api-guide
GitHub: matija2209/payload-plugin-api-guide
该插件根据 Payload CMS 的实时配置自动生成 API 参考文档、OpenAPI 规范及面向 AI agent 的查询指南，帮助开发者和 AI 助手准确理解项目接口。
Stars: 1 | Forks: 0
# @matija2209/payload-agent-api-guide
根据您的 Payload CMS 配置生成实时 API 参考和 agent 优先的查询指南。
该插件会读取您的实时 Payload 配置，并将其转换为实用的 API 文档、OpenAPI 参考以及可供 agent 阅读的说明——这样开发者和 AI 编程 agent 就能在无需猜测的情况下理解如何查询您的项目。
## 为什么需要
Payload 的 REST API 功能强大，但初学者和 AI agent 往往会弄错细节。他们可能会假设使用通用的 REST 模式——例如，通过 `/api/posts/my-slug` 获取具有特定 slug 的文章——而不是使用 Payload 真正的查询语法 `where.slug.equals`。
此插件通过直接根据您的 Payload 设置生成特定于项目的文档来解决此问题。
## 路由
所有路由均位于 `{payload.routes.api}/api-guide` 下（默认为：`/api/api-guide`）。
| 路由 | 描述 |
|---|---|
| `/api/api-guide` | 人类可读的 HTML 指南 |
| `/api/api-guide/reference` | 交互式 API 浏览器 (Scalar UI) |
| `/api/api-guide/openapi.json` | OpenAPI 3.1 规范 |
| `/api/api-guide/agent.md` | 面向 AI 编程 agent 的简明规则指南 |
| `/api/api-guide/agent.json` | 结构化项目地图（collections、字段、endpoints） |
| `/api/api-guide/llms.txt` | 包含指向所有资源链接的 LLM 入口点 |
| `/api/api-guide/query-recipes.json` | 每个 collection 的常见查询模式 |
## 安装说明
```
npm install @matija2209/payload-agent-api-guide
# 或
pnpm add @matija2209/payload-agent-api-guide
```
**Peer 依赖：** `payload >= 3.85.0`
## 用法
```
import { buildConfig } from 'payload'
import { apiGuidePlugin } from '@matija2209/payload-agent-api-guide'
export default buildConfig({
plugins: [
apiGuidePlugin({
title: 'My Project API Guide',
}),
],
// ...rest of config
})
```
## 选项
```
type ApiGuidePluginOptions = {
/** Disable the plugin without removing it. Default: true */
enabled?: boolean
/** Base path under the Payload API route. Default: '/api-guide' */
basePath?: string
/** Title shown in the HTML guide and OpenAPI spec. Default: 'Payload API Guide' */
title?: string
/** Include auth-enabled collections. Default: true */
includeAuth?: boolean
}
```
## 生成的内容
### 来自您的 collections
对于每个 collection，插件会读取：
- slug、labels（单数/复数）
- 所有字段名称、类型、必填状态、本地化
- relationship 字段及其目标
- upload 字段
- 是否存在 `slug` 字段（用于基于 slug 的获取方案）
- 是否启用 drafts
- 是否启用 auth
- 是否为 upload collection
### 来自您的 globals
对于每个 global：
- slug、label
- 所有字段名称和类型
### 生成的输出
**`/api/api-guide`** —— 一个独立的 HTML 页面，介绍如何在此特定项目中使用 REST API。包含每个 collection 的字段表、获取示例以及常见错误部分。
**`/api/api-guide/reference`** —— 从 CDN 加载的 Scalar UI，指向生成的 OpenAPI 规范。
**`/api/api-guide/openapi.json`** —— 完整的 OpenAPI 3.1 规范，包括：
- 每个 collection（`GET`、`POST`、`PATCH`、`DELETE`）和 global（`GET`、`POST`）的路径
- 具有子 `slug` 字段的 collection 的基于 slug 的获取路径
- 共享的查询参数组件（`where`、`depth`、`select`、`limit`、`page`、`sort`、`locale`、`draft`）
- 源自字段定义的每个 collection 的 schema 组件
**`/api/api-guide/agent.md`** —— 为 AI 编程 agent 编写的 markdown 指南。包括：
- 关键规则（slug 获取模式、qs-esm 用法、depth、select、分页）
- `qs-esm` 代码示例
- 每个 collection 的字段表和获取示例
- 常见错误表
**`/api/api-guide/agent.json`** —— 结构化的 JSON 项目地图。包括：
- `apiBase`、`collections`、`globals`
- 每个 collection：字段列表、endpoint URL、slug 字段名称、draft/auth/upload 特征
- 以机器可读形式解释 Payload REST 约定的 `queryGuide` 块
**`/api/api-guide/llms.txt`** —— 遵循 [llms.txt](https://llmstxt.org) 约定的 LLM 入口点文件。列出所有生成的资源及链接。
**`/api/api-guide/query-recipes.json`** —— 每个 collection 的具体查询方案数组：
- 列出文档
- 通过 ID 获取
- 通过 slug 获取（基于 where）
- 分页获取
- 仅获取已发布内容（适用于启用 draft 的 collection）
- 获取带有填充 relationship 的内容
- 仅获取选定字段的内容
- 获取 global
## Agent 工作流
在使用此插件进入 Payload 项目时，推荐的 agent 工作流如下：
1. 读取 `/api/api-guide/llms.txt` 以获取可用资源概览
2. 读取 `/api/api-guide/agent.md` 了解如何查询此项目的规则
3. 检查 `/api/api-guide/agent.json` 获取 collections、字段和 endpoint 模式
4. 使用 `/api/api-guide/openapi.json` 获取正式的 endpoint 参考
5. 使用特定于项目的字段名称和查询模式编写获取代码
## 关键规则
这是 Payload REST 最常见的错误：
```
// Wrong — returns 404 or wrong data
fetch('/api/posts/my-slug')
// Correct — use where query
fetch('/api/posts?where[slug][equals]=my-slug&limit=1')
.then(r => r.json())
.then(({ docs }) => docs[0])
```
使用 [`qs-esm`](https://www.npmjs.com/package/qs-esm) 安全地构建 `where` 查询：
```
import qs from 'qs-esm'
const query = qs.stringify({
where: { slug: { equals: 'my-post' } },
depth: 1,
limit: 1,
})
const res = await fetch(`/api/posts?${query}`)
const { docs } = await res.json()
const post = docs[0]
```
## 环境要求
- Payload `>= 3.85.0`
- Node.js `>= 18.20.2`
## 发布流程
此软件包旨在发布来自 `dist/` 的编译输出。
在本地发布之前：
```
pnpm install
pnpm build
pnpm test:int
npm pack --dry-run
npm publish --dry-run
```
对于首次公开发布，请手动发布：
```
npm publish --access public
```
在该软件包存在于 npm 上之后，为 `@matija2209/payload-agent-api-guide` 配置 npm 受信任的发布，并使用 `.github/workflows/` 中的 GitHub Actions 工作流。
推荐的发布流程：
1. 提交一个 PR，并让 `.github/workflows/ci.yml` 运行构建、lint、集成测试和 e2e。
2. 将 `package.json` 升级到新版本并提交。
3. 创建一个匹配的标签，如 `v1.0.1`。
4. 推送提交和标签。
5. `.github/workflows/publish.yml` 仅在标签与软件包版本完全匹配时才会发布。
## 许可证
MIT
标签：API文档, CMS, LLM集成, MITM代理, OpenAPI, Payload插件, Syscall, Web开发, 自动化攻击