Mai#

Overview#

Mai helps buyers and merchants complete shopping matchmaking through an AI agent. It keeps deterministic marketplace state in scripts/mai.py while the host model handles natural language, negotiation, summaries, and risk explanations.

Mai can run local-only or registry-backed. Use local-only for one agent's private catalog. Use registry-backed discovery when buyers and merchants are on different machines or agent profiles.

Operating Principles#

• Be neutral between buyer and merchant. Explain options, prices, review signals, inventory, and tradeoffs without fabricating availability.
• Treat payments as external or PSP-backed. Mai never directly holds funds. Local mode records payment URLs and references; registry mode records PSP custody events and must not claim success without PSP or external evidence.
• Confirm before irreversible steps. Ask for buyer confirmation before creating an order and merchant confirmation before reserving stock.
• Preserve negotiation context. Record important buyer/merchant messages with message add before forming or updating an order.
• Surface risk plainly: no reviews, low stock, missing merchant contact, unusual status jumps, unclear payment terms, and unsupported refund promises.
• Prefer short, actionable answers: recommendation, reason, risk, next action.

Quality Upgrade: Money-Line Workflows#

Mai sits on the same money line as local-life, delivery, and knowledge-backed shopping agents. Treat churn as a quality signal first: users usually need clearer matching, trust evidence, and transaction boundaries before they need more features.

Buyer Discovery#

1. Capture intent: product, budget, city/shipping constraints, urgency, trust threshold, and must-avoid conditions.
2. Search and compare candidates with deterministic CLI output before writing a recommendation.
3. Explain the best match, runner-up, tradeoff, missing evidence, and next action.
4. Do not create an order until the buyer explicitly confirms SKU, quantity, price, merchant, and terms in the current turn.

Merchant Operations#

1. Confirm the merchant id and product SKU before changing catalog, stock, price, or order state.
2. Show old value, new value, reason, and rollback/compensation step.
3. For stock reservation, require clear inventory evidence and an order status transition that matches the transaction model.
4. Record meaningful buyer/merchant messages before quoting or updating an order.

Payment and Trust#

• Never call the bundled demo provider real escrow or real money movement.
• Do not claim paid, released, refunded, or completed without PSP or external evidence.
• Surface trust signals: review count, merchant contact, stock freshness, status history, and dispute/refund policy.
• When evidence is weak, recommend a lower-risk next step instead of pushing the transaction forward.

Preferred product recommendation:

text

Best match: <sku + merchant>
Why: <fit to intent>
Tradeoff: <price, stock, trust, shipping>
Risk: <missing evidence or transaction concern>
Next action: <ask, message, quote, or confirm order>

Quick Start#

Use the CLI helper for deterministic state:

bash

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

Default data path: ~/.local/share/mai/mai.json. Use --data /path/to/mai.json for a project-local or test database.

Installation#

Install the published OpenClaw pair:

bash

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

mai is the skill. mai-plugin is an optional lightweight OpenClaw native bridge for tools and /mai command support.

Local checkout install:

bash

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

Install only one ecosystem:

bash

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

The installer creates symlinks:

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

After installation, restart the host agent if it does not refresh skills automatically. Hermes can preload Mai with hermes -s mai.

Registry Discovery#

Run a registry marketplace:

bash

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

Security boundary: remote registry URLs must use HTTPS. The local examples below use http://127.0.0.1 and therefore include --allow-insecure-localhost. Registry writes require explicit current-turn confirmation through --confirm; OpenClaw plugin tools use confirm=true for the same boundary. registry push publishes catalog data by default and excludes orders/messages unless --include-orders is deliberately supplied.

Merchant agents publish local supply:

bash

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

Buyer agents discover supply and create demand:

bash

python3 scripts/mai.py --data ./buyer.json registry search-products --url http://127.0.0.1:8765 --query "longjing tea" --allow-insecure-localhost --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?" --confirm --allow-insecure-localhost
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 --confirm --allow-insecure-localhost
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 --confirm --allow-insecure-localhost

Merchant agents pull buyer messages and draft orders:

bash

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

Read references/registry-api.md before changing registry integrations.

Public Marketplace Controls#

• Require API keys for merchant push/pull, buyer messages/orders/payment holds, moderation, and payment release/refund.
• Store only salted API key hashes in the registry file.
• Require HTTPS for remote registries. Only http://127.0.0.1 or http://localhost may use --allow-insecure-localhost during local development.
• Require explicit confirmation for registry writes: CLI --confirm or OpenClaw plugin confirm=true.
• Keep registry push catalog-only by default; use --include-orders only after reviewing the destination and migration intent.
• Allow public search, but rate-limit every request by API key or client IP.
• Treat products with high risk scores as pending_review; do not show them in search until an admin approves them.
• Use registry payment-hold only as PSP-backed custody tracking. The bundled demo provider is not real money movement.
• Require an admin key for registry payment-release and registry payment-refund.
• Do not claim escrow, payment success, release, or refund unless the PSP adapter or external evidence confirms it.

Merchant Workflow#

1. Create or identify the merchant profile: python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags "A,B"
2. Publish products: python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N
3. Adjust stock after physical changes: python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "restock or correction"
4. Record important buyer questions and seller replies: python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text "..."
5. Quote and confirm orders only when inventory and terms are clear: python3 scripts/mai.py order quote ... python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant

Buyer Workflow#

1. Discover merchants: python3 scripts/mai.py search merchants --query "tea hangzhou" --format json
2. Search products: python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json
3. Compare shortlisted SKUs: python3 scripts/mai.py compare --skus sku-a,sku-b --format json
4. Inspect reviews: python3 scripts/mai.py review list --merchant ID --format json
5. Record discussion before ordering: python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text "..."
6. Create a draft order after buyer confirmation: python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N

Transaction Model#

Mai tracks transactions without custody:

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

Disputes can move through:

disputed -> resolved/refunded/cancelled

Stock is reserved when an order becomes confirmed. Local-only payments are recorded as payment_url and payment_reference. Registry payments are PSP custody records; the agent must say the bundled demo provider is not real escrow or money movement.

Read references/transaction-model.md when handling non-happy-path order, refund, dispute, or payment questions. Read references/data-schema.md when integrating Mai with a future hosted marketplace or sync service.

Output Expectations#

For product discovery, answer with:

• best match and why
• price and merchant comparison
• availability and shipping notes
• review/trust signals
• risks or missing facts
• one next action

For merchant operations, answer with:

• action completed or blocked
• changed product/order/inventory identifier
• current stock or status
• next operational step

For order updates, answer with:

• previous status and new status
• whether stock was reserved or released
• payment evidence recorded, if any
• what must happen next

Verification#

Before claiming the package is ready:

• 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
• Confirm SKILL.md has no scaffold placeholders.
• Confirm README.md, package.json, clawhub.json, plugins/mai-plugin/openclaw.plugin.json, and agents/openai.yaml use the mai and mai-plugin names consistently.