# 知习 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 基本完成。
```