榴莲去哪儿了 · 对外产品文档

工具集产品说明书 v1.0

版本：1.0 ｜ 发布日期：2026-09-24
适用对象：通用 Agent 开发者、平台接入方、产品技术团队
定位：榴莲垂直能力的原子工具集，供外部 Agent 调用完成"选一颗→交付→售后"全流程
目录
  1. 工具集定位与价值主张
  2. 工具架构：四个原子能力
  3. recommend · 智能推荐
  4. find_stores · 门店发现
  5. store_pick · 选一颗
  6. fulfillment · 履约管理
  7. 调用流程与上下文传递
  8. 信用闸门与 SLA
  9. 接入方式
  10. 典型场景示例
  11. 边界与限制

一、工具集定位与价值主张

一句话：我们不做通用 Agent，我们做被通用 Agent 调用的榴莲垂直工具。
定位：稀缺物理供给 + 兑现信用，不是对话体验。
我们提供什么
四个原子 Tool：recommend / find_stores / store_pick / fulfillment，覆盖"推荐→发现→选品→履约"全链路
我们不做什么
不做对话界面、不做用户身份管理、不做支付——这些是通用 Agent 的事

核心价值

维度说明
稀缺供给6万亩30年老树 + 自建工厂，顶级猫山王/黑刺产能约 60% 可控
果级证据一果一码，批次溯源，糖度/房数/落果时间可验证
兑现信用不熟包退、36小时履约、错误承诺 <5%
门店网络4000+ 水果店可逐家激活，就近交付

二、工具架构：四个原子能力

recommend
基于用户偏好和当前场景，推荐适合的商品（哪颗/哪批）
find_stores
查找附近有货、可履约的门店
store_pick
在指定门店内选一颗具体商品（果级选择）
fulfillment
管理交付：到店/配送/改期/售后
调用顺序：recommend → find_stores → store_pick → fulfillment
设计原则：每个 Tool 独立可调用，但组合使用时效果最佳。上下文通过 request_id 贯穿，保证全链路可追踪。

R
recommend
智能推荐 · 基于偏好和场景推荐商品

职责

根据用户本次需求（occasion/taste/budget/time）和授权偏好，返回适合的商品候选，附带"为什么是这颗"的依据。

输入参数

字段类型必填说明
occasionstring否场景：家庭聚餐/送礼/自吃/...
taste_preferencestring否口味：偏甜/微苦/绵密/...
frozen_okboolean否是否接受冷冻品
budget_rangeobject否{min, max} 价格区间（元）
eat_timedatetime否计划食用时间
locationobject否{lat, lng} 或 {city, district}
user_preferencesarray否授权的历史偏好（来自上下文）
headcountinteger否食用人数，影响规格推荐

返回结构

"candidates": [
  {
    "product_id": "musangking_batch_20260920_A1",
    "type": "猫山王·冷冻整果",
    "price": 398,
    "weight_range": "1.8-2.2kg",
    "evidence": {
      "drop_date": "2026-09-20",
      "brix_range": "38-42",
      "origin": "彭亨州·Raub产区",
      "cert_ref": "MY-ORG-2026-0920-A1"
    },
    "rationale": "适合家庭聚餐，偏甜口味，冷冻品可保存7天",
    "talk_track": "这款猫山王9月20日落果，糖度38-42度，适合4-6人家庭分享，冷冻锁鲜可保存7天。"
  }
],
"request_id": "req_20260924_abc123"

约束与纪律

F
find_stores
门店发现 · 查找附近有货可履约的门店

职责

基于推荐结果和用户位置，返回有库存、可履约的门店列表。

输入参数

字段类型必填说明
product_idstring是来自 recommend 的商品 ID
locationobject是{lat, lng} 或 {city, district}
radius_kminteger否搜索半径，默认 10km
delivery_typestring否pickup / delivery / both
request_idstring是链路追踪 ID

返回结构

"stores": [
  {
    "store_id": "store_shenyang_hunan_001",
    "name": "鲜果时光·浑南店",
    "distance_km": 2.3,
    "stock": 3, // 该商品可售数量
    "available_slots": ["今日18:00前", "明日10:00-12:00"],
    "services": ["到店自提", "3km内配送", "开果服务"],
    "rating": 4.8,
    "fulfillment_sla": {
      "response_median_min": 3,
      "error_rate": 0.02
    }
  }
],
"request_id": "req_20260924_abc123"

约束与纪律

P
store_pick
选一颗 · 在门店内选择具体商品

职责

在指定门店内，为用户锁定一颗具体商品（果级选择），生成服务单。

输入参数

字段类型必填说明
store_idstring是来自 find_stores
product_idstring是来自 recommend
selection_preferencestring否"最大/最小/随机/糖度最高"
delivery_slotstring是来自门店 available_slots
request_idstring是链路追踪 ID

返回结构

"service_order": {
  "service_order_id": "so_20260924_xyz789",
  "store_id": "store_shenyang_hunan_001",
  "product_id": "musangking_batch_20260920_A1",
  "fruit_id": "fruit_A1_007", // 具体哪一颗
  "weight_kg": 2.05,
  "price": 408,
  "delivery_slot": "今日18:00前",
  "lock_until": "2026-09-24T15:30:00+08:00", // 预留截止时间
  "status": "locked"
},
"request_id": "req_20260924_abc123"

