argon-theme/tests/test-shortcode-example.md

AI 垃圾评论检测系统架构

系统概述

本文档展示 Argon 主题的 AI 垃圾评论检测系统的完整架构和流程。

主流程图

[mermaid theme="default" width="100%" align="center"] flowchart TD Start([用户提交评论]) --> PreProcess[预处理评论] PreProcess --> CheckEnabled{启用 AI 检测?}

CheckEnabled -->|否| DirectSave[直接保存评论]
CheckEnabled -->|是| CheckMode{检测模式?}

CheckMode -->|manual| DirectSave
CheckMode -->|keyword| CheckKeyword[检查关键字]
CheckMode -->|sample| CheckSample[智能抽样]
CheckMode -->|all| NeedCheck[需要检测]

CheckKeyword --> KeywordMatch{匹配关键字?}
KeywordMatch -->|是| NeedCheck
KeywordMatch -->|否| DirectSave

CheckSample --> SampleDecision{抽中?}
SampleDecision -->|是| NeedCheck
SampleDecision -->|否| DirectSave

NeedCheck --> SetPending[设置待审核状态]
SetPending --> SaveWithFlag[保存评论并标记]
SaveWithFlag --> TriggerDetect[触发 AI 检测]

TriggerDetect --> CallAPI[调用 AI API]
CallAPI --> ParseResult[解析结果]

ParseResult --> CheckConfidence{置信度?}
CheckConfidence -->|高| AutoHandle[自动处理]
CheckConfidence -->|中| ManualReview[人工审核]
CheckConfidence -->|低| MarkNormal[标记正常]

AutoHandle --> CheckAction{处理方式?}
CheckAction -->|trash| MoveTrash[移入回收站]
CheckAction -->|hold| KeepPending[保持待审核]
CheckAction -->|mark| JustMark[仅标记]

MoveTrash --> NotifyAdmin[通知管理员]
KeepPending --> NotifyAdmin
JustMark --> SaveResult[保存结果]
ManualReview --> SaveResult
MarkNormal --> SaveResult
NotifyAdmin --> SaveResult

SaveResult --> AILearn{启用学习?}
AILearn -->|是| ExtractKeywords[提取关键词]
AILearn -->|否| End([结束])
ExtractKeywords --> UpdateDB[更新词库]
UpdateDB --> End

DirectSave --> End

style Start fill:#e1f5e1,stroke:#2e7d32,stroke-width:2px
style End fill:#e1f5e1,stroke:#2e7d32,stroke-width:2px
style MoveTrash fill:#ff6b6b,stroke:#c62828,stroke-width:2px
style MarkNormal fill:#95e1d3,stroke:#2e7d32,stroke-width:2px
style ManualReview fill:#ffa500,stroke:#ff8f00,stroke-width:2px

[/mermaid]

检测模式详解

[mermaid theme="default" width="80%" align="center"] flowchart LR subgraph Manual[Manual 模式] M1[关闭实时检测] M2[仅手动扫描] end

subgraph Keyword[Keyword 模式]
    K1[关键字触发]
    K2[精准检测]
    K3[低成本]
end

subgraph Sample[Sample 模式]
    S1[智能抽样]
    S2[平衡准确性]
    S3[控制成本]
end

subgraph All[All 模式]
    A1[全量检测]
    A2[最高准确性]
    A3[高成本]
end

style Manual fill:#e3f2fd
style Keyword fill:#fff3e0
style Sample fill:#f3e5f5
style All fill:#fce4ec

[/mermaid]

AI 检测流程

[mermaid theme="default" width="90%"] sequenceDiagram participant User as 用户 participant WP as WordPress participant Argon as Argon 主题 participant AI as AI API participant DB as 数据库

User->>WP: 提交评论
WP->>Argon: 触发 preprocess_comment
Argon->>Argon: 检查检测规则

alt 需要检测
    Argon->>DB: 保存评论（待审核）
    Argon->>AI: 发送检测请求
    AI-->>Argon: 返回检测结果
    Argon->>Argon: 解析结果和置信度
    
    alt 高置信度垃圾评论
        Argon->>DB: 移入回收站
        Argon->>WP: 发送通知邮件
    else 中等置信度
        Argon->>DB: 标记待人工审核
    else 正常评论
        Argon->>DB: 标记为正常
    end
    
    Argon->>DB: 保存检测记录
    
    opt 启用 AI 学习
        Argon->>AI: 提取关键词
        AI-->>Argon: 返回关键词
        Argon->>DB: 更新学习词库
    end
else 跳过检测
    Argon->>DB: 直接保存评论
end

WP-->>User: 显示提交结果

[/mermaid]

数据库结构

