# shop_agent

**Repository Path**: andy1215/shop_agent

## Basic Information

- **Project Name**: shop_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能选品系统

基于 AgentScope 的多人并发智能选品推荐系统。用户通过自然语言描述需求，系统理解意图后从商城接口查询匹配商品。

## 功能特性

- 🤖 **AI 驱动** - 自然语言理解用户选品需求
- 🔄 **SSE 流式响应** - 实时返回推荐结果
- 👥 **多用户并发** - 支持多用户同时使用
- 💾 **三层记忆架构** - 用户 → 会话 → 上下文持久化存储
- 🛠️ **AgentScope ReAct Agent** - 通过 Agent + Tool Calling 自动查询商品并生成推荐

## 快速开始

### 环境要求

- Python 3.12+
- uv 包管理器

如果本机还没有安装 `uv`，可以先执行：

```bash
pip install uv
```

### 安装

```bash
# 克隆项目
git clone <repository-url>
cd demo1

# 安装依赖
uv sync
```

### 配置

项目根目录需要有 `.env` 文件，用来配置大模型访问参数：

```env
DASHSCOPE_API_KEY=your-api-key
DASHSCOPE_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
DASHSCOPE_MODEL=glm-5
```

说明：

- `DASHSCOPE_API_KEY` 必填，否则推荐接口无法调用模型
- `DASHSCOPE_BASE_URL` 和 `DASHSCOPE_MODEL` 可以直接使用上面的默认值
- 项目会自动读取根目录下的 `.env`

### 启动服务

在项目根目录执行：

```bash
uv run uvicorn main:app --reload
```

启动成功后默认监听：

- 应用首页：<http://127.0.0.1:8000/>
- API 文档：<http://127.0.0.1:8000/docs>
- 健康检查：<http://127.0.0.1:8000/health>

注意：

- 不要直接双击本地 `index.html` 文件运行前端
- 应通过 `http://127.0.0.1:8000/` 访问，这样页面会和后端走同一个服务地址

### 运行效果验证

服务启动后，可以先用下面几种方式确认系统正常：

1. 打开 `http://127.0.0.1:8000/health`，返回 `{"status":"ok"}` 说明服务已启动
2. 打开 `http://127.0.0.1:8000/docs`，可以直接调试接口
3. 打开 `http://127.0.0.1:8000/`，在页面里输入用户 ID 和选品需求，点击“开始推荐”

### 推荐流程说明

页面或接口调用推荐时，系统会按下面的流程运行：

1. 创建或复用当前用户会话
2. 读取历史上下文
3. 调用大模型解析选品需求
4. 通过 AgentScope ReAct Agent 调用商品搜索工具
5. 以 SSE 流式返回推荐结果
6. 将用户问题和助手回复写入 SQLite 记忆库

### 常用运行命令

```bash
# 启动开发服务
uv run uvicorn main:app --reload

# 运行测试
uv run pytest -q

# 查看接口文档
# 浏览器访问 http://127.0.0.1:8000/docs
```

## API 接口

### SSE 流式接口

| 接口 | 说明 |
|------|------|
| `GET /sse/product/recommend?user_id=xxx&query=推荐欧洲热销商品` | 智能选品推荐，自动创建或复用会话 |
| `GET /sse/product/chat?user_id=xxx&session_id=xxx&query=追问内容` | 对话追问 |

### 会话管理

| 接口 | 说明 |
|------|------|
| `POST /session/create?user_id=xxx&title=会话标题` | 创建新会话 |
| `GET /session/list?user_id=xxx` | 获取用户会话列表 |
| `GET /session/history?session_id=xxx` | 获取会话历史 |
| `DELETE /session/delete?session_id=xxx` | 删除会话 |

### 商城数据

| 接口 | 说明 |
|------|------|
| `GET /mall/categories` | 获取商品类别 |
| `GET /mall/regions` | 获取销售区域 |
| `GET /mall/products?category=electronics&region=Europe` | 直接搜索商品 |

### 推荐接口示例

```bash
curl "http://127.0.0.1:8000/sse/product/recommend?user_id=user_001&query=推荐几个在欧洲卖得好的电子产品"
```

### 会话接口示例

```bash
curl -X POST "http://127.0.0.1:8000/session/create?user_id=user_001&title=欧洲选品"
curl "http://127.0.0.1:8000/session/list?user_id=user_001"
curl "http://127.0.0.1:8000/session/history?session_id=session_xxx"
```

## 项目结构

```
demo1/
├── main.py              # FastAPI 入口 + SSE 路由
├── core/
│   ├── memory.py        # SQLite 三层记忆管理
│   ├── agentscope_service.py # AgentScope 模型与代理编排
│   └── product_agent.py # 选品智能体核心逻辑
├── mall/
│   ├── mock_api.py      # 模拟商城接口
│   └── models.py        # 商品数据模型
├── models/
│   └── schemas.py       # API 请求/响应模型
├── index.html           # SSE 测试前端页面
└── data/
    └── memory.db        # SQLite 数据库
```

## 记忆架构

```
用户 (user_id)
  └── 会话 (session_id)
        └── 上下文 (context_id)
```

- 支持多用户并发
- 每个用户可有多个会话
- 会话内保存完整对话历史

## 开发

```bash
# 代码格式化
uv run black .

# 运行测试
uv run pytest
```

## 技术栈

- **FastAPI** - Web 框架
- **AgentScope** - Agent 编排、工具调用与记忆协作
- **OpenAI SDK** - 兼容 OpenAI 协议的模型网关访问
- **SQLite + aiosqlite** - 异步数据库
- **SSE** - 服务端推送事件
- **Pydantic** - 数据验证

## License

MIT