nanhaoluo
28f0a1265e
- 更新 Mermaid 库版本从 v10 升级到 v11.12.2 - 优化错误处理逻辑，避免重复嵌套错误容器 - 修复查看源代码时可能出现的嵌套报错问题 - 改进渲染前检查，跳过已处理的错误容器和已渲染的图表 - 优化重新渲染逻辑，只处理成功渲染的图表，排除错误容器 - 增强代码提取逻辑，优先使用传入的代码参数 - 添加主题切换时的智能判断，避免不必要的重新渲染 - 更新 functions.php 中的 CDN 地址到 v11 - 更新 settings.php 中的预览功能 CDN 地址到 v11 - 改进错误容器的 DOM 结构，使用独立元素而非 innerHTML
8.9 KiB
8.9 KiB
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
- THE Prompt_Engine SHALL 提供三种预设模式：极简模式（minimal）、标准模式（standard）、增强模式（enhanced）
- WHEN 管理员选择极简模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 100-150 的 Prompt
- WHEN 管理员选择标准模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 200-300 的 Prompt
- WHEN 管理员选择增强模式 THEN THE Prompt_Engine SHALL 生成 token 消耗约 300-500 的 Prompt
- WHERE 管理员选择自定义模式 THE Prompt_Engine SHALL 允许管理员编辑自定义 Prompt 模板
- THE Prompt_Engine SHALL 在每个 Prompt 中包含明确的输出格式要求（JSON 格式）
Requirement 2: 置信度评分系统
User Story: 作为博客管理员，我希望 AI 能够提供置信度评分，以便我了解判断的可靠性并做出相应决策。
Acceptance Criteria
- WHEN AI_Detector 分析评论 THEN THE AI_Detector SHALL 返回 0-1 范围的 Confidence_Score
- THE AI_Detector SHALL 在返回结果中包含 is_spam（布尔值）、confidence（浮点数）、reason（字符串）三个字段
- WHEN Confidence_Score >= 0.9 THEN THE AI_Detector SHALL 标记为"非常确定"
- WHEN 0.7 <= Confidence_Score < 0.9 THEN THE AI_Detector SHALL 标记为"比较确定"
- WHEN 0.5 <= Confidence_Score < 0.7 THEN THE AI_Detector SHALL 标记为"中等确定"
- WHEN Confidence_Score < 0.5 THEN THE AI_Detector SHALL 标记为"不太确定"
Requirement 3: 智能处理建议
User Story: 作为博客管理员，我希望系统能够根据置信度自动决定处理方式，以便减少人工审核工作量。
Acceptance Criteria
- THE AI_Detector SHALL 在返回结果中包含 Processing_Suggestion 字段
- WHEN Confidence_Score >= Detection_Threshold AND is_spam = true THEN THE AI_Detector SHALL 返回 suggestion = "auto"
- WHEN 0.5 <= Confidence_Score < Detection_Threshold AND is_spam = true THEN THE AI_Detector SHALL 返回 suggestion = "review"
- WHEN Confidence_Score < 0.5 OR is_spam = false THEN THE AI_Detector SHALL 返回 suggestion = "approve"
- THE AI_Detector SHALL 允许管理员在设置中配置 Detection_Threshold（默认值 0.85）
- WHEN suggestion = "auto" THEN THE AI_Detector SHALL 自动将评论标记为垃圾或移至回收站
- WHEN suggestion = "review" THEN THE AI_Detector SHALL 将评论标记为待审核状态
- WHEN suggestion = "approve" THEN THE AI_Detector SHALL 允许评论正常发布并记录低置信度日志
Requirement 4: 上下文信息增强
User Story: 作为博客管理员，我希望 AI 能够结合文章内容和用户历史进行判断，以便提高检测准确性。
Acceptance Criteria
- THE Context_Builder SHALL 收集评论所属文章的标题和摘要
- THE Context_Builder SHALL 收集评论者的历史评论数量和通过率
- THE Context_Builder SHALL 收集评论的时间戳和 IP 地址
- WHEN 构建检测请求 THEN THE Context_Builder SHALL 将 Comment_Context 包含在 Prompt 中
- THE Context_Builder SHALL 对敏感信息（如完整邮箱）进行脱敏处理
- WHERE 文章摘要超过 200 字符 THE Context_Builder SHALL 截取前 200 字符
Requirement 5: 学习优化机制
User Story: 作为博客管理员，我希望系统能够从我的审核决策中学习，以便不断优化检测准确性。
Acceptance Criteria
- WHEN 管理员批准或拒绝 AI 标记的评论 THEN THE Learning_Module SHALL 记录 Feedback_Record
- THE Feedback_Record SHALL 包含 AI 判断结果、管理员决策、时间戳、评论特征哈希
- THE Learning_Module SHALL 定期分析 Feedback_Record 计算误判率
- WHEN 某类型评论的误判率 > 30% THEN THE Learning_Module SHALL 在管理后台显示优化建议
- THE Learning_Module SHALL 提供"导出反馈数据"功能用于分析
- THE Learning_Module SHALL 在设置页面显示当前的准确率统计（总检测数、自动处理数、误判数）
Requirement 6: 设置界面优化
User Story: 作为博客管理员，我希望有清晰的设置界面来配置检测参数，以便根据博客规模调整策略。
Acceptance Criteria
- THE AI_Detector SHALL 在设置页面提供 Prompt 模式选择下拉框
- THE AI_Detector SHALL 在设置页面提供 Detection_Threshold 滑块（范围 0.5-1.0，步长 0.05）
- THE AI_Detector SHALL 在设置页面提供"智能抽查比例"设置（范围 0-100%）
- THE AI_Detector SHALL 在设置页面显示当前月份的 API 调用统计和预估费用
- THE AI_Detector SHALL 提供"测试 Prompt"功能，允许管理员输入示例评论测试检测效果
- THE AI_Detector SHALL 在设置页面提供不同博客规模的推荐配置模板
Requirement 7: 后台显示增强
User Story: 作为博客管理员，我希望在评论列表中看到 AI 检测结果的详细信息，以便快速做出审核决策。
Acceptance Criteria
- WHEN 评论被 AI 检测 THEN THE AI_Detector SHALL 在评论列表显示置信度标签
- THE AI_Detector SHALL 使用不同颜色标识不同置信度等级（红色：>0.9，橙色：0.7-0.9，黄色：0.5-0.7）
- WHEN 鼠标悬停在置信度标签上 THEN THE AI_Detector SHALL 显示详细的分析原因
- THE AI_Detector SHALL 在评论详情页显示完整的 AI 分析报告
- THE AI_Detector SHALL 提供"重新检测"按钮允许管理员使用不同模式重新分析
- WHEN 管理员批准或拒绝 AI 判断 THEN THE AI_Detector SHALL 显示反馈已记录的提示
Requirement 8: API 错误处理
User Story: 作为博客管理员，我希望系统能够优雅地处理 API 错误，以便在 API 不可用时不影响评论功能。
Acceptance Criteria
- WHEN API 请求失败 THEN THE AI_Detector SHALL 记录错误日志并允许评论正常发布
- WHEN API 返回格式错误 THEN THE AI_Detector SHALL 使用默认值（is_spam=false, confidence=0, suggestion="approve"）
- THE AI_Detector SHALL 在连续失败 3 次后自动禁用实时检测 1 小时
- THE AI_Detector SHALL 在设置页面显示最近的 API 错误日志（最多 10 条）
- WHEN API 恢复正常 THEN THE AI_Detector SHALL 自动重新启用实时检测
- THE AI_Detector SHALL 提供"手动重试"按钮允许管理员立即恢复检测
Requirement 9: 性能优化
User Story: 作为博客管理员，我希望 AI 检测不会显著影响评论提交速度，以便保持良好的用户体验。
Acceptance Criteria
- THE AI_Detector SHALL 使用异步方式调用 API，不阻塞评论提交
- WHEN 实时检测启用 THEN THE AI_Detector SHALL 在评论提交后立即返回"评论已提交，正在审核中"
- THE AI_Detector SHALL 在 API 响应后更新评论状态（通过或待审核）
- THE AI_Detector SHALL 提供"批量扫描"功能，允许管理员对现有评论进行批量检测
- WHEN 批量扫描运行 THEN THE AI_Detector SHALL 使用队列机制避免 API 速率限制
- THE AI_Detector SHALL 缓存用户历史统计数据，避免重复查询数据库
Requirement 10: 数据隐私保护
User Story: 作为博客管理员，我希望系统在发送数据给 AI 时保护用户隐私，以便符合数据保护法规。
Acceptance Criteria
- THE AI_Detector SHALL 对邮箱地址进行脱敏处理（仅保留域名）
- THE AI_Detector SHALL 对 IP 地址进行脱敏处理（仅保留前两段）
- THE AI_Detector SHALL 不发送用户的真实姓名和联系方式
- THE AI_Detector SHALL 在设置页面提供"数据脱敏级别"选项（标准/严格）
- WHERE 严格模式启用 THE AI_Detector SHALL 不发送任何用户标识信息
- THE AI_Detector SHALL 在隐私政策中说明 AI 检测功能的数据使用方式