名称： moltpho
描述： 通过 Moltpho 在亚马逊上自主购物 - 使用 Base 主网上的 mUSD 搜索商品、管理信用额并购买商品
元数据： {"requires": {"http": true, "browser": true}}

Moltpho 购物技能

使用 Base 主网上由信用支持的 mUSD 代币，在亚马逊上自主购买商品。

概述

Moltpho 是一个无头购物商城，使 AI 智能体能够通过 mUSD（Base 主网上的 ERC-20 代币）支持的信用系统发现和购买亚马逊商品。此技能处理：

• 智能体注册和凭证管理
• 商品搜索与发现
• 自主和主动购买
• 信用余额监控
• x402 支付协议集成

引导流程

首次调用时，技能必须检查现有凭证，并在需要时进行注册。

凭证位置

注册流程

1. 检查凭证文件：在相应路径查找。
2. 如果缺失：调用 POST /v1/agents/register，需提供：
   • openclaw_instance_id（如果可用）
   • agent_display_name
   • agent_description
   • 注册时无需配送地址信息
3. 保存凭证：使用 chmod 600 权限保存文件。
4. 自动打开浏览器：显示提示：“正在浏览器中打开门户以完成设置...”
5. 注册过程不包含配送地址信息 - 在所有者通过门户添加配送地址前，订单将失败。

凭证文件格式

{
  "agent_id": "uuid",
  "api_key_id": "moltpho_key_...",
  "api_key_secret": "moltpho_secret_...",
  "api_base_url": "https://api.moltpho.com",
  "wallet_address": "0xabc123..."
}

核心功能

bootstrap()

初始化智能体凭证，并为所有者打开门户进行设置。

1. 检查凭证文件是否存在于平台特定路径。
2. 如果存在且有效：加载凭证，使用 GET /v1/agents/me 验证。
3. 如果缺失或无效：
   a. 调用 POST /v1/agents/register（无需认证）。
   b. 接收：agent_id, api_key_id, api_key_secret, claim_url, wallet_address。
   c. 使用 chmod 600 权限写入凭证文件。
   d. 显示：“正在浏览器中打开门户以完成设置...”
   e. 在浏览器中打开 claim_url（24 小时内有效）。
4. 返回智能体状态（UNCLAIMED, CLAIMED, DEGRADED, SUSPENDED）。

collect_shipping_profile()

（可选）从所有者处收集配送信息。

注意：此功能是**可选**的。所有者可以通过门户配置配送信息。
      在配送地址信息存在之前，订单将因 INVALID_SHIPPING_PROFILE 而失败。

如果在对话中收集：
1. 请求全名。
2. 请求地址（街道、城市、州、邮政编码）。
3. 请求电子邮件。
4. 请求电话号码。
5. 验证：仅支持美国地址（v1 版本不支持国际地址）。
6. 调用 POST /v1/shipping_profiles（upsert_shipping_profile）。
7. 确认地址信息已保存。

POST 端点会更新默认地址信息：
- 如果不存在地址信息，则创建一个。
- 如果已存在地址信息，则更新它。

update_shipping_profile()

更新智能体的配送地址。

参数：
- full_name：收件人全名
- address1：街道地址
- address2：公寓/套房（可选）
- city：城市
- state：州（2 字母代码）
- postal_code：邮政编码
- email：联系邮箱
- phone：联系电话

流程：
1. 验证所有必填字段。
2. 验证美国地址（v1 版本仅支持美国）。
3. 调用 POST /v1/shipping_profiles（更新默认地址信息）。
4. 返回更新后的地址信息。

使用场景：
- “更新我的配送地址”
- “将我的收货地址更改为...”
- 引导流程中的首次设置

catalog_search(query, constraints)

通过 Moltpho 在亚马逊上搜索商品。

参数：
- query：搜索词（字符串）
- constraints：可选过滤器
  - max_price：最高价格（美元）
  - category：商品类别关键词
  - min_rating：最低星级评分（1-5）

流程：
1. 调用 GET /v1/catalog/search?query={query}&limit=20。
2. 如果提供了本地约束条件，则应用它们。
3. 展示结果，包括：
   - 商品标题和品牌
   - Moltpho 价格（最终价格，包含 10% 加价）
   - 可用状态
   - 评分（如果可用）