约束与纪律

F
fulfillment
履约管理 · 交付、改期、售后

职责

管理 service_order 的生命周期：确认支付、跟踪交付、处理改期/取消、售后赔付。

主要动作

action说明关键参数
confirm_payment确认支付（对接外部支付回调）service_order_id, payment_ref
get_status查询履约状态service_order_id
reschedule改期service_order_id, new_slot
cancel取消service_order_id, reason
report_issue报品质问题service_order_id, issue_type, evidence
resolve_issue售后处理结果issue_id, resolution (refund/replace/compensate)

返回结构（get_status 示例）

"service_order": {
  "service_order_id": "so_20260924_xyz789",
  "status": "delivering", // locked/paid/preparing/delivering/delivered/completed
  "events": [
    {"time": "2026-09-24T14:00", "event": "已付款"},
    {"time": "2026-09-24T14:30", "event": "门店备货中"},
    {"time": "2026-09-24T16:00", "event": "骑手已取货"}
  ],
  "estimated_arrival": "2026-09-24T17:30"
}

约束与纪律

三、调用流程与上下文传递

标准购买流程

// 用户说："周六和家人吃，帮我选一颗榴莲" // 1. 通用 Agent 调用 recommend recommend({
  occasion: "家庭聚餐",
  eat_time: "2026-09-27T18:00",
  headcount: 4,
  location: {city: "沈阳", district: "浑南"}
})
→ 返回 candidates[0].product_id = "musangking_batch_20260920_A1" // 2. 调用 find_stores find_stores({
  product_id: "musangking_batch_20260920_A1",
  location: {lat: 41.72, lng: 123.45},
  radius_km: 5
})
→ 返回 stores[0].store_id = "store_shenyang_hunan_001" // 3. 调用 store_pick store_pick({
  store_id: "store_shenyang_hunan_001",
  product_id: "musangking_batch_20260920_A1",
  delivery_slot: "今日18:00前",
  request_id: "req_20260924_abc123"
})
→ 返回 service_order_id = "so_20260924_xyz789" // 4. 用户确认支付 → 通用 Agent 调用 fulfillment.confirm_payment fulfillment({
  action: "confirm_payment",
  service_order_id: "so_20260924_xyz789",
  payment_ref: "wx_pay_20260924_456"
}) // 5. 后续查询/改期/售后都通过 fulfillment 接口

上下文传递规则

上下文类型传递方式用途
request_id每次调用必传全链路追踪，保证幂等
user_preferencesrecommend 输入个性化推荐（来自用户授权）
rationalerecommend 输出供通用 Agent 讲给用户听
service_order_idstore_pick 输出，fulfillment 输入订单锚点，关联原渠道单号

四、信用闸门与 SLA

核心纪律："有依据、能兑现"是整条链的信用闸门。
承诺前校验，不是承诺后补救。

三道闸门

闸门检查内容不达标处理
证据门批次/检验记录真实存在且未过期不展示该商品
可售门实时库存 + 门店营业 + 时段可约标灰/不返回
承诺门门店端在 SLA 内确认可交付不承诺时间

SLA 指标

指标目标值说明
门店操作时长≤30 秒店员确认库存/时段的操作时间
响应中位数≤5 分钟门店对调用请求的响应时间
错误可售承诺率<5%承诺了但兑现不了的比例
售后受理时效≤24 小时report_issue 后首次响应时间
赔付兑现率100%符合赔付条件的 100% 兑现
红线：连续 7 天错误承诺率 >5% 的门店，自动暂停承诺能力，直至整改验收通过。

五、接入方式

方式适用场景接入复杂度
MCP 协议豆包、千问等支持 MCP 的 Agent低（标准协议）
RESTful API自建系统、微信小微中（需签名认证）
SDK深度集成场景中（Python/Node/Go）

认证与鉴权

六、典型场景示例

场景 1：日常购买（主线）

用户："帮我选一颗榴莲，今晚吃。"

流程：recommend → find_stores → store_pick → fulfillment

关键：一人一颗，独立交付，复购率是北极星。

场景 2：改期

用户："昨天那颗榴莲，帮我改到明天。"

流程：fulfillment(action=reschedule, service_order_id=xxx)

关键：通过 service_order_id 找到原单，不依赖用户复述。

场景 3：品质问题

用户："这颗榴莲不熟，怎么退？"

流程：fulfillment(action=report_issue, service_order_id=xxx, issue_type="not_ripe")

关键：不熟包退，100% 兑现，issue_id 全程追踪。

七、边界与限制

我们不做的事

什么情况下会失败

失败类型返回调用方处理建议
无合适商品candidates: []告知用户"当前无适合选择"，不强推
附近无门店stores: []扩大 radius 或建议配送
库存不足stock: 0返回"已售罄"，不虚假承诺
门店超时未响应timeout error降级到其他门店或告知用户稍后重试
售后不符合条件issue_rejected + reason明确告知原因，不强行赔付
核心纪律：宁可失败，也不虚假承诺。一次失信，永久失去调用方信任。