快速开始

先理解目标

WordPress AI 开发不是直接把模型接口写进某个按钮里。更稳的方式是：

1. 运行站点先连接模型服务。
2. 开发者把主题或插件里的具体功能包装成 Ability。
3. Ability 负责权限、输入、输出和执行。
4. AI Client 负责把 prompt 发给模型。
5. 需要自动化时，只允许 AI 调用你明确开放的只读或低风险能力。

这样做的好处是，功能后续可以被后台按钮、REST、AI 助手、批处理任务重复使用，不会每个地方都写一套模型调用代码。

现实前提

多数用户找 AI 帮忙二开时，只会提供子比主题源码，最多再提供自己的子主题或插件文件。AI 不应该要求用户把完整 wp-includes、AI 插件、Provider 插件、数据库和服务器配置全部打包过来。

正确做法是：

1. 用本站文档理解 WordPress AI Client、Abilities API、Provider 和 AI 插件的通用规则。
2. 用用户提供的子比主题源码判断扩展入口，例如 inc/functions/ai、文章 SEO 字段、Ajax、Hook、Meta 读写方式。
3. 把新增 AI 能力写到独立插件或子主题里，尽量不直接改主题核心文件。
4. 只有涉及运行环境时，才让用户确认 WordPress 版本、AI 插件、Provider 插件和 API Key 是否已经安装配置。

如果你是把源码发给 AI 助手做二开，先看 只提供主题源码时。那一页专门说明：哪些信息该从主题源码里找，哪些底层规则直接看本站文档，哪些运行状态才需要问用户。

运行站点要准备什么

站点真正运行 AI 功能时，需要具备这些条件：

这几项是运行环境条件，不等于用户需要把这些源码或密钥发给 AI 助手。开发时只需要确认“是否已安装、是否已启用、是否已连接”，不要让用户暴露 API Key。

用户提供给 AI 的材料

用户通常只需要提供：

建议第一版只做“生成但不保存”的功能。用户看到结果后手动确认，再保存到文章字段、分类字段、主题已有 Meta 或扩展插件自己的数据表。

开发者从哪里下手

第一次写功能时，按这个顺序做：

1. 注册一个 Ability 分类，例如 zibll-ai-ext。
2. 写一个只读 Ability，例如 zibll-ai-ext/read-post-context。
3. 给它写 input_schema，明确需要 post_id。
4. 给它写 output_schema，明确返回标题、摘要、正文。
5. 写 permission_callback，用 WordPress capability 判断权限。
6. 在 PHP 里直接执行 Ability，确认读数据没问题。
7. 再写一个 generate-* Ability，在里面调用 wp_ai_client_prompt()。
8. 生成结果稳定后，再写 save-* 或 apply-* 能力保存数据。

不要把读取、生成、保存、发布全部塞进一个函数。拆开以后，每一步都能单独测试，也方便用户确认。

推荐交付结构

即使用户只提供了子比主题源码，也不建议直接改 wp-content/themes/zibll 的核心文件。更稳的交付方式是独立插件：

wp-content/plugins/zibll-ai-ext-demo/
├─ zibll-ai-ext-demo.php
└─ includes/
   ├─ abilities.php
   ├─ ai-client.php
   └─ admin.php

如果用户已有子主题，也可以把少量 UI 按钮和样式放到子主题里，但 Ability 注册、AI 调用、保存逻辑仍建议放在独立插件中，方便停用、升级和排查。

最小插件入口可以这样写：

<?php
/**
 * Plugin Name: Zibll AI Extension Demo
 * Description: Demo WordPress AI Client abilities.
 */

defined( 'ABSPATH' ) || exit;

require __DIR__ . '/includes/abilities.php';
require __DIR__ . '/includes/ai-client.php';
require __DIR__ . '/includes/admin.php';

第一版功能怎么选

推荐从这些低风险功能开始：

不建议第一版就做：

• 自动发布文章。
• 自动删除评论。
• 自动扣积分或改余额。
• 自动改订单状态。
• 自动给用户发消息。

这些能力不是不能做，而是必须放在人工确认、权限校验、日志记录和回滚方案之后。

成功标准

一个合格的第一版 WordPress AI 功能，应当满足：

• API Key 不出现在前端。
• 用户没有权限时不能执行。
• 输入有 schema，输出有 schema。
• AI 生成失败时返回 WP_Error，页面能给用户明确提示。
• 只生成建议，不自动覆盖用户内容。
• 保存动作由用户点击触发。
• 日志里能看到 provider、model、耗时和错误。