4. 如果缓存过期，结果会包含“价格可能已变动”的警告。

频率限制：60 次请求/分钟

purchase(item, qty)

通过 x402 支付流程执行购买。

参数：
- item：ASIN 或商品标识符
- qty：数量（默认为 1）

流程：
1. 预算检查：调用 GET /v1/balance 验证可用信用额。
   - available_credit = balance - active_reservations
   - 检查是否超过单笔订单上限（如果设置）
   - 检查是否超过每日上限（如果设置）

2. 创建报价：调用 POST /v1/quotes。
   - 包含：asin, quantity, shipping_profile_id
   - 返回：quote_id, total_due_usd, expires_at（10 分钟 TTL）
   - 创建对余额的软预留
   - 如果未设置配送地址信息，可能因 INVALID_SHIPPING_PROFILE 失败

3. 发起订单：调用 POST /v1/orders 并带上 quote_id。
   - 首次调用返回 402 Payment Required，并带有 PAYMENT-REQUIRED 头部。

4. 签名支付：调用 POST /v1/wallets/x402/sign。
   - 包含：payment_required blob, idempotency_key
   - 返回：用于 x402 头部的 payment_signature

5. 完成订单：使用 PAYMENT-SIGNATURE 头部重试 POST /v1/orders。
   - 成功时：返回 order_id, status（PAID/PLACED）
   - 软预留转换为实际支出

报价过期自动重试：
- 如果在流程中报价过期，自动重试最多 3 次。
- 仅当新价格在原始报价的 5% 范围内时才重试。
- 在 3 次重试后或价格变动 >5% 时失败。

频率限制：
- 报价：20 次/分钟
- 订单：5 次/分钟
- 签名：10 次/分钟

proactive_monitoring()

监控对话以发现购买需求信号，并在适当时采取行动。

此功能在对话期间被动运行，以检测购买机会。

需求信号（显式）：
- “我需要”、“我们用完了”、“买”、“订购”、“更换”
- “快用完了”、“几乎用完了”
- 带有紧迫感的直接商品提及

需求信号（隐式）：
- 反复抱怨缺少物品
- 提到关键物品短缺
- 暗示即时需求的上下文

置信度评分：
- 1.0：明确的购买请求（“给我买 X”）
- 0.8：强烈的暗示需求（“我们卫生纸完全用完了”）
- 0.5：微弱的暗示便利性（**不要**购买）
- 0.0：未知/不明确

预算信号处理：
- 诸如“钱紧”、“预算有限”、“买不起”等短语
- 将置信度降低 0.3-0.5
- 如果仍高于阈值，则谨慎进行

主动购买允许的条件（全部满足）：
- 所有者已启用主动购买（默认开启）
- 置信度 >= 0.8（阈值）
- 商品匹配低风险类别：
  - 家庭必需品
  - 办公用品
  - 线缆/适配器
  - 基本厨房用品
  - 洗漱用品
- 价格 <= min(per_order_cap, $75)
- 商品关键词不在禁止类别中
- 商品不在系统阻止列表中
- 配送地址信息存在

日志记录：
每次购买记录：
- “购买原因”（决策理由）
- 检测到的信号
- 置信度等级（高/中/低）
- 预算影响

budget_check()

在任何购买前验证是否有足够的信用额。

流程：
1. 调用 GET /v1/balance。
2. 响应包括：
   - available_credit_cents：可支出金额
   - staged_refunds：待处理退款（用星号显示）
   - target_limit：所有者配置的信用额度
3. 与以下进行比较：
   - 报价总额
   - 单笔订单上限（如果设置）
   - 每日上限（如果设置，跟踪每日支出）
4. 返回：can_purchase（布尔值）, available_amount, reason_if_blocked

create_support_ticket(type, description, order_id)

为退货、包裹丢失或其他问题创建支持工单。

参数：
- type：工单类型 - RETURN, LOST_PACKAGE, 或 OTHER
- description：问题的详细描述（1-2000 字符）
- order_id：订单 ID（RETURN 和 LOST_PACKAGE 必需）

流程：
1. 验证工单类型和描述。
2. 如果是 RETURN 或 LOST_PACKAGE，验证是否提供了 order_id。
3. 调用 POST /v1/support_tickets，参数为 { type, description, order_id }。
4. 返回工单 ID 和状态。

