教程：50 行代码，做一个能下单的购物 agent

目标：用 commerce-mcp-sandbox（我们的开源模拟商城）做后端，跑通"搜品 → 下单 → 支付 → 签收 → 退款"完整购物生命周期。全程不花钱、不需要任何电商接口资质。

0. 原理

购物 agent = 你的 agent 逻辑 + 一个可调用的商城后端。后端以 MCP 协议暴露六个工具（搜索/详情/下单/状态/物流/售后），你的 agent 只需要"会调工具 + 会向用户转述"。沙箱后端在内存里模拟了真实商城的全状态机（包括发货推进和退款），所以你能提前把所有边界情况测完。

用户 ⇄ 你的 agent 逻辑 ⇄ MCP 协议 ⇄ commerce-mcp-sandbox（模拟商城）
                                   └─ 换成真实端点 = 上线（工具签名不变）

1. 起一个沙箱后端

npx commerce-mcp-sandbox --http 3300
# 或 stdio 模式直接挂进宿主：
# { "mcpServers": { "commerce-sandbox": { "command": "npx", "args": ["commerce-mcp-sandbox"] } } }

零依赖、零配置、零资金。内存数据，重启即清。

2. 最小 agent（Node，约 50 行）

// npm install @modelcontextprotocol/sdk
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3300/mcp'));
const mcp = new Client({ name: 'my-shopping-agent', version: '0.1.0' });
await mcp.connect(transport);

async function call(tool, args) {
  const r = await mcp.callTool({ name: tool, arguments: args });
  return r.structuredContent ?? JSON.parse(r.content[0].text);
}

// —— 购物生命周期 ——
// 1) 用户说"要买保温杯"
const found = await call('search_products', { query: '保温杯' });
console.log('推荐:', found.items[0]);

// 2) 用户确认后下单（金额服务端算，你只传 sku 和数量）
const order = await call('create_order', {
  items: [{ sku: found.items[0].sku, qty: 1 }],
  receiver: { name: '张三', phone: '13800138000', address: '浙江省杭州市西湖区文一西路100号' },
  user_ref: 'demo-user'
});

// 3) 把 pay_hint 呈现给用户（沙箱里是"调 pay_order 即支付"）
await call('pay_order', { order_no: order.order_no });

// 4) 等沙箱自动推进发货（真实环境是轮询状态/收推送）
setTimeout(async () => {
  const st = await call('get_order', { order_no: order.order_no });
  console.log('订单状态:', st.status, '| 事件:', st.events.map(e => e.event));
}, 6000);

3. 必须处理的四件事（决定 agent 好不好用）

1. 下单前复述确认：商品、价格（分转元）、收货信息——念给用户听并得到"确认"。这份对话记录是售后争议时的证据。
2. 幂等：同一购买意图用同一个 Idempotency-Key，网络重试才不会重复扣单。
3. 库存快照有时效：inventory_snapshot_at 太旧就先刷新再推荐，下单撞 OUT_OF_STOCK 就换品。
4. 状态主动播报：发货了、签收了、退款到账了——不要等用户来问。

4. 从沙箱到真实货架

你的 agent 逻辑一行不改，换后端端点即可：

5. 常见问题

Q: 佣金怎么算？ 用户通过你的 agent 成交的每笔订单，按成交金额的 5% 归接入方，平台按月结算——这是"agent 引荐交易"的回报，且不影响用户价格。

Q: 售后谁处理？ 平台处理：退货上门取件（用户每月 3 次免费）、商家仓验货、自动原路退款。你只需要在对话里调 request_aftersale 并告诉用户进度。

Q: agent 能碰用户的钱吗？ 不能，也不需要。用户直接向平台支付（微信收银台），这就是"agent 永不碰钱"的信任设计。