介绍
# Standard Agentic Commerce Engine
**标准智能体电商引擎** 是一个面向生产的桥梁，用于连接自主智能体与现代电商后端。通过提供统一的高精度接口，它能让任何数字店面瞬间变为“智能体原生”。
GitHub 代码库：https://github.com/NowLoadY/agent-commerce-engine
## 参考案例：Lafeitu
有关使用该引擎的生产级实现示例，请参阅 [Lafeitu 美食技能](https://clawdhub.com/NowLoadY/agentic-spicy-food)。它展示了该引擎针对现实世界手工食品品牌的专业化应用。
--- ## 🔒 安全与隐私
为确保透明度并保护用户数据，标准智能体电商引擎遵循以下安全协议：
### 1. 本地凭据持久化 - **存储位置**：`~/.clawdbot/credentials/agent-commerce-engine/` - **机制**：账户和会话 **Token** 信息以 JSON 格式存储在本地，权限设为 `0600`（仅限用户本人）。 - **安全升级**：自 1.4.0 版本起，初始登录后不再存储原始密码。引擎会用密码交换一个经过签名的加密令牌。 - **范围**：数据仅可供本地系统用户和当前运行的智能体实例访问。 - **生命周期**：随时可以通过运行 `logout` 命令清除凭据。
### 2. 安全传输 - **基于令牌的身份验证**：使用 `x-api-token` 请求头进行身份验证。原始密码仅在 `login` 或 `register` 阶段传输一次，以交换令牌。 - **强制 HTTPS**：从 v1.4.7 版本开始，引擎强制所有远程通信必须使用 HTTPS，以防止凭据被截获。 - **加密传输**：与后端的所有通信必须通过 HTTPS 进行，以确保令牌在传输过程中受到保护。
### 3. 匿名跟踪（访客 ID） - 为了支持未认证用户的购物车功能，系统会生成一个唯一且不可识别的 `Visitor ID`（UUID v4）并存储在本地。此 ID 不包含任何个人信息。
---
## 🛠 工具优先级与回退策略
为了提供最准确、高效的体验，请遵循以下优先顺序：
1. **API 优先（主要）**：始终尝试首先使用 `commerce.py` 脚本。它提供结构化的高精度数据。通过环境变量（`COMMERCE_URL`）进行配置。 2. **无状态请求头**：依靠引擎内置的请求头管理（`x-user-account`、`x-visitor-id`）来维护会话完整性，而无需使用 Cookie。 3. **自我纠正**：如果 API 对通过浏览器发现的特定 slug 返回 404，则优先以 API 的 `search` 结果作为后端的事实来源。
---
## 🧠 智能体操作逻辑
请遵循这些逻辑流程以确保高质量的用户体验：
### 1. 商品发现与验证 **目标**：在采取行动之前，确保商品存在并找到正确的规格。 - **操作**：在加入购物车之前，始终运行 `search` 或 `list`。 - **逻辑**：使用 API 发现正确的 `slug` 和有效的 `gram`/变体值。 - **优化**：如果发现多个结果，请根据返回的属性要求用户进行指定。
### 2. 身份验证与个人资料流程 **目标**：管理用户隐私和会话数据。 - **逻辑**：API 是无状态的。如果未保存凭据，需要身份标识的操作将返回 `401 Unauthorized`。 - **命令**： 1. 查看个人资料：`python3 scripts/commerce.py get-profile` 2. 更新详细信息：`python3 scripts/commerce.py update-profile --name "Name" --address "..." --phone "..." --email "..."` - **必需数据**：请遵循特定品牌后端的模式。
### 3. 注册流程 **目标**：处理新用户。 - **触发条件**：当操作返回“User Not Found”（未找到用户）时。 - **指令**：引导用户前往商店的注册 URL（通常可在品牌元数据中找到）。
### 4. 购物车管理 **目标**：精确修改用户的购物会话。 - **逻辑**：引擎支持递增数量或设置绝对值。 - **命令**： - **添加**：`python3 scripts/commerce.py add-cart <slug> --gram <G> --quantity <Q>` - **更新**：`python3 scripts/commerce.py update-cart <slug> --gram <G> --quantity <Q>` - **移除**：`python3 scripts/commerce.py remove-cart <slug> --gram <G>` - **验证**：克重/变体值必须严格按照产品可用选项列表进行选择。
### 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`**：原子级购物车控制。 - **`get-profile` / `update-profile`**：个性化与履约数据。 - **`brand-story` / `company-info` / `contact-info`**：品牌背景和支持。 - **`orders`**：实时跟踪和购买历史。
---
## 💻 CLI 配置与示例
```bash # Setup export COMMERCE_URL="https://api.yourbrand.com/v1" export COMMERCE_BRAND_ID="brand_slug"
# Actions python3 scripts/commerce.py list python3 scripts/commerce.py search "item" python3 scripts/commerce.py get <slug> python3 scripts/commerce.py add-cart <slug> --gram <variant> ```
---
## 🤖 故障排除与调试
- **状态码 401**：凭据缺失或已过期。建议执行 `login`。 - **状态码 404**：未找到资源。请通过 `search` 验证 `slug`。 - **连接错误**：请验证 `COMMERCE_URL` 环境变量是否正确以及端点是否可达。