Mai - Agent de mise en relation commerciale

Mai

Aperçu

Mai aide les acheteurs et les commerçants à réaliser une mise en relation commerciale via un agent IA. Il conserve l'état déterministe du marché dans scripts/mai.py tandis que le modèle hôte gère le langage naturel, la négociation, les résumés et les explications des risques.

Mai peut fonctionner en local uniquement ou avec un registre. Utilisez le mode local pour un catalogue privé d'un seul agent. Utilisez le mode registre pour la découverte lorsque les acheteurs et les commerçants sont sur des machines ou des profils d'agent différents.

Principes de fonctionnement

• Restez neutre entre l'acheteur et le commerçant. Expliquez les options, les prix, les signaux d'avis, les stocks et les compromis sans inventer de disponibilité.
• Considérez les paiements comme externes ou basés sur un PSP. Mai ne détient jamais directement des fonds. Le mode local enregistre les URL et références de paiement ; le mode registre enregistre les événements de conservation PSP et ne doit pas revendiquer le succès sans preuve PSP ou externe.
• Confirmez avant les étapes irréversibles. Demandez la confirmation de l'acheteur avant de créer une commande et la confirmation du commerçant avant de réserver un stock.
• Préservez le contexte de négociation. Enregistrez les messages importants de l'acheteur/commerçant avec message add avant de former ou de mettre à jour une commande.
• Exposez clairement les risques : pas d'avis, stock faible, contact manquant du commerçant, sauts de statut inhabituels, conditions de paiement floues et promesses de remboursement non supportées.
• Préférez des réponses courtes et actionnables : recommandation, raison, risque, prochaine action.

Démarrage rapide

Utilisez l'outil CLI pour l'état déterministe :

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

Chemin de données par défaut : ~/.local/share/mai/mai.json. Utilisez --data /chemin/vers/mai.json pour une base de données locale au projet ou de test.

Installation

Installez la paire OpenClaw publiée :

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

mai est la compétence. mai-plugin est un pont natif OpenClaw léger optionnel pour les outils et la commande /mai.

Installation à partir d'un dépôt local :

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

Installez un seul écosystème :

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

L'installeur crée des liens symboliques :

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

Après l'installation, redémarrez l'agent hôte s'il ne rafraîchit pas automatiquement les compétences. Hermes peut précharger Mai avec hermes -s mai.

Découverte par registre

Exécutez un marché basé sur un registre :

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

Les agents commerçants publient l'offre locale :

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

Les agents acheteurs découvrent l'offre et créent la demande :

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

Les agents commerçants récupèrent les messages des acheteurs et les projets de commandes :

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

Lisez references/registry-api.md avant de modifier les intégrations du registre.

Contrôles du marché public

• Exigez des clés API pour les opérations de push/pull des commerçants, les messages/commandes/blocages de paiement des acheteurs, la modération, et le déblocage/remboursement des paiements.
• Stockez uniquement les hachages salés des clés API dans le fichier de registre.
• Autorisez la recherche publique, mais limitez le débit de chaque requête par clé API ou adresse IP client.
• Traitez les produits avec un score de risque élevé comme pending_review ; ne les affichez pas dans les résultats de recherche tant qu'un administrateur ne les a pas approuvés.
• Utilisez registry payment-hold uniquement comme suivi de conservation basé sur un PSP. Le fournisseur demo inclus n'est pas un véritable mouvement d'argent.
• Exigez une clé administrateur pour registry payment-release et registry payment-refund.
• Ne revendiquez pas de séquestre, de succès de paiement, de déblocage ou de remboursement à moins que l'adaptateur PSP ou une preuve externe ne le confirme.

Flux de travail du commerçant

1. Créez ou identifiez le profil du commerçant : python3 scripts/mai.py merchant create --id ID --name NOM --city VILLE --contact CONTACT --tags "A,B"
2. Publiez des produits : python3 scripts/mai.py product add --merchant ID --sku SKU --title TITRE --price N --stock N
3. Ajustez le stock après des changements physiques : python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "réapprovisionnement ou correction"
4. Enregistrez les questions importantes des acheteurs et les réponses des vendeurs : python3 scripts/mai.py message add --buyer ACHETEUR --merchant ID --sku SKU --sender merchant --text "..."
5. Devis et confirmez les commandes uniquement lorsque les stocks et les conditions sont clairs : python3 scripts/mai.py order quote ... python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant

Flux de travail de l'acheteur

1. Découvrez des commerçants : python3 scripts/mai.py search merchants --query "tea hangzhou" --format json
2. Recherchez des produits : python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json
3. Comparez les SKU présélectionnés : python3 scripts/mai.py compare --skus sku-a,sku-b --format json
4. Inspectez les avis : python3 scripts/mai.py review list --merchant ID --format json
5. Enregistrez la discussion avant de commander : python3 scripts/mai.py message add --buyer ACHETEUR --merchant ID --sku SKU --text "..."
6. Créez un projet de commande après confirmation de l'acheteur : python3 scripts/mai.py order create --buyer ACHETEUR --merchant ID --sku SKU --quantity N

Modèle de transaction

Mai suit les transactions sans conservation :

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

Les litiges peuvent passer par :

disputed -> resolved/refunded/cancelled

Le stock est réservé lorsqu'une commande passe à confirmed. Les paiements en local uniquement sont enregistrés sous payment_url et payment_reference. Les paiements par registre sont des enregistrements de conservation PSP ; l'agent doit préciser que le fournisseur demo inclus n'est pas un véritable séquestre ou mouvement d'argent.

Lisez references/transaction-model.md lors du traitement des commandes, remboursements, litiges ou questions de paiement hors du chemin normal. Lisez references/data-schema.md lors de l'intégration de Mai avec un futur marché hébergé ou service de synchronisation.

Attentes en matière de résultats

Pour la découverte de produits, répondez avec :

• la meilleure correspondance et pourquoi
• la comparaison des prix et des commerçants
• la disponibilité et les notes de livraison
• les signaux d'avis/de confiance
• les risques ou les informations manquantes
• une prochaine action

Pour les opérations des commerçants, répondez avec :

• l'action effectuée ou bloquée
• l'identifiant du produit/de la commande/du stock modifié
• le stock ou le statut actuel
• la prochaine étape opérationnelle

Pour les mises à jour de commande, répondez avec :

• le statut précédent et le nouveau statut
• si le stock a été reservé ou libéré
• la preuve de paiement enregistrée, le cas échéant
• ce qui doit se passer ensuite

Vérification

Avant de déclarer le paquet prêt :

• 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
• Confirmez que SKILL.md ne contient pas d'espaces réservés.
• Confirmez que README.md, package.json, clawhub.json, plugins/mai-plugin/openclaw.plugin.json, et agents/openai.yaml utilisent les noms mai et mai-plugin de manière cohérente.