ios-projects/docs/system-map/capabilities/05-AI对话与知识库问答.md

05 AI 对话与知识库问答 — 跨项目完整能力分析

项目角色分类：主链路（iOS、主 API、DeepSeek 模型服务）、上游支撑（Python RAG Worker，仅为知识库内容供给，不参与对话上下文加载）、运维可观测（Admin）。 Qdrant 不参与对话上下文加载——所有 5 种 Scope 的上下文均来自 PostgreSQL KnowledgeItem 表。 Heavy Runtime 不直接参与基础 AI 对话——它负责异步 AI 分析任务（学习状态分析、测验生成等），对话链路走 AiGateway 直达模型。 Rust Document Runtime 不参与 AI 对话链路。

---

1. 能力目标

用户可以通过自然语言与 AI 进行学习相关的对话。对话可以限定在特定知识库、资料或知识点的范围内，AI 基于范围内知识内容回答问题，并提供来源引用。支持流式回复、思考过程展示和多会话管理。

---

2. C 端入口

入口页面	对话范围	触发方式
AI 反馈页	全局	"深入提问"按钮
知识库详情页	知识库	底部 AI 对话按钮
资料阅读页	资料	工具栏 AI 按钮
知识点详情页	知识点	工具栏菜单（如有）
AI 反馈页 → AIChatPage	全局	"深入提问" → AIChatPage
（废弃）AI 首页	全局	底部输入栏（页面无入口）

---

3. 对话范围

3.1 全局对话（scopeType: global）

• 上下文来源： 无知识库上下文。AI 仅基于通用知识回答。
• RAG 查询范围： 不进行任何检索。
• 会话识别： 创建 session 时 scopeType=global 且 scopeId 为空。
• 切换处理： 用户从范围对话点击"新建对话"可创建全局对话。

3.2 知识库范围（scopeType: knowledge_base）

• 上下文来源： 从 KnowledgeItem 表查询该知识库下的知识点（最多 30 条，每条截取前 500 字符，总计最多 4000 字符）。
• RAG 查询范围： 上下文直接从 PostgreSQL 的 KnowledgeItem 表加载。所有 5 种 Scope 均不调用 Qdrant——loadContextByScope 在代码中完全不涉及向量搜索。
• 会话识别： 创建 session 时 scopeType=knowledge_base，scopeId=。相同知识库范围的会话通过 "open-or-create" 模式复用（同一用户同一知识库只有一个活跃对话会话）。
• 切换处理： 用户切换到另一个知识库的对话时，创建新会话或恢复已有会话。

3.3 资料范围（scopeType: material）

• 上下文来源： 按 sourceRef 匹配该资料关联的知识点。与知识库范围相同，上下文直接从 PostgreSQL 的 KnowledgeItem 表加载。Qdrant 不参与对话上下文加载。
• 会话识别： session 的 scopeType=material，scopeId=。
• 切换处理： 用户离开资料阅读页后，对话会话保留。下次进入同一资料时恢复。

3.4 知识点范围（scopeType: knowledge_item）

• 上下文来源： 单个知识点的完整内容。
• RAG 查询范围： 单个知识点本身，无需检索。
• 会话识别： session 的 scopeType=knowledge_item，scopeId=。
• 切换处理： 每个知识点有独立会话。

3.5 范围切换机制

• 用户在不同入口进入 AI 对话时，系统根据当前上下文自动确定对话范围。
• 每个范围维护独立的 ChatSession。
• 会话列表 Sheet 可按范围过滤显示。
• ScopeSnapshot 保存在每条消息中，确保历史消息知道其产生时的范围上下文。

---

4. 用户主流程

用户进入对话（从知识库详情页/资料阅读页/AI 反馈页等入口）
→ iOS 调用 API 创建或恢复会话（open-or-create，相同范围复用会话）
→ 用户输入消息
→ iOS 调用流式发送 API（POST /rag-chat/sessions/:id/stream）
→ API 校验会话所有权
→ API 内容安全检查（敏感词匹配）
→ API 保存用户消息（含 scopeSnapshot）
→ API 自动生成会话标题（首次消息时，截取前 40 字符）
→ API 根据 scopeType 加载上下文：
    - global：空上下文
    - knowledge_base：从 KnowledgeItem 表查询最多 30 条（每条约 500 字符）
    - material/folder：按相应过滤条件查询
    - knowledge_item：查询单个知识点
