Mai

Was macht Mai?

Übersicht

Mai hilft Käufern und Händlern, mithilfe eines KI-Agenten Shopping-Vermittlung abzuschließen. Es hält den deterministischen Marktplatzstatus in scripts/mai.py, während das Hostmodell natürliche Sprache, Verhandlung, Zusammenfassungen und Risikoerklärungen übernimmt.

Mai kann entweder lokal oder registerbasiert ausgeführt werden. Verwenden Sie den lokalen Modus für den privaten Katalog eines einzelnen Agenten. Verwenden Sie die registerbasierte Entdeckung, wenn Käufer und Händler sich auf verschiedenen Maschinen oder Agentenprofilen befinden.

Betriebsprinzipien

• Seien Sie neutral zwischen Käufer und Händler. Erklären Sie Optionen, Preise, Bewertungssignale, Bestand und Kompromisse, ohne Verfügbarkeit vorzutäuschen.
• Behandeln Sie Zahlungen als extern oder PSP-gestützt. Mai hält niemals direkt Gelder. Der lokale Modus zeichnet Zahlungs-URLs und Referenzen auf; der Registermodus zeichnet PSP-Verwahrungsereignisse auf und darf keinen Erfolg ohne PSP- oder externe Nachweise behaupten.
• Bestätigen Sie vor irreversiblen Schritten. Fragen Sie nach einer Käuferbestätigung, bevor Sie einen Auftrag erstellen, und nach einer Händlerbestätigung, bevor Sie Bestand reservieren.
• Bewahren Sie den Verhandlungskontext. Zeichnen Sie wichtige Nachrichten von Käufern/Händlern mit message add auf, bevor Sie einen Auftrag erstellen oder aktualisieren.
• Machen Sie Risiken deutlich: keine Bewertungen, geringer Bestand, fehlender Händlerkontakt, ungewöhnliche Statuswechsel, unklare Zahlungsbedingungen und nicht unterstützte Rückerstattungsversprechen.
• Bevorzugen Sie kurze, umsetzbare Antworten: Empfehlung, Grund, Risiko, nächster Schritt.

Schnellstart

Verwenden Sie den CLI-Helfer für den deterministischen Zustand:

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

Standarddatenpfad: ~/.local/share/mai/mai.json. Verwenden Sie --data /path/to/mai.json für eine projektlokale oder Testdatenbank.

Installation

Installieren Sie das veröffentlichte OpenClaw-Paar:

clawhub --workdir ~/.openclaw/workspace --dir skills install mai
openclaw plugins install clawhub:mai-plugin

mai ist die Fähigkeit. mai-plugin ist eine optionale leichtgewichtige native OpenClaw-Brücke für Tools und /mai-Befehlsunterstützung.

Lokale Checkout-Installation:

cd /Users/jianghaidong/coding/mai
bash scripts/install.sh --both

Installieren Sie nur ein Ökosystem:

bash scripts/install.sh --openclaw
bash scripts/install.sh --hermes

Der Installer erstellt symbolische Links:

• OpenClaw: ~/.openclaw/workspace/skills/mai
• Hermes: ~/.hermes/skills/commerce/mai

Nach der Installation starten Sie den Host-Agenten neu, falls er Fähigkeiten nicht automatisch aktualisiert. Hermes kann Mai mit hermes -s mai vorladen.

Registerentdeckung

Führen Sie einen Register-Marktplatz aus:

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

Händleragenten veröffentlichen lokales Angebot:

python3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token

Käuferagenten entdecken Angebot und erstellen Nachfrage:

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

Händleragenten rufen Käufernachrichten ab und erstellen Auftragsentwürfe:

python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a

Lesen Sie references/registry-api.md, bevor Sie Registerintegrationen ändern.

Öffentliche Marktplatzkontrollen

