Ontology MCP Server Rl Stable Baselines3

🚀 本体强化学习电商智能体

🛍️ 本体强化学习电商智能体（原 “本体MCP服务器”）着重展示了最新的强化学习驱动的闭环系统。该系统仍依赖模型上下文协议（MCP），将本体推理、电子商务业务逻辑、内存管理和Gradio用户界面相结合，让你能够端到端地重现完整的购物助手体验。

🤖 强化学习驱动的智能体：内置Stable Baselines3 PPO训练流程，涵盖从数据→训练→评估→部署的全流程，使智能体能够持续从真实对话记录和工具日志中学习，自动发现更安全、更高效的工具链策略。

🚀 快速开始

选项A：Docker（推荐）

要求

• Docker 20.10 及以上版本
• Docker Compose 2.0 及以上版本
• 8GB 及以上内存
• 20GB 以上磁盘空间

一键启动

# 1. 克隆仓库
git clone <repository-url>
cd ontology-mcp-server-RL-Stable-Baselines3

# 2. 配置环境变量
cp .env.example .env
nano .env  # 填写大语言模型（LLM）的API密钥

# 3. 启动所有服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

# 5. 停止服务
docker-compose down

服务端点

• MCP服务器：http://localhost:8000
• 智能体用户界面：http://localhost:7860
• 训练仪表盘：http://localhost:7861

常用命令

# 重启单个服务
docker-compose restart agent-ui

# 进入容器进行调试
docker exec -it ontology-agent-ui bash

# 检查状态
docker-compose ps

# 清理并重新构建（谨慎使用）
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d

GPU支持（可选）

安装 nvidia-docker，然后取消 docker-compose.yml 中 training-dashboard 下GPU相关块的注释。

distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

选项B：本地开发

1. 环境准备

要求

• Python 3.10 及以上版本
• 推理/演示需要 8GB 及以上内存（强化学习训练需要 32GB 及以上）
• Linux/macOS/WSL2 操作系统
• 可选GPU（建议NVIDIA显卡，显存≥12GB）
• 40GB 以上磁盘空间（用于数据库、Chroma向量和强化学习检查点）

安装依赖

git clone <repository-url>
cd ontology-mcp-server-RL-Stable-Baselines3
python3 -m venv .venv
source .venv/bin/activate  # Windows系统：.venv\Scripts\activate
pip install -e .

2. 初始化数据库

Docker部署会在首次启动时自动执行这些步骤。手动步骤仅适用于本地开发。

export ONTOLOGY_DATA_DIR="$(pwd)/data"
python scripts/init_database.py        # 创建表
python scripts/seed_data.py            # 初始化基础用户/产品数据
python scripts/add_bulk_products.py    # 可选：添加1000多个产品
python scripts/add_bulk_users.py       # 可选：添加200多个用户
python scripts/update_demo_user_names.py --seed 2025

示例用户

用户ID	姓名	邮箱	会员等级	累计消费
1	张三	zhangsan@example.com	普通会员	0元
2	李四	lisi@example.com	VIP会员	6500元
3	王五	wangwu@example.com	SVIP会员	12000元

示例产品

• iPhone 15 Pro Max（9999元）
• iPhone 15 Pro（8999元）
• iPhone 15（5999元）
• AirPods Pro 2（1899元）
• 配件等

3. 配置大语言模型（LLM）

src/agent/config.yaml 支持DeepSeek、OpenAI兼容的API或本地的Ollama：

llm:
  provider: "deepseek"
  api_url: "https://api.deepseek.com/v1"
  api_key: "your-api-key-here"
  model: "deepseek-chat"
  temperature: 0.7
  max_tokens: 2000

或者通过环境变量配置：

export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"

# 本地Ollama（以qwen3:8b为例）
export LLM_PROVIDER="ollama"
export OLLAMA_API_URL="http://localhost:11434/v1"
export OLLAMA_MODEL="qwen3:8b"
export OLLAMA_API_KEY="ollama"  # Ollama会忽略该值

3.1 配置MCP基础URL

训练脚本 (train_rl_agent.py) 和Gradio智能体都通过HTTP调用MCP。如有需要，可以覆盖 MCP_BASE_URL：