→ API 将上下文注入系统提示模板
→ API 调用 AiGateway → 路由到 DeepSeek Provider → deepseek-v4-pro
→ DeepSeek 流式返回（content 块 + thinking 块）
→ API 通过 SSE 逐块转发给 iOS
→ iOS 实时展示 AI 回复（含思考过程可折叠动画）
→ 流式完成后 API 保存 AI 消息（含 token 计数）
→ API 保存引用（前 5 个上下文项作为 ChatCitation）
→ iOS 展示引用信息
→ 用户可复制回复、重新生成、或发送新消息

---

5. 项目职责

iOS — 主链路参与者

• AI 对话界面（消息气泡、思考过程展示、引用展示）
• 流式接收与实时渲染（SSE 解析）
• 输入栏（文字输入、语音图标占位、发送按钮）
• 会话列表 Sheet（搜索、切换、删除、归档、置顶）
• 新建对话
• 范围标签展示（当前对话限定范围）
• 复制回复、重新生成

主 API — 主链路参与者

• 会话 CRUD（open-or-create、列表、更新、软删除）
• 会话所有权校验
• 消息发送（同步 + 流式）
• 内容安全检查（输入消息和 AI 输出）
• 上下文加载（按 scopeType 从 KnowledgeItem 表查询）
• 系统提示构建（上下文注入）
• AiGateway 路由（模型选择、回退、重试）
• SSE 流式转发
• 引用保存（ChatCitation）
• Token 使用记录（ModelInvocationLog）
• 自动标题生成

DeepSeek 模型服务 — 主链路参与者

• 接收系统提示 + 用户消息 + 上下文
• 流式生成回复（content + reasoning_content）
• 模型：deepseek-v4-pro（primary tier），deepseek-v4-flash（cheap tier）
• 通过 AiGateway 统一管理 API 密钥和路由

Python RAG Worker — 上游支撑（间接参与）

• 不直接参与对话流程。负责文档导入后的处理（解析→分块→嵌入→索引），为知识库提供结构化的知识点内容。
• RAG 处理结果（KnowledgeItem、KnowledgeChunk）是对话上下文的间接来源——KnowledgeItem 表中的内容可能来自 RAG 生成的候选知识点。
• 注意：知识库范围对话的上下文来自 KnowledgeItem 表（PostgreSQL），不依赖 Qdrant 向量搜索，也不依赖 RAG 的实时处理状态。

Qdrant — 不参与对话上下文加载

• 存储文档块的向量索引，用于文档导入后的语义检索（Admin RAG 调试页使用）。
• 不参与 AI 对话的上下文加载——loadContextByScope 完全不调用 Qdrant，所有 5 种 Scope 的上下文均来自 PostgreSQL。

Admin — 运维与可观测

• 会话日志查看（Admin 聊天日志页，查看所有会话和消息）
• AI 网关管理（路由规则、提供商管理、回退日志）
• AI 使用统计（调用次数、延迟、失败率、成本，按提供商和模型）
• AI 成本管理（费用记录、按用户统计、导出）
• 模型配置（temperature、max_tokens 等参数）
• 内容安全审核（敏感词库、审核记录、举报管理、违规处罚）

Heavy Runtime — 不直接参与

Heavy Runtime 负责异步 AI 分析任务（学习状态分析、薄弱点识别、测验生成、闪卡生成），通过独立的作业排队机制运作。基础 AI 对话不经过 Heavy Runtime，而是通过 AiGateway 直接调用 DeepSeek。

---

6. 会话管理

6.1 创建

• 方式： open-or-create 模式。用户从入口进入对话时，iOS 调用 POST /rag-chat/sessions。
• 复用逻辑： 相同 scopeType + scopeId + userId 下存在未归档未删除的会话时，返回已有会话（HTTP 200）。否则创建新会话（HTTP 201）。
• 这意味着： 每个用户在每个知识库范围内只有一个活跃对话会话。

