插件介绍 - 数字先锋API文档

# 数字先锋 API

WordPress AI 写作插件 MVP，对接数字先锋 API (https://api.cxsee.com) 自动生成文章内容。

**版本**: 0.2.0
下载地址：[点击下载插件包](https://docs.cxsee.com/cxsee-ai-writer.zip "点击下载插件包")

## 功能特性

- ✅ 后台设置页（设置 → 数字先锋 API）
- ✅ REST API: `POST /wp-json/ai/v1/generate`
- ✅ **Gutenberg 编辑器** - 三个位置显示 AI 生成按钮（顶部/文档面板/菜单）
- ✅ **经典编辑器** - 文章编辑页面顶部显示 AI 生成功能面板
- ✅ 自动检测编辑器类型，无需配置
- ✅ **API Key 可见/隐藏切换** - 保护隐私，方便核对
- ✅ **模型列表动态加载** - 自动获取可用模型，一键选择
- ✅ **API Key 在线测试** - 实时验证密钥有效性
- ✅ 输入 sanitize / 输出 escape
- ✅ **兼容 RiPro 等主题** - 无论是否启用 Gutenberg 都能正常使用

## 安装说明

### 1. 上传插件

```bash
# 方法 A: 通过 WordPress 后台
1. 将 `cxsee-ai-writer` 文件夹打包为 ZIP
2. WordPress 后台 → 插件 → 安装插件 → 上传插件
3. 选择 ZIP 文件并安装
4. 启用插件

# 方法 B: 手动上传
1. 将 `cxsee-ai-writer` 文件夹上传到 `/wp-content/plugins/`
2. WordPress 后台 → 插件 → 启用 "数字先锋 API"
```

### 2. 配置 API

1. 进入 **设置 → 数字先锋 API**
2. 填写 **API Key**（必填）
3. 点击 **👁️ 显示** 按钮可查看/隐藏 API Key
4. 点击 **🧪 测试** 按钮验证 API Key 是否有效
5. 点击 **🔄 加载模型列表** 获取可用模型
6. 从列表中选择想要的模型（自动保存）
7. 保存设置

### 3. 使用 AI 写作

**插件自动检测您使用的编辑器类型，并提供相应界面：**

---

#### 🟦 Gutenberg 编辑器（区块编辑器）

打开文章编辑器后，编辑 器下方 AI 生成按钮：

![](/uploads/editor/20260418/img_69e28d20793b83.43747978.png)

```
**点击任意按钮后弹出窗口：**
- 输入关键词（必填）
- 选择语气风格
- 设置目标字数
- 点击 **"✨ 立即生成"**
- 成功后自动回填标题和正文

---

#### 🟩 经典编辑器

如果您使用经典编辑器（或主题禁用了 Gutenberg），会在文章标题下方看到一个醒目的 AI 生成面板：

```
┌─────────────────────────────────────────────────────────┐
│ [文章标题输入框]                                         │
├─────────────────────────────────────────────────────────┤
│ ✨ AI 生成文章                                           │
│ 使用 AI 快速生成文章内容                                 │
│                                                          │
│ 关键词：[________________]  语气风格：[professional▼]   │
│ 目标字数：[1000  ]        标题结构：[使用 H2/H3 标题▼]   │
│                                                          │
│ [✨ 立即生成]                                            │
└─────────────────────────────────────────────────────────┘
```

**点击"立即生成"后：**
- 自动生成标题 → 填入标题框
- 自动生成正文 → 填入编辑器
- 自动生成摘要 → 填入摘要框

---

### ℹ️ 常见问题

**Q: 我的主题禁用了 Gutenberg，插件还能用吗？**  
A: 可以！插件会自动检测编辑器类型，在经典编辑器中显示独立面板。

**Q: 需要修改主题文件吗？**  
A: 不需要！插件已内置 Gutenberg 和经典编辑器双重支持。

**Q: 为什么看不到按钮/面板？**  
A: 请先确认：
1. 已启用插件
2. 已配置 API Key（设置 → 数字先锋 API）
3. 具有 `edit_posts` 权限

---

## API 文档

官方 API 文档：[https://docs.cxsee.com]

---

## REST API 调用示例

### cURL 示例

```bash
# 获取 WP REST nonce（需要先登录）
# 然后在浏览器控制台运行：wpApiSettings.nonce

# 调用生成接口
curl -X POST "https://your-site.com/wp-json/ai/v1/generate" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE_HERE" \
  -d '{
    "keyword": "人工智能发展趋势",
    "tone": "professional",
    "word_count": 1500,
    "with_headings": true
  }'
```

### JavaScript 示例

```javascript
const response = await fetch('/wp-json/ai/v1/generate', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-WP-Nonce': wpApiSettings.nonce
    },
    body: JSON.stringify({
        keyword: '人工智能发展趋势',
        tone: 'professional',
        word_count: 1500,
        with_headings: true
    })
});

