标准代理化商务引擎

该标准代理化商务引擎是一个标准客户端与协议指南，用于将代理程序连接至兼容的电子商务后端。它为代理程序提供了一致的方式来搜索产品、管理购物车、访问账户数据、创建订单，并将支付环节交还给用户处理。

GitHub 仓库：https://github.com/NowLoadY/agent-commerce-engine

快速入门：后端集成

该代理化商务引擎包含一份服务器规范，位于SERVER_SPEC.md文件中，适用于希望提供兼容商务API的网站。通过实现文档中描述的端点，现有的网店可以支持代理驱动的产品发现、购物车操作、账户流程和订单创建，而无需为每个品牌定制开发工具。

参考案例：辣飞兔

要查看一个使用此引擎的生产级实现示例，请参考辣飞兔美食技能。它展示了该引擎如何专为一个现实世界的手工食品品牌进行定制化应用。

🔒 安全与隐私

为确保透明度并保护用户数据，标准智能商务引擎遵循以下安全协议：

1. 本地凭证持久化

• 存储位置：~/.openclaw/credentials/agent-commerce-engine/
• 机制：账户和会话令牌信息以JSON格式本地存储。凭证文件以0600（仅用户）权限写入。
• 安全升级：自1.4.0版本起，原始密码在首次登录后绝不存储。引擎会将密码交换为签名的加密令牌。
• 范围：凭证存储在本地机器上，供当前用户环境重复使用。
• 生命周期：凭证可随时通过运行logout命令清除。

2. 安全传输

• 基于令牌的身份验证：使用x-api-token请求头进行身份验证。原始密码仅在登录或注册阶段传输一次，以换取令牌。
• HTTPS 强制实施：客户端拒绝非HTTPS的远程端点。localhost和127.0.0.1仍可用于本地开发。
• 加密传输：生产环境流量预期通过HTTPS运行，因此令牌不会通过明文HTTP发送。

3. 匿名跟踪（访客ID）

• 为了支持未认证用户的购物车功能，会生成一个唯一的、不可识别的访客ID（UUID v4）并本地存储。此ID不包含任何个人信息。

🛠 工具优先级与回退策略

为提供最准确高效的体验，请遵循以下优先级顺序：

1. API 优先（主要方式）：始终优先尝试使用commerce.py脚本。它提供结构化、高精度的数据。通过--store <url>参数定位目标店铺。
2. 无状态请求头：依赖引擎内置的请求头管理（x-user-account、x-visitor-id）来维持会话完整性，无需依赖 Cookie。
3. 自我修正：如果 API 对通过浏览器发现的特定 slug 返回 404 错误，应优先将 API 的搜索结果作为后端数据的权威来源。

🧠 智能体运行逻辑

遵循以下逻辑流程，以确保高质量的用户体验：

1. 产品发现与验证

目标：在采取行动前，确保商品存在并找到正确的规格。

• 行动：在加入购物车前，务必先执行搜索或列表操作。
• 逻辑：使用API来发现正确的标识符（slug）和有效的变体（variant）规格。利用--page和--limit参数来安全地浏览大型商品目录，避免超出上下文限制。
• 优化：如果找到多个结果，请根据返回的属性要求用户进行指定。如果结果中的总页数（totalPages）大于当前页码（page），则考虑获取下一页数据或优化搜索条件。

2. 身份验证与个人资料流程

目标：管理用户隐私和会话数据。

• 逻辑：该API是无状态的。需要身份验证的操作将返回401 未授权如果凭证未保存。
• 命令：
  1. 查看个人资料：python3 scripts/commerce.py get-profile
  2. 更新详细信息：python3 scripts/commerce.py update-profile --name "姓名" --address "..." --phone "..." --email "..."
• 所需数据：遵循特定品牌后端的架构要求。

3. 注册流程

目标：处理新用户。

• 触发条件：当用户需要新账户或后端返回“用户未找到”时。
• 说明：优先使用内置的发送代码和注册当后端支持这些命令时执行它们。如果后端仅返回一个注册URL，则将用户引导至该流程。

4. 购物车管理

目标：精确修改用户的购物会话。

• 逻辑：引擎支持增加数量或设置绝对值。
• 命令：
  • 添加：python3 scripts/commerce.py add-cart <slug> --variant <V> --quantity <Q>
  • 更新：python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>
  • 移除：python3 scripts/commerce.py remove-cart <slug> --variant <V>
  • 清空：python3 scripts/commerce.py clear-cart
  • 结账 / 创建订单 (交接):python3 scripts/commerce.py create-order --name <姓名> --phone <电话> --province <省份> --city <城市> --address <详细地址>
• 验证: 变体值必须严格从产品的可用选项列表中选择。
• 支付流程 (关键): 由于缺乏金融授权，智能体目前无法直接执行消费者支付（银行卡/移动钱包）。一旦通过create-order生成订单，API通常会返回一个URL。智能体必须将此URL交给真实用户以完成支付。

5. 品牌信息与故事叙述

目标: 获取品牌身份和支持数据。

• 逻辑: 使用brand-info接口来检索叙述性内容。
• 工具:
  • python3 scripts/commerce.py brand-story：获取品牌故事/使命。
  • python3 scripts/commerce.py company-info：获取公司正式信息。
  • python3 scripts/commerce.py contact-info：获取客户支持渠道。

🚀 功能摘要

• search/list：产品发现和库存扫描。使用--page <N>和--limit <N>来安全地对大型商品目录进行分页。
• get：深入了解产品规格、变体和定价。
• promotions：当前业务规则、运费门槛和有效优惠。
• cart：完整的会话摘要，包括VIP折扣以及税费/运费估算。
• add-cart/update-cart/remove-cart/clear-cart: 原子级购物车控制。
• create-order: 将购物车最终化为待处理订单，并获取供用户交接的安全支付链接。
• get-profile/update-profile: 个性化与履约数据。
• brand-story/company-info/contact-info: 品牌背景与支持信息。
• orders: 实时追踪与购买历史。

💻 命令行界面配置与示例

# Target a store directly via --store (preferred)
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 list --page 1 --limit 20
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 search "item"
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 add-cart <slug> --variant <variant_id>

# Or use environment variable (deprecated, will be removed in a future version)
export COMMERCE_URL="https://api.yourbrand.com/v1"
python3 scripts/commerce.py list

凭证会根据域名自动存储在~/.openclaw/credentials/agent-commerce-engine/<domain>/ 目录下。.

🤖 故障排除与调试

• AUTH_REQUIRED: 令牌缺失或已过期。请运行login命令以获取新令牌。
• AUTH_INVALID: 凭证错误。请验证账户和密码。
• PRODUCT_NOT_FOUND: 未找到资源。请通过search命令验证slug。
• VARIANT_UNAVAILABLE: 请求的变体无效或缺货。请检查instruction字段以获取可用替代方案。
• CART_EMPTY: 尝试结算时购物车为空。请先添加商品。
• 连接错误: 请验证--storeURL正确且端点可访问。