# LangGraph Sidecar 迁移 — 需求与决策汇总

**日期**: 2026-07-20
**状态**: 终稿（已批准）
**版本**: 1.0

---

## 1. 背景与动因

### 1.1 现有 AI 架构

cfc-backend 自 2025 年起接入 [Dify](http://dify.bianwoyou.cn/v1)（开源 LLM 应用平台）提供全部 AI 能力：

| 使用场景 | Dify 能力 | Java 消费者 |
|---------|-----------|------------|
| 家庭 AI 聊天（通用助手 + 精准营养助手） | Chatbot API | `AIService.sendMessage()`, `sendNutritionMessage()` |
| 工作流（任务解析/舌诊/异步摘要） | Workflow API | `AIService.runWorkflow()`, `sendTongueDiagnosis()` |
| 知识库检索 | Datasets API | `DifySyncService.syncToDify()` |
| 文章 AI 问答 | Chatbot API | `ArticleService.getAiQuestions()` |

Dify 深度嵌入 8 个 Service、3 个 Controller，承担 AI 能力中间件角色。

### 1.2 迁移动因

| 问题 | 描述 | 优先级 |
|------|------|--------|
| **数据安全** | 所有对话/报告数据经 Dify 平台流转，无法保证数据不外泄 | P0 |
| **黑盒 Prompt** | Dify 应用内的 prompt 编辑无版本管理，调试困难 | P1 |
| **不可控发布** | Dify 版本升级可能引入不兼容变更，发布节奏被动 | P1 |
| **运维负担** | Dify 自部署实例需单独维护资源，偶发不可用 | P2 |
| **灵活性不足** | Agent 编排能力有限，难以实现复杂条件路由和 HITL | P2 |
| **成本** | Dify 本身无授权费，但作为中间层增加了调用链路开销 | P3 |

---

## 2. 需求分析

### 2.1 核心需求

| ID | 需求 | 说明 | 优先级 |
|----|------|------|--------|
| R1 | 消除 Dify 单点依赖 | 所有 AI 能力线下部署，不依赖外部平台 | P0 |
| R2 | Java 8/Spring Boot 2.7 不动 | 后端不升级 JDK/框架，最小化 Java 侧改动 | P0 |
| R3 | Agent 编排能力 | 支持条件路由、多步骤、工具调用、循环 | P0 |
| R4 | 对话记忆 | 短期（窗口）+ 长期（实体/事实）+ 语义（向量召回） | P0 |
| R5 | RAG 知识库 | 知识文档加载、分块、向量化、混合检索 | P1 |
| R6 | 工具调用安全 | Python Agent 通过 HTTP 调 Java 获取数据，不直连 MySQL | P1 |
| R7 | 灰度迁移 | Dify 保留为 fallback，流量逐步切换 | P0 |
| R8 | 运维简单 | 最小化中间件依赖，单机可部署 | P1 |

### 2.2 覆盖场景

| 场景 | 当前实现 | 目标 Agent |
|------|---------|-----------|
| 家庭聊天（通用） | Dify Chatbot → AIService | ChatAgent（StateGraph） |
| 精准营养推荐 | Dify Chatbot → AIService | RecommendAgent（LLM + RAG） |
| 健康报告解读 | Dify Workflow | AnalysisAgent |
| 舌诊分析 | Dify Workflow | MultiModalAgent |
| 任务自动解析 | Dify Workflow | TaskAgent（ChatAgent 子节点） |
| 文章 AI 问答 | Dify Chatbot | ChatAgent + RAG |
| 知识库同步 | Dify Datasets API | KnowledgePipeline |

### 2.3 非需求

- 不改动 Java 端 JDK/Spring Boot 版本
- 不改动 cfc 业务逻辑（Controller/Service 现有行为不变）
- 不立即引入 PostgreSQL/Redis 等额外中间件
- 不做完整的 A/B 测试平台

---

## 3. 方案评估

### 3.1 候选方案

#### A. Spring AI（Java 侧内嵌）

| 维度 | 评估 |
|------|------|
| 技术栈 | Spring AI 1.x + Spring Boot 3.x → **需升级 JDK 8→21** |
| Agent 能力 | 基础 Tool Calling + Chain, **无 StateGraph/条件路由** |
| RAG | 基础 ETL pipeline, 不如 LangChain 成熟 |
| 学习成本 | 团队熟悉 Java, 但 Spring AI 2025 年才 GA, 生态不完善 |
| **结论** | ❌ 否决 — 需要 JDK 升级 + Agent 能力不足 |

#### B. LangChain4j（Java 侧内嵌）

| 维度 | 评估 |
|------|------|
| 技术栈 | LangChain4j 1.x, **兼容 Java 8** |
| Agent 能力 | Tool Calling + 简单链, **无 LangGraph 编排** |
| RAG | 完整 pipeline (embedding/store/retrieval) |
| 社区 | 较小, 文档不完善 |
| LLM 调用 | 需通过 Spring AI 或直接 HTTP |
| **结论** | ❌ 否决 — Agent 编排能力不足, 无图执行引擎 |

#### C. Python LangGraph Sidecar ✅

| 维度 | 评估 |
|------|------|
| 技术栈 | FastAPI + LangChain + LangGraph + ChromaDB |
| Agent 能力 | **完整 StateGraph**：条件路由/循环/并行/HITL/持久化 |
| RAG | 最成熟的 LangChain RAG pipeline |
| 记忆 | 三层记忆（BufferMemory + EntityMemory + VectorStoreMemory） |
| Java 改动 | 最小——仅 AIService 加 HTTP 路由, 新增 AiGateway |
| 社区 | 全球最大 LLM 框架生态 |
| 部署 | Docker Compose / systemd 均可 |
| **结论** | ✅ **选定方案** |

### 3.2 决策树

```
Dify 替代方案
├─ 留在 Java 侧
│  ├─ Spring AI    → ❌ 需 JDK 21 + Agent 能力不足
│  └─ LangChain4j  → ❌ Agent 编排能力不足 + 社区小
└─ Python 侧服务   → ✅ LangGraph Sidecar
```

### 3.3 已否决但文档化的选择

| 方案 | 否决原因 | 存档位置 |
|------|---------|---------|
| Spring Boot 3 升级 + Spring AI | 需 JDK 8→21 全量升级, 风险大, Agent能力不足 | `docs/backup/architecture/` |
| LangChain4j 内嵌 | Agent编排受限, 无StateGraph, 社区不成熟 | — |
| Dify 继续使用 + 小修小补 | 数据安全问题不解决, 长期不可持续 | — |
| 替换 Dify 但保留 AxonHub 路由 | 增加第三方依赖, 不如直接调 LLM API | — |

---

## 4. 最终架构

### 4.1 架构总览

```
用户 (微信小程序 / Web)
  │ HTTP
  ▼
cfc-backend (Java 8, Spring Boot 2.7.18)
  ├── 业务 Controller (不变)
  ├── AIService.java → AiGateway.java (HTTP→Python, fallback→Dify)
  └── AiContextService.java (Python 调用的数据接口)
  │ HTTP (内网)
  ▼
langgraph-service (Python 3.11, FastAPI :9000)
  ├── FastAPI 网关 + Agents (RecommendAgent / ChatAgent / AnalysisAgent / MultiModalAgent)
  ├── LangGraph StateGraph 引擎 + Checkpointer + Memory Manager
  ├── RAG Pipeline (ChromaDB 文件模式 + 混合检索 + 重排序)
  └── Tool 层 (HTTP → Java 数据接口)
  │
  ▼
LLM API (DeepSeek-V3 / Qwen2.5 / Embedding API)
```

### 4.2 关键设计决策

| 决策 | 选项 | 选择 | 理由 |
|------|------|------|------|
| JDK 版本 | 8 / 21 | **Java 8 不变** | 全量升级风险大, LangGraph sidecar 不需要 |
| 内存数据库 | SQLite / Chroma / PGVector | **ChromaDB 文件模式** | 零配置, 10 万条内足够 |
| Checkpointer | MemorySaver / PG | **MemorySaver 优先** | Phase 1-2 不依赖 PG, 后续按需升级 |
| 工具调用方式 | 直连 MySQL / HTTP 调 Java | **HTTP 调 Java** | 数据主权在 Java 侧, 安全可控 |
| 部署方式 | Docker Compose / systemd | **两者皆可** | 开发用 Docker, 生产按实际情况选 |
| 模型路由 | 直调 LLM / 通过 AxonHub | **直调 LLM API** | 简化架构, 减少第三方依赖 |
| 记忆同步 | Python 主写 / Java 主写 | **Python 主写** | 记忆是 Agent 的一部分，自然归 Python |
| Dify 处理 | 立即停用 / 保留 fallback | **保留 fallback** | 灰度迁移, 按阶段逐步关闭 |

### 4.3 项目结构

```
D:\workspace\cfc\cfc-langgraph\        # 新建 Python 项目
├── pyproject.toml / Dockerfile / docker-compose.yml
├── app/
│   ├── main.py / config.py / api/    # FastAPI 入口 + 路由
│   ├── agents/                        # LangGraph Agent 定义
│   ├── graphs/                        # StateGraph 图定义
│   ├── tools/                         # Agent Tool (HTTP→Java)
│   ├── rag/                           # RAG Pipeline
│   ├── memory/                        # 记忆管理
│   └── models/                        # Pydantic 模型
├── data/chroma_db/                    # 向量数据库持久化
└── tests/
```

### 4.4 API 接口

| 端点 | 方法 | Agent | 说明 |
|------|------|-------|------|
| `/api/v1/chat` | POST | ChatAgent | 家庭 AI 聊天 |
| `/api/v1/recommend` | POST | RecommendAgent | 商品/活动/文章推荐 |
| `/api/v1/analyze` | POST | AnalysisAgent | 健康报告解读 |
| `/api/v1/agent` | POST | Orchestrator | 多 Agent 编排 |
| `/api/v1/tongue` | POST | MultiModalAgent | 舌诊图像分析 |
| `/api/v1/health` | GET | — | 健康检查 |

Java AI Gateway 接口（供 Python Tool 层调用）：

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/ai/context/user/{id}` | GET | 用户/家庭上下文 |
| `/api/ai/context/report/{id}` | GET | 健康报告详情 |
| `/api/ai/context/emotion/{id}` | GET | 情绪数据 |
| `/api/product/search` | POST | 商品/活动检索 |

### 4.5 资源估算

| 资源 | 最低 | 推荐 |
|------|------|------|
| CPU | 0.5 核 | 1 核 |
| 内存 | 256MB | 512MB |
| 磁盘 | 1GB (代码+Chroma) | 5GB (含日志) |
| LLM Token | 与 Dify 基本持平 (+10% Agent 多轮) | — |

---

## 5. 分阶段迁移计划

### Phase 1：基建 + RecommendAgent（第1-2周）

**目标**: Python 服务跑起来, 第一个 Agent 上线

| Task | 内容 | 文件 |
|------|------|------|
| 1 | 脚手架：pyproject.toml, FastAPI 骨架, Dockerfile | `cfc-langgraph/` |
| 2 | 配置管理 + .env 模板 | `app/config.py`, `.env.example` |
| 3 | 健康检查 + 基础中间件 | `app/api/health.py` |
| 4 | ChromaDB 初始化 + 知识库文章加载 | `app/rag/` |
| 5 | RecommendAgent (LLM + tool search_product/search_article) | `app/agents/recommend_agent.py` |
| 6 | 推荐 API (`POST /api/v1/recommend`) | `app/api/recommend.py` |
| 7 | Java AiGateway (HTTP→Python + 熔断 + Dify fallback) | `cfc-backend/.../service/AiGateway.java` |
| 8 | RecommendationController 改造：灰度 5% 走 Python | `cfc-backend/.../controller/` |
| 9 | Docker Compose 编排 | `docker-compose.yml` |
| 10 | 集成测试 + 边界验证 | `tests/` |

**交付标准**:
- `curl /api/v1/health` 返回 200
- `curl /api/v1/recommend` 返回推荐结果（含 LLM 理由）
- Java 侧 5% 流量走 Python, 异常自动 fallback
- 编译验证 `mvn clean compile`

**计划文档**: `docs/superpowers/plans/2026-07-20-langgraph-phase1.md`

### Phase 2：ChatAgent + RAG + 记忆（第3-4周）

**目标**: 替代 Dify 核心聊天能力

| Task | 内容 |
|------|------|
| 1 | 三层记忆（BufferMemory + EntityMemory + VectorStoreMemory） |
| 2 | 意图分类器（classify_intent node） |
| 3 | ChatAgent StateGraph（classify→load_context→llm_call→parse_tasks） |
| 4 | RAG Pipeline（混合检索 + 重排序 + 压缩） |
| 5 | Java Context API（供 Python 调用的 HTTP 数据接口） |
| 6 | Java AIService 改造：聊天优先走 Python, Dify fallback |
| 7 | 集成测试 + 灰度 30% |
| 8 | AiUserFact / AiConversationSummary 设为只读 |

**计划文档**: `docs/superpowers/plans/2026-07-20-langgraph-phase2.md`

### Phase 3：高级 Agent + 知识库自动化（第5-6周）

**目标**: 剩余场景迁移 + 运维就绪

| Task | 内容 |
|------|------|
| 1 | AnalysisAgent（报告解读 StateGraph） |
| 2 | MultiModalAgent（舌诊） |
| 3 | KnowledgePipeline（定时从 Java 拉文章→分块→向量化） |
| 4 | LangSmith Trace 接入 |
| 5 | DifySyncService 标记废弃 |
| 6 | 灰度 100%, Dify 降级为冷备 |

**计划文档**: `docs/superpowers/plans/2026-07-20-langgraph-phase3.md`

### Phase 4：收尾 + 运维（第7-8周）

**目标**: 运维完善, 代码清理

| Task | 内容 |
|------|------|
| 1 | Python 侧性能调优（连接池、缓存、异步） |
| 2 | Prometheus 监控 + /metrics 暴露 |
| 3 | JSON 日志标准化 + 日志聚合 |
| 4 | 生产级 Docker Compose |
| 5 | Java 侧清理 Dify 相关代码 |
| 6 | 运维文档 + 架构文档更新 |

**计划文档**: `docs/superpowers/plans/2026-07-20-langgraph-phase4.md`

---

## 6. 决策日志

### 6.1 已决定的否决项

| 否决项 | 时间 | 原因 |
|--------|------|------|
| Spring Boot 3 升级 | 2026-07-20 | 全量升级 JDK 8→21 风险大, 收益不足 |
| Dify 原地修补 | 2026-07-20 | 数据安全问题不解决 |
| AxonHub 模型路由 | 2026-07-20 | 增加第三方依赖, 直调 LLM API 更简单 |
| Java LangChain4j | 2026-07-20 | Agent 编排能力不足, 社区小 |
| Python 直连 MySQL | 2026-07-20 | 数据安全性、事务一致性风险 |
| Dify 立即下线 | 2026-07-20 | 需要灰度过渡期 |

### 6.2 已确立的原则

1. **数据主权**: Agent Tool 一律通过 HTTP 调 Java 接口, Python 不直连 DB
2. **最小改动**: Java 侧只改 AIService 路由和新增 AiGateway, 不动业务逻辑
3. **灰度安全**: 每个 Phase 都有流量开关 + Dify fallback, 可随时回退
4. **渐进式迁移**: 4 个 Phase 串行, 每阶段有独立验证点
5. **无锁定**: LangGraph 是标准 Python 框架, 无需特殊基础设施

---

## 7. 文档清单

### 7.1 当前有效文档（无需变更）

| 文件 | 说明 |
|------|------|
| `docs/superpowers/specs/2026-07-20-langgraph-migration-design.md` | LangGraph 迁移设计文档（架构/API/记忆/部署） |
| `docs/superpowers/specs/2026-07-20-langgraph-requirements-summary.md` | **本文件** — 需求与决策汇总 |
| `docs/superpowers/plans/2026-07-20-langgraph-phase1.md` | Phase 1 实施计划（10 个 Task） |
| `docs/superpowers/plans/2026-07-20-langgraph-phase2.md` | Phase 2 实施计划（8 个 Task） |
| `docs/superpowers/plans/2026-07-20-langgraph-phase3.md` | Phase 3 实施计划（6 个 Task） |
| `docs/superpowers/plans/2026-07-20-langgraph-phase4.md` | Phase 4 实施计划（6 个 Task） |

### 7.2 已归档文档（被本方案否决）

| 原路径 | 现路径 | 说明 |
|--------|--------|------|
| `docs/architecture/SpringBoot3升级+Dify替代实施计划.md` | `docs/backup/architecture/SpringBoot3升级+Dify替代实施计划.md` | Spring Boot 3 + Spring AI 方案（JDK 升级前提） |
| `docs/architecture/Dify替代迁移可行性分析.md` | `docs/backup/architecture/Dify替代迁移可行性分析.md` | Spring AI 替代可行性分析 |
| `docs/architecture/2026-07-20-SB3-upgrade-plan.md` | `docs/backup/architecture/2026-07-20-SB3-upgrade-plan.md` | SB3 升级 + Dify 替代实现计划 |
| `docs/数据与AI结合技术方案.md` | `docs/backup/数据与AI结合技术方案.md` | 原始数据+AI 技术方案（Dify 时代） |
| `docs/实现计划.md` | `docs/backup/实现计划.md` | 原始实现计划（Dify 时代） |

---

## 8. 风险登记册

| 风险 | 概率 | 影响 | 应对 | 责任人 |
|------|------|------|------|--------|
| Python 服务不稳定 | 中 | 高 | Phase 1 灰度 5% + 熔断 + Dify fallback | 开发 |
| LangGraph 学习成本 | 高 | 中 | Phase 1 从最简 Agent 开始 | 开发 |
| 记忆数据迁移丢失 | 低 | 中 | Phase 2 前 Java 侧保持双写 | 开发 |
| ChromaDB 性能瓶颈 | 低 | 中 | 10 万条内足够, 超出切 PGVector | 架构 |
| LLM API 费用增加 | 中 | 低 | Agent 多轮约多 10% token | 运营 |
| Java 8 兼容性 | 低 | 高 | Java 侧不改依赖, 不影响 | 开发 |

---

## 9. 当前状态

- ✅ 方案评审通过
- ✅ 设计文档发布
- ✅ 4 个 Phase 计划已编写并推送 (`cfclub` 分支)
- ⏸ 等待执行指令
- ❌ Phase 1-4 尚未开始实施

**下一步**: 用户确认 → 开始 Phase 1 Task 1（脚手架搭建）