Laburen挑战赛-人工智能销售代理（MCP+D1）
🎯 挑战的目标
该项目的目的是证明 对话式销售代理的设计与实现 通过 模型上下文协议（MCP）. 优先考虑了一个解耦且富有成效的架构，构建了一个具有真实状态持久性的自己的后端（REST API），能够自主处理复杂的业务流（搜索、购物车、库存）。
______________________________________________________________________
📱 WhatsApp频道（范围和限制）
该代理的设计和结构是为了在 WhatsApp.
- 理想整合：WhatsApp->Twilio->Chatwoot->Laburen代理->MCP后端。
- 当前状态（演示）：由于集成（Twilio）的运营成本和批准时间，功能演示是通过 Web独立 的Laburens。
- 文件：在实际生产环境中激活WhatsApp频道的完整指南详细介绍在
docs/deployment_guide.md.
______________________________________________________________________
📐 概念阶段·人工智能代理设计
本节描述了为代理自主处理销售而设计的交互逻辑。
1.互动流程图
下图说明了代理如何协调工具以满足用户的意图，从探索到购物车管理。
sequenceDiagram
participant U as Usuario
participant A as Agente IA
participant API as MCP Backend
participant DB as D1 Database
Note over U, A: Fase 1: Exploración
U->>A: "Busco pantalones deportivos"
A->>API: POST /products/list { "search": "pantalón deportivo" }
API->>DB: SELECT * FROM products...
DB-->>API: [ID: 5, ID: 12...]
API-->>A: Lista de productos
A-->>U: Muestra opciones con IDs y precios
Note over U, A: Fase 2: Gestión de Carrito
U->>A: "Quiero 2 unidades del ID 5"
alt Carrito Nuevo
A->>API: POST /cart { }
API-->>A: { "cartId": 101 }
end
A->>API: POST /cart/add { "cartId": 101, "productId": 5, "qty": 2 }
API->>DB: INSERT INTO cart_items...
DB-->>API: OK
API-->>A: Success
A-->>U: "Agregado. ¿Algo más?"
Note over U, A: Fase 3: Edición (Opcional)
U->>A: "Mejor solo quiero 1"
A->>API: POST /cart/update { "cartId": 101, "productId": 5, "qty": 1 }
API-->>A: Updated
A-->>U: "Listo, actualicé tu carrito."2.端点定义
是 行动 该代理可以与系统交互。
不重要：MCP从不返回面向最终用户的文本。所有答案都是结构化的JSON，用于独家消费和代理推理。
| 端点 | 方法 | 描述 | 预期正文（JSON） |
|---|---|---|---|
/products/list | Post | 在目录中搜索产品。 | { "search": "keyword" } |
/cart | Post | 初始化新的购买会话。 | {} |
/cart/add | post | 将项目添加到活动购物车中。 | { "cartId": 1, "productId": 5, "qty": 2 } |
/cart/get | POST | 获取购物车的当前状态和总数。 | { "cartId": 1 } |
/cart/update | post | 修改数量或删除（如果数量=0）。 | { "cartId": 1, "productId": 5, "qty": 1 } |
______________________________________________________________________
🚀 建筑
- 运行时：Cloudflare Workers（无服务器）- *低延迟和即时可扩展性。*
- 数据库Cloudflare D1（分布式SQLite） *边缘轻快的坚持。*
- API设计：“代理优先”（仅限JSON/POST）- *优化用于LLM函数调用。*
- 语言：TypeScript- *类型安全性和可维护性。*
📂 项目结构
/src
/controllers -> Lógica de negocio pura (SQL queries, validaciones), sin conocimiento del agente.
/routes -> Capa de contrato MCP (adaptadores HTTP para las Tools).
index.ts -> Entry point y Router principal.
/docs
design.md -> Diagramas de flujo y especificación técnica detallada.
agent_config.md -> System Prompt y JSON Schemas listos para copiar a Laburen.
deployment_guide.md -> Guía paso a paso para integración (Twilio, Chatwoot, Deploy).
/scripts
convert_xlsx_to_sql.js -> Utilidad ETL para importar productos desde Excel.🛠️ 安装和本地使用
- 安装依赖项:
npm install- 启动本地服务器:
npm run devAPI将在 http://localhost:8787.
- Probar端点:
查看JSON示例 docs/design.md.
☁️ 生产部署
- 登录Cloudflare:
npx wrangler login- 初始化数据库（仅第一次）:
npx wrangler d1 execute shop_db --remote --file=./schema.sql
npx wrangler d1 execute shop_db --remote --file=./seed_products.sql- 派遣工人:
npm run deploy🤖 配置代理
要将此后端与人工智能连接：
- 复制部署的工作人员的URL。
- 美国 JSON模式 定义于
docs/agent_config.md在Laburen中配置工具。 - 粘贴 系统提示 在模型配置中建议。
______________________________________________________________________
完成⚡和typescript。