argon-theme/.kiro/steering/phase-3-implementation-plan.md

第三阶段：UI 重构实施计划

📅 开始时间

2026-01-26

🎯 实施目标

完成 settings.php 的 UI 重构，移除旧代码和向后兼容逻辑，实现统一的 AI 功能管理界面。

📋 实施步骤

步骤 1：添加补充的 AJAX 函数到 functions.php

需要添加的函数：

• argon_ajax_get_unified_api() - 获取单个 API 配置
• argon_ajax_test_unified_api() - 测试 API 连通性

文件位置: tmp/additional-ajax-functions.php

插入位置: functions.php 的 AJAX 函数区域（约第 8900 行之后）

步骤 2：在 settings.php 中插入新的 AI 功能部分

插入位置: 第 1985 行之前（在"文章功能"分类之前）

内容来源:

• tmp/new-ai-settings-section.php - HTML 结构
• tmp/new-ai-settings-js.php - JavaScript 交互代码

需要包含的部分:

1. AI 功能 h1 标题
2. API 管理 (h2)
   • 已配置的 API 列表
   • 添加/编辑 API 表单
3. 文章摘要 (h2)
   • 启用开关
   • 选择 API
   • Prompt 设置
   • 排除文章 ID
   • 清除缓存按钮
4. 评论审核 (h2)
   • 启用开关
   • 选择 API
   • 其他设置（保留原有）

步骤 3：移除旧的 AI 设置代码

3.1 移除文章功能中的旧 AI 摘要设置

位置: settings.php 第 1989-2600 行左右

需要移除的内容:

• 启用 AI 文章摘要
• AI 服务商选择
• 10 个提供商的多 API 配置界面
• 摘要提示词
• 排除文章 ID
• 清除缓存按钮

保留的内容:

• 其他文章功能设置（脚注、分享、目录等）

3.2 移除评论设置中的旧 AI 识别部分

位置: settings.php 第 4665-4900 行左右

需要移除的内容:

• 启用 AI 识别
• 检测策略
• 关键字管理
• Prompt 模式等

注意: 这些设置会在新的"评论审核"部分重新添加

步骤 4：更新选项保存逻辑

位置: settings.php 末尾的 argon_update_themeoptions() 函数

需要移除的保存逻辑:

// 移除
argon_update_option('argon_ai_summary_provider');

// 移除所有提供商的 API 配置保存
// argon_ai_openai_apis, argon_ai_anthropic_apis 等

需要添加的保存逻辑:

// 场景化 API 设置
argon_update_option('argon_ai_summary_active_api');
argon_update_option('argon_ai_spam_active_api');

步骤 5：移除 functions.php 中的向后兼容代码

需要移除的内容:

1. 旧的多 API 管理函数 (约第 7000-7150 行):

   • argon_get_provider_apis()
   • argon_get_active_api()
   • argon_add_provider_api()
   • argon_update_provider_api()
   • argon_delete_provider_api()
   • argon_set_active_api()

2. 数据迁移函数 (约第 7200-7250 行):

   • argon_migrate_ai_apis()
   • add_action('after_setup_theme', 'argon_migrate_ai_apis')

3. argon_get_ai_provider_config() 中的向后兼容逻辑:

   • 移除回退到旧系统的代码
   • 只保留从新系统获取配置的逻辑

4. argon_get_active_api_config() 中的向后兼容逻辑:

   • 移除最后的回退代码

保留的内容:

• 所有统一 API 管理函数
• 所有新的 AJAX 函数

步骤 6：清理测试文件

可以删除的文件:

• test-system-status.php
• test-unified-api-system.php
• tmp/ai-settings-new-structure.php
• tmp/new-ai-settings-section.php
• tmp/new-ai-settings-js.php
• tmp/additional-ajax-functions.php

保留的文件:

• 所有 steering 文档（作为历史记录）

🔍 验证清单

功能验证

• 可以添加新 API
• 可以编辑 API
• 可以删除 API
• 可以测试 API 连通性
• 可以刷新模型列表
• 文章摘要可以选择 API
• 评论审核可以选择 API
• 不同场景可以使用不同 API
• 清除摘要缓存功能正常

数据验证

• 旧数据已迁移到新系统
• 设置保存后正确存储
• 刷新页面后配置保持
• AI 功能正常工作

界面验证

• 新界面显示正常
• 响应式布局正常
• 交互动画流畅
• 错误提示清晰

⚠️ 注意事项

1. 备份: 在每一步之前都要备份文件
2. 测试: 每完成一步都要测试功能
3. Git: 每完成一个步骤就提交一次
4. 回滚: 如果出现问题，立即回滚到上一个提交

📊 预计时间

• 步骤 1: 10 分钟
• 步骤 2: 30 分钟
• 步骤 3: 20 分钟
• 步骤 4: 10 分钟
• 步骤 5: 20 分钟
• 步骤 6: 5 分钟
• 测试验证: 30 分钟

总计: 约 2 小时

🎉 完成标志

当以下条件全部满足时，第三阶段完成：

1. ✅ 新的 AI 功能界面正常显示
2. ✅ 所有 API 管理功能正常工作
3. ✅ 文章摘要和评论审核功能正常
4. ✅ 旧代码已完全移除
5. ✅ 向后兼容代码已移除
6. ✅ 所有测试通过
7. ✅ Git 提交完成

📝 Git 提交计划

commit 1: feat: 添加统一 API 管理的补充 AJAX 函数
commit 2: feat: 在 settings.php 中添加新的 AI 功能界面
commit 3: refactor: 移除 settings.php 中的旧 AI 设置代码
commit 4: refactor: 更新选项保存逻辑
commit 5: refactor: 移除 functions.php 中的向后兼容代码
commit 6: chore: 清理临时测试文件
commit 7: docs: 更新 AI 设置重构完成文档

🔗 相关文件

• functions.php - 核心函数
• settings.php - 设置页面
• tmp/additional-ajax-functions.php - 补充函数
• tmp/new-ai-settings-section.php - 新界面 HTML
• tmp/new-ai-settings-js.php - 新界面 JS
• .kiro/steering/phase-1-complete.md - 第一阶段总结
• .kiro/steering/phase-2-testing-guide.md - 第二阶段测试指南
• .kiro/steering/ai-refactor-next-steps.md - 下一步计划