const result = await response.json();
console.log(result.data.title);
console.log(result.data.content);
```

### PHP 示例（WordPress 内）

```php
$response = wp_remote_post(rest_url('ai/v1/generate'), array(
    'method' => 'POST',
    'headers' => array(
        'Content-Type' => 'application/json',
        'X-WP-Nonce' => wp_create_nonce('wp_rest')
    ),
    'body' => json_encode(array(
        'keyword' => '人工智能发展趋势',
        'tone' => 'professional',
        'word_count' => 1500,
        'with_headings' => true
    ))
));

$result = json_decode(wp_remote_retrieve_body($response), true);
```

---

## API 响应格式

### 成功响应

```json
{
  "success": true,
  "data": {
    "title": "文章标题",
    "summary": "2-3 句摘要",
    "content": "<h2>标题</h2><p>正文内容...</p>",
    "tags": ["标签 1", "标签 2", "标签 3"],
    "meta_description": "SEO 描述（150-160 字符）"
  }
}
```

### 错误响应

```json
{
  "code": "missing_api_key",
  "message": "API Key not configured.",
  "data": { "status": 500 }
}
```

---

## 设置项说明

| 字段 | 说明 | 必填 |
|------|------|------|
| API Key | 数字先锋 API 密钥 | 是 |
| Mode | Free / Pro 模式 | 否（默认 Free） |
| Model | 模型名称 | 否（默认 qwen3.5-plus） |
| Custom Endpoint | 自定义 API 端点 | 否（仅 Pro 模式可用） |

---

## 文件结构

```
cxsee-ai-writer/
├── cxsee-ai-writer.php          # 主入口文件
├── README.md                     # 本文件
├── includes/
│   ├── class-ai-client.php       # API 客户端
│   └── class-digital-pioneer-api.php # 主类（设置页 + REST）
├── assets/
│   └── js/
│       └── editor-toolbar.js     # Gutenberg 编辑器按钮
├── debug-helper.php              # 调试工具（脚本加载检测）
├── debug-editor-check.php        # 编辑器类型诊断（临时使用）
└── classic-editor-support.php    # 经典编辑器兼容方案（RiPro 备选）
```

---

## 系统要求

- WordPress 6.0+
- PHP 7.4+
- 有效的数字先锋 API Key
- **Gutenberg 区块编辑器**（经典编辑器需要额外配置，见下方）

---

## RiPro 主题用户特别注意

如果您使用的是 **RiPro-V5** 主题，按钮不显示是因为主题可能禁用了 Gutenberg 编辑器。

### 解决方案（三选一）

#### 方案 A: 强制启用 Gutenberg（推荐）

在主题 `functions.php` 添加一行代码：

```php
// 文件：wp-content/themes/ripro-v5/functions.php
// 在末尾添加：
add_filter('use_block_editor_for_post_type', '__return_true');
```

保存后刷新文章编辑页面，应该能看到按钮。

#### 方案 B: 使用经典编辑器支持（备选）

如果 RiPro 主题必须使用经典编辑器，可以启用经典编辑器支持：

```php
// 将 classic-editor-support.php 内容复制到主题 functions.php
// 或者在插件中引入此文件
```

这会在经典编辑器上方添加一个 AI 生成面板。

#### 方案 C: 主题设置

检查 RiPro 主题设置中是否有：
- "启用区块编辑器"
- "Gutenberg 支持"
- "使用经典编辑器"（关闭此选项）

---

## 常见问题排查

### Q: 编辑器中没有看到 "✨ AI 生成" 按钮

**按钮位置（三个地方）：**
1. **顶部发布区域** - "保存草稿" 和 "发布" 按钮之间
2. **右侧「文档」面板** - 面板顶部
3. **右上角 ⋮ 菜单** - 插件 → ✨ AI 生成

**检查步骤：**

1. **确认在文章编辑页面**
   - 必须是「新建文章」或「编辑文章」页面
   - 其他页面不会显示

2. **检查浏览器控制台（重要！）**
   - 按 `F12` 打开开发者工具
   - 切换到 **Console** 标签
   - 查看是否有错误信息
   - 应该看到：`✅ 数字先锋 API 插件已加载`

3. **确认使用 Gutenberg 编辑器（关键！）**
   - 数字先锋 API **仅支持 Gutenberg 区块编辑器**
   - 如果使用经典编辑器或主题禁用了 Gutenberg，按钮不会显示
   - **RiPro 主题用户注意：** RiPro 可能默认禁用 Gutenberg
   
   **检查方法：**
   - 编辑文章时，看到右上角有 "⋮" 三个点菜单 → 是 Gutenberg ✅
   - 看到的是传统可视化编辑器（类似 Word） → 是经典编辑器 ❌
   
   **启用 Gutenberg（RiPro 主题）：**
   ```php
   // 在主题 functions.php 添加这行
   add_filter('use_block_editor_for_post_type', '__return_true');
   ```
   
   或者在 RiPro 主题设置中查找 "启用区块编辑器" 选项。

4. **确认插件已启用**
   - WordPress 后台 → 插件 → 已安装插件
   - 确认 "数字先锋 API" 状态为「启用」

5. **检查 API Key 配置**
   - 设置 → 数字先锋 API
   - 确认 API Key 已填写并保存

6. **清除缓存**
   - 浏览器缓存：`Ctrl+Shift+Delete` 清除
   - 如有缓存插件，清除服务器缓存

7. **使用调试工具**
   - 将 `debug-editor-check.php` 内容复制到主题 `functions.php`
   - 刷新文章编辑页面
   - 查看页面顶部的黄色诊断框
   - 查看浏览器控制台的调试日志

### Q: 使用 RiPro 主题，按钮不显示

**原因：** RiPro 主题可能禁用了 Gutenberg 编辑器。

**解决方法：**

1. **方法 A: 主题 functions.php 强制启用**
   ```php
   // 在 wp-content/themes/ripro-v5/functions.php 末尾添加
   add_filter('use_block_editor_for_post_type', '__return_true');
   ```

2. **方法 B: 主题设置**
   - 进入 RiPro 主题设置
   - 查找 "编辑器设置" 或 "Gutenberg"
   - 启用区块编辑器

3. **方法 C: 使用插件**
   - 安装 "Disable Classic Editor" 插件
   - 强制使用 Gutenberg

4. **方法 D: 临时切换主题测试**
   - 暂时启用 Twenty Twenty-Four 主题
   - 检查按钮是否显示
   - 如果显示，确认是 RiPro 主题问题

### Q: 控制台显示 "wp.plugins not available"

这表示 Gutenberg 编辑器未正确加载。尝试：
1. 清除浏览器缓存
2. 确认使用的是区块编辑器（Gutenberg），不是经典编辑器
3. 检查主题是否兼容 Gutenberg

### Q: REST API 返回 403 错误

- 确认已登录 WordPress
- 确认用户有 `edit_posts` 权限
- 检查 nonce 是否正确传递

### Q: 如何调试插件加载问题

临时将 `debug-helper.php` 内容添加到主题 `functions.php`：

```php
// 复制 debug-helper.php 内容到这里
```

然后在文章编辑页面查看 HTML 源码中的调试注释。

### Q: REST API 返回 403 错误

- 确认已登录 WordPress
- 确认用户有 `edit_posts` 权限
- 检查 nonce 是否正确传递

---

## 安全说明

- 所有输入经过 `sanitize_*` 处理
- 所有输出经过 `esc_*` 处理
- REST API 需要登录且具有 `edit_posts` 权限
- 所有请求需要 nonce 校验
- 所有 PHP 文件包含 `defined('ABSPATH') || exit;`

---

上一篇：没有了下一篇：如何获取API Key令牌