Agent Commerce Engine

核心用法

Standard Agentic Commerce Engine 是一个生产级通用引擎，连接自主代理与现代电商后端。开发者通过实现标准协议（SERVER_SPEC.md），可在数分钟内将现有网站转为"Agent-Ready"状态。

主要能力：

• 商品发现：search/list 支持分页浏览大型目录，get 获取详细规格与变体
• 购物车管理：原子级操作（add-cart/update-cart/remove-cart/clear-cart），支持精确数量控制
• 订单创建：create-order 生成待支付订单并返回支付链接，由用户完成最终付款（代理不处理资金授权）
• 用户管理：本地凭证存储、Token 认证、个人信息更新
• 品牌信息：获取品牌故事、企业信息、客服渠道

使用方式：通过 python3 scripts/commerce.py --store <url> 指定目标店铺，所有操作基于无状态 API。

显著优点

1. 标准化协议：统一接口适配任意兼容的无头电商后端，降低集成成本
2. 生产就绪：包含完整错误码体系（AUTH_REQUIRED、PRODUCT_NOT_FOUND 等）、分页安全机制、自校正逻辑
3. 安全设计：Token 替换密码存储（v1.4.0+）、强制 HTTPS（v1.4.7+）、0600 权限本地凭证、UUID v4 匿名访客跟踪
4. 隐私优先：用户数据本地隔离，可随时执行 logout 清除凭证

潜在局限

• 支付断层：代理无法直接执行消费者支付（银行卡/移动支付），必须将支付 URL 交接给真人用户
• 生态依赖：需要后端商家主动实现 SERVER_SPEC.md 协议，存量系统改造存在 friction
• Token 生命周期：凭证过期需重新登录，无刷新机制说明

适合人群

• 希望让 AI 代理具备电商能力的开发者/品牌方
• 运营无头电商（Headless Commerce）架构的技术团队
• 需要自动化商品发现、比价、库存查询的智能购物场景

常规风险

| 风险类型 | 说明 |

|---------|------|

| 凭证泄露 | 本地 JSON 存储虽有 0600 权限，但 root 用户或其他进程仍可读取 |

| 中间人攻击 | 虽强制 HTTPS，但首次 `login` 时密码仍传输一次，需确保证书有效性 |

| 订单误操作 | 代理可能因理解错误创建非预期订单，支付前需用户确认 |

| 数据残留 | 访客 ID 本地持久化，可能用于跨会话追踪行为模式 |

核心用法

Standard Agentic Commerce Engine 是一款生产级的通用电商代理引擎，充当自主AI代理与现代电商后端之间的标准化桥梁。通过统一的高精度接口，它能让任意数字 storefront 瞬间变为"Agent-Native"。

关键功能模块：

• 商品发现：search/list 支持分页查询，get 获取完整规格与变体
• 购物车原子操作：add-cart/update-cart/remove-cart/clear-cart 精确控制购物会话
• 订单创建与支付转交：create-order 生成待支付订单并返回支付URL，由用户完成最终支付（代理不直接处理金融授权）
• 用户管理：get-profile/update-profile 管理个人信息，login/register 处理认证
• 品牌叙事：brand-story/company-info/contact-info 获取品牌背景与支持信息

典型工作流：
1. 通过 --store 指定目标店铺API端点
2. 使用 search 确认商品存在并获取正确 slug 和 variant
3. add-cart 添加商品，引擎自动处理 x-user-account/x-visitor-id 会话状态
4. cart 查看实时购物车，含运费/税费估算
5. create-order 生成订单，将支付URL交给用户完成交易

---

显著优点

| 维度 | 优势 |

|------|------|

| **标准化协议** | 提供 `SERVER_SPEC.md` 规范，任何电商后端可在数分钟内对接 |

| **无状态架构** | 通过 Header 管理会话（`x-api-token`/`x-user-account`/`x-visitor-id`），无需Cookie |

| **安全设计** | v1.4.0+ 仅存储Token不存明文密码；v1.4.7+ 强制HTTPS；凭证文件 `0600` 权限 |

| **生产就绪** | 已通过 Lafeitu 真实 artisanal food 品牌验证 |

| **轻量依赖** | 仅依赖 `requests` 库，供应链攻击面极小 |

---

潜在局限与风险

| 类别 | 说明 |

|------|------|

| **支付能力边界** | 代理无法直接执行信用卡/移动支付，必须将支付URL转交用户，存在"最后一步"人工依赖 |

| **Token生命周期** | 当前需手动重新登录刷新Token，无自动续期机制 |

| **输入验证** | 前端输入校验（邮箱/URL格式）可更严格，依赖后端返回错误 |

| **日志安全** | 当前无详细日志，未来若添加需避免Token/密码入日志 |

| **版本锁定** | 未提供 `requirements.txt`，建议声明 `requests>=2.25.0` |

---

适合人群

• 电商开发者：希望快速将现有无头电商系统接入AI代理生态
• 品牌运营方：需要为 artisanal/垂直品牌（如Lafeitu）构建AI购物助手
• Agent平台集成商：寻求标准化的电商能力模块
• 隐私敏感用户：重视本地凭证存储、Token替代密码的安全模式

---

常规风险

• 配置风险：--store URL配置错误可能导致请求发往非预期端点（但强制HTTPS降低了中间人风险）
• 凭证泄露：虽然本地存储权限严格，但物理设备被攻破后Token仍可被读取
• API兼容性：后端若不完全遵循 SERVER_SPEC.md，可能导致功能异常
• 订单状态同步：支付完成后需后端主动通知或用户手动确认，存在状态同步延迟