argon-theme/.kiro/steering/phase-2-testing-guide.md

第二阶段：测试和验证指南

📅 开始时间

2026-01-26

🎯 测试目标

验证统一 API 管理系统的后端功能是否正常工作，为第三阶段的 UI 重构做准备。

📋 测试清单

1. 系统状态检查 ✅

测试文件: test-system-status.php

访问方式:

https://your-site.com/wp-content/themes/argon/test-system-status.php

检查项目:

• 所有核心函数已加载
• 数据迁移状态正常
• API 配置正确显示
• 场景配置正常工作
• 旧数据已备份

预期结果:

• 显示"✓ 统一 API 管理系统已就绪！"
• 如果有旧配置，应该已经迁移到新系统
• 文章摘要和评论审核场景应该有活动的 API

---

2. 详细功能测试 ✅

测试文件: test-unified-api-system.php

访问方式:

https://your-site.com/wp-content/themes/argon/test-unified-api-system.php

检查项目:

• 函数存在性检查通过
• 数据迁移成功
• API 配置列表正确显示
• 旧数据检查正常
• 场景化 API 测试通过
• 向后兼容性测试通过

预期结果:

• 所有测试项显示绿色 ✓
• 测试总结显示"✓ 统一 API 管理系统已就绪！"

---

3. AI 功能实际测试

3.1 文章摘要测试

步骤:

1. 确保已配置文章摘要的活动 API
2. 创建或编辑一篇文章
3. 发布文章
4. 查看文章页面，检查是否显示 AI 摘要

检查点:

• AI 摘要正常生成
• 使用的是正确的 API（检查日志）
• 没有错误信息

如果失败:

• 检查 WordPress 错误日志
• 查看文章的 _argon_ai_summary_error meta
• 确认 API 密钥和端点正确

3.2 评论审核测试

步骤:

1. 确保已配置评论审核的活动 API
2. 启用 AI 垃圾评论检测
3. 发表一条测试评论
4. 检查评论是否被正确处理

检查点:

• AI 检测正常工作
• 使用的是正确的 API
• 检测结果合理

如果失败:

• 检查 WordPress 错误日志
• 查看评论的 meta 数据
• 确认 API 密钥和端点正确

---

4. 小米 Mimo API 专项测试

背景: 用户反馈小米 Mimo 无法使用

测试步骤:

4.1 检查配置

// 在 test-system-status.php 中查看
// 小米 Mimo 的配置是否正确

检查点:

• API 密钥格式正确
• 端点是否为 https://api.mimo.xiaomi.com/v1/chat/completions
• 模型是否为 MiMo-V2-Flash 或其他有效模型

4.2 手动测试 API

创建测试脚本 test-xiaomi-api.php:

<?php
require_once('../../../wp-load.php');

if (!current_user_can('manage_options')) {
    wp_die('权限不足');
}

// 获取小米 Mimo 配置
$config = argon_get_active_api_config('summary');

if ($config['provider'] !== 'xiaomi') {
    echo '当前活动 API 不是小米 Mimo';
    exit;
}

// 测试 API 调用
$api_key = $config['api_key'];
$api_endpoint = !empty($config['api_endpoint']) 
    ? $config['api_endpoint'] 
    : 'https://api.mimo.xiaomi.com/v1/chat/completions';
$model = !empty($config['model']) ? $config['model'] : 'MiMo-V2-Flash';

$data = [
    'model' => $model,
    'messages' => [
        [
            'role' => 'user',
            'content' => '你好，这是一个测试。请回复"测试成功"。'
        ]
    ],
    'max_tokens' => 100
];

$response = wp_remote_post($api_endpoint, [
    'headers' => [
        'Content-Type' => 'application/json',
        'Authorization' => 'Bearer ' . $api_key
    ],
    'body' => json_encode($data),
    'timeout' => 30
]);

echo '<h1>小米 Mimo API 测试</h1>';
echo '<h2>请求配置</h2>';
echo '<pre>';
echo 'API 端点: ' . $api_endpoint . "\n";
echo '模型: ' . $model . "\n";
echo 'API 密钥: ' . substr($api_key, 0, 12) . '...' . "\n";
echo '</pre>';

echo '<h2>响应结果</h2>';
if (is_wp_error($response)) {
    echo '<p style="color: red;">错误: ' . $response->get_error_message() . '</p>';
} else {
    $status_code = wp_remote_retrieve_response_code($response);
    $body = wp_remote_retrieve_body($response);
    
    echo '<p>状态码: ' . $status_code . '</p>';
    echo '<h3>响应内容</h3>';
    echo '<pre>' . htmlspecialchars($body) . '</pre>';
    
    if ($status_code === 200) {
        $result = json_decode($body, true);
        if (isset($result['choices'][0]['message']['content'])) {
            echo '<p style="color: green;">✓ API 调用成功！</p>';
            echo '<p>AI 回复: ' . htmlspecialchars($result['choices'][0]['message']['content']) . '</p>';
        }
    } else {
        echo '<p style="color: red;">✗ API 调用失败</p>';
    }
}
?>

检查点:

• API 返回 200 状态码
• 响应包含有效的 JSON
• 能够正确解析 AI 回复

