# LangChain 1.0 升级说明

## 一、升级概览

本项目已完成从 LangChain 0.3 到 LangChain 1.x 的升级，并同步升级 LangGraph 至 1.x。升级后兼容 Python 3.12。

## 二、依赖变更

| 包 | 升级前 | 升级后 |
|----|--------|--------|
| langchain | >=0.3.0 | >=1.0.0 |
| langchain-core | (间接依赖) | >=0.3.0 |
| langchain-openai | >=0.2.0 | >=0.2.0 |
| langgraph | >=0.2.74 | >=1.0.0 |
| langchain-community | >=0.4.0 | **已移除**（项目未使用） |

## 三、代码改造说明

### 3.1 保持不变的部分

项目采用 **自定义 StateGraph** 架构（非 `create_react_agent`），以下导入在 LangChain/LangGraph 1.x 中保持兼容：

```python
from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode
from langchain_core.tools import tool
```

### 3.2 已适配的变更

1. **消息内容提取**：LangChain 1.0 引入 `content_blocks`，`content` 可能为字符串或 multimodal 列表。新增 `_extract_message_text()` 辅助函数，统一处理两种格式。
2. **依赖精简**：移除未使用的 `langchain-community`，减少依赖冲突。

### 3.3 LangChain 1.0 主要变更（参考）

- **包命名空间精简**：核心功能移至 `langchain-core`，`langchain` 主包聚焦 Agent 构建
- **create_agent**：若未来迁移到 `langchain.agents.create_agent`，可参考 `docs/Skills实现方案-LangChain1.0.md`
- **langchain-classic**：Legacy chains、Retrievers 等已迁移至 `langchain-classic`，本项目未使用

## 四、环境要求

- **Python**：3.12+（**LangChain 1.x 要求 Python 3.10+**，不支持 3.9 及以下）
- 若系统默认 Python 版本过低，需使用虚拟环境：

```bash
# 方式 1：使用 conda（推荐，项目根目录 scripts/setup_conda_env.sh）
conda create -n shop_agent python=3.12
conda activate shop_agent
pip install -r requirements.txt

# 方式 2：使用 pyenv
pyenv install 3.12
pyenv local 3.12
pip install -r requirements.txt

# 方式 3：使用 venv（需系统已安装 python3.12）
python3.12 -m venv venv
source venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
```

## 五、验证

```bash
# 验证导入
python -c "
from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph
from langgraph.prebuilt import ToolNode
print('LangChain 1.x 依赖加载成功')
"
```