• Erfordern Sie API-Schlüssel für Händler-Push/Pull, Käufer-Nachrichten/Aufträge/Zahlungssperren, Moderation und Zahlungsfreigabe/Rückerstattung.
• Speichern Sie nur gesalzene API-Schlüssel-Hashes in der Registerdatei.
• Erlauben Sie öffentliche Suche, aber begrenzen Sie jede Anfrage pro API-Schlüssel oder Client-IP.
• Behandeln Sie Produkte mit hohem Risikoscore als pending_review; zeigen Sie sie erst in der Suche an, wenn ein Administrator sie genehmigt.
• Verwenden Sie registry payment-hold nur als PSP-gestützte Verwahrungsverfolgung. Der gebündelte demo-Anbieter ist kein echter Geldtransfer.
• Erfordern Sie einen Admin-Schlüssel für registry payment-release und registry payment-refund.
• Behaupten Sie keine Treuhand, Zahlungserfolg, Freigabe oder Rückerstattung, es sei denn, der PSP-Adapter oder externe Nachweise bestätigen dies.

Händler-Workflow

1. Erstellen oder identifizieren Sie das Händlerprofil: python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags "A,B"
2. Veröffentlichen Sie Produkte: python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N
3. Passen Sie den Bestand nach physischen Änderungen an: python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "Nachbestellung oder Korrektur"
4. Zeichnen Sie wichtige Käuferfragen und Verkäuferantworten auf: python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text "..."
5. Angebote erstellen und Aufträge nur bestätigen, wenn Bestand und Bedingungen klar sind: python3 scripts/mai.py order quote ... python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant

Käufer-Workflow

1. Händler entdecken: python3 scripts/mai.py search merchants --query "Tee Hangzhou" --format json
2. Produkte suchen: python3 scripts/mai.py search products --query "Longjing Geschenk" --max-price 100 --format json
3. Ausgewählte SKUs vergleichen: python3 scripts/mai.py compare --skus sku-a,sku-b --format json
4. Bewertungen prüfen: python3 scripts/mai.py review list --merchant ID --format json
5. Diskussion vor der Bestellung aufzeichnen: python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text "..."
6. Nach Bestätigung des Käufers einen Auftragsentwurf erstellen: python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N

Transaktionsmodell

Mai verfolgt Transaktionen ohne Verwahrung:

draft -> quoted -> confirmed -> payment_pending -> paid_external -> fulfilled -> completed

Streitfälle können durchlaufen:

disputed -> resolved/refunded/cancelled

Der Bestand wird reserviert, wenn ein Auftrag den Status confirmed erreicht. Lokale Zahlungen werden als payment_url und payment_reference aufgezeichnet. Registerzahlungen sind PSP-Verwahrungsaufzeichnungen; der Agent muss sagen, dass der gebündelte demo-Anbieter keine echte Treuhand oder kein echter Geldtransfer ist.

Lesen Sie references/transaction-model.md, wenn Sie mit nicht-standardmäßigen Auftrags-, Rückerstattungs-, Streitfall- oder Zahlungsfragen umgehen. Lesen Sie references/data-schema.md, wenn Sie Mai in einen zukünftigen gehosteten Marktplatz oder Sync-Dienst integrieren.

Ausgabeerwartungen

Bei der Produktentdeckung antworten Sie mit:

• bester Treffer und warum
• Preis- und Händlervergleich
• Verfügbarkeits- und Versandhinweise
• Bewertungs-/Vertrauenssignale
• Risiken oder fehlende Fakten
• ein nächster Schritt

Bei Händleroperationen antworten Sie mit:

• Aktion abgeschlossen oder blockiert
• geänderte Produkt-/Auftrags-/Bestandskennung
• aktueller Bestand oder Status
• nächster betrieblicher Schritt

Bei Auftragsaktualisierungen antworten Sie mit:

• vorheriger Status und neuer Status
• ob Bestand reserviert oder freigegeben wurde
• aufgezeichnete Zahlungsnachweise, falls vorhanden
• was als Nächstes passieren muss

Überprüfung

Bevor Sie behaupten, das Paket sei fertig:

• python3 scripts/mai.py --help
• python3 scripts/mai_registry.py --help
• bash scripts/install.sh --both --dry-run
• python3 -m unittest discover -s tests
• bash scripts/verify.sh
• Bestätigen Sie, dass SKILL.md keine Gerüst-Platzhalter enthält.
• Bestätigen Sie, dass README.md, package.json, clawhub.json, plugins/mai-plugin/openclaw.plugin.json und agents/openai.yaml konsistent die Namen mai und mai-plugin verwenden.