# 本地/开发环境
export MCP_BASE_URL="http://127.0.0.1:8000"

# Docker/生产环境（容器间通信）
export MCP_BASE_URL="http://ontology-mcp-server:8000"

4. 启动服务

选项1：使用 start_all.sh 脚本（推荐）

./scripts/start_all.sh
# 默认汇总到 logs/server.log（按日轮转），若想恢复各脚本独立日志，运行前导出 DISABLE_SCRIPT_LOG_FILES=0
tail -f logs/server.log

停止所有服务：

./scripts/stop_all.sh

选项2：分别启动

./scripts/run_server.sh
./scripts/run_agent.sh
./scripts/run_training_dashboard.sh
./scripts/run_tensorboard.sh

选项3：手动命令启动

# 终端1：启动MCP服务器（FastAPI）
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
uvicorn ontology_mcp_server.server:app --host 0.0.0.0 --port 8000

# 终端2：启动Gradio用户界面
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://127.0.0.1:8000"
python -m agent.gradio_ui

# 终端3：启动强化学习训练仪表盘
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://127.0.0.1:8000"
python scripts/run_training_dashboard.py

# 终端4：启动TensorBoard
source .venv/bin/activate
tensorboard --logdir data/rl_training/logs/tensorboard --host 0.0.0.0 --port 6006

若要更改Gradio的绑定地址/端口，请在启动前设置 GRADIO_SERVER_NAME 和 GRADIO_SERVER_PORT。run_agent.sh / run_training_dashboard.sh 接受 AGENT_HOST/PORT 和 TRAINING_DASHBOARD_HOST/PORT 参数，它们会将这些值传递给Gradio的环境变量，以保持端口7860/7861独立。

5. 访问用户界面

访问 http://127.0.0.1:7860。

界面标签页：

• 💬 计划：聊天输入框、AI回复、推理计划、实时状态
• 🔧 工具调用：工具名称/参数、时间戳、调用结果、错误信息
• 🧠 记忆：对话历史列表、摘要、检索控制、会话管理
• 🛍️ 电商分析：质量指标、意图分析、对话状态、推荐引擎
• 📋 执行日志：完整的大语言模型输入/输出和工具调用跟踪信息

记忆流程（Mermaid图）

flowchart LR
  subgraph Ingest[摄入与存储]
    direction TB
    U(用户输入)
    U --> AT(ChromaMemory.add_turn)
    AT --> SUM(生成摘要)
    SUM --> DB((ChromaDB集合))
    AT --> DB
  end

  subgraph Extract[提取]
    direction TB
    AT --> EX(用户上下文提取器)
    EX --> UM(用户上下文管理器)
  end

  subgraph Retrieval[检索与注入]
    direction TB
    UM --> CTX(为提示获取上下文)
    CTX --> NOTE_CTX(注入上下文和历史记录)
    NOTE_CTX --> AGT(智能体/大语言模型)
  end

  AGT --> TC(工具调用)
  TC --> AT
  TC -->|创建订单生成ORD...| UM

6. 示例对话

用户：你好
AI：你好！欢迎光临...（意图：问候）

用户：推荐一款手机？
AI：[commerce.search_products] 返回4款iPhone型号...

用户：iPhone 15 Pro Max有货吗？
AI：[commerce.check_stock] 有货，库存50台...

用户：加入购物车
AI：[commerce.add_to_cart] 已添加...（状态：浏览 → 购物车）

7. 交互序列图

完整对话的日志驱动分段（推荐 → 多轮搜索 → 结账 → 售后 → 分析）记录在 中。每个部分都包含一个Mermaid序列图和一个PNG快照，方便你将原始日志、工具调用和用户界面状态对应起来。

8. 可选的强化学习循环

• 使用 scripts/generate_dialogue_corpus.py 生成最新的200个完全真实的场景
• 运行 python test_rl_modules.py 对强化学习模块进行基本检查
• 执行 python train_rl_agent.py --timesteps ... 启动PPO训练
• 详细信息见下文 🧠 强化学习（阶段6）

🔧 MCP服务器API

MCP服务器提供HTTP端点。

健康检查

curl http://localhost:8000/health

功能列表

