214 lines
7.8 KiB
Markdown
214 lines
7.8 KiB
Markdown
|
# 知习 AI 架构 V1：决策与执行清单
|
|||
|
|
|
|||
|
|
> **2026-05-16 已确认并完成**：三层架构（Provider → Gateway → Workflow），阶段 0 全部完成。
|
|||
|
|
> 设计方向文档：[AI架构设计.md](./[设计中]-AI架构设计.md)
|
|||
|
|
>
|
|||
|
|
> **状态：✅ 阶段 0 完成 | 阶段 1 基本完成 | 阶段 2 待推进**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 一、架构原则
|
|||
|
|
|
|||
|
|
## 核心分层
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
业务模块层（ActiveRecall / ai-analysis）
|
|||
|
|
↓ 调用
|
|||
|
|
AI Workflow 层（ActiveRecallAnalysisWorkflow）
|
|||
|
|
↓ 调用
|
|||
|
|
AI Gateway 层（AiGatewayService：选模型、记日志、解析 JSON、超时重试）
|
|||
|
|
↓ 调用
|
|||
|
|
AI Provider 层（DeepSeekProvider / MiniMaxProvider / MockAiProvider）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**每一层的职责边界**：
|
|||
|
|
|
|||
|
|
| 层 | 知道什么 | 不知道什么 |
|
|||
|
|
|----|---------|-----------|
|
|||
|
|
| Provider | messages, model, temperature, signal | 知识点、主动回忆、FocusItem |
|
|||
|
|
| Gateway | feature, promptVersion, cost, retry | 业务 Workflow 细节 |
|
|||
|
|
| Workflow | 知识点、回答、分析逻辑 | 模型 API 细节 |
|
|||
|
|
| 业务模块 | 自己的 CRUD | AI 调用细节 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 二、已确认决策（全部实现）
|
|||
|
|
|
|||
|
|
| 编号 | 决策 | 结论 | 状态 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| A | 架构分层 | Provider → Gateway → Workflow 三层 | ✅ |
|
|||
|
|
| B | Mock 保留 | Mock 跑通闭环，永久保留 | ✅ |
|
|||
|
|
| C | 第一个 Provider | DeepSeek（V4-Flash 便宜，V4-Pro 强推理） | ✅ |
|
|||
|
|
| D | 第二个 Provider | MiniMax M2.7（Coding Plan 已付费，主力分析） | ✅ |
|
|||
|
|
| E | Model Router | 三层：cheap / primary / strong，显式 fallback | ✅ |
|
|||
|
|
| F | Gateway 超时 | AbortController 30s + 自动重试 + fallback | ✅ |
|
|||
|
|
| G | Prompt 管理 | 代码文件 + promptKey / promptVersion 追踪 | ✅ |
|
|||
|
|
| H | JSON 校验 | Zod Schema + 三层容错（parse → fence → extract） | ✅ |
|
|||
|
|
| I | 成本控制 | AiUsageLog + AiCostCalculatorService | ✅ |
|
|||
|
|
| J | 旧代码清理 | 删除 infrastructure/ai，ai-analysis 迁到新 gateway | ✅ |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 三、当前文件结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
src/modules/ai/
|
|||
|
|
├── ai.module.ts # NestJS DI：Map<string, AiProvider>
|
|||
|
|
├── ai.controller.ts # POST /ai/analyze-recall · GET /ai/models
|
|||
|
|
├── model-router.ts # cheap / primary / strong 三档路由
|
|||
|
|
├── gateway/
|
|||
|
|
│ ├── ai-gateway.types.ts # GatewayRequest / GatewayResponse / ModelTier
|
|||
|
|
│ └── ai-gateway.service.ts # 统一入口：选模型、30s超时、重试、JSON三层容错、记日志
|
|||
|
|
├── providers/
|
|||
|
|
│ ├── ai-provider.interface.ts # AiGenerateInput(signal) / AiGenerateOutput
|
|||
|
|
│ ├── mock-ai.provider.ts # 永久保留，返回 simulated 分析结果
|
|||
|
|
│ ├── deepseek.provider.ts # DeepSeek API（OpenAI 兼容）
|
|||
|
|
│ └── minimax.provider.ts # MiniMax M2.7（OpenAI 兼容）
|
|||
|
|
├── prompts/
|
|||
|
|
│ ├── prompt-template.service.ts # key + version 注册表
|
|||
|
|
│ ├── active-recall-analysis.prompt.ts # System Prompt
|
|||
|
|
│ └── schemas/
|
|||
|
|
│ └── active-recall-analysis.schema.ts # Zod Schema + JSON 输出示例
|
|||
|
|
├── usage/
|
|||
|
|
│ ├── ai-cost-calculator.service.ts # 按模型计算费用
|
|||
|
|
│ └── ai-usage-log.service.ts # 写 AiUsageLog
|
|||
|
|
└── workflows/
|
|||
|
|
└── active-recall-analysis.workflow.ts # 第一个 Workflow：主动回忆分析
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 关联模块
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
src/modules/ai-analysis/ # 导入 AiModule，用 ActiveRecallAnalysisWorkflow
|
|||
|
|
├── ai-analysis.module.ts
|
|||
|
|
├── ai-analysis.controller.ts # POST /ai-analysis · GET /ai-analysis/:id
|
|||
|
|
├── ai-analysis.service.ts
|
|||
|
|
└── ai-analysis.repository.ts
|
|||
|
|
|
|||
|
|
src/modules/active-recall/ # 导入 AiModule，提交答案异步触发分析
|
|||
|
|
├── active-recall.module.ts
|
|||
|
|
├── active-recall.controller.ts # POST /active-recalls/:id/submit
|
|||
|
|
├── active-recall.service.ts
|
|||
|
|
└── active-recall.repository.ts
|
|||
|
|
|
|||
|
|
src/infrastructure/ai/ # ❌ 已删除（旧 AiService + 旧 MockAiProvider）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 四、数据流（主动回忆分析）
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
1. POST /active-recalls/:id/submit
|
|||
|
|
↓
|
|||
|
|
2. ActiveRecallService.submit() 保存回答 + 异步 analysisWorkflow.execute()
|
|||
|
|
↓
|
|||
|
|
3. ActiveRecallAnalysisWorkflow.execute({ userId, questionText, knowledgeItemContent, userAnswer })
|
|||
|
|
↓
|
|||
|
|
4. PromptTemplateService.get('active-recall-analysis', '1.0.0')
|
|||
|
|
↓
|
|||
|
|
5. AiGatewayService.generate({ feature, userId, tier:'primary', promptKey, messages, outputSchema })
|
|||
|
|
↓
|
|||
|
|
6. ModelRouter.resolve('primary') → minimax-m2.7（fallback: deepseek-v4-pro）
|
|||
|
|
↓
|
|||
|
|
7. Provider.generate() + AbortController(30s) → fetch()
|
|||
|
|
↓
|
|||
|
|
8. JSON 三层容错：直接 parse → 提取 markdown fence → 提取 { } 对象
|
|||
|
|
↓
|
|||
|
|
9. Zod Schema 校验 → ActiveRecallAnalysisResult
|
|||
|
|
↓
|
|||
|
|
10. AiUsageLogService.log() 记 tokens / cost / latency
|
|||
|
|
↓
|
|||
|
|
11. GatewayResponse { parsed, usage }
|
|||
|
|
↓
|
|||
|
|
12. Workflow 返回 ActiveRecallAnalysisResult
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 五、数据库
|
|||
|
|
|
|||
|
|
## AiUsageLog（已加入 schema，待 db push）
|
|||
|
|
|
|||
|
|
```prisma
|
|||
|
|
model AiUsageLog {
|
|||
|
|
id String @id @default(cuid())
|
|||
|
|
userId String
|
|||
|
|
feature String @db.VarChar(64)
|
|||
|
|
provider String @db.VarChar(32)
|
|||
|
|
model String @db.VarChar(100)
|
|||
|
|
tier String @db.VarChar(32)
|
|||
|
|
promptKey String @db.VarChar(128)
|
|||
|
|
promptVersion String @db.VarChar(32)
|
|||
|
|
inputTokens Int @default(0)
|
|||
|
|
outputTokens Int @default(0)
|
|||
|
|
estimatedCost Float @default(0)
|
|||
|
|
latencyMs Int @default(0)
|
|||
|
|
success Boolean @default(true)
|
|||
|
|
errorMessage String? @db.VarChar(500)
|
|||
|
|
createdAt DateTime @default(now())
|
|||
|
|
|
|||
|
|
user User @relation(fields: [userId], references: [id])
|
|||
|
|
|
|||
|
|
@@index([userId])
|
|||
|
|
@@index([feature])
|
|||
|
|
@@index([createdAt])
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> ⚠️ `prisma db push` 待 SSH 隧道连通后执行
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 六、可执行任务状态
|
|||
|
|
|
|||
|
|
## 阶段 0：AI 地基 ✅ 14/14
|
|||
|
|
|
|||
|
|
| # | 任务 | 状态 |
|
|||
|
|
|---|------|------|
|
|||
|
|
| 1 | AiUsageLog 表（prisma schema） | ✅ |
|
|||
|
|
| 2 | 统一 AiProvider 接口（generate + signal） | ✅ |
|
|||
|
|
| 3 | ModelRouter（cheap / primary / strong） | ✅ |
|
|||
|
|
| 4 | AiGatewayService（统一入口 + JSON 容错 + 超时重试） | ✅ |
|
|||
|
|
| 5 | PromptTemplateService（key + version） | ✅ |
|
|||
|
|
| 6 | DeepSeekProvider | ✅ |
|
|||
|
|
| 7 | MiniMaxProvider | ✅ |
|
|||
|
|
| 8 | Zod Schema（ActiveRecallAnalysisResult） | ✅ |
|
|||
|
|
| 9 | AiUsageLogService + AiCostCalculatorService | ✅ |
|
|||
|
|
| 10 | ActiveRecallAnalysisWorkflow | ✅ |
|
|||
|
|
| 11 | AiModule（DI 注入） | ✅ |
|
|||
|
|
| 12 | AiController（analyze-recall / models） | ✅ |
|
|||
|
|
| 13 | MockAiProvider（保留不动） | ✅ |
|
|||
|
|
| 14 | 删除旧 infrastructure/ai | ✅ |
|
|||
|
|
|
|||
|
|
## 阶段 1：集成打通 ✅ 4/6
|
|||
|
|
|
|||
|
|
| # | 任务 | 状态 |
|
|||
|
|
|---|------|------|
|
|||
|
|
| 15 | ai-analysis 改用 ActiveRecallAnalysisWorkflow | ✅ |
|
|||
|
|
| 16 | ai-analysis.module 导入 AiModule | ✅ |
|
|||
|
|
| 17 | active-recall 提交答案触发分析 | ✅ |
|
|||
|
|
| 18 | Gateway AbortController 30s 超时 | ✅ |
|
|||
|
|
| 19 | prisma db push 建 AiUsageLog 表 | ⚠️ 等隧道 |
|
|||
|
|
| 20 | 真实 AI 切换 + Prompt 调优 | ⏳ 后续 |
|
|||
|
|
|
|||
|
|
## 阶段 2：待推进
|
|||
|
|
|
|||
|
|
| # | 任务 |
|
|||
|
|
|---|------|
|
|||
|
|
| 21 | 11 个业务 Repository：in-memory Map → Prisma |
|
|||
|
|
| 22 | 所有 Controller 加 JwtAuthGuard |
|
|||
|
|
| 23 | 真实 AI 联调 + 样本测试 + Prompt 调优 |
|
|||
|
|
| 24 | 更多 Workflow（知识导入、费曼分析、复习卡片、长期趋势） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 七、一句话总结
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
DeepSeek 只是第一个模型，不是 AI 架构本身。
|
|||
|
|
知习现在有了「可替换模型、可追踪成本、可校验输出、可沉淀学习结果」的三层 AI 工作流架构：
|
|||
|
|
Provider → Gateway → Workflow。
|
|||
|
|
阶段 0 全部完成，阶段 1 基本完成。
|
|||
|
|
```
|