feat: 添加统一 API 系统测试脚本和文档

- 创建 test-unified-api-system.php 测试脚本 - 测试功能包括：函数存在性、数据迁移、API配置、向后兼容等 - 添加阶段性实施计划文档 - 添加新 AI 设置界面草稿
2026-01-26 13:25:49 +08:00
parent 5254ee0d8b
commit 2c25caae23
4 changed files with 852 additions and 0 deletions
--- a/.kiro/steering/ai-refactor-next-steps.md
+++ b/.kiro/steering/ai-refactor-next-steps.md
@@ -0,0 +1,144 @@
+# AI 设置重构 - 下一步工作
+
+## 已完成的工作 ✅
+
+### 1. functions.php 更新
+- ✅ 添加数据迁移函数 `argon_migrate_ai_apis()`
+- ✅ 添加统一 API 管理函数
+  - `argon_get_all_apis()` - 获取所有 API
+  - `argon_get_api_by_id($api_id)` - 获取指定 API
+  - `argon_add_api($config)` - 添加 API
+  - `argon_update_api($api_id, $config)` - 更新 API
+  - `argon_delete_api($api_id)` - 删除 API
+  - `argon_set_active_api_for_scenario($scenario, $api_id)` - 设置场景使用的 API
+  - `argon_get_active_api_config($scenario)` - 获取场景的活动 API 配置
+- ✅ 更新 `argon_get_ai_provider_config()` 支持新数据结构
+- ✅ 添加新的 AJAX 处理函数
+  - `argon_ajax_add_unified_api()`
+  - `argon_ajax_update_unified_api()`
+  - `argon_ajax_delete_unified_api()`
+  - `argon_ajax_set_active_unified_api()`
+  - `argon_ajax_get_all_unified_apis()`
+- ✅ 在主题加载时自动迁移旧数据
+
+### 2. 草稿文件
+- ✅ 创建新的 AI 设置界面草稿 (`tmp/ai-settings-new-structure.php`)
+- ✅ 设计了新的界面结构和交互逻辑
+
+## 待完成的工作 📋
+
+### 3. settings.php 重构
+
+#### 3.1 移除旧的 AI 设置部分
+需要移除的内容：
+- 第 1985-2400 行：旧的文章功能 - AI 摘要部分（包含按提供商分组的 API 配置）
+- 第 4662-5100 行：评论设置中的 AI 垃圾评论识别部分
+
+#### 3.2 添加新的 AI 功能部分
+在合适的位置（建议在第 1985 行之前）插入新的 AI 功能部分：
+
+```php
+<!-- ========== AI 功能 ========== -->
+<h1 style="color: #5e72e4; margin-top: 50px; font-size: 32px;"><?php _e('AI 功能', 'argon');?></h1>
+
+<!-- API 管理 (h2) -->
+<!-- 文章摘要 (h2) -->
+<!-- 评论审核 (h2) -->
+```
+
+#### 3.3 添加 JavaScript 交互代码
+需要添加完整的 JavaScript 代码来处理：
+- 添加/编辑/删除 API
+- 测试 API 连通性
+- 刷新模型列表
+- 切换活动 API
+- 表单验证
+
+#### 3.4 更新选项保存逻辑
+在 settings.php 末尾的保存函数中：
+- 移除旧的 API 配置保存逻辑
+- 添加新的统一 API 配置保存逻辑
+- 保存场景化的活动 API 设置
+
+### 4. 测试
+
+#### 4.1 数据迁移测试
+- 测试从旧的多 API 系统迁移到新系统
+- 验证所有 API 配置都正确迁移
+- 验证活动 API 设置正确
+
+#### 4.2 功能测试
+- 测试添加新 API
+- 测试编辑 API
+- 测试删除 API
+- 测试切换活动 API
+- 测试 API 连通性测试功能
+- 测试模型列表刷新功能
+
+#### 4.3 场景测试
+- 测试文章摘要生成（使用新的 API 系统）
+- 测试垃圾评论检测（使用新的 API 系统）
+- 测试不同场景使用不同 API
+
+#### 4.4 向后兼容测试
+- 测试没有新数据时的回退逻辑
+- 测试旧数据的自动迁移
+
+### 5. 文档更新
+- 更新用户文档，说明新的 API 管理方式
+- 更新开发文档，说明新的数据结构
+
+## 实施建议
+
+由于 settings.php 的重构涉及大量代码修改（需要移除约 500 行旧代码，添加约 800 行新代码），建议：
+
+1. **分步实施**：
+   - 第一步：只添加新的 AI 功能部分，保留旧的设置（共存）
+   - 第二步：测试新功能是否正常工作
+   - 第三步：移除旧的设置部分
+   - 第四步：全面测试
+
+2. **备份策略**：
+   - 在每一步之前都创建备份
+   - 使用 Git 分支进行开发
+   - 保留回滚方案
+
+3. **用户通知**：
+   - 在更新日志中说明重大变更
+   - 提供迁移指南
+   - 说明新功能的优势
+
+## 风险评估
+
+### 高风险项
+- ❗ settings.php 重构可能影响现有用户的配置
+- ❗ 数据迁移可能失败，导致 API 配置丢失
+- ❗ JavaScript 代码可能与现有代码冲突
+
+### 缓解措施
+- ✅ 已实现自动数据迁移和向后兼容
+- ✅ 保留旧数据作为备份
+- ✅ 使用独立的 AJAX 端点，避免冲突
+- 📋 需要充分测试后再发布
+
+## 时间估算
+
+- settings.php 重构：2-3 小时
+- JavaScript 代码编写：1-2 小时
+- 测试和调试：2-3 小时
+- 文档更新：1 小时
+
+**总计：6-9 小时**
+
+## 下一步行动
+
+1. 用户确认是否继续进行 settings.php 的重构
+2. 如果继续，建议创建一个新的 Git 分支
+3. 按照上述步骤逐步实施
+4. 每完成一个步骤就进行测试和提交
+
+## 备注
+
+- 当前已完成的 functions.php 修改已经提交（commit 5254ee0）
+- 新的数据结构和 API 已经可以使用
+- 只需要更新 settings.php 的界面部分即可完成整个重构
--- a/.kiro/steering/ai-settings-refactor-plan.md
+++ b/.kiro/steering/ai-settings-refactor-plan.md
@@ -0,0 +1,161 @@
+# AI 设置页面重构方案
+
+## 重构目标
+
+将当前按提供商分组的 API 管理方式改为统一的 API 列表管理，并重新组织 AI 功能的设置结构。
+
+## 当前结构问题
+
+1. **API 管理分散**：每个提供商独立管理 API，用户需要在 10 个提供商之间切换
+2. **结构不清晰**：AI 摘要和评论审核分散在不同的一级分类中
+3. **用户体验差**：添加 API 时需要先选择提供商，然后才能配置
+
+## 新结构设计
+
+### 页面结构
+```
+AI 功能 (独立 h1，不在分类编号中)
+├── API 管理 (h2)
+│   ├── 已配置的 API 列表（统一显示所有提供商的 API）
+│   └── 添加新 API（输入密钥 → 选择提供商 → 选择模型）
+├── 文章摘要 (h2)
+│   ├── 启用 AI 摘要
+│   ├── 默认服务商选择
+│   ├── Prompt 设置
+│   └── 排除文章设置
+└── 评论审核 (h2)
+    ├── 启用 AI 识别
+    ├── 实时检测模式
+    ├── 关键字管理
+    ├── Prompt 模式
+    └── 其他配置
+```
+
+### 数据结构变更
+
+#### 旧数据结构
+```php
+// 每个提供商独立存储
+argon_ai_openai_apis = [
+    {id: 'api_1', name: '主API', api_key: 'sk-xxx', ...}
+]
+argon_ai_anthropic_apis = [...]
+// ... 10 个提供商
+```
+
+#### 新数据结构
+```php
+// 统一存储所有 API
+argon_ai_apis = [
+    {
+        id: 'api_1',
+        name: '主 OpenAI API',
+        provider: 'openai',
+        api_key: 'sk-xxx',
+        api_endpoint: '',
+        model: 'gpt-4o-mini',
+        is_active: false,
+        created_at: 1234567890
+    },
+    {
+        id: 'api_2',
+        name: '备用 Claude API',
+        provider: 'anthropic',
+        api_key: 'sk-ant-xxx',
+        api_endpoint: '',
+        model: 'claude-3-5-sonnet-20241022',
+        is_active: true,
+        created_at: 1234567891
+    }
+]
+
+// 当前使用的 API（按场景）
+argon_ai_summary_active_api = 'api_1'  // 文章摘要使用的 API
+argon_ai_spam_active_api = 'api_2'     // 垃圾评论检测使用的 API
+```
+
+## 实施步骤
+
+### 步骤 1：数据迁移函数
+创建 `argon_migrate_ai_apis()` 函数，将旧的分散数据迁移到新的统一结构。
+
+### 步骤 2：更新核心函数
+- 修改 `argon_get_ai_provider_config()` 支持新数据结构
+- 添加 `argon_get_all_apis()` 获取所有 API
+- 添加 `argon_get_api_by_id($api_id)` 获取指定 API
+- 添加 `argon_add_api($config)` 添加 API
+- 添加 `argon_update_api($api_id, $config)` 更新 API
+- 添加 `argon_delete_api($api_id)` 删除 API
+- 添加 `argon_set_active_api_for_scenario($scenario, $api_id)` 设置场景使用的 API
+
+### 步骤 3：重构 settings.php
+- 移除原有的按提供商分组的 API 配置界面
+- 创建新的统一 API 列表界面
+- 重新组织 AI 功能的设置结构
+
+### 步骤 4：更新 AJAX 处理函数
+- 更新所有 API 管理相关的 AJAX 函数
+- 支持新的数据结构
+
+### 步骤 5：向后兼容
+- 在主题加载时自动检测并迁移旧数据
+- 保留旧数据作为备份
+
+## 界面设计
+
+### API 管理界面
+```
+┌─ 已配置的 API ─────────────────────────────────────┐
+│                                                     │
+│ ● 主 OpenAI API (gpt-4o-mini)                      │
+│   OpenAI (ChatGPT) | sk-xxx...                     │
+│   [测试] [编辑] [删除]                              │
+│                                                     │
+│ ○ 备用 Claude API (claude-3-5-sonnet)              │
+│   Anthropic (Claude) | sk-ant-xxx...               │
+│   [测试] [编辑] [删除]                              │
+│                                                     │
+│ [+ 添加新 API]                                      │
+└─────────────────────────────────────────────────────┘
+
+添加/编辑 API:
+┌─────────────────────────────────────────────────────┐
+│ 配置名称: [主 OpenAI API_________________]          │
+│ API 密钥: [sk-xxx_______________________] [显示]    │
+│ 提供商:   [OpenAI (ChatGPT) ▼]                     │
+│ API 端点: [_____________________________] (可选)    │
+│ 模型:     [gpt-4o-mini__________________] [刷新]    │
+│                                                     │
+│ [保存] [取消]                                        │
+└─────────────────────────────────────────────────────┘
+```
+
+### 文章摘要设置
+```
+启用 AI 摘要: [启用 ▼]
+默认使用 API: [主 OpenAI API ▼]
+Prompt 设置: [...]
+排除文章 ID: [...]
+```
+
+### 评论审核设置
+```
+启用 AI 识别: [☑] 启用 AI 自动识别垃圾评论
+默认使用 API: [备用 Claude API ▼]
+实时检测模式: [智能抽查 ▼]
+...
+```
+
+## 优势
+
+1. **统一管理**：所有 API 在一个列表中，一目了然
+2. **灵活配置**：不同场景可以使用不同的 API
+3. **易于添加**：添加 API 时直接输入密钥和选择提供商
+4. **更好的 UX**：不需要在多个提供商之间切换
+
+## 注意事项
+
+1. **数据迁移**：确保旧数据能够正确迁移到新结构
+2. **向后兼容**：保留旧数据作为备份，以防迁移失败
+3. **测试充分**：需要测试所有 AI 功能是否正常工作
+4. **文档更新**：更新用户文档说明新的配置方式