门店菜品热量计算·免费版（store-dish-calorie-lite）

> 🆓 免费引流版：单次最多算 10 道菜，功能与专业版完全一致。
> 需要一次算整本菜单（11~100 道）？请用 store-dish-calorie（¥29.9/单次 ≤100 道）。

一、功能简介

给谁用：想先试算几道招牌菜热量的餐饮门店老板、菜单研发、连锁运营。

交付什么：把你口述或表格里的「菜名 + 食材 + 克重」，算出每道菜的热量、蛋白质、脂肪、碳水化合物、膳食纤维，输出：

• 逐道菜营养报告（人读）
• 菜单营养总表（Markdown 表，可直接贴进菜单/外卖平台）
• 结构化 JSON（机器读，含未匹配/歧义标记，供下游判断数据完整度）
• GEO JSON-LD（schema.org Recipe + NutritionInformation，可直接投喂 AI 搜索 / 紫微台）

内置 312 条中餐常见食材库，采用整数定点计算（零浮点误差）；规格系数（大份 ×1.5 / 双人份 ×2.0）仅在展示层乘，底层恒算标准份。

核心价值：零成本先体验「食材→营养」全流程；歧义食材（如「油」「花生」）列出候选强制确认，库外食材如实标为未匹配而绝不编造营养值。

二、使用示例

示例 1 · 单道菜
> 输入：「宫保鸡丁：鸡胸肉 200g、花生 50g、食用油 15g、黄瓜 80g」
> 输出：热量 700.65 kcal ｜ 蛋白 51.84g ｜ 脂肪 47.3g ｜ 碳水 18.17g ｜ 纤维 2.55g
> （并提示「花生」存在歧义，已按 花生（炒） 计）

示例 2 · 少量菜品批量（免费额度内）
> 输入：「先帮我算这 6 道菜的热量」（附 Excel / 口述 1~10 道菜）
> 输出：菜单营养总表（菜名 │ 热量 │ 蛋白 │ 脂肪 │ 碳水 │ 纤维），并列出需确认的歧义项与库外食材
> （超过 10 道会自动提示升级专业版）

示例 3 · 投喂 AI 搜索
> 输入：「把算好的营养数据同步到紫微台」
> 输出：符合 schema.org 规范的 JSON-LD，可直接 POST 到紫微台模块对接桥

三、触发词

• 帮我算下这道菜的热量 / 这道菜多少卡路里
• 给菜单每道菜标上热量 / 出一份菜品营养表
• 先试算几道菜的营养成分（10 道以内）
• 这份套餐多少卡路里 / 营养含量是多少
• 算出这道菜的蛋白质脂肪碳水
• 把菜品营养数据同步到紫微台 / 生成 GEO 营养数据

四、边界与依赖

五、安全承诺

• 只读：仅读取你指定的菜单文件与技能自带食材库，不扫描、不遍历你的其他目录
• 不上传：默认不发送任何数据到外部服务器；GEO 同步为可选显式动作，需你提供端点与令牌才会执行
• 不改源文件：绝不修改/覆盖你的原始菜单文件，结果只输出到 stdout 或你指定的新文件
• 无 shell 执行：除调用自身脚本外，不执行任何系统命令、不下载远程代码
• 零依赖：不安装任何第三方包，无可疑网络请求

概述

让餐饮门店老板用「自家菜品配方」算出每一道菜的热量与三大营养素。门店老板只会说
「宫保鸡丁：鸡胸肉 200g、花生 50g、油 15g……」，不会给食材 id —— 本技能内置 312 条食材库
与名称查表（模糊匹配 + 歧义提示），把口语化配方转成精确营养合计，输出可读报告或机器 JSON。

计算采用整数定点算法（原型同款，零浮点误差），底层恒算标准份，规格系数（大份/双人份）
仅在展示层乘。详见 references/food_data_spec.md。

何时使用

• 门店老板问「这道菜多少卡路里」「帮我算下招牌菜的热量」（10 道以内）
• 老板想先试算几道菜，再决定要不要算整本菜单（>10 道 → 专业版 store-dish-calorie）
• 老板发了菜品配方表（docx / Excel / 口述），想批量算营养
• 想把菜品营养结构化发布到 AI 搜索（GEO / 紫微台模块对接桥）

工作流

第 1 步 · 收集菜品配方

向老板确认每道菜的 菜名 + 食材及克重。两种入口：
- 口述/对话：逐道问「这道菜用了什么、各多少克？」；或老板一次性口述多道。
- 文件：老板丢来菜单 docx / Excel（列：菜品名、食材名、克重），解析成配方行
（列映射 [菜品名称, 分类, 食材名称, 克重(g), 备注]）。

