覓珍（MiZhen，取"寻覓珍選"之意）是一个基于 Agno 框架的多 Agent 商品智能选品系统。用户用自然语言描述选品需求（如"推荐一些春节送礼的商品，预算 300 元以内"），系统通过 维度确认 → 商品查询 → 结果汇总 的流程，返回符合条件的商品列表（SKU）。
用户
│
▼
┌─────────────────────────────────────────┐
│ Team Leader（qwen-plus） │
│ 职责：需求分析、维度梳理、用户确认、任务委托 │
│ 工具：think（推理）、search_knowledge_base │
│ （知识库）、send_sku_list（历史过滤） │
└──────────────┬──────────────────────────┘
│ delegate_task_to_member
▼
┌─────────────────────────────────────────┐
│ 数据查询专家（qwen-flash） │
│ 职责：执行商品查询、结果评估、SKU 输出 │
│ 工具：think/analyze（推理）、search_goods │
│ （商品查询）、send_sku_list（SKU 输出）│
└──────────────┬──────────────────────────┘
│
┌──────────┼──────────────┐
▼ ▼ ▼
MySQL Milvus（可选） LLM API
商品数据表 知识库向量检索 （DashScope）
- 意图识别：Team Leader 判断是新查询还是"基于历史结果过滤"
- 维度梳理：拆解需求为品类（必须细化到具体小类）、品牌、价格区间等，结合知识库检索补充信息
- 用户确认：展示维度方案，支持多轮迭代（新增条件 → 重新梳理 → 再确认），直到用户明确确认
- 委托查询：将维度 JSON 委托给数据查询专家
- 执行查询：数据查询专家按品类分别调用
search_goods，用analyze评估结果，符合要求立即调用send_sku_list输出 SKU（JSON 格式） - 结果汇总：Team Leader 以 Markdown 表格汇总（品类、数量、价格范围、主要品牌），并分析与用户意图的关联
- 双模型策略：Leader 用 qwen-plus（强推理），Worker 用 qwen-flash（低成本），平衡效果与成本
- 长期记忆：通过
MemoryManager自动提取用户偏好（场景、行业、价格、品类、品牌等维度），注入后续对话上下文 - 会话持久化：对话会话存储在 MySQL，支持多轮对话和上下文恢复
- SKU 流式输出：
send_sku_list以 JSON 格式输出商品 ID 列表，前端可从事件流中解析
smart_product_selection/
├── smart_product_selection_team.py # 主入口：Team/Agent 创建与启动
├── requirements.txt # Python 依赖
├── config/
│ └── config.example.json # 配置模板（复制为 config.json 后填写）
├── core/
│ └── config_loader.py # 配置加载器（支持环境变量覆盖）
├── tools/
│ ├── goods_selection_tool.py # 商品明细表查询工具（search_goods）
│ ├── sku_sender_tool.py # SKU 处理工具（send_sku_list）
│ ├── knowledge_retrieval_tool.py # 知识库检索工具（可选，依赖 Milvus）
│ └── milvus_tools.py # Milvus 向量检索封装
├── prompts/
│ ├── agent_instructions.py # Team Leader / 数据查询专家 指令
│ ├── reasoning_instructions.py # 推理工具（think/analyze）指令
│ └── memory_instructions.py # 用户记忆提取指令
├── scripts/
│ ├── init_goods_db.py # 商品数据表初始化（建表 + 示例数据）
│ └── build_knowledge_base.py # 知识库构建（选品知识向量化灌入 Milvus，可选）
├── utils/
│ └── logger.py # 日志工具（RotatingFileHandler）
├── docs/
│ └── API_USAGE.md # API 使用文档
└── logs/ # 运行日志目录
# 克隆仓库
git clone https://github.com/Happy-Chen-CH/mizhen.git
cd mizhen
# 建议使用 conda（要求 Python 3.11）
conda create -n smart_product_selection python=3.11
conda activate smart_product_selection
pip install -r requirements.txt注意：项目基于
agno==2.3.13开发，Team/Agent 参数与该版本绑定，升级前请先验证兼容性。
cp config/config.example.json config/config.json编辑 config/config.json，替换所有 YOUR_ 开头的占位符：
| 配置项 | 说明 | 是否必需 |
|---|---|---|
llm.api_key |
DashScope（阿里云百炼）API Key，控制台获取 | ✅ 必需 |
llm.model_name |
Team Leader 模型，默认 qwen-plus |
有默认值 |
llm.worker_model_name |
数据查询专家模型，默认 qwen-flash |
有默认值 |
embedding.api_key |
Embedding API Key（通常与上面相同） | ✅ 必需（用知识库时） |
mysql.host/port/user/password |
MySQL 连接信息（会话 + 记忆库） | ✅ 必需 |
graph_db.host/port/user/password |
商品数据库连接信息（可与 mysql 相同） | ✅ 必需 |
milvus.host/port + collection_name |
Milvus 向量库（知识库检索用） | ⭕ 可选 |
也可以用环境变量代替写进配置文件（优先级更高，推荐用于密钥类配置）：
export DASHSCOPE_API_KEY="sk-xxxx" # LLM + Embedding API Key
export MYSQL_HOST="127.0.0.1"
export MYSQL_PASSWORD="your_password"
export GRAPH_DB_HOST="127.0.0.1"
export GRAPH_DB_PASSWORD="your_password"
export MILVUS_HOST="127.0.0.1" # 可选没有 Milvus？没关系。知识库检索是可选功能，主程序会自动跳过，不影响核心商品查询流程。 没有商品数据？运行
python scripts/init_goods_db.py自动建表并插入示例数据。
python scripts/init_goods_db.py该脚本会在 graph_db 中创建 goods_selection_graph 表并插入 10 条示例商品。如果你有真实商品数据，可以直接往这张表里导数据（字段说明见 docs/API_USAGE.md）。
python smart_product_selection_team.py启动后：
- 🌐 Web 界面（Agno OS）：http://localhost:7778
- 📚 API 文档：http://localhost:7778/docs
- ⚙️ 配置页面：http://localhost:7778/config
- 🔗 对话接口：
POST /teams/smart-product-selection-team/runs
端口可通过环境变量修改：AGENTOS_PORT=7780 python smart_product_selection_team.py
在 Web 界面中尝试：
推荐一些春节送礼的商品，预算 300 元以内
系统会先梳理查询维度并请你确认，确认后执行查询，最后以表格汇总结果。你还可以继续追问：
在刚才的结果中，只保留价格 200 元以下的
- DashScope API Key（必需）：
llm.api_key/embedding.api_key，或环境变量DASHSCOPE_API_KEY - MySQL 数据库（必需）：用于会话和长期记忆持久化，配置段
mysql（数据库不存在时需自行创建：CREATE DATABASE smart_product_selection DEFAULT CHARSET utf8mb4;，会话/记忆表由框架自动创建） - 商品数据库（必需）：配置段
graph_db，需包含goods_selection_graph表（可用scripts/init_goods_db.py初始化） - Milvus 向量库（可选）：配置段
milvus，用于知识库语义检索；不部署则自动降级跳过 - 知识库内容（可选）：如果启用知识库检索，运行
python scripts/build_knowledge_base.py可自动创建 Milvus 集合并灌入内置选品知识向量；也可自行向collection_name指定的集合导入数据（字段：embedding+text，维度 2048，与text-embedding-v4对齐）
Q：启动时报"配置验证失败"？
A：检查 config/config.json 是否还有 YOUR_ 开头的占位符没替换。
Q：知识库工具创建失败？ A：属于可选功能，通常是 Milvus 未部署或集合不存在，不影响核心的商品查询功能。
Q：商品查询返回"未找到符合条件的商品"？
A：确认 goods_selection_graph 表中有数据（python scripts/init_goods_db.py），且品类名称与表中 category 字段能模糊匹配。
Q：端口被占用？
A：AGENTOS_PORT=7780 python smart_product_selection_team.py，或 lsof -i :7778 查找占用进程。
- Agno 2.3.13：多 Agent 编排框架（Team + Agent + AgentOS）
- DashScope：通义千问大模型（qwen-plus / qwen-flash）+ text-embedding-v4
- MySQL：会话与长期记忆持久化、商品数据存储
- Milvus：知识库向量检索（可选）
- FastAPI：AgentOS 底层 HTTP 服务
本项目采用 MIT License 开源。