常见问题:

1. 401 Unauthorized: API 密钥无效或过期
2. 403 Forbidden: API 密钥没有权限
3. 404 Not Found: API 端点错误
4. 429 Too Many Requests: 超过速率限制
5. 500 Internal Server Error: 服务器错误

---

5. 向后兼容性测试

测试场景: 确保旧代码仍然能正常工作

测试步骤:

1. 测试旧的 API 获取函数:

// 在 test-unified-api-system.php 中已包含
$old_config = argon_get_ai_provider_config('openai');

检查点:

• 函数返回有效配置
• 配置包含 api_key, api_endpoint, model, provider
• 如果新系统有数据，优先使用新系统
• 如果新系统无数据，回退到旧系统

2. 测试多 API 管理函数:

// 旧的多 API 函数应该仍然可用
$openai_apis = argon_get_provider_apis('openai');
$active_api = argon_get_active_api('openai');

检查点:

• 旧函数仍然可用
• 返回的数据格式正确

---

6. 错误日志检查

位置:

• WordPress 调试日志: wp-content/debug.log
• 服务器错误日志: 根据服务器配置

检查内容:

• 没有 PHP Fatal Error
• 没有 PHP Warning（除非是已知的）
• 没有 AI API 调用错误
• 没有数据迁移错误

如何启用调试: 在 wp-config.php 中添加：

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

---

📊 测试结果记录

系统状态

• ✅ 通过
• ⚠️ 部分通过（记录问题）
• ❌ 失败（记录错误）

问题记录:

问题 1: [描述]
- 错误信息: 
- 复现步骤:
- 预期行为:
- 实际行为:

问题 2: [描述]
...

AI 功能测试

• ✅ 文章摘要正常
• ✅ 评论审核正常
• ✅ 小米 Mimo 正常

问题记录:

[如有问题，在此记录]

向后兼容性

• ✅ 旧函数正常工作
• ✅ 数据迁移成功
• ✅ 回退机制正常

---

🔧 问题排查指南

问题 1: 数据迁移失败

症状: argon_ai_apis_migrated 为 'false'

排查步骤:

1. 检查是否有旧数据
2. 查看错误日志
3. 手动执行迁移函数
4. 检查数据库权限

解决方案:

// 手动触发迁移
delete_option('argon_ai_apis_migrated');
argon_migrate_ai_apis();

问题 2: API 配置为空

症状: argon_get_all_apis() 返回空数组

排查步骤:

1. 检查是否有旧配置
2. 检查数据迁移状态
3. 查看数据库中的 argon_ai_apis 选项

解决方案:

• 如果有旧配置但未迁移，手动触发迁移
• 如果没有旧配置，需要在设置页面添加新配置

问题 3: AI 功能不工作

症状: 文章摘要或评论审核不生成结果

排查步骤:

1. 检查是否配置了活动 API
2. 检查 API 密钥是否有效
3. 查看错误日志
4. 测试 API 连通性

解决方案:

• 确保设置了活动 API
• 验证 API 密钥和端点
• 检查网络连接
• 查看 API 提供商的状态

问题 4: 小米 Mimo 无法使用

可能原因:

1. API 密钥格式错误
2. API 端点错误
3. 模型名称错误
4. 网络连接问题
5. API 配额用尽

排查步骤:

1. 使用 test-xiaomi-api.php 测试
2. 检查 API 密钥格式（应该是 sk- 开头）
3. 确认端点为 https://api.mimo.xiaomi.com/v1/chat/completions
4. 确认模型为 MiMo-V2-Flash
5. 查看详细的错误响应

---

✅ 测试通过标准

满足以下条件即可进入第三阶段（UI 重构）：

1. 核心功能:

   • 所有核心函数正常工作
   • 数据迁移成功
   • API 配置正确存储和读取

2. AI 功能:

   • 文章摘要正常生成
   • 评论审核正常工作
   • 至少一个 AI 提供商可用

3. 向后兼容:

   • 旧函数仍然可用
   • 旧数据已备份
   • 回退机制正常

4. 无严重错误:

   • 没有 PHP Fatal Error
   • 没有数据丢失
   • 没有功能退化

---

📝 测试完成后的行动

如果测试通过 ✅

1. 更新文档，记录测试结果
2. 准备进入第三阶段（UI 重构）
3. 创建 Git 分支用于 UI 开发

如果测试失败 ❌

1. 记录所有问题和错误信息
2. 分析问题原因
3. 修复问题
4. 重新测试
5. 确认修复后再进入下一阶段

---

🔗 相关文件

• test-system-status.php - 快速状态检查
• test-unified-api-system.php - 详细功能测试
• test-xiaomi-api.php - 小米 Mimo 专项测试（需创建）
• functions.php - 核心函数实现
• .kiro/steering/phase-1-complete.md - 第一阶段总结
• .kiro/steering/ai-refactor-next-steps.md - 下一步计划

---

📞 需要帮助？

如果在测试过程中遇到问题，请提供：

1. 测试脚本的完整输出
2. WordPress 错误日志内容
3. 具体的错误信息和截图
4. 复现步骤

我将帮助您分析和解决问题。