> 克重是精度关键。若老板只给「适量/少许」，按常识估算并告知是近似值；不要假装精确。
> 免费版单次最多 10 道菜，若菜品较多请先选 10 道以内试算，或引导老板使用专业版算整本菜单。

第 2 步 · 归一化为 menu.json

构造如下结构的数组（每道菜一个对象），写入临时文件（如 /tmp/menu.json）：

[
  {
    "name": "宫保鸡丁",
    "brandName": "老王川菜馆",
    "spec": "std",
    "ingredients": [
      {"food": "鸡胸肉", "weight_g": 200},
      {"food": "花生",   "weight_g": 50}
    ]
  }
]

food 用老板口述的食材名即可（脚本会自动查表）；weight_g 为可食部克重，必须为正数
（负数/零/非数字会被自动剔除并标注，绝不参与计算）。

> 可直接参考内置示例：references/sample_menu.json（老王川菜馆 5 道菜，含歧义与库外食材）。

第 3 步 · 运行计算

node <skill>/scripts/calc_dish.js --menu /tmp/menu.json --max-dishes 10

<skill> 为技能根目录（含 scripts/、assets/）。脚本会：查表匹配食材 → 定点合计 →
打印每道菜报告。未匹配/歧义/非法克重都会在报告中明确指出。

> 额度：免费版单次最多 10 道。脚本强制拦截、无法通过参数突破——传入菜品 >10 或
> --max-dishes >10 都会报 ⛔ 免费版单次上限 10 道 并以退出码 2 结束，
> 并提示升级专业版。整本菜单（11~100 道）请用 store-dish-calorie（¥29.9/单次 ≤100 道）。

第 4 步 · 处理未匹配与歧义（重要）

• 歧义（如「油」「花生」可能指多种）：报告已列候选，但默认取第一项。必须向老板确认
  或生成 --map 纠偏文件后重算。纠偏示例 fix.json（右侧必须是库内精确名称）：

json {"花生": "花生（炒）", "豆腐": "豆腐（北/老）"}

重算：node <skill>/scripts/calc_dish.js --menu /tmp/menu.json --map /tmp/fix.json

> ⚠️ 歧义不消解会显著失真：实测「宫保鸡丁」若把花生误取为花生油，热量会偏高约 163 kcal、
> 蛋白少算约 12g（见 references/demo_output.md）。

• 未匹配（食材库没收录，如「干辣椒」「猪肉末」）：请老板从库中选近似项，或后续补库；
  该食材排除出合计并在报告标注。
• 非法克重（负数/零/非数字）：自动剔除并标注，绝不产出负营养值。

第 5 步 · 交付前跑质量闸门（必做）

node <skill>/scripts/verify_harness.js --menu /tmp/menu.json

18 项自动校验（输入合法性 / 输出可解析 / 无 NaN·null 泄漏 / 关键字段齐全 / 数值非负 /
计算确定性 / 未匹配如实标注 / 非法克重剔除 / JSON-LD 合规）。全部 PASS 才可交付，
任一项失败会列出具体问题并以退出码 1 结束。

第 6 步 · 输出结果给老板

• 逐道菜营养报告（默认文本，已含热量/蛋白/脂肪/碳水/纤维）
• 菜单营养总表：汇总成 Markdown 表格（菜名 │ 热量 │ 蛋白 │ 脂肪 │ 碳水）
• GEO JSON-LD（如要发布到 AI 搜索）：加 --geo --json 生成 schema.org Recipe，
  可直接 POST 到紫微台模块对接桥（见 references/food_data_spec.md 第 5 节）

node <skill>/scripts/calc_dish.js --menu /tmp/menu.json --geo --json

脚本与资源

注意事项

• 免费额度：单次最多 10 道菜；整本菜单请用专业版 store-dish-calorie（¥29.9/单次 ≤100 道）。
• 克重口径：所有营养基于「可食部克重」，带骨/带壳/烹饪失水不折算，除非老板明确说明。
• 油/调料易低估：门店菜热量常来自油和糖，务必让老板把「油、糖、酱」的克重也报上。
• 库未覆盖：食材库以中餐常见原料为主，西餐/新式食材可能缺失，缺失项如实告知并建议补库。
• 不要编造营养值：查不到就标未匹配，绝不用估算值冒充库数据。
• 歧义必须确认：尤其「油」「花生」「豆腐」这类同名多条目的食材，不确认会显著失真。