6.2 切换

• 方式： 用户在会话列表 Sheet 中点击历史会话 → iOS 调用 API 加载该会话的消息历史。
• 效果： 当前对话界面切换到所选会话，范围标签更新。

6.3 搜索

• 方式： 在会话列表 Sheet 中输入搜索词 → 本地过滤或 API 搜索。
• 范围： 当前范围内的会话。

6.4 归档

• 方式： 会话列表 Sheet 中滑动 → "归档"。
• 效果： API 更新会话 isArchived=true。已归档会话不在默认列表中显示。
• 恢复： 可通过更新 isArchived=false 取消归档。

6.5 删除

• 方式： 会话列表 Sheet 中滑动 → "删除"。
• 效果： API 软删除会话（isDeleted=true）。消息保留在数据库中但不再对用户可见。

6.6 置顶

• 方式： 会话列表 Sheet 中左滑 → "置顶"/"取消置顶"。
• 效果： API 更新会话 isPinned 状态。置顶会话排在最前。

6.7 Scope（对话范围）

• 每个会话有 scopeType 和 scopeId，确定上下文来源。
• 新建对话时，如果用户从范围入口（知识库/资料）进入，新会话继承该范围。
• 用户也可以在对话中切换到全局模式创建新会话。

6.8 Scope Snapshot（范围快照）

• 每条消息保存一个 scopeSnapshot 对象：{ scopeType, scopeId, parentKnowledgeBaseId }。
• 作用：将消息冻结到发送时的范围上下文。即使后续范围发生变化，历史消息仍知道自己引用了哪个范围的上下文。

6.9 引用（Citation）

• AI 回复后，系统从上下文项中提取前 5 个创建 ChatCitation。
• 每个引用包含：chunkId（知识点 ID）、sourceTitle（标题）、excerptText（内容前 500 字符）。
• iOS 在消息气泡中展示引用信息。

6.10 历史消息

• iOS 进入会话时调用 GET /rag-chat/sessions/:id/messages 加载历史。
• 消息按时间排序，含角色（user/assistant）、内容、token 数和引用。

---

7. 核心业务数据

7.1 对话会话（ChatSession）

• 谁创建： API 在 iOS 调用 open-or-create 时创建（或返回已有）。
• 谁更新： API 在每次消息发送时更新 lastMessageAt；iOS 操作更新 isPinned/isArchived/isDeleted/title/modelMode/modelId。
• 谁查询： iOS 获取会话列表和消息历史；Admin 在聊天日志页查看。
• 用途： 对话的组织单元，承载范围信息和消息列表。

7.2 对话范围（ChatScope）

• 概念性对象（非独立数据库表），由 ChatSession 的 scopeType + scopeId 定义。
• 取值： global、knowledge_base、folder、material、knowledge_item。
• 用途： 确定上下文加载策略和会话唯一性。

7.3 消息（ChatMessage）

• 谁创建： API 在发送流程中创建用户消息和 AI 消息。
• 谁更新： 创建后不可修改。
• 谁查询： iOS 加载会话消息历史；Admin 在聊天日志详情中查看。
• 用途： 对话的完整记录，含角色、内容、token 数、scopeSnapshot。

7.4 引用（ChatCitation）

• 谁创建： API 在 AI 回复保存后自动创建（从前 5 个上下文项提取）。
• 谁更新： 创建后不可修改。
• 谁查询： iOS 在消息详情中展示；消息列表查询时惰性加载。
• 用途： 为 AI 回复提供可追溯的来源引用。

7.5 范围快照（ScopeSnapshot）

• 概念性对象（嵌入在 ChatMessage 中），包含 { scopeType, scopeId, parentKnowledgeBaseId }。
• 用途： 冻结每条消息产生时的对话范围。

7.6 知识分块（KnowledgeChunk）

• 谁创建： Python RAG Worker 在文档处理时创建。
• 谁更新： 不更新（软删除通过 Qdrant 实现）。
• 谁查询： Admin 在分块管理页查看；Qdrant 向量搜索（当前仅 Admin RAG 调试页使用，不用于对话上下文加载）。
• 用途： 文档的语义检索向量索引。当前不参与 AI 对话上下文构建。