curl http://localhost:8000/capabilities

调用工具

curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "commerce.search_products",
    "params": {
      "available_only": true,
      "limit": 5
    }
  }'

21个工具

本体工具（3个）

1. ontology.explain_discount
2. ontology.normalize_product
3. ontology.validate_order

电商工具（18个） 4. commerce.search_products 5. commerce.get_product_detail 6. commerce.check_stock 7. commerce.get_product_recommendations 8. commerce.get_product_reviews 9. commerce.add_to_cart 10. commerce.view_cart 11. commerce.remove_from_cart 12. commerce.create_order 13. commerce.get_order_detail 14. commerce.cancel_order 15. commerce.get_user_orders 16. commerce.process_payment 17. commerce.track_shipment 18. commerce.get_shipment_status 19. commerce.create_support_ticket 20. commerce.process_return 21. commerce.get_user_profile

🧠 智能体架构

核心组件

1. ReAct智能体 (react_agent.py)

   • 基于LangChain的ReAct工作流（推理 + 行动）
   • 自动工具选择和推理跟踪
   • 支持多轮对话感知

2. 对话状态 (conversation_state.py)

   • 8个阶段：问候 → 浏览 → 选择 → 购物车 → 结账 → 跟踪 → 服务 → 空闲
   • 跟踪VIP状态、购物车状态、浏览历史
   • 根据关键词和工具使用情况自动检测状态转换

3. 系统提示 (prompts.py)

   • 电商角色设定：专业、友好的购物顾问
   • 生成中文提示时使用礼貌的“您”语气，避免使用系统术语
   • 确认有风险的操作（付款、取消订单）
   • 鼓励提出澄清问题，而非直接拒绝

4. 对话记忆 (chroma_memory.py)

   • 后端：ChromaDB
   • 检索模式：最近、相似度、混合
   • 自动总结每一轮对话
   • 持久化存储在 data/chroma_memory/

5. 质量跟踪 (quality_metrics.py)

   • 对话质量评分（0 - 1）
   • 用户满意度估计
   • 工具效率和延迟跟踪

6. 意图跟踪器 (intent_tracker.py)

   • 14种意图（问候、搜索、查看购物车、结账、跟踪订单等）
   • 置信度分数和历史记录

7. 推荐引擎 (recommendation_engine.py)

   • 个性化产品推荐
   • 使用浏览/购物车历史和会员等级信息

🧠 强化学习（阶段6）

硬件提示：PPO训练建议使用≥8核CPU、≥32GB内存和≥1块显存≥12GB的GPU（如RTX 3080/4090/A6000）。仅使用CPU也可以进行训练，但100K步可能需要5 - 8小时，而使用GPU则可将时间缩短至约1小时。请为 data/rl_training/ 预留≥15GB的磁盘空间。

目标与优势

• 让ReAct智能体通过Stable Baselines3 PPO实现自我提升
• 将用户上下文/意图/工具使用/产品信息编码为128维状态向量
• 多目标奖励机制（任务成功、效率、满意度、安全性）
• Gymnasium环境复用LangChain智能体，无需重新实现业务逻辑

模块概述 (src/agent/rl_agent/)

文件	角色	说明
state_extractor.py	将多源对话编码为128维向量	处理嵌入/简单特征，兼容字符串/对象意图
reward_calculator.py	多目标奖励计算	任务/效率/满意度/安全性 + 回合汇总
gym_env.py	EcommerceGymEnv	22个离散动作（21个工具 + 直接回复）
ppo_trainer.py	训练编排	DummyVecEnv + 评估/检查点回调 + TensorBoard
train_rl_agent.py	命令行入口	可配置训练步数、评估频率、检查点、嵌入方式

场景语料库 data/training_scenarios/sample_dialogues.json 包含200个真实对话，涉及5种场景类别下的真实用户/订单/产品。

闭环流程：数据 → 训练 → 应用

1. 数据阶段

   • 确保数据库已填充数据：运行 add_bulk_products.py、add_bulk_users.py、update_demo_user_names.py --seed 2025
   • 生成200个真实场景：执行 python scripts/generate_dialogue_corpus.py
   • 可选的验证代码片段（类别计数）见README.zh.md

