feat: 更新 Mermaid 到 v11 并优化错误处理
- 更新 Mermaid 库版本从 v10 升级到 v11.12.2 - 优化错误处理逻辑，避免重复嵌套错误容器 - 修复查看源代码时可能出现的嵌套报错问题 - 改进渲染前检查，跳过已处理的错误容器和已渲染的图表 - 优化重新渲染逻辑，只处理成功渲染的图表，排除错误容器 - 增强代码提取逻辑，优先使用传入的代码参数 - 添加主题切换时的智能判断，避免不必要的重新渲染 - 更新 functions.php 中的 CDN 地址到 v11 - 更新 settings.php 中的预览功能 CDN 地址到 v11 - 改进错误容器的 DOM 结构，使用独立元素而非 innerHTML
This commit is contained in:
911
.kiro/specs/ai-spam-detection-optimization/design.md
Normal file
911
.kiro/specs/ai-spam-detection-optimization/design.md
Normal file
@@ -0,0 +1,911 @@
|
||||
# Design Document
|
||||
|
||||
## Overview
|
||||
|
||||
本设计文档描述了 Argon 主题 AI 垃圾评论检测优化功能的技术实现方案。系统采用模块化架构，将 Prompt 管理、置信度评分、上下文构建、学习机制等功能解耦，便于维护和扩展。
|
||||
|
||||
核心设计理念：
|
||||
- **灵活性优先**：通过多级 Prompt 和可配置阈值适应不同场景
|
||||
- **准确性保障**：引入置信度评分和上下文信息提升判断质量
|
||||
- **成本可控**：提供不同模式平衡准确性和 API 费用
|
||||
- **持续优化**：通过学习机制不断改进检测效果
|
||||
|
||||
## Architecture
|
||||
|
||||
系统采用分层架构设计：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "表现层"
|
||||
A[设置界面] --> B[评论列表界面]
|
||||
end
|
||||
|
||||
subgraph "业务逻辑层"
|
||||
C[AI_Detector 主控制器]
|
||||
D[Prompt_Engine]
|
||||
E[Context_Builder]
|
||||
F[Learning_Module]
|
||||
G[Threshold_Manager]
|
||||
end
|
||||
|
||||
subgraph "数据访问层"
|
||||
H[WordPress Options API]
|
||||
I[WordPress Comments API]
|
||||
J[Feedback Database]
|
||||
end
|
||||
|
||||
subgraph "外部服务"
|
||||
K[OpenAI API]
|
||||
L[其他 AI Provider]
|
||||
end
|
||||
|
||||
A --> C
|
||||
B --> C
|
||||
C --> D
|
||||
C --> E
|
||||
C --> F
|
||||
C --> G
|
||||
D --> K
|
||||
D --> L
|
||||
E --> I
|
||||
F --> J
|
||||
G --> H
|
||||
C --> H
|
||||
C --> I
|
||||
```
|
||||
|
||||
### 核心组件职责
|
||||
|
||||
1. **AI_Detector**: 主控制器，协调各模块完成检测流程
|
||||
2. **Prompt_Engine**: 管理不同模式的 Prompt 模板，生成检测请求
|
||||
3. **Context_Builder**: 收集和构建评论上下文信息
|
||||
4. **Learning_Module**: 记录反馈数据，分析误判率，提供优化建议
|
||||
5. **Threshold_Manager**: 管理检测阈值和处理策略
|
||||
|
||||
## Components and Interfaces
|
||||
|
||||
### 1. Prompt_Engine
|
||||
|
||||
**职责**: 管理和生成不同模式的 Prompt
|
||||
|
||||
**接口**:
|
||||
```php
|
||||
class Argon_Spam_Prompt_Engine {
|
||||
/**
|
||||
* 获取指定模式的 Prompt
|
||||
* @param string $mode 模式: minimal, standard, enhanced, custom
|
||||
* @param array $context 评论上下文信息
|
||||
* @return string 完整的 Prompt
|
||||
*/
|
||||
public function get_prompt($mode, $context);
|
||||
|
||||
/**
|
||||
* 获取自定义 Prompt 模板
|
||||
* @return string 自定义模板
|
||||
*/
|
||||
public function get_custom_template();
|
||||
|
||||
/**
|
||||
* 保存自定义 Prompt 模板
|
||||
* @param string $template 模板内容
|
||||
* @return bool 是否成功
|
||||
*/
|
||||
public function save_custom_template($template);
|
||||
|
||||
/**
|
||||
* 验证 Prompt 模板格式
|
||||
* @param string $template 模板内容
|
||||
* @return array ['valid' => bool, 'errors' => array]
|
||||
*/
|
||||
public function validate_template($template);
|
||||
}
|
||||
```
|
||||
|
||||
**Prompt 模板结构**:
|
||||
|
||||
极简模式（minimal）:
|
||||
```
|
||||
你是一个垃圾评论检测助手。请判断以下评论是否为垃圾评论。
|
||||
|
||||
评论内容: {content}
|
||||
评论者: {author}
|
||||
网站: {url}
|
||||
|
||||
请以 JSON 格式返回:
|
||||
{
|
||||
"is_spam": true/false,
|
||||
"confidence": 0.0-1.0,
|
||||
"reason": "简短理由"
|
||||
}
|
||||
```
|
||||
|
||||
标准模式（standard）:
|
||||
```
|
||||
你是一个专业的垃圾评论检测助手。请根据以下标准判断评论是否为垃圾:
|
||||
1. 内容质量: 是否有实质性内容
|
||||
2. 相关性: 是否与文章主题相关
|
||||
3. 用户行为: 用户名、邮箱、网站是否可疑
|
||||
4. 语言特征: 是否包含垃圾评论常见模式
|
||||
|
||||
评论信息:
|
||||
- 内容: {content}
|
||||
- 评论者: {author}
|
||||
- 邮箱域名: {email_domain}
|
||||
- 网站: {url}
|
||||
- 文章标题: {post_title}
|
||||
- 文章摘要: {post_excerpt}
|
||||
|
||||
用户历史:
|
||||
- 历史评论数: {comment_count}
|
||||
- 通过率: {approval_rate}
|
||||
|
||||
请以 JSON 格式返回:
|
||||
{
|
||||
"is_spam": true/false,
|
||||
"confidence": 0.0-1.0,
|
||||
"reason": "详细理由",
|
||||
"suggestion": "auto/review/approve"
|
||||
}
|
||||
```
|
||||
|
||||
增强模式（enhanced）:
|
||||
```
|
||||
你是一个高级垃圾评论检测专家。请进行多维度深度分析:
|
||||
|
||||
1. 内容合规性分析
|
||||
- 是否包含违规内容
|
||||
- 是否包含广告推广
|
||||
- 是否包含恶意链接
|
||||
|
||||
2. 内容质量分析
|
||||
- 是否有实质性观点
|
||||
- 语言表达是否自然
|
||||
- 是否为复制粘贴内容
|
||||
|
||||
3. 用户行为分析
|
||||
- 用户名是否可疑（随机字符、营销词汇）
|
||||
- 邮箱域名是否可信
|
||||
- 网站是否为垃圾站点
|
||||
|
||||
4. 上下文相关性分析
|
||||
- 评论与文章主题的相关度
|
||||
- 评论时间是否异常（批量发送）
|
||||
- 用户历史行为是否正常
|
||||
|
||||
评论信息:
|
||||
- 内容: {content}
|
||||
- 评论者: {author}
|
||||
- 邮箱域名: {email_domain}
|
||||
- 网站: {url}
|
||||
- IP 地址段: {ip_segment}
|
||||
- 评论时间: {comment_time}
|
||||
|
||||
文章信息:
|
||||
- 标题: {post_title}
|
||||
- 摘要: {post_excerpt}
|
||||
- 分类: {post_category}
|
||||
|
||||
用户历史:
|
||||
- 历史评论数: {comment_count}
|
||||
- 通过率: {approval_rate}
|
||||
- 最近评论时间: {last_comment_time}
|
||||
|
||||
请以 JSON 格式返回:
|
||||
{
|
||||
"is_spam": true/false,
|
||||
"confidence": 0.0-1.0,
|
||||
"reason": "综合分析理由",
|
||||
"suggestion": "auto/review/approve",
|
||||
"analysis": {
|
||||
"content_compliance": "分析结果",
|
||||
"content_quality": "分析结果",
|
||||
"user_behavior": "分析结果",
|
||||
"context_relevance": "分析结果"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Context_Builder
|
||||
|
||||
**职责**: 收集和构建评论上下文信息
|
||||
|
||||
**接口**:
|
||||
```php
|
||||
class Argon_Spam_Context_Builder {
|
||||
/**
|
||||
* 构建评论上下文
|
||||
* @param WP_Comment $comment 评论对象
|
||||
* @param string $privacy_level 隐私级别: standard, strict
|
||||
* @return array 上下文信息数组
|
||||
*/
|
||||
public function build_context($comment, $privacy_level = 'standard');
|
||||
|
||||
/**
|
||||
* 获取文章信息
|
||||
* @param int $post_id 文章 ID
|
||||
* @return array ['title' => string, 'excerpt' => string, 'category' => string]
|
||||
*/
|
||||
private function get_post_info($post_id);
|
||||
|
||||
/**
|
||||
* 获取用户历史统计
|
||||
* @param string $email 用户邮箱
|
||||
* @return array ['count' => int, 'approval_rate' => float, 'last_time' => string]
|
||||
*/
|
||||
private function get_user_stats($email);
|
||||
|
||||
/**
|
||||
* 脱敏处理
|
||||
* @param array $context 原始上下文
|
||||
* @param string $privacy_level 隐私级别
|
||||
* @return array 脱敏后的上下文
|
||||
*/
|
||||
private function sanitize_context($context, $privacy_level);
|
||||
}
|
||||
```
|
||||
|
||||
**上下文数据结构**:
|
||||
```php
|
||||
[
|
||||
'content' => string, // 评论内容
|
||||
'author' => string, // 评论者名称
|
||||
'email_domain' => string, // 邮箱域名（脱敏）
|
||||
'url' => string, // 网站 URL
|
||||
'ip_segment' => string, // IP 地址段（脱敏）
|
||||
'comment_time' => string, // 评论时间
|
||||
'post_title' => string, // 文章标题
|
||||
'post_excerpt' => string, // 文章摘要（截取 200 字符）
|
||||
'post_category' => string, // 文章分类
|
||||
'comment_count' => int, // 用户历史评论数
|
||||
'approval_rate' => float, // 用户评论通过率
|
||||
'last_comment_time' => string // 最近评论时间
|
||||
]
|
||||
```
|
||||
|
||||
### 3. AI_Detector
|
||||
|
||||
**职责**: 主控制器，协调检测流程
|
||||
|
||||
**接口**:
|
||||
```php
|
||||
class Argon_Spam_AI_Detector {
|
||||
/**
|
||||
* 检测评论是否为垃圾
|
||||
* @param WP_Comment $comment 评论对象
|
||||
* @param bool $async 是否异步检测
|
||||
* @return array 检测结果
|
||||
*/
|
||||
public function detect($comment, $async = true);
|
||||
|
||||
/**
|
||||
* 处理检测结果
|
||||
* @param WP_Comment $comment 评论对象
|
||||
* @param array $result 检测结果
|
||||
* @return void
|
||||
*/
|
||||
public function process_result($comment, $result);
|
||||
|
||||
/**
|
||||
* 批量检测评论
|
||||
* @param array $comment_ids 评论 ID 数组
|
||||
* @param callable $progress_callback 进度回调函数
|
||||
* @return array 检测结果统计
|
||||
*/
|
||||
public function batch_detect($comment_ids, $progress_callback = null);
|
||||
|
||||
/**
|
||||
* 测试 Prompt
|
||||
* @param string $content 测试内容
|
||||
* @param string $mode Prompt 模式
|
||||
* @return array 检测结果
|
||||
*/
|
||||
public function test_prompt($content, $mode);
|
||||
}
|
||||
```
|
||||
|
||||
**检测结果数据结构**:
|
||||
```php
|
||||
[
|
||||
'is_spam' => bool, // 是否垃圾评论
|
||||
'confidence' => float, // 置信度 0-1
|
||||
'reason' => string, // 判断理由
|
||||
'suggestion' => string, // 处理建议: auto/review/approve
|
||||
'analysis' => array, // 详细分析（仅增强模式）
|
||||
'timestamp' => int, // 检测时间戳
|
||||
'mode' => string, // 使用的 Prompt 模式
|
||||
'api_provider' => string // API 提供商
|
||||
]
|
||||
```
|
||||
|
||||
### 4. Learning_Module
|
||||
|
||||
**职责**: 记录反馈数据，分析误判率
|
||||
|
||||
**接口**:
|
||||
```php
|
||||
class Argon_Spam_Learning_Module {
|
||||
/**
|
||||
* 记录反馈
|
||||
* @param int $comment_id 评论 ID
|
||||
* @param array $ai_result AI 检测结果
|
||||
* @param string $admin_action 管理员操作: approve, spam, trash
|
||||
* @return bool 是否成功
|
||||
*/
|
||||
public function record_feedback($comment_id, $ai_result, $admin_action);
|
||||
|
||||
/**
|
||||
* 计算误判率
|
||||
* @param int $days 统计天数
|
||||
* @return array ['total' => int, 'false_positive' => int, 'false_negative' => int, 'rate' => float]
|
||||
*/
|
||||
public function calculate_error_rate($days = 30);
|
||||
|
||||
/**
|
||||
* 获取优化建议
|
||||
* @return array 建议列表
|
||||
*/
|
||||
public function get_optimization_suggestions();
|
||||
|
||||
/**
|
||||
* 导出反馈数据
|
||||
* @param int $days 导出天数
|
||||
* @return string CSV 格式数据
|
||||
*/
|
||||
public function export_feedback($days = 30);
|
||||
|
||||
/**
|
||||
* 获取统计数据
|
||||
* @return array 统计信息
|
||||
*/
|
||||
public function get_statistics();
|
||||
}
|
||||
```
|
||||
|
||||
**反馈记录数据结构**:
|
||||
```php
|
||||
[
|
||||
'comment_id' => int,
|
||||
'ai_result' => array, // AI 检测结果
|
||||
'admin_action' => string, // 管理员操作
|
||||
'timestamp' => int,
|
||||
'pattern_hash' => string, // 评论特征哈希
|
||||
'is_error' => bool // 是否误判
|
||||
]
|
||||
```
|
||||
|
||||
### 5. Threshold_Manager
|
||||
|
||||
**职责**: 管理检测阈值和处理策略
|
||||
|
||||
**接口**:
|
||||
```php
|
||||
class Argon_Spam_Threshold_Manager {
|
||||
/**
|
||||
* 获取当前阈值
|
||||
* @return float 阈值 0.5-1.0
|
||||
*/
|
||||
public function get_threshold();
|
||||
|
||||
/**
|
||||
* 设置阈值
|
||||
* @param float $threshold 阈值
|
||||
* @return bool 是否成功
|
||||
*/
|
||||
public function set_threshold($threshold);
|
||||
|
||||
/**
|
||||
* 判断是否应该自动处理
|
||||
* @param array $result 检测结果
|
||||
* @return bool 是否自动处理
|
||||
*/
|
||||
public function should_auto_process($result);
|
||||
|
||||
/**
|
||||
* 获取推荐配置
|
||||
* @param string $blog_size 博客规模: small, medium, large
|
||||
* @return array 推荐配置
|
||||
*/
|
||||
public function get_recommended_config($blog_size);
|
||||
}
|
||||
```
|
||||
|
||||
## Data Models
|
||||
|
||||
### 1. 配置选项（WordPress Options）
|
||||
|
||||
```php
|
||||
// Prompt 模式
|
||||
'argon_spam_detection_prompt_mode' => 'standard' // minimal, standard, enhanced, custom
|
||||
|
||||
// 自定义 Prompt 模板
|
||||
'argon_spam_detection_custom_prompt' => ''
|
||||
|
||||
// 检测阈值
|
||||
'argon_spam_detection_threshold' => 0.85 // 0.5-1.0
|
||||
|
||||
// 智能抽查比例
|
||||
'argon_spam_detection_sample_rate' => 30 // 0-100
|
||||
|
||||
// 隐私级别
|
||||
'argon_spam_detection_privacy_level' => 'standard' // standard, strict
|
||||
|
||||
// API 配置
|
||||
'argon_spam_detection_api_provider' => 'openai' // openai, custom
|
||||
'argon_spam_detection_api_key' => ''
|
||||
'argon_spam_detection_api_endpoint' => ''
|
||||
|
||||
// 实时检测开关
|
||||
'argon_spam_detection_realtime_enabled' => true
|
||||
|
||||
// 自动禁用配置
|
||||
'argon_spam_detection_auto_disable_after_errors' => 3
|
||||
'argon_spam_detection_auto_disable_duration' => 3600 // 秒
|
||||
|
||||
// 统计数据
|
||||
'argon_spam_detection_stats' => [
|
||||
'total_detections' => 0,
|
||||
'auto_processed' => 0,
|
||||
'manual_reviewed' => 0,
|
||||
'api_calls_this_month' => 0,
|
||||
'last_reset_time' => 0
|
||||
]
|
||||
```
|
||||
|
||||
### 2. 评论元数据（Comment Meta）
|
||||
|
||||
```php
|
||||
// AI 检测结果
|
||||
'argon_spam_ai_result' => [
|
||||
'is_spam' => bool,
|
||||
'confidence' => float,
|
||||
'reason' => string,
|
||||
'suggestion' => string,
|
||||
'analysis' => array,
|
||||
'timestamp' => int,
|
||||
'mode' => string,
|
||||
'api_provider' => string
|
||||
]
|
||||
|
||||
// 检测状态
|
||||
'argon_spam_detection_status' => 'pending' // pending, completed, failed
|
||||
|
||||
// 重新检测次数
|
||||
'argon_spam_redetection_count' => 0
|
||||
```
|
||||
|
||||
### 3. 反馈数据库表
|
||||
|
||||
创建自定义表存储反馈数据：
|
||||
|
||||
```sql
|
||||
CREATE TABLE {prefix}_argon_spam_feedback (
|
||||
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
|
||||
comment_id BIGINT UNSIGNED NOT NULL,
|
||||
ai_is_spam TINYINT(1) NOT NULL,
|
||||
ai_confidence FLOAT NOT NULL,
|
||||
ai_reason TEXT,
|
||||
ai_suggestion VARCHAR(20),
|
||||
admin_action VARCHAR(20) NOT NULL,
|
||||
is_error TINYINT(1) NOT NULL,
|
||||
pattern_hash VARCHAR(64),
|
||||
created_at DATETIME NOT NULL,
|
||||
PRIMARY KEY (id),
|
||||
KEY comment_id (comment_id),
|
||||
KEY created_at (created_at),
|
||||
KEY is_error (is_error)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||||
```
|
||||
|
||||
## Correctness Properties
|
||||
|
||||
*属性是一个特征或行为，应该在系统的所有有效执行中保持为真——本质上是关于系统应该做什么的正式陈述。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*
|
||||
|
||||
### Property 1: Prompt 模式完整性
|
||||
|
||||
*对于任何* 上下文数据，Prompt_Engine 应该能够为所有三种预设模式（minimal、standard、enhanced）生成有效的 Prompt，且每个 Prompt 都包含 JSON 格式要求。
|
||||
|
||||
**Validates: Requirements 1.1, 1.6**
|
||||
|
||||
### Property 2: Token 消耗范围约束
|
||||
|
||||
*对于任何* 上下文数据和任何预设模式，生成的 Prompt 的 token 消耗应该在该模式指定的范围内（极简：100-150，标准：200-300，增强：300-500）。
|
||||
|
||||
**Validates: Requirements 1.2, 1.3, 1.4**
|
||||
|
||||
### Property 3: 自定义模板往返一致性
|
||||
|
||||
*对于任何* 有效的自定义 Prompt 模板字符串，保存后再读取应该得到相同的模板内容。
|
||||
|
||||
**Validates: Requirements 1.5**
|
||||
|
||||
### Property 4: 检测结果数据结构完整性
|
||||
|
||||
*对于任何* 评论，AI_Detector 返回的结果应该包含 is_spam（布尔值）、confidence（0-1 范围的浮点数）、reason（字符串）、suggestion（字符串）四个必需字段。
|
||||
|
||||
**Validates: Requirements 2.1, 2.2, 3.1**
|
||||
|
||||
### Property 5: 置信度分类正确性
|
||||
|
||||
*对于任何* 置信度值，系统应该根据以下规则正确分类：>= 0.9 为"非常确定"，0.7-0.9 为"比较确定"，0.5-0.7 为"中等确定"，< 0.5 为"不太确定"。
|
||||
|
||||
**Validates: Requirements 2.3, 2.4, 2.5, 2.6**
|
||||
|
||||
### Property 6: 处理建议逻辑正确性
|
||||
|
||||
*对于任何* 检测结果和阈值配置，当 confidence >= threshold 且 is_spam = true 时应返回 "auto"，当 0.5 <= confidence < threshold 且 is_spam = true 时应返回 "review"，其他情况应返回 "approve"。
|
||||
|
||||
**Validates: Requirements 3.2, 3.3, 3.4**
|
||||
|
||||
### Property 7: 阈值配置往返一致性
|
||||
|
||||
*对于任何* 有效的阈值值（0.5-1.0），保存后再读取应该得到相同的阈值。
|
||||
|
||||
**Validates: Requirements 3.5**
|
||||
|
||||
### Property 8: 评论处理状态正确性
|
||||
|
||||
*对于任何* 评论和处理建议，当 suggestion = "auto" 时评论应被标记为垃圾，当 suggestion = "review" 时评论应被标记为待审核，当 suggestion = "approve" 时评论应被正常发布。
|
||||
|
||||
**Validates: Requirements 3.6, 3.7, 3.8**
|
||||
|
||||
### Property 9: 上下文数据完整性
|
||||
|
||||
*对于任何* 评论，Context_Builder 构建的上下文应该包含文章标题、文章摘要、用户历史评论数、用户通过率、评论时间戳、IP 地址等所有必需字段。
|
||||
|
||||
**Validates: Requirements 4.1, 4.2, 4.3**
|
||||
|
||||
### Property 10: 上下文传递正确性
|
||||
|
||||
*对于任何* 构建的上下文，生成的 Prompt 应该包含该上下文中的关键信息（如文章标题、评论内容等）。
|
||||
|
||||
**Validates: Requirements 4.4**
|
||||
|
||||
### Property 11: 敏感信息脱敏正确性
|
||||
|
||||
*对于任何* 包含敏感信息的评论，Context_Builder 返回的上下文中的邮箱应只保留域名，IP 地址应只保留前两段。
|
||||
|
||||
**Validates: Requirements 4.5, 10.1, 10.2**
|
||||
|
||||
### Property 12: 摘要截取正确性
|
||||
|
||||
*对于任何* 超过 200 字符的文章摘要，Context_Builder 返回的摘要应该被截取为 200 字符。
|
||||
|
||||
**Validates: Requirements 4.6**
|
||||
|
||||
### Property 13: 反馈记录完整性
|
||||
|
||||
*对于任何* 管理员审核操作，Learning_Module 记录的反馈应该包含 AI 判断结果、管理员决策、时间戳、评论特征哈希等所有必需字段。
|
||||
|
||||
**Validates: Requirements 5.1, 5.2**
|
||||
|
||||
### Property 14: 误判率计算正确性
|
||||
|
||||
*对于任何* 反馈数据集，Learning_Module 计算的误判率应该等于（误判数量 / 总检测数量）。
|
||||
|
||||
**Validates: Requirements 5.3**
|
||||
|
||||
### Property 15: 优化建议触发正确性
|
||||
|
||||
*对于任何* 反馈数据集，当某类型评论的误判率超过 30% 时，Learning_Module 应该生成相应的优化建议。
|
||||
|
||||
**Validates: Requirements 5.4**
|
||||
|
||||
### Property 16: 反馈数据导出格式正确性
|
||||
|
||||
*对于任何* 反馈数据集，导出的 CSV 数据应该包含所有必需列（comment_id、ai_result、admin_action、timestamp 等），且格式符合 CSV 标准。
|
||||
|
||||
**Validates: Requirements 5.5**
|
||||
|
||||
### Property 17: 统计数据准确性
|
||||
|
||||
*对于任何* 反馈数据集，Learning_Module 返回的统计数据（总检测数、自动处理数、误判数）应该与实际数据一致。
|
||||
|
||||
**Validates: Requirements 5.6**
|
||||
|
||||
### Property 18: API 错误默认值正确性
|
||||
|
||||
*对于任何* API 错误响应，AI_Detector 应该使用默认值（is_spam=false, confidence=0, suggestion="approve"）并允许评论正常发布。
|
||||
|
||||
**Validates: Requirements 8.1, 8.2**
|
||||
|
||||
### Property 19: 自动禁用机制正确性
|
||||
|
||||
*对于任何* API 调用序列，当连续失败次数达到配置的阈值（默认 3 次）时，系统应该自动禁用实时检测指定时长（默认 1 小时）。
|
||||
|
||||
**Validates: Requirements 8.3**
|
||||
|
||||
### Property 20: 错误日志容量限制
|
||||
|
||||
*对于任何* 错误日志序列，系统应该只保留最近的 N 条（默认 10 条）错误日志。
|
||||
|
||||
**Validates: Requirements 8.4**
|
||||
|
||||
### Property 21: 自动恢复机制正确性
|
||||
|
||||
*对于任何* 被禁用的检测系统，当 API 调用成功时，系统应该自动重新启用实时检测。
|
||||
|
||||
**Validates: Requirements 8.5**
|
||||
|
||||
### Property 22: 手动恢复功能正确性
|
||||
|
||||
*对于任何* 被禁用的检测系统，调用手动恢复功能后，系统应该立即重新启用实时检测并清除错误计数。
|
||||
|
||||
**Validates: Requirements 8.6**
|
||||
|
||||
### Property 23: 异步检测非阻塞性
|
||||
|
||||
*对于任何* 评论提交，当异步检测启用时，评论提交操作应该在 API 调用完成前就返回成功响应。
|
||||
|
||||
**Validates: Requirements 9.1**
|
||||
|
||||
### Property 24: 状态更新正确性
|
||||
|
||||
*对于任何* 评论和 API 响应，当 API 返回结果后，评论的状态应该根据处理建议正确更新（auto → 垃圾/回收站，review → 待审核，approve → 已发布）。
|
||||
|
||||
**Validates: Requirements 9.3**
|
||||
|
||||
### Property 25: 批量扫描完整性
|
||||
|
||||
*对于任何* 评论 ID 列表，批量扫描功能应该对列表中的每个评论都执行检测，且返回的结果数量应该等于输入的评论数量。
|
||||
|
||||
**Validates: Requirements 9.4**
|
||||
|
||||
### Property 26: 队列限速正确性
|
||||
|
||||
*对于任何* 批量扫描操作，API 调用的频率应该不超过配置的速率限制（如每秒最多 N 次调用）。
|
||||
|
||||
**Validates: Requirements 9.5**
|
||||
|
||||
### Property 27: 缓存一致性
|
||||
|
||||
*对于任何* 用户邮箱，在缓存有效期内多次查询该用户的历史统计应该返回相同的结果，且只执行一次数据库查询。
|
||||
|
||||
**Validates: Requirements 9.6**
|
||||
|
||||
### Property 28: 隐私保护完整性
|
||||
|
||||
*对于任何* 评论和隐私级别配置，发送给 API 的数据不应包含用户的真实姓名、完整邮箱（标准模式）或任何用户标识信息（严格模式）。
|
||||
|
||||
**Validates: Requirements 10.3, 10.5**
|
||||
|
||||
### Property 29: 隐私级别配置往返一致性
|
||||
|
||||
*对于任何* 有效的隐私级别值（standard 或 strict），保存后再读取应该得到相同的配置。
|
||||
|
||||
**Validates: Requirements 10.4**
|
||||
|
||||
## Error Handling
|
||||
|
||||
### API 错误处理
|
||||
|
||||
1. **连接超时**：
|
||||
- 超时时间：30 秒
|
||||
- 处理：记录错误日志，使用默认值，允许评论发布
|
||||
- 重试：不自动重试，由自动禁用机制控制
|
||||
|
||||
2. **API 返回错误状态码**：
|
||||
- 4xx 错误：记录错误，使用默认值，不计入连续失败
|
||||
- 5xx 错误：记录错误，使用默认值，计入连续失败
|
||||
- 速率限制（429）：延迟重试，不计入连续失败
|
||||
|
||||
3. **响应格式错误**：
|
||||
- JSON 解析失败：记录错误，使用默认值
|
||||
- 缺少必需字段：记录警告，使用默认值填充
|
||||
- 字段类型错误：记录警告，尝试类型转换
|
||||
|
||||
4. **自动禁用机制**：
|
||||
- 触发条件：连续失败 N 次（默认 3 次）
|
||||
- 禁用时长：M 分钟（默认 60 分钟）
|
||||
- 恢复条件：时间到期或手动恢复或 API 调用成功
|
||||
- 通知：在管理后台显示禁用状态和原因
|
||||
|
||||
### 数据验证错误
|
||||
|
||||
1. **评论数据不完整**：
|
||||
- 缺少必需字段：记录警告，跳过检测
|
||||
- 字段格式错误：记录警告，尝试修复或跳过
|
||||
|
||||
2. **配置数据无效**：
|
||||
- 阈值超出范围：使用默认值 0.85
|
||||
- 模式不存在：使用默认模式 standard
|
||||
- 自定义模板格式错误：显示错误提示，不保存
|
||||
|
||||
3. **上下文构建失败**：
|
||||
- 文章不存在：使用空字符串
|
||||
- 用户历史查询失败：使用默认值（count=0, rate=0）
|
||||
- 数据库错误：记录错误，使用最小上下文
|
||||
|
||||
### 数据库错误
|
||||
|
||||
1. **反馈记录失败**：
|
||||
- 记录错误日志
|
||||
- 不影响评论处理流程
|
||||
- 在管理后台显示警告
|
||||
|
||||
2. **统计查询失败**：
|
||||
- 返回空数据或默认值
|
||||
- 在管理后台显示错误提示
|
||||
|
||||
3. **批量操作失败**：
|
||||
- 记录失败的评论 ID
|
||||
- 继续处理剩余评论
|
||||
- 在完成后显示失败列表
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### 测试方法
|
||||
|
||||
本项目采用双重测试策略：
|
||||
|
||||
1. **单元测试**：验证具体示例、边缘情况和错误条件
|
||||
2. **属性测试**：验证通用属性在所有输入下的正确性
|
||||
|
||||
两种测试方法互补，共同保证系统的正确性和健壮性。
|
||||
|
||||
### 单元测试重点
|
||||
|
||||
单元测试应关注以下方面：
|
||||
|
||||
1. **具体示例**：
|
||||
- 典型的垃圾评论示例
|
||||
- 典型的正常评论示例
|
||||
- 边界值测试（置信度 0.5, 0.85, 0.9 等）
|
||||
|
||||
2. **边缘情况**：
|
||||
- 空评论内容
|
||||
- 超长评论内容
|
||||
- 特殊字符和 Unicode
|
||||
- 文章不存在
|
||||
- 用户无历史记录
|
||||
|
||||
3. **错误条件**：
|
||||
- API 超时
|
||||
- API 返回错误
|
||||
- 数据库连接失败
|
||||
- 配置数据无效
|
||||
|
||||
4. **集成点**：
|
||||
- WordPress 钩子集成
|
||||
- 评论状态更新
|
||||
- 管理后台显示
|
||||
|
||||
### 属性测试配置
|
||||
|
||||
**测试库选择**：
|
||||
- PHP: PHPUnit + Eris (Property-Based Testing)
|
||||
- 或使用 Pest + Pest Property Testing Plugin
|
||||
|
||||
**测试配置**：
|
||||
- 每个属性测试最少运行 100 次迭代
|
||||
- 使用随机种子确保可重现性
|
||||
- 失败时自动缩小（shrinking）到最小失败案例
|
||||
|
||||
**属性测试标签格式**：
|
||||
```php
|
||||
/**
|
||||
* @test
|
||||
* Feature: ai-spam-detection-optimization, Property 1: Prompt 模式完整性
|
||||
*/
|
||||
public function test_prompt_mode_completeness() {
|
||||
// 属性测试实现
|
||||
}
|
||||
```
|
||||
|
||||
### 测试数据生成
|
||||
|
||||
**生成器定义**：
|
||||
|
||||
1. **评论生成器**：
|
||||
- 随机内容（1-1000 字符）
|
||||
- 随机作者名（1-50 字符）
|
||||
- 随机邮箱（有效格式）
|
||||
- 随机 URL（有效格式或空）
|
||||
- 随机 IP 地址
|
||||
|
||||
2. **上下文生成器**：
|
||||
- 随机文章标题（1-200 字符）
|
||||
- 随机文章摘要（0-500 字符）
|
||||
- 随机用户历史（count: 0-1000, rate: 0-1）
|
||||
|
||||
3. **配置生成器**：
|
||||
- 随机阈值（0.5-1.0）
|
||||
- 随机模式（minimal, standard, enhanced）
|
||||
- 随机隐私级别（standard, strict）
|
||||
|
||||
4. **API 响应生成器**：
|
||||
- 随机 is_spam（true/false）
|
||||
- 随机 confidence（0-1）
|
||||
- 随机 reason（1-200 字符）
|
||||
- 随机 suggestion（auto/review/approve）
|
||||
|
||||
### 测试覆盖率目标
|
||||
|
||||
- **代码覆盖率**：> 80%
|
||||
- **分支覆盖率**：> 75%
|
||||
- **属性测试覆盖**：所有 29 个正确性属性
|
||||
- **单元测试覆盖**：所有核心函数和边缘情况
|
||||
|
||||
### 性能测试
|
||||
|
||||
1. **响应时间测试**：
|
||||
- 评论提交响应时间 < 100ms（异步模式）
|
||||
- 同步检测响应时间 < 3s
|
||||
- 批量扫描 100 条评论 < 5 分钟
|
||||
|
||||
2. **并发测试**：
|
||||
- 模拟 10 个并发评论提交
|
||||
- 验证无数据竞争和死锁
|
||||
|
||||
3. **负载测试**：
|
||||
- 批量扫描 1000 条评论
|
||||
- 验证内存使用 < 256MB
|
||||
- 验证数据库查询次数合理
|
||||
|
||||
### 集成测试
|
||||
|
||||
1. **WordPress 集成**：
|
||||
- 测试评论提交钩子
|
||||
- 测试评论状态更新
|
||||
- 测试管理后台显示
|
||||
|
||||
2. **API 集成**：
|
||||
- 测试 OpenAI API 调用
|
||||
- 测试自定义 API 端点
|
||||
- 测试错误处理
|
||||
|
||||
3. **数据库集成**：
|
||||
- 测试反馈记录存储
|
||||
- 测试统计数据查询
|
||||
- 测试批量操作
|
||||
|
||||
### 测试环境
|
||||
|
||||
1. **本地开发环境**：
|
||||
- PHP 7.4+
|
||||
- WordPress 5.8+
|
||||
- MySQL 5.7+
|
||||
- PHPUnit 9.5+
|
||||
|
||||
2. **CI/CD 环境**：
|
||||
- GitHub Actions 或类似 CI 工具
|
||||
- 自动运行所有测试
|
||||
- 代码覆盖率报告
|
||||
|
||||
3. **测试数据**：
|
||||
- 使用 WordPress Test Suite
|
||||
- 创建测试数据库
|
||||
- 使用 mock API 响应
|
||||
|
||||
### 测试执行顺序
|
||||
|
||||
1. **快速测试**（< 1 分钟）：
|
||||
- 单元测试
|
||||
- 快速属性测试（10 次迭代）
|
||||
|
||||
2. **完整测试**（< 10 分钟）：
|
||||
- 所有单元测试
|
||||
- 完整属性测试（100 次迭代）
|
||||
- 集成测试
|
||||
|
||||
3. **性能测试**（< 30 分钟）：
|
||||
- 响应时间测试
|
||||
- 并发测试
|
||||
- 负载测试
|
||||
|
||||
### 测试维护
|
||||
|
||||
1. **定期更新**：
|
||||
- 随着需求变化更新测试
|
||||
- 添加新发现的边缘情况
|
||||
- 优化慢速测试
|
||||
|
||||
2. **失败分析**：
|
||||
- 记录所有测试失败
|
||||
- 分析失败原因
|
||||
- 修复或更新测试
|
||||
|
||||
3. **覆盖率监控**：
|
||||
- 定期检查覆盖率报告
|
||||
- 识别未覆盖的代码
|
||||
- 添加缺失的测试
|
||||
|
||||
151
.kiro/specs/ai-spam-detection-optimization/requirements.md
Normal file
151
.kiro/specs/ai-spam-detection-optimization/requirements.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Requirements Document
|
||||
|
||||
## Introduction
|
||||
|
||||
本文档定义了 Argon 主题 AI 垃圾评论检测功能的优化需求。当前系统已实现基础的 AI 检测功能，但在灵活性、准确性和成本控制方面存在不足。本次优化旨在通过引入多级 Prompt 系统、置信度评分、智能处理建议和学习机制，提升检测准确率并降低误判率。
|
||||
|
||||
## Glossary
|
||||
|
||||
- **AI_Detector**: AI 垃圾评论检测系统
|
||||
- **Prompt_Engine**: Prompt 生成和管理引擎
|
||||
- **Confidence_Score**: 置信度评分，范围 0-1，表示 AI 判断的确定性
|
||||
- **Processing_Suggestion**: 处理建议，包括 auto（自动处理）、review（人工审核）、approve（直接通过）
|
||||
- **Context_Builder**: 上下文信息构建器，收集评论相关的文章、用户历史等信息
|
||||
- **Learning_Module**: 学习模块，记录和分析管理员审核决策
|
||||
- **Detection_Threshold**: 检测阈值，用于判断是否自动处理的置信度临界值
|
||||
- **Comment_Context**: 评论上下文，包括文章信息、用户历史、时间戳等
|
||||
- **Feedback_Record**: 反馈记录，存储 AI 判断和管理员决策的对比数据
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1: 多级 Prompt 系统
|
||||
|
||||
**User Story:** 作为博客管理员，我希望能够选择不同的检测模式，以便在准确性和 API 成本之间取得平衡。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Prompt_Engine SHALL 提供三种预设模式：极简模式（minimal）、标准模式（standard）、增强模式（enhanced）
|
||||
2. WHEN 管理员选择极简模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 100-150 的 Prompt
|
||||
3. WHEN 管理员选择标准模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 200-300 的 Prompt
|
||||
4. WHEN 管理员选择增强模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 300-500 的 Prompt
|
||||
5. WHERE 管理员选择自定义模式 THE Prompt_Engine SHALL 允许管理员编辑自定义 Prompt 模板
|
||||
6. THE Prompt_Engine SHALL 在每个 Prompt 中包含明确的输出格式要求（JSON 格式）
|
||||
|
||||
### Requirement 2: 置信度评分系统
|
||||
|
||||
**User Story:** 作为博客管理员，我希望 AI 能够提供置信度评分，以便我了解判断的可靠性并做出相应决策。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN AI_Detector 分析评论 THEN THE AI_Detector SHALL 返回 0-1 范围的 Confidence_Score
|
||||
2. THE AI_Detector SHALL 在返回结果中包含 is_spam（布尔值）、confidence（浮点数）、reason（字符串）三个字段
|
||||
3. WHEN Confidence_Score >= 0.9 THEN THE AI_Detector SHALL 标记为"非常确定"
|
||||
4. WHEN 0.7 <= Confidence_Score < 0.9 THEN THE AI_Detector SHALL 标记为"比较确定"
|
||||
5. WHEN 0.5 <= Confidence_Score < 0.7 THEN THE AI_Detector SHALL 标记为"中等确定"
|
||||
6. WHEN Confidence_Score < 0.5 THEN THE AI_Detector SHALL 标记为"不太确定"
|
||||
|
||||
### Requirement 3: 智能处理建议
|
||||
|
||||
**User Story:** 作为博客管理员，我希望系统能够根据置信度自动决定处理方式，以便减少人工审核工作量。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE AI_Detector SHALL 在返回结果中包含 Processing_Suggestion 字段
|
||||
2. WHEN Confidence_Score >= Detection_Threshold AND is_spam = true THEN THE AI_Detector SHALL 返回 suggestion = "auto"
|
||||
3. WHEN 0.5 <= Confidence_Score < Detection_Threshold AND is_spam = true THEN THE AI_Detector SHALL 返回 suggestion = "review"
|
||||
4. WHEN Confidence_Score < 0.5 OR is_spam = false THEN THE AI_Detector SHALL 返回 suggestion = "approve"
|
||||
5. THE AI_Detector SHALL 允许管理员在设置中配置 Detection_Threshold（默认值 0.85）
|
||||
6. WHEN suggestion = "auto" THEN THE AI_Detector SHALL 自动将评论标记为垃圾或移至回收站
|
||||
7. WHEN suggestion = "review" THEN THE AI_Detector SHALL 将评论标记为待审核状态
|
||||
8. WHEN suggestion = "approve" THEN THE AI_Detector SHALL 允许评论正常发布并记录低置信度日志
|
||||
|
||||
### Requirement 4: 上下文信息增强
|
||||
|
||||
**User Story:** 作为博客管理员，我希望 AI 能够结合文章内容和用户历史进行判断，以便提高检测准确性。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Context_Builder SHALL 收集评论所属文章的标题和摘要
|
||||
2. THE Context_Builder SHALL 收集评论者的历史评论数量和通过率
|
||||
3. THE Context_Builder SHALL 收集评论的时间戳和 IP 地址
|
||||
4. WHEN 构建检测请求 THEN THE Context_Builder SHALL 将 Comment_Context 包含在 Prompt 中
|
||||
5. THE Context_Builder SHALL 对敏感信息（如完整邮箱）进行脱敏处理
|
||||
6. WHERE 文章摘要超过 200 字符 THE Context_Builder SHALL 截取前 200 字符
|
||||
|
||||
### Requirement 5: 学习优化机制
|
||||
|
||||
**User Story:** 作为博客管理员，我希望系统能够从我的审核决策中学习，以便不断优化检测准确性。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN 管理员批准或拒绝 AI 标记的评论 THEN THE Learning_Module SHALL 记录 Feedback_Record
|
||||
2. THE Feedback_Record SHALL 包含 AI 判断结果、管理员决策、时间戳、评论特征哈希
|
||||
3. THE Learning_Module SHALL 定期分析 Feedback_Record 计算误判率
|
||||
4. WHEN 某类型评论的误判率 > 30% THEN THE Learning_Module SHALL 在管理后台显示优化建议
|
||||
5. THE Learning_Module SHALL 提供"导出反馈数据"功能用于分析
|
||||
6. THE Learning_Module SHALL 在设置页面显示当前的准确率统计（总检测数、自动处理数、误判数）
|
||||
|
||||
### Requirement 6: 设置界面优化
|
||||
|
||||
**User Story:** 作为博客管理员，我希望有清晰的设置界面来配置检测参数，以便根据博客规模调整策略。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE AI_Detector SHALL 在设置页面提供 Prompt 模式选择下拉框
|
||||
2. THE AI_Detector SHALL 在设置页面提供 Detection_Threshold 滑块（范围 0.5-1.0，步长 0.05）
|
||||
3. THE AI_Detector SHALL 在设置页面提供"智能抽查比例"设置（范围 0-100%）
|
||||
4. THE AI_Detector SHALL 在设置页面显示当前月份的 API 调用统计和预估费用
|
||||
5. THE AI_Detector SHALL 提供"测试 Prompt"功能，允许管理员输入示例评论测试检测效果
|
||||
6. THE AI_Detector SHALL 在设置页面提供不同博客规模的推荐配置模板
|
||||
|
||||
### Requirement 7: 后台显示增强
|
||||
|
||||
**User Story:** 作为博客管理员，我希望在评论列表中看到 AI 检测结果的详细信息，以便快速做出审核决策。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN 评论被 AI 检测 THEN THE AI_Detector SHALL 在评论列表显示置信度标签
|
||||
2. THE AI_Detector SHALL 使用不同颜色标识不同置信度等级（红色：>0.9，橙色：0.7-0.9，黄色：0.5-0.7）
|
||||
3. WHEN 鼠标悬停在置信度标签上 THEN THE AI_Detector SHALL 显示详细的分析原因
|
||||
4. THE AI_Detector SHALL 在评论详情页显示完整的 AI 分析报告
|
||||
5. THE AI_Detector SHALL 提供"重新检测"按钮允许管理员使用不同模式重新分析
|
||||
6. WHEN 管理员批准或拒绝 AI 判断 THEN THE AI_Detector SHALL 显示反馈已记录的提示
|
||||
|
||||
### Requirement 8: API 错误处理
|
||||
|
||||
**User Story:** 作为博客管理员，我希望系统能够优雅地处理 API 错误，以便在 API 不可用时不影响评论功能。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN API 请求失败 THEN THE AI_Detector SHALL 记录错误日志并允许评论正常发布
|
||||
2. WHEN API 返回格式错误 THEN THE AI_Detector SHALL 使用默认值（is_spam=false, confidence=0, suggestion="approve"）
|
||||
3. THE AI_Detector SHALL 在连续失败 3 次后自动禁用实时检测 1 小时
|
||||
4. THE AI_Detector SHALL 在设置页面显示最近的 API 错误日志（最多 10 条）
|
||||
5. WHEN API 恢复正常 THEN THE AI_Detector SHALL 自动重新启用实时检测
|
||||
6. THE AI_Detector SHALL 提供"手动重试"按钮允许管理员立即恢复检测
|
||||
|
||||
### Requirement 9: 性能优化
|
||||
|
||||
**User Story:** 作为博客管理员，我希望 AI 检测不会显著影响评论提交速度，以便保持良好的用户体验。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE AI_Detector SHALL 使用异步方式调用 API，不阻塞评论提交
|
||||
2. WHEN 实时检测启用 THEN THE AI_Detector SHALL 在评论提交后立即返回"评论已提交，正在审核中"
|
||||
3. THE AI_Detector SHALL 在 API 响应后更新评论状态（通过或待审核）
|
||||
4. THE AI_Detector SHALL 提供"批量扫描"功能，允许管理员对现有评论进行批量检测
|
||||
5. WHEN 批量扫描运行 THEN THE AI_Detector SHALL 使用队列机制避免 API 速率限制
|
||||
6. THE AI_Detector SHALL 缓存用户历史统计数据，避免重复查询数据库
|
||||
|
||||
### Requirement 10: 数据隐私保护
|
||||
|
||||
**User Story:** 作为博客管理员，我希望系统在发送数据给 AI 时保护用户隐私，以便符合数据保护法规。
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE AI_Detector SHALL 对邮箱地址进行脱敏处理（仅保留域名）
|
||||
2. THE AI_Detector SHALL 对 IP 地址进行脱敏处理（仅保留前两段）
|
||||
3. THE AI_Detector SHALL 不发送用户的真实姓名和联系方式
|
||||
4. THE AI_Detector SHALL 在设置页面提供"数据脱敏级别"选项（标准/严格）
|
||||
5. WHERE 严格模式启用 THE AI_Detector SHALL 不发送任何用户标识信息
|
||||
6. THE AI_Detector SHALL 在隐私政策中说明 AI 检测功能的数据使用方式
|
||||
407
.kiro/specs/ai-spam-detection-optimization/tasks.md
Normal file
407
.kiro/specs/ai-spam-detection-optimization/tasks.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# Implementation Plan: AI 垃圾评论检测优化
|
||||
|
||||
## Overview
|
||||
|
||||
本实施计划将 AI 垃圾评论检测功能从基础版本升级为具有多级 Prompt、置信度评分、智能处理建议和学习机制的完整系统。实施采用模块化方式，每个核心组件独立开发和测试，最后进行集成。
|
||||
|
||||
实施策略：
|
||||
- 先实现核心组件（Prompt_Engine, Context_Builder, AI_Detector）
|
||||
- 再实现辅助组件（Learning_Module, Threshold_Manager）
|
||||
- 然后实现数据库和设置界面
|
||||
- 最后进行集成测试和优化
|
||||
|
||||
## Tasks
|
||||
|
||||
- [x] 1. 数据库表创建和初始化
|
||||
- 创建反馈数据表 `{prefix}_argon_spam_feedback`
|
||||
- 添加必要的索引（comment_id, created_at, is_error）
|
||||
- 实现数据库升级函数，在主题激活时自动创建表
|
||||
- _Requirements: 5.1, 5.2_
|
||||
|
||||
- [x] 2. 实现 Prompt_Engine 核心功能
|
||||
- [x] 2.1 创建 Argon_Spam_Prompt_Engine 类
|
||||
- 实现 get_prompt() 方法，支持三种预设模式
|
||||
- 实现 get_custom_template() 和 save_custom_template() 方法
|
||||
- 实现 validate_template() 方法验证模板格式
|
||||
- _Requirements: 1.1, 1.5, 1.6_
|
||||
|
||||
|
||||
- [ ]* 2.2 编写 Prompt_Engine 属性测试
|
||||
- **Property 1: Prompt 模式完整性**
|
||||
- **Validates: Requirements 1.1, 1.6**
|
||||
|
||||
- [ ]* 2.3 编写 Prompt_Engine 属性测试
|
||||
- **Property 2: Token 消耗范围约束**
|
||||
- **Validates: Requirements 1.2, 1.3, 1.4**
|
||||
|
||||
- [ ]* 2.4 编写 Prompt_Engine 属性测试
|
||||
- **Property 3: 自定义模板往返一致性**
|
||||
- **Validates: Requirements 1.5**
|
||||
|
||||
- [ ]* 2.5 编写 Prompt_Engine 单元测试
|
||||
- 测试三种预设模式的 Prompt 生成
|
||||
- 测试自定义模板的保存和读取
|
||||
- 测试模板验证功能（有效和无效模板）
|
||||
- 测试边缘情况（空模板、超长模板、特殊字符）
|
||||
- _Requirements: 1.1, 1.5, 1.6_
|
||||
|
||||
- [x] 3. 实现 Context_Builder 核心功能
|
||||
- [x] 3.1 创建 Argon_Spam_Context_Builder 类
|
||||
- 实现 build_context() 方法收集评论上下文
|
||||
- 实现 get_post_info() 方法获取文章信息
|
||||
- 实现 get_user_stats() 方法获取用户历史统计
|
||||
- 实现 sanitize_context() 方法进行隐私脱敏
|
||||
- 添加缓存机制优化用户历史查询性能
|
||||
- _Requirements: 4.1, 4.2, 4.3, 4.5, 9.6_
|
||||
|
||||
- [ ]* 3.2 编写 Context_Builder 属性测试
|
||||
- **Property 9: 上下文数据完整性**
|
||||
- **Validates: Requirements 4.1, 4.2, 4.3**
|
||||
|
||||
- [ ]* 3.3 编写 Context_Builder 属性测试
|
||||
- **Property 10: 上下文传递正确性**
|
||||
- **Validates: Requirements 4.4**
|
||||
|
||||
- [ ]* 3.4 编写 Context_Builder 属性测试
|
||||
- **Property 11: 敏感信息脱敏正确性**
|
||||
- **Validates: Requirements 4.5, 10.1, 10.2**
|
||||
|
||||
- [ ]* 3.5 编写 Context_Builder 属性测试
|
||||
- **Property 12: 摘要截取正确性**
|
||||
- **Validates: Requirements 4.6**
|
||||
|
||||
- [ ]* 3.6 编写 Context_Builder 单元测试
|
||||
- 测试文章信息获取（存在和不存在的文章）
|
||||
- 测试用户历史统计（有历史和无历史的用户）
|
||||
- 测试隐私脱敏（标准和严格模式）
|
||||
- 测试摘要截取（短摘要和长摘要）
|
||||
- 测试缓存机制（重复查询应使用缓存）
|
||||
- _Requirements: 4.1, 4.2, 4.3, 4.5, 4.6, 9.6_
|
||||
|
||||
- [x] 4. 实现 Threshold_Manager 核心功能
|
||||
- [x] 4.1 创建 Argon_Spam_Threshold_Manager 类
|
||||
- 实现 get_threshold() 和 set_threshold() 方法
|
||||
- 实现 should_auto_process() 方法判断是否自动处理
|
||||
- 实现 get_recommended_config() 方法提供推荐配置
|
||||
- _Requirements: 3.5, 6.6_
|
||||
|
||||
- [ ]* 4.2 编写 Threshold_Manager 属性测试
|
||||
- **Property 6: 处理建议逻辑正确性**
|
||||
- **Validates: Requirements 3.2, 3.3, 3.4**
|
||||
|
||||
- [ ]* 4.3 编写 Threshold_Manager 属性测试
|
||||
- **Property 7: 阈值配置往返一致性**
|
||||
- **Validates: Requirements 3.5**
|
||||
|
||||
- [ ]* 4.4 编写 Threshold_Manager 单元测试
|
||||
- 测试阈值的保存和读取
|
||||
- 测试自动处理判断逻辑（各种置信度和阈值组合）
|
||||
- 测试推荐配置（小型、中型、大型博客）
|
||||
- 测试边界值（阈值 0.5, 0.85, 1.0）
|
||||
- _Requirements: 3.2, 3.3, 3.4, 3.5, 6.6_
|
||||
|
||||
- [x] 5. 实现 AI_Detector 主控制器
|
||||
- [x] 5.1 创建 Argon_Spam_AI_Detector 类
|
||||
- 实现 detect() 方法协调检测流程
|
||||
- 实现 process_result() 方法处理检测结果
|
||||
- 实现 batch_detect() 方法批量检测评论
|
||||
- 实现 test_prompt() 方法测试 Prompt 效果
|
||||
- 集成 Prompt_Engine、Context_Builder、Threshold_Manager
|
||||
- 实现异步检测机制（使用 WordPress Cron 或 Action Scheduler）
|
||||
- _Requirements: 2.1, 2.2, 3.1, 9.1, 9.2, 9.3, 9.4_
|
||||
|
||||
- [ ]* 5.2 编写 AI_Detector 属性测试
|
||||
- **Property 4: 检测结果数据结构完整性**
|
||||
- **Validates: Requirements 2.1, 2.2, 3.1**
|
||||
|
||||
- [ ]* 5.3 编写 AI_Detector 属性测试
|
||||
- **Property 5: 置信度分类正确性**
|
||||
- **Validates: Requirements 2.3, 2.4, 2.5, 2.6**
|
||||
|
||||
- [ ]* 5.4 编写 AI_Detector 属性测试
|
||||
- **Property 8: 评论处理状态正确性**
|
||||
- **Validates: Requirements 3.6, 3.7, 3.8**
|
||||
|
||||
- [ ]* 5.5 编写 AI_Detector 单元测试
|
||||
- 测试检测流程（同步和异步模式）
|
||||
- 测试结果处理（auto、review、approve 三种建议）
|
||||
- 测试批量检测（小批量和大批量）
|
||||
- 测试 Prompt 测试功能
|
||||
- 测试错误处理（API 超时、返回错误等）
|
||||
- _Requirements: 2.1, 2.2, 3.1, 3.6, 3.7, 3.8, 9.1, 9.2, 9.3, 9.4_
|
||||
|
||||
- [x] 6. Checkpoint - 核心组件测试
|
||||
- 确保所有核心组件测试通过，询问用户是否有问题
|
||||
|
||||
- [x] 7. 实现 API 错误处理机制
|
||||
- [x] 7.1 实现错误处理和自动禁用功能
|
||||
- 实现连接超时处理（30 秒超时）
|
||||
- 实现错误状态码处理（4xx、5xx、429）
|
||||
- 实现响应格式错误处理（JSON 解析失败、字段缺失）
|
||||
- 实现自动禁用机制（连续失败 N 次后禁用 M 分钟）
|
||||
- 实现手动恢复功能
|
||||
- 实现错误日志记录（最多保留 10 条）
|
||||
- _Requirements: 8.1, 8.2, 8.3, 8.4, 8.5, 8.6_
|
||||
|
||||
- [ ]* 7.2 编写 API 错误处理属性测试
|
||||
- **Property 18: API 错误默认值正确性**
|
||||
- **Validates: Requirements 8.1, 8.2**
|
||||
|
||||
- [ ]* 7.3 编写 API 错误处理属性测试
|
||||
- **Property 19: 自动禁用机制正确性**
|
||||
- **Validates: Requirements 8.3**
|
||||
|
||||
- [ ]* 7.4 编写 API 错误处理属性测试
|
||||
- **Property 20: 错误日志容量限制**
|
||||
- **Validates: Requirements 8.4**
|
||||
|
||||
- [ ]* 7.5 编写 API 错误处理属性测试
|
||||
- **Property 21: 自动恢复机制正确性**
|
||||
- **Validates: Requirements 8.5**
|
||||
|
||||
- [ ]* 7.6 编写 API 错误处理属性测试
|
||||
- **Property 22: 手动恢复功能正确性**
|
||||
- **Validates: Requirements 8.6**
|
||||
|
||||
- [ ]* 7.7 编写 API 错误处理单元测试
|
||||
- 测试各种错误场景（超时、4xx、5xx、429、格式错误）
|
||||
- 测试自动禁用触发和恢复
|
||||
- 测试手动恢复功能
|
||||
- 测试错误日志记录和容量限制
|
||||
- _Requirements: 8.1, 8.2, 8.3, 8.4, 8.5, 8.6_
|
||||
|
||||
- [x] 8. 实现性能优化功能
|
||||
- [x] 8.1 实现异步检测和批量扫描
|
||||
- 优化异步检测流程（使用 WordPress Cron 或 Action Scheduler）
|
||||
- 实现批量扫描队列机制（避免 API 速率限制）
|
||||
- 实现进度回调和状态更新
|
||||
- 优化数据库查询（使用缓存和批量查询）
|
||||
- _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6_
|
||||
|
||||
- [ ]* 8.2 编写性能优化属性测试
|
||||
- **Property 23: 异步检测非阻塞性**
|
||||
- **Validates: Requirements 9.1**
|
||||
|
||||
- [ ]* 8.3 编写性能优化属性测试
|
||||
- **Property 24: 状态更新正确性**
|
||||
- **Validates: Requirements 9.3**
|
||||
|
||||
- [ ]* 8.4 编写性能优化属性测试
|
||||
- **Property 25: 批量扫描完整性**
|
||||
- **Validates: Requirements 9.4**
|
||||
|
||||
- [ ]* 8.5 编写性能优化属性测试
|
||||
- **Property 26: 队列限速正确性**
|
||||
- **Validates: Requirements 9.5**
|
||||
|
||||
- [ ]* 8.6 编写性能优化属性测试
|
||||
- **Property 27: 缓存一致性**
|
||||
- **Validates: Requirements 9.6**
|
||||
|
||||
- [ ]* 8.7 编写性能优化单元测试
|
||||
- 测试异步检测（评论提交响应时间 < 100ms）
|
||||
- 测试批量扫描（100 条评论 < 5 分钟）
|
||||
- 测试队列限速（每秒最多 N 次调用）
|
||||
- 测试缓存机制（重复查询使用缓存）
|
||||
- _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6_
|
||||
|
||||
- [x] 9. 实现 Learning_Module 学习机制
|
||||
- [x] 9.1 创建 Argon_Spam_Learning_Module 类
|
||||
- 实现 record_feedback() 方法记录反馈
|
||||
- 实现 calculate_error_rate() 方法计算误判率
|
||||
- 实现 get_optimization_suggestions() 方法生成优化建议
|
||||
- 实现 export_feedback() 方法导出反馈数据
|
||||
- 实现 get_statistics() 方法获取统计数据
|
||||
- _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_
|
||||
|
||||
- [ ]* 9.2 编写 Learning_Module 属性测试
|
||||
- **Property 13: 反馈记录完整性**
|
||||
- **Validates: Requirements 5.1, 5.2**
|
||||
|
||||
- [ ]* 9.3 编写 Learning_Module 属性测试
|
||||
- **Property 14: 误判率计算正确性**
|
||||
- **Validates: Requirements 5.3**
|
||||
|
||||
- [ ]* 9.4 编写 Learning_Module 属性测试
|
||||
- **Property 15: 优化建议触发正确性**
|
||||
- **Validates: Requirements 5.4**
|
||||
|
||||
- [ ]* 9.5 编写 Learning_Module 属性测试
|
||||
- **Property 16: 反馈数据导出格式正确性**
|
||||
- **Validates: Requirements 5.5**
|
||||
|
||||
- [ ]* 9.6 编写 Learning_Module 属性测试
|
||||
- **Property 17: 统计数据准确性**
|
||||
- **Validates: Requirements 5.6**
|
||||
|
||||
- [ ]* 9.7 编写 Learning_Module 单元测试
|
||||
- 测试反馈记录（各种管理员操作）
|
||||
- 测试误判率计算（不同数据集）
|
||||
- 测试优化建议生成（误判率 > 30%）
|
||||
- 测试反馈数据导出（CSV 格式）
|
||||
- 测试统计数据获取（准确性验证）
|
||||
- _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_
|
||||
|
||||
- [x] 10. Checkpoint - 辅助组件测试
|
||||
- 确保所有辅助组件测试通过，询问用户是否有问题
|
||||
|
||||
- [x] 11. 实现隐私保护功能
|
||||
- [x] 11.1 实现数据脱敏和隐私保护
|
||||
- 在 Context_Builder 中实现邮箱脱敏（仅保留域名）
|
||||
- 在 Context_Builder 中实现 IP 脱敏（仅保留前两段）
|
||||
- 实现隐私级别配置（标准/严格）
|
||||
- 在严格模式下不发送任何用户标识信息
|
||||
- _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5_
|
||||
|
||||
- [ ]* 11.2 编写隐私保护属性测试
|
||||
- **Property 28: 隐私保护完整性**
|
||||
- **Validates: Requirements 10.3, 10.5**
|
||||
|
||||
- [ ]* 11.3 编写隐私保护属性测试
|
||||
- **Property 29: 隐私级别配置往返一致性**
|
||||
- **Validates: Requirements 10.4**
|
||||
|
||||
- [ ]* 11.4 编写隐私保护单元测试
|
||||
- 测试邮箱脱敏（标准和严格模式）
|
||||
- 测试 IP 脱敏（标准和严格模式）
|
||||
- 测试隐私级别配置保存和读取
|
||||
- 测试严格模式下不发送用户标识信息
|
||||
- _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5_
|
||||
|
||||
- [x] 12. 实现设置界面
|
||||
- [x] 12.1 创建设置页面 UI
|
||||
- 添加 Prompt 模式选择下拉框（极简/标准/增强/自定义）
|
||||
- 添加自定义 Prompt 编辑器（仅在自定义模式下显示）
|
||||
- 添加检测阈值滑块（0.5-1.0，步长 0.05）
|
||||
- 添加智能抽查比例设置（0-100%）
|
||||
- 添加隐私级别选择（标准/严格）
|
||||
- 添加 API 配置（提供商、密钥、端点）
|
||||
- 显示当前月份 API 调用统计和预估费用
|
||||
- 添加"测试 Prompt"功能（输入示例评论测试效果）
|
||||
- 提供不同博客规模的推荐配置模板
|
||||
- 显示最近的 API 错误日志（最多 10 条）
|
||||
- 添加"手动重试"按钮恢复检测
|
||||
- _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 8.4, 8.6_
|
||||
|
||||
- [x] 12.2 实现设置保存和验证
|
||||
- 实现设置保存逻辑（使用 WordPress Options API）
|
||||
- 实现设置验证（阈值范围、模式有效性等）
|
||||
- 实现测试 Prompt 功能（调用 AI_Detector.test_prompt()）
|
||||
- 实现推荐配置应用功能
|
||||
- 实现手动重试功能
|
||||
- _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 8.6_
|
||||
|
||||
- [ ]* 12.3 编写设置界面单元测试
|
||||
- 测试设置保存和读取
|
||||
- 测试设置验证（有效和无效值）
|
||||
- 测试测试 Prompt 功能
|
||||
- 测试推荐配置应用
|
||||
- 测试手动重试功能
|
||||
- _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 8.6_
|
||||
|
||||
- [x] 13. 实现后台显示增强
|
||||
- [x] 13.1 增强评论列表显示
|
||||
- 在评论列表添加置信度标签（不同颜色表示不同等级）
|
||||
- 实现鼠标悬停显示详细分析原因
|
||||
- 在评论详情页显示完整 AI 分析报告
|
||||
- 添加"重新检测"按钮（支持选择不同模式）
|
||||
- 在管理员操作后显示"反馈已记录"提示
|
||||
- _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6_
|
||||
|
||||
- [x] 13.2 集成 Learning_Module 反馈记录
|
||||
- 在管理员批准/拒绝评论时调用 Learning_Module.record_feedback()
|
||||
- 在评论列表显示反馈状态
|
||||
- 在设置页面显示准确率统计
|
||||
- _Requirements: 5.1, 5.6, 7.6_
|
||||
|
||||
- [ ]* 13.3 编写后台显示单元测试
|
||||
- 测试置信度标签显示（各种置信度值）
|
||||
- 测试详细分析显示
|
||||
- 测试重新检测功能
|
||||
- 测试反馈记录集成
|
||||
- _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6_
|
||||
|
||||
- [x] 14. Checkpoint - UI 和集成测试
|
||||
- 确保所有 UI 和集成功能正常工作，询问用户是否有问题
|
||||
|
||||
- [x] 15. 集成 WordPress 钩子
|
||||
- [x] 15.1 集成评论提交钩子
|
||||
- 在 `pre_comment_approved` 钩子中调用 AI_Detector.detect()
|
||||
- 根据检测结果决定评论状态（auto/review/approve）
|
||||
- 实现智能抽查逻辑（根据配置的抽查比例）
|
||||
- _Requirements: 3.6, 3.7, 3.8, 6.3, 9.1, 9.2_
|
||||
|
||||
- [x] 15.2 集成评论管理钩子
|
||||
- 在 `wp_set_comment_status` 钩子中调用 Learning_Module.record_feedback()
|
||||
- 在 `edit_comment` 钩子中更新检测结果
|
||||
- _Requirements: 5.1, 7.6_
|
||||
|
||||
- [x] 15.3 集成主题激活钩子
|
||||
- 在主题激活时创建数据库表
|
||||
- 初始化默认配置
|
||||
- _Requirements: 5.1_
|
||||
|
||||
- [ ]* 15.4 编写 WordPress 集成测试
|
||||
- 测试评论提交流程（各种检测结果）
|
||||
- 测试评论状态更新
|
||||
- 测试反馈记录
|
||||
- 测试主题激活初始化
|
||||
- _Requirements: 3.6, 3.7, 3.8, 5.1, 9.1, 9.2_
|
||||
|
||||
- [x] 16. 性能测试和优化
|
||||
- [ ]* 16.1 运行性能测试
|
||||
- 测试评论提交响应时间（目标 < 100ms）
|
||||
- 测试同步检测响应时间（目标 < 3s）
|
||||
- 测试批量扫描性能（100 条评论 < 5 分钟）
|
||||
- 测试并发评论提交（10 个并发）
|
||||
- 测试内存使用（批量扫描 1000 条评论 < 256MB）
|
||||
- _Requirements: 9.1, 9.2, 9.4_
|
||||
|
||||
- [x] 16.2 优化性能瓶颈
|
||||
- 根据性能测试结果优化慢速代码
|
||||
- 优化数据库查询（添加索引、使用缓存）
|
||||
- 优化 API 调用（批量处理、限速）
|
||||
- _Requirements: 9.4, 9.5, 9.6_
|
||||
|
||||
- [x] 17. 文档和用户指南
|
||||
- [x] 17.1 编写开发文档
|
||||
- 编写 API 文档（所有公共方法）
|
||||
- 编写架构文档（组件关系和数据流）
|
||||
- 编写测试文档（如何运行测试）
|
||||
- 编写贡献指南（如何添加新功能）
|
||||
|
||||
- [x] 17.2 编写用户指南
|
||||
- 编写设置指南（如何配置各项参数）
|
||||
- 编写使用指南（如何使用各项功能）
|
||||
- 编写故障排除指南（常见问题和解决方案）
|
||||
- 编写最佳实践指南（不同博客规模的推荐配置）
|
||||
|
||||
- [x] 18. 最终集成测试
|
||||
- [ ]* 18.1 运行完整测试套件
|
||||
- 运行所有单元测试
|
||||
- 运行所有属性测试（100 次迭代）
|
||||
- 运行所有集成测试
|
||||
- 运行性能测试
|
||||
- 生成代码覆盖率报告（目标 > 80%）
|
||||
|
||||
- [x] 18.2 手动测试关键流程
|
||||
- 测试评论提交和检测流程
|
||||
- 测试管理员审核和反馈记录
|
||||
- 测试批量扫描功能
|
||||
- 测试设置界面和配置保存
|
||||
- 测试错误处理和自动禁用
|
||||
- 测试隐私保护功能
|
||||
|
||||
- [x] 19. Final Checkpoint - 完整功能验证
|
||||
- 确保所有功能正常工作，所有测试通过，询问用户是否准备发布
|
||||
|
||||
## Notes
|
||||
|
||||
- 任务标记 `*` 的为可选测试任务，可根据项目进度决定是否实施
|
||||
- 每个任务都引用了相关的需求编号，便于追溯
|
||||
- Checkpoint 任务用于阶段性验证，确保增量开发的质量
|
||||
- 属性测试使用 PHPUnit + Eris 或 Pest + Pest Property Testing Plugin
|
||||
- 每个属性测试最少运行 100 次迭代
|
||||
- 单元测试关注具体示例、边缘情况和错误条件
|
||||
- 集成测试验证组件之间的协作和 WordPress 集成
|
||||
- 性能测试确保系统满足响应时间和资源使用要求
|
||||
@@ -14,7 +14,7 @@
|
||||
- 设置模块导出和初始化接口
|
||||
- _需求：1.1, 2.1, 3.1_
|
||||
|
||||
- [~] 2. 实现 DOM 缓存模块
|
||||
- [ ] 2. 实现 DOM 缓存模块
|
||||
- [x] 2.1 创建 ArgonDOMCache 类
|
||||
- 实现构造函数和 Map 存储结构
|
||||
- 实现 init() 方法缓存常用元素
|
||||
@@ -30,7 +30,7 @@
|
||||
- 测试缓存清空功能
|
||||
- _需求：1.5_
|
||||
|
||||
- [~] 3. 实现事件管理模块
|
||||
- [ ] 3. 实现事件管理模块
|
||||
- [x] 3.1 创建 ArgonEventManager 类基础结构
|
||||
- 实现构造函数和监听器注册表
|
||||
- 实现 on()、off()、clear() 方法
|
||||
@@ -60,7 +60,7 @@
|
||||
- [x] 4. 检查点 - 基础模块验证
|
||||
- 确保所有测试通过，询问用户是否有问题
|
||||
|
||||
- [~] 5. 实现资源加载模块
|
||||
- [ ] 5. 实现资源加载模块
|
||||
- [x] 5.1 创建 ArgonResourceLoader 类
|
||||
- 实现构造函数和加载状态管理
|
||||
- 实现 loadScript() 异步加载方法
|
||||
@@ -82,7 +82,7 @@
|
||||
- 测试加载失败降级方案
|
||||
- _需求：19.4_
|
||||
|
||||
- [~] 6. 实现渲染优化模块
|
||||
- [ ] 6. 实现渲染优化模块
|
||||
- [x] 6.1 创建 ArgonRenderOptimizer 类
|
||||
- 实现构造函数和读写队列
|
||||
- 实现 read() 和 write() 方法
|
||||
|
||||
@@ -4907,6 +4907,18 @@ void 0;
|
||||
renderChart(element, index) {
|
||||
const chartId = `mermaid-chart-${Date.now()}-${index}`;
|
||||
|
||||
// 检查是否已经是错误容器（避免重复处理错误）
|
||||
if (element.classList && element.classList.contains('mermaid-error-container')) {
|
||||
this.logDebug(`元素已经是错误容器，跳过: ${chartId}`);
|
||||
return;
|
||||
}
|
||||
|
||||
// 检查是否已经是渲染成功的容器（避免重复渲染）
|
||||
if (element.classList && element.classList.contains('mermaid-container') && element.dataset.mermaidCode) {
|
||||
this.logDebug(`图表已成功渲染，跳过: ${chartId}`);
|
||||
return;
|
||||
}
|
||||
|
||||
// 检查是否已渲染（避免重复渲染）
|
||||
if (this.rendered.has(element)) {
|
||||
this.logDebug(`图表已渲染，跳过: ${chartId}`);
|
||||
@@ -4963,7 +4975,9 @@ void 0;
|
||||
container.dataset.currentTheme = this.getMermaidTheme();
|
||||
|
||||
// 替换原始代码块
|
||||
if (element.parentNode) {
|
||||
element.parentNode.replaceChild(container, element);
|
||||
}
|
||||
|
||||
// 标记为已渲染
|
||||
this.rendered.add(container);
|
||||
@@ -5035,31 +5049,72 @@ void 0;
|
||||
handleRenderError(element, error, code) {
|
||||
this.logError('图表渲染失败', error);
|
||||
|
||||
// 如果元素已经是错误容器，避免重复嵌套
|
||||
if (element.classList && element.classList.contains('mermaid-error-container')) {
|
||||
this.logDebug('元素已经是错误容器，跳过重复处理');
|
||||
return;
|
||||
}
|
||||
|
||||
// 提取原始代码（优先使用传入的 code，其次从元素中提取）
|
||||
let originalCode = code;
|
||||
if (!originalCode) {
|
||||
// 尝试从不同类型的元素中提取代码
|
||||
if (element.dataset && element.dataset.mermaidCode) {
|
||||
originalCode = element.dataset.mermaidCode;
|
||||
} else if (element.textContent) {
|
||||
originalCode = element.textContent.trim();
|
||||
}
|
||||
}
|
||||
|
||||
// 创建错误提示容器
|
||||
const errorContainer = document.createElement('div');
|
||||
errorContainer.className = 'mermaid-error-container';
|
||||
errorContainer.dataset.errorHandled = 'true'; // 标记已处理
|
||||
|
||||
// 提取错误信息
|
||||
const errorMessage = error.message || '未知错误';
|
||||
const errorType = this.getErrorType(errorMessage);
|
||||
|
||||
errorContainer.innerHTML = `
|
||||
<div class="mermaid-error-header">
|
||||
// 创建错误显示结构
|
||||
const errorHeader = document.createElement('div');
|
||||
errorHeader.className = 'mermaid-error-header';
|
||||
errorHeader.innerHTML = `
|
||||
<span class="mermaid-error-icon">⚠️</span>
|
||||
<span class="mermaid-error-title">Mermaid 图表渲染失败</span>
|
||||
</div>
|
||||
<div class="mermaid-error-body">
|
||||
<p class="mermaid-error-type">错误类型: ${errorType}</p>
|
||||
<p class="mermaid-error-message">${this.escapeHtml(errorMessage)}</p>
|
||||
</div>
|
||||
<details class="mermaid-error-code">
|
||||
<summary>查看原始代码</summary>
|
||||
<pre><code class="language-mermaid">${this.escapeHtml(code || element.textContent)}</code></pre>
|
||||
</details>
|
||||
`;
|
||||
|
||||
const errorBody = document.createElement('div');
|
||||
errorBody.className = 'mermaid-error-body';
|
||||
errorBody.innerHTML = `
|
||||
<p class="mermaid-error-type">错误类型: ${errorType}</p>
|
||||
<p class="mermaid-error-message">${this.escapeHtml(errorMessage)}</p>
|
||||
`;
|
||||
|
||||
// 创建代码查看区域
|
||||
const codeDetails = document.createElement('details');
|
||||
codeDetails.className = 'mermaid-error-code';
|
||||
|
||||
const codeSummary = document.createElement('summary');
|
||||
codeSummary.textContent = '查看原始代码';
|
||||
|
||||
const codeBlock = document.createElement('pre');
|
||||
const codeElement = document.createElement('code');
|
||||
codeElement.className = 'language-mermaid';
|
||||
codeElement.textContent = originalCode || '(无法提取代码)';
|
||||
|
||||
codeBlock.appendChild(codeElement);
|
||||
codeDetails.appendChild(codeSummary);
|
||||
codeDetails.appendChild(codeBlock);
|
||||
|
||||
// 组装错误容器
|
||||
errorContainer.appendChild(errorHeader);
|
||||
errorContainer.appendChild(errorBody);
|
||||
errorContainer.appendChild(codeDetails);
|
||||
|
||||
// 替换原始代码块
|
||||
if (element.parentNode) {
|
||||
element.parentNode.replaceChild(errorContainer, element);
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
@@ -5155,7 +5210,8 @@ void 0;
|
||||
* 重新渲染所有图表（主题切换时）
|
||||
*/
|
||||
reRenderCharts() {
|
||||
const charts = document.querySelectorAll('.mermaid-container');
|
||||
// 只选择成功渲染的图表容器，排除错误容器
|
||||
const charts = document.querySelectorAll('.mermaid-container:not(.mermaid-error-container)');
|
||||
|
||||
if (charts.length === 0) {
|
||||
return;
|
||||
@@ -5190,6 +5246,13 @@ void 0;
|
||||
charts.forEach((chart, index) => {
|
||||
const code = chart.dataset.mermaidCode;
|
||||
if (!code) {
|
||||
this.logDebug('图表缺少原始代码，跳过重新渲染');
|
||||
return;
|
||||
}
|
||||
|
||||
// 检查主题是否真的需要更新
|
||||
if (chart.dataset.currentTheme === newTheme) {
|
||||
this.logDebug('图表主题未改变，跳过重新渲染');
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -5209,6 +5272,8 @@ void 0;
|
||||
this.logDebug(`图表重新渲染成功: ${chartId}`);
|
||||
}).catch(error => {
|
||||
this.logError('图表重新渲染失败', error);
|
||||
// 重新渲染失败时，不替换为错误容器，保持原样
|
||||
// 因为之前已经成功渲染过，只是主题切换失败
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -9256,8 +9256,8 @@ function argon_get_mermaid_library_url() {
|
||||
|
||||
// 根据 CDN 来源返回对应的 URL
|
||||
$cdn_urls = [
|
||||
'jsdelivr' => 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js',
|
||||
'unpkg' => 'https://unpkg.com/mermaid@10/dist/mermaid.min.js',
|
||||
'jsdelivr' => 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js',
|
||||
'unpkg' => 'https://unpkg.com/mermaid@11/dist/mermaid.min.js',
|
||||
'local' => get_template_directory_uri() . '/assets/vendor/mermaid/mermaid.min.js'
|
||||
];
|
||||
|
||||
@@ -9283,8 +9283,8 @@ function argon_get_mermaid_library_url() {
|
||||
*/
|
||||
function argon_get_mermaid_fallback_urls() {
|
||||
return [
|
||||
'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js',
|
||||
'https://unpkg.com/mermaid@10/dist/mermaid.min.js',
|
||||
'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js',
|
||||
'https://unpkg.com/mermaid@11/dist/mermaid.min.js',
|
||||
get_template_directory_uri() . '/assets/vendor/mermaid/mermaid.min.js'
|
||||
];
|
||||
}
|
||||
|
||||
@@ -3117,7 +3117,7 @@ function themeoptions_page(){
|
||||
<th><label><?php _e('自定义 CDN 地址', 'argon');?></label></th>
|
||||
<td>
|
||||
<input type="text" class="regular-text" name="argon_mermaid_cdn_custom_url" value="<?php echo get_option('argon_mermaid_cdn_custom_url', ''); ?>" placeholder="https://example.com/mermaid.min.js"/>
|
||||
<p class="description"><?php _e('当 CDN 来源选择"自定义 CDN 地址"时生效。请输入完整的 Mermaid 库 URL（必须以 .js 结尾）', 'argon');?></p>
|
||||
<p class="description"><?php _e('当 CDN 来源选择"自定义 CDN 地址"时生效。请输入完整的 Mermaid 库 URL（必须以 .js 结尾）。推荐使用 Mermaid v11 或更高版本', 'argon');?></p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
@@ -3384,7 +3384,7 @@ function themeoptions_page(){
|
||||
// 动态加载 Mermaid 库
|
||||
if (typeof mermaid === 'undefined') {
|
||||
const script = document.createElement('script');
|
||||
script.src = 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js';
|
||||
script.src = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
|
||||
script.onload = function() {
|
||||
renderMermaid(code);
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user