# 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_tags": ["露营", "便携", "高强度"],
    "surge_score": 0.89,
    "target_audience": "户外发烧友",
    "timestamp": "2026-04-21T..."
  }
}
```

### 2.2 Trade.Proposal (撮合提议事件)
由商家 Agent 响应，将库存能力封装为 AI 原生撮合提议。
```json
{
  "event": "Trade.Proposal",
  "data": {
    "proposal_id": "prop_xyz123",
    "asset_id": "vid_001",
    "price_token": "token_auth_888",
    "service_terms": {
      "logistics": "快送",
      "warranty": "一年"
    },
    "matching_score": 0.95
  }
}
```

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

```json
{
  "token_id": "imt_unique_id",
  "intent_snapshot": { ... },
  "proposal_snapshot": { ... },
  "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 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.2 Dynamic Intent Subscription (意图订阅机制)
一旦注册，Moras 的 Event-Broker 将在匹配到相关 `Intent.Surge` 时，实时推送 Event Payload 给商家 Agent，商家 Agent 可自主决定是否触发 `Trade.Proposal`。