startup-plan/技术设计/api-server/AI架构设计.md

# 知习 AI 工作流与学习 Agent 设计总结

> **设计方向文档。**
> 
> **实现状态（2026-05-17）**：
> - ✅ 三层架构落地：Provider（DeepSeek + MiniMax + Mock）→ Gateway → Workflow
> - ✅ AI Gateway 完整实现（多模型路由、重试、成本计算、JSON 解析三层回退）
> - ✅ 1 个 Workflow 完成：主动回忆分析（ActiveRecallAnalysisWorkflow）
> - 🔶 待实现 Workflow：知识导入解析、费曼解释评估、复习卡片生成、长期趋势分析
> - ✅ AI Usage Logging + Cost Calculation 已接入
> 
> **最后更新**：2026-05-17

## 一、核心原则

知习的 AI 能力不应该是一套通用聊天接口，也不应该所有业务都共用同一套 AI 工作流。

更合理的设计是：

```text
以产品业务流程为主导
按业务场景划分 AI 工作流
按任务复杂度选择模型
用用户学习画像实现“越用越懂你”
后期再演进为受控的学习 Agent
```

当前阶段不建议一开始就做完全自治 Agent，也不建议为每个用户单独部署一个真实 Agent 进程。

更合理的是：

```text
统一 AI Workflow Engine
+ 每个用户独立的学习画像
+ 每个用户独立的长期学习记忆
+ 可复用的 Prompt / Skill / Workflow
= 逻辑上的个人学习 Agent
```

用户感知上可以是“我的专属学习 Agent”，但技术实现上不应该是一人一个独立运行的 Agent。

---

## 二、为什么不能所有业务共用一套 AI 工作流

知习里的 AI 任务类型差异很大。

例如：

```text
知识导入
主动回忆分析
费曼解释分析
待巩固项生成
复习卡片生成
长期学习趋势分析
后台风控和成本监控
```

这些任务的输入、目标、模型要求、成本要求都不同。

所以不应该设计成：

```text
所有任务 → 同一个 Prompt → 同一个模型 → 同一种分析结果
```

而应该设计成：

```text
不同业务场景 → 不同 AI Workflow → 不同模型策略 → 不同结构化输出
```

---

## 三、业务分级工作流设计

### 1. 知识导入工作流

目标：把用户输入的内容整理成可学习结构。

```text
上传文档 / 输入内容
→ 文本提取
→ 内容清洗
→ 知识点切分
→ 生成标题 / 摘要 / 标签
→ 用户确认
→ 入库
```

适合模型：

```text
便宜模型
中档模型
规则代码
```

不需要一开始就使用最强模型。

---

### 2. 主动回忆分析工作流

目标：判断用户是否真正理解知识点。

```text
用户提交主动回忆回答
→ 检查回答质量
→ 提取回答覆盖的要点
→ 对比知识点关键点
→ 判断理解程度
→ 找出遗漏 / 误解 / 模糊表达
→ 生成待巩固项
→ 生成复习建议
→ 保存结构化分析结果
```

这是知习最核心的 AI 工作流之一，应该使用主力模型。

适合模型：

```text
主力模型
强模型
必要时结合便宜模型做预处理
```

注意：便宜模型可以做清洗和提取，但核心判断最好由主力模型完成。

---

### 3. 复习工作流

目标：低成本、高频地帮助用户完成间隔复习。

```text
读取到期复习项
→ 生成复习卡片
→ 用户回答
→ 判断掌握情况
→ 更新复习状态
→ 更新 nextReviewAt
```

适合模型：

```text
规则算法
便宜模型
中档模型
少量核心判断使用主力模型
```

复习工作流不应该每一步都调用强模型，否则成本会过高。

---

### 4. 长期学习分析工作流

目标：根据用户一段时间内的学习数据，生成趋势分析和改进建议。

```text
读取最近 7 / 30 天学习记录
→ 统计主动回忆表现
→ 统计薄弱点类型
→ 识别重复错误
→ 分析复习完成率
→ 生成阶段性学习报告
→ 给出下一阶段建议
```

这个工作流可以异步执行，不需要用户实时等待。

适合模型：

```text
中档模型
主力模型
异步队列
```

---

### 5. 后台风控与成本分析工作流

目标：控制 AI 成本、监控异常调用、辅助后台运营。

```text
统计 AI 调用次数
→ 计算 token 和成本
→ 识别异常用户
→ 识别高失败率任务
→ 生成后台告警
→ 辅助管理员排查问题
```

这个工作流主要靠规则和数据库统计，不一定需要强模型。

---

## 四、模型选择原则

模型选择不应该按“哪个最强”来决定，而应该按任务分级。

可以分成四类：

```text
轻任务：便宜模型
核心分析：主力模型
复杂推理：强模型
后台异步任务：可低优先级慢慢跑
```

例如：

```text
简单数据清洗、摘要、标签提取：
使用便宜模型或规则代码。

主动回忆薄弱点分析：
使用 DeepSeek V4 Pro / V4 Flash 这类主力模型。

长期学习趋势分析：
可以异步使用主力模型。

复习卡片生成：
可以使用中档模型或便宜模型。
```

关键原则：

```text
便宜模型负责客观提取和清洗
主力模型负责学习判断和薄弱点诊断
强模型必须能看到原始证据，不能只依赖便宜模型的二次总结
```

避免这种高风险流程：

```text
用户原始回答
→ 便宜模型总结
→ 强模型只看总结后做判断
```

更安全的是：

```text
用户原始回答
+ 知识点原文 / 关键点
+ 便宜模型提取结果
→ 主力模型综合判断
```

---

## 五、用户数据不足时怎么处理

第一版不应该依赖“海量用户数据”。

