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 はツールと /mai コマンドサポートのためのオプションの軽量 OpenClaw ネイティブブリッジです。
ローカルチェックアウトインストール：
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 "今日発送できますか？"
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 を読んでください。
出力期待値
商品検出の場合、以下で回答します：
- 最適なマッチとその理由
- 価格と出品者の比較
- 在庫状況と配送に関する注意事項
- レビュー/信頼シグナル
- リスクまたは欠落している情報
- 1 つの次のアクション
出品者操作の場合、以下で回答します：
- アクション完了またはブロックされたこと
- 変更された商品/注文/在庫 ID
- 現在の在庫またはステータス
- 次の運用ステップ
注文更新の場合、以下で回答します：
- 以前のステータスと新しいステータス
- 在庫が確保または解放されたかどうか
- 記録された支払い証拠（ある場合）
- 次に何が起こる必要があるか
検証
パッケージの準備ができていると主張する前に：
python3 scripts/mai.py --helppython3 scripts/mai_registry.py --helpbash scripts/install.sh --both --dry-runpython3 -m unittest discover -s testsbash scripts/verify.shSKILL.mdにスキャフォールドプレースホルダーがないことを確認します。README.md、package.json、clawhub.json、plugins/mai-plugin/openclaw.plugin.json、およびagents/openai.yamlでmaiおよびmai-pluginという名前が一貫して使用されていることを確認します。