2. 训练

source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://localhost:8000"
export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"
export TRAIN_DEVICE="gpu"  # 若GPU不可用，可回退到CPU
python test_rl_modules.py
python train_rl_agent.py \
  --timesteps 100000 \
  --eval-freq 2000 \
  --checkpoint-freq 20000 \
  --output-dir data/rl_training \
  --max-steps-per-episode 12 \
  --scenario-file data/training_scenarios/sample_dialogues.json \
  --device "${TRAIN_DEVICE:-gpu}"

训练日志会输出到 data/rl_training/logs/tensorboard/。

3. 评估与产物

• 最佳模型：data/rl_training/best_model/best_model.zip
• 最终模型：data/rl_training/models/ppo_ecommerce_final.zip
• 检查点：data/rl_training/checkpoints/ppo_ecommerce_step_*.zip
• 回合统计信息：data/rl_training/logs/training_log.json

4. 部署

python - <<'PY'
from agent.react_agent import LangChainAgent
from agent.rl_agent.ppo_trainer import PPOTrainer

agent = LangChainAgent(max_iterations=6)
trainer = PPOTrainer(agent, output_dir="data/rl_training")
trainer.create_env(max_steps_per_episode=10)
trainer.load_model("data/rl_training/best_model/best_model.zip")

query = "我需要十部华为旗舰手机，预算约7000元"
action_idx, action_name, _ = trainer.predict(query)
print("强化学习建议的动作:", action_idx, action_name)

result = agent.run(query)
print(result["最终答案"])
PY

强化学习仪表盘（Gradio）

src/training_dashboard/ 提供了一个独立的控制台，支持语料库聚合、训练编排、指标可视化、模型管理和热重载：

1. 将 config/training_dashboard.example.yaml 复制为 config/training_dashboard.yaml 并调整路径
2. 运行 PYTHONPATH=src python scripts/run_training_dashboard.py 启动仪表盘
3. 标签页：概述（实时状态、奖励/长度曲线、日志）、语料库管理（静态/日志混合）、训练控制、模型管理

奖励分解

• R_task：成功下单奖励10分；缺少关键信息或回复为空则扣分
• R_efficiency：工具调用次数少且延迟低则奖励；调用次数过多则惩罚
• R_satisfaction：使用实时质量评分奖励主动引导行为
• R_safety：初始值为+1；SHACL验证失败或使用不安全工具最多扣10分

调优提示

• 若资源允许，启用 --use-text-embedding 以获得更丰富的状态表示
• 调整 PPOTrainer 中的 reward_weights 以平衡任务成功和安全性
• max_steps_per_episode：短回合用于频繁评估；长回合用于完整购物流程

🏗️ 本体与架构

本体语义模型

系统定义了 12个核心业务实体，并明确了它们之间的关系和属性：

核心交易实体

1. 用户

   • 属性：用户ID、用户名、邮箱、电话、用户等级（普通会员/VIP会员/SVIP会员）、累计消费、信用评分
   • 操作：查询用户信息、用户认证
   • 关系：创建订单、拥有购物车商品、发起支持工单

2. 产品

   • 属性：产品ID、产品名称、类别、品牌、型号、价格、库存数量、规格
   • 操作：搜索产品、获取产品详情、检查库存、获取推荐、获取评价
   • 关系：被购物车商品、订单商品和评价引用

3. 购物车商品

   • 属性：购物车ID、用户ID、产品ID、数量、添加时间
   • 操作：添加到购物车、查看购物车、从购物车移除
   • 关系：关联用户和产品

4. 订单

   • 属性：订单ID、订单编号、总金额、折扣金额、最终金额、订单状态、支付状态
   • 操作：创建订单、获取订单详情、取消订单、获取用户订单
   • 关系：包含订单商品，生成支付和物流记录
   • 本体推理：折扣金额根据用户等级、订单金额和首单状态由本体规则计算得出

5. 订单商品

   • 属性：商品ID、订单ID、产品ID、产品名称、数量、单价、小计
   • 关系：订单包含多个订单商品，每个订单商品引用一个产品

