name: walk-kcal description: 走得越远，这一顿的卡路里额度越高 —— 用步行距离换额度的吃饭决策。当用户说「现在吃什么」「走过去能多吃多少」「这顿还能吃多少卡」「附近有什么低热量/快餐/西餐/小吃」「换一批」「还有别的吗」时使用。① 按步行距离折算额度；② 麦当劳官方营养值 + 周边餐厅统一推荐，每道菜标「吃得下 / 超了」；③ 按业态与半径细化；④ 出竖屏长图 + 可点的下一步选项。

walk-kcal · 走得越远，这一顿吃得越多

这份文件有两类读者，看不同章节就行：

• Agent → 只看 一、运行手册
• 人（评委 / 第一次用）→ 看 二、装与用
• 想了解内部怎么实现 → 三、技术说明

一句话：你今天还能吃多少卡，取决于你愿意走多远。

一、运行手册（Agent）

1.1 何时启用

1.2 对话协议

这是渐进细化的多轮对话，不是单次问答。 用户首句通常很短（「吃什么」）， 应答须先给可用结果，再给出可细化方向。

三条硬规则

1. 零参数调用必须先出结果，不得先反问用户偏好。 唯一例外是位置：没有位置算不出距离，因此没有"走多远"。 但位置也先自行获取（见 1.3 四档），四档都失败才向用户询问。 不得把 examples/* 里的演示快照当作"用户附近"。
2. 用 next 字段引导，不罗列参数。 next=[{'label':'只看快餐'},…] → 输出「要只看快餐吗？」； 禁止输出「可用参数：industry=快餐|小吃|西餐…」。
3. 细化选项一律取自 next，不自行构造。 它是按当前数据算出来的 （K11 附近咖啡多则提示咖啡）；自造的选项往往查不到结果。

用户话术 → 参数

一轮回复的结构

<结论句>   ← 直接用返回值的 text 字段（已按「结论｜依据｜来源｜下一步」写好）
<长图>     ← 渠道支持图片时
<选项>     ← 把 next 转成问句；Bot 渠道可直接渲染成按钮

不得只发图了事 —— 用户会不知道下一步能做什么。

★ text 中若出现「ⓘ 数据来源：这次没能走实时…」，必须原样保留。 它表示某条渠道回退到了本地快照（meta.source_notes 有机器可读版本）。 默认配置（读内置快照）不会出现这段，出现即表示真的回退过。

1.3 位置获取（四档，按代价从低到高）

# ② 自动定位（机器可读；首次会编译一个 C# 小工具，约 3~7 秒，之后 <3 秒）
python walkkcal/locate.py
# 成功 → {"ok":true,"lat":31.26596,"lon":121.40968,"accuracy_m":159,"source":"WiFi",...}
# 失败 → {"ok":false,"reason":"...","hint":"..."}

# 拿到坐标后直接出图（不输入地址即可，shoot.py 内部会自动定位）
python walkkcal/shoot.py

★ locate.py 只接受 source 为 WiFi / Satellite 的结果。 开启代理时系统会退回 IP 定位、返回机房坐标（实测会指到境外）， 此时它主动弃权（ok:false）—— 用这种坐标算「附近 800 米」没有意义。 ★ 也可绕过定位：--lat 31.23 --lon 121.41，或设 WALKKCAL_LAT / WALKKCAL_LON。 ★ locate.py 无第三方依赖（用系统自带的 .NET Framework csc.exe 编译一个 50 行 C# 工具， 产物缓存在 out/_tools/，不入仓库）。

没有地图 Key 时的行为（硬约束）

python walkkcal/config.py      # 一次看清：配置来自哪个文件 / 有哪些键 / 哪些有值

无地图 Key 时：档 ② 不可用（shoot.py 无法解析地址、也检索不到周边）。

禁止：把 examples/* 中的演示快照当作"用户附近"（等价于用演示数据冒充真实结果）。

演示点位清单（与用户位置无关）

这些是仓库里预采集的演示点位（见 examples/README.md）—— 不是用户位置。

用离线场景出图时，回复中必须点明是哪个点位，且不得表述为「你附近」。

1.4 执行流程

① 确定位置          用户给的地址 / locate.py → 经纬度
② 拉周边门店        pack_mcd.search_stores()            → 麦当劳门店
                    pack_nearby_dining.search_stores() → 周边本地店
                    （市中心一个路口就近 200 家 → 只选 15 家，但如实显示总数）
③ 选店              walkkcal/select.py
                    ① 麦当劳保底，但 ≤ 1/3
                    ② 四象限轮转（避免地图偏向某一侧）
                    ③ 同象限按「额度内可吃道数 ↓、距离 ↑」
                    ④ 取满 15 止
④ 算额度            quota = 450 + (walk_m // 80 + 1) * 4
⑤ 逐菜取热量（分层，每层携带来源标签）
                    L1  pack.heat_of()      官方表 / 语料命中  →「菜谱推算」±25%
                    L2  prior.dish_prior()  菜名关键词定品类  →「品类估算」±35%
                    L3  prior.store_prior() 门店类型定品类    →「同类估算」±45%
                    L4  均不命中             → 弃权（不给数值）
                    verdict = '吃下' if kcal <= quota else '超了'
⑥ 再取网点定性      低于缺口(绿) / 适配缺口(黄) / 高于缺口(红)
⑦ 渲染长图          python walkkcal/render.py

★ 分层估算的效果（6 个演示场景 1236 条推荐菜实测）：只用 L1 覆盖 70.6%， 加入 L2/L3 后 98.1%，弃权 1.9%。每个数值都携带自身可信度。

1.5 输出契约

一次调用返回四项（契约见 walkkcal/reply.py）：

text 示例：

额度 450 卡。附近 47 家餐饮，24 家进入候选（麦当劳最多占 1/3），本批列 15 家（第 1/2 批）。 最合适的是「星巴克」——走 166 米，7 道在额度内。要换一批看看吗？

视觉编码（两套编码各管一件事）：

• 形状 = 业态（碗 = 餐馆 / 汉堡 = 麦当劳 / 咖啡杯 / 购物袋 / 火锅）
• 颜色 = 热量（绿 = 低于缺口 / 黄 = 适配 / 红 = 高于缺口）

1.6 参数速查

★ --radius 有两层默认值：shoot.py 命令行 800 米，数据层 nearby_dining() 1500 米。 需要收窄就显式传 --radius。

二、装与用（人）

2.1 安装：一个目录 + 这份文件

所有支持 Skill 的宿主都是同一个办法：建一个技能目录，把这份 SKILL.md 放进去。

只装你正在用的那一个，不需要全装：

# 把 <宿主目录> 换成上表里你用那一个（示例：Trae CN）
mkdir -p ~/.trae-cn/skills/walk-kcal
cp SKILL.md ~/.trae-cn/skills/walk-kcal/

• 也可以不走技能目录 —— 在会话里直接 @ 引用这份文件即可（技能就是一份 Markdown 说明书）。
• 装好后新开一个会话，说「附近吃什么」就能触发。
• 改了仓库里的 SKILL.md 后要重新复制一次（技能目录里是副本，不是软链）。
• 本文件不含任何机器的绝对路径，副本放哪儿都不影响运行。 唯一的硬要求见下面第 1 条。

2.2 运行前提

这四项没有一项是"必须先有"的 —— 缺哪一项，项目都仍然能跑，只是能力范围相应收窄。

2.3 配置：Key 放在哪

不要把 Key 写进 .py 文件（那样会被一起提交上去）。统一从配置文件或环境变量读。

唯一入口是 walkkcal/config.py，取值顺序如下（环境变量优先级最高）：

① 环境变量
② WALKKCAL_CONFIG 指向的 JSON（设了就用它，不再往下看）
③ <仓库>/config.local.json                    ← 项目配置文件（推荐放这里）
④ <仓库>/walkkcal/config.local.json

# 第一次用：从模板复制一份，填 Key
cp config.example.json config.local.json
# 查看配置从哪里读到（只报告有没有值，不打印值本身）
python walkkcal/config.py

• 配置文件格式是 JSON（不是 YAML）—— 本项目坚持零第三方依赖，而读 YAML 需要额外装库。
• config.local.json 已被 .gitignore 排除，永远不会进版本库。
• 程序报错信息里的 Key 会被自动替换成 <已屏蔽 XXX>，不会顺着日志漏出去。
• 若担心误提交，可以自查仓库里有没有形如 32 位十六进制串的密钥常量。

最小可用配置 = 一套「店 + 菜」的数据源。 麦当劳和地图是并列的两套来源， 配任意一套就能跑：

一个都不配也能跑 —— 项目内置了数据快照（含麦当劳 158 条营养值 + 几个演示点位）， 效果完整，只是不针对你的位置。

麦当劳的实时门店检索需要一个能翻译坐标的地图 Key（它的接口不接收经纬度）， 细节见 3.2。

2.4 30 秒验证

cd <仓库根目录>
cp config.example.json config.local.json    # 首次：填 AMAP_KEY
python walkkcal/shoot.py "上海市浦东新区凌河路618弄95号"

⚠️ 上面这个地址只是示例，不是默认点位 —— 实际使用时换成用户给的位置。 命令会打印池子家数 / 请求次数 / 耗时，并生成一张图（约 16 秒）。 如果没装出图扩展包，产出的是同名 .svg —— 这是正常现象，不是故障。

也可以不输地址，直接自动定位（Windows 上基于 WiFi 指纹，实测精度 150~500 米）：

python walkkcal/shoot.py

★ 想临时用环境变量覆盖 Key：AMAP_KEY=真实key python walkkcal/shoot.py "…" （别真写成 AMAP_KEY=xxx —— 那会把 Key 设成字面量 xxx，然后报无权限。）

看到「构建期自检通过」加一个图片文件，就说明整条链路是通的。

2.5 常用命令

# ★ 一步出图（推荐）：给一个地址就行 —— 解析 → 抓数 → 渲染，约 16 秒
python walkkcal/shoot.py "上海市黄浦区南京东路100号"
# → out/上海市黄浦区南京东路100号_76fd57.png

python walkkcal/shoot.py "陆家嘴" --quota 400              # 这顿只吃 400 卡
python walkkcal/shoot.py "苏州市姑苏区观前街" --city 苏州   # 跨城市必须 --city
python walkkcal/shoot.py "陆家嘴" --radius 1000 --out out/ljz.png
python walkkcal/shoot.py "人民广场" --keep-scene           # 留下场景数据供排查

# 渲染已有场景（不联网，1~2 秒；适合换业态 / 翻页）
python walkkcal/render.py
WALKKCAL_DATA=examples/linghelu python walkkcal/render.py

# 只采集数据、不出图
python walkkcal/fetch_pois_at.py <lat> <lon> <radius> <场景名> --scene

两者的分工：shoot.py 用于只有地址、要联网抓一个新点位； render.py 用于已有场景数据、只想换业态或翻页。

⚠️ 不传 WALKKCAL_DATA 时，render.py 读的是 examples/default = 上海·静安虬江路 —— 那是演示点位，不是用户位置。

★ 抓取速度（134 秒 → 14 秒）来自把「逐店算距离」改成批量算距离 （高德 /v3/distance 一次能收 100 个目的地），请求数从 111 降到 9~12 次。 不要为了更快去调小请求间隔 —— 地图配额按并发计算，百度实测贴到 3 QPS 就会收到告警。

2.6 环境变量

render.py 没有命令行参数，离线渲染只能靠环境变量。

★ 每个 Key 都有两种放法：环境变量，或 config.local.json。 环境变量优先；配置文件的好处是不会跟着代码一起被提交。 查看当前实际读到哪个：python walkkcal/config.py。

三、技术说明

3.1 调用了哪些 MCP 能力

配置见 mcp-config.example.json（只含 ${MCD_MCP_TOKEN} 占位符）。 不配 Token 也能跑离线演示：读 examples/default/ 快照 + packs/mcd_nutrition_snapshot.py。

3.2 麦当劳实时路径（默认关闭）

让麦当劳走实时需要两个 Key：因为它的门店接口不接收经纬度， 必须先用地图 Key 把坐标翻译成文字地标。

用户坐标 ──① 地图 Key 逆地理编码──▶ city + keyword ──② MCD_MCP_TOKEN──▶ 官方门店

自检命令（会打印每条渠道的门店来源与回退原因）：

WALKKCAL_MCD_LIVE=1 python packs/registry.py
#   · src=mcp        → 走的是官方实时
#   · src=snapshot   → 回退到本地快照，同行写明原因

★ 通用接口一律用经纬度（search_stores(lon, lat, radius)）—— 经纬度是普适的，接口不为任何一家的格式降级；格式翻译统一关在各自的适配层里。

★ 两条链各自的取数方式：

两者默认同源：shoot.py 先实时抓成场景，渲染再读它。 （图上的麦当劳来自地图 POI 的名称匹配，不来自 MCP —— 所以打开实时后文字与图片可能不一致。）

3.3 诚实边界（必须在输出中说明）

1. 中餐热量由菜谱推算，平均误差 25-28%；麦当劳是 MCP 官方精确值
2. 规则已预设：只数推荐菜，不含饮料甜品；多种做法取平均
3. 算不出的不猜 —— 宁可显示「算不出」，不给假数字
4. 数据为快照，不构成医疗建议

详细规则见仓库 README.md 与 docs/ 下的技术文档。

walk-kcal

你今天还能吃多少卡，取决于你愿意走多远。

麦当劳程序员节创意开发大赛参赛作品

试试看（不用装任何东西） ｜ GitHub 源码

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 卡起步

同一街区里，麦当劳的推荐菜大多落在普通人的一餐额度之内。

这不是我们编的，是算出来的。

对热量预算紧张的人来说，走进麦当劳，反而是最安全的选择。

这个工具能做什么

输出一张竖屏长图，可以直接发微信、发小红书。

独特之处

同类赛道里，大多数项目只算了菜品的热量；提到「步行」的，几乎没几个把它接到热量上。

三种形式，同一份结果：

麦当劳 MCP 开放的，是它自己的营养表。可真实场景里，你 400 米外那家面馆多少卡？ 没有人做这件事。我们做了。

内置两款能力 —— 也可以接你自己的

这个 demo 自带两款数据源，开箱即用：

麦当劳的两条通道

只想看个 demo、不想去申请 Token？ 直接跑就行 —— 效果是完整的。 想要实时的门店和营养值，再去申请一个 Token 也不迟：https://open.mcd.cn/mcp（免费）。

可以按需组合 —— 一个环境变量的事：

也可以接你自己的 —— 点评的企业接口、美团、或者你手上任何一份门店／菜品数据。 数据源是可插拔的：加一个文件 + 一个环境变量，主流程 0 行改动。

麦当劳在这里是一个可信的数据源，不是一个产品的边界。

跑起来

先跑内置场景 —— 这一步一个 Key 都不需要。

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 个工具）：

python entry/mcp_server.py            # 直接跑，或者
docker build -t walk-kcal . && docker run -i --rm walk-kcal

快照里已经存好了门店、推荐菜、步行距离和热量 —— 麦当劳的官方营养值也是内嵌的 （demo 用到的 22 条，已按官方实时表校准）。

两套数据源，各配各的 —— 都不配也能跑：

# 抓新点位：地址 → 坐标 → 抓数 → 出图，实测约 16 秒
python walkkcal/shoot.py "上海市黄浦区南京东路100号"

输出格式是可选的：默认出 SVG —— 浏览器打开就能看、放大不糊，大多数场景够用； 想要 PNG（例如直接发微信、小红书），装一个很小的扩展包即可。

全部命令、5 个内置实拍场景、换点位、跨城市、环境变量总表 → docs/快速开始.md

这两款能力是怎么接进来的

不看代码也能看懂的部分：

• 地图 / 语料 / 渠道都是可插拔的。 上层只认一套通用接口 —— 门店用经纬度， 热量用菜名，业态用归一化后的 12 个词。
• 某家的私有格式一律关在它自己的适配层里。 地图服务商的类目名怎么翻译、 某个品牌的门店接口只吃文字地标而不收经纬度 —— 这些差异都消化在各自的 provider / pack 内部，主流程一行都不用改。
• 所以换一家（百度、点评、美团…）＝ 加一个文件 + 一个环境变量。

想看它落到实处 → walkkcal/providers/（地图）· packs/（数据源）· docs/扩展开发.md

麦当劳那条链的具体调用（用了哪些 Tool、怎么和本地估算融合） → MCP_INTEGRATION.md

我们诚实地告诉你

额度是你自己定的预算，不是算法塞给你的建议 —— 走路只让它随距离增长。

中餐热量是估算的（平均误差 25–28%），因为菜谱里几乎没有可用的分量信息 （少数标了「2 人份」，标准却各不相同，我们没有采用），而且配料和调料的影响，有时候比主料还大。 我们花最大力气的地方不是「算得更准」，而是知道什么时候算不准，然后如实显示「算不出」—— 而不是猜一个看起来正常的数字。

宁可少算，不可算错。　详见 → docs/数据源与误差.md

免责

本项目为麦当劳程序员节创意开发大赛参赛作品，由参赛者独立开发，非麦当劳官方产品。 输出仅供参考，不构成医疗、营养或其他专业建议。 餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准。

如果它帮到你了

如果你也常在楼下纠结「这顿吃什么」，它帮你把账算清楚了一点 —— 那点一下右上角的 ⭐ Star 就是最好的鼓励。它不会改变代码， 但会让更多同样在纠结的人看到这个工具。

（也欢迎提 Issue 说说你那个城市的菜算得准不准：哪个算错了、哪个该有却没有。 这比 Star 对它更有用。）

你今天还能吃多少卡，取决于你愿意走多远。