feat(ai): V2 深度增强 — SSE 流式/全局助手/内容安全/多角色覆盖

对标 Khanmigo/Duolingo Max/Squirrel AI/Century Tech 实现： - SSE 流式响应：createAiChatCompletionStream AsyncGenerator + /api/ai/chat/stream SSE 端点 + useAiChatStream hook（AbortController 停止生成 + localStorage 持久化） - Markdown 渲染：AiMarkdownRenderer（react-markdown + remark-gfm + 代码块/表格/列表 + hover 复制按钮） - 全局 AI 助手：AiAssistantWidget 浮动按钮 + Sheet 侧抽屉 + usePathname 路由推断上下文（7 类场景系统提示）+ dashboard layout 全局注入 AiClientProvider - 内容安全：content-safety.ts 多层过滤（输入/输出安全过滤 + 每日限制 student 50/teacher 200/parent 30/admin 500 + 学生苏格拉底模式），COPPA/FERPA K12 合规 - 多角色 AI 覆盖：家长端 AiChildSummary（学情摘要）+ 管理员端 AiUsageDashboard（使用监控）+ 学生端 AiStudyPath（个性化学习路径） - i18n 修复：8 处错误键引用 + zh-CN/en ai.json 全面扩展 - 架构文档 004/005 同步更新
2026-06-23 01:34:37 +08:00
parent a60105455e
commit 4da9194a5e
27 changed files with 3522 additions and 172 deletions
--- a/docs/architecture/audit/ai-module-audit-report-v2.md
+++ b/docs/architecture/audit/ai-module-audit-report-v2.md
@@ -0,0 +1,508 @@
+# AI 模块审计报告 V2 — 深度可用性分析与行业对标
+
+> 审计范围：基于 V1 审计报告（`ai-module-audit-report.md`）已完成的实现，进行第二轮深度审计。
+> 审计日期：2026-06-23
+> 审计方法：逐组件可用性走查 + 行业标杆对标（Khanmigo / Duolingo Max / Squirrel AI / Century Tech）+ 多角色用户旅程分析
+> 审计依据：`docs/standards/coding-standards.md`、`docs/architecture/004_architecture_impact_map.md`、行业研究
+
+---
+
+## 一、V1 完成度回顾
+
+### 1.1 已完成项
+
+| 编号 | V1 改进项 | 状态 | 实现位置 |
+|------|----------|------|---------|
+| P0-1 | AI 聊天端点权限校验 | ✅ | [actions.ts](file:///e:/Desktop/CICD/src/modules/ai/actions.ts) `aiChatAction` |
+| P0-2 | AI 独立模块 | ✅ | `src/modules/ai/` 完整结构 |
+| P0-3 | exam-ai-generator i18n | ✅ | [exam-ai-generator.tsx](file:///e:/Desktop/CICD/src/modules/exams/components/exam-ai-generator.tsx) |
+| P0-4 | AI 管线错误消息 i18n | ✅ | [request.ts](file:///e:/Desktop/CICD/src/modules/exams/ai-pipeline/request.ts) |
+| P0-5 | ai-suggest.ts 类型安全 | ✅ | [ai-suggest.ts](file:///e:/Desktop/CICD/src/modules/lesson-preparation/ai-suggest.ts) |
+| P1-1 | AiService 接口抽象 | ✅ | [types.ts](file:///e:/Desktop/CICD/src/modules/ai/types.ts) |
+| P1-2 | 可复用 AI 组件 | ✅ | 9 个组件 |
+| P1-3 | AI Error Boundary | ✅ | [ai-error-boundary.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-error-boundary.tsx) |
+| P1-4 | 错题集 AI 集成 | ✅ | [ai-error-book-analysis.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-error-book-analysis.tsx) |
+| P1-5 | 改题 AI 集成 | ✅ | [ai-grading-assist.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-grading-assist.tsx) |
+| P1-6 | AI 使用监控 | ✅ | [usage-tracker.ts](file:///e:/Desktop/CICD/src/modules/ai/services/usage-tracker.ts) |
+| P1-7 | 备课 AI 内容生成 | ✅ | [ai-lesson-content-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-lesson-content-generator.tsx) |
+| P2-4 | 题目变体生成 | ✅ | [ai-question-variant-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-question-variant-generator.tsx) |
+| P2-7 | 架构图同步 | ✅ | 004/005 文档 |
+
+### 1.2 未完成项（V2 重点）
+
+| 编号 | V1 改进项 | 状态 | 原因 |
+|------|----------|------|------|
+| P2-1 | 流式响应 | ❌ | V1 仅实现非流式 |
+| P2-2 | AI 对话历史 | ❌ | 未持久化 |
+| P2-3 | Prompt 可配置化 | ⚠️ | 模板已抽取但仍硬编码在 TS 文件中 |
+| P2-5 | 多 Provider 对比 | ❌ | 未实现 |
+| P2-6 | 内容安全过滤 | ❌ | 未实现 |
+
+---
+
+## 二、深度可用性走查（逐组件）
+
+### 2.1 AiChatPanel — 通用聊天面板
+
+**文件**：[ai-chat-panel.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-chat-panel.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.1.1 | **无流式响应** — 用户等待完整 AI 回复才看到内容 | P0 | L77-96 | Khanmigo/Duolingo 均使用 SSE 流式输出，逐 token 渲染 | 长文本（>500 字）等待 10-30 秒，用户以为卡死 |
+| U2.1.2 | **无 Markdown 渲染** — AI 回复以纯文本显示 | P0 | L139 | 所有主流 AI 产品均渲染 Markdown（代码块、列表、表格） | AI 生成的代码、表格、列表无法正确显示，可读性极差 |
+| U2.1.3 | **无复制按钮** — 用户无法复制 AI 回复 | P1 | L132-141 | ChatGPT/Claude 均提供 hover 复制按钮 | 教师想复用 AI 生成的内容需手动选择文本 |
+| U2.1.4 | **无停止生成按钮** — 流式时无法中断 | P1 | — | Khanmigo 明确将 stop-generation 列为 K12 必备 | AI 生成不当内容时无法及时止损 |
+| U2.1.5 | **无建议提示词** — 空状态无引导 | P1 | L119 | Khanmigo 首屏展示"试试问我..."建议 | 新用户不知道能问什么，首次使用门槛高 |
+| U2.1.6 | **无清除对话按钮** — i18n 键 `chat.clear` 存在但无 UI | P1 | — | 所有聊天产品均有清空按钮 | 对话越来越长，上下文窗口爆满后 AI 回复质量下降 |
+| U2.1.7 | **无对话历史持久化** — 刷新页面对话丢失 | P1 | L44 | Khanmigo 提供 chat history 面板 | 教师备课时生成的 AI 内容刷新即丢失 |
+| U2.1.8 | **无 token/模型指示器** — 用户不知道用了哪个模型 | P2 | — | OpenAI PlayGround 显示模型与 token 用量 | 无法评估 AI 调用成本 |
+| U2.1.9 | **aria-live 缺失** — 屏幕阅读器无法感知新消息 | P1 | L121 | WCAG 2.1 AA 要求 | 视障用户无法使用 |
+
+### 2.2 AiGradingAssist — 批改辅助
+
+**文件**：[ai-grading-assist.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-grading-assist.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.2.1 | **CardDescription 与 CardTitle 使用相同 i18n 键** | P0 | L97 `t("grading.title")` | — | 描述区域显示重复文字，UI 不专业 |
+| U2.2.2 | **无批量批改** — 一次只能批改一题 | P1 | — | Khanmigo 的 student work summary 支持批量 | 教师批改 30 人 × 5 道主观题 = 150 次点击 |
+| U2.2.3 | **无分数对比** — 不显示教师已给分数 vs AI 建议 | P1 | — | — | 教师无法快速判断 AI 建议是否合理 |
+| U2.2.4 | **无置信度阈值配置** — 低置信度建议也直接展示 | P2 | L87 | — | confidence < 0.5 的建议可能误导教师 |
+| U2.2.5 | **无 Socratic 模式** — 直接给分而非引导思考 | P2 | — | Khanmigo 的 Socratic 方法不直接给答案 | 教师过度依赖 AI，丧失独立判断 |
+
+### 2.3 AiErrorBookAnalysis — 错题本分析
+
+**文件**：[ai-error-book-analysis.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-error-book-analysis.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.3.1 | **无"立即练习"按钮** — 相似题生成后只能"选择" | P0 | L150-159 | Duolingo Max 的 "Explain My Answer" 后直接进入练习 | 学生看到相似题但无法直接作答，流程断裂 |
+| U2.3.2 | **薄弱点分析不持久化** — 刷新即丢失 | P1 | L59 | Squirrel AI 持续追踪薄弱点变化趋势 | 无法追踪薄弱点改善进度 |
+| U2.3.3 | **无 SM2 算法集成** — AI 相似题不进入复习队列 | P1 | — | Squirrel AI 的闭环：诊断→练习→复习→再诊断 | AI 生成的相似题是一次性的，无法形成学习闭环 |
+| U2.3.4 | **无趋势可视化** — 薄弱点无历史趋势图 | P2 | — | Century Tech 的 dashboard 展示 mastery 进展 | 学生/家长无法看到进步 |
+| U2.3.5 | **无难度递进** — 相似题难度不随掌握度调整 | P2 | L69 `count: 3` | Squirrel AI 的自适应难度 | 掌握度高的学生仍收到简单题，浪费时间 |
+
+### 2.4 AiLessonContentGenerator — 备课内容生成
+
+**文件**：[ai-lesson-content-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-lesson-content-generator.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.4.1 | **CardDescription 与 CardTitle 使用相同 i18n 键** | P0 | L108 `t("lessonPrep.generateContent")` | — | 描述区域重复 |
+| U2.4.2 | **附加上下文 label 使用错误键** | P0 | L131 `t("lessonPrep.generateContent")` | — | 标签显示"生成内容"而非"附加上下文" |
+| U2.4.3 | **placeholder 使用错误键** | P0 | L137 `t("lessonPrep.generateContent")` | — | 占位符显示"生成内容" |
+| U2.4.4 | **插入按钮使用错误键** | P0 | L178 `t("lessonPrep.generateContent")` | — | 按钮显示"生成内容"而非"插入内容" |
+| U2.4.5 | **无内容预览/编辑** — 生成后直接插入 | P1 | L168-180 | Khanmigo 生成的内容可编辑后再插入 | 教师无法微调 AI 生成的内容 |
+| U2.4.6 | **无生成历史** — 无法回看之前生成的内容 | P1 | — | Khanmigo 的 chat history | 教师生成了 5 段内容，只能保留最后 1 段 |
+| U2.4.7 | **无课程标准对齐** — 生成内容不关联课标 | P2 | — | Khanmigo 与课程标准对齐 | 生成内容可能偏离教学大纲 |
+
+### 2.5 AiQuestionVariantGenerator — 题目变体生成
+
+**文件**：[ai-question-variant-generator.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-question-variant-generator.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.5.1 | **所有变体类型标签使用相同 i18n 键** | P0 | L87-89 全部 `t("exam.generate")` | — | 三个选项显示相同文字"生成"，无法区分 |
+| U2.5.2 | **无批量生成** — 一次只生成 1 个变体 | P1 | — | — | 教师需要 5 个变体需点击 5 次 |
+| U2.5.3 | **无难度滑块** — different_difficulty 无法指定目标难度 | P1 | — | — | 教师无法控制变简单还是变难 |
+| U2.5.4 | **无知识点映射展示** — 不显示变体覆盖的知识点 | P2 | — | Squirrel AI 的知识图谱可视化 | 教师无法验证变体是否覆盖目标知识点 |
+
+### 2.6 AiSuggestionCard — 相似题建议卡片
+
+**文件**：[ai-suggestion-card.tsx](file:///e:/Desktop/CICD/src/modules/ai/components/ai-suggestion-card.tsx)
+
+| 编号 | 问题 | 严重度 | 位置 | 行业对标 | 用户影响 |
+|------|------|--------|------|---------|---------|
+| U2.6.1 | **无难度筛选** — 所有难度混合展示 | P2 | — | — | 学生只想练习中等难度题时无法筛选 |
+| U2.6.2 | **无"全部添加"按钮** — 需逐题选择 | P2 | — | — | 批量添加效率低 |
+
+### 2.7 全局架构层面
+
+| 编号 | 问题 | 严重度 | 行业对标 | 用户影响 |
+|------|------|--------|---------|---------|
+| U2.7.1 | **无全局 AI 助手入口** | P0 | Khanmigo 嵌入式助手 / Duolingo 角色触发 | 用户在非集成页面无法获取 AI 帮助 |
+| U2.7.2 | **无上下文感知** | P0 | Khanmigo 自动感知当前学习内容 | AI 不知道用户当前在做什么，建议不精准 |
+| U2.7.3 | **无内容安全过滤** | P0 | Khanmigo 多层 moderation + Duolingo 人工审核 | 学生可能接触不当内容，违反 COPPA/FERPA |
+| U2.7.4 | **无家长 AI 功能** | P1 | Khanmigo 家长可见聊天记录 / Squirrel AI 24/7 家长面板 | 家长无法获取子女学情 AI 摘要 |
+| U2.7.5 | **无管理员 AI 仪表盘** | P1 | Khanmigo district dashboard / Century Tech 全校视图 | 管理员无法监控 AI 使用量与成本 |
+| U2.7.6 | **无学生学习路径** | P1 | Squirrel AI 纳米级知识图谱 / Century Tech nuggets | 学生缺少个性化学习引导 |
+| U2.7.7 | **无每日交互限制** | P1 | Khanmigo 每日上限防止滥用 | 学生可能过度使用 AI 聊天偏离学习 |
+
+---
+
+## 三、行业标杆对标
+
+### 3.1 竞品功能矩阵
+
+| 能力 | Khanmigo | Duolingo Max | Squirrel AI | Century Tech | 本系统 V1 | 本系统 V2 目标 |
+|------|----------|-------------|-------------|-------------|----------|--------------|
+| **流式输出** | ✅ SSE | ✅ SSE | ✅ | ✅ | ❌ | ✅ |
+| **Markdown 渲染** | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
+| **Socratic 模式** | ✅ 不直接给答案 | — | — | — | ❌ | ✅ |
+| **内容安全过滤** | ✅ 多层 moderation | ✅ 人工+AI | ✅ 物理中心 | ✅ 教师监督 | ❌ | ✅ |
+| **对话历史** | ✅ 可查看 | ✅ | ✅ | ✅ | ❌ | ✅ |
+| **全局助手入口** | ✅ 嵌入式 | ✅ 角色触发 | ✅ 平台级 | ✅ Dashboard | ❌ | ✅ |
+| **上下文感知** | ✅ 内容库集成 | ✅ 课程对齐 | ✅ 诊断驱动 | ✅ 自适应 | ❌ | ✅ |
+| **学习路径推荐** | — | — | ✅ 纳米级 | ✅ nuggets | ❌ | ✅ |
+| **家长面板** | ✅ 聊天记录可见 | — | ✅ 24/7 分析 | — | ❌ | ✅ |
+| **管理员仪表盘** | ✅ district | — | ✅ | ✅ 全校 | ❌ | ✅ |
+| **每日限制** | ✅ | — | — | — | ❌ | ✅ |
+| **停止生成** | ✅ | ✅ | — | — | ❌ | ✅ |
+| **批量批改** | ✅ student summary | — | — | ✅ 自标记 | ❌ | ✅ |
+| **自适应难度** | — | ✅ | ✅ 核心 | ✅ | ❌ | ✅ |
+
+### 3.2 关键差距分析
+
+#### 差距 1：无流式响应（影响所有 AI 交互）
+
+**行业做法**：
+- Khanmigo 和 Duolingo Max 均使用 SSE 流式输出
+- 逐 token 渲染模拟"打字效果"，降低感知延迟
+- 配合"停止生成"按钮，让用户可控
+
+**我们的差距**：
+- 所有 AI 调用等待完整响应才返回
+- 长文本生成时用户看到的是空白 + loading spinner
+- 无法中断不当内容生成
+
+**影响**：用户体验差，长文本等待 10-30 秒，学生误以为系统卡死
+
+#### 差距 2：无内容安全过滤（影响学生侧）
+
+**行业做法**（Khanmigo 多层防护）：
+1. **输入过滤**：Moderation API 分类用户输入，拦截暴力/自残/色情/PII
+2. **输出过滤**：AI 回复展示前扫描
+3. **行为限制**：每日交互上限
+4. **透明审计**：所有聊天记录对家长/教师可见
+5. **自动告警**：moderation 触发时邮件通知成人
+6. **访问控制**：未成年人仅通过家长/学区订阅
+
+**我们的差距**：
+- 学生可直接调用 AI 聊天，无任何过滤
+- 无每日限制
+- 无聊天记录审计
+- 无不当内容告警
+
+**影响**：违反 COPPA/FERPA 合规要求；学生可能接触不当内容；学校无法审计 AI 使用
+
+#### 差距 3：无全局 AI 助手入口
+
+**行业做法**：
+- Khanmigo：嵌入式聊天集成在教师/学生 dashboard 中
+- Duolingo Max：角色图标触发（Lin, Eddy 等角色）
+- 通用模式：右下角悬浮按钮 → 侧边抽屉
+
+**我们的差距**：
+- AI 仅嵌入在 4 个特定页面（备课/错题/试卷/批改）
+- 用户在其他页面无法获取 AI 帮助
+- 无上下文感知（AI 不知道用户当前页面）
+
+**影响**：AI 使用率低；用户在需要时找不到 AI 入口
+
+#### 差距 4：无学习路径推荐
+
+**行业做法**：
+- Squirrel AI：纳米级知识分解（10,000+ 节点），诊断驱动路径
+- Century Tech：nuggets 微内容 + 自适应路径
+- 共同点：诊断 → 路径 → 练习 → 复习 → 再诊断的闭环
+
+**我们的差距**：
+- 错题本 AI 分析是一次性的，不持久化
+- AI 生成的相似题不进入 SM2 复习队列
+- 无知识图谱可视化
+- 无自适应难度
+
+**影响**：AI 价值未形成闭环；学生缺少个性化学习引导
+
+#### 差距 5：无家长/管理员 AI 功能
+
+**行业做法**：
+- Khanmigo：家长可查看子女聊天记录；学区管理员有 dashboard
+- Squirrel AI：24/7 家长分析面板
+- Century Tech：全校课程覆盖视图
+
+**我们的差距**：
+- 家长端无任何 AI 功能
+- 管理员无 AI 使用统计
+- 无成本监控
+
+**影响**：家长无法获取子女学情 AI 摘要；管理员无法优化 AI 使用策略
+
+---
+
+## 四、V2 改进优先级
+
+### P0（紧急 — 影响安全与核心体验）
+
+| 编号 | 改进项 | 对标 | 实现方向 |
+|------|--------|------|---------|
+| V2-P0-1 | **流式响应（SSE）** | Khanmigo/Duolingo | 新增 `aiChatStreamAction` + EventSource API + 停止生成按钮 |
+| V2-P0-2 | **Markdown 渲染** | 所有竞品 | 引入 `react-markdown` + `remark-gfm`，AI 回复渲染为富文本 |
+| V2-P0-3 | **内容安全过滤** | Khanmigo 多层防护 | 输入/输出双层过滤 + 每日限制 + 学生侧 Socratic 模式 |
+| V2-P0-4 | **全局 AI 助手悬浮按钮** | Khanmigo 嵌入式 | 右下角悬浮按钮 → 侧边抽屉，上下文感知 |
+| V2-P0-5 | **修复 i18n 键错误** | — | 修复 AiGradingAssist/AiLessonContentGenerator/AiQuestionVariantGenerator 中重复/错误键 |
+| V2-P0-6 | **复制按钮 + 清除对话** | ChatGPT/Claude | AiChatPanel 增加 hover 复制 + 清除对话按钮 |
+| V2-P0-7 | **建议提示词** | Khanmigo | 空状态展示角色相关的建议问题 |
+| V2-P0-8 | **aria-live 无障碍** | WCAG 2.1 AA | 消息列表添加 `aria-live="polite"` |
+
+### P1（重要 — 影响功能完整性）
+
+| 编号 | 改进项 | 对标 | 实现方向 |
+|------|--------|------|---------|
+| V2-P1-1 | **AI 对话历史持久化** | Khanmigo | localStorage 存储最近 20 条对话 + 历史面板 |
+| V2-P1-2 | **家长 AI 学情摘要** | Khanmigo 家长面板 / Squirrel AI | 新增 `AiChildSummary` 组件 + `generateChildSummaryAction` |
+| V2-P1-3 | **管理员 AI 使用统计** | Khanmigo district / Century Tech | 新增 `AiUsageDashboard` 组件 + `getAiUsageStatsAction` |
+| V2-P1-4 | **学生学习路径推荐** | Squirrel AI / Century Tech | 新增 `AiStudyPath` 组件 + `recommendStudyPathAction` |
+| V2-P1-5 | **错题相似题"立即练习"** | Duolingo Max | AiErrorBookAnalysis 增加"练习"按钮，进入答题流程 |
+| V2-P1-6 | **备课内容预览/编辑** | Khanmigo | AiLessonContentGenerator 生成后可编辑再插入 |
+| V2-P1-7 | **批量 AI 批改** | Khanmigo student summary | 新增 `AiBatchGradingAssist` 组件 |
+| V2-P1-8 | **每日交互限制** | Khanmigo | Server Action 层按用户+日期计数，超限返回 429 |
+
+### P2（优化 — 提升体验与扩展性）
+
+| 编号 | 改进项 | 对标 | 实现方向 |
+|------|--------|------|---------|
+| V2-P2-1 | **自适应难度** | Squirrel AI | 相似题难度根据 masteryLevel 动态调整 |
+| V2-P2-2 | **薄弱点趋势可视化** | Century Tech | 薄弱点历史趋势图 |
+| V2-P2-3 | **知识点映射展示** | Squirrel AI 知识图谱 | 变体生成后展示覆盖的知识点 |
+| V2-P2-4 | **多 Provider 对比** | — | 同一 Prompt 并行调用多 Provider |
+| V2-P2-5 | **Prompt 可配置化** | — | Prompt 模板存入数据库，支持版本管理 |
+| V2-P2-6 | **token/模型指示器** | OpenAI PlayGround | AiChatPanel 显示模型与 token 用量 |
+| V2-P2-7 | **Socratic 模式** | Khanmigo | 学生侧 AI 不直接给答案，引导思考 |
+
+---
+
+## 五、用户旅程分析（多角色）
+
+### 5.1 教师旅程
+
+**场景**：张老师要批改 30 名学生的语文主观题作业
+
+**当前流程（V1）**：
+1. 进入作业批改页 → 看到学生列表
+2. 点击学生 A → 看到主观题答案
+3. 点击"AI 批改建议" → 等待 5 秒 → 看到 AI 建议
+4. 点击"应用分数" → 点击"应用反馈"
+5. 点击下一个学生 → 重复 2-4
+6. **总计**：30 学生 × 3 题 × 4 次点击 = 360 次点击
+
+**行业最佳实践（Khanmigo）**：
+1. 进入批改页 → AI 自动扫描所有学生答案
+2. AI 批量生成评分建议（student work summary）
+3. 教师查看汇总，快速确认/调整
+4. **总计**：1 次批量生成 + 30 次确认 = 31 次点击
+
+**差距**：缺少批量批改能力，效率差 10 倍
+
+### 5.2 学生旅程
+
+**场景**：李同学做错了一道数学题，想针对性练习
+
+**当前流程（V1）**：
+1. 进入错题本 → 看到错题列表
+2. 点击错题 → 打开详情对话框
+3. 点击"AI 智能分析" → 等待 → 看到相似题
+4. 点击"选择" → 相似题... 然后呢？**流程断裂**
+5. 无法直接练习相似题
+
+**行业最佳实践（Duolingo Max）**：
+1. 做错题 → "Explain My Answer" 按钮
+2. AI 解释为什么错 → 直接进入"再练一题"
+3. 相似题难度自适应 → 形成学习闭环
+
+**差距**：相似题生成后无法直接练习，无自适应难度，无学习闭环
+
+### 5.3 家长旅程
+
+**场景**：王家长想了解子女近期学习情况
+
+**当前流程（V1）**：
+1. 进入家长 dashboard → 看到成绩/考勤
+2. **无任何 AI 功能**
+3. 需手动翻阅各科成绩自行分析
+
+**行业最佳实践（Squirrel AI）**：
+1. 家长面板 → AI 自动生成子女学情摘要
+2. AI 识别薄弱点 → 给出家庭辅导建议
+3. 24/7 可查看详细分析
+
+**差距**：家长端完全无 AI 能力
+
+### 5.4 管理员旅程
+
+**场景**：赵校长想了解全校 AI 使用情况
+
+**当前流程（V1）**：
+1. **无任何 AI 管理功能**
+2. 无法知道哪些教师在用 AI
+3. 无法知道 AI 成本
+4. 无法知道 AI 效果
+
+**行业最佳实践（Khanmigo district）**：
+1. 管理员 dashboard → AI 使用量趋势
+2. 按教师/学科/班级分解
+3. 成本统计 + 异常告警
+
+**差距**：管理员完全无 AI 可见性
+
+---
+
+## 六、V2 实现方案
+
+### 6.1 流式响应架构
+
+```
+客户端 (EventSource)
+  └─▶ POST /api/ai/chat/stream (SSE Route)
+        └─▶ aiChatStreamAction (Server Action)
+              └─▶ AiService.chatStream() (返回 AsyncGenerator)
+                    └─▶ createAiChatCompletionStream() (OpenAI SDK stream: true)
+```
+
+**关键设计**：
+- 使用 Server-Sent Events（SSE）而非 WebSocket（单向足够，更简单）
+- 客户端用 `fetch` + `ReadableStream` 消费（EventSource 不支持 POST）
+- 支持 `AbortController` 中断生成
+- 流式完成后 `withAiTracking` 记录完整 token 用量
+
+### 6.2 全局 AI 助手架构
+
+```
+app/(dashboard)/layout.tsx
+  └─▶ <AiAssistantWidget /> (全局悬浮按钮)
+        ├─▶ usePathname() 感知当前页面
+        ├─▶ 根据路由推断上下文（如 /teacher/homework → 批改上下文）
+        └─▶ 侧边抽屉 <AiChatPanel>
+              ├─▶ systemPrompt 根据上下文动态生成
+              └─▶ contextMessage 注入当前页面信息
+```
+
+**上下文感知规则**：
+| 路由模式 | 上下文 | systemPrompt |
+|---------|--------|-------------|
+| `/teacher/homework/*` | 作业批改 | "You are a grading assistant..." |
+| `/teacher/lesson-plans/*` | 备课 | "You are a lesson planning assistant..." |
+| `/teacher/exams/*` | 试卷 | "You are an exam design assistant..." |
+| `/student/error-book/*` | 错题本 | "You are a study tutor. Use Socratic method..." |
+| `/student/homework/*` | 做作业 | "You are a homework helper. Don't give direct answers..." |
+| `/parent/*` | 家长面板 | "You are a family education advisor..." |
+
+### 6.3 内容安全过滤架构
+
+```
+aiChatAction (Server Action)
+  ├─▶ 1. 输入过滤：filterUserInput(messages)
+  │      └─▶ 检查关键词/PII/不当内容 → 拦截返回错误
+  ├─▶ 2. 每日限制：checkDailyLimit(userId)
+  │      └─▶ 超限返回 429
+  ├─▶ 3. 调用 AI：service.chat()
+  ├─▶ 4. 输出过滤：filterAiOutput(content)
+  │      └─▶ 扫描不当内容 → 替换/拦截
+  └─▶ 5. 记录审计：logAiInteraction(userId, messages, response)
+```
+
+**学生侧额外限制**：
+- Socratic 模式：system prompt 强制不直接给答案
+- 每日上限：50 条消息（可配置）
+- 关键词过滤：暴力、自残、色情、PII
+
+### 6.4 i18n 新增键结构
+
+```json
+{
+  "chat": {
+    "streaming": "AI is typing...",
+    "stopGeneration": "Stop generating",
+    "copy": "Copy",
+    "copied": "Copied!",
+    "clearConfirm": "Clear all messages?",
+    "suggestedPrompts": {
+      "teacher": ["Help me grade this", "Generate a lesson activity", "Create a quiz question"],
+      "student": ["Explain this concept", "Give me a practice question", "Help me study"],
+      "parent": ["How is my child doing?", "What should I focus on at home?"],
+      "admin": ["Show AI usage stats", "Which teachers use AI most?"]
+    }
+  },
+  "safety": {
+    "blocked": "Your message was blocked by safety filter",
+    "dailyLimit": "Daily AI usage limit reached. Please try again tomorrow.",
+    "studentMode": "AI is in student mode. It will guide you to find the answer."
+  },
+  "parent": {
+    "summary": "AI Learning Summary",
+    "generateSummary": "Generate Summary",
+    "weaknessHint": "Areas to focus on",
+    "suggestion": "Family tutoring suggestion"
+  },
+  "admin": {
+    "usageDashboard": "AI Usage Dashboard",
+    "totalCalls": "Total AI Calls",
+    "activeUsers": "Active Users",
+    "costEstimate": "Estimated Cost",
+    "topUsers": "Top Users",
+    "byCapability": "By Capability"
+  },
+  "studyPath": {
+    "title": "Your Learning Path",
+    "nextSteps": "Recommended Next Steps",
+    "mastered": "Mastered",
+    "inProgress": "In Progress",
+    "needsWork": "Needs Work"
+  },
+  "lessonPrep": {
+    "additionalContext": "Additional context",
+    "additionalContextPlaceholder": "Add any specific requirements...",
+    "insertContent": "Insert Content",
+    "editBeforeInsert": "Edit before insert"
+  },
+  "exam": {
+    "variantType": {
+      "same_knowledge_point": "Same knowledge point, different context",
+      "different_difficulty": "Different difficulty",
+      "different_format": "Different format"
+    }
+  }
+}
+```
+
+---
+
+## 七、架构图同步说明
+
+V2 实现后需在 004/005 文档中新增以下节点：
+
+### 7.1 新增导出
+
+| 文档 | 节点 | 内容 |
+|------|------|------|
+| 005 | `modules.ai.exports.functions` | 新增 `aiChatStreamAction`、`generateChildSummaryAction`、`getAiUsageStatsAction`、`recommendStudyPathAction` |
+| 005 | `modules.ai.exports.components` | 新增 `AiAssistantWidget`、`AiMarkdownRenderer`、`AiChildSummary`、`AiUsageDashboard`、`AiStudyPath`、`AiBatchGradingAssist` |
+| 005 | `modules.ai.exports.services` | 新增 `filterUserInput`、`filterAiOutput`、`checkDailyLimit`、`logAiInteraction` |
+| 004 | AI 模块章节 | 新增 V2 组件清单与安全过滤说明 |
+
+### 7.2 新增路由
+
+| 文档 | 节点 | 内容 |
+|------|------|------|
+| 005 | `routes` | 新增 `/api/ai/chat/stream`（SSE 端点） |
+
+### 7.3 新增依赖
+
+| 文档 | 节点 | 内容 |
+|------|------|------|
+| 005 | `dependencyMatrix` | `parent → ai`、`dashboard → ai`（全局 widget） |
+
+---
+
+## 八、总结
+
+V1 完成了 AI 模块的基础架构与四大业务场景集成，但在**用户体验深度**、**安全合规**、**多角色覆盖**三个方面与行业标杆存在显著差距。
+
+V2 的核心目标是：
+1. **补齐流式 + Markdown + 安全过滤**三大基础体验
+2. **新增全局助手 + 上下文感知**提升 AI 可达性
+3. **覆盖家长 + 管理员**两个缺失角色
+4. **实现学习路径推荐**形成学习闭环
+5. **修复 i18n 键错误**消除 UI 缺陷
+
+实现后，AI 模块将达到 Khanmigo 级别的功能完整度，满足 K12 教育场景的安全合规要求。