名称： standard-agentic-commerce-engine
版本： 1.5.0
描述： 一个生产就绪的通用智能体商务引擎。该工具使自主智能体能够通过标准化协议与任何兼容的无头电商后端进行交互。它提供开箱即用的支持，包括商品发现、购物车操作和安全的用户管理。
标签： [ecommerce, shopping-agent, commerce-engine, standard-protocol, headless-commerce, agentic-web]
元数据： {"clawdbot":{"emoji":"🛒","requires":{"bins":["python3"],"tools":[],"env":["COMMERCE_URL","COMMERCE_BRAND_ID"],"paths":["~/.clawdbot/credentials/agent-commerce-engine/"]},"install":[{"id":"python-deps","kind":"pip","package":"requests","label":"安装 Python 依赖"}]}}

标准智能体商务引擎

标准智能体商务引擎 是一个生产就绪的桥梁，连接自主智能体与现代电商后端。它通过提供一个统一、高精度的接口，使任何数字店面都能瞬间变得“智能体原生”。

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

快速开始：开箱即用的后端设置

agent-commerce-engine 提供了一个标准规范 (SERVER_SPEC.md)，旨在使任何现有网站瞬间变得“智能体就绪”。通过查看并复现提供的最小可行 Python/FastAPI 服务器模板，开发者可以在几分钟内建立一个兼容的智能体原生后端接口。

参考案例：Lafeitu

要查看使用此引擎的生产级实现示例，请参阅 Lafeitu 美食技能。它展示了该引擎如何为现实世界的手工食品品牌进行专门化。

🔒 安全与隐私

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

1. 本地凭证持久化

• 存储位置：~/.clawdbot/credentials/agent-commerce-engine/
• 机制：账户和会话 令牌 信息以 JSON 格式本地存储，权限设置为 0600（仅用户可读写）。
• 安全升级：自版本 1.4.0 起，初始登录后绝不存储原始密码。引擎会将密码交换为签名的加密令牌。
• 范围：数据仅对本地系统用户和运行的智能体实例可访问。
• 生命周期：随时可以通过运行 logout 命令清除凭证。

2. 安全传输

• 基于令牌的认证：使用 x-api-token 请求头进行身份验证。原始密码仅在 login 或 register 阶段传输一次，以交换令牌。
• HTTPS 强制实施：自 v1.4.7 起，引擎强制要求所有远程通信使用 HTTPS，以防止凭证被截获。
• 加密传输：与后端的所有通信必须通过 HTTPS 进行，以确保令牌在传输过程中受到保护。

3. 匿名追踪（访客 ID）

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

🛠 工具优先级与回退策略

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

1. API 优先（主要）：始终首先尝试使用 commerce.py 脚本。它提供结构化、高精度的数据。通过环境变量 (COMMERCE_URL) 进行配置。
2. 无状态请求头：依赖引擎内置的请求头管理 (x-user-account, x-visitor-id) 来维持会话完整性，而无需 Cookie。
3. 自我修正：如果 API 对通过浏览器发现的特定商品标识符返回 404 错误，请优先将 API 的 search 结果视为后端的事实来源。

🧠 智能体操作逻辑

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

1. 商品发现与验证

目标：在采取行动前，确保商品存在并找到正确的规格。
- 操作：在加入购物车前，始终运行 search 或 list。
- 逻辑：使用 API 来发现正确的 slug 和有效的 variant 规格。
- 细化：如果找到多个结果，请根据返回的属性要求用户进行指定。

2. 认证与个人资料流程

目标：管理用户隐私和会话数据。
- 逻辑：API 是无状态的。需要身份验证的操作在凭证未保存时会返回 401 Unauthorized。
- 命令：
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：商品发现和库存扫描。
• get：深入了解商品规格、变体和定价。
• promotions：当前业务规则、运费门槛和有效优惠。
• cart：完整的会话摘要，包括 VIP 折扣和税费/运费估算。
• add-cart / update-cart / remove-cart / clear-cart：原子级的购物车控制。
• create-order：将购物车转换为待处理订单，并获取安全的支付 URL 以供用户交接。
• get-profile / update-profile：个性化与履约数据。
• brand-story / company-info / contact-info：品牌背景与支持信息。
• orders：实时追踪与购买历史。

💻 CLI 配置与示例

# 设置
export COMMERCE_URL="https://api.yourbrand.com/v1"
export COMMERCE_BRAND_ID="brand_slug"

# 操作
python3 scripts/commerce.py list
python3 scripts/commerce.py search "商品"
python3 scripts/commerce.py get <slug>
python3 scripts/commerce.py add-cart <slug> --variant <variant_id>
python3 scripts/commerce.py create-order --name "张三" --phone "555-0100" --province "省份" --city "城市" --address "街道 123 号"

🤖 故障排除与调试

• 状态码 401：凭证缺失或已过期。建议执行 login。
• 状态码 404：资源未找到。通过 search 验证 slug。
• 连接错误：验证 COMMERCE_URL 环境变量是否正确且端点可访问。