# Moras AI 原生电商撮合协议 (Intent-Matching Protocol) - Spec v0.1

## 1. 设计目标
本协议旨在构建供需双方（用户端 Agent 与 商家端 Agent）的“零货架”交互范式。将电商交互从“货架商品检索”转化为“意图匹配与撮合协商”。

## 2. 事件驱动范式 (Event Schema)
供需双方通过 Webhook 或 Broker 交换以下标准化事件：

### 2.1 Intent.Surge (意图爆发事件)
由流量侧 Agent (Moras) 触发，发布给已订阅的商家 Agent。
```json
{
  "event": "Intent.Surge",
  "data": {
    "intent_id": "int_abc123",
    "raw_query": "agent wants pet feeder under 50 before Friday",
    "intent_tags": ["pet", "feeder", "under_50"],
    "budget_range": { "max": 50, "currency": "USD" },
    "time_window": { "deadline": "2026-05-01T00:00:00.000Z", "urgency": "high" },
    "asset_refs": [
      { "type": "creator_video", "id": "vid_001", "evidence_score": 0.82 }
    ],
    "attribution_chain": [
      { "agent_id": "gpt-shopper", "role": "demand_agent", "event": "intent.created" }
    ],
    "workflow": {
      "skill_id": "moras-shop.submit_intent",
      "mcp_tools": ["merchant.registry.lookup"],
      "a2a_peer": "gpt-shopper"
    }
  }
}
```

### 2.2 Trade.Proposal (撮合提议事件)
由商家 Agent 响应，将库存能力封装为 AI 原生撮合提议。
```json
{
  "event": "Trade.Proposal",
  "data": {
    "proposal_id": "prp_xyz123",
    "intent_id": "int_abc123",
    "merchant_agent_id": "mch_001",
    "product_id": "1001",
    "asset_refs": [
      { "type": "pcd", "id": "rec_1001" },
      { "type": "merchant_quote", "id": "quote_1001" }
    ],
    "price": 39.99,
    "inventory_status": "available",
    "service_terms": {
      "logistics": "platform-default",
      "return_window_days": 30
    },
    "trust_score": { "score": 0.87, "basis": ["creator proof", "merchant reputation"] },
    "proposal_state": "quoted",
    "attribution_chain": [
      { "agent_id": "gpt-shopper", "role": "demand_agent", "event": "intent.created" },
      { "agent_id": "moras-core", "role": "commerce_protocol", "event": "proposal.generated" }
    ],
    "workflow": { "skill_id": "moras-shop.submit_proposal", "mcp_tools": ["pcd.lookup"] }
  }
}
```

## 3. 撮合对象模型 (Matching Object)
撮合的核心是 **`IntentMatchingToken`**，它是买卖双方 Agent 达成一致后的原子凭证。

```json
{
  "token_id": "imt_unique_id",
  "intent_snapshot": { "intent_id": "int_abc123", "time_window": { "deadline": "..." } },
  "proposal_snapshot": { "proposal_id": "prp_xyz123", "proposal_state": "quoted", "trust_score": { "score": 0.87 } },
  "trace_ids": {
    "channel": "a2a-gpt",
    "proposal_state": "quoted",
    "attribution_agents": ["gpt-shopper", "moras-core"]
  },
  "status": "READY_TO_EXECUTE",
  "signature": "SHA256_HASH"
}
```

## 4. 落地规划
- **Phase 1**: 在 `src/events/broker.js` 中增加事件发布逻辑，在 `src/pcd/matcher.js` 增加 Intent 识别逻辑（已有 `detectSurge` 雏形）。
- **Phase 2**: 在 `src/rest/` 下新增 `/v1/proposal` 接口，用于商户 Agent 投递 `Trade.Proposal`。
- **Phase 3**: 自动化 Agent 侧调用闭环。

**对外说明**：网关 Portal 的 **/reference** 页提供「意图撮合」小节与 OpenAPI `merchant` 标签；本文件可通过 **GET /docs/INTENT_MATCHING_PROTOCOL.md** 直链阅读。

---

## 5. B 端 Agent 入驻协议 (B-Side Integration)

为了实现“由 KOC 倒逼 B 端上线”，商家 Agent 需遵循以下接入规范。

### 5.1 Commerce Agent Registration (外部 Agent 注册)
任意外部 Agent 可先通过 `/v1/agents/register` 或 `/v1/agents/import-card` 接入通用目录；商家 Agent 仍兼容 `/v1/merchant/register`。

```json
POST /v1/agents/register
{
  "agent_id": "pay_paypal_demo",
  "agent_type": "payment",
  "endpoint": "https://paypal.example/a2a",
  "protocols": ["a2a-jsonrpc", "webhook"],
  "auth_methods": ["signed_webhook", "intent_mandate"],
  "capability_profile": {
    "payment": { "create_checkout": true, "authorize_intent_mandate": true }
  }
}
```

### 5.2 Merchant Agent Registration (商户 Agent 注册)
商家 Agent 也可通过 `/v1/merchant/register` 接口上报能力，以便 Moras 调度。

```json
POST /v1/merchant/register
{
  "merchant_id": "mch_001",
  "agent_endpoint": "https://agent.merchant.com/webhook",
  "subscription_tags": ["露营", "户外"],
  "capabilities": ["stock_check", "price_quote"]
}
```

### 5.3 Dynamic Intent Subscription (意图订阅机制)
一旦注册，Moras 的 Event-Broker 将在匹配到相关 `Intent.Surge` 时，实时推送 Event Payload 给商家 Agent，商家 Agent 可自主决定是否触发 `Trade.Proposal`。