6. 支付

   • 属性：支付ID、订单ID、支付方式、支付金额、支付状态、交易ID、支付时间
   • 操作：处理支付
   • 关系：由订单生成
   • 注意：交易ID作为支付凭证

7. 物流

   • 属性：物流ID、订单ID、物流单号、承运商、当前状态、当前位置、预计送达时间
   • 操作：跟踪物流、获取物流状态
   • 关系：由订单生成，记录物流轨迹

8. 物流轨迹

   • 属性：轨迹ID、物流ID、状态、位置、描述、记录时间
   • 关系：多个轨迹属于一个物流记录

客户服务与售后实体

9. 支持工单

   • 属性：工单ID、工单编号、用户ID、订单ID、类别、优先级、状态、主题、描述
   • 操作：创建支持工单
   • 关系：用户为订单创建，包含支持消息

10. 支持消息

    • 属性：消息ID、工单ID、发送者类型、发送者ID、消息内容、发送时间
    • 关系：多个消息属于一个支持工单

11. 退货

    • 属性：退货ID、退货编号、订单ID、用户ID、退货类型（退货/换货）、原因、状态、退款金额
    • 操作：处理退货
    • 关系：由订单发起

12. 评价

    • 属性：评价ID、产品ID、用户ID、订单ID、评分（1 - 5星）、内容、图片
    • 操作：获取产品评价
    • 关系：用户对产品进行评价

架构图

实体关系：

• 用户 → 订单 → 订单商品 → 产品
• 订单 → 购物车商品 → 产品
• 订单 → 支付（支付金额、支付方式、交易ID）
• 订单 → 物流 → 物流轨迹（位置、时间）
• 用户/订单 → 支持工单 → 支持消息
• 订单 → 退货（退货编号、退货类型、退款金额）
• 产品 → 评价（评分、内容）

本体推理：

• 折扣规则：VIP/SVIP会员折扣、批量折扣（≥5000/≥10000）、首单折扣
• 物流规则：满500元免运费（或VIP/SVIP会员）、SVIP会员次日达、偏远地区附加费
• 退货政策：普通会员7天无理由退货、VIP/SVIP会员15天无理由退货、特定类别商品规则

MCP工具层：21个工具通过本体推理对12个实体进行操作 ReAct智能体：调用工具，通过强化学习（PPO模型、奖励系统）进行优化

🎯 本体规则覆盖情况

ontology_rules.ttl 中的规则在 ecommerce_ontology.py 中实现了100%覆盖。

用户等级规则（2条）

规则	触发条件	方法
VIP升级规则	累计消费 ≥ 5000元	infer_user_level()
SVIP升级规则	累计消费 ≥ 10000元	infer_user_level()

折扣规则（5条）

规则	触发条件	折扣	方法
VIP折扣规则	VIP用户	95折	infer_discount()
SVIP折扣规则	SVIP用户	9折	infer_discount()
5000元批量折扣规则	订单金额 ≥ 5000元	95折	infer_discount()
10000元批量折扣规则	订单金额 ≥ 10000元	9折	infer_discount()
首单折扣规则	首次购买用户	98折	infer_discount()

会员折扣和批量折扣不叠加，取最优折扣。

物流规则（5条）

规则	触发条件	物流费用	方法
满500元免运费规则	订单金额 ≥ 500元	0元标准运费	infer_shipping()
VIP/SVIP免运费规则	VIP/SVIP会员	0元标准运费	infer_shipping()
SVIP次日达规则	SVIP会员	0元次日达运费	infer_shipping()
普通会员不满500元标准运费规则	普通会员订单金额 < 500元	15元标准运费	infer_shipping()
偏远地区附加费规则	偏远地址	加收30元	infer_shipping()

退货/换货规则（5条）

规则	适用范围	退货期限	额外条件
普通会员7天无理由退货规则	普通用户	7天	无需理由
VIP/SVIP会员15天无理由退货规则	VIP/SVIP会员	15天	无需理由
电子产品退货规则	电子产品	按会员等级	设备未开封
配件退货规则	配件	按会员等级	包装完好
服务类商品不退货规则	服务类商品	不适用	不可退货

组合策略（2条）

策略	场景	行为
折扣叠加策略	存在多个折扣	选择最优折扣
物流优先级策略	存在多种物流选项	应用优先级最高的选项

