assistant/CLAUDE.md

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)

# 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）
• 向量搜索: 使用语义搜索找到最相关的文档片段

配置方式

本项目配置命令

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
2. 创建新项目或选择现有项目
3. 导航至 "Context7" 标签
4. 复制 API 密钥（格式：ctx7sk-<uuid>）

可用工具

1. get-documentation-context

获取文档上下文（主要工具）

参数:

{
  "library_id": "react",           // 库 ID (必填)
  "query": "如何使用 useEffect",    // 查询问题 (必填)
  "version": "19.0.0"              // 指定版本 (可选)
}

2. get-docs

获取库的完整文档列表

参数:

{
  "library_id": "nextjs",
  "version": "15.0.0"
}

3. resolve-library-id

从库名称/URL 获取标准化的 library_id

参数:

{
  "identifier": "react"  // 或 GitHub URL、npm 包名等
}

返回:

{
  "library_id": "react",
  "available_versions": ["18.3.1", "19.0.0", "19.1.0"]
}

4. search-code

在文档中搜索代码示例

参数:

{
  "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 仓库
• Context7 API 文档
• Upstash Console

---

最近修改历史

2026-01-20 - Form 格式订单详情

修改文件: agent/integrations/chatwoot.py

修改内容:

• 新增 send_order_form() 方法，使用 content_type="form" 展示订单详情
• 支持字段类型：text, text_area, select
• 订单字段映射：订单号、状态、下单时间、商品列表、总金额、运费、物流信息、备注

API 参考:

• Create New Message - Chatwoot API
• Interactive Messages - Chatwoot User Guide

数据结构:

{
  "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

示例:

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 文件

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 超时导致镜像拉取失败

解决方案: 添加中国镜像源

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.1panel.live",
    "https://dockerhub.icu"
  ]
}

---

常见操作

启动服务

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

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f agent

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

环境变量生效

# 修改 .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 提交

# 查看状态
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 文档
• FastMCP 文档
• Chatwoot API 文档
• 智谱 AI API 文档

Context7 相关

• Context7 GitHub 仓库
• Context7 API 文档
• Upstash Console
• Context7 MCP 教程

外部参考

• 热门 MCP Server 详解 - 火山引擎
• Context7 MCP 为 Cursor 提供实时文档上下文 - 知乎
• Context7 MCP Server 介绍 - 二师兄的博客
• AI 编程焕新：用 Context7 - 腾讯云

---

最后更新: 2026-01-20 维护者: Claude Code