adexbn / walk-kcal

# walk-kcal
**你今天还能吃多少卡，取决于你愿意走多远。**
*麦当劳程序员节创意开发大赛参赛作品*
**试试看（不用装任何东西）** ｜ GitHub 源码
 English TL;DR (the README below is in Chinese) 
**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/
---
站在楼下纠结「现在吃什么」时，你真正想知道的是——**这一顿，我吃得下吗？**
 一张竖屏长图：附近哪家店、哪道菜 你这顿吃不吃得下 —— 绿色 = 吃得起，红色 = 超了（划掉）。 
---
## 反常识：麦当劳居然是个低热量选项
我们把麦当劳官方营养表（158 条）和 155 万条中餐菜谱摊在一起算了一遍。
- **麦香鱼 325 卡** · 麦满分 250 卡 · 迷你草莓新地 122 卡
- 而隔一条街那家面馆的红烧肉盖饭，**780 卡起步**
**同一街区里，麦当劳的推荐菜大多落在普通人的一餐额度之内。**
这不是我们编的，是算出来的。
> 对热量预算紧张的人来说，走进麦当劳，反而是最安全的选择。
---
## 这个工具能做什么
| 你说 | 它做 |
|---|---|
| 我现在还能吃 450 卡，附近有什么能吃的 | 算额度、列附近店、每道菜标「吃得下 / 超了」 |
| 走过去 500 米能多吃多少 | 走 500 米 ≈ 多挣 28 卡，额度实时重算 |
| 麦当劳和隔壁面馆哪个更合适 | 同一额度下对比热量，一眼看出差距 |
| 这家店整体会不会吃超 | 按推荐菜相对额度给店铺定性 |
输出一张竖屏长图，可以直接发微信、发小红书。
---
## 独特之处
同类赛道里，大多数项目只算了菜品的热量；提到「步行」的，几乎没几个把它接到热量上。
| 别人通常做的 | 我们做的 |
|---|---|
| 算一下麦当劳某一款汉堡的热量 | **你楼下的任意一家店**，例如麦当劳 |
| 把距离当成「还有多远」 | 把距离换成「**这顿能多吃多少卡**」 |
| 只做一个平台 | **三种形式**，共用同一份内核 |
**三种形式，同一份结果：**
| | 形式 | 怎么用 |
|---|---|---|
| ① | **Skill** | 对 Agent 说一句「附近吃什么」 |
| ② | **Bot** | 在聊天软件里发消息，回复带可点的按钮 |
| ③ | **MCP** | 从任何 MCP 客户端调用，标准 JSON-RPC |
> 麦当劳 MCP 开放的，是它自己的营养表。可真实场景里，**你 400 米外那家面馆多少卡？**
> 没有人做这件事。我们做了。
---
## 内置两款能力 —— 也可以接你自己的
这个 demo 自带两款数据源，开箱即用：
| 能力 | 供什么 | 来源 |
|---|---|---|
| **麦当劳** | 门店 + 推荐菜 + **官方精确营养值**（官方表 158 条，含蛋白/脂肪/碳水/钠/钙） | 麦当劳官方 MCP |
| **高德地图** | 周边**任意**餐厅 + 网友推荐菜 + **真实路网**步行距离 | 高德开放平台 |
### 麦当劳的两条通道
| 通道 | 怎么开 | 你拿到什么 |
|---|---|---|
| **内置快照** | 什么都不用配 | 门店 + 推荐菜 + **官方热量值**（收录 demo 用到的 **22 条**；官方全表 158 条，2026-10-16 已用实时表逐条校准） |
| **实时数据** | 配上 `MCD_MCP_TOKEN`（+ `WALKKCAL_MCD_LIVE=1`） | 门店与营养值都实时从 `mcp.mcd.cn` 拉 |
**只想看个 demo、不想去申请 Token？** 直接跑就行 —— 效果是完整的。
想要**实时**的门店和营养值，再去申请一个 Token 也不迟： （免费）。
**可以按需组合** —— 一个环境变量的事：
| 你想要的 | 怎么配 | 你会拿到 |
|---|---|---|
| 两个都要（**默认**） | 不设 | 麦当劳与周边餐厅**合并成一份结果** |
| **只要麦当劳** | `WALKKCAL_PACKS=mcd` | 只有麦当劳，全部官方精确值 |
| **只要周边餐厅**（即「只要地图」） | `WALKKCAL_PACKS=nearby` | 只有你楼下那些面馆、火锅、小吃 |
**也可以接你自己的** —— 点评的企业接口、美团、或者你手上任何一份门店／菜品数据。
数据源是**可插拔**的：加一个文件 + 一个环境变量，**主流程 0 行改动**。
> 麦当劳在这里是一个**可信的数据源**，不是一个**产品的边界**。
---
## 跑起来
**先跑内置场景 —— 这一步一个 Key 都不需要。**
 [code] 
只需要 Python 3.8+，**不用 pip install 任何东西** —— 默认输出 SVG（浏览器直接打开、放大不