walk-kcal Skill 技能

技能简介

walk-kcal 把一句"我今天还能吃多少卡"变成一个能执行的决策：它用一套换算规则（基础额度 450 kcal，每走 80 米多 4 kcal，走 800 米大约多挣 44 卡，约等于半个苹果）把步行距离直接折成"这顿还能吃多少"，然后列出你周边的餐厅与推荐菜，逐道菜标注吃得起还是超了，输出一张竖屏长图，可直接发微信或小红书。它是麦当劳程序员节创意开发大赛的参赛作品，由参赛者独立开发，不是麦当劳官方产品。

核心能力

• 三种形态共用一份内核：Skill（对 Agent 说一句"附近吃什么"）、Bot（在聊天软件发消息，回复带可点按钮）、MCP（标准 JSON-RPC，4 个工具，任何 MCP 客户端都能调）。
• 额度随距离实时重算：问"走过去 500 米能多吃多少"，会直接回答多挣约 28 卡并重算额度。
• 跨店对比：麦当劳与隔壁面馆在同一度量下并排比较热量差距；也可按推荐菜相对额度给整家店定性。
• 双数据源内置：麦当劳官方 MCP（官方营养表 158 条，含蛋白、脂肪、碳水、钠、钙；内置快照收录 22 条并于 2026-10-16 用实时表逐条校准）与高德地图（周边任意餐厅、网友推荐菜、真实路网步行距离）。
• 可插拔数据源：地图、语料、渠道都走统一接口，某个服务商的私有格式被关在自己的适配层里，换一家等于加一个文件加一个环境变量，主流程零改动。
• 诚实的估算策略：中餐热量平均误差 25–28%（菜谱普遍缺分量信息），算法会明确显示"算不出"，宁可少算不可算错。
• 离线可跑：内置 5 个场景渲染不发起任何网络请求，还带一个自包含的离线可交互 demo。

安装配置

1. 只要 Python 3.8 以上，不用 pip install 任何东西，默认输出 SVG，浏览器直接打开放大不糊；需要 PNG（发微信、小红书）再装一个可选扩展包。
2. 数据源全不配也能跑：git clone 后执行 python walkkcal/render.py 即可出图（内置场景，1 到 2 秒，无网络请求）；离线交互 demo 用浏览器打开 demo/explore.html 即可。
3. 想要实时麦当劳数据：申请免费 Token 后设置 MCD_MCP_TOKEN 与 WALKKCAL_MCD_LIVE=1，门店与营养值就会实时从 mcp.mcd.cn 拉取。
4. 想要周边任意餐厅：配置高德地图的 AMAP_KEY；用 WALKKCAL_PACKS=mcd 或 nearby 可只取其中一路数据，默认是两路合并。

使用步骤

1. 克隆仓库并进入目录，python walkkcal/render.py 生成内置场景的示例长图，先确认渲染正常。
2. 抓自己的点位：python walkkcal/shoot.py "上海市黄浦区南京东路100号"，会依次做地址转坐标、抓取数据与出图，实测约 16 秒。
3. 当 MCP Server 用：python entry/mcp_server.py 直接跑，或 docker build -t walk-kcal . && docker run -i --rm walk-kcal 走容器。
4. 在 Agent 里问"附近吃什么"或"我还能吃 450 卡，附近有什么能吃的"，技能会算额度、列店、逐菜标注。
5. 想批量出图或接入自己的点评、美团等数据源，按文档加一个 provider 文件并设置对应环境变量即可。

适用场景

• 楼下纠结吃什么：把犹豫变成一张可比较的清单。
• 减脂期热量预算：把额度与距离挂钩，用步行换餐食弹性。
• 商场与写字楼周边探店：拿它生成的竖屏长图发朋友圈或小红书。
• 步行友好型本地生活：把"走过去"这件事变成可计算的收益。
• Agent 应用样例：一份完整的多形态（Skill / Bot / MCP）小项目，适合当参考实现读。

适用人群

关注热量与饮食的普通用户、健身与减脂人群、做本地生活内容与探店账号的创作者，以及想给 Agent 接一个有趣真实数据源的开发者。当前地图数据与菜谱语料以中国为主，海外使用需要自己接 Google/OSM 与 USDA、OpenFoodFacts 这类数据源。

工作原理

上层只认一套通用接口：门店用经纬度，热量用菜名，业态归一化成 12 个词。某个品牌接口只吃文字地标而不收经纬度、某家地图服务商的类目名需要翻译，这些差异全部消化在各自的 provider 与 pack 内部，主流程一行不改。热量估计按明确分层推进：精确菜谱 → 品类中位数 → 业态先验 → 明确的"未知"，每一道菜都会标注它落在哪一层以及误差范围。

官方链接

• GitHub：https://github.com/adexbn/walk-kcal
• 离线 demo：仓库内 demo/explore.html
• 麦当劳 MCP 申请：https://open.mcd.cn/mcp
• 许可与免责：本项目为参赛作品，输出仅供参考，不构成医疗或营养建议