--- name: mcd-deal-hunter description: 麦当劳中国 MCP 的「券 × 商品」到手价优化器。给定想吃的餐品或想用的券,用 calculate-price 做带券/不带券的对照实验,算出真实净省金额与热量代价,输出三栏建议(纯省钱 / 性价比 / 劝退)。Use when 用户问「有什么券能用」「怎么点最便宜」「帮我用券」「这单能省多少」,或在麦当劳下单前想确认优惠是否划算。只做建议,绝不下单或付款。 --- # 券的价值换算 核心洞察:**券本身不含价格。** `query-store-coupons` 只给 `couponId`、`couponCode`、有效期 `tradeDateTime` 和适用商品 `products[].productCode` —— **没有折扣金额**。`title` 是活动名(实测值为「1024"码"力翻倍」),既不是商品名也不是价格。 因此「省多少钱」只有一个可靠来源:`calculate-price` 带券与不带券的**差值**。禁止用券标题、常识或历史价格推断金额。 ## 数据源职责 | 工具 | 给什么 | 陷阱 | |---|---|---| | `auto-bind-coupons` | 一键领光麦麦省全部可领券 | 零成本写操作,先领再谈;不要循环调用 | | `available-coupons` | 可领取券的标题 / 状态 / 图片 | **无 `couponId`**,不能直接用于下单 | | `query-my-coupons` | 卡包里的全部券 | **不承诺本店本单可用**,不可作为选券依据 | | `query-store-coupons` | 本店 + 本取餐方式的可用券,含 `couponId` / `couponCode` / 有效期 / `products[]` | 无金额,必须过 `calculate-price` | | `calculate-price` | 唯一的价格真相 | 金额单位是**分**;对不可售/虚拟 `productCode` 会**静默返回 `price=0` 且 `success:true`**;每次调用计入 600 次/分钟限额 | 选券只认 `query-store-coupons`。用它之外的券去跑价格,会在 `calculate-price` 处失败。 ## 流程 1. **定渠道**(决定 `orderType` / `beCode`,详见 `references/ordering.md`) 2. **拿门店**:自取 / 得来速用 `query-nearby-stores`;外送 / 团餐走 `delivery-query-addresses` → `delivery-query-stores`。收藏门店为空会返回 `600050`,改用 `searchType=2` 并索取城市 + 关键词。 3. **领券**:`auto-bind-coupons` 4. **取可用券**:`query-store-coupons(storeCode, orderType, beType)` 5. **取菜单**:`query-meals(storeCode, orderType, beType[, beCode])`,用 `productCode` 对齐 6. **匹配**:券的 `products[].productCode` ↔ 菜单商品 ↔ 用户想吃的。注意券经常把商品锁成一个**套餐**——此时要么引导用户改买,要么直接说这张券用不上 7. **对照实验**:同一购物车跑两次 `calculate-price`,基线(不带券)与带券,差值即净省 8. **输出**,然后停下等用户确认 ## 输出(面向用户) 只回答三件事:这单多少钱、怎么更省、代价是什么。**第一句就给实付价**,不铺垫。 ``` 1. 纯省钱 <方案> 省 X 元 Y kcal 2. 性价比 <方案> 省 X 元 Z 元/100kcal 3. 劝退 <方案> 省 X 元 但 +N kcal ≈ M 碗米饭 ``` 第三栏是本 skill 的重点:**免费券只免钱,不免热量**。 ### 不许出现在回答里 这些是过程,不是结论: - 字段名与原始值:`productList`、`price=2048`、`couponId`、`orderType`、`takeWayList` - 金额的「分」值 - 对 skill 规则的自述:「按 skill 规定」「通过价格可信性校验」 - 内部预算与余量:「还剩 13 次」 - 工具名、调用顺序、试了几次、哪一步失败过 ### 省钱基准 - **不许拿划线价当基准。** `originalPrice → price` 只能说明「相对标价便宜」,不等于最划算。要讲「省」,必须跟一个**真实可买的替代方案**比(单品自由组合、另一张券、另一个渠道) - 没有真实替代方案可比时,只报实付价,不要硬凑一个「省了 X 元」 - 但前提要一句话交代清楚,例如「这个套餐只能靠券买,单点不卖」 ### 券怎么展示 - 问「这单多少钱」→ 只给**到期时间**。`couponId` 是内部键,不展示 - 问「我有哪些券」→ 才按工具自带的表格展示(含券ID、券码),那是用户管理券的场景 ### 校验失败时用人话 说「这个券在本店买不了」,不要说「`productList` 为空」。 本店无可用券就直说,给出不折腾的基线方案,不要编造优惠。 ## 凑单判断(`enjoyable.balance`) `calculate-price` 返回的 `data.enjoyable.balance` 是**门槛差额**(分):为正表示「还差这么多钱就能拿到 `enjoyable` 描述的优惠」,`enjoyable.realDiscount` 是拿到后的优惠值(元,`amountType` 1=特价 2=折扣 3=立减)。`balance = 0` 表示当前购物车已达标,不需要凑单。 判断方法**不要手算**:加一个凑单品,再跑一次 `calculate-price`,直接比两次的 `price` 字段。省了才算凑;没省就不能建议用户多买。 凑进来的东西同样有热量成本,要进第三栏。 ## 渠道不只是配送费 **每个渠道有自己的商品编码。** 拿自取的码去算外送价,`calculate-price` 不报错 —— 它把不认识的商品**静默丢掉**,返回一个"只有配送费"的假价格。 实测(门店 1421094): | 商品 | 自取码 | 自取价 | 外送码 | 外送价 | 加价 | |---|---|---|---|---|---| | 那么大鸡排(椒盐风味) | `521156` | 14.00 | `521156` | 15.50 | +1.50(+10.7%) | | 麦辣鸡腿汉堡 | `1440` | 22.50 | `901440` | 25.50 | +3.00(+13.3%) | | 巨无霸 | `1100` | 26.50 | `901100` | 29.00 | +2.50(+9.4%) | | 板烧鸡腿堡 | `1406` | 23.50 | `901406` | 26.50 | +3.00(+12.8%) | | 中薯条 → 薯条 | `4810` | 14.00 | `501205` | 15.00 | 换号 | 编码关系**没有统一规律**:多半是加 `90` 前缀,但薯条换成了完全另一套号,而鸡排两边同码。只能按名称逐条对齐,不能按规则推导。 于是渠道差异有三层,而不只是配送费: 1. **商品本身有渠道定价** —— 外送比自取普遍贵 9–13% 2. 外送另加配送费 + 打包费(实测配送费 6.00,打包费 1.60–1.90 随打包件数变) 3. **券池按渠道分** —— 同一家店,外送 0 张券、自取 1 张 券会把差价放大:龙焰鸡腿堡两件套那张券让自取从 34.00 掉到 20.48,而外送根本不存在这张券。 **所以换渠道必须重做两件事**:用该渠道的 `query-meals` 重新取码,用该渠道的 `query-store-coupons` 重新查券。不能复用。 另注:单品价格也随**门店**变(巨无霸上海 25.50、东莞 26.50),所以跨店比价同样不能套用另一家店的菜单价。 ## 渠道对照(外送 vs 自取) 用户问「外送还是自取」「送到家贵多少」时走这个流程。不要只报一个渠道的价。 **必须同门店比。** 外送的门店由收货地址决定(`delivery-query-stores`),自取报价必须用**同一家店**,否则比出来的是门店差异,不是渠道差异。 1. 取外送门店 → `storeCode` + `beCode` 2. `query-meals(orderType=2, beType=2, beCode)` → 外送商品码 3. `query-meals(orderType=1, beType=1, storeCode)` → 自取商品码(**两套码不同,不能复用**) 4. 两次 `calculate-price`,**逐项核对 `productList` 的商品与数量**和请求一致 5. 两次 `query-store-coupons`(`orderType` 不同 → 券池不同) 6. 出表 ### 输出格式 ``` 同一份餐:自取 X 元,外送 Y 元 —— 贵 Z 元(+W%) | | 自取 | 外送 | |---|---|---| | <商品 A> | | | | <商品 B> | | | | 配送费 | — | | | 打包费 | — | | | 合计 | X | Y | 差价构成 - 商品加价 a 元 —— 比例性的,按订单金额走,凑单摊不掉 - 固定费用 b 元 —— 配送 + 打包,单越大摊得越薄 ``` 一个可直接用的估算:**总溢价 ≈ 11% + 固定费用 ÷ 商品金额**。所以凑单只能接近 11%,到不了。 ### 规则 - 券的差异单独一行说:外送 N 张 / 自取 M 张。如果券会改变结论(比如自取有券、外送没有),必须点出来,那才是真正让差价翻倍的部分 - **不许只提「外送贵在配送费」** —— 差价里有两块性质不同的东西:商品加价随金额线性增长,固定费用不随金额变。小额单里费用占大头(本例 7.90 / 11.90),大额单里商品加价反超。两块都得拆出来 - 实测只覆盖一家店、几个商品。不要把加价幅度外推到别的门店或别的区域 ## 闸门(硬规则) - **绝不**调用 `create-order`、`mall-create-order`、`draw-lottery`、`party-order-create`。本 skill 只产出建议 - `create-order` 不幂等。超时不得重试;要确认订单是否落库只能查 `order-list` - 支付只能由人类完成,agent 拿到的只是支付链接。不得宣称「已下单成功」 - 一次分析的 `calculate-price` 预算 ≤ 15 次。超出就把不确定项标为「待验证」,不要硬猜 ## 已知坑 - 同一 `couponId` 可对应多个 `couponCode`,按 `couponId` 分组展示 - 券带 `promotionId`,但它不是本项目需要的键 - **永远不要**拿 `title` 当价格或商品名的来源 - 「免费」是相对该商品原价而言,不代表整单省钱——必须用差值验证 - **价格可信性校验**:`calculate-price` 对券专用虚拟码、以及**用错渠道的商品码**,都会返回 `success:true` 但把商品静默丢掉。报数前必须逐项核对 `productList` 的**商品与数量**和请求一致,不只看它非空 - 外送场景的失败是三种随机形态:静默丢弃个别商品、`productList` 全空但 `price` 只有配送费、或直接报 `60006`。看到任何一种都说明编码用错了,不是商品售罄 - `orderType=1` 的 `takeWayList` code **按门店变**,已见 `eat-in` / `locker-out` / `take-in-store` / `take-dt-quick` 四种。永远从返回里读,不要硬编码(详见 `references/ordering.md`)