SHACL验证

commerce_service.py 在创建订单前调用SHACL验证，以确保数据完整性，并记录主要违规信息和三元组数量。

📊 Gradio用户界面功能

• 💬 计划：输入框、AI回复、推理计划、实时状态
• 🔧 工具调用：工具名称/参数、时间戳、调用结果、错误信息
• 🧠 记忆：历史记录列表、摘要、检索控制、会话管理
• 🛍️ 电商分析：质量指标、意图分析、对话状态、推荐引擎
• 📋 执行日志：完整的大语言模型输入/输出和工具调用跟踪信息

📚 文档

• 阶段3完成报告
• 阶段4完成报告
• 记忆指南
• 记忆配置指南
• 执行日志指南
• Gradio用户界面指南
• 智能体使用指南

🧪 测试

source .venv/bin/activate
python test_memory_quick.py
python test_execution_log.py
python test_phase4_shopping.py
python test_phase4_advanced.py
python test_gradio_ecommerce.py
python test_rl_modules.py

pytest tests/
pytest tests/test_services.py
pytest tests/test_commerce_service.py
python train_rl_agent.py --timesteps 20000 --eval-freq 2000 --checkpoint-freq 5000

⚙️ 配置

环境变量

MCP / 数据根目录

export ONTOLOGY_DATA_DIR="$(pwd)/data"
export APP_HOST=0.0.0.0
export APP_PORT=8000

本体开关（config.yaml）

ontology:
   use_owlready2: true  # 默认启用，可通过 config.yaml 修改

如需在运行时临时关闭，可设置 ONTOLOGY_USE_OWLREADY2=false 环境变量覆盖上述配置。

智能体与大语言模型（LLM）

export MCP_BASE_URL="http://127.0.0.1:8000"
export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"
export LLM_PROVIDER="deepseek"

Gradio服务

export GRADIO_SERVER_NAME=0.0.0.0
export GRADIO_SERVER_PORT=7860
export AGENT_HOST=0.0.0.0
export AGENT_PORT=7860
export TRAINING_DASHBOARD_HOST=0.0.0.0
export TRAINING_DASHBOARD_PORT=7861
export LOG_DIR="$(pwd)/logs"
export TB_LOG_DIR="$(pwd)/data/rl_training/logs/tensorboard"
export TB_HOST=0.0.0.0
export TB_PORT=6006

# 统一日志输出
export ONTOLOGY_SERVER_LOG_DIR="$(pwd)/logs"   # 默认也是 repo/logs
# 设为 0 可恢复各 run_*.sh 生成单独 log 文件
export DISABLE_SCRIPT_LOG_FILES=1

强化学习辅助配置

export TRAIN_DEVICE=gpu
export RL_OUTPUT_DIR="$(pwd)/data/rl_training"

记忆管理

export MEMORY_ENABLED=true
export MEMORY_BACKEND=chromadb
export CHROMA_PERSIST_DIR="data/chroma_memory"
export MEMORY_RETRIEVAL_MODE=recent
export MEMORY_MAX_TURNS=10

config.yaml 示例

完整配置选项见 src/agent/config.yaml（支持DeepSeek/Ollama、记忆管理、智能体开关）。

🗄️ 数据库架构

SQLite数据库 data/ecommerce.db 包含12个表：

• users、products、cart_items、orders、order_items
• payments、shipments、shipment_tracks
• support_tickets、support_messages、returns、reviews

🎯 使用场景

1. 搜索与推荐：commerce.search_products 结合推荐引擎
2. 完整购买流程：浏览 → 选择 → 购物车 → 结账 → 支付 → 跟踪
3. 订单管理：commerce.get_user_orders、取消/退货流程
4. 本体推理：ontology.explain_discount 用于上下文相关的折扣解释

🤝 贡献代码

1. Fork本项目
2. 创建新分支：git checkout -b feature/AmazingFeature
3. 提交代码：git commit -m 'Add some AmazingFeature'
4. 推送分支：git push origin feature/AmazingFeature
5. 打开Pull Request

🏷️ 版本亮点

v1.5.3 (2025-12-01) — 确认记忆与完整工具跟踪

