# AI 搭子对接 Dify 知识库 - V2 完整架构设计
> ⚠️ **本文档状态（2026-06-29 重建）**：
> - V2 是"100 明星 + 多 AI 平台"的**完整架构设计**
> - **MVP 阶段不实施**——MVP 阶段只做 1 个明星（肖战）+ 1 个 Dify Workflow
> - **MVP 实施级方案**：[2026-06-29-ai-chat-dify-mvp-design.md](2026-06-29-ai-chat-dify-mvp-design.md)（**先读这个**）
> - V2 文档保留作为 Stage 2+ 的**演进路线图**和**详细代码参考**
> ★ **MVP 优先原则**：MVP 阶段不实施本文档中"为未来 100 明星 + 多 AI 平台"准备的设计。请先按 MVP 实施（约 1 周），跑通后再按本文档的 §10 演进。
---
## 〇、文档说明
- **V2 适用范围**：所有 star_id，所有 AI 平台对接（Dify 先行）
- **V2 工作量**：约 4-5 周（含 Dify 端 + 后端 + 测试）—— **不要分配实施时间，按业务节奏推进**
- **目标状态**：长期可维护、可扩展（30+ 明星 + 多 AI 平台）
- **V1 → V2 演进**：V1 评审发现"一星一 App / API Key 散落 / Prompt 边界混乱 / 上下文重复 / 会话仅 Redis / Fallback 副作用 / 抽象太浅 / if-else 工厂" 8 大问题，V2 全部解决（详见 §1.2 和 §14）
### 〇.1 方案概述（★ 必读）
#### 〇.1.1 我们要解决的问题
**业务问题**：追星 App 用户与"角角"AI 搭子聊天时，AI 没有**专属知识库**，无法针对所追明星（默认肖战）给出有针对性的回答。
**技术问题**（4 大类）：
1. **缺乏 RAG 能力**：现有 AI 只能用通用 LLM 知识，无明星专属数据
2. **会话无持久化**：当前仅 Redis 缓存 24h，用户次日回来会失忆
3. **AI 平台耦合**：未来要接 Coze/FastGPT/OpenAI 等
4. **运营成本失控**：扩到 100 明星时，配置/版本/审计会爆炸
#### 〇.1.2 整体实现路径
```
数据迁移 Dify 端准备 后端代码 联调测试
├ 建 2 张表 ├ 准备知识库 ├ model ├ 内部账号测试
├ ├ 创 Workflow ├ repository ├ WebSocket 联调
└ └ 不需要 Code 节点 └ service └ 错误注入
└ provider
└ main.go 装配
```
**不要分配实施时间**——按业务节奏推进。
#### 〇.1.3 关键决策
| 决策项 | V2 选择 | 理由 |
|--------|---------|------|
| Dify 架构 | **Workflow**（不是 Chat App） | Workflow 支持 Knowledge Retrieval Node 动态选 dataset_id |
| 多星隔离 | Backend 维护 `star_id → dataset_id` 映射 | Dify 端 Workflow 内部用变量查 |
| API Key | **全局 1 个** | App 重建/删除不影响 Backend |
| Prompt 责任 | **Dify 路径：Dify 负责；MiniMax 路径：Backend 拼 system prompt** | Dify 端用 Workflow 模板组装；MiniMax 端无 Dify 替代 |
| 会话存储 | PostgreSQL 主，Redis 1h 缓存 | 永久保留，跨设备同步 |
| Backend context 维护 | **删除** SaveContext 给 LLM 用 | Dify 内部管 LLM 上下文 |
| Fallback 策略 | **仅无 conversation 时**允许 | 已开 conversation 失败则报错，不切 LLM |
| Provider 抽象 | `AIProvider` 复合接口 | LLM + RAG + Conversation 一起实现 |
#### 〇.1.4 核心架构图（TL;DR）
```
Mobile App
│ WebSocket
▼
Gateway (不感知 Provider)
│ Dubbo Triple
▼
AIChatService
│
├─ ChatEngine (核心编排)
│ ├─ AuditService (前置 + 后置 + 滑动窗口)
│ ├─ MemoryStore (长期记忆)
│ ├─ RedisLock (防并发 race)
│ └─ ProviderFactory (按 star_id 选 Provider)
│
├─ DifyProvider (协调整合)
│ ├─ DatasetResolver (star_id → dataset_id)
│ ├─ WorkflowClient (Dify HTTP + SSE)
│ ├─ HistoryClient (Dify /v1/messages)
│ └─ ConversationStore (缓存 + 持久化)
│
└─ MiniMaxProvider (直接 LLM + 本地 Conversation)
外部：Dify Workflow (开始 → 知识检索 → LLM → 内容审核 → 结束)
dataset_id 由 Backend 传入，Workflow 不再维护 mapping
```
#### 〇.1.5 演进路径（参见 [MVP §10](2026-06-29-ai-chat-dify-mvp-design.md#十stage-2-演进路径)）
> ★ **Stage 2+ 必踩的 3 个坑**（P0 修复）和 **3 个架构评审笔记**已迁移到 MVP §10。
> 实施 V2 任何章节前，**先读 MVP §10** 的"演进时必踩的坑"。
---
## 一、背景与目标
### 1.1 现状
| 维度 | 现状 |
|------|------|
| AI 角色 | 所有人共用"角角"默认人设，与"星"无关 |
| LLM | MiniMax `M2-her`（[llm_service.go](backend/services/aiChatService/service/llm_service.go)） |
| star_id 传递 | JWT → middleware → Dubbo Attachments → AIChat 解析，链路完整 |
| 知识维度 | **缺失**。当前 AI 无法获取所追明星的事实性资料 |
| Dify 现状 | Gateway 侧 [dify_client.go](backend/gateway/service/dify_client.go) 已存在，但仅服务"镭射卡"链路 |
| 会话存储 | Redis context，24h TTL（**无持久化**） |
### 1.2 V1 方案已识别的设计缺陷（架构评审结论）
> V1 评审打分：工程完整度 9/10，可维护性 6.5/10，长期扩展性 5.5/10，与 Dify 结合方式 6/10
| 缺陷 | V1 做法 | 后果 |
|------|---------|------|
| **一星一 App** | 每个明星独立 Chat App + Dataset + API Key | 100 星 = 100 个 App，运营改 prompt 要改 100 次 |
| **API Key 数量爆炸** | `star_app_mapping: {87: app-xxx, 88: app-yyy}` | Key 跟业务身份绑定，App 重建/删除会全失效 |
| **Prompt 边界混乱** | Dify system prompt + Backend persona 双写 | 两边都在管"人设"，冲突不可避免 |
| **上下文重复维护** | Dify Conversation + Backend Redis Context 双份 | 必然漂移 |
| **会话仅在 Redis** | conversation_id 24h TTL | 用户次日重连会失忆 |
| **Fallback 有副作用** | 失败即切 MiniMax | 中途切会丢上下文 |
| **Provider 抽象太浅** | 只抽 LLMProvider | 接 Coze/FastGPT 时发现 Knowledge/Conversation 硬编码了 Dify |
| **if-else 工厂** | Provider 内部 `if useDify { ... } else { ... }` | 扩展性差 |
### 1.3 V2 目标
1. ✅ **运营成本 O(1)**：改 prompt 只改 1 处
2. ✅ **会话永久保留**：用户 1 周后重连，能继续上次对话
3. ✅ **职责清晰**：Dify 路径 Backend 不参与 prompt 组装
4. ✅ **可扩展**：未来接 Coze/FastGPT，只需实现 `AIProvider` 接口
5. ✅ **风险可控**：渐进式上线，配置回滚
### 1.4 V2 关键决策
| 决策项 | V2 选择 | 理由 |
|--------|---------|------|
| Dify 架构 | **Workflow**（不是 Chat App） | Workflow 支持 Knowledge Retrieval Node 动态选 dataset_id |
| 多星隔离 | Backend 维护 `star_id → dataset_id` 映射 | Dify 端 Workflow 内部用变量查 |
| API Key | **全局 1 个** | App 重建/删除不影响 Backend |
| Prompt 责任 | **Dify 路径：Dify 负责；MiniMax 路径：Backend 拼 system prompt** | Dify 端用 Workflow 模板组装；MiniMax 端无 Dify 替代，Backend 沿用 [prompt_builder.go](backend/services/aiChatService/service/prompt_builder.go) |
| 会话存储 | PostgreSQL 主，Redis 1h 缓存 | 永久保留，跨设备同步 |
| Backend context 维护 | **删除** SaveContext 给 LLM 用 | Dify 内部管 LLM 上下文 |
| Fallback 策略 | **仅无 conversation 时**允许 | 已开 conversation 失败则报错，不切 LLM |
| Provider 抽象 | `AIProvider` 复合接口 | LLM + RAG + Conversation 一起实现 |
---
## 二、整体架构
### 2.1 V2 分层架构
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Mobile App (UniApp) │
│ WebSocket /ai-chat?token=Bearer_xxx │
│ 协议：保持不变（仅服务端内部切换 Provider） │
└─────────────────────────────────┬───────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Gateway (:8080) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ AIChatWebSocketHandler (Hub) │ │
│ │ 透传到 AIChatService，不感知 AI Provider │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ Dubbo Triple │
└──────────────────────────────┼──────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ AIChatService (:20008) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Chat Engine (核心编排) │ │
│ │ 职责： │ │
│ │ - 鉴权 / 审计 / 限流（横切关注点） │ │
│ │ - 选 AIProvider（按 star_id） │ │
│ │ - 调 MemoryStore 召回长期记忆 │ │
│ │ - 调 AIProvider.GetConversation / StreamChat │ │
│ │ - 流式审核 + 推 WebSocket │ │
│ │ - 调 AIProvider.AppendMessage 保存 │ │
│ │ - 调 AIProvider.UpdateExternalID 持久化 Dify conv_id │ │
│ │ - 调 GetWelcomeMessage（InitSession） │ │
│ │ - 调 MemoryStore.ExtractMemory（每 N 轮） │ │
│ │ Chat Engine 不知道 Dify / MiniMax 是什么，只跟 AIProvider 打交道 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ AIProvider (复合接口) │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ │ DifyProvider │ │ MiniMaxProvider │ │ CozeProvider │ │ │
│ │ │ (当前实现) │ │ (当前实现) │ │ (未来) │ │ │
│ │ │ LLM ✓ │ │ LLM ✓ │ │ LLM ✓ │ │ │
│ │ │ RAG ✓ (Dify 知识)│ │ RAG ✗ (无) │ │ RAG ✓ (Coze KB) │ │ │
│ │ │ Conversation ✓ │ │ Conversation ✓ │ │ Conversation ✓ │ │ │
│ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────┐
│ Dify Server │
│ POST /v1/workflows/run │
│ { │
│ inputs: { │
│ dataset_id, │
│ query, │
│ user_*, │
│ }, │
│ user, response_mode, │
│ conversation_id │
│ } │
│ │
│ Workflow 内部: │
│ 1. Knowledge Retrieval 节点 │
│ 2. LLM 节点 │
│ 3. 内容审核节点 │
│ 4. 输出 │
└──────────────────────────────┘
```
### 2.2 核心数据流（一次完整对话）
```
[Mobile]
│ WebSocket send {action: "send_message", session_id, message, persona_id}
│
▼
[Gateway Hub]
│ 鉴权 (JWT → user_id, star_id)
│
▼
[AIChatService Provider.SendMessage]
│
├─ 1. 前置审核 (AuditService.AuditText)
│
├─ 2. 选 AIProvider (ProviderFactory.Select(starID))
│ ├─ dify.star_dataset_mapping 命中 → DifyProvider
│ └─ 未命中 → MiniMaxProvider
│
├─ 3. 长期记忆召回 (MemoryStore.Recall)
│
├─ 4. 加分布式锁 (RedisLock.Acquire)
│ └─ conv_lock:{userId}:{starId} 30s TTL
│
├─ 5. 获取/创建会话
│ └─ DifyProvider.GetOrCreateConversation(key)
│ └─ ★ ConversationStore 内部封装
│
├─ 6. 构造请求 (ChatRequest)
│
├─ 7. 调 Provider.StreamChat
│ ├─ Dify 路径: DatasetResolver + WorkflowClient.StreamRun
│ └─ MiniMax 路径: 调 MiniMax API
│
├─ 8. 流式返回 + 逐 token 后置审核
│
├─ 9. 更新 Dify conv_id
│
├─ 10. 保存会话消息
│
└─ 11. 记忆提取 (每 5 轮)
```
### 2.3 Provider 决策点
```go
// ProviderFactory 单例，按 star_id 选 AIProvider
type ProviderFactory struct {
difyConfig model.DifyConfig
difyProvider AIProvider
miniMaxProvider AIProvider
}
func (f *ProviderFactory) Select(starID int64) AIProvider {
if !f.difyConfig.Enable {
return f.miniMaxProvider
}
if _, ok := f.difyConfig.StarDatasetMapping[starID]; ok {
return f.difyProvider
}
return f.miniMaxProvider
}
func (f *ProviderFactory) SelectFallback(currentName string) AIProvider {
if !f.difyConfig.FallbackToMiniMax {
return nil
}
if currentName == "dify" {
return f.miniMaxProvider
}
return nil
}
```
---
## 三、Dify 端准备工作
> **前置条件**：需要 1 名 Dify 管理员账号（产品/运营），负责 Datasets、Workflow 维护。
### 3.1 准备数据集（Datasets）
**为每个明星创建一个 Dataset**：
1. 登录 Dify → "知识库" → "创建知识库"
2. 命名规范：`star-{identity_id}-kb`（如 `star-xz-kb`、`star-wyb-kb`）
3. 选择索引模式：`high_quality`（embedding + 向量检索）
4. 导入资料（多种方式任选）：
- **文件上传**：PDF / Word / Markdown / CSV
- **Notion 同步**：绑定 Notion 数据库
- **Web 同步**：抓取官网、官方微博、官方粉丝站
- **API 同步**：Dify 提供 `/v1/datasets/{id}/document/create_by_file`
5. **配置分段**：
- 段落长度：500-1024 tokens
- 分段 overlap：50-100
6. **等待所有文档向量化完成**（Dify UI 每个文档显示 ✓ 后才继续）
**Dataset ID 记录**：每个 Dataset 创建后获得 UUID。
### 3.2 创建统一 Workflow
1. 进入"工作室" → "创建空白应用" → 类型选 **Workflow**
2. 命名：`star-chat-workflow`（全平台共用）
3. 配置"开始"节点的 Input 变量：
```yaml
inputs:
- name: dataset_id # string, ★ Backend 传入
type: text
- name: query # string, 用户原始消息
type: text
- name: user_nickname # string
type: text
- name: user_memory # string, optional
type: paragraph
- name: user_style # string, optional
type: text
- name: user_language # string, default "zh-CN"
type: text
```
4. 添加 **知识检索节点 (Knowledge Retrieval)**：
- Knowledge：选"运行时根据输入选择"
- 变量：`{{ dataset_id }}`
- Query：`{{ query }}`
- TopK：3
5. 添加 **LLM 节点**：
```markdown
你是一个专属 AI 搭子，名字叫"角角"。
【用户称呼】请称呼用户为"{{ user_nickname }}"
【说话风格】{{ user_style }}
【语言】{{ user_language }}
# 用户原始问题
{{ query }}
# 用户长期记忆
{{ user_memory }}
# 知识库检索结果
{{#knowledge_retrieval_node.result#}}
请基于以上信息回答用户问题。
```
6. 添加"内容审核"节点：
- 类型：Dify 原生"内容审核"节点
- 位置：LLM 节点 → 内容审核节点 → 结束节点
- 配置：
- moderation_type: `keywords`
- keywords: 敏感词列表（每行一个）
- on_failure: `replace_with_text` = "抱歉，这个话题我无法继续，我们换个话题聊聊吧。"
7. 添加"结束"节点
8. **调试**：传 `inputs={dataset_id, query, user_*}` 验证 RAG 召回
9. **发布** → 复制 API Key
### 3.3 单一数据源原则
> **★ 关键设计原则**：dataset_id 的"star → dataset"映射**只在 Backend 维护**（`ai_chat_configs.dify.star_dataset_mapping`），Workflow 不感知 star 概念。
```
[Backend DifyProvider] [Dify Workflow]
│ │
│ 1. SELECT dify.star_dataset_mapping │
│ WHERE star_id = 87 │
│ → dataset_id = "ds-xxxx" │
│ │
│ 2. POST /v1/workflows/run │
│ inputs: { │
│ dataset_id: "ds-xxxx", ←────────┼──→ 开始节点
│ query, user_* │
│ } │
```
**拒绝的做法**（V1 错误示例）：
```python
# ❌ Workflow 内部维护映射（数据冗余）
STAR_DATASET_MAP = {
"87": "ds-aaaa-xxxx",
"88": "ds-bbbb-yyyy",
}
```
**为什么错**：
- Backend 改 mapping → 忘改 Workflow → 用户问"肖战"答"王一博"的资料
- 运营修改 Dataset ID → 必须同步两个地方
**Workflow 内部节点串联**：
```
[开始] inputs:{dataset_id, query, user_*}
↓
[知识检索] dataset_id 直接使用
↓
[LLM] prompt 模板
↓
[内容审核]
↓
[结束]
```
### 3.4 关于"换星新建会话"
- `(user_id, star_id)` 是 ai_conversations 表的唯一键
- 用户从 star=87 切到 star=88：自动建新会话
- 用户从 star=88 切回 star=87：恢复原会话
- **这是预期行为**
### 3.5 知识库自动同步（未来项目）
> V2 不在 AIChat 范围，但留出接口。
- 独立 Worker 负责：拉取 RSS / 微博 / 公众号 / Notion；去重；调 Dify API
- AIChat 端不感知此 Worker 存在
---
## 四、配置与数据层
### 4.1 ai_chat_configs 新增数据
```sql
INSERT INTO ai_chat_configs (config_key, config_value, config_type, category, description, is_encrypted) VALUES
('dify.enable', 'false', 'boolean', 'dify', 'Dify 集成总开关', FALSE),
('dify.api_base', 'https://api.dify.ai/v1', 'string', 'dify', 'Dify API 基础 URL', FALSE),
('dify.workflow_url', '/workflows/run', 'string', 'dify', 'Workflow API 路径', FALSE),
('dify.star_dataset_mapping', '{"87":"ds-aaaa-xxxx"}', 'json', 'dify', 'star_id → Dataset ID 映射', FALSE),
('dify.api_key', 'app-xxxxxxxxxxxx', 'string', 'dify', 'Dify Workflow API Key', TRUE),
('dify.timeout_sec', '60', 'number', 'dify', 'Dify 单次请求超时(秒)', FALSE),
('dify.user_id_salt', 'topfans-default-salt-CHANGE-ME', 'string', 'dify', 'Dify user 字段哈希盐值', TRUE),
('dify.retry_count', '2', 'number', 'dify', 'Dify 单次失败重试次数', FALSE),
('dify.fallback_to_minimax', 'false', 'boolean', 'dify', 'Dify 失败后是否 fallback', FALSE);
```
### 4.2 PostgreSQL 新增表：ai_conversations
```sql
CREATE TABLE IF NOT EXISTS ai_conversations (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL,
star_id BIGINT NOT NULL,
provider_name VARCHAR(32) NOT NULL,
external_conversation_id VARCHAR(128),
message_count INT DEFAULT 0,
last_active_at BIGINT NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT,
created_at BIGINT NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT,
updated_at BIGINT NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT,
CONSTRAINT uk_ai_conv_user_star UNIQUE (user_id, star_id)
);
CREATE INDEX idx_ai_conversations_user_star ON ai_conversations(user_id, star_id);
CREATE INDEX idx_ai_conversations_last_active ON ai_conversations(last_active_at DESC);
COMMENT ON TABLE ai_conversations IS 'AI 会话元数据';
-- AI 消息表（仅 MiniMax 路径使用）
CREATE TABLE IF NOT EXISTS ai_messages (
id BIGSERIAL PRIMARY KEY,
conversation_id BIGINT NOT NULL REFERENCES ai_conversations(id) ON DELETE CASCADE,
role VARCHAR(16) NOT NULL,
content TEXT NOT NULL,
created_at BIGINT NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT
);
CREATE INDEX idx_ai_messages_conversation ON ai_messages(conversation_id, created_at);
COMMENT ON TABLE ai_messages IS 'AI 消息表';
```
### 4.3 Redis 角色
| Key 模式 | Value | TTL | 角色 |
|----------|-------|-----|------|
| `conv_meta:{userId}:{starId}` | JSON 会话元数据 | 1h | ai_conversations 读缓存 |
| `msg_cache:{conversation_id}` | JSON 消息列表 | 10min | GetHistory 响应缓存 |
| `ai_user_memories` 相关 | 不变 | 24h | 长期记忆召回缓存 |
| `conv_lock:{userId}:{starId}` | token | 30s | 分布式锁（★ P0-1） |
> **关键**：`conv_meta` 缓存**只是性能优化**。Redis flush 不影响数据完整性。
---
## 五、代码改造
### 5.1 改造总览
| 层级 | 改动 | 工作量 |
|------|------|--------|
| `service/ai_provider.go` | **新增**：`AIProvider` 复合接口 + 数据结构 | 中 |
| `service/dify_provider.go` | **新增**：`DifyProvider` | 中 |
| `service/dify_workflow_client.go` | **新增**：Dify HTTP + SSE | 中 |
| `service/dify_history_client.go` | **新增**：Dify /v1/messages | 中 |
| `service/dataset_resolver.go` | **新增**：star_id → dataset_id | 小 |
| `service/conversation_store.go` | **新增**：ConversationStore 接口 + CachedConversationStore | 中 |
| `service/minimax_provider.go` | **新增**：`MiniMaxProvider` | 中 |
| `service/chat_engine.go` | **新增**：核心编排 | 中 |
| `service/provider_factory.go` | **新建**：按 star_id 选 Provider | 中 |
| `service/redis_lock.go` | **新建**：RedisLock | 中 |
| `model/ai_chat_models.go` | **新增**：`DifyConfig` / `Conversation` / `AIMessage` | 小 |
| `repository/conversation_repository.go` | **新建**：ai_conversations GORM 仓储 | 中 |
| `repository/message_repository.go` | **新建**：ai_messages GORM 仓储 | 中 |
| `provider/ai_chat_provider.go` | **大幅简化**：只做参数解析 + 鉴权 + 调 ChatEngine | 小 |
| `main.go` | **改造**：装配 ProviderFactory + ChatEngine | 小 |
| `migrations/ai_conversations.sql` | **新增**：上述 DDL | 小 |
| **前端** | **无改动** ✅ | 0 |
**总工作量估计**：核心代码 ~1500-2000 行
### 5.2 AIProvider 复合接口定义
**新文件** `service/ai_provider.go`：
```go
package service
import (
"context"
"github.com/topfans/backend/services/aiChatService/model"
)
// AIProvider 复合 AI 后端能力
// 每个实现负责：LLM 调用 + RAG 检索 + 会话管理（Composite Pattern）
type AIProvider interface {
Name() string
// LLM 能力
StreamChat(ctx context.Context, req *ChatRequest) (StreamReader, error)
StreamChatWithBackup(ctx context.Context, req *ChatRequest) (StreamReader, error)
// RAG 能力
Retrieve(ctx context.Context, req *RetrieveRequest) (*RetrieveResult, error)
// Conversation 能力
GetOrCreateConversation(ctx context.Context, key ConversationKey) (*Conversation, error)
GetConversationMessages(ctx context.Context, conv *Conversation, limit int) ([]*ChatMessage, error)
AppendConversationMessages(ctx context.Context, conv *Conversation, msgs []*ChatMessage) error
UpdateConversationExternalID(ctx context.Context, conv *Conversation, externalID string) error
}
// 数据结构
type ChatRequest struct {
UserID int64
StarID int64
SessionID string
Message string
Conversation *Conversation
SystemInputs *SystemInputs
}
type SystemInputs struct {
UserMemory string
UserStyle string
UserNickname string
UserLanguage string
}
type ConversationKey struct {
UserID int64
StarID int64
}
type Conversation struct {
ID int64
UserID int64
StarID int64
ProviderName string
ExternalConvID string
MessageCount int
LastActiveAt int64
}
type ChatMessage struct {
Role string
Content string
}
type RetrieveRequest struct {
StarID int64
Query string
TopK int
DatasetID string
}
type RetrieveResult struct {
Documents []*Document
}
type Document struct {
ID string
Content string
Score float64
Metadata map[string]string
}
// MemoryStore 长期记忆接口
type MemoryItem struct {
ID uint
Content string
Keywords []string
Weight int
}
type MemoryStore interface {
Recall(ctx context.Context, userID int64, query string, limit int) ([]*MemoryItem, error)
Extract(ctx context.Context, userID int64, recentMessages []*ChatMessage) error
GetUserMemories(ctx context.Context, userID int64) ([]*MemoryItem, error)
}
// ConversationStore 抽象
type ConversationStore interface {
GetOrCreate(ctx context.Context, key ConversationKey, providerName string) (*Conversation, error)
GetMessages(ctx context.Context, conv *Conversation, limit int) ([]*ChatMessage, error)
AppendMessages(ctx context.Context, conv *Conversation, msgs []*ChatMessage) error
UpdateExternalID(ctx context.Context, conv *Conversation, externalID string) error
}
```
### 5.3 DifyProvider 实现
**新文件** `service/dify_provider.go`：
```go
package service
import (
"context"
"crypto/sha256"
"encoding/hex"
"fmt"
"time"
"github.com/topfans/backend/services/aiChatService/model"
)
// DifyProvider 通过 Dify Workflow 提供 AI 能力
// 复合实现：LLM（Workflow 内）+ RAG（Workflow 内）+ Conversation（Dify 管）
type DifyProvider struct {
workflowClient WorkflowClient
historyClient HistoryClient
convStore ConversationStore
datasetResolver DatasetResolver
userIDSalt string
sensitiveWords []string
}
func NewDifyProvider(
cfg model.DifyConfig,
convStore ConversationStore,
workflowClient WorkflowClient,
historyClient HistoryClient,
datasetResolver DatasetResolver,
sensitiveWords []string,
) *DifyProvider {
return &DifyProvider{
workflowClient: workflowClient,
historyClient: historyClient,
convStore: convStore,
datasetResolver: datasetResolver,
userIDSalt: cfg.UserIDSalt,
sensitiveWords: sensitiveWords,
}
}
func (p *DifyProvider) Name() string { return "dify" }
func (p *DifyProvider) StreamChat(ctx context.Context, req *ChatRequest) (StreamReader, error) {
return p.workflowClient.StreamRun(ctx, WorkflowRunParams{
DatasetID: p.datasetResolver.Resolve(req.StarID),
Query: req.Message,
UserNickname: req.SystemInputs.UserNickname,
UserMemory: req.SystemInputs.UserMemory,
UserStyle: req.SystemInputs.UserStyle,
UserLanguage: req.SystemInputs.UserLanguage,
UserHashed: p.hashUserID(req.UserID),
ExternalConvID: req.Conversation.ExternalConvID,
SensitiveWords: p.sensitiveWords,
})
}
func (p *DifyProvider) GetOrCreateConversation(ctx context.Context, key ConversationKey) (*Conversation, error) {
return p.convStore.GetOrCreate(ctx, key, p.Name())
}
func (p *DifyProvider) GetConversationMessages(ctx context.Context, conv *Conversation, limit int) ([]*ChatMessage, error) {
if conv.ExternalConvID == "" {
return nil, nil
}
return p.historyClient.FetchMessages(ctx, HistoryFetchParams{
ExternalConvID: conv.ExternalConvID,
UserHashed: p.hashUserID(conv.UserID),
Limit: limit,
})
}
func (p *DifyProvider) AppendConversationMessages(ctx context.Context, conv *Conversation, msgs []*ChatMessage) error {
conv.MessageCount += len(msgs)
conv.LastActiveAt = time.Now().UnixMilli()
return p.convStore.AppendMessages(ctx, conv, msgs)
}
func (p *DifyProvider) UpdateConversationExternalID(ctx context.Context, conv *Conversation, externalID string) error {
if externalID == "" || externalID == conv.ExternalConvID {
return nil
}
return p.convStore.UpdateExternalID(ctx, conv, externalID)
}
func (p *DifyProvider) hashUserID(userID int64) string {
h := sha256.Sum256([]byte(fmt.Sprintf("%d:%s", userID, p.userIDSalt)))
return "aichat-" + hex.EncodeToString(h[:8])
}
```
### 5.4 DifyClient 组件
**新文件** `service/dify_workflow_client.go`：
```go
package service
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"time"
"github.com/topfans/backend/pkg/logger"
"go.uber.org/zap"
)
type DifyWorkflowClientConfig struct {
APIBase string
WorkflowURL string
APIKey string
TimeoutSec int
RetryCount int
}
type DifyWorkflowClient struct {
cfg DifyWorkflowClientConfig
httpClient *http.Client
}
func NewDifyWorkflowClient(cfg DifyWorkflowClientConfig) *DifyWorkflowClient {
return &DifyWorkflowClient{
cfg: cfg,
httpClient: &http.Client{
Timeout: time.Duration(cfg.TimeoutSec) * time.Second,
},
}
}
func (c *DifyWorkflowClient) StreamRun(ctx context.Context, params WorkflowRunParams) (StreamReader, error) {
inputs := map[string]interface{}{
"dataset_id": params.DatasetID,
"query": params.Query,
"user_nickname": params.UserNickname,
"user_memory": params.UserMemory,
"user_style": params.UserStyle,
"user_language": params.UserLanguage,
}
body := map[string]interface{}{
"inputs": inputs,
"response_mode": "streaming",
"conversation_id": params.ExternalConvID,
"user": params.UserHashed,
}
var lastErr error
attempts := c.cfg.RetryCount
if attempts < 1 {
attempts = 1
}
for i := 0; i < attempts; i++ {
jsonData, _ := json.Marshal(body)
httpReq, _ := http.NewRequestWithContext(ctx, "POST",
c.cfg.APIBase+c.cfg.WorkflowURL, bytes.NewReader(jsonData))
httpReq.Header.Set("Authorization", "Bearer "+c.cfg.APIKey)
httpReq.Header.Set("Content-Type", "application/json")
resp, err := c.httpClient.Do(httpReq)
if err != nil {
lastErr = fmt.Errorf("dify request: %w", err)
time.Sleep(500 * time.Millisecond)
continue
}
if resp.StatusCode != http.StatusOK {
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
lastErr = fmt.Errorf("dify returned HTTP %d", resp.StatusCode)
time.Sleep(500 * time.Millisecond)
continue
}
return NewDifyStreamReader(resp.Body, params.SensitiveWords), nil
}
return nil, lastErr
}
```
**新文件** `service/dify_history_client.go`：
```go
package service
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"time"
)
type DifyHistoryClientConfig struct {
APIBase string
APIKey string
TimeoutSec int
}
type DifyHistoryClient struct {
cfg DifyHistoryClientConfig
httpClient *http.Client
}
func NewDifyHistoryClient(cfg DifyHistoryClientConfig) *DifyHistoryClient {
return &DifyHistoryClient{
cfg: cfg,
httpClient: &http.Client{Timeout: time.Duration(cfg.TimeoutSec) * time.Second},
}
}
func (c *DifyHistoryClient) FetchMessages(ctx context.Context, params HistoryFetchParams) ([]*ChatMessage, error) {
url := fmt.Sprintf("%s/messages?conversation_id=%s&user=%s&limit=%d",
c.cfg.APIBase, params.ExternalConvID, params.UserHashed, params.Limit)
httpReq, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
httpReq.Header.Set("Authorization", "Bearer "+c.cfg.APIKey)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("dify fetch history: %w", err)
}
defer resp.Body.Close()
var result struct {
Data []struct {
Role string `json:"role"`
Content string `json:"content"`
} `json:"data"`
}
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
return nil, fmt.Errorf("dify decode history: %w", err)
}
msgs := make([]*ChatMessage, len(result.Data))
for i, m := range result.Data {
msgs[i] = &ChatMessage{Role: m.Role, Content: m.Content}
}
return msgs, nil
}
```
### 5.5 model 包新增
**修改文件** `model/ai_chat_models.go`：
```go
package model
type DifyConfig struct {
Enable bool
APIBase string
WorkflowURL string
APIKey string
TimeoutSec int
UserIDSalt string
RetryCount int
FallbackToMiniMax bool
StarDatasetMapping map[int64]string
}
type Conversation struct {
ID int64 `gorm:"primaryKey;autoIncrement"`
UserID int64 `gorm:"index;not null"`
StarID int64 `gorm:"index;not null"`
ProviderName string `gorm:"type:varchar(32);not null"`
ExternalConvID string `gorm:"type:varchar(128);default:''"`
MessageCount int `gorm:"default:0"`
LastActiveAt int64 `gorm:"autoUpdateTime:milli"`
CreatedAt int64 `gorm:"autoCreateTime:milli"`
UpdatedAt int64 `gorm:"autoUpdateTime:milli"`
}
func (Conversation) TableName() string { return "ai_conversations" }
type AIMessage struct {
ID int64 `gorm:"primaryKey;autoIncrement"`
ConversationID int64 `gorm:"index;not null"`
Role string `gorm:"type:varchar(16);not null"`
Content string `gorm:"type:text;not null"`
CreatedAt int64 `gorm:"autoCreateTime:milli"`
}
func (AIMessage) TableName() string { return "ai_messages" }
```
### 5.6 ChatEngine 编排
**新文件** `service/chat_engine.go`：
```go
package service
import (
"context"
"fmt"
"strings"
"time"
"github.com/redis/go-redis/v9"
"github.com/topfans/backend/pkg/logger"
"go.uber.org/zap"
)
type ChatEngine struct {
providers *ProviderFactory
memoryStore MemoryStore
auditService *AuditService
redisLock RedisLock
redisClient *redis.Client
triggerTurns int
}
func NewChatEngine(
providers *ProviderFactory,
memory MemoryStore,
audit *AuditService,
redisLock RedisLock,
redisClient *redis.Client,
triggerTurns int,
) *ChatEngine {
return &ChatEngine{
providers: providers,
memoryStore: memory,
auditService: audit,
redisLock: redisLock,
redisClient: redisClient,
triggerTurns: triggerTurns,
}
}
type RedisLock interface {
Acquire(ctx context.Context, key string, ttl time.Duration) (acquired bool, token string, err error)
Release(ctx context.Context, key string, token string) error
}
type redisLockImpl struct{ client *redis.Client }
func NewRedisLock(client *redis.Client) *redisLockImpl { return &redisLockImpl{client} }
func (l *redisLockImpl) Acquire(ctx context.Context, key string, ttl time.Duration) (bool, string, error) {
token := uuid.New().String()
ok, err := l.client.SetNX(ctx, key, token, ttl).Result()
return ok, token, err
}
func (l *redisLockImpl) Release(ctx context.Context, key, token string) error {
const script = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`
return l.client.Eval(ctx, script, []string{key}, token).Err()
}
func (e *ChatEngine) SendMessage(ctx context.Context, userID, starID int64, personaID, message string) (<-chan *StreamChunk, error) {
out := make(chan *StreamChunk, 16)
go func() {
defer close(out)
if !e.auditService.AuditText(message) {
e.sendSafeResponse(out)
return
}
provider := e.providers.Select(starID)
providerName := provider.Name()
memories, _ := e.memoryStore.Recall(ctx, userID, message, 5)
memoryText := formatMemories(memories)
lockKey := fmt.Sprintf("conv_lock:%d:%d", userID, starID)
lockAcquired, lockToken, _ := e.redisLock.Acquire(ctx, lockKey, 30*time.Second)
if !lockAcquired {
time.Sleep(200 * time.Millisecond)
lockAcquired, lockToken, _ = e.redisLock.Acquire(ctx, lockKey, 30*time.Second)
if !lockAcquired {
out <- &StreamChunk{Type: "error", Error: "系统繁忙"}
return
}
}
defer e.redisLock.Release(ctx, lockKey, lockToken)
conv, _ := provider.GetOrCreateConversation(ctx, ConversationKey{UserID: userID, StarID: starID})
if conv == nil {
out <- &StreamChunk{Type: "error", Error: "会话创建失败"}
return
}
req := &ChatRequest{
UserID: userID,
StarID: starID,
Message: message,
Conversation: conv,
SystemInputs: &SystemInputs{UserMemory: memoryText, UserLanguage: "zh-CN"},
}
streamReader, err := provider.StreamChat(ctx, req)
if err != nil {
if handled := e.handleLLMFailure(ctx, provider, req, out); !handled {
out <- &StreamChunk{Type: "error", Error: "服务暂不可用"}
}
return
}
defer streamReader.Close()
var fullResponse string
for {
content, done, err := streamReader.Next()
if err != nil {
out <- &StreamChunk{Type: "error", Error: "服务异常"}
return
}
if content != "" && !e.auditService.AuditResponse(content) {
safeMsg := e.auditService.DefaultSafeResponse()
out <- &StreamChunk{Type: "message", Content: safeMsg, IsEnd: false}
out <- &StreamChunk{Type: "message", IsEnd: true}
provider.AppendConversationMessages(ctx, conv, []*ChatMessage{
{Role: "user", Content: message},
{Role: "assistant", Content: safeMsg},
})
return
}
fullResponse += content
out <- &StreamChunk{Type: "message", Content: content, IsEnd: done}
if done { break }
}
if newConvID := streamReader.GetConversationID(); newConvID != "" && newConvID != conv.ExternalConvID {
provider.UpdateConversationExternalID(ctx, conv, newConvID)
conv.ExternalConvID = newConvID
}
provider.AppendConversationMessages(ctx, conv, []*ChatMessage{
{Role: "user", Content: message},
{Role: "assistant", Content: fullResponse},
})
newTurns := conv.MessageCount / 2
if newTurns >= e.triggerTurns && newTurns%e.triggerTurns == 0 {
extractCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
go func() {
defer cancel()
e.memoryStore.Extract(extractCtx, userID, []*ChatMessage{
{Role: "user", Content: message},
{Role: "assistant", Content: fullResponse},
})
}()
}
}()
return out, nil
}
func (e *ChatEngine) sendSafeResponse(out chan<- *StreamChunk) {
safeMsg := e.auditService.DefaultSafeResponse()
out <- &StreamChunk{Type: "message", Content: safeMsg, IsEnd: false}
out <- &StreamChunk{Type: "message", IsEnd: true}
}
func (e *ChatEngine) handleLLMFailure(ctx context.Context, provider AIProvider, req *ChatRequest, out chan<- *StreamChunk) bool {
if req.Conversation.MessageCount > 0 {
out <- &StreamChunk{Type: "error", Error: "服务暂不可用，请稍后重试"}
return true
}
fallback := e.providers.SelectFallback(provider.Name())
if fallback != nil {
streamReader, _ := fallback.StreamChat(ctx, req)
if streamReader != nil {
defer streamReader.Close()
for {
content, done, _ := streamReader.Next()
if content != "" {
out <- &StreamChunk{Type: "message", Content: content, IsEnd: done}
}
if done { break }
}
return true
}
}
return false
}
```
### 5.7 main.go 装配
```go
// 加载 Dify 配置
difyConfigs, _ := configRepo.GetByCategory(loadCtx, "dify")
difyConfig, _ := loadDifyConfig(difyConfigs)
// 创建 ConversationStore
convStore := service.NewCachedConversationStore(convRepo, msgRepo, redisClient)
// 创建 Dify 客户端组件
workflowClient := service.NewDifyWorkflowClient(service.DifyWorkflowClientConfig{
APIBase: difyConfig.APIBase,
WorkflowURL: difyConfig.WorkflowURL,
APIKey: difyConfig.APIKey,
TimeoutSec: difyConfig.TimeoutSec,
RetryCount: difyConfig.RetryCount,
})
historyClient := service.NewDifyHistoryClient(service.DifyHistoryClientConfig{
APIBase: difyConfig.APIBase,
APIKey: difyConfig.APIKey,
})
datasetResolver := service.NewDatasetResolver(difyConfig.StarDatasetMapping)
// 创建 Provider
difyProvider := service.NewDifyProvider(difyConfig, convStore, workflowClient, historyClient, datasetResolver, nil)
miniMaxProvider := service.NewMiniMaxProvider(convRepo, msgRepo)
// 创建 ProviderFactory
factory := service.NewProviderFactory(difyConfig, difyProvider, miniMaxProvider)
// 创建 Redis 锁
redisLock := service.NewRedisLock(redisClient)
// 创建 ChatEngine
chatEngine := service.NewChatEngine(factory, memoryService, auditService, redisLock, redisClient, 5)
// Provider 大幅简化
aiChatProvider := provider.NewAIChatProvider(chatEngine)
```
### 5.8 Provider 大幅简化
```go
// 极简版本：只做 Dubbo 入口 + 参数解析
func (p *AIChatProvider) SendMessage(ctx context.Context, req *pb.ChatMessageRequest, stream pb.AIChatService_SendMessageServer) error {
userID, _, err := extractUserInfoFromDubboAttachments(ctx)
if err != nil { return err }
chunks, err := p.chatEngine.SendMessage(ctx, userID, 87, "", req.Message)
if err != nil { return err }
for chunk := range chunks {
if chunk.Type == "error" {
stream.Send(&pb.ChatMessageResponse{Content: chunk.Error, IsEnd: true})
} else {
stream.Send(&pb.ChatMessageResponse{Content: chunk.Content, IsEnd: chunk.IsEnd})
}
}
return nil
}
```
> **从此 Provider 不再有 `if useDify` 分支**。
---
## 六、消息流时序
### 6.1 首次对话（Dify 路径）
```
[Mobile] → [Gateway] → [Provider] → [ChatEngine]
│
├─ 1. 前置审核
├─ 2. 选 DifyProvider
├─ 3. 长期记忆召回
├─ 4. 加锁 (RedisLock)
├─ 5. GetOrCreateConv
│ └─ 查 Redis 缓存 → 查 PG → 创建
│
├─ 6. StreamChat
│ ├─ DatasetResolver.Resolve(87) → dataset_id
│ ├─ WorkflowClient.StreamRun(params)
│ └─ POST /v1/workflows/run
│ └─ {dataset_id, query, user_*}
│
│ ↓ Dify 返回 SSE
│ ↓
│ audit + stream.Send
│ ↓
│ message{content, is_end}
│ ↓
├─ 7. UpdateExternalID
│ └─ convStore.UpdateExternalID
│
├─ 8. AppendMessages
│ └─ 更新 message_count
│
└─ 9. 释放锁 + 记忆提取
```
### 6.2 续接对话（次日重连）
```
1. ChatEngine.SendMessage
2. GetOrCreateConv → ConvStore.GetOrCreate → 查 Redis 缓存命中
3. StreamChat → WorkflowClient.StreamRun → POST {conversation_id: "uuid-xxx"}
4. 流式返回
5. AppendMessages
```
**关键**：conversation_id 在 DB 中永久保留，跨天/跨设备都能续上。
### 6.3 Fallback 场景
```
DifyProvider.StreamChat
↓ 失败
DifyProvider.StreamChatWithBackup // 网络层重试一次
↓ 失败
├─ conv.MessageCount == 0 && dify.fallback_to_minimax=true
│ → 切到 MiniMaxProvider
└─ 其他情况
→ 返回错误给前端
```
---
## 七、错误处理与降级
### 7.1 错误分类与处理
| 错误类型 | 处理 |
|---------|------|
| **Dify 401/403** | 直接返回错误（不重试、不 fallback） |
| **Dify 5xx** | 重试 N 次（dify.retry_count），仍失败按 fallback 规则 |
| **Dify timeout** | 同 5xx |
| **Dify 流中断** | 后置 audit 拦截 + 返回安全回复 |
| **PostgreSQL 不可用** | GetOrCreateConv 失败，返回错误 |
| **Redis 不可用** | 降级到直接读 PostgreSQL |
### 7.2 监控指标（建议）
| 指标 | 类型 | 来源 |
|------|------|------|
| `aichat_provider_request_total{provider, status}` | counter | ChatEngine |
| `aichat_provider_fallback_total{from, reason}` | counter | ChatEngine |
| `aichat_dify_stream_duration_ms` | histogram | DifyProvider |
---
## 八、安全与审核
### 8.1 审核
- **前置审核**：`auditService.AuditText(message)` 拦截敏感词
- **后置审核**：`auditService.AuditResponse(token)` 逐 token 拦截
- **Dify 流中 error 事件**：ChatEngine 捕获 err 后发安全回复
### 8.2 知识库内容安全
- Dify Dataset 导入时由 Dify 端做内容审核
- 建议 Workflow 内部加"内容审核节点"（Dify 原生能力）
### 8.3 Dify API Key 安全
- 存储：`ai_chat_configs.config_value`，`is_encrypted=TRUE`
- 实际加解密：依赖 PostgreSQL 访问控制
- 不记录到日志
- 不返回给前端
### 8.4 user 字段隐私
- 哈希化：`aichat-{sha256(userId + salt)[:16]}`
- 盐值：`dify.user_id_salt` 环境变量
- Dify 端运营无法反推 user_id
---
## 九、配置文件清单
### 9.1 环境变量
| 变量 | 用途 | 必填 |
|------|------|------|
| `DIFY_USER_ID_SALT` | 哈希 user_id 的盐 | 是 |
### 9.2 ai_chat_configs 数据
9 个 `dify.*` 配置项（详见 §4.1）
### 9.3 不需要的环境变量
- `DIFY_API_KEY`：走 ai_chat_configs
- `DIFY_API_BASE`：走 ai_chat_configs
---
## 十、Stage 2+ 演进路径
> **MVP 优先**：MVP 阶段不实施本文档的复杂设计。先读 [MVP 文档](2026-06-29-ai-chat-dify-mvp-design.md)，按 MVP 实施。
**Stage 2+ 演进时必踩的 3 个坑**（P0 修复笔记）和 **3 个架构评审笔记**，已迁到 MVP §10（V2 不重复）。
| Stage | 触发条件 | 关键改动 |
|-------|---------|---------|
| **Stage 2** | 用户量 > 1000 OR 加第 2 个星 | 1. 多星 Dataset 切换
2. WebSocket 端 InitSession 欢迎语动态化
3. ai_conversations 加 UNIQUE |
| **Stage 3** | Dify 偶发故障 OR SLA 要求 | 1. MiniMax fallback
2. Dify retry 循环 |
| **Stage 4** | 用户量 > 10万 OR 接 2+ AI 平台 | 1. AIProvider 抽象
2. ProviderFactory 策略模式
3. CozeProvider / OpenAIProvider 实现 |
| **Stage 5** | 用户量 > 100万 OR 业务复杂 | 1. ChatEngine Pipeline 化
2. AIProfile 配置化
3. 长期记忆提取 |
---
## 十一、目录与文件改动
```
backend/services/aiChatService/
├── main.go ← 改
├── model/
│ ├── ai_chat_models.go ← 改（新增 DifyConfig / Conversation / AIMessage）
│ └── ai_chat_errors.go
├── provider/
│ ├── ai_chat_provider.go ← 大幅简化
├── service/
│ ├── ai_provider.go ← 新建：AIProvider interface
│ ├── dify_provider.go ← 新建：DifyProvider
│ ├── dify_workflow_client.go ← 新建
│ ├── dify_history_client.go ← 新建
│ ├── dataset_resolver.go ← 新建
│ ├── conversation_store.go ← 新建
│ ├── minimax_provider.go ← 新建
│ ├── chat_engine.go ← 新建
│ ├── provider_factory.go ← 新建
│ ├── redis_lock.go ← 新建
│ ├── chat_service.go ← 删除
│ ├── llm_service.go ← 保留
│ ├── prompt_builder.go ← 保留
│ ├── memory_service.go ← 改
│ ├── audit_service.go ← 改（加 GetSensitiveWords）
│ ├── persona_service.go ← 不改
└── repository/
├── conversation_repository.go ← 新建
├── message_repository.go ← 新建
├── memory_repository.go ← 不改
├── persona_repository.go ← 不改
└── config_repository.go ← 不改
migrations/
└── ai_conversations.sql ← 新建
```
**新建文件**：11 个
**修改文件**：5 个
**删除文件**：1 个
---
## 十二、关键文件参考索引
### 12.1 相关文档
- **MVP 实施级方案**：[2026-06-29-ai-chat-dify-mvp-design.md](2026-06-29-ai-chat-dify-mvp-design.md)（**先读**）
- AI Chat 整体设计：[backend/docs/AI-Chat-Service设计方案.md](backend/docs/AI-Chat-Service设计方案.md)
### 12.2 后端代码
- AIChat Provider：[backend/services/aiChatService/provider/ai_chat_provider.go](backend/services/aiChatService/provider/ai_chat_provider.go)
- AIChat LLM Service：[backend/services/aiChatService/service/llm_service.go](backend/services/aiChatService/service/llm_service.go)
- AIChat Memory Service：[backend/services/aiChatService/service/memory_service.go](backend/services/aiChatService/service/memory_service.go)
- AIChat 装配：[backend/services/aiChatService/main.go](backend/services/aiChatService/main.go)
- 模型定义：[backend/services/aiChatService/model/ai_chat_models.go](backend/services/aiChatService/model/ai_chat_models.go)
- Star 模型：[backend/pkg/models/user.go](backend/pkg/models/user.go)
- Gateway WebSocket：[backend/gateway/socket/ai_chat_socket.go](backend/gateway/socket/ai_chat_socket.go)
- Dify 现有（镭射卡）：[backend/gateway/service/dify_client.go](backend/gateway/service/dify_client.go)
### 12.3 前端
- 页面：[frontend/pages/ai-dazi/index.vue](frontend/pages/ai-dazi/index.vue)
- WebSocket 封装：[frontend/utils/socket/AiChatSocket.js](frontend/utils/socket/AiChatSocket.js)
- 全局管理：[frontend/utils/socket/GlobalSocketManager.js](frontend/utils/socket/GlobalSocketManager.js)
### 12.4 Dify 官方
- Workflow API：https://docs.dify.ai/api-reference/workflow/run-workflow
- Knowledge Retrieval 节点：https://docs.dify.ai/guides/workflow/node/knowledge-retrieval
---
## 十三、后续优化（不在 V2 范围）
> 这些是 P0 修复笔记和架构评审笔记的具体化，**详见 MVP §10**：
> - ★ P0 修复：并发 race（RedisLock）、审计后保存、组合敏感词（滑动窗口）
> - ★ 架构评审：Provider God Class、Provider 依赖存储、Workflow 重复 mapping
其他：
- Coze / FastGPT 接入（Stage 4）
- 知识库自动同步 Worker（独立项目）
- ConfigWatcher 热加载
- 用户 persona 完全自定义
- 对话质量评估
- A/B 测试框架
- 多轮摘要压缩
- 跨星记忆
---
## 十四、总结
V2 是"100 明星 + 多 AI 平台"的完整架构设计。
**V2 vs MVP**：
- V2 完整（约 1500-2000 行代码、5 周工作量）
- MVP 精简（约 300-500 行代码、1 周可落地）
**实施路径**：
1. **MVP 阶段**：按 [MVP 文档](2026-06-29-ai-chat-dify-mvp-design.md) 实施（**不要看 V2**）
2. **Stage 2+**：MVP 跑通后，参考 V2 的具体代码示例 + MVP §10 的关键坑笔记
3. **Stage 4 抽象**：从 V2 复制 `AIProvider` interface 代码，按需调整
V2 与 MVP 是**互补**关系，不是替代关系。