# @ai-stack/payloadcms 中文文档

规范地址：https://npmcn.com/package/%40ai-stack/payloadcms/

版本：4\.0\.1
npm 元数据更新时间：2026-10-13T21:32:38.836Z
中文译文更新时间：2026-11-05T22:58:17.323Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ai-stack/payloadcms
原文对照：https://npmcn.com/package/%40ai-stack/payloadcms/?lang=original
项目主页：https://github.com/ashbuilds/payload-ai#readme
源码仓库：https://github.com/ashbuilds/payload-ai

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：815 kB，274 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^18\.20\.2 \|\| \>=20\.9\.0
- 运行依赖：25 个
- peer 依赖：lexical ^0\.50\.0，payload ^3\.90\.2，@lexical/html ^0\.50\.0，@payloadcms/ui ^3\.90\.2，@payloadcms/translations ^3\.90\.2，@payloadcms/richtext-lexical ^3\.90\.2
- 首次发布：2024-08-25T19:11:43.416Z
- 最新版本发布：2026-10-13T21:32:38.459Z
- 近 30 天下载量：10127（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 28 个）

## 中文简介

**升级到4.0.0?** 读取 [移徙指南](https://npmcn.com/package/%40ai-stack/payloadcms/MIGRATION.md)。引用图像和提取的即时附件现在需要一个明确的存储解析器.

## 安装

```sh
npm install @ai-stack/payloadcms
```

也可以使用：`pnpm add @ai-stack/payloadcms`、`yarn add @ai-stack/payloadcms`、`bun add @ai-stack/payloadcms`

## README

# 有效载荷AI插件

**升级到4.0.0?** 读取 [移徙指南](https://npmcn.com/package/%40ai-stack/payloadcms/MIGRATION.md)。引用图像和提取的即时附件现在需要一个明确的存储解析器.

![Payload AI Plugin](https://npmcn.com/package/%40ai-stack/payloadcms/assets/payload-ai-intro.gif)

**用智能自动化转换内容创造——你的模型,你的方式**

![Supported AI Providers](https://npmcn.com/package/%40ai-stack/payloadcms/assets/providers.png)

* * *

## 这是什么?

有效载荷AI插件是您用于涡轮充电内容创建的秘密武器. 它无缝地将尖端AI能力直接整合到 [有效载荷CMS](https://payloadcms.com/)将你的内容工作流程从乏味变为巨大.

### 🎥 在行动中看到它

-   **[快速演示](https://youtu.be/qaYukeGpuu4)** - 看着魔法发生
-   **[扩展演示](https://youtu.be/LEsuHbKalNY)** - 潜入所有地物
-   **[自定义指南](https://npmcn.com/package/%40ai-stack/payloadcms/guide.md)** - 自己来

* * *

## QQ Beta 通知

此插件正在积极演变 。 我们不断的运输改进和新的特征. 已测试有效载荷v3.88.0.

**快速启动提示 :** 试试看 [有效载荷网站模板](https://github.com/payloadcms/payload/tree/main/templates/website) 对于最平滑的经验.

* * *

## \* 特性

### & RichText 字段

**内容生成魔法 :**

-   ✅ **编曲** - 从零开始生成内容
-   ✅ **校对** - 波兰语你的口语(Beta)
-   ✅ **翻译** - 打破语言障碍
-   ✅ **重写** - 找更好的方法说出来(Beta)
-   🔜 **扩展** - 阐述想法
-   🔜 **总结** - 淡出精髓
-   🔜 **简化** - 把复杂的事情说清楚

### QQ 上传字段

-   🎙️ **语音生成** - 由11Labs & OpenAI提供动力
-   🖼️ **图像生成** - 由OpenAI(DALL-E & GPT-Image-1)提供动力

### 功率用户特性

-   🔌 **带上你的模型** - 不仅限于我们的违约
-   🎛️ **外地一级提示** - 定制每个字段的AI行为
-   🔐 **访问控制** - 锁定谁可以使用AI特性
-   🧠 **提示编辑器** - 微调AI指示
-   🌍 **i18n 辅助** - 与你的多语言设置工作
-   🎨 **自定义组件** - 用你自己的UI扩展

### 就快来了

-   文档分析器
-   事实检查
-   \* 自动化工作流程
-   编辑建议
-   AI聊天助理

* * *

## \* 安装

```bash
pnpm add @ai-stack/payloadcms
```

就这样! 现在,让我们配置它.

* * *

## QQ 快速设置

### 步骤1:配置插件

添加为 `src/payload.config.ts`数字 :

```typescript
import { payloadAiPlugin } from '@ai-stack/payloadcms'

export default buildConfig({
  plugins: [
    payloadAiPlugin({
      collections: {
        [Posts.slug]: true,
      },
      debugging: false,
    }),
  ],
  // ... rest of your config
})
```

### 步骤2: 在您的字段中启用 AI

添加到您的 RichText 字段(例如, `src/collections/Posts/index.ts`:

```typescript
import { PayloadAiPluginLexicalEditorFeature } from '@ai-stack/payloadcms'

fields: [
  {
    name: 'content',
    type: 'richText',
    editor: lexicalEditor({
      features: ({ rootFeatures }) => {
        return [
          HeadingFeature({ enabledHeadingSizes: ['h1', 'h2', 'h3', 'h4'] }),
          // Add this line:
          PayloadAiPluginLexicalEditorFeature(),
        ]
      },
    }),
  },
]
```

### 第3步: 添加您的 API 密钥

有效载荷AI可以从两个方面读取提供者证书:

1.  环境变量.
2.  插件配置, 当证书在有效载荷开始前得到解决时有用, 例如 per- instect 多租户设置, 外部秘密管理器, 或测试 .

#### 备选案文A:环境变量

创建一个 `.env` 中的文件。 为您想要使用的提供者添加密钥 :

```env
# Text Generation - Choose your provider(s)
OPENAI_API_KEY=your-openai-api-key           # OpenAI models (GPT-4, etc.)
ANTHROPIC_API_KEY=your-anthropic-api-key     # Claude models
GOOGLE_GENERATIVE_AI_API_KEY=your-google-key # Gemini models
MINIMAX_API_KEY=your-minimax-api-key         # MiniMax M3 / M2.7 models

# Image Generation - Choose your provider(s)
OPENAI_API_KEY=your-openai-api-key           # DALL-E (uses same key as above)
# OPENAI_ORG_ID=your-org-id                  # Required only for GPT-Image-1 model
GOOGLE_GENERATIVE_AI_API_KEY=your-google-key # Imagen (uses same key as above)

# Audio/Voice Generation - Choose your provider(s)
ELEVENLABS_API_KEY=your-elevenlabs-api-key   # ElevenLabs voices
OPENAI_API_KEY=your-openai-api-key           # OpenAI TTS (uses same key as above)

# Optional: Use custom OpenAI-compatible endpoint
# OPENAI_BASE_URL=https://api.openai.com/v1
```

**您只需要您计划使用的提供者的钥匙 .** 根据你的喜好来混合和匹配!

#### 选项B:插件配置

如果你想在开始的时候自己解开秘密,就通过 `providers`。配置值优先于环境变量,省略值仍然回到 `.env`。 。 。 .

```typescript
payloadAiPlugin({
  collections: {
    [Posts.slug]: true,
  },
  providers: {
    openai: {
      apiKey: process.env.PAYLOAD_AI_OPENAI_API_KEY,
      baseURL: process.env.PAYLOAD_AI_OPENAI_BASE_URL,
      orgId: process.env.PAYLOAD_AI_OPENAI_ORG_ID,
    },
  },
})
```

支持的提供者密钥 : `openai`, (中文(简体) ), `anthropic`, (中文(简体) ), `google`, (中文(简体) ), `elevenLabs`,以及 `minimax`。 。 。 .

**重要内容:** 更新后重新启动您的服务器 `.env` 或插件设置!

您可能需要重新生成导入地图 :

```bash
payload generate:importmap
```

* * *

## 高级配置

**QQ 访问控制与多选项设置**

生成需要来自 `access.generate`源文件, 并且内置媒体的创建也强制要求用户的收藏、字段和 每个文档权限。 配置 `overrideInstructions.access` 限制能读的人 或编辑指令; `access.settings` 控制设置 UI 不替换这些设置 收藏规则。 自定义 `mediaUpload` 召回必须执行自己的访问检查,因为 如下所示。 信任的初始化和教学种子与用户请求分开运行.

### 参考图像和存储

参考图像现在需要服务器侧 `resolveReferenceImage` 调用。 这是一个 断开图像编辑的更改,在提示中使用样本图像或图像 URL,以及用于 文本生成方式 `extractAttachments` 启用 。 文本到图像 生成时没有引用,则不变。 插件不获取引用 URL, 转发登录证书,或要求Node DNS/HTTP API进行参考解析.

对于选中的样本图像, 插件从 `uploadCollectionSlug` (默认 : `media`)与呼叫者的有效载荷读取权限和 `depth: 0` 之前,他引用解析器。 使用文档的ID从一个 固定存储桶或其他应用控制的商店。 不要使用文档的 URL 或文件名作为未选中的网络目的或文件系统路径。 访问所隐藏的字段 解析器将无法使用控制 .

解决者收到 `{ source, request, signal, maxBytes }` 并且必须返回一个PNG,JPEG, 或网络P `Blob`。 。 。 . `source.kind` 实值 `media` (与 `collection` 和授权 `document`(中文(简体) ) 或者说 `url` (与 **无信任** 从快取出 URL). 拒绝 URL 源, 除非您 应用程序可以将其映射到明确批准的存储对象并授权访问. 仅仅检查一个 URL 是否使用 HTTPS 是不够的 。 优先储存有固定的 SDK 任意获取 URL 的 buckle/ account ; 不转发 cookie 或 符号 .

例如,连接应用程序的存储读取器:

```typescript
resolveReferenceImage: async ({ source, signal, maxBytes }) => {
  if (source.kind !== 'media') {
    throw new Error('Only selected media can be used as reference images.')
  }
  // Application-owned helper: map this authorized ID to your fixed bucket/object key.
  // Enforce maxBytes during loading and honor signal to cancel outstanding work.
  return readReferenceBlobFromStorage({
    collection: source.collection,
    id: source.document.id,
    signal,
    maxBytes,
  })
},
```

`readReferenceBlobFromStorage` 上面是一个应用程序帮助器,而不是一个有效载荷或插件 API. 它的执行取决于您的存储适配器。 该插件验证返回的 Blob, 拒绝20米B以上的空文件或文件,30秒后停止等待. 解决者 必须在加载时执行限制,以避免缓冲过大的对象;取消是 合作和需要荣誉 `signal`。MIME 检查不验证图像文件内容. 内建文本模型通过相同的回调和通过字节解决已提取附件 给AI SDK。 自动SDK附件下载被禁用 。 URL 仍然是普通文本 当附件提取被禁用时. 自定义生成模型继续负责它们自己提出的任何网络请求.

```typescript
import { payloadAiPlugin } from '@ai-stack/payloadcms'

export default buildConfig({
  plugins: [
    payloadAiPlugin({
      collections: {
        [Posts.slug]: true,
      },

      // Enable AI for globals too
      globals: {
        [Home.slug]: true,
      },

      // Development helpers
      debugging: false,
      disableSponsorMessage: false,
      generatePromptOnInit: process.env.NODE_ENV !== 'production',

      // Specify media collection for GPT-Image-1
      uploadCollectionSlug: 'media',

      // Lock down AI features
      access: {
        generate: ({ req }) => req.user?.role === 'admin',
        settings: ({ req }) => req.user?.role === 'admin',
      },

      // Customize language options
      options: {
        enabledLanguages: ['en-US', 'zh-SG', 'zh-CN', 'en'],
      },

      // Reference additional fields in prompts
      promptFields: [
        {
          name: 'url',
          collections: ['images'],
        },
        {
          name: 'markdown',
          async getter(doc, { collection }) {
            return docToMarkdown(collection, doc)
          },
        },
      ],

      // Control initial prompt generation
      seedPrompts: ({ path }) => {
        if (path.endsWith('.meta.description')) {
          return {
            data: {
              prompt: 'Generate SEO-friendly meta description: {{markdown}}',
            },
          }
        }
        if (path.endsWith('.slug')) return false // Disable for slugs
        return undefined // Use defaults
      },

      // Custom media upload (useful for multi-tenant)
      mediaUpload: async (result, { request, collection }) => {
        return request.payload.create({
          collection,
          data: result.data,
          file: result.file,
          overrideAccess: false,
          req: request,
        })
      },
    }),
  ],
})
```
**自定义组件和字段**

自定义字段不会自动继承AI能力. 如果您的 AI 启用字段没有显示 Compose 设置, 请手动添加此组件路径 :

```
@ai-stack/payloadcms/fields#ComposeField
```

**除错提示 :** 启用 `debugging: true` 在您的插件配置中查看哪些字段启用了 AI.

* * *

## 页:1

需要更多细节吗? 看看这个 **[完整设置指南](https://npmcn.com/package/%40ai-stack/payloadcms/guide.md)** 用于:

-   自定义模型配置
-   高级快速工程
-   外地定制
-   解决问题提示

* * *

## 支持此项目

我空闲时间用"Q"建造的 如果此插件能节省您的工作时间, 请考虑为未来的开发加油 !

[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://www.buymeacoffee.com/ashbuilds)

每杯咖啡都会让AI模型运行 和新的特性运输。 谢谢

* * *

## 捐款

我们爱贡献者! 无论你正在修复打字机,建议特征,还是建设新的能力,所有的贡献都是受欢迎的.

### 贡献方式

-   报告错误
-   建议的特性
-   \* 改进文件编制
-   提交拉动请求

加入对话 [有效载荷的磁盘](https://discord.com/channels/967097582721572934/1264949995656843345) 让我们一起打造一个神奇的东西!

### 地方发展

想黑进插件吗? 这就是:

#### 先决条件

-   节点.js(版本为 `.nvmrc`(中文(简体) )
-   小时
-   数据库连接( Postgres 或 MongoDB)
-   可选: AI 提供者 API 密钥

#### 设置

```bash
# 1. Install dependencies
pnpm install

# 2. Set up environment
cp dev/.env.example dev/.env
# Edit dev/.env with your DATABASE_URI, PAYLOAD_SECRET, and API keys

# 3. Start development server
pnpm dev
# Admin UI available at http://localhost:3000

# 4. Generate types/importmap if needed
pnpm generate:importmap
pnpm generate:types
```

#### 发展 工作流量

-   插件来源 : `src/`
-   测试应用程序 : `dev/`
-   编辑文件 `src/` 并刷新以查看变化

#### 测试和质量

```bash
pnpm test                    # Run all tests
pnpm lint                    # ESLint
pnpm prettier --write .      # Format code
pnpm build                   # Build plugin
```

#### 在另一个工程中测试

```bash
pnpm pack
# In your other project:
pnpm add /path/to/ai-plugin-*.tgz
```

#### 项目结构

```
├── src/              # Plugin source code
├── dev/              # Test Payload app
│   ├── int.spec.ts   # Integration tests
│   └── e2e.spec.ts   # E2E tests
└── README.md         # You are here!
```

* * *

由社区制作

[恒星在 GitHub](https://github.com/ashbuilds/payload-ai) 二. 支助 [加入磁盘](https://discord.com/channels/967097582721572934/1264949995656843345) 二. 支助 [阅读指南](https://npmcn.com/package/%40ai-stack/payloadcms/guide.md)

## 常见问题

### @ai-stack/payloadcms 是什么？

升级到4\.0\.0? 读取 移徙指南。引用图像和提取的即时附件现在需要一个明确的存储解析器\.

### 如何安装 @ai-stack/payloadcms？

在项目目录运行 npm install @ai-stack/payloadcms，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：lexical（^0\.50\.0）、payload（^3\.90\.2）、@lexical/html（^0\.50\.0）、@payloadcms/ui（^3\.90\.2）、@payloadcms/translations（^3\.90\.2）、@payloadcms/richtext-lexical（^3\.90\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ai-stack/payloadcms 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ai-stack/payloadcms 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ai-stack/payloadcms 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^18\.20\.2 \|\| \>=20\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ai-stack/payloadcms 可以商用吗？

@ai-stack/payloadcms 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ai-stack/payloadcms 的下载量有多少？

根据 npm 官方下载统计，@ai-stack/payloadcms 在 2026/10/05 – 2026/11/03 这 30 天内被下载 10,127 次，日均约 338 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ai-stack/payloadcms 还在维护吗？

最新版本 4\.0\.1 发布于 2026/10/14（23 天前）；至今共发布 65 个版本，其中过去 12 个月发布了 28 个；首次发布于 2024/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。