walk-kcal

# walk-kcal **你今天还能吃多少卡，取决于你愿意走多远。** *麦当劳程序员节创意开发大赛参赛作品* **[试试看（不用装任何东西）](https://adexbn.github.io/walk-kcal/)** ｜ [GitHub 源码](https://github.com/adexbn/walk-kcal) <details> <summary><b>English TL;DR</b> (the README below is in Chinese)</summary> **Walk-Kcal** turns walking distance into a meal calorie budget: `450 kcal + 4 kcal per 80 m`. Walking 800 m buys you **+44 kcal** — about half an apple. Given a location, it lists nearby restaurants and their recommended dishes, estimates kcal per dish in explicit layers (exact recipe → category median → store-type prior → **"unknown"**), and marks each dish as *fits your budget* or *over*. McDonald's nutrition comes from the official China MCP (`query-nearby-stores`, `list-nutrition-foods`); other restaurants are estimated from a Chinese recipe corpus, with the layer and error range disclosed per dish. > ⚠️ **Not a turnkey tool for your country.** Map data and the recipe corpus are Chinese. > What ports is the *pipeline* — plug in your own map API (Google / OSM) and nutrition source > (USDA / OpenFoodFacts), and keep the abstain layer. **Demo (no install):** https://adexbn.github.io/walk-kcal/ </details> --- 站在楼下纠结「现在吃什么」时，你真正想知道的是——**这一顿，我吃得下吗？** <p align="center"> <img src="assets/screenshot-preview.png" width="290" alt="输出长图：地图圈层 + 门店卡片，每道菜标绿（吃得起）或标红（超了）"><br> _{一张竖屏长图：附近哪家店、哪道菜<strong>你这顿吃不吃得下</strong> —— 绿色 = 吃得起，红色 = 超了（划掉）。} </p> --- ## 反常识：麦当劳居然是个低热量选项 我们把麦当劳官方营养表（158 条）和 155 万条中餐菜谱摊在一起算了一遍。 - **麦香鱼 325 卡** · 麦满分 250 卡 · 迷你草莓新地 122 卡 - 而隔一条街那家面馆的红烧肉盖饭，**780 卡起步** **同一街区里，麦当劳的推荐菜大多落在普通人的一餐额度之内。** 这不是我们编的，是算出来的。 > 对热量预算紧张的人来说，走进麦当劳，反而是最安全的选择。 --- ## 这个工具能做什么 | 你说 | 它做 | |---|---| | 我现在还能吃 450 卡，附近有什么能吃的 | 算额度、列附近店、每道菜标「吃得下 / 超了」 | | 走过去 500 米能多吃多少 | 走 500 米 ≈ 多挣 28 卡，额度实时重算 | | 麦当劳和隔壁面馆哪个更合适 | 同一额度下对比热量，一眼看出差距 | | 这家店整体会不会吃超 | 按推荐菜相对额度给店铺定性 | 输出一张竖屏长图，可以直接发微信、发小红书。 --- ## 独特之处 同类赛道里，大多数项目只算了菜品的热量；提到「步行」的，几乎没几个把它接到热量上。 | 别人通常做的 | 我们做的 | |---|---| | 算一下麦当劳某一款汉堡的热量 | **你楼下的任意一家店**，例如麦当劳 | | 把距离当成「还有多远」 | 把距离换成「**这顿能多吃多少卡**」 | | 只做一个平台 | **三种形式**，共用同一份内核 | **三种形式，同一份结果：** | | 形式 | 怎么用 | |---|---|---| | ① | **Skill** | 对 Agent 说一句「附近吃什么」 | | ② | **Bot** | 在聊天软件里发消息，回复带可点的按钮 | | ③ | **MCP** | 从任何 MCP 客户端调用，标准 JSON-RPC | <p align="center"> <img src="assets/screenshot-three-shells.png" alt="三种接入形式：① Skill（Agent 宿主）② Bot（聊天软件）③ MCP（任何 MCP 客户端）"> </p> > 麦当劳 MCP 开放的，是它自己的营养表。可真实场景里，**你 400 米外那家面馆多少卡？** > 没有人做这件事。我们做了。 --- ## 内置两款能力 —— 也可以接你自己的 这个 demo 自带两款数据源，开箱即用： | 能力 | 供什么 | 来源 | |---|---|---| | **麦当劳** | 门店 + 推荐菜 + **官方精确营养值**（官方表 158 条，含蛋白/脂肪/碳水/钠/钙） | 麦当劳官方 MCP | | **高德地图** | 周边**任意**餐厅 + 网友推荐菜 + **真实路网**步行距离 | 高德开放平台 | ### 麦当劳的两条通道 | 通道 | 怎么开 | 你拿到什么 | |---|---|---| | **内置快照** | 什么都不用配 | 门店 + 推荐菜 + **官方热量值**（收录 demo 用到的 **22 条**；官方全表 158 条，2026-10-16 已用实时表逐条校准） | | **实时数据** | 配上 `MCD_MCP_TOKEN`（+ `WALKKCAL_MCD_LIVE=1`） | 门店与营养值都实时从 `mcp.mcd.cn` 拉 | **只想看个 demo、不想去申请 Token？** 直接跑就行 —— 效果是完整的。 想要**实时**的门店和营养值，再去申请一个 Token 也不迟：<https://open.mcd.cn/mcp>（免费）。 **可以按需组合** —— 一个环境变量的事： | 你想要的 | 怎么配 | 你会拿到 | |---|---|---| | 两个都要（**默认**） | 不设 | 麦当劳与周边餐厅**合并成一份结果** | | **只要麦当劳** | `WALKKCAL_PACKS=mcd` | 只有麦当劳，全部官方精确值 | | **只要周边餐厅**（即「只要地图」） | `WALKKCAL_PACKS=nearby` | 只有你楼下那些面馆、火锅、小吃 | **也可以接你自己的** —— 点评的企业接口、美团、或者你手上任何一份门店／菜品数据。 数据源是**可插拔**的：加一个文件 + 一个环境变量，**主流程 0 行改动**。 > 麦当劳在这里是一个**可信的数据源**，不是一个**产品的边界**。 --- ## 跑起来 **先跑内置场景 —— 这一步一个 Key 都不需要。** ```bash git clone https://github.com/adexbn/walk-kcal && cd walk-kcal python walkkcal/render.py # 出图（内置场景，1~2 秒，无网络请求） # 打开离线可交互 demo（自包含，不发任何网络请求） start demo\explore.html # Windows open demo/explore.html # macOS xdg-open demo/explore.html # Linux ``` 只需要 Python 3.8+，**不用 pip install 任何东西** —— 默认输出 SVG（浏览器直接打开、放大不糊）； 想要 PNG（发微信/小红书那种）再装一个可选扩展包。 想当 MCP Server 跑（stdio 传输，4 个工具）： ```bash python entry/mcp_server.py # 直接跑，或者 docker build -t walk-kcal . && docker run -i --rm walk-kcal ``` 快照里已经存好了门店、推荐菜、步行距离和热量 —— 麦当劳的官方营养值也是内嵌的 （demo 用到的 22 条，已按官方实时表校准）。 **两套数据源，各配各的 —— 都不配也能跑：** | 数据源 | 配了你会得到 | 需要什么 | |---|---|---| | **麦当劳** | 门店与营养值走实时（而非内置快照） | `MCD_MCP_TOKEN` + `WALKKCAL_MCD_LIVE=1` | | **地图**（默认高德） | 你周边任意餐厅 + 真实步行距离 | 高德地图的 `AMAP_KEY` | ```bash # 抓新点位：地址 → 坐标 → 抓数 → 出图，实测约 16 秒 python walkkcal/shoot.py "上海市黄浦区南京东路100号" ``` **输出格式是可选的**：默认出 **SVG** —— 浏览器打开就能看、放大不糊，大多数场景够用； 想要 **PNG**（例如直接发微信、小红书），装一个很小的扩展包即可。 > 全部命令、5 个内置实拍场景、换点位、跨城市、环境变量总表 > → [`docs/快速开始.md`](docs/快速开始.md) --- ## 这两款能力是怎么接进来的 不看代码也能看懂的部分： - **地图 / 语料 / 渠道都是可插拔的。** 上层只认一套通用接口 —— 门店用经纬度， 热量用菜名，业态用归一化后的 12 个词。 - **某家的私有格式一律关在它自己的适配层里。** 地图服务商的类目名怎么翻译、 某个品牌的门店接口只吃文字地标而不收经纬度 —— 这些差异都消化在各自的 provider / pack 内部，主流程一行都不用改。 - 所以换一家（百度、点评、美团…）＝ **加一个文件 + 一个环境变量**。 想看它落到实处 → [`walkkcal/providers/`](walkkcal/providers/)（地图）· [`packs/`](packs/)（数据源）· [`docs/扩展开发.md`](docs/扩展开发.md) 麦当劳那条链的具体调用（用了哪些 Tool、怎么和本地估算融合） → [`MCP_INTEGRATION.md`](MCP_INTEGRATION.md) --- ## 我们诚实地告诉你 **额度是你自己定的预算，不是算法塞给你的建议** —— 走路只让它随距离增长。 中餐热量是估算的（平均误差 **25–28%**），因为菜谱里**几乎没有可用的分量信息** （少数标了「2 人份」，标准却各不相同，我们没有采用），而且**配料和调料的影响，有时候比主料还大**。 我们花最大力气的地方不是「算得更准」，而是**知道什么时候算不准**，然后如实显示「算不出」—— 而不是猜一个看起来正常的数字。 > 宁可少算，不可算错。　详见 → [`docs/数据源与误差.md`](docs/数据源与误差.md) --- ## 免责 本项目为麦当劳程序员节创意开发大赛参赛作品，**由参赛者独立开发，非麦当劳官方产品**。 输出仅供参考，不构成医疗、营养或其他专业建议。 餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准。 --- ## 如果它帮到你了 如果你也常在楼下纠结「这顿吃什么」，它帮你把账算清楚了一点 —— 那**点一下右上角的 ⭐ Star** 就是最好的鼓励。它不会改变代码， 但会让更多同样在纠结的人看到这个工具。 （也欢迎提 Issue 说说你那个城市的菜算得准不准：哪个算错了、哪个该有却没有。 这比 Star 对它更有用。） --- <div align="center"> **你今天还能吃多少卡，取决于你愿意走多远。** </div>