• 确认模式持久化：用户批准关键工具（创建订单/支付）后，运行过程会将清理后的参数和观察结果写回 tool_log、记忆和对话状态，使下一回合能看到已完成的订单，避免再次进入结账流程
• 验证防护硬停止：ontology_validate_order 被标记为关键工具，提醒信息会阻止最终回复，直到SHACL验证完成，订单确认后智能体现在会主动提示用户继续支付
• 端到端工具透明度：流式事件会传输完整的观察负载，Gradio用户界面不再截断JSON数据，大大方便了审计和调试
• 新领域报告：新增 文档，记录与记忆相关的经验教训（包含英文和中文索引），帮助未来贡献者避免回归问题

v1.5.2 (2025-11-29) — 流式跟踪基线 ✅

• 真正的流式管道：react_agent.py 现在提供基于生成器的 run_stream 方法，DeepSeek适配器发出令牌增量，Gradio用户界面逐令牌渲染思考过程和最终答案（提交记录：505b39e → 7c99e84 → aab0956）
• 搜索准确性提升：可配置的多策略意图跟踪器、基于大语言模型的查询重写器、FTS5全文索引 + 混合回退策略（FTS5 → LIKE → 类别）显著提高了通用查询（如 “电子产品”）的准确性
• 可追溯性工具： 使用Mermaid图和PNG证据记录每个对话回合（推荐 → 多轮搜索 → 结账 → 售后 → 分析），两个README文件现在都指向该文档。标签 v1.5.2 标志着下游强化学习实验的新基线

v1.5.1 (2025-11-23)

• 内联图表（Markdown + Base64 PNG），包含意图/用户上下文元数据和 _filter_charts_by_intent() 隐私保护功能
• analytics_service.py 提供五个图表数据端点和 analytics_get_chart_data MCP工具（第22个功能）
• 依赖对齐：plotly>=6.1.0,<7.0.0、kaleido==0.2.1；诊断脚本（verify_chart_fix.py、test_chart_feature.py）和数据/日志备份
• 训练仪表盘用户体验改进：点击预览语料库、同步JSON视图、多实例调试的主机/端口日志

v1.2.3 (2025-11-15) — 重命名与致谢

• 项目更名为 本体强化学习电商智能体；记录强化学习相关上下文
• 新增对Stable Baselines3/Gymnasium/TensorBoard等的致谢
• 工具改进：订单ID验证，避免 OverflowError；支持Ollama的 qwen3:8b 模型

v1.2.2 (2025-11-12) — README强化学习指南

• 在README开头添加了强化学习闭环描述，强调数据 → 训练 → TensorBoard → 部署流程

v1.2.0 (2025-11-11) — 动态用户上下文系统

• 自动提取用户ID、电话号码、地址、订单ID、产品ID
• 提示注入确保对话连续性；正则表达式引擎处理多语言/多宽度变体
• 基于集合的去重，严格的 ORD... 验证，产品ID范围保护
• 测试：tests/test_user_context.py

v1.2.1 (2025-11-11) — 近期订单跟踪热修复

• create_order 现在强制解析有效 ORD... ID的观察/输入，调用 set_recent_order()

v1.1.0 (2025-11-10) — Gradio用户界面增强

• 十个快速测试按钮（本体和SHACL操作）
• 流式响应、主动按钮状态管理、生成器修复

v1.0.0 (2025-11-08) — 订单验证基线

• 订单创建前自动进行SHACL验证；详细的违规日志记录
• 提示改进和100%规则覆盖（折扣/物流/退货/组合）

基础版本 (2025-10)

• 完成阶段1 - 5：ORM、本体、21个工具、ReAct智能体、Gradio用户界面

📦 版本历史

版本	日期	亮点	下载
v1.5.3	2025-12-01	确认模式持久化、验证防护硬停止、完整工具负载流式传输、新的记忆经验教训文章	git checkout v1.5.3
v1.5.2	2025-11-29	流式生成器管道、意图/查询/搜索升级、日志驱动的图表 + 基线标签	git checkout v1.5.2
v1.5.1	2025-11-23	内联图表流式传输、分析MCP工具、仪表盘用户体验升级	git checkout v1.5.1
v1.5.0	2025-11-20	强化学习闭环、Docker/Compose打包、5标签Gradio用户界面	git checkout v1.5.0
v1.0.0	2025-10	阶段1 - 3基线（本体 + 工具 + 智能体）	git checkout v1.0.0

