Mai
Visão Geral
A Mai ajuda compradores e comerciantes a completar a correspondência de compras através de um agente de IA. Ela mantém o estado determinístico do marketplace em scripts/mai.py, enquanto o modelo hospedeiro lida com linguagem natural, negociação, resumos e explicações de risco.
A Mai pode ser executada apenas localmente ou com suporte de registro. Use o modo local para um catálogo privado de um único agente. Use a descoberta com suporte de registro quando compradores e comerciantes estiverem em máquinas ou perfis de agente diferentes.
Princípios Operacionais
- Seja neutro entre comprador e comerciante. Explique opções, preços, sinais de avaliação, inventário e compensações sem inventar disponibilidade.
- Trate os pagamentos como externos ou suportados por PSP. A Mai nunca retém fundos diretamente. O modo local registra URLs de pagamento e referências; o modo registro registra eventos de custódia do PSP e não deve reivindicar sucesso sem evidência do PSP ou externa.
- Confirme antes de etapas irreversíveis. Peça confirmação do comprador antes de criar um pedido e confirmação do comerciante antes de reservar estoque.
- Preserve o contexto de negociação. Grave mensagens importantes do comprador/comerciante com
message addantes de formar ou atualizar um pedido. - Exponha o risco claramente: sem avaliações, estoque baixo, falta de contato do comerciante, saltos de status incomuns, termos de pagamento pouco claros e promessas de reembolso não suportadas.
- Prefira respostas curtas e acionáveis: recomendação, motivo, risco, próxima ação.
Início Rápido
Use o auxiliar CLI para estado determinístico:
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
Caminho de dados padrão: ~/.local/share/mai/mai.json.
Use --data /path/to/mai.json para um banco de dados local do projeto ou de teste.
Instalação
Instale o par OpenClaw publicado:
clawhub --workdir ~/.openclaw/workspace --dir skills install mai
openclaw plugins install clawhub:mai-plugin
mai é a habilidade. mai-plugin é uma ponte nativa OpenClaw leve e opcional para ferramentas e suporte ao comando /mai.
Instalação com checkout local:
cd /Users/jianghaidong/coding/mai
bash scripts/install.sh --both
Instale apenas um ecossistema:
bash scripts/install.sh --openclaw
bash scripts/install.sh --hermes
O instalador cria links simbólicos:
- OpenClaw:
~/.openclaw/workspace/skills/mai - Hermes:
~/.hermes/skills/commerce/mai
Após a instalação, reinicie o agente hospedeiro se ele não atualizar as habilidades automaticamente. O Hermes pode pré-carregar a Mai com hermes -s mai.
Descoberta com Registro
Execute um marketplace com registro:
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
Os agentes comerciantes publicam a oferta local:
python3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token
Os agentes compradores descobrem a oferta e criam demanda:
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
Os agentes comerciantes puxam as mensagens dos compradores e rascunham pedidos:
python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a
Leia references/registry-api.md antes de alterar as integrações de registro.
Controles do Marketplace Público
- Exija chaves de API para push/pull do comerciante, mensagens/pedidos/retenções de pagamento do comprador, moderação e liberação/reembolso de pagamentos.
- Armazene apenas hashes de chaves de API com sal no arquivo de registro.
- Permita pesquisa pública, mas limite a taxa de cada solicitação por chave de API ou IP do cliente.
- Trate produtos com pontuações de risco altas como
pending_review; não os mostre na pesquisa até que um administrador os aprove. - Use
registry payment-holdapenas como rastreamento de custódia suportado por PSP. O provedordemoincluído não é movimentação de dinheiro real. - Exija uma chave de administrador para
registry payment-releaseeregistry payment-refund. - Não reivindique garantia, sucesso de pagamento, liberação ou reembolso a menos que o adaptador PSP ou evidência externa confirme.
Fluxo de Trabalho do Comerciante
- Crie ou identifique o perfil do comerciante:
python3 scripts/mai.py merchant create --id ID --name NAME --city CIDADE --contact CONTATO --tags "A,B" - Publique produtos:
python3 scripts/mai.py product add --merchant ID --sku SKU --title TÍTULO --price N --stock N - Ajuste o estoque após alterações físicas:
python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "reabastecimento ou correção" - Registre perguntas importantes dos compradores e respostas dos vendedores:
python3 scripts/mai.py message add --buyer COMPRADOR --merchant ID --sku SKU --sender merchant --text "..." - Faça orçamentos e confirme pedidos apenas quando o inventário e os termos estiverem claros:
python3 scripts/mai.py order quote ...python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant
Fluxo de Trabalho do Comprador
- Descubra comerciantes:
python3 scripts/mai.py search merchants --query "tea hangzhou" --format json - Pesquise produtos:
python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json - Compare SKUs pré-selecionados:
python3 scripts/mai.py compare --skus sku-a,sku-b --format json - Inspecione avaliações:
python3 scripts/mai.py review list --merchant ID --format json - Registre a discussão antes de pedir:
python3 scripts/mai.py message add --buyer COMPRADOR --merchant ID --sku SKU --text "..." - Crie um rascunho de pedido após a confirmação do comprador:
python3 scripts/mai.py order create --buyer COMPRADOR --merchant ID --sku SKU --quantity N
Modelo de Transação
A Mai rastreia transações sem custódia:
rascunho -> orçado -> confirmado -> pagamento_pendente -> pago_externo -> atendido -> concluído
As disputas podem passar por:
disputado -> resolvido/reembolsado/cancelado
O estoque é reservado quando um pedido se torna confirmado. Pagamentos apenas locais são registrados como payment_url e payment_reference. Pagamentos com registro são registros de custódia PSP; o agente deve dizer que o provedor demo incluído não é garantia ou movimentação de dinheiro real.
Leia references/transaction-model.md ao lidar com pedidos, reembolsos, disputas ou perguntas de pagamento fora do caminho feliz.
Leia references/data-schema.md ao integrar a Mai com um futuro marketplace hospedado ou serviço de sincronização.
Expectativas de Saída
Para descoberta de produtos, responda com:
- melhor correspondência e por quê
- comparação de preço e comerciante
- notas de disponibilidade e envio
- sinais de avaliação/confiança
- riscos ou informações faltantes
- uma próxima ação
Para operações do comerciante, responda com:
- ação concluída ou bloqueada
- identificador do produto/pedido/inventário alterado
- estoque ou status atual
- próximo passo operacional
Para atualizações de pedido, responda com:
- status anterior e novo status
- se o estoque foi reservado ou liberado
- evidência de pagamento registrada, se houver
- o que deve acontecer a seguir
Verificação
Antes de afirmar que o pacote está pronto:
python3 scripts/mai.py --helppython3 scripts/mai_registry.py --helpbash scripts/install.sh --both --dry-runpython3 -m unittest discover -s testsbash scripts/verify.sh- Confirme que
SKILL.mdnão tem placeholders de esqueleto. - Confirme que
README.md,package.json,clawhub.json,plugins/mai-plugin/openclaw.plugin.jsoneagents/openai.yamlusam os nomesmaiemai-pluginde forma consistente.