Mai

¿Qué hace Mai?

Resumen

Mai ayuda a compradores y comerciantes a completar el emparejamiento de compras a través de un agente de IA. Mantiene el estado determinista del marketplace en scripts/mai.py mientras que el modelo anfitrión maneja el lenguaje natural, la negociación, los resúmenes y las explicaciones de riesgo.

Mai puede ejecutarse en modo local o con respaldo de registro (registry-backed). Usa el modo local para un catálogo privado de un solo agente. Usa el modo con descubrimiento por registro cuando compradores y comerciantes están en diferentes máquinas o perfiles de agente.

Principios Operativos

• Sé neutral entre comprador y comerciante. Explica opciones, precios, señales de reseñas, inventario y compensaciones sin inventar disponibilidad.
• Trata los pagos como externos o respaldados por PSP. Mai nunca retiene fondos directamente. El modo local registra URLs de pago y referencias; el modo registro registra eventos de custodia del PSP y no debe reclamar éxito sin evidencia del PSP o externa.
• Confirma antes de pasos irreversibles. Solicita confirmación del comprador antes de crear un pedido y confirmación del comerciante antes de reservar stock.
• Preserva el contexto de negociación. Registra mensajes importantes del comprador/comerciante con message add antes de formar o actualizar un pedido.
• Expone los riesgos claramente: sin reseñas, stock bajo, falta de contacto del comerciante, saltos de estado inusuales, términos de pago poco claros y promesas de reembolso no soportadas.
• Prefiere respuestas cortas y procesables: recomendación, motivo, riesgo, siguiente acción.

Inicio Rápido

Usa el ayudante CLI para el estado determinista:

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

Ruta de datos predeterminada: ~/.local/share/mai/mai.json. Usa --data /path/to/mai.json para una base de datos local del proyecto o de prueba.

Instalación

Instala el par publicado de OpenClaw:

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

mai es la habilidad. mai-plugin es un puente nativo ligero opcional de OpenClaw para herramientas y soporte del comando /mai.

Instalación desde checkout local:

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

Instalar solo un ecosistema:

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

El instalador crea enlaces simbólicos:

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

Después de la instalación, reinicia el agente anfitrión si no actualiza las habilidades automáticamente. Hermes puede precargar Mai con hermes -s mai.

Descubrimiento por Registro

Ejecuta un marketplace con 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

Los agentes comerciantes publican su oferta local:

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

Los agentes compradores descubren oferta y crean 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 "¿Se puede enviar hoy?"
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

Los agentes comerciantes obtienen mensajes de compradores y borradores de pedidos:

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

Lee references/registry-api.md antes de cambiar las integraciones del registro.

Controles del Marketplace Público

• Exige claves API para push/pull de comerciantes, mensajes/pedidos/retenciones de pago de compradores, moderación y liberación/reembolso de pagos.
• Almacena solo hashes salados de las claves API en el archivo de registro.
• Permite búsqueda pública, pero limita la tasa de cada solicitud por clave API o IP del cliente.
• Trata los productos con puntuaciones de riesgo altas como pending_review; no los muestres en la búsqueda hasta que un administrador los apruebe.
• Usa registry payment-hold solo como seguimiento de custodia respaldado por PSP. El proveedor demo incluido no es movimiento de dinero real.
• Requiere una clave de administrador para registry payment-release y registry payment-refund.
• No reclames depósito en garantía, éxito de pago, liberación o reembolso a menos que el adaptador PSP o evidencia externa lo confirmen.

Flujo de Trabajo del Comerciante

1. Crear o identificar el perfil del comerciante: python3 scripts/mai.py merchant create --id ID --name NOMBRE --city CIUDAD --contact CONTACTO --tags "A,B"
2. Publicar productos: python3 scripts/mai.py product add --merchant ID --sku SKU --title TÍTULO --price N --stock N
3. Ajustar stock después de cambios físicos: python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "reabastecimiento o corrección"
4. Registrar preguntas importantes de compradores y respuestas de vendedores: python3 scripts/mai.py message add --buyer COMPRADOR --merchant ID --sku SKU --sender merchant --text "..."
5. Cotizar y confirmar pedidos solo cuando el inventario y los términos estén claros: python3 scripts/mai.py order quote ... python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant

Flujo de Trabajo del Comprador

1. Descubrir comerciantes: python3 scripts/mai.py search merchants --query "té hangzhou" --format json
2. Buscar productos: python3 scripts/mai.py search products --query "longjing regalo" --max-price 100 --format json
3. Comparar SKU preseleccionados: python3 scripts/mai.py compare --skus sku-a,sku-b --format json
4. Inspeccionar reseñas: python3 scripts/mai.py review list --merchant ID --format json
5. Registrar discusión antes de pedir: python3 scripts/mai.py message add --buyer COMPRADOR --merchant ID --sku SKU --text "..."
6. Crear un borrador de pedido después de la confirmación del comprador: python3 scripts/mai.py order create --buyer COMPRADOR --merchant ID --sku SKU --quantity N

Modelo de Transacción

Mai rastrea transacciones sin custodia:

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

Las disputas pueden moverse a través de:

disputed -> resolved/refunded/cancelled

El stock se reserva cuando un pedido se vuelve confirmed. Los pagos en modo local se registran como payment_url y payment_reference. Los pagos por registro son registros de custodia del PSP; el agente debe decir que el proveedor demo incluido no es depósito en garantía ni movimiento de dinero real.

Lee references/transaction-model.md al manejar pedidos, reembolsos, disputas o preguntas de pago que no sigan la ruta feliz.

Lee references/data-schema.md al integrar Mai con un marketplace alojado futuro o un servicio de sincronización.

Expectativas de Salida

Para descubrimiento de productos, responde con:

• mejor coincidencia y por qué
• comparación de precios y comerciantes
• notas de disponibilidad y envío
• señales de reseñas/confianza
• riesgos o datos faltantes
• una siguiente acción

Para operaciones de comerciante, responde con:

• acción completada o bloqueada
• identificador de producto/pedido/inventario cambiado
• stock o estado actual
• siguiente paso operativo

Para actualizaciones de pedidos, responde con:

• estado anterior y nuevo estado
• si el stock fue reservado o liberado
• evidencia de pago registrada, si la hay
• qué debe suceder a continuación

Verificación

Antes de reclamar que el paquete está listo:

• 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
• Confirmar que SKILL.md no tenga marcadores de posición de plantilla.
• Confirmar que README.md, package.json, clawhub.json, plugins/mai-plugin/openclaw.plugin.json y agents/openai.yaml usen los nombres mai y mai-plugin de manera consistente.