Mai
概述
Mai 通过 AI 代理帮助买家和商家完成购物配对。它在 scripts/mai.py 中维护确定性的市场状态,而宿主模型则负责处理自然语言、议价、摘要和风险解释。
Mai 可以只运行在本地,也可以由注册表支持。本地模式适用于单个代理的私有目录。当买家和商家位于不同机器或代理配置文件上时,使用注册表支持的发现模式。
操作原则
- 在买家和商家之间保持中立。解释选项、价格、评价信号、库存和权衡,不虚构可用性。
- 将支付视为外部或 PSP 支持。Mai 绝不直接持有资金。本地模式记录支付 URL 和引用;注册表模式记录 PSP 托管事件,并且在没有 PSP 或外部证据的情况下,不得声称成功。
- 在不可逆步骤之前进行确认。在创建订单前要求买家确认,在预留库存前要求商家确认。
- 保留议价上下文。在形成或更新订单之前,使用
message add记录重要的买家/商家消息。 - 直白地揭示风险:没有评价、库存不足、缺少商家联系方式、状态异常跳变、支付条款不明确以及不支持的退款承诺。
- 倾向于简短、可操作的答案:推荐、理由、风险、下一步行动。
快速开始
使用 CLI 辅助工具进行确定性状态管理:
python3 scripts/mai.py merchant create --id seller-a --name "West Lake Tea" --city Hangzhou --contact "wechat:westlake" --tags "tea,gift"
python3 scripts/mai.py product add --merchant seller-a --sku tea-a --title "Longjing Gift Box" --price 88 --stock 5 --category tea --tags "longjing,gift"
python3 scripts/mai.py search products --query "longjing tea" --format json
python3 scripts/mai.py compare --skus tea-a,tea-b --format json
python3 scripts/mai.py order create --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86
默认数据路径:~/.local/share/mai/mai.json。
使用 --data /path/to/mai.json 指定项目本地或测试数据库。
安装
安装已发布的 OpenClaw 配对:
clawhub --workdir ~/.openclaw/workspace --dir skills install mai
openclaw plugins install clawhub:mai-plugin
mai 是技能。mai-plugin 是一个可选的轻量级 OpenClaw 原生桥接,用于工具和 /mai 命令支持。
本地检出安装:
cd /Users/jianghaidong/coding/mai
bash scripts/install.sh --both
仅安装一个生态系统:
bash scripts/install.sh --openclaw
bash scripts/install.sh --hermes
安装程序会创建符号链接:
- OpenClaw:
~/.openclaw/workspace/skills/mai - Hermes:
~/.hermes/skills/commerce/mai
安装后,如果宿主代理没有自动刷新技能,请重新启动。Hermes 可以使用 hermes -s mai 预加载 Mai。
注册表发现
运行注册表市场:
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token admin-token --role admin --subject ops-admin
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token seller-token --role merchant --subject seller-a --merchant-id seller-a
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token buyer-token --role buyer --subject alice --buyer-id alice
python3 scripts/mai_registry.py serve --data ./mai-registry.json --host 127.0.0.1 --port 8765 --rate-limit-per-minute 60
商家代理发布本地供应:
python3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token
买家代理发现供应并创建需求:
python3 scripts/mai.py --data ./buyer.json registry search-products --url http://127.0.0.1:8765 --query "longjing tea" --format json
python3 scripts/mai.py --data ./buyer.json registry message --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --text "Can this ship today?"
python3 scripts/mai.py --data ./buyer.json registry order --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86
python3 scripts/mai.py --data ./buyer.json registry payment-hold --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --order ORD-0001
商家代理拉取买家消息和草拟订单:
python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a
在更改注册表集成之前,请阅读 references/registry-api.md。
公共市场控制
- 对商家推送/拉取、买家消息/订单/支付持有、审核以及支付发放/退款要求 API 密钥。
- 在注册表文件中仅存储加盐的 API 密钥哈希。
- 允许公共搜索,但对每个请求按 API 密钥或客户端 IP 进行速率限制。
- 将高风险评分的产品视为
pending_review;在管理员批准之前,不要将其显示在搜索结果中。 - 仅将
registry payment-hold用作 PSP 支持的托管跟踪。捆绑的demo提供商并非真正的资金转移。 registry payment-release和registry payment-refund需要管理员密钥。- 除非 PSP 适配器或外部证据确认,否则不要声称托管、支付成功、发放或退款。
商家工作流
- 创建或识别商家档案:
python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags "A,B" - 发布产品:
python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N - 实物变动后调整库存:
python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "restock or correction" - 记录重要的买家问题和卖家回复:
python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text "..." - 仅在库存和条款明确时报价并确认订单:
python3 scripts/mai.py order quote ...python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant
买家工作流
- 发现商家:
python3 scripts/mai.py search merchants --query "tea hangzhou" --format json - 搜索产品:
python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json - 比较入围的 SKU:
python3 scripts/mai.py compare --skus sku-a,sku-b --format json - 查看评价:
python3 scripts/mai.py review list --merchant ID --format json - 在订购前记录讨论:
python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text "..." - 在买家确认后创建草稿订单:
python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N
交易模型
Mai 跟踪交易但不持有资金:
draft -> quoted -> confirmed -> payment_pending -> paid_external -> fulfilled -> completed
纠纷可以通过以下流程处理:
disputed -> resolved/refunded/cancelled
当订单变为 confirmed 时,库存被预留。仅本地支付的支付记录为 payment_url 和 payment_reference。注册表支付是 PSP 托管记录;代理必须声明捆绑的 demo 提供商并非真正的托管或资金转移。
在处理非乐观路径的订单、退款、纠纷或支付问题时,请阅读 references/transaction-model.md。
在将 Mai 与未来的托管市场或同步服务集成时,请阅读 references/data-schema.md。
输出期望
对于产品发现,回答应包括:
- 最佳匹配项及其原因
- 价格和商家比较
- 可用性和发货说明
- 评价/信任信号
- 风险或缺失信息
- 一个下一步行动
对于商家操作,回答应包括:
- 操作完成或被阻止
- 更改的产品/订单/库存标识符
- 当前库存或状态
- 下一个操作步骤
对于订单更新,回答应包括:
- 先前状态和新状态
- 库存是否已预留或释放
- 如有,记录的支付证据
- 接下来必须发生什么
验证
在声称包已就绪之前:
python3 scripts/mai.py --helppython3 scripts/mai_registry.py --helpbash scripts/install.sh --both --dry-runpython3 -m unittest discover -s testsbash scripts/verify.sh- 确认
SKILL.md中没有占位符。 - 确认
README.md、package.json、clawhub.json、plugins/mai-plugin/openclaw.plugin.json和agents/openai.yaml中一致使用mai和mai-plugin名称。