Mai
개요
Mai는 AI 에이전트를 통해 구매자와 판매자가 쇼핑 매칭을 완료할 수 있도록 돕습니다. 결정론적 마켓플레이스 상태를 scripts/mai.py에 유지하고, 호스트 모델이 자연어, 협상, 요약, 위험 설명을 처리합니다.
Mai는 로컬 전용 또는 레지스트리 기반으로 실행할 수 있습니다. 단일 에이전트의 개인 카탈로그에는 로컬 전용을 사용하세요. 구매자와 판매자가 다른 머신이나 에이전트 프로필에 있는 경우 레지스트리 기반 검색을 사용하세요.
운영 원칙
- 구매자와 판매자 사이에서 중립을 유지하세요. 가용성을 조작하지 않고 옵션, 가격, 리뷰 신호, 재고, 트레이드오프를 설명하세요.
- 결제는 외부 또는 PSP 기반으로 처리하세요. Mai는 직접 자금을 보유하지 않습니다. 로컬 모드는 결제 URL과 참조를 기록하고, 레지스트리 모드는 PSP 보관 이벤트를 기록하며, PSP 또는 외부 증거 없이 성공을 주장하지 마세요.
- 되돌릴 수 없는 단계를 수행하기 전에 확인하세요. 주문을 생성하기 전에 구매자 확인을, 재고를 확보하기 전에 판매자 확인을 요청하세요.
- 협상 맥락을 보존하세요. 주문을 구성하거나 업데이트하기 전에
message add로 중요한 구매자/판매자 메시지를 기록하세요. - 위험을 명확히 표시하세요: 리뷰 없음, 재고 부족, 판매자 연락처 누락, 비정상적인 상태 변경, 불분명한 결제 조건, 지원되지 않는 환불 약속 등.
- 짧고 실행 가능한 답변을 선호하세요: 추천, 이유, 위험, 다음 조치.
빠른 시작
결정론적 상태를 위한 CLI 도우미 사용:
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
기본 데이터 경로: ~/.local/share/mai/mai.json.
프로젝트 로컬 또는 테스트 데이터베이스에는 --data /path/to/mai.json을 사용하세요.
설치
게시된 OpenClaw 쌍 설치:
clawhub --workdir ~/.openclaw/workspace --dir skills install mai
openclaw plugins install clawhub:mai-plugin
mai는 스킬입니다. mai-plugin은 도구 및 /mai 명령 지원을 위한 선택적 경량 OpenClaw 네이티브 브리지입니다.
로컬 체크아웃 설치:
cd /Users/jianghaidong/coding/mai
bash scripts/install.sh --both
하나의 에코시스템만 설치:
bash scripts/install.sh --openclaw
bash scripts/install.sh --hermes
설치 프로그램이 심볼릭 링크를 생성합니다:
- OpenClaw:
~/.openclaw/workspace/skills/mai - Hermes:
~/.hermes/skills/commerce/mai
설치 후, 호스트 에이전트가 자동으로 스킬을 새로고침하지 않으면 다시 시작하세요. Hermes는 hermes -s mai로 Mai를 미리 로드할 수 있습니다.
레지스트리 검색
레지스트리 마켓플레이스 실행:
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
판매자 에이전트가 로컬 공급을 게시:
python3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token
구매자 에이전트가 공급을 검색하고 수요를 생성:
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
판매자 에이전트가 구매자 메시지를 가져오고 주문 초안을 작성:
python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a
레지스트리 통합을 변경하기 전에 references/registry-api.md를 읽으세요.
공개 마켓플레이스 제어
- 판매자 푸시/풀, 구매자 메시지/주문/결제 보류, 중재, 결제 해제/환불에 API 키를 요구하세요.
- 레지스트리 파일에 솔티드 API 키 해시만 저장하세요.
- 공개 검색을 허용하되, 모든 요청을 API 키 또는 클라이언트 IP로 속도 제한하세요.
- 위험 점수가 높은 상품은
pending_review로 처리하고, 관리자가 승인할 때까지 검색에 표시하지 마세요. registry payment-hold는 PSP 기반 보관 추적으로만 사용하세요. 번들로 제공되는demo제공자는 실제 자금 이동이 아닙니다.registry payment-release및registry payment-refund에는 관리자 키가 필요합니다.- PSP 어댑터 또는 외부 증거가 확인하지 않는 한 에스크로, 결제 성공, 해제 또는 환불을 주장하지 마세요.
판매자 워크플로우
- 판매자 프로필 생성 또는 식별:
python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags "A,B" - 상품 게시:
python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N - 물리적 변경 후 재고 조정:
python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "restock or correction" - 중요한 구매자 질문과 판매자 답변 기록:
python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text "..." - 재고와 조건이 명확할 때만 견적 및 주문 확인:
python3 scripts/mai.py order quote ...python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant
구매자 워크플로우
- 판매자 검색:
python3 scripts/mai.py search merchants --query "tea hangzhou" --format json - 상품 검색:
python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json - 후보 SKU 비교:
python3 scripts/mai.py compare --skus sku-a,sku-b --format json - 리뷰 검사:
python3 scripts/mai.py review list --merchant ID --format json - 주문 전 논의 기록:
python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text "..." - 구매자 확인 후 주문 초안 생성:
python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N
거래 모델
Mai는 보관 없이 거래를 추적합니다:
draft -> quoted -> confirmed -> payment_pending -> paid_external -> fulfilled -> completed
분쟁은 다음을 통해 진행될 수 있습니다:
disputed -> resolved/refunded/cancelled
주문이 confirmed가 되면 재고가 예약됩니다. 로컬 전용 결제는 payment_url 및 payment_reference로 기록됩니다. 레지스트리 결제는 PSP 보관 기록입니다. 에이전트는 번들로 제공되는 demo 제공자가 실제 에스크로 또는 자금 이동이 아님을 명시해야 합니다.
비정상 경로 주문, 환불, 분쟁 또는 결제 질문을 처리할 때는 references/transaction-model.md를 읽으세요.
향후 호스팅 마켓플레이스 또는 동기화 서비스와 Mai를 통합할 때는 references/data-schema.md를 읽으세요.
출력 기대치
상품 검색의 경우 다음을 포함하여 답변하세요:
- 최적의 매치와 그 이유
- 가격 및 판매자 비교
- 가용성 및 배송 정보
- 리뷰/신뢰 신호
- 위험 또는 누락된 정보
- 한 가지 다음 조치
판매자 작업의 경우 다음을 포함하여 답변하세요:
- 완료 또는 차단된 작업
- 변경된 상품/주문/재고 식별자
- 현재 재고 또는 상태
- 다음 운영 단계
주문 업데이트의 경우 다음을 포함하여 답변하세요:
- 이전 상태 및 새 상태
- 재고가 예약 또는 해제되었는지 여부
- 기록된 결제 증거(있는 경우)
- 다음에 수행해야 할 작업
검증
패키지가 준비되었다고 주장하기 전에:
python3 scripts/mai.py --helppython3 scripts/mai_registry.py --helpbash scripts/install.sh --both --dry-runpython3 -m unittest discover -s testsbash scripts/verify.shSKILL.md에 스캐폴드 플레이스홀더가 없는지 확인하세요.README.md,package.json,clawhub.json,plugins/mai-plugin/openclaw.plugin.json,agents/openai.yaml에서mai및mai-plugin이름이 일관되게 사용되는지 확인하세요.