NextEdu/docs/architecture/audit/ai-module-audit-report-v2.md

# 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 教育场景的安全合规要求。