# B2B Shopping AI Assistant - Claude 开发上下文 > 本文件记录项目架构、技术决策、最近修改历史，便于 Claude Code 继续开发维护 --- ## 项目概览 **项目名称**: B2B Shopping AI Assistant **技术栈**: Python + LangGraph + FastMCP + Chatwoot + Docker **AI 模型**: 智谱 AI GLM-4-Flash **主要功能**: 订单查询、产品咨询、售后服务、FAQ 智能问答 --- ## 服务架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 客户端渠道 │ │ (Website Widget / API / Chatwoot) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Chatwoot (消息平台) │ │ http://localhost:3000 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ LangGraph Agent (AI 代理层) │ │ http://localhost:8000 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Router │ │ Product │ │ Order │ │ Aftersale│ │ │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ MCP Servers (工具服务) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Strapi │ │ Order │ │ Aftersale│ │ Product │ │ │ │ MCP │ │ MCP │ │ MCP │ │ MCP │ │ │ │ :8001 │ │ :8002 │ │ :8003 │ │ :8004 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 后端服务 (Hyperf PHP) │ │ https://api.qa1.gaia888.com │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Orders │ │ Products │ │ Aftersales│ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 目录结构 ``` ai/ ├── agent/ # AI Agent 主服务 │ ├── agents/ # 各业务 Agent 实现 │ │ ├── router.py # 路由 Agent（意图识别） │ │ ├── customer_service.py # 客服 Agent（FAQ、公司信息） │ │ ├── order.py # 订单 Agent │ │ ├── product.py # 产品 Agent │ │ └── aftersale.py # 售后 Agent │ ├── core/ # 核心框架 │ │ ├── state.py # AgentState 状态管理 │ │ ├── graph.py # LangGraph 工作流 │ │ ├── llm.py # LLM 客户端（智谱 AI） │ │ └── language_detector.py # 多语言检测 │ ├── integrations/ # 第三方集成 │ │ ├── chatwoot.py # Chatwoot API 客户端 │ │ └── hyperf_client.py # Hyperf API 客户端 │ ├── prompts/ # 提示词模板 │ ├── utils/ # 工具函数 │ │ ├── logger.py # 日志工具 │ │ ├── faq_library.py # 本地 FAQ 库（仅社交问候） │ │ ├── response_cache.py # Redis 响应缓存 │ │ ├── cache.py # Redis 缓存客户端 │ │ └── token_manager.py # Token 管理 │ ├── webhooks/ # Webhook 处理 │ │ └── chatwoot_webhook.py # Chatwoot Webhook 接收 │ ├── config.py # 配置管理 │ └── main.py # FastAPI 应用入口 │ ├── mcp_servers/ # MCP 服务集群 │ ├── strapi_mcp/ # 知识库 MCP (端口 8001) │ ├── order_mcp/ # 订单 MCP (端口 8002) │ ├── aftersale_mcp/ # 售后 MCP (端口 8003) │ ├── product_mcp/ # 产品 MCP (端口 8004) │ └── shared/ # 共享模块 │ ├── docker-compose.yml # Docker 编排配置 ├── nginx.conf # Nginx 配置 ├── .env # 环境变量 └── postgres-with-pgvector.Dockerfile # PostgreSQL Dockerfile ``` --- ## 重要配置文件 ### 环境变量 (.env) ```env # AI 模型 ZHIPU_API_KEY=87ecd9d88ef549bc817e1feeba226a3b.hfbTWh4Hhdw8Kulh ZHIPU_MODEL=GLM-4-Flash-250414 ENABLE_REASONING_MODE=false REASONING_MODE_FOR_COMPLEX=true # Redis REDIS_HOST=redis REDIS_PORT=6379 # Chatwoot CHATWOOT_API_URL=http://chatwoot:3000 CHATWOOT_API_TOKEN=fnWaEeAyC1gw1FYQq6YJMWSj CHATWOOT_ACCOUNT_ID=2 CHATWOOT_WEBHOOK_SECRET=b7a12b9c9173718596f02fd912fb59f97891a0e7abb1a5e457b4c8858b2d21b5 # Hyperf API HYPERF_API_URL=https://api.qa1.gaia888.com HYPERF_API_TOKEN= # Mall API MALL_API_URL=https://apicn.qa1.gaia888.com MALL_TENANT_ID=2 MALL_CURRENCY_CODE=EUR MALL_LANGUAGE_ID=1 MALL_SOURCE=us.qa1.gaia888.com ``` ### 服务端口映射 | 服务 | 容器名 | 内部端口 | 外部端口 | 说明 | |------|--------|----------|----------|------| | Agent | ai_agent | 8000 | 8000 | AI 代理服务 | | Chatwoot | ai_chatwoot | 3000 | 3000 | 客服平台 | | Redis | ai_redis | 6379 | - | 缓存/队列 | | PostgreSQL | ai_postgres | 5432 | - | Chatwoot 数据库 | | Nginx | ai_nginx | 80 | 8080 | 文档静态服务 | | Strapi MCP | ai_strapi_mcp | 8001 | 8001 | 知识库服务 | | Order MCP | ai_order_mcp | 8002 | 8002 | 订单服务 | | Aftersale MCP | ai_aftersale_mcp | 8003 | 8003 | 售后服务 | | Product MCP | ai_product_mcp | 8004 | 8004 | 产品服务 | --- ## 关键代码文件 ### 1. Agent 核心流程 **agent/core/graph.py:156-188** - LangGraph 状态图定义 - Agent 路由逻辑 - 条件边和工具调用流程 **agent/core/state.py:16-67** - AgentState 数据结构 - ConversationState 枚举 - 核心状态字段定义 ### 2. Router - 意图识别 **agent/agents/router.py:38-57** - FAQ 快速路径优化（在 LLM 前检查本地 FAQ） - 多语言意图识别 **agent/agents/router.py:73-147** - LLM 意图分类 prompt - 支持意图：customer_service, order, product, aftersale ### 3. Customer Service Agent **agent/agents/customer_service.py:40-64** - Router 级 FAQ 响应复用 - 本地 FAQ 库备份检查 **agent/agents/customer_service.py:72-164** - 多语言分类关键词（8 种语言：en, nl, de, es, fr, it, tr, zh） - 自动查询 FAQ 分类：register, order, payment, shipment, return ### 4. Chatwoot 集成 **agent/integrations/chatwoot.py:228-384** - `send_order_form()` - 使用 content_type="form" 发送订单详情 - `send_order_card()` - 使用 content_type="cards" 发送订单卡片 - `send_rich_message()` - 通用富媒体消息发送 **agent/webhooks/chatwoot_webhook.py** - Webhook 接收处理 - 消息格式转换 - 并发会话管理 ### 5. FAQ 系统 **agent/utils/faq_library.py:15-49** - 本地 FAQ 库（仅包含社交问候：你好、谢谢、再见等） - 业务 FAQ 由 Strapi MCP 处理 - 支持精确匹配和模糊匹配 --- ## Context7 MCP 集成 ### 什么是 Context7？ **Context7 MCP** 是一个为 AI 编码助手和 LLM 提供实时、版本特定的代码文档和示例的服务。它解决了 AI 模型训练数据过时的问题，确保 AI 始终使用最新的官方文档。 **核心功能**： - **实时文档访问**: 从 GitHub 仓库获取最新的官方文档 - **版本特定**: 支持查询特定版本（如 React 19、Next.js 15）的文档 - **多语言支持**: 支持 100+ 主流库（前端、后端、数据库、AI/ML） - **向量搜索**: 使用语义搜索找到最相关的文档片段 ### 配置方式 #### 本项目配置命令 ```bash claude mcp add --transport http context7 https://mcp.context7.com/mcp \ --header "CONTEXT7_API_KEY: ctx7sk-9be917f9-9086-4d85-a3d3-23555aaa2da6" ``` #### API 密钥获取 1. 访问 [Upstash Console](https://console.upstash.com/) 2. 创建新项目或选择现有项目 3. 导航至 "Context7" 标签 4. 复制 API 密钥（格式：`ctx7sk-`） ### 可用工具 #### 1. `get-documentation-context` 获取文档上下文（主要工具） **参数**: ```json { "library_id": "react", // 库 ID (必填) "query": "如何使用 useEffect", // 查询问题 (必填) "version": "19.0.0" // 指定版本 (可选) } ``` #### 2. `get-docs` 获取库的完整文档列表 **参数**: ```json { "library_id": "nextjs", "version": "15.0.0" } ``` #### 3. `resolve-library-id` 从库名称/URL 获取标准化的 library_id **参数**: ```json { "identifier": "react" // 或 GitHub URL、npm 包名等 } ``` **返回**: ```json { "library_id": "react", "available_versions": ["18.3.1", "19.0.0", "19.1.0"] } ``` #### 4. `search-code` 在文档中搜索代码示例 **参数**: ```json { "query": "useEffect cleanup", "libraries": ["react", "nextjs"], "limit": 5 } ``` ### 支持的库（部分） | 类别 | 库 | |------|-----| | 前端框架 | React, Vue, Next.js, Nuxt, Svelte | | 后端框架 | FastAPI, Django, Express, Laravel | | 数据库 | PostgreSQL, MySQL, MongoDB, Redis | | 工具库 | Lodash, Axios, Moment.js | | AI/ML | LangChain, TensorFlow, PyTorch | ### 使用场景 **在开发中使用 Context7**: - 查询 LangGraph 最新 API 文档 - 获取 FastAPI 特定版本的代码示例 - 了解 Docker Compose 最新配置选项 **示例**: ``` 用户: LangGraph 如何定义条件边？ Claude: [调用 get-documentation-context] 根据 LangGraph 官方文档，条件边使用 add_conditional_edges()... ``` ### 相关链接 - [Context7 GitHub 仓库](https://github.com/upstash/context7) - [Context7 API 文档](https://context7.mintlify.app/api-reference/context/get-documentation-context) - [Upstash Console](https://console.upstash.com/) --- ## 最近修改历史 ### 2026-01-20 - Form 格式订单详情 **修改文件**: `agent/integrations/chatwoot.py` **修改内容**: - 新增 `send_order_form()` 方法，使用 `content_type="form"` 展示订单详情 - 支持字段类型：text, text_area, select - 订单字段映射：订单号、状态、下单时间、商品列表、总金额、运费、物流信息、备注 **API 参考**: - [Create New Message - Chatwoot API](https://developers.chatwoot.com/api-reference/messages/create-new-message) - [Interactive Messages - Chatwoot User Guide](https://www.chatwoot.com/hc/user-guide/articles/1677689344-how-to-use-interactive-messages) **数据结构**: ```json { "content": "订单详情", "content_type": "form", "content_attributes": { "items": [ { "name": "order_id", "label": "订单号", "type": "text", "default": "123456789" } ] } } ``` ### 2026-01-20 - 多语言 FAQ 分类支持 **修改文件**: `agent/agents/customer_service.py:72-164` **修改内容**: - 为 5 个业务分类添加 8 种语言关键词（en, nl, de, es, fr, it, tr, zh） - 分类：register, order, payment, shipment, return **示例**: ```python category_keywords = { "register": [ "register", "sign up", "account", # English "注册", "账号", "登录", "密码", # Chinese # ... 其他语言 ] } ``` ### 2026-01-20 - FAQ 架构优化 **修改文件**: - `agent/agents/router.py:38-57` - `agent/utils/faq_library.py:15-49` **问题**: 本地 FAQ 库包含业务相关问答，导致返回硬编码数据而非 Strapi CMS 数据 **解决方案**: 1. 本地 FAQ 库仅保留社交问候（18 个关键词） 2. Router 层添加 FAQ 快速路径检查 3. 业务查询自动调用 Strapi MCP 工具 **本地 FAQ 覆盖范围**: - 问候类：你好、hi、hello、hey - 感谢类：谢谢、thank you、thanks - 再见类：再见、bye、goodbye - 时间问候：早上好、下午好、晚上好、good morning ### 2026-01-20 - Chatwoot PID 文件修复 **修改文件**: `docker-compose.yml:64-68` **问题**: Chatwoot 容器因残留 PID 文件陷入重启循环 **解决方案**: 在启动命令中自动清理 PID 文件 ```yaml chatwoot: command: sh -c "rm -f /app/tmp/pids/server.pid && bundle exec rails s -p 3000 -b 0.0.0.0" ``` ### 2026-01-20 - Docker 镜像拉取优化 **修改文件**: `/etc/docker/daemon.json` **问题**: Docker Hub 超时导致镜像拉取失败 **解决方案**: 添加中国镜像源 ```json { "registry-mirrors": [ "https://docker.m.daocloud.io", "https://docker.1panel.live", "https://dockerhub.icu" ] } ``` --- ## 常见操作 ### 启动服务 ```bash # 启动所有服务 docker-compose up -d # 查看服务状态 docker-compose ps # 查看日志 docker-compose logs -f agent # 重启单个服务 docker-compose restart agent ``` ### 环境变量生效 ```bash # 修改 .env 后，需要重启相关服务 # Agent 服务依赖的环境变量：ZHIPU_*, REDIS_*, CHATWOOT_*, STRAPI_*, HYPERF_* docker-compose restart agent # Chatwoot 服务依赖的环境变量：CHATWOOT_*, POSTGRES_*, REDIS_* docker-compose restart chatwoot chatwoot_worker # MCP 服务依赖的环境变量：HYPERF_*, STRAPI_* docker-compose restart strapi_mcp order_mcp aftersale_mcp product_mcp ``` ### Git 提交 ```bash # 查看状态 git status # 添加文件（排除测试文件） git add agent/integrations/chatwoot.py # 提交 git commit -m "feat: 添加订单详情 form 格式展示支持" # 推送 git push origin main ``` --- ## 技术决策记录 ### 1. 为什么使用 LangGraph？ - **状态图工作流**: 支持 Agent 之间的条件跳转和循环 - **内置检查点**: 支持 conversation history 的持久化 - **可视化调试**: 可以导出 Mermaid 图表查看工作流 ### 2. 为什么使用 MCP (Model Context Protocol)？ - **解耦**: Agent 与业务逻辑分离 - **复用**: MCP 工具可被多个 Agent 共享 - **标准化**: 统一的工具调用接口 ### 3. 为什么 FAQ 分两级？ - **本地 FAQ 库**: 处理社交问候（你好、谢谢等），避免 LLM 调用 - **Strapi MCP**: 处理业务 FAQ（注册、订单等），确保数据一致性 ### 4. 为什么 Router 层检查 FAQ？ - **性能优化**: 跳过 LLM 意图识别，直接返回 - **成本降低**: 减少 LLM API 调用 - **用户体验**: 即时响应常见问候 ### 5. 为什么集成 Context7 MCP？ - **解决文档过时**: AI 模型训练数据截止到 2023 年，无法获取最新 API - **版本特定**: 支持查询特定版本的文档（如 LangGraph 0.3 vs 0.2） - **代码示例**: 提供实际可运行的代码片段，减少 AI 幻觉 - **开发效率**: 减少查文档时间，专注于业务逻辑 --- ## 已知问题 ### 1. Form 类型数据展示 **问题**: Chatwoot 的 form 类型主要用于用户输入，用于只读展示时字段可编辑 **当前方案**: 使用 `default` 属性预填值，用户可以看到但技术上可修改 **未来改进**: - 研究是否支持只读模式 - 或考虑使用 cards + JSON 格式展示结构化数据 ### 2. Token 传递 **问题**: 部分 MCP 工具调用可能未正确传递 Chatwoot conversation ID **当前方案**: 在 AgentState 中维护 conversation_id --- ## 参考文档 ### 项目相关 - [LangGraph 文档](https://langchain-ai.github.io/langgraph/) - [FastMCP 文档](https://github.com/jlowin/fastmcp) - [Chatwoot API 文档](https://developers.chatwoot.com/) - [智谱 AI API 文档](https://open.bigmodel.cn/dev/api) ### Context7 相关 - [Context7 GitHub 仓库](https://github.com/upstash/context7) - [Context7 API 文档](https://context7.mintlify.app/api-reference/context/get-documentation-context) - [Upstash Console](https://console.upstash.com/) - [Context7 MCP 教程](https://dev.to/mehmetakar/context7-mcp-tutorial-3he2) ### 外部参考 - [热门 MCP Server 详解 - 火山引擎](https://www.volcengine.com/docs/86677/2165252) - [Context7 MCP 为 Cursor 提供实时文档上下文 - 知乎](https://zhuanlan.zhihu.com/p/1914959847792804088) - [Context7 MCP Server 介绍 - 二师兄的博客](https://www.cloudesx.com/article/Context7-mcp-server) - [AI 编程焕新：用 Context7 - 腾讯云](https://cloud.tencent.com/developer/article/2528436) --- **最后更新**: 2026-01-20 **维护者**: Claude Code