fix(ai): V3 长期问题修复+规则合规+竞品对标
## P1 安全加固 - 原子化每日限额（tryConsumeDailyQuota）解决 TOCTOU 竞态 - 流式端点补齐 Zod 校验 + rate limit + 服务端强制 systemPrompt - 配额回退机制（refundDailyQuota）：过滤/失败不扣配额 - PII 最小化：移除 AI prompt 中的学生姓名 ## P1 数据一致性 - 修复 capability 埋点缺失 child_summary/study_path 类型 - 创建 data-access.ts：真实统计聚合替代硬编码零 - 修复 generateChildSummary/recommendStudyPath 的 capability 标记 ## P2 可靠性 - AI 调用重试机制（withRetry 指数退避，429/5xx，2 次重试） - 30s 超时配置 - 流式 controller 安全 enqueue（防已关闭抛错） - localStorage 防抖持久化（500ms，流式过程中跳过） ## P2 TypeScript/规则合规 - 移除 as 断言（VariantType 类型守卫、Permission 类型、StreamErrorKey） - 补齐返回类型标注（POST/getStatusFromError/DashboardLayout） - 拆分 use-ai-chat-stream hook（190→107 行，函数体≤80 行） - 抽取 stream-utils.ts（SSE 解析/错误映射/消息工具） - Tailwind 任意值添加注释说明（max-w-[80%] 聊天气泡） ## P3 竞品对标 - 苏格拉底式辅导强化（对标 Khanmigo）： - SOCRATIC_TUTOR_SYSTEM_PROMPT 3 级提示升级 - 强化 STUDENT_BLOCKED_PATTERNS 正则（中英文答案拦截） - validateSocraticOutput 服务端校验（问号结尾+连续陈述句限制） - socratic_warning SSE 事件类型 - 知识图谱集成（对标 Squirrel AI）： - StudyPathInput 新增 knowledgeGraph/textbookId 字段 - recommendStudyPathAction 自动从 textbooks 模块获取图谱+掌握度 - STUDY_PATH_SYSTEM_PROMPT 增加前置依赖链规则 - WEAKNESS_ANALYSIS_SYSTEM_PROMPT 增加 rootCause 字段 ## 架构文档同步 - 004 更新 AI 模块章节（V3 标记/新导出/依赖关系/安全机制/文件清单） - 005 更新 modules.ai 节点（dependsOn/exports/dataAccess/streamUtils/dependencyMatrix）
This commit is contained in:
SpecialX
@@ -2056,33 +2056,41 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
| **student** | `AiStudyPath` | `student/*` | 学习路径推荐 — V2 新增 |
|
||||
|
||||
**依赖关系**：
|
||||
- `modules/ai` → `shared/lib/ai`（AI SDK 封装，含流式 `createAiChatCompletionStream`）
|
||||
- `modules/ai` → `shared/lib/ai`（AI SDK 封装，含流式 `createAiChatCompletionStream`，V3 增加 `withRetry` 重试机制）
|
||||
- `modules/ai` → `shared/lib/auth-guard`（权限校验）
|
||||
- `modules/ai` → `shared/lib/track-event`（使用量埋点）
|
||||
- `modules/ai` → `shared/types/permissions`（权限常量）
|
||||
- `modules/ai` → `shared/types/action-state`（返回值类型）
|
||||
- `modules/ai` → `modules/textbooks/data-access-graph`（知识图谱+掌握度查询）— V3 新增
|
||||
- `app/(dashboard)/layout` → `modules/ai`（全局 Provider + Widget）— V2 新增
|
||||
- `app/api/ai/chat/stream` → `modules/ai/services/content-safety`（SSE 端点安全过滤）— V3 加固
|
||||
- 业务模块 → `modules/ai/context/ai-client-provider`（通过 Context 注入）
|
||||
- 业务模块 → `modules/ai/components/*`（组合 AI 组件）
|
||||
|
||||
**安全机制（V2 新增）**：
|
||||
**安全机制（V2 新增 / V3 加固）**：
|
||||
- 输入过滤：`filterUserInput` 拦截暴力/自残/色情/PII
|
||||
- 输出过滤：`filterAiOutput` 扫描 AI 回复
|
||||
- 每日限制：学生 50 次/天，教师 200 次/天，家长 30 次/天
|
||||
- 学生 Socratic 模式：system prompt 强制不直接给答案
|
||||
- SSE 端点权限校验：`requirePermission(AI_CHAT)`
|
||||
- V3 原子配额：`tryConsumeDailyQuota` 解决 TOCTOU 竞态，`refundDailyQuota` 过滤/失败时回退
|
||||
- V3 苏格拉底校验：`validateSocraticOutput` 检查问号结尾+连续陈述句限制，`SOCRATIC_TUTOR_SYSTEM_PROMPT` 3 级提示升级
|
||||
- V3 SSE 端点加固：Zod 校验 + rate limit + 服务端强制 systemPrompt（忽略客户端）
|
||||
- V3 重试机制：`withRetry` 指数退避（429/5xx，2 次重试，1s/2s/4s 延迟）
|
||||
- V3 知识图谱集成：`recommendStudyPathAction` 自动从 textbooks 模块获取图谱+掌握度注入 prompt
|
||||
|
||||
**文件清单**：
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `modules/ai/types.ts` | ~270 | 类型定义（8 个业务场景类型 + AiService/AiClientService） |
|
||||
| `modules/ai/schema.ts` | ~205 | Zod 验证 schema（8 个输入 + 8 个输出） |
|
||||
| `modules/ai/actions.ts` | ~340 | 9 个 Server Actions（含权限校验） |
|
||||
| `modules/ai/services/ai-service.ts` | ~400 | DefaultAiService 实现（8 个方法） |
|
||||
| `modules/ai/services/prompt-templates.ts` | ~210 | 8 个系统提示词模板 |
|
||||
| `modules/ai/services/usage-tracker.ts` | ~83 | AI 使用量埋点 |
|
||||
| `modules/ai/services/content-safety.ts` | ~130 | 内容安全过滤（输入/输出/每日限制）— V2 新增 |
|
||||
| `modules/ai/types.ts` | ~290 | 类型定义（8 个业务场景类型 + AiService/AiClientService，V3 新增 knowledgeGraph/textbookId） |
|
||||
| `modules/ai/schema.ts` | ~230 | Zod 验证 schema（8 个输入 + 8 个输出，V3 新增 knowledgeGraph/textbookId） |
|
||||
| `modules/ai/actions.ts` | ~400 | 9 个 Server Actions（含权限校验，V3 新增知识图谱获取） |
|
||||
| `modules/ai/data-access.ts` | ~138 | AI 事件存储+统计聚合 — V3 新增 |
|
||||
| `modules/ai/services/ai-service.ts` | ~430 | DefaultAiService 实现（8 个方法，V3 新增知识图谱上下文注入） |
|
||||
| `modules/ai/services/prompt-templates.ts` | ~250 | 9 个系统提示词模板（V3 新增 SOCRATIC_TUTOR_SYSTEM_PROMPT） |
|
||||
| `modules/ai/services/usage-tracker.ts` | ~90 | AI 使用量埋点（V3 新增 child_summary/study_path 能力） |
|
||||
| `modules/ai/services/content-safety.ts` | ~290 | 内容安全过滤（输入/输出/每日限制/原子配额/苏格拉底校验）— V2 新增 / V3 加固 |
|
||||
| `modules/ai/context/ai-client-provider.tsx` | ~62 | React Context Provider + Hooks |
|
||||
| `modules/ai/components/ai-assistant-widget.tsx` | ~170 | 全局 AI 助手悬浮按钮 — V2 新增 |
|
||||
| `modules/ai/components/ai-chat-panel.tsx` | ~305 | AI 对话面板（流式 + Markdown）— V2 增强 |
|
||||
@@ -2097,7 +2105,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
| `modules/ai/components/ai-error-boundary.tsx` | ~88 | AI 错误边界 |
|
||||
| `modules/ai/components/ai-skeleton.tsx` | ~47 | AI 骨架屏 |
|
||||
| `modules/ai/components/ai-provider-selector.tsx` | ~129 | 服务商选择器 |
|
||||
| `modules/ai/hooks/use-ai-chat-stream.ts` | ~170 | 流式 AI 对话 Hook — V2 新增 |
|
||||
| `modules/ai/hooks/use-ai-chat-stream.ts` | ~107 | 流式 AI 对话 Hook（V3 拆分至 ≤80 行函数体）— V2 新增 / V3 重构 |
|
||||
| `modules/ai/hooks/stream-utils.ts` | ~120 | SSE 流解析工具（consumeSseStream/getStreamErrorKey 等）— V3 新增 |
|
||||
| `modules/ai/hooks/use-ai-chat.ts` | ~57 | 非流式 AI 对话 Hook |
|
||||
| `modules/ai/hooks/use-ai-suggestion.ts` | ~72 | AI 建议 Hook |
|
||||
| `app/api/ai/chat/stream/route.ts` | ~160 | SSE 流式端点 — V2 新增 |
|
||||
|
||||
@@ -16341,7 +16341,8 @@
|
||||
},
|
||||
"ai": {
|
||||
"dependsOn": [
|
||||
"shared"
|
||||
"shared",
|
||||
"textbooks"
|
||||
],
|
||||
"uses": {
|
||||
"shared": [
|
||||
@@ -16353,6 +16354,10 @@
|
||||
"types.action-state",
|
||||
"lib.track-event.trackEvent",
|
||||
"i18n.messages"
|
||||
],
|
||||
"textbooks": [
|
||||
"data-access-graph.getKnowledgePointsWithRelations",
|
||||
"data-access-graph.getStudentKpMastery"
|
||||
]
|
||||
},
|
||||
"exports": {
|
||||
@@ -16422,11 +16427,27 @@
|
||||
"filterAiOutput",
|
||||
"checkDailyLimit",
|
||||
"incrementDailyUsage",
|
||||
"getDailyLimit"
|
||||
"getDailyLimit",
|
||||
"tryConsumeDailyQuota",
|
||||
"refundDailyQuota",
|
||||
"validateSocraticOutput"
|
||||
],
|
||||
"dataAccess": [
|
||||
"recordAiEvent",
|
||||
"getAiUsageStats"
|
||||
],
|
||||
"streamUtils": [
|
||||
"consumeSseStream",
|
||||
"getStreamErrorKey",
|
||||
"extractErrorMessage",
|
||||
"removeTrailingEmptyAssistant",
|
||||
"appendTokenToLastAssistant"
|
||||
],
|
||||
"promptTemplates": [
|
||||
"CHILD_SUMMARY_SYSTEM_PROMPT",
|
||||
"STUDY_PATH_SYSTEM_PROMPT"
|
||||
"STUDY_PATH_SYSTEM_PROMPT",
|
||||
"SOCRATIC_TUTOR_SYSTEM_PROMPT",
|
||||
"CHAT_SYSTEM_PROMPT"
|
||||
]
|
||||
},
|
||||
"integrations": {
|
||||
@@ -16841,6 +16862,12 @@
|
||||
"type": "normal",
|
||||
"description": "使用 lib/ai.createAiChatCompletion、auth-guard.requirePermission、types.permissions、types.action-state"
|
||||
},
|
||||
{
|
||||
"from": "ai",
|
||||
"to": "textbooks",
|
||||
"type": "normal",
|
||||
"description": "V3 新增：使用 data-access-graph.getKnowledgePointsWithRelations/getStudentKpMastery 获取知识图谱与掌握度，注入学习路径推荐"
|
||||
},
|
||||
{
|
||||
"from": "homework",
|
||||
"to": "ai",
|
||||
|
||||
Reference in New Issue
Block a user