diff --git a/README.md b/README.md
new file mode 100644
index 0000000..77dd3fc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,239 @@
+# B2B Shopping AI Assistant
+
+基于 AI 的 B2B 电商智能客服助手平台，支持订单查询、产品咨询、售后服务等业务场景。
+
+## 功能特性
+
+- **智能对话**: 基于智谱 AI (GLM-4) 的自然语言理解与生成
+- **订单管理**: 查询、修改、取消订单，物流追踪，发票获取
+- **产品服务**: 产品搜索、库存查询、B2B 报价、个性化推荐
+- **售后支持**: 退货、换货、投诉、工单处理
+- **知识库问答**: FAQ 智能问答
+- **多渠道接入**: 通过 Chatwoot 支持多种客服渠道
+
+## 技术架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      客户端渠道                              │
+│  (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)                       │
+│              http://hyperf-api:9501/api/v1                   │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
+│  │ Orders   │ │ Products │ │ Aftersales                   │
+│  └──────────┘ └──────────┘ └──────────┘                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 目录结构
+
+```
+├── agent/                    # AI Agent 主服务
+│   ├── agents/              # 各业务 Agent 实现
+│   ├── core/                # 核心框架
+│   ├── integrations/        # 第三方集成
+│   ├── prompts/             # 提示词模板
+│   ├── utils/               # 工具函数
+│   └── webhooks/            # Webhook 处理
+│
+├── mcp_servers/             # MCP 服务集群
+│   ├── strapi_mcp/         # 知识库 MCP
+│   ├── order_mcp/          # 订单 MCP
+│   ├── aftersale_mcp/      # 售后 MCP
+│   ├── product_mcp/        # 产品 MCP
+│   └── shared/             # 共享模块
+│
+├── hyperf_api/              # Hyperf PHP 后端
+│   └── openapi.yaml        # API 契约文档
+│
+├── docs/                    # 文档
+├── scripts/                 # 脚本工具
+├── tests/                   # 测试用例
+├── docker-compose.yml       # Docker 编排配置
+└── nginx.conf               # Nginx 配置
+```
+
+## 快速开始
+
+### 环境要求
+
+- Docker & Docker Compose
+- Python 3.10+ (本地开发)
+- PHP 8.1+ (本地开发)
+
+### 配置环境
+
+```bash
+# 复制环境变量模板
+cp .env.example .env
+
+# 编辑配置
+vim .env
+```
+
+必需配置项：
+
+```env
+# AI 模型
+ZHIPU_API_KEY=your_api_key
+ZHIPU_MODEL=glm-4
+
+# 数据库
+POSTGRES_PASSWORD=your_secure_password
+
+# Chatwoot
+CHATWOOT_SECRET_KEY_BASE=your_secret_key
+CHATWOOT_API_TOKEN=your_api_token
+
+# 后端 API
+HYPERF_API_URL=http://hyperf-api:9501
+HYPERF_API_TOKEN=your_token
+
+# Strapi (可选)
+STRAPI_API_URL=http://your-strapi:1337
+STRAPI_API_TOKEN=your_token
+```
+
+### 启动服务
+
+```bash
+# 构建并启动所有服务
+docker-compose up -d --build
+
+# 查看服务状态
+docker-compose ps
+
+# 查看日志
+docker-compose logs -f agent
+```
+
+### 服务端口
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| Agent | 8000 | AI 代理服务 |
+| Chatwoot | 3000 | 客服平台 |
+| Nginx | 8080 | 文档静态服务 |
+| Strapi MCP | 8001 | 知识库服务 |
+| Order MCP | 8002 | 订单服务 |
+| Aftersale MCP | 8003 | 售后服务 |
+| Product MCP | 8004 | 产品服务 |
+
+### 访问地址
+
+- **客服平台**: http://localhost:3000
+- **API 文档**: http://localhost:8080/docs/
+- **Agent 健康检查**: http://localhost:8000/health
+
+## 开发指南
+
+### Agent 开发
+
+```bash
+cd agent
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 运行测试
+python -m pytest tests/
+
+# 本地调试
+python main.py
+```
+
+### MCP 服务开发
+
+```bash
+cd mcp_servers/{service_name}
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 启动服务 (默认端口见 docker-compose.yml)
+python server.py
+```
+
+### 添加新功能
+
+1. 在 `hyperf_api/openapi.yaml` 中定义 API 契约
+2. 实现 MCP 工具函数
+3. 编写 Agent Prompt 模板
+4. 在对应 Agent 中集成新能力
+5. 编写测试用例
+
+## API 概览
+
+### 订单服务
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/v1/orders/query` | POST | 查询订单 |
+| `/api/v1/orders/{id}/logistics` | GET | 物流追踪 |
+| `/api/v1/orders/{id}/modify` | PUT | 修改订单 |
+| `/api/v1/orders/{id}/cancel` | POST | 取消订单 |
+| `/api/v1/orders/{id}/invoice` | GET | 获取发票 |
+
+### 产品服务
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/v1/products/search` | POST | 产品搜索 |
+| `/api/v1/products/{id}` | GET | 产品详情 |
+| `/api/v1/products/recommend` | POST | 产品推荐 |
+| `/api/v1/products/quote` | POST | B2B 报价 |
+| `/api/v1/products/inventory/check` | POST | 库存查询 |
+
+### 售后服务
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/v1/aftersales/return` | POST | 申请退货 |
+| `/api/v1/aftersales/exchange` | POST | 申请换货 |
+| `/api/v1/aftersales/complaint` | POST | 投诉处理 |
+| `/api/v1/aftersales/ticket` | POST | 创建工单 |
+| `/api/v1/aftersales/query` | GET | 售后记录 |
+
+## 测试
+
+```bash
+# 运行 Agent 测试
+cd agent && python -m pytest tests/
+
+# 测试 API 端点
+python agent/test_endpoint.py
+```
+
+## License
+
+MIT