7.7 模型配置（Model Configuration）

• 谁管理： Admin 通过 AI 网关管理页配置路由规则和提供商。
• 谁使用： AiGateway 在每次对话请求时根据 tier（primary/cheap/strong）和 taskType 选择模型。
• 当前配置： primary tier → deepseek-v4-pro；cheap tier → deepseek-v4-flash。

---

8. 异常与降级

8.1 RAG 尚未处理完成

• 场景： 资料已上传但 Python RAG Worker 尚未完成向量索引。
• 影响： 知识库范围对话的上下文来自 KnowledgeItem 表——不受 RAG 处理状态影响。所有 Scope 的上下文加载均不依赖 Qdrant，RAG 未完成不影响对话功能。

8.2 检索无结果

• 场景： 知识库为空或范围内无匹配知识点。
• API 处理： loadContextByScope 返回 isEmpty=true。系统提示注入"当前知识库中暂无相关内容"。
• 模型行为： AI 基于通用知识回答，可能告知用户知识库内容不足。

8.3 模型调用失败

• 场景： DeepSeek API 返回错误（超时、限流、服务异常）。
• API 处理： AiGateway 自动回退（fallback 到同 tier 的备用模型/提供商），最多重试 3 次。
• 用户感知： 如果所有重试均失败，返回错误提示。Admin 可在回退日志中查看详情。

8.4 流式响应中断

• 场景： SSE 连接在网络问题或客户端断开时中断。
• API 处理： 检测 res.destroyed，优雅停止流式输出。已生成的部分内容可能不保存为完整消息（取决于中断时机）。
• iOS 处理： 显示连接中断提示。用户可重新发送消息。

8.5 用户取消生成

• 场景： 用户在 AI 生成过程中取消（iOS 断开 SSE 连接或发送取消请求）。
• API 处理： 检测连接断开，停止流式输出。
• 影响： 部分生成的内容不保存。用户可重新发送。

8.6 会话被删除

• 场景： 用户或 Admin 删除会话。
• API 处理： 软删除（isDeleted=true）。消息保留但不可见。
• 用户感知： 会话从列表中消失。已删除会话不可恢复（当前无回收站功能）。

8.7 资料被删除

• 场景： 对话引用的知识库/资料/知识点被删除。
• API 处理： 上下文加载时自动过滤已删除项。历史消息的 scopeSnapshot 仍保留原范围信息，但该范围可能不再可访问。
• 用户感知： 新对话中该范围无上下文可用。历史消息仍可查看但引用可能失效。

8.8 无权限

• 场景： 用户尝试访问其他用户的会话。
• API 处理： 会话所有权校验失败，返回 403/404。
• 用户感知： 无法查看或操作非自己的会话。

8.9 Token 超限

• 场景： 上下文 + 对话历史超过模型上下文窗口。
• API 处理： 上下文加载有 4000 字符硬限制。长对话历史可能需要截断（具体策略待确认）。
• 用户感知： 较早的对话内容可能不被模型考虑。

8.10 模型 API Key 无效

• 场景： 平台 DeepSeek API Key 过期或余额不足。
• API 处理： AiGateway 调用失败。如果用户配置了自己的 API Key，可回退到用户 Key。
• Admin 处理： Admin 在密钥管理页更新或轮换 Key。
• 用户感知： 对话报错。用户可在 AI 设置中提供自己的 DeepSeek Key。

8.11 DeepSeek 服务不可用

• 场景： DeepSeek API 全面不可用。
• API 处理： AiGateway 尝试所有提供商后失败。
• 用户感知： 对话完全不可用，显示服务异常提示。
• Admin 处理： Admin 在 AI 网关管理页监控提供商状态，配置备用提供商。

---

9. 查询与管理入口

用户查询

• 会话列表： iOS 对话页工具栏 → 会话列表 Sheet（搜索、筛选）。
• 消息历史： iOS 对话页加载历史消息。
• 引用信息： iOS 消息气泡中展示。
• AI 使用统计： iOS 端当前未展示（无用户可见的 token 用量或成本页面）。

Admin 查询

