ibh4/mac-buddy/mcd-buddy

Mac-Buddy · 麦麦搭子（Skill）

参赛名称：Mac-Buddy 麦麦搭子——懂你口味的点餐助手；产品名：Mac-Buddy · 麦麦搭子；仓库名 / Skill 名：`mcd-buddy`。参赛展示时请始终带上完整名称与功能副标题，便于与同名作品区分。

这是基于麦当劳 MCP 的独立开发者作品，非官方产品。页面与对话中都应明确这一点。

一、这条 Skill 依赖什么（先说清楚，避免装了跑不起来）

本 Skill 依赖本仓库的本地后端才能完成持久化与真实核价。它不是一个纯提示词包。

安装前提：

1. Node.js >= 20；
2. 在仓库根目录执行 npm install；
3. 演示模式：npm run demo（不需要任何 Token，立即可用）；
4. 真实模式：cp .env.example apps/server/.env，填入 MCD_MCP_TOKEN（不要加 Bearer 前缀，后端自动补），再 npm run build && npm start。

网页前端（汉堡主题）：本地网页是用户主要交互界面，默认运行即自动弹出。

• 开发模式：npm run dev —— 启动后自动打开浏览器到 http://127.0.0.1:5173（即为网页前端，由 Vite 提供）。
• 生产模式：npm run start —— 后端在 8787 托管已构建的前端并自动打开浏览器。需先 npm run build 生成 apps/web/dist。
• 不想自动打开浏览器时，设环境变量 NO_OPEN=1 再启动。
• 前端视觉基于 Burger-Theme-Website 模板的视觉语言（暖色背景 + 黄色强调 + 汉堡主图与浮动配料贴纸 + Aclonica 展示字体），仅取用其通用食物插画与风格，不复制其文字内容与品牌，品牌仍为「麦麦搭子 / Mac-Buddy」，并保留「非官方产品」声明。

自检：bash scripts/check.sh（类型检查 → 离线测试 → 构建 → 演示模式冒烟）。

