Skip to content
Back to search

mcd-nutrition-expert

身材管控期也想吃麦当劳?这个专家会帮你根据每日消耗搭配麦麦套餐。基于 SP 矩阵理论,打通麦当劳官方 MCP Server 的营养选型与点餐闭环(35 个官方工具 · 14 个 REST 接口 · 零第三方前端依赖)。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chinaopenclaw--mcd-nutrition-expert/badge.svg)](/listings/chinaopenclaw--mcd-nutrition-expert)

HTML

<a href="/listings/chinaopenclaw--mcd-nutrition-expert"><img src="/api/listings/chinaopenclaw--mcd-nutrition-expert/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/ChinaOpenClaw/mcd-nutrition-expert.git
cd mcd-nutrition-expert/skills/mcd-nutrition-expert
pip install fastapi uvicorn

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 529 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 麦当劳营养膳食专家(McDonald's Nutrition Diet Expert)
  2. > 身材管控期也想吃麦当劳?这个专家会帮你根据每日消耗搭配麦麦套餐。
  3. 一个基于 **SP 矩阵理论** 的个人饮食搭配可视化选型工具,基于麦当劳官方 MCP Server 打通「营养计算 → SP 选型 → 套餐推荐 → 门店点餐 → 领券下单 → 健康记录」的完整闭环。
  4. [![MCP](https://img.shields.io/badge/MCP-35%20%E5%AE%98%E6%96%B9%E5%B7%A5%E5%85%B7-DA291C?style=flat-square)](https://github.com/M-China/mcd-mcp-server)
  5. [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square)](https://www.python.org/)
  6. [![FastAPI](https://img.shields.io/badge/FastAPI-14%20REST%20API-009688?style=flat-square)](https://fastapi.tiangolo.com/)
  7. [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
  8. [![WorkBuddy](https://img.shields.io/badge/WorkBuddy-Skill-0052D9?style=flat-square)](workbuddy.md)
  9. [![Stars](https://img.shields.io/github/stars/ChinaOpenClaw/mcd-nutrition-expert?style=social)](https://github.com/ChinaOpenClaw/mcd-nutrition-expert/stargazers)
  10. <p align="center">
  11. <img src="docs/video/assets/social-preview.png" alt="麦当劳营养膳食专家 · SP 矩阵" width="100%">
  12. </p>
  13. <p align="center">
  14. <img src="docs/screenshots/03-sp-matrix.png" alt="SP 矩阵选型界面" width="820">
  15. </p>
  16. <p align="center"><b>SP 矩阵选型界面</b> —— 156 个餐品的真实分布,金色十字是按你的身体档案推导出的目标点</p>
  17. <div align="center">
  18. | 指标 | 数值 | | 指标 | 数值 |
  19. |---|---:|:---:|---|---:|
  20. | 官方 MCP 工具 | **35** | | 营养数据条目 | **160** |
  21. | 门店菜单条目 | **98** | | 菜单 SP 覆盖率 | **88%** |
  22. | 四象限分布 | 主力 47 / 解馋 46 / 填充 53 / 双刃 10 | | 动态阈值 | `P50×0.6 + P75×0.4` |
  23. | REST 接口 | **14** | | 前端第三方依赖 | **0** |
  24. </div>
  25. ---
  26. ## 〇、目标用户与使用示例
  27. ### 目标用户
  28. | 人群 | 典型场景 | 本项目帮他解决什么 |
  29. |---|---|---|
  30. | **体重管理期人群**(减脂 / 塑形) | 加班到八点,只能吃麦当劳,不知道怎么点不超热量 | 按档案算出单餐 626 kcal 目标,直接给出结构合理的套餐(如 555 kcal 低钠方案) |
  31. | **健身增肌人群** | 练完腿想吃麦当劳,需要高蛋白但不想钠爆表 | SP 矩阵的「双刃区」精确标注高蛋白高钠餐品,配合钠上限控制摄入量 |
  32. | **有代谢指标关注需求的人** | 需要控钠(高血压、肾脏指标等日常管理) | 钠负担作为独立维度参与打分,高钠组合会被显著降权 |
  33. | **不想做功课的普通用户** | 站在点餐机前 30 秒做不了决定 | 「一键求解」直接给出 3 套可执行方案 + 象限角标标注,决策时间 < 10 秒 |
  34. | **餐饮 / 营养方向的开发者** | 想学如何把 MCP 用在真实业务场景 | 完整源码 + 架构文档 + API 文档 + 5 个真实接口陷阱记录,可直接复用于其他 MCP 集成 |
  35. | **WorkBuddy 用户** | 希望在对话中直接完成选餐 | 以 Skill 形态交付,可在 WorkBuddy 会话内自然语言调用全链路能力 |
  36. ### 使用示例
  37. > 以下所有数值均为**真实接口实测输出**(`POST /api/recommend`),非示意。
  38. **示例 1 · 减脂期午餐(女 28 岁 / 165cm / 58kg / 中等活动 / 减脂)**
  39. ```
  40. 目标:全天 1625 kcal · 蛋白 116g · 碳水 189g · 脂肪 45g · 钠上限 2000 mg
  41. 单餐目标 552 kcal(1625 × 34%)
  42. 方案一(评分 0.8214)
  43. 637 kcal · 蛋白 44g · 钠 1878 mg · 占全天 39.2%
  44. · 主餐 麦辣鸡腿汉堡 485 kcal
  45. · 饮品 无糖可口可乐中杯 0 kcal
  46. · 小食 蜜汁BBQ风味薄皮脆汁鸡-带骨里脊 152 kcal
  47. ⚠ 钠 1878 mg,已达上限 94%
  48. ⚠ 热量比单餐目标高 84 kcal,训练日可接受,休息日建议减一份小食
  49. 方案二(评分 0.8162)—— 本餐钠负担最低
  50. 580 kcal · 蛋白 33g · 钠 1049 mg · 占全天 35.7%
  51. · 主餐 双层吉士汉堡 429 kcal
  52. · 饮品 优品豆浆小杯 151 kcal
  53. 方案三(评分 0.7963)
  54. 642 kcal · 蛋白 39g · 钠 1474 mg · 占全天 39.5%
  55. · 主餐 双层吉士汉堡 429 kcal
  56. · 饮品 无糖可口可乐中杯 0 kcal
  57. · 小食 麦乐鸡5块 213 kcal
  58. ```
  59. > 💡 系统的价值不止于「给出一套餐」,更在于**同时告诉你取舍在哪**:方案一蛋白最足但钠到 94%,方案二钠只有一半但蛋白少 11g —— 用户可以自己权衡,而不是在「不知道热量」和「只知道热量」之间二选一。
  60. **示例 2 · 增肌日午餐(男 25 岁 / 178cm / 82kg / 高强度活动 / 增肌)**
  61. ```
  62. 目标:全天 3502 kcal · 蛋白 148g · 碳水 535g · 脂肪 86g · 钠上限 2000 mg
  63. 单餐目标 1191 kcal
  64. 方案一(评分 0.7392)—— 含甜点
  65. 1341 kcal · 蛋白 55g · 钠 1838 mg · 占全天 38.3%
  66. · 主餐 芝士安格斯厚牛堡 696 kcal
  67. · 小食 麦麦脆汁鸡-琵琶腿 328 kcal
  68. · 饮品 可乐大杯 224 kcal
  69. · 甜点 圆筒冰淇淋 93 kcal
  70. ⚠ 钠 1838 mg,已达上限 92%
  71. 方案二(评分 0.7193)—— 推荐
  72. 1028 kcal · 蛋白 54g · 钠 1744 mg · 占全天 29.4%
  73. · 主餐 芝士安格斯厚牛堡 696 kcal
  74. · 小食 麦麦脆汁鸡-带骨里脊 332 kcal
  75. · 饮品 无糖可口可乐中杯 0 kcal
  76. 方案三(评分 0.7144)—— 系统主动标红
  77. 1130 kcal · 蛋白 47g · 钠 2149 mg
  78. ⚠ 钠摄入 2149 mg,已超出 2000 mg 上限(超出 149 mg)。
  79. 这是本方案最需要你知晓的取舍点:建议把含糖饮料换成无糖、
  80. 并避免同一天再叠加其他高钠食物。
  81. ```
  82. > 💡 注意方案三:**系统没有藏起这个超标项**。它在 `warnings` 里主动把超出量算给你看,而不是给一个看起来很美的组合 —— 这正是「可解释」的含义。
  83. **示例 3 · 领券点餐闭环(Web 界面)**
  84. ```
  85. 1. 建档 → 身高体重年龄 → 自动出全天目标与 SP 目标点
  86. 2. SP 矩阵 → 156 个餐品按四象限散点分布,金色十字 = 我的目标点
  87. 3. 套餐推荐 → 三套方案,含每样餐品的贴合度百分比
  88. 4. 门店点餐 → 点击门店 → 进店菜单,每个条目带象限角标 + 贴合度
  89. → 套餐自动展开内含单品
  90. 5. 领券 → 「我的卡包」显示已持有的券(显示券码)+ 可领取券
  91. 6. 下单 → 购物车实时计价 → 提交订单
  92. 7. 健康记录 → 吃完记一笔 → 体重趋势 + 热量缺口 + 象限分布回看
  93. ```
  94. **示例 4 · 独立 Web 应用运行**
  95. ```bash
  96. git clone https://github.com/ChinaOpenClaw/mcd-nutrition-expert.git
  97. cd mcd-nutrition-expert/skills/mcd-nutrition-expert
  98. cp .env.example .env # 填入你的 MCP Token
  99. pip install -r requirements.txt
  100. python scripts/server.py # → http://127.0.0.1:8899
  101. ```
  102. **示例 5 · 作为 WorkBuddy Skill 调用**
  103. 见 `workbuddy.md`。核心触发语:
  104. ```
  105. 「帮我按 SP 矩阵推荐一套麦当劳套餐」
  106. 「我今天想吃麦当劳,算一下该怎么点」
  107. 「看看我的热量缺口够不够吃这一套」
  108. ```
  109. ---
  110. ## 一、核心洞察:为什么需要它
  111. 控卡期吃麦当劳,真正的痛点不是「不知道吃什么」,而是:
  112. | 痛点 | 具体表现 | 本项目的解法 |
  113. |---|---|---|
  114. | **不知道该吃多少** | 全天目标 1800 kcal,不知道单餐该占多少 | Mifflin-St Jeor + FAO/WHO 活动系数算出全天 TDEE,再按单餐份额(34%)折算单餐目标 |
  115. | **不知道该点哪个** | 菜单近百个条目,看得见的热量标签为零 | 160 个餐品全量营养数据 + SP 矩阵四象限定位 |
  116. | **不知道哪套搭得值** | 套餐名看不懂,勾起来才发现全是糖和油 | 结构角色模型(主餐/小食/饮品/甜点)+ 多目标约束求解 |
  117. | **不知道自己吃过了什么** | 吃完就忘,热量缺口无从谈起 | SQLite 每日记录 + 体重趋势 + 象限分布可视化 |
  118. ---
  119. ## 二、SP 矩阵理论的应用
  120. ### 2.1 从战略定位到饮食定位
  121. 经典 SP(Sweet Point)矩阵用「竞争强度」与「市场地位」划分战略象限。迁移到饮食选型,映射为两个营养密度维度:
  122. | SP 原始维度 | 饮食映射 | 计算方式 | 业务含义 |
  123. |---|---|---|---|
  124. | X 轴(吸引力) | **营养密度** | (蛋白质g + 碳水g) / (热量/100) | 每 100 kcal 能带来多少克营养 |
  125. | Y 轴(强度) | **钠负担** | 钠mg / (热量/100) | 每 100 kcal 带来多少钠负担 |
  126. ### 2.2 四象限
  127. ```
  128. 钠负担高
  129. │
  130. ┌─────────────┼─────────────┐
  131. │ │ │
  132. │ 解馋区 │ 双刃区 │
  133. │ (低密度高钠) │ (高密度高钠) │
  134. 营养密度低┼─────────────┼────────── 营养密度高
  135. │ │ │
  136. │ 填充区 │ 主力区 ★ │
  137. │ (低密度低钠) │ (高密度低钠) │
  138. └─────────────┼─────────────┘
  139. │
  140. 钠负担低
  141. ```
  142. | 象限 | 定位 | 特征 | 建议 | 实测数量 |
  143. |---|---|---|---|---:|
  144. | **主力区** ⭐ | 日常主力 | 营养密度高、钠负担低 | 控卡期首选,建议常点 | 47 |
  145. | **双刃区** | 双刃剑 | 营养密度高但钠也高 | 增肌日可吃,控卡日限一次 | 10 |
  146. | **解馋区** | 情绪价值 | 营养密度低、钠负担高 | 想吃就吃,别当正餐 | 46 |
  147. | **填充区** | 饱腹陷阱 | 营养密度低、钠负担低 | 减脂期尽量避开 | 53 |
  148. > 上图方位与 `docs/screenshots/03-sp-matrix.png` 实际界面一致(X 轴向右为营养密度递增,Y 轴向上为钠负担递增)。
  149. > 实测 156 个有效样本的分布:**主力区 47 / 解馋区 46 / 填充区 53 / 双刃区 10**。
  150. ### 2.3 贴合度 fit
  151. 每个餐品相对「你的目标点」计算归一化欧氏距离,映射到 0–100% 的贴合度:
  152. ```
  153. fit = 1 - dist / 1.4
  154. ```
  155. 目标点由用户档案推导(蛋白+碳水密度、钠密度),因此**同一个餐品对不同人的贴合度完全不同**——这正是 SP 矩阵作为「个人化选型工具」的价值。
  156. ### 2.4 界面实录
  157. | ② SP 矩阵选型 | ③ 个性化套餐推荐 |
  158. |---|---|
  159. | ![SP矩阵](docs/screenshots/03-sp-matrix.png) | ![套餐推荐](docs/screenshots/04-recommend.png) |
  160. 散点图每个点是一个餐品,金色十字是你的目标点;右侧按贴合度排序,直接给出「最该点的那一个」。
  161. | ④ 门店点餐 | ⑤ 健康可视化 |
  162. |---|---|
  163. | ![门店点餐](docs/screenshots/05-menu.png) | ![健康可视化](docs/screenshots/07-health.png) |
  164. 菜单里每个条目都带 SP 象限角标与贴合度百分比;健康页把每日摄入与目标画在同一张图上,缺口一目了然。
  165. ---
  166. ## 三、功能全景
  167. ### ① 建档 · 营养目标计算
  168. - **BMR**:Mifflin-St Jeor 公式;若用户填写体脂率则切换到 Katch-McArdle(瘦体重法)修正
  169. - **TDEE**:BMR × FAO/WHO 活动系数(sedentary 1.2 / light 1.375 / moderate 1.55 / active 1.725 / athlete 1.9)
  170. - **四种目标模式**:
  171. | 模式 | 热量系数 | 蛋白质 | 说明 |
  172. |---|---|---|---|
  173. | 减脂 cut | TDEE × 0.80 | 2.0 g/kg | 20% 热量缺口,保肌 |
  174. | 维持 maintain | TDEE × 1.00 | 1.4 g/kg | 体重管理 |
  175. | 增肌 bulk | TDEE × 1.12 | 1.8 g/kg | 12% 盈余 |
  176. | 塑形 recomp | TDEE × 0.90 | 1.8 g/kg | 温和缺口 + 高蛋白 |
  177. ### ② SP 矩阵可视化选型
  178. - 原生 Canvas 绘制散点矩阵(零第三方依赖,离线可用)
  179. - 象限底色 + 动态分界线(P50×0.6 + P75×0.4)
  180. - 散点半径随贴合度变化,金色十字为你的目标点
  181. - 四象限直方图统计
  182. ### ③ 套餐推荐求解器
  183. **结构角色模型**(取代朴素分类笛卡尔积):
  184. ```
  185. 主餐(唯一) → 小食(≤1) → 饮品(唯一) → 甜点(≤1)
  186. ```
  187. 硬约束组合:
  188. - 主餐占本餐热量 40%–85%
  189. - 角色级热量上限(比例 ∪ 真实规格绝对上限的较大值)
  190. - 配菜必须带蛋白(≥6g)或足量主食(≥120 kcal)——防止「玉米杯」挤掉真正的蛋白源
  191. - 减脂/塑形模式禁止甜点
  192. - 钠 ≤ 全日上限 × 1.25
  193. **多目标加权打分**:
  194. | 维度 | 权重 | 说明 |
  195. |---|---|---|
  196. | 热量命中 | 26% | 相对单餐目标的偏离度 |
  197. | 蛋白质 | 28% | 相对单餐蛋白目标 |
  198. | 碳水 | 13% | |
  199. | 脂肪 | 11% | |
  200. | 钠友好 | 14% | 分段函数,超限强扣分 |
  201. | 饱腹性价比 | 8% | 饱腹价值 / 热量密度 |
  202. **局部搜索改进**:加一份 / 减一份 / 换一份三邻域迭代 + 多样性去重。
  203. 实测输出(25 岁男性 / 175cm / 70kg / 轻度活动 / 减脂,全天目标 1841 kcal、单餐目标 626 kcal):
  204. ```
  205. 方案 1 719 kcal(占全天 39%)· 蛋白 44g · 钠 1981mg
  206. 板烧鸡腿堡 + 麦麦脆汁鸡-琵琶腿 + 无糖可口可乐中杯
  207. 方案 2 611 kcal(占全天 33%)· 蛋白 43g · 钠 1993mg
  208. 麦辣鸡腿汉堡 + 无糖可口可乐中杯 + 蒜了吧黄油风味薄皮脆汁鸡-带骨里脊
  209. 方案 3 555 kcal(占全天 30%)· 蛋白 46g · 钠 1802mg
  210. 双层吉士汉堡 + 蒜了吧黄油风味薄皮脆汁鸡-带骨里脊 + 无糖可口可乐中杯
  211. ```
  212. 三套方案都满足「主餐唯一 + 饮品唯一 + 小食 ≤1 + 甜点 ≤1」的结构约束,
  213. 且饮品位固定落在零卡选项上——这是控卡期的关键:热量与钠的波动全部来自主餐与小食的选择。
  214. ### ④ 门店点餐(点击门店进入店内)
  215. - 门店列表 → 点击进店 → 分类 tab → 菜单网格
  216. - **每个菜单条目都带 SP 象限标签 + 贴合度 + 营养四宫格(热量/蛋白/脂肪/钠)**
  217. - 套餐条目自动展开内含单品(「含:龙焰鸡腿堡 / 中薯条 / 可乐中杯」)
  218. - 新品未收录营养表时按品类关键词近似估算,并显式标注「新品估算」
  219. - 购物车 sticky bar → 实时计价(分/元双口径换算)→ 下单 → 自动记入健康档案
  220. ### ⑤ 优惠券与下单
  221. - 可领取 / 我的卡包 / 本店可用三段式
  222. - 一键领券(`auto-bind-coupons`)
  223. - 计价与下单走 `calculate-price` / `create-order`,正确处理 `productCode` + `quantity` 契约与「分」单位
  224. ### ⑥ 健康可视化记录
  225. - SQLite 三表分离:`daily_log`(日汇总)/ `meal_log`(明细)/ `profile`(档案)
  226. - KPI 卡 + 体重折线 + 热量收支双线 + 象限分布条形图
  227. - 自动补齐空日期,连续性趋势不断裂
  228. ---
  229. ## 四、技术架构
  230. ```
  231. ┌─────────────────────────────────────────────┐
  232. │ web/index.html (单文件前端 · 原生 Canvas) │
  233. │ ①建档 ②SP矩阵 ③套餐推荐 ④门店点餐 ⑤健康可视化 │
  234. └──────────────────┬──────────────────────────┘
  235. │ HTTP / JSON
  236. ┌──────────────────▼──────────────────────────┐
  237. │ scripts/server.py FastAPI + uvicorn │
  238. │ /api/health /api/target /api/matrix │
  239. │ /api/recommend /api/stores /api/menu │
  240. │ /api/coupons /api/cart /api/order │
  241. │ /api/records /api/records/weight /api/account│
  242. └──────────────────┬──────────────────────────┘
  243. │
  244. ┌───────────────┼────────────────┐
  245. │ │ │
  246. ┌──▼──────────┐ ┌──▼─────────┐ ┌────▼──────────┐
  247. │nutrition_ │ │combo_ │ │sp_matrix.py │
  248. │engine.py │ │solver.py │ │ SP 四象限 │
  249. │ BMR/TDEE │ │ 约束求解 │ │ 贴合度 │
  250. │ 目标计算 │ │ 局部搜索 │ └───────────────┘
  251. └─────────────┘ └────┬───────┘
  252. │
  253. ┌──────────────┐ ┌───▼─────────┐ ┌──────────────┐
  254. │mcp_client.py │ │health_store │ │ │
  255. │ MCP 客户端 │ │ SQLite │ │ │
  256. └──────┬───────┘ └───┬─────────┘ └──────────────┘
  257. │ │
  258. ┌──────▼─────────────▼──────────┐
  259. │ 麦当劳官方 MCP Server │
  260. │ https://mcp.mcd.cn (35 个工具) │
  261. └──────────────────────────────────┘
  262. ```
  263. ### 模块职责
  264. | 文件 | 职责 |
  265. |---|---|
  266. | `scripts/nutrition_engine.py` | BMR/TDEE/目标计算、餐品分类表、策略建议 |
  267. | `scripts/combo_solver.py` | 结构角色模型、多目标约束求解、局部搜索 |
  268. | `scripts/sp_matrix.py` | SP 四象限计算、贴合度、象限多样性推荐 |
  269. | `scripts/mcp_client.py` | MCP Streamable HTTP 客户端(限流/重试/退避) |
  270. | `scripts/health_store.py` | SQLite 健康档案(三表分离) |
  271. | `scripts/server.py` | FastAPI 后端 + 价格口径归一 + 套餐聚合 |
  272. | `scripts/shoot_views.js` | Playwright 前端五视图截图验证(回归用) |
  273. | `web/index.html` | 单文件前端(原生 Canvas 图表,零第三方依赖) |
  274. ### 菜单 SP 覆盖率
  275. 门店菜单里约 **56%** 的条目是「三件套 / 四件套 / 分享餐」,官方营养表只收录单品。
  276. 项目通过 `query-meal-detail` 拉取套餐内含单品、按热量加权聚合出套餐自身的 SP 坐标,
  277. 配合五级名称匹配(精确 → 去后缀 → 去前缀修饰 → 双向包含 → 品类关键词回退),
  278. 把菜单的 SP 标注覆盖率从 **31/87(35%)提升到 86/98(88%)**。
  279. 未被营养表收录的新品,按同品类中位单品近似并显式标注「新品估算」,不假装精确。
  280. ---
  281. ## 五、快速开始
  282. ### 环境要求
  283. - Python 3.10+
  284. - 麦当劳 MCP Server 访问 Token
  285. ### 安装
  286. ```bash
  287. git clone https://github.com/ChinaOpenClaw/mcd-nutrition-expert.git
  288. cd mcd-nutrition-expert/skills/mcd-nutrition-expert
  289. pip install fastapi uvicorn
  290. ```
  291. ### 配置
  292. ```bash
  293. cp .env.example .env
  294. # 编辑 .env,填入你的 MCP Token
  295. ```
  296. ```ini
  297. MCD_MCP_URL=https://mcp.mcd.cn
  298. MCD_MCP_TOKEN=your_token_here
  299. ```
  300. ### 运行
  301. ```bash
  302. cd scripts
  303. python -m uvicorn server:app --host 127.0.0.1 --port 8899
  304. ```
  305. 浏览器打开 <http://127.0.0.1:8899> 即可。
  306. ### 离线自测
  307. ```bash
  308. cd scripts
  309. python combo_solver.py --selftest # 求解器自检(内嵌样例数据)
  310. python nutrition_engine.py --demo # 营养目标计算演示
  311. ```
  312. ---
  313. ## 六、目录结构
  314. ```
  315. mcd-nutrition-expert/
  316. ├── CONTEST_DECLARATION.md # 参赛声明(原文,内容不可改)
  317. ├── MCP_INTEGRATION.md # MCP 集成说明(含 5 个真实踩坑记录)
  318. ├── mcp-config.example.json # 脱敏 MCP 配置示例(仅环境变量占位符)
  319. ├── workbuddy.md # WorkBuddy Skill 使用说明
  320. ├── README.md
  321. ├── deck/
  322. │ └── index.html # 项目讲解视频幻灯片源(14 页,红金主题)
  323. ├── tools/ # 讲解视频生产流水线(可复现)
  324. │ ├── make_sp_svg.py # 用真实接口数据渲染 SP 矩阵 SVG
  325. │ ├── render_deck.js # Playwright + chromium 渲染 14 张幻灯片
  326. │ ├── narration.py # 14 段旁白文案(与幻灯片一一对应)
  327. │ ├── pronunciation_overrides.py # 多音字读音覆盖表(单一数据源)
  328. │ ├── tts_stepaudio.py # StepAudio 2.5 TTS 引擎(Key 走环境变量)
  329. │ ├── resynth.py # 只重合成指定段落(改文案后省配额)
  330. │ ├── assemble_narration.py # 分段音频 → 单轨 wav + timeline.json
  331. │ ├── build_video.py # 幻灯片 + 音轨 → 1080p 成片
  332. │ ├── check_quadrants.py # 象限语义门禁(前端/视频 vs 后端判定)
  333. │ ├── verify_sp_canvas.js # 浏览器内逐点校验 Canvas 象限归属
  334. │ └── make_social_preview.py # 生成 GitHub 社交预览图
  335. ├── docs/
  336. │ ├── ARCHITECTURE.md # 架构与算法说明
  337. │ ├── API.md # 接口清单
  338. │ ├── 项目简介.md # 申报与答辩素材源(一句话/150/350/800 字四版)
  339. │ ├── 项目简介-纯文本.txt # 纯文本版,便于粘贴到 Issue / 表单
  340. │ ├── screenshots/ # 前端五视图实录
  341. │ └── video/ # 讲解视频产物
  342. │ ├── assets/sp-matrix.svg # 真实数据 SP 矩阵图
  343. │ ├── slides/ # 14 张 1080p 幻灯片
  344. │ └── audio/ # 旁白音轨(gitignore)
  345. └── skills/mcd-nutrition-expert/
  346. ├── SKILL.md # Skill 定义
  347. ├── .env.example # Token 占位符
  348. ├── scripts/ # 六个核心模块 + 截图脚本
  349. ├── web/index.html # 单文件前端
  350. ├── references/ # 参考资料
  351. └── data/health.db # 本地 SQLite(gitignore)
  352. ```
  353. ---
  354. ## 七、项目讲解视频
  355. `tools/` 下是一条完整可复现的流水线,从真实接口数据到 1080p 成片:
  356. | 步骤 | 命令 | 产出 |
  357. |---|---|---|
  358. | 1 · 生成 SP 矩阵图 | `python tools/make_sp_svg.py` | `docs/video/assets/sp-matrix.svg`(真实数据散点图) |
  359. | 2 · 渲染幻灯片 | `node tools/render_deck.js` | `docs/video/slides/slide-01..14.png`(1920×1080@2x) |
  360. | 3 · 合成旁白 | `python tools/tts_stepaudio.py --voice ruyananshi --speed 1.2` | `docs/video/audio/s01..14.wav` |
  361. | 4 · 装配音轨 | `python tools/assemble_narration.py --source stepaudio` | `docs/video/audio/narration.wav` + `timeline.json` |
  362. | 5 · 合成成片 | `python tools/build_video.py` | `docs/video/麦当劳营养膳食专家_项目讲解_1080p.mp4` |
  363. 要点:
  364. - **音画严格对齐** —— 第 4 步产出 `timeline.json`,第 5 步按段时长裁切画面
  365. - **画面完全静止**,仅做 0.30s 淡入 / 0.34s 淡出,不做推镜,避免逐帧亚像素抖动
  366. - **多音字读音受控** —— `pronunciation_overrides.py` 维护 157 条读音覆盖
  367. (矩阵/阈值/中位数/解馋/膳食/打烊/琵琶腿…),StepAudio 的 `pronunciation_map` 原生生效
  368. - **ffmpeg 自动探测** —— 支持 `MCD_FFMPEG` 环境变量、`@ffmpeg-installer`、PATH 三级回退
  369. > **TTS 凭据**:第 3 步需要自备 StepAudio 兼容网关的 API Key,仓库内不保存任何明文凭据。
  370. > ```bash
  371. > export HCNSEC_API_KEY="sk-..." # bash
  372. > $env:HCNSEC_API_KEY = "sk-..." # PowerShell
  373. > ```
  374. > 改文案后若只想重合成个别段落,可用 `python tools/resynth.py 3` 单独重跑第 3 段。
  375. **象限语义门禁** —— SP 矩阵有「后端判定」与「前端/视频绘制」两条语义线,必须始终一致。
  376. `tools/check_quadrants.py` 从真实接口取数,逐点校验散点落入的底色矩形与后端 quadrant 是否匹配:
  377. ```bash
  378. python tools/check_quadrants.py
  379. # [1] SVG 视频素材
  380. # ✓ SVG:156 个散点全部落在与后端判定一致的象限内
  381. # [2] 前端 Canvas
  382. # ✓ 前端 drawSP() 象限坐标与后端语义一致(主力区、双刃区、解馋区、填充区)
  383. ```
  384. 象限语义(与 `scripts/sp_matrix.py` 判定逻辑一一对应):
  385. | 象限 | 判定条件 | 方位 | 特征 | 实测 |
  386. |---|---|---|---|---:|
  387. | **主力区** | `x ≥ x_th 且 y < y_th` | 右下 | 高营养密度 + 低钠 | 47 |
  388. | **双刃区** | `x ≥ x_th 且 y ≥ y_th` | 右上 | 高营养密度 + 高钠 | 10 |
  389. | **解馋区** | `x < x_th 且 y ≥ y_th` | 左上 | 低营养密度 + 高钠 | 46 |
  390. | **填充区** | `x < x_th 且 y < y_th` | 左下 | 低营养密度 + 低钠 | 53 |
  391. ---
  392. ## 八、隐私与安全
  393. - **Token 只从环境变量读取**,不写入代码库,不出现在任何提交中
  394. - **API Key 同样只从环境变量读取** —— `tools/tts_stepaudio.py` 不含任何明文凭据,
  395. 未设置 `HCNSEC_API_KEY` 时直接报错退出,不发起无意义的网络请求
  396. - 仓库历史已做凭据清洗(`git filter-branch`),当前所有提交均不含明文密钥
  397. - `.env` / `data/*.db` 已加入 `.gitignore`
  398. - 健康档案(体重、饮食记录)仅存储在本地 SQLite,不上传任何服务器
  399. - 所有 MCP 调用均通过 `mcp_client.py` 统一出口,便于审计
  400. ---
  401. ## 九、致谢
  402. - 麦当劳程序员节创意开发大赛提供的 MCP Server 与 35 个官方工具
  403. - 官方营养数据(160 个餐品的完整营养成分)
  404. - SP 矩阵理论(Sweet Point 战略定位矩阵)的思想迁移
  405. ---
  406. **免责声明**:本项目为赛事参赛作品,由参赛者独立开发,非麦当劳官方产品。输出仅供参考,不构成医疗、营养或其他专业建议。餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.