• 会话日志： Admin 聊天日志页 → 查看所有会话（含用户 ID、知识库 ID、消息数）。
• 消息详情： Admin 聊天日志页 → 点击会话查看全部消息（角色、内容预览、token 数、时间）。
• AI 网关管理： Admin AI 网关页（路由规则 CRUD、提供商启用/禁用、回退日志）。
• AI 使用统计： Admin 指标页（按提供商/模型的调用次数、延迟、失败率、成本）。
• AI 成本管理： Admin 计费页（费用记录 CRUD、按用户统计、导出 CSV）。
• 内容安全审核： Admin 内容安全页（敏感词库、审核记录、举报管理、违规处罚）。

系统内部查询与管理

• AiGateway 路由： 每次对话请求时自动查询路由规则和提供商配置。
• Token 使用记录： AiGateway 自动记录每次调用的 inputTokens/outputTokens/延迟/成本到 ModelInvocationLog。
• 每日使用聚合： 系统自动聚合用户和平台的每日 AI 使用量（UserAiUsageDaily、PlatformAiBudgetDaily）。
• 配额检查： 发送消息前检查用户每日配额和平台预算。

---

10. 当前完成状态

组件	状态	说明
iOS 流式对话界面	已完成	SSE 解析 + 思考过程展示 + 引用展示
iOS 消息气泡渲染	已完成	用户消息紫色渐变 + AI 消息含思考折叠
iOS 复制/重新生成	已完成	复制到剪贴板 + 重新发送
iOS 会话列表 Sheet	已完成	搜索、切换、删除、归档、置顶
iOS 新建对话	已完成	强制创建新会话
iOS 范围标签展示	已完成	对话顶部显示当前范围
iOS 全局对话	已完成	无上下文对话
iOS 知识库范围对话	已完成	从知识库详情页底部按钮进入
iOS 资料范围对话	已完成	从资料阅读页工具栏 AI 按钮进入
iOS 知识点范围对话	暂未确认	API scopeType=knowledge_item 已定义；iOS 知识点详情页工具栏菜单未发现直接 AI 对话入口，可能需从知识点详情页手动跳转
API open-or-create 会话	已完成	相同范围复用已有会话
API 内容安全检查	已完成	输入消息 + AI 输出敏感词匹配
API 上下文加载（KnowledgeItem 表）	已完成	按 scopeType 查询最多 30 条
API 系统提示构建	已完成	上下文注入到提示模板
API AiGateway 路由	已完成	tier 路由 + 回退 + 重试
API SSE 流式转发	已完成	Content-Type: text/event-stream
API 引用保存	已完成	前 5 个上下文项 → ChatCitation
API 自动标题生成	已完成	首次消息截取前 40 字符
API Token 使用记录	已完成	ModelInvocationLog
DeepSeek 模型调用	已完成	deepseek-v4-pro（primary）、deepseek-v4-flash（cheap）
Qdrant 参与对话上下文加载	未完成	loadContextByScope 完全不调用 Qdrant；所有 5 种 Scope 上下文均来自 PostgreSQL KnowledgeItem 表
联网搜索	暂未确认	未发现联网搜索功能实现
深度思考	已完成	DeepSeek reasoning_content → SSE thinking 块 → iOS 思考过程展示
文件附件	暂未确认	未发现对话中上传文件功能
导图	暂未确认	未发现 AI 生成导图功能
分享	暂未确认	未发现对话分享功能
生成笔记	暂未确认	未发现从对话生成笔记功能
Admin 会话日志查看	已完成	聊天日志页
Admin AI 网关管理	已完成	路由规则 + 提供商 + 回退日志
Admin AI 使用统计	已完成	按提供商/模型的调用统计
Admin AI 成本管理	已完成	费用记录 + 按用户统计 + 导出
Admin 内容安全审核	已完成	敏感词库 + 审核记录 + 举报 + 违规
用户 AI 用量展示	未完成	iOS 端无 token 用量或配额展示
用户自定义 API Key	已完成	iOS 设置页 → AI 设置 → 输入自己的 DeepSeek Key
平台预算回退	已完成	平台预算不足时自动回退到用户 Key