要区分三种分析：

### 1. 单次回答分析

不需要大量用户数据。

依赖的是：

```text
知识点内容
用户本次回答
知识点关键要点
AI 分析规则
```

这个阶段现在就能做。

---

### 2. 个人学习趋势分析

不需要大量平台用户，但需要同一个用户自己的历史数据。

依赖的是：

```text
最近学习记录
主动回忆提交次数
AI 分析评分变化
待巩固项变化
复习完成率
重复出现的薄弱点
```

这个需要用户持续使用一段时间后才能更准确。

---

### 3. 群体级智能优化

这个需要大量用户数据。

例如：

```text
基于大量用户优化学习路径
预测某类知识点常见错误
优化复习算法
做人群画像
优化会员转化
```

这不是第一版重点。

第一版应该聚焦：

```text
基于用户自己的知识内容、主动回忆回答、AI 分析结果和复习表现，逐步形成个人学习画像。
```

---

## 六、用户学习画像设计

知习后期所谓“个人 Agent 成长”，不应该理解为模型自己训练升级，而应该理解为系统持续积累用户学习画像。

可以记录：

```text
用户常见薄弱类型
用户常错知识点
用户复习完成率
用户主动回忆平均得分
用户偏好的解释方式
用户经常缺失的回答类型
用户最近学习强度
用户重复出现的错误模式
```

这些数据可以组成：

```text
UserLearningProfile
```

有了这个画像后，系统可以逐步做到：

```text
分析时更关注用户常犯错误
复习时优先安排重复薄弱点
生成解释时适配用户偏好
学习报告更贴近用户真实表现
```

这就是“学习 Agent 越来越懂用户”的基础。

---

## 七、Agent 设计原则

知习后期可以做 Learning Agent，但应该是受控 Agent，不是完全自治 Agent。

推荐定义：

```text
Learning Agent
= 业务工作流
+ 用户学习画像
+ 长期学习记忆
+ 工具调用能力
+ 结构化输出
+ 权限控制
+ 成本控制
+ 审计日志
```

Agent 可以做：

```text
分析用户回答
发现薄弱点
生成待巩固项
安排复习建议
追踪重复错误
生成阶段性学习报告
```

Agent 不应该随意做：

```text
自动删除用户知识库
自动修改订阅
自动退款
自动封号
自动无限调用 AI
自动访问其他用户数据
```

所有关键操作都必须有权限控制、日志记录和后台审计。

---

## 八、推荐演进路线

### V0：固定业务工作流

先不做 Agent。

只打通最核心的一条链路：

```text
用户提交主动回忆回答
→ AI 分析理解程度
→ 生成待巩固项
→ 生成复习建议
→ 记录 token 和费用
→ 前端展示结果
```

---

### V1：用户学习画像

开始记录用户长期学习表现。

```text
薄弱点类型
复习完成率
主动回忆得分
重复错误
知识点掌握变化
```

这时系统开始具备“越来越懂用户”的基础。

---

### V2：逻辑 Learning Agent

在统一工作流引擎上加载用户画像和历史记忆。

```text
统一 Workflow Engine
+ 用户学习画像
+ 用户历史学习记录
+ 用户薄弱点
= 用户专属学习 Agent 体验
```

对用户来说，它像一个个人学习 Agent。

但技术上不是每人一个独立进程，而是共享引擎 + 用户级记忆。

---

### V3：受控技能成长

后期可以引入类似 Agent Skill 的能力。

但不要让 Agent 自由生成并上线技能，而应该：

```text
系统生成候选 Skill
→ 后台审核
→ 灰度发布
→ 监控效果
→ 正式启用
```

这样既能成长，又能保持产品稳定和安全。

---

## 九、后端概念设计

后端可以逐步抽象出三个核心概念：

```text
Workflow：业务工作流
AgentProfile：用户学习画像
Skill：可复用分析策略
```

可以预留的数据结构方向：

```text
ai_workflows
- id
- key
- name
- businessType
- version
- status

ai_workflow_steps
- id
- workflowId
- stepKey
- modelTier
- promptKey
- order
- inputSchema
- outputSchema

user_learning_profiles
- userId
- weakTypes
- preferredExplanationStyle
- recallAccuracyAvg
- reviewCompletionRate
- repeatedMistakes
- updatedAt

ai_skills
- id
- key
- description
- workflowKey
- version
- isActive
- source
- createdAt
```

第一版不一定全部建表，但设计上要预留这些方向。

---

## 十、当前最应该落地的第一版

当前不应该一上来做完整 Agent 系统。

第一版最适合落地的是：

```text
主动回忆分析 Workflow V1
+ AI Usage Logs
+ Prompt Version
+ Structured JSON Result
+ User Learning Profile V1
```

具体流程：

```text
1. 用户提交主动回忆回答
2. 后端保存原始回答
3. 规则检查回答是否为空、过短、重复
4. 便宜模型或规则提取回答覆盖点
5. 主力模型分析薄弱点和理解程度
6. 返回结构化 JSON
7. 生成待巩固项
8. 生成复习建议
9. 记录模型、token、费用、耗时、promptVersion
10. 更新用户学习画像
11. 前端展示 AI 分析结果
```

这条链路跑通后，知习就不再是一个 AI 聊天壳，而是开始具备真正的主动学习系统能力。

---

## 一句话总结

```text
知习的 AI 设计应该从“业务分级工作流”开始，而不是一开始做完全自治 Agent；后期通过用户学习画像、长期记忆和受控 Skill 系统，逐步演进成每个用户感知上的专属学习 Agent。
```

这个方向也符合当前项目阶段：现在最重要的是先把 iOS App 和后端真实打通，并围绕最小学习闭环逐步接入真实 AI 分析能力。