yuexuan521 / git-to-big-mac-hedger

# 🍔 Git 提交与巨无霸热量对冲器
> **努力了一天，应该好好放松。**
>
> 你今天的努力没有被记在 OKR 里，也没有出现在周报上——但它确实发生了。
> 我们把它从 Git 里挖出来，折算成一顿**刚好配得上今天**的麦当劳。
读取你今天的 Git 提交 → 评估这一天的分量（L1~L4）→ 算出热量上限 → 通过麦当劳 MCP 从**真实门店菜单与优惠**里挑出一份「性价比最高 / 折扣力度最大」的治愈系套餐 → 打印一张《赛博治愈对冲账单》。
零依赖，`node index.js --demo all` 即可跑通全流程。
---
## 一、为什么做这个
程序员的一天是高度非线性的。写了 13 个 commit 的那天和写了 2 个的那天，身体感受完全不同，但日历上看起来一模一样。
于是出现两种坏结局：
- **过度补偿**：今天只改了三行文档，晚上却点了全家桶，负罪感到凌晨两点。
- **不敢犒赏**：今天线上着火救了一整天，最后只吃了碗泡面，觉得"也没干什么"。
这两种情况是同一个问题：**没有一个客观的量尺，去衡量"今天值多少放松"**。
工时是自报的，会撒谎；Git 是副产品，不会。**这个项目就用 Git 里的增删行数，给今天的努力定个价。**
---
## 二、四个层次：从微光到拯救世界
| 等级 | 名称 | English | 判定分数 | 热量上限 | 判词 |
| :--: | --- | --- | ---: | ---: | --- |
| **L1** | 微光轻步 | Chill | `Score 另：深夜提交 2 次、周末提交 13 次、热修/回滚 3 次——这些不计入得分，但今天确实更累。
原因很简单：**计分会造成双重惩罚**。热修那天通常行数本来就多，再叠一个 25 分/次的加成，会把 L4 推到几千分去，让 1200 这个门槛失去意义；而「深夜」取决于你的时区与作息习惯，把它算进客观分里是不公平的。把它降级为一句人话提示，信息没丢，标定反而干净了。
---
## 三、怎么挑套餐：不是最便宜，是刚刚好
拿到热量上限后，程序读 `data/live/` 里的 **mcd-mcp 真实快照**（菜单价格、营养热量、套餐成分、可领优惠券），拼成一份可核算的商品目录，然后逐个打分：
 [code] 
**硬约束：总热量 ≤ 今日上限。** 超了直接排除，并明确告诉你差多少（账单里的「差一点点」）。
### 为什么留 25% 给额度利用率
纯按折扣排序会退化成「买最便宜的打折品」：L4 拿着 2000 kcal 的额度，被推荐一杯 9.9 元的冰美式——这是明显的产品事故。利用率这一项就是防它的。反过来，纯按利用率排又会推荐最贵的，所以三项必须共存。
### 为什么要有「点两份」
门店在售的最顶套餐是 `全明星双人分享餐八件套`（2142 kcal），**超出 L4 的 2000 上限**；次一档的套餐只有 949 kcal，L4 的额度永远用不到一半。于是匹配器会给每个打折套餐额外生成一个 **×2 候选**（热量、价格、优惠同倍放大，**折扣率不变**），只有放得进额度的才会进入候选集。
实测效果：L4 从「949 kcal / 47% 利用率」变成「1842 kcal / 92% 利用率」，而 L3 因为装不下双份，结论稳定停在单份——四档推荐不再重复。用 `--no-double`（或代码里 `maxPortions: 1`）可以关掉。
### 热量是算出来的，不是估的
真实接口不给套餐热量，只给成分。所以流程是：
 [code] 
名字对不上就**排除该商品**，绝不猜一个数字。本轮有 20 个商品因此被排除（例如「Hold不住鸡排堡（椒盐风味）」不在营养表中），账单里会写明「已排除 20 个无法核算热量的商品，不做估算」。
---
## 四、快速开始
不需要 `npm install`，没有任何第三方依赖。
 [code] 
### 终端输出长这样
 [code] 
账单之后跟一段补充说明：为什么是它 / 备选方案 / 差一点点 / 距下一档还差多少 / 哪些信号不计分 / 数据源与排除数。加 `--no-extras` 只输出账单主体。完整样例见 docs/sample-report.md。
### 四档演示的实测结果
| 场景 | 描述 | 新增/删除/提交 | 得分 | 等级 | 上限 | 推荐套餐 | 价格 | 热量 |
| --- | --- | --- | ---: | :--: | ---: | --- | ---: | ---: |
| `l1` | 周四 · 正常下班 | 18 / 4 / 2 | 84 | L1 | 400 | 那么大鸡排（椒盐风味） | ¥14.0 | 385（96%） |
| `l2` | 周四 · 稳步推进 | 180 / 40 / 4 | 360 | L2 | 700 | 麦乐鸡经典中套餐 | ¥25.0 | 649（93%） |
| `l3` | 周五 · 攻坚 + 加班 | 380 / 180 / 7 | 860 | L3 | 1100 | 麦辣鸡腿汉堡三件套 | ¥33.5 | 921（84%） |
| `l4` | 周六 · 线上救火通宵 | 700 / 320 / 13 | 1570 | L4 | 2000 | 麦辣鸡腿汉堡三件套 ×2 | ¥67.0 | 1842（92%） |
四档推荐**互不重复**，额度利用率都在 84% 以上——不是"努力了一天推荐你吃个甜筒"。
加 `--unlimited` 后 L4 会切到真正的无上限，此时答案是 `全明星双人分享餐八件套`（2142 kcal，56.4% off，¥49.9/原价 ¥114.5）——那份超出上限 142 kcal 的双人餐，正好是"宇宙级功德"该有的样子。
### 命令行参数
| 参数 | 说明 |
| --- | --- |
| `--demo [l1\|l2\|l3\|l4\|all]` | 使用内置演示场景（默认 `l3`） |
| `--input ` | 解析贴进来的 `git log --shortstat` / `git diff --stat` 文本 |
| `--days ` | 统计最近 n 天，默认 1 |
| `--store ` | 门店编码（快照默认 `1450750`，不一致会明确报错而不是静默回退） |
| `--unlimited` | L4 视为不限热量（默认 2000 kcal） |
| `--out ` | 导出 Markdown 账单 |
| `--record ` | 导出 MCP 调用记录 |
| `--json [file]` | 输出机器可读 JSON（`-` 表示 stdout） |
| `--no-extras` | 只输出账单主体 |
| `-h, --help` | 帮助 |
---
## 五、麦当劳 MCP 接入
本项目调用的是真实的 **`mcd-mcp`**，工具以宿主原生形态注入。用到的 5 个接口：
| 工具 | 作用 | 本项目怎么用 |
| --