# Moras Commerce Runtime Layer

SellToAI（前身 Moras A2A，K2Lab 旗下）的下一层不是“再做一个购物 Agent”，而是把外部 Agent、商家、内容资产、支付与归因系统编排成可审计的 **Agentic Commerce Runtime**。

---

## 1. 分层模型

Moras Commerce Runtime 借鉴 Hermes Agent 的工程骨架：入口适配、Gateway、Agent 主循环、记忆、技能、自我修复/复盘。

对应到电商交易链路：

1. **External Agents & Channels**：GPT、Gemini、Hermes、OpenClaw、微信、飞书、购物平台、商家系统、支付网络。
2. **Adapter Layer**：User Agent Adapter、Merchant Agent Adapter、Content/MAP Adapter、Payment Adapter、Channel Adapter。
3. **Intent Gateway**：统一外部输入为标准 Intent，包含预算、时间窗口、约束、资产引用和用户授权。
4. **Commerce Agent Loop**：Asset Agent、Merchant Agent、Trust Agent、Deal Agent、Feedback Agent 共同生成可信成交提案。
5. **Protocol Memory & Skills**：沉淀用户偏好、商家信誉、内容资产、历史成交和 Commerce SOP。
6. **Settlement & Audit Layer**：通过 Commerce Proposal、MatchToken、Attribution Chain、Risk/Audit、Commission/Settlement 闭环。

---

## 2. 新协议原语

本 PR 先把 Runtime Layer 做成轻量协议字段，不立即新增 SQL 表，继续沿用 `metadata` 兼容模式。

### runtime_session

一次 Commerce Agent Loop 的运行上下文：

- `runtime_id`：运行时会话 ID。
- `entry_agent_id`：入口 Agent，例如 GPT/Hermes/微信 Agent。
- `mode`：运行模式，例如 `assisted_checkout`。
- `stage`：当前阶段，例如 `intent_received`、`proposal_ready`。

### agent_steps

审计型 Agent 步骤列表：

- Intent normalize
- Asset evidence collect
- Merchant quote
- Trust check
- Proposal rank
- MatchToken issue
- Feedback record

### commerce_budget

Agentic Commerce 的治理预算：

- `max_agent_iterations`
- `max_merchant_queries`
- `max_proposal_versions`
- `require_user_confirmation_before_payment`

### commerce_memory_refs

协议级记忆引用：

- `user_taste_memory`
- `merchant_trust_memory`
- `asset_memory`
- `deal_memory`

### skill_refs

本次交易使用的 Commerce Skills / SOP，例如企业采购 SOP、达人选品 SOP、私域团购 SOP。

### runtime_trace

可审计运行轨迹：

- `loop`：Intent → Evidence → Candidates → Trust Check → Proposal → Decision → MatchToken → Feedback。
- `current_step`
- `audit_status`

---

## 3. API

### POST /v1/commerce-runtime

运行一次最小 Commerce Runtime 闭环：

1. 创建 Intent。
2. 创建 Proposal。
3. 创建 Match Session。
4. 签发 MatchToken。
5. 返回完整 runtime trace。

请求主体包含：

- `intent`
- `runtime_session`
- `agent_steps`
- `commerce_budget`
- `commerce_memory_refs`
- `skill_refs`
- `proposal`

响应主体包含：

- `runtime_session`
- `intent`
- `proposal`
- `match_session`
- `match_token`
- `agent_steps`
- `commerce_budget`
- `commerce_memory_refs`
- `skill_refs`
- `runtime_trace`

---

## 4. A2A / MCP 暴露

Agent Card 新增 capability：

- `commerce_runtime: true`

Agent Card 新增 skill：

- `run_commerce_runtime`

MCP 新增 tool：

- `run_commerce_runtime`

这让外部 GPT/Gemini/Hermes/OpenClaw 不只提交意图，也可以请求 Moras 运行一条可审计的交易循环。

---

## 5. MatchToken 审计增强

MatchToken 的 `trace_ids` 现在携带：

- `runtime_id`
- `runtime_stage`
- `audit_status`
- `skill_refs`

这样 MatchToken 不只是“匹配凭证”，也能作为投资人叙事里的交易审计凭证：谁发起、谁参与、走了哪些 SOP、是否满足支付前用户确认边界。

---

## 6. 当前边界

- Runtime 字段暂存 `metadata`，保持现有 MySQL schema 兼容。
- `commerce_budget` 初版主要是协议表达与审计，不阻断所有业务动作。
- `commerce_memory_refs` 当前是引用，不直接读取外部记忆库。
- 后续可把 agent steps、runtime sessions、commerce skills 拆成独立表，用于查询、回放与训练。