[mermaid theme="default" width="85%"] erDiagram COMMENT ||--o{ COMMENT_META : has COMMENT { bigint comment_ID PK bigint comment_post_ID FK text comment_content varchar comment_author varchar comment_author_email varchar comment_author_IP datetime comment_date varchar comment_approved }

COMMENT_META {
    bigint meta_id PK
    bigint comment_id FK
    varchar meta_key
    longtext meta_value
}

SPAM_DETECTION ||--|| COMMENT : detects
SPAM_DETECTION {
    bigint id PK
    bigint comment_id FK
    varchar result
    float confidence
    text reason
    text keywords
    datetime detected_at
    varchar detection_code
}

LEARNED_KEYWORDS ||--o{ SPAM_DETECTION : learns_from
LEARNED_KEYWORDS {
    bigint id PK
    varchar keyword
    int weight
    varchar category
    datetime created_at
    datetime updated_at
}

[/mermaid]

系统状态机

[mermaid theme="default" width="70%"] stateDiagram-v2 [*] --> Submitted: 用户提交

Submitted --> Pending: 需要检测
Submitted --> Approved: 跳过检测

Pending --> Detecting: 开始检测
Detecting --> Analyzed: 检测完成

Analyzed --> Spam: 高置信度垃圾
Analyzed --> Suspicious: 中等置信度
Analyzed --> Clean: 低置信度/正常

Spam --> Trash: 自动处理
Spam --> Hold: 保持待审核
Spam --> Marked: 仅标记

Suspicious --> ManualReview: 等待人工审核
Clean --> Approved: 自动通过

ManualReview --> Approved: 管理员批准
ManualReview --> Trash: 管理员拒绝

Hold --> Approved: 管理员批准
Hold --> Trash: 管理员拒绝

Marked --> Approved: 管理员批准
Marked --> Trash: 管理员拒绝

Trash --> [*]
Approved --> [*]

note right of Detecting
    调用 AI API
    解析返回结果
    计算置信度
end note

note right of ManualReview
    显示在后台
    等待管理员操作
end note

[/mermaid]

性能优化策略

[mermaid theme="default" width="95%"] flowchart TD subgraph Input[输入优化] I1[关键字预过滤] I2[白名单用户] I3[智能抽样] end

subgraph Process[处理优化]
    P1[异步检测]
    P2[批量处理]
    P3[缓存结果]
end

subgraph API[API 优化]
    A1[Prompt 优化]
    A2[Token 控制]
    A3[超时处理]
end

subgraph Storage[存储优化]
    S1[索引优化]
    S2[定期清理]
    S3[归档历史]
end

Input --> Process
Process --> API
API --> Storage

style Input fill:#e8f5e9
style Process fill:#e3f2fd
style API fill:#fff3e0
style Storage fill:#f3e5f5

[/mermaid]

配置建议矩阵

[mermaid theme="default" width="100%"] graph TB subgraph Small[小型博客 < 100评论/天] S1[检测模式: keyword] S2[Prompt: 标准模式] S3[置信度阈值: > 0.9] S4[自动处理: trash] end

subgraph Medium[中型博客 100-500评论/天]
    M1[检测模式: sample 30%]
    M2[Prompt: 标准模式]
    M3[置信度阈值: > 0.85]
    M4[自动处理: hold]
end

subgraph Large[大型博客 > 500评论/天]
    L1[检测模式: sample 40%]
    L2[Prompt: 极简模式]
    L3[置信度阈值: > 0.8]
    L4[自动处理: mark]
    L5[定期批量扫描]
end

style Small fill:#c8e6c9
style Medium fill:#fff9c4
style Large fill:#ffccbc

[/mermaid]

错误处理流程

[mermaid theme="default" width="85%"] flowchart TD Start([检测开始]) --> CallAPI[调用 AI API]

CallAPI --> CheckResponse{响应状态?}

CheckResponse -->|成功| ParseJSON[解析 JSON]
CheckResponse -->|超时| Timeout[超时处理]
CheckResponse -->|错误| APIError[API 错误]

ParseJSON --> ValidateData{数据有效?}
ValidateData -->|是| ProcessResult[处理结果]
ValidateData -->|否| DataError[数据错误]

Timeout --> RetryCheck{重试次数?}
RetryCheck -->|< 3| Retry[重试请求]
RetryCheck -->|>= 3| FallbackPending[降级：待审核]

Retry --> CallAPI

APIError --> LogError[记录错误日志]
DataError --> LogError

LogError --> NotifyAdmin[通知管理员]
NotifyAdmin --> FallbackPending

ProcessResult --> SaveResult[保存结果]
FallbackPending --> SaveResult

SaveResult --> End([结束])

style Timeout fill:#ffccbc
style APIError fill:#ffccbc
style DataError fill:#ffccbc
style FallbackPending fill:#fff9c4
style ProcessResult fill:#c8e6c9

[/mermaid]

总结

通过以上流程图，我们可以清晰地看到：

1. 主流程：从用户提交到最终处理的完整流程
2. 检测模式：四种模式的特点和适用场景
3. 时序交互：各组件之间的交互顺序
4. 数据结构：数据库表关系和字段定义
5. 状态机：评论的各种状态转换
6. 性能优化：多层次的优化策略
7. 配置建议：不同规模博客的推荐配置
8. 错误处理：完善的异常处理机制

这个系统设计充分考虑了：

• ✅ 准确性：多级置信度判断
• ✅ 性能：异步处理、智能抽样
• ✅ 成本：灵活的检测模式
• ✅ 可靠性：完善的错误处理
• ✅ 可维护性：清晰的架构设计