使用场景：
- “我想退回这个商品” → type=RETURN，链接到订单
- “我的包裹从未送达” → type=LOST_PACKAGE，链接到订单
- “我有一个关于账单的问题” → type=OTHER，无需订单

注意：退货和包裹丢失需要支持工单。
      仅订单取消会自动退款。

list_support_tickets()

列出智能体的支持工单。

流程：
1. 调用 GET /v1/support_tickets。
2. 显示工单信息：类型、状态、订单链接、创建日期。
3. 状态含义：
   - OPEN：已提交，等待支持审核
   - IN_PROGRESS：正在处理中
   - WAITING_CUSTOMER：支持需要您提供更多信息
   - RESOLVED：问题已解决
   - CLOSED：工单已关闭

logout()

删除本地凭证（智能体在服务器端保留）。

流程：
1. 删除平台特定路径下的凭证文件。
2. 显示：“凭证已移除。智能体仍存在于 Moltpho 服务器上。”
3. 要完全删除智能体，所有者必须使用门户。

注意：此操作仅删除**本地**凭证。智能体账户、钱包和购买历史记录仍保留在 Moltpho 服务器上，直到所有者通过门户删除。

浏览器门户使用

该技能使用浏览器处理所有者敏感操作。

何时打开浏览器

浏览器指南

• 始终显示提示：“正在浏览器中打开门户...”
• 切勿在聊天中索取卡号、密码或敏感凭证
• 门户通过 Stripe Elements 处理所有 PCI 敏感操作
• 所有者通过魔法链接（基于电子邮件）进行身份验证

API 认证

所有 API 请求（注册除外）都需要认证。

头部

Authorization: Bearer <api_key_secret>

或更推荐：

X-Moltpho-Key-Id: <api_key_id>
X-Moltpho-Signature: <HMAC 签名>

幂等性

对于改变状态的操作，始终包含：

Idempotency-Key: <唯一键>

以下操作必需：
- POST /v1/quotes
- POST /v1/orders
- POST /v1/wallets/x402/sign

错误处理

常见错误

报价过期自动重试

当报价在 x402 流程中过期时：
1. 获取同一商品的新报价。
2. 将价格与原始报价进行比较。
3. 如果在 5% 容差范围内：继续使用新报价。
4. 如果变动 >5%：因 PRICE_CHANGED 失败。
5. 最多重试 3 次。

约束与限制

系统限制

频率限制

禁止购买的商品（系统强制执行）

无论所有者设置如何，以下类别无法购买：
- 武器、枪支、弹药
- 管制物质、处方药
- 烟草、尼古丁产品
- 酒精
- 成人内容
- 危险材料

支付系统

信用模型

• 所有者以美元设置目标信用额度。
• 每周自动充值将信用额恢复到目标值。
• 信用由 Base 主网上的 mUSD 代币支持。
• 比亚马逊价格高 10% 的加价（覆盖费用 + Gas）。

x402 流程

1. POST /v1/orders 返回 402，并带有 PAYMENT-REQUIRED 头部。
2. 调用 POST /v1/wallets/x402/sign，参数为支付数据块。
3. 钱包服务签署 EIP-3009 授权。
4. 使用 PAYMENT-SIGNATURE 头部重试订单。
5. 协调者在 Base 主网上结算。
6. 订单进入履行流程。

退款

智能体状态

最佳实践

在任何购买前

1. 调用 budget_check() 验证可用信用额。
2. 确认配送地址信息存在。
3. 检查商品是否在类别禁止列表中。
4. 验证主动购买的置信度阈值。

对话指南

• 在执行前始终确认购买总价。
• 购买后报告订单状态和剩余信用额。
• 如果检测到预算信号，承认约束条件。
• 切勿强迫用户增加信用额。

错误恢复

• 遇到 INSUFFICIENT_CREDIT：建议通过门户增加信用额。
• 遇到 INVALID_SHIPPING_PROFILE：收集配送信息并调用 upsert_shipping_profile()，或引导至门户。
• 遇到 SUSPENDED：解释所有者必须通过门户解决。

快速参考

重要端点

门户 URL

https://portal.moltpho.com

所有者操作