路径依赖说明：本 Skill 只使用相对路径（scripts/check.sh、references/*.md），不含任何作者本机的绝对路径。

二、三条运行路径（必须区分，不要混为一谈）

• 路径 A：WorkBuddy 连接器——由 WorkBuddy 用已配置的 mcd-mcp 连接器调用 MCP，再用本地后端 REST API 保存餐单与版本。
• 路径 B：本地后端独立网页——浏览器调本地后端，后端用标准 MCP 客户端连接远端。网页不继承 WorkBuddy 的连接器权限，必须单独配置 MCD_MCP_TOKEN。
• 路径 C：本 Skill 的脚本——scripts/ 下的启动与自检脚本，只在本机运行。

三者共享同一套业务逻辑（纯函数层）与数据模型，见 docs/architecture.md。

三、适用场景 / 触发语句

• “把我的历史订单存成老样子”
• “还是老样子，今天饮料换一下”
• “这份另存为周末版”
• “看看今天这版和原来改了什么”
• “用回最初那一版，查一下现在还能不能点”
• “今天微微调一下，但主食别动”
• “随便来一份，别超过 40 块”
• “今天吃什么？抽个签”
• “这一餐大概多少卡 / 蛋白质多少”
• “能量少一点 / 蛋白多一点 / 钠少一点”
• “同样吃，看看有没有优惠”
• “我最近都点了啥 / 我大概喜欢什么”
• “核对后帮我下单”（仅在用户明确确认后）

四、MCP 工具（实际用到的）

优先使用已在 WorkBuddy 启用并信任的 mcd-mcp 连接器。 调用前务必用 `tools/list` 实际读取 `inputSchema`，不要凭工具名猜参数。

• order-list 历史订单（只读） · query-order 订单详情
• query-nearby-stores 门店（beType 必传：1 到店自取 / 2 麦乐送到家 / 5 得来速）
• query-meals 门店菜单（storeCode、orderType、beType；详情页含商品图 image）
• query-meal-detail 餐品详情与套餐组成（含 image）
• calculate-price 真实核价（金额单位为「分」；支持按商品传 couponCode/couponId）
• create-order 用户确认后创建订单（orderType=1 时 takeWayCode 必传）
• list-nutrition-foods 官方营养资料（无入参，返回纯文本表格）
• query-store-coupons 门店优惠券（返回的是数组，且不含优惠金额）

query-promotions 仅适用于团餐（beType=6），普通点餐不要用它。

完整工具清单与踩坑记录见 `references/mcp-tools.md`。

营养资料的取数坑点、匹配策略与真实数据快照见 `references/nutrition.md`。

本地 REST API 清单见 `references/api.md`。

五、硬性规则（任何一条都不能为了方便而打破）

5.1 微微调 / 随机 / 食签

• 微微调默认最多改 1 处；一次“替换”计 1 处（不是两处）；锁定项不得改动或移除；

套餐内替换必须走 query-meal-detail；冲突时只说明原因并给出可放宽项，绝不自动突破约束；结果只是草稿。

• 随机：候选在本地确定性构建；“换一个”只推进种子，不反复调用 MCP；相同条件 + 相同种子可复现；

最终金额以 calculate-price 为准。

• 食签：严禁使用或暗示黄历 / 生肖 / 星座 / 八字 / 财运 / 转运等运势逻辑。

它是基于「偏好 40% + 意图 30% + 差异 20% + 口味 10%」的启发式打分，缺数据时忽略该项并重新归一化； 日期按 Asia/Shanghai；当日结果稳定并缓存。

5.2 这一餐的能量卡

• 只在规格与计量基准可核对时匹配；名称相似但份量未知的不认定为同一份量；
• 官方营养表按「每份」给出且无重量列，因此只按数量累加，不做每 100g 换算；
• 能量优先取 kcal；只有 kJ 时按 1 kcal = 4.184 kJ 换算；
• 套餐只累计组成项，不重复计入套餐本身；
• 特制（如去酱）无对应数据时标注「特制后的营养变化未知」，绝不编造减少值；
• 缺失显示「暂无数据」，绝不填 0；部分匹配显示覆盖情况（如「4 项中 3 项已匹配」）；
• 碳水不是糖，钠不是盐；糖恒为「暂无数据」，绝不由碳水推算；
• 用当前资料分析历史餐单时必须标明口径，不声称还原历史摄入；
• 未设置能量参考值时不给健康评分或红绿灯；也不按疾病 / 人群 / 体检指标自动给阈值。

5.3 老样子轻一点

• 尊重锁定；默认最多替换 1 个槽位；只用当前门店可售且套餐规则允许的候选；尊重预算与排除项；
• 只对营养数据可比较的候选给精确差值；数据缺失时不输出精确差值；
• 每个目标最多 4 个方案：同类替换优先；当同类没有能改善该指标的候选时，跨类兜底（只保留确实改善目标的候选，绝不强行跨类）；因此界面上极少出现「没有符合条件的替换方案」，而是给出几个配套方案供选择；不因单一指标下降就宣称「更健康」；
• 无方案时给出原因与可放宽项，绝不自动取消锁定；应用只改草稿，保存才建版本；
• 所有差值由确定性代码计算，语言模型只负责解释。

5.4 同样吃，看看优惠

• 有券方案与无券方案必须是同一门店、同一就餐方式、同一组商品，不为了凑券加东西；
• 「少付 ¥X」只在 calculate-price 核价确实更低时出现；没有可比的无券价格时只给已核实金额；
• 有附加条件的券写清条件，交给用户自己选；不宣称「已把所有券都用上」；
• 绝不自动领券、开通会员、消耗积分；没有更合适的优惠是正常结果，不谎报最低价。

5.5 看图轻松点

• 图片地址只来自 MCP 工具返回的官方地址（后端已限定 https），绝不自行拼接 URL、绝不使用搜索来的图；
• 绝不把官方产品图下载打包进仓库：产品摄影有版权，也违反「原创性声明」与本项目「不打包官方图片」的约束。

仓库里只放原创 SVG 插画，统一标注「示意图」；真实图只在运行时由 MCP 返回并直接使用其 https 地址。

• 实测边界：单品编码才有图；促销/组合编码（多为 99 开头）返回 code:60001，此时就是没有图，不要用别的图顶替。
• 实测边界：非营业时间 query-meals 返回 600057，但 query-meal-detail 仍能返回单品图片 —— 取图链路要能独立兜底。

想一次拿全店所有单品的图必须在营业时间：用 POST /api/product-images/warm 或 bash scripts/warm-product-images.sh <门店编码> 预热（只把 https 地址存进本地 SQLite，不下载图片文件）。

• 固定容器尺寸 + object-fit: contain；懒加载 + 占位 + 失败降级，并标注「示意图」；
• 始终同时显示商品名称与规格，绝不只靠图传达信息；演示模式下统一按示意图处理，不与真实图混用。

5.6 下单前看一眼

• 集中呈现门店 / 就餐方式 / 商品（图 + 名称 + 规格 + 数量）/ 真实金额 / 与老样子的差别 / 剩余不确定项；
• 出现两份相同商品时提示「确认需要两份吗」，绝不静默删除；
• 餐品、门店、就餐方式或关键参数变化就重新核价并要求重新确认；
• 只有点「确认下单」才调用 `create-order`；没有任何强制等待计时；
• create-order 超时或结果不明时先 query-order 核实，不盲目重试。

5.7 饮食足迹口径

• 消费次数只统计已完成订单，取消 / 未支付 / 退款 / 异常一律排除；按订单号去重；
• 模板、草稿、演示数据不算消费次数；他人订单默认不计入个人口味；
• 绝不从菜名臆测配料或口味；每条画像结论必须可解释（来源 + 依据条数 + 显式/推断 + 改正入口）。

六、已实现 / 规划中（不要夸大）

已实现：老样子模板与版本、差异对比、自然语言微调、微微调、随机来一份、今日食签、 能量卡、老样子轻一点、看看优惠、真实商品图、下单前核对、饮食足迹与口味画像。

规划中（尚未实现，不要在对话中宣称可用）：预约下单、真正的多券叠加寻优、 把「优惠」扩展到会员权益与积分、按门店营业时间自动择时。

七、数据与安全

• 数据保存在本地 SQLite：apps/server/data/mcd-old-same.db（已被 .gitignore 忽略）；

删除本机数据：bash scripts/delete-local-data.sh。

• 不持久化手机号、地址、支付链接等敏感返回值。
• Token 只存在于 apps/server/.env；后端只监听 127.0.0.1；前端产物与日志不含 Token。
• 演示模式与真实模式严格区分，演示数据不冒充真实订单；演示模式不产生任何真实订单或支付链接。