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)

```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-<uuid>`）

### 可用工具

#### 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