📝 更新日志

2025-12-01

• 确认循环持久化：确认分支现在将每个执行的工具（参数 + 观察结果）推回 tool_log、记忆和 ConversationState，使后续回合能立即看到已完成的订单，而无需重新运行结账流程
• 强制SHACL验证：ontology_validate_order 加入 CRITICAL_TOOLS 列表，提醒信息会阻止最终回复，直到验证完成；订单确认后，智能体主动询问是否继续支付
• 聊天中显示完整工具输出：流式事件现在包含完整的JSON观察结果，Gradio用户界面不再截断长负载，使审计和调试变得简单
• 新的经验教训文档：发布 docs/articles/12-memory-intent-lessons.md，记录使用记忆进行意图检测和推理的实际注意事项

2025-11-30

• 本体优先推理覆盖：ecommerce_ontology.py 现在优先加载 ontology_rules.ttl 用于折扣、物流、退货、取消四大流程，命中规则时返回 rule_applied，无匹配才退回静态策略；对应 tests/test_commerce_service.py、tests/test_services.py 已通过全量pytest
• 日志统一与按日轮转：所有Python模块写入 logs/server.log（日切 + server_YYYYMMDD.log 归档），start_all.sh 默认设置 DISABLE_SCRIPT_LOG_FILES=1 防止重复日志，如需旧行为可手动置0；新增 ONTOLOGY_SERVER_LOG_DIR/ONTOLOGY_LOG_BACKUP_COUNT 控制输出目录与留存天数
• 本体资产清理：ontology_commerce.ttl 和 ontology_ecommerce.ttl 补齐SWRL前缀、变量、折扣实体与规则，使Owlready2/外部引擎读取更稳定；README/配置章节同步记录新的日志变量与使用方式

2025-11-29

• 真正的流式循环：react_agent.py 现在提供基于生成器的 run_stream 方法，DeepSeek适配器发出令牌增量，Gradio用户界面逐令牌渲染思考过程和最终答案，实现透明的推理回放
• 意图 + 检索栈：可配置的多策略意图跟踪器、基于大语言模型的 query_rewriter.py 以及 commerce_service.py/db_service.py 中的FTS5→LIKE→类别回退策略，在保留小众意图召回率的同时，大大提高了通用查询（如 “电子产品”）的准确性
• 可追溯文档： 使用Mermaid图和PNG证据记录五个基于日志的序列，README文件链接到该文档，标签 v1.5.2 标志着版本历史表中的新基线

详细的中文更新日志见 README.zh.md（与英文亮点对应）。

🙏 致谢

• LangChain & FastAPI – ReAct智能体编排 + MCP服务器
• Gradio – 五标签电商用户界面框架
• ChromaDB & SQLite – 语义记忆 + 电商数据存储
• Stable Baselines3 / Gymnasium / TensorBoard – 强化学习训练与可视化
• DeepSeek – 大语言模型提供商
• RDFLib & PySHACL – 本体推理 + SHACL验证
• SQLAlchemy – ORM基础

🧩 案例研究

• 场景：预算20万元的VIP买家要求智能体 “花光预算” 购买最贵的手机，涵盖洞察 → 推荐 → 购物车 → 支付 → 售后跟踪
• 亮点：16步记忆链、22个MCP工具（6次本体调用、2次SHACL检查）、动态图表、自动VIP折扣、购物车 + 结账编排
• 完整流程：

📖 引用

@software{ontology_rl_commerce_agent_2025,
  author  = {Shark8848},
  title   = {Ontology RL Commerce Agent},
  year    = {2025},
  url     = {https://github.com/shark8848/ontology-mcp-server-RL-Stable-Baselines3},
  version = {v1.2.3}
}

📄 许可证

本项目采用 MIT许可证 发布。简体中文参考翻译见 LICENSE.zh.md。

📧 联系我们

作者：shark8848@gmail.com — 如果本项目对你有帮助，请给仓库点个星！