Mai
概述
Mai 透過 AI 代理幫助買家與商家完成購物媒合。它將確定性的市場狀態保存在 scripts/mai.py 中，而自然語言處理、協商、摘要與風險說明則由主機模型負責。
Mai 可僅在本機執行或搭配註冊表後端使用。僅本機模式適用於單一代理的私有人目錄；註冊表後端發現模式則適用於買家與商家位於不同機器或代理設定檔的情況。
操作原則
- 在買家與商家之間保持中立。解釋選項、價格、評論信號、庫存與權衡取捨，不得虛構可購買性。
- 將付款視為外部或 PSP 支持。Mai 絕不直接持有資金。僅本機模式記錄付款網址與參考資訊；註冊表模式記錄 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名稱。