云锦鸿文档

Appearance

Agent 交互协议（Barter Zone × OpenClaw） ​

版本: v1.0 | 日期: 2026-05-18 | 关联 PRD: v2.0

一、概述 ​

本文档定义 Barter Zone 系统与 OpenClaw Agent 之间的交互协议，涵盖物品分析、智能匹配、多跳交换链发现和智能估值四大核心能力。

1.1 通信模式 ​

  • 同步调用：物品分析、单次匹配查询（用户等待结果）
  • 异步调用：全库匹配扫描、多跳链发现（后台任务 + 推送通知）
  • 协议格式：JSON over HTTPS（REST API）
  • 认证方式：Bearer Token（服务端到服务端）

1.2 错误处理 ​

所有 Agent 响应遵循统一错误格式：

json
{
  "code": "AGENT_ERROR",
  "message": "描述信息",
  "details": {}
}
错误码说明处理策略
AGENT_TIMEOUTAgent 响应超时（>10s）重试 1 次，仍失败则返回默认结果
AGENT_RATE_LIMIT请求频率超限排队等待后重试
AGENT_INVALID_INPUT输入参数无效返回 400 给前端
AGENT_SERVICE_ERRORAgent 服务内部错误降级处理，返回缓存/默认结果
AGENT_NO_MATCH无匹配结果正常返回空数组

二、物品分析（Analyze） ​

2.1 请求 ​

POST /api/agent/analyze
json
{
  "image_urls": [
    "https://storage.example.com/item1_001.jpg",
    "https://storage.example.com/item1_002.jpg"
  ],
  "title_hint": "iPhone 14 Pro",
  "description_hint": "九成新，无磕碰"
}
字段类型必填说明
image_urlsstring[]是物品图片 URL（1~9 张）
title_hintstring否用户已填的标题，辅助识别
description_hintstring否用户已填的描述，辅助识别

2.2 响应 ​

json
{
  "success": true,
  "data": {
    "category": "数码",
    "sub_category": "手机",
    "brand": "Apple",
    "model": "iPhone 14 Pro",
    "condition": "95新",
    "condition_score": 0.95,
    "tags": ["数码", "手机", "苹果", "iPhone", "5G"],
    "estimated_value": {
      "min": 3500,
      "max": 4200,
      "currency": "CNY",
      "confidence": 0.85
    },
    "key_features": [
      "256GB 存储",
      "暗紫色",
      "原装配件"
    ],
    "safety_check": {
      "passed": true,
      "risk_level": "low",
      "flags": []
    },
    "confidence": 0.92,
    "processing_time_ms": 1200
  }
}

2.3 字段说明 ​

字段类型说明
categorystring一级分类（数码/家居/图书/服饰/运动/母婴/其他）
sub_categorystring二级分类
brandstring?品牌识别结果
modelstring?具体型号
conditionstring成色描述（全新/99新/95新/9新/8新/7新及以下）
condition_scorenumber成色评分（0~1）
tagsstring[]AI 自动提取的标签（≤10 个）
estimated_valueobject估值区间
key_featuresstring[]关键特征列表
safety_checkobject安全检查结果
confidencenumber整体识别置信度（0~1）

三、智能匹配（Match） ​

3.1 单物品匹配 ​

POST /api/agent/match
json
{
  "item_id": "item_abc123",
  "strategy": "balanced",
  "limit": 20
}
字段类型必填说明
item_idstring是待匹配物品 ID
strategystring否匹配策略：balanced(默认) / value_priority / quick_swap
limitnumber否返回数量上限，默认 20

匹配策略说明 ​

策略权重分配适用场景
balanced标签40% + 估值30% + 热度20% + 距离10%默认推荐
value_priority估值50% + 标签30% + 热度10% + 距离10%高价值物品
quick_swap热度40% + 距离30% + 标签20% + 估值10%快速成交

响应 ​

json
{
  "success": true,
  "data": {
    "matches": [
      {
        "item_id": "item_def456",
        "score": 0.87,
        "match_type": "direct",
        "reason": "对方想要的「手机」与你发布的「iPhone 14 Pro」高度匹配，估值区间重叠度高",
        "value_overlap": 0.82,
        "tag_match_count": 4,
        "distance_km": 5.2
      },
      {
        "item_id": "item_ghi789",
        "score": 0.75,
        "match_type": "chain",
        "chain_path": [
          {
            "item_id": "item_abc123",
            "user_id": "user_A",
            "wants": ["华为", "手机"]
          },
          {
            "item_id": "item_jkl012",
            "user_id": "user_B",
            "wants": ["数码", "耳机"]
          },
          {
            "item_id": "item_ghi789",
            "user_id": "user_C",
            "wants": ["iPhone", "苹果"]
          }
        ],
        "reason": "发现环形交换链：你的 iPhone → 用户B的耳机 → 用户C的华为 → 你想要的华为",
        "value_overlap": 0.71,
        "chain_length": 3
      }
    ],
    "total": 2,
    "processing_time_ms": 800
  }
}

3.2 全库异步匹配 ​

物品发布后触发后台异步任务：

POST /api/agent/async-match
json
{
  "item_id": "item_abc123",
  "notify_users": true
}

流程：

  1. 消息队列接收任务
  2. Agent 扫描全库 status=available 的物品
  3. 计算双向匹配（A 想要 B 有的，B 也想要 A 有的）
  4. 匹配结果存入 matches 集合
  5. 对 score ≥ 0.7 的匹配推送通知给双方
  6. 匹配结果有效期 7 天，过期后下次触发重新计算

四、多跳交换链（Chain Discovery） ​

4.1 触发条件 ​

  • 用户手动触发：点击「发现更多交换可能」
  • 系统定时触发：每日凌晨 2:00 全量计算
  • 发布触发：新物品发布后异步执行

4.2 请求 ​

POST /api/agent/discover-chains
json
{
  "item_id": "item_abc123",
  "max_depth": 4,
  "min_score": 0.5,
  "limit": 10
}
字段类型必填说明
item_idstring是起始物品 ID
max_depthnumber否最大跳数（3~6），默认 4
min_scorenumber否最小匹配分数，默认 0.5
limitnumber否返回链条数上限，默认 10

4.3 响应 ​

json
{
  "success": true,
  "data": {
    "chains": [
      {
        "chain_id": "chain_xxx",
        "score": 0.85,
        "length": 3,
        "path": [
          {
            "step": 1,
            "item_id": "item_abc123",
            "user_id": "user_A",
            "item_title": "iPhone 14 Pro",
            "wants": ["华为"],
            "offers": ["iPhone"]
          },
          {
            "step": 2,
            "item_id": "item_jkl012",
            "user_id": "user_B",
            "item_title": "华为 Mate 60",
            "wants": ["耳机"],
            "offers": ["华为"]
          },
          {
            "step": 3,
            "item_id": "item_mno345",
            "user_id": "user_C",
            "item_title": "AirPods Pro 2",
            "wants": ["iPhone"],
            "offers": ["耳机"]
          }
        ],
        "reason": "三方环形交换：A 的 iPhone → B 的华为 → C 的 AirPods → 回到 A 想要的方向",
        "estimated_success_rate": 0.72
      }
    ],
    "total": 1,
    "processing_time_ms": 2500
  }
}

4.4 算法说明 ​

算法: 改进的多跳匹配图搜索

1. 构建交换图 G = (V, E)
   - 节点 V = 所有 status=available 的物品
   - 有向边 (A→B) 存在当且仅当: A 的 want_tags ∩ B 的 ai_tags ≠ ∅

2. 对目标物品 source，执行有向 BFS（最大深度 max_depth）

3. 当 BFS 到达节点 target 且 target.ai_tags ∩ source.want_tags ≠ ∅ 时，
   检查是否存在环形路径 source → ... → target → source

4. 对每条环形路径计算综合评分:
   score = Σ(edge_score) / path_length × value_compatibility × freshness_factor

5. 按 score 降序返回 top-K 链条

优化策略:
- 剪枝：单边 score < 0.3 的边不继续扩展
- 缓存：每日凌晨预计算高频物品的链条
- 并行：同一深度的节点并行处理

五、智能估值（Estimate） ​

5.1 请求 ​

POST /api/agent/estimate
json
{
  "item_id": "item_abc123"
}

5.2 响应 ​

json
{
  "success": true,
  "data": {
    "value_range": {
      "min": 3500,
      "max": 4200,
      "median": 3800,
      "currency": "CNY"
    },
    "confidence": 0.85,
    "factors": [
      { "name": "成色", "impact": "positive", "detail": "95新，状态良好" },
      { "name": "市场行情", "impact": "neutral", "detail": "当前市场均价 ¥3,800" },
      { "name": "配件完整度", "impact": "positive", "detail": "原装配件齐全" },
      { "name": "供需比", "impact": "negative", "detail": "同类物品供给较多" }
    ],
    "similar_items": [
      {
        "item_id": "item_sim001",
        "title": "iPhone 14 Pro 256G 暗紫",
        "final_value": 3700,
        "status": "exchanged"
      }
    ],
    "disclaimer": "AI 估值仅供参考，最终交换价值由双方协商确定"
  }
}

六、安全检查（Safety） ​

6.1 物品安全审核 ​

每次物品创建/编辑时自动触发安全检查，集成在 analyze 接口的 safety_check 字段。

检查维度：

维度说明处理
违禁物品枪支/毒品/假证等直接拦截，禁止发布
虚假图片AI 生成图/网图盗用降权 + 人工审核标记
低俗内容色情/暴力图片直接拦截
价格异常估值与期望严重偏离提醒用户确认
重复发布相似物品短时间多次发布频率限制

6.2 风控规则 ​

用户行为评分模型:

base_score = 100
- 同一内容重复发布: -10/次
- 被拒交换: -2/次
- 好评: +3/次
- 被投诉: -15/次
- 实名认证: +20

触发条件:
- score < 60: 限制发布频率（1件/小时）
- score < 30: 限制交换发起（需人工审核）
- score < 0: 自动封禁

七、性能指标 ​

指标目标告警阈值
单次分析延迟≤ 2s> 5s
单次匹配延迟≤ 1s> 3s
多跳链发现延迟≤ 3s> 8s
异步匹配完成≤ 30s> 60s
全量链计算≤ 2h> 4h
Agent 可用性≥ 99.9%< 99.5%
分析准确率≥ 90%< 85%
匹配点击率≥ 30%< 20%

八、降级策略 ​

故障场景降级方案
Agent 服务不可用物品发布仍可进行，跳过 AI 分析，用户手动填写分类/标签
匹配服务超时返回基于标签的简单匹配结果（SQL 查询替代）
估值服务异常隐藏估值展示，不影响核心流程
全量扫描失败跳过当日异步匹配，不影响已缓存的匹配结果
安全检查异常放行但标记为"待审核"，人工后续复核

由云锦鸿维护

© 2026 云锦鸿信息技术