nanhaoluo/argon-theme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d0ae1dbed716a7eb0886d6bdbd85ec0c4ff58a47
argon-theme/.kiro/specs/ai-spam-detection-optimization/requirements.md
nanhaoluo 28f0a1265e feat: 更新 Mermaid 到 v11 并优化错误处理 
- 更新 Mermaid 库版本从 v10 升级到 v11.12.2
- 优化错误处理逻辑，避免重复嵌套错误容器
- 修复查看源代码时可能出现的嵌套报错问题
- 改进渲染前检查，跳过已处理的错误容器和已渲染的图表
- 优化重新渲染逻辑，只处理成功渲染的图表，排除错误容器
- 增强代码提取逻辑，优先使用传入的代码参数
- 添加主题切换时的智能判断，避免不必要的重新渲染
- 更新 functions.php 中的 CDN 地址到 v11
- 更新 settings.php 中的预览功能 CDN 地址到 v11
- 改进错误容器的 DOM 结构，使用独立元素而非 innerHTML
2026-01-24 22:46:00 +08:00

152 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 检测功能的数据使用方式
Reference in New Issue View Git Blame Copy Permalink