smart-diet-tracker (中国营养膳食指南)

> 能力契约单一事实源。正文遵循极简工程规范，细节下沉至 references/，跨平台确定性执行。

能力边界

能做：
1. 膳食指南八大准则与平衡宝塔评估：全面对齐《中国居民膳食指南 (2022)》，监控平衡膳食宝塔五大类（谷薯类、蔬菜类、水果类、水产肉蛋类、奶豆坚果类）覆盖度，核算食物多样性达标指数（每天 $\ge 12$ 种、每周 $\ge 25$ 种，不含调味品与补剂），评估深色蔬菜过半（$\ge 150\text{g}$）、全谷杂豆（$50 \sim 150\text{g}$）与奶制品（$300 \sim 500\text{ml}$）达标情况。
2. 身体档案录入与出生年份防固化：采集性别、出生年份/年月、身高、当前体重与活动水平，自动计算当前实岁（随公历年份动态演进计算，彻底防范年龄固化）、BMR 与 TDEE。目标设定以身体检测结果与个性化计划为准，检测结果、计划与动态实岁落盘于腾讯文档【目标】子表并双轨同步本地；原始默认配置仅供冷启动参考。支持绑定用户自有的腾讯文档 ID。
3. 自然语言多餐次与包装条码智能记录：智能解析用户自然语言输入与 8-14 位商品条形码（内置 Open Food Facts 官方数据库双镜像自动匹配），提取餐次（早餐/午餐/晚餐/加餐/零食/饮品/运动）、发生时间、食物组成、生熟重、调味与补剂，估算热量及宏量营养素。
4. 腾讯文档时间降序排版与防覆盖同步：通过 sheet-mcp 将单餐流水在【每日记录】按时间严格降序（date DESC, time DESC）计算位置插入新行或原位覆盖更新，杜绝误覆盖历史记录；自动汇总当日数据并在【每日汇总】按日期降序插入或幂等更新；严格执行快速通道协议（云端幂等去重、四步排版协议、平铺并发降级、空值显式清理与用户自留列强保护）。
5. 餐后状态与油脂吸收评估：监测高油脂餐饮对消化与代谢的影响；支持选填餐后 1h/2h 生理指标，若发现高脂诱发的消化延迟（2h >= 1h 且 2h >= 7.0），判定为延迟升糖并执行餐后轻运动与下餐控油干预方案。
6. 多维营养看板与体重统计学去噪：精细核算净碳水、蛋白质 MPS 达标餐数、食物多样性评分、钠摄入与水肿风险、进食时间窗；运用 EWMA 指数加权移动平均与 OLS 线性回归斜率，剥离水钠储留与糖原结合水波动，消除称重焦虑。
7. 平衡膳食红榜指引与外食避雷：依据《中国居民膳食指南》及用户真实红黑榜，严格过滤高盐高油料理包外卖与劣迹店铺毒点，根据当前剩余预算提供合规点餐推荐与进食顺序流。
8. 高频食材动态自学习与个性化沉淀：建立用户本地动态食材库（~/.diet_tracker/custom_foods.json），扫码与手工登记的个性化食材自动转存并累计频次；匹配时结合静态词典与动态库，按使用频次与词长优先匹配。
9. 拍照视觉三阶解耦与生物定标核算：接收用户餐饮照片时，强制执行三阶推理（食材分割清单 -> 烹调方式与吸油率判定 -> 肢体标尺克重折算），杜绝端到端盲猜总卡路里；驱动确定性 CLI 管道入库。
10. 明细求和与汇总双轨对账：提供 audit 检查命令，自动比对腾讯文档【每日记录】单项累加与【每日汇总】当日数值，检测并一键消除历史数据漂移。
11. SkillHub 自身自动升级：提供 upgrade-skill 命令，自动检测 SkillHub 远端版本差异并驱动 CLI 完成就地覆盖升级，保持技能最新能力。

不能做：
1. 不能替代专业临床执业医师诊断或开具处方药物。
2. 不在没有用户明确指令下伪造血糖或称重数据。
3. 不向未授权的第三方外部服务上传个人健康隐私数据。
4. 严禁越权访问其他外部腾讯文档 — 信源严格且唯一限定于绑定的单一《每日饮食记录》工作簿，严禁遍历云端空间、跨文档检索或读取用户的任何其他私有文档。

触发条件

• 应当加载：
• 用户需要记录早餐、午餐、晚餐、下午茶、夜宵、饮品或独立运动。
• 用户提供食物名称、分量、包装营养成分表或外食描述，希望估算热量与营养。
• 用户发送餐饮照片、外卖包装照片、餐盘截图或询问“看看这顿吃了多少卡路里”。
• 用户首次使用需要初始化身体参数或调整每日目标预算。
• 用户提供餐后 1h/2h 血糖或运动时长，需要联动记录并评估波动风险。
• 用户要求同步、查询或对账腾讯文档中的《每日饮食记录》表格。
• 用户询问当前剩余预算、外食推荐、食物多样性达标情况或避雷店铺。
• 不应当加载：
• 纯粹的通用文档格式转换或 PPT 制作（交由 tencent-docs 或 html-ppt 处理）。
• 纯代码重构或通用工程架构设计（交由 project-architect 处理）。

前置条件

1. 环境与运行支持：
   - 本地拥有 Python 3.8+ 解释器（仅依赖标准库）。
2. 腾讯文档连接（可选，支持离线降级）：
   - 环境变量 TENCENT_DOCS_TOKEN 已配置，或本地 mcporter 已注册 tencent-docs 与 sheet-mcp。
   - 权限前置校验：会话首条记录前通过 manage.search_file 验证权威文档 file_id 有效性；若出现 10016 优先核对 ID 拼写，禁止死循环盲目重试。
   - 若未配置或处于离线环境，系统自动降级为本地缓存模式（local_cache），保证零中断运行。
3. SkillHub CLI 支持（可选，用于技能自升级）：
   - 本地系统已安装 skillhub CLI（如通过 Antigravity/AGY 安装在 AppData/Local/agy/bin/skillhub.cmd 或位于系统 PATH，或已存在 ~/.skillhub/skills_store_cli.py）。
   - 若未安装 skillhub，技能主体记录与同步功能不受影响，仅 upgrade-skill 命令提示外部依赖缺失。

核心工作流

[录入与解析] -> [营养核算与控糖评估] -> [本地持久化与腾讯文档同步] -> [看板呈现与下一步执行]

步骤 1：身体档案初始化（首次或重设）

• 单步引导追问协议 (Step-by-Step Guided Intake Protocol)：
• 交互式点击追问：当用户首次建档且未一次性提供完整参数时，必须优先调用交互式多选卡片（如 ask_question 组件）渲染可选列表供用户直接点击提交；严格执行一次只问一个问题，且首个选项必须为推荐项并带 (Recommended) 标记（对齐全局单步澄清与交互体验规约），免除手动打字负担。
• 标准追问序列：
  1. 性别（推荐：男 / 女）
  2. 出生年份/年月（推荐：YYYY/MM，如 1995/05，公历动态折算精确实岁并随公历月份自增；若仅提供 YYYY 年份则按年中 7 月 1 日折算，防年龄固化）
  3. 身高（推荐：厘米，如 175 cm）
  4. 当前体重（推荐：公斤，如 72 kg）
  5. 目标体重（推荐：公斤，如 65 kg）
  6. 日常活动水平（推荐：久坐办公 / 轻度活动 / 中度活动）
  7. 腾讯文档 ID（选填：用于云端双轨自动同步，无则暂存本地）
• 全量输入自适应：若用户在一句话中已包含完整或部分指标（如“男 1995年 174cm 72.2kg 目标65kg 久坐”），直接全量解析建档，不发起已明确字段的冗余追问。

[CHECKPOINT] [STOP] 档案预算变更核验：首次设定或重设身高、体重、目标预算前，展示计算结果与既有档案对比，获得确认后再写入 profile.json。

执行初始化命令，录入基础指标并绑定腾讯文档目标文件 ID：

python scripts/tdoc_sync.py profile --gender male --height 174 --weight 72 --target-weight 68 --birth-year 1995 --activity light --file-id YOUR_DOC_ID

• 计算并输出：BMI、BMR、TDEE、目标热量赤字及三大营养素克数。
• 绑定腾讯文档目标文件 ID。

步骤 2：记录日常饮食与运动

用户输入自然语言或包装食品条形码后，运行解析与双轨同步流水线：

# 方式 A：日常自然语言记录
python scripts/tdoc_sync.py record "午餐沙县卤鸡排饭吃1/3米饭 蔬菜80g 美式咖啡 冻干羽衣甘蓝粉3g 散步20分钟 1h血糖8.4"

# 方式 B：包装食品条形码扫码记录 (Open Food Facts 官方成分直连)
python scripts/tdoc_sync.py record "加餐 扫码 3017620422003 30g"

# 方式 C：条形码单品营养快速核验
python scripts/tdoc_sync.py lookup 3017620422003

# 方式 D：拍照识别视觉三阶解耦执行 (Vision Protocol)
python scripts/tdoc_sync.py record "午餐 掌心去皮鸡腿100g 拳头米饭150g 清炒菜心100g (过水涮油) 1h血糖6.8"

• 三级营养核算规约：
• Tier-1（条形码与词典直连）：优先通过 meal_parser.py 解析 8-14 位条形码（直连 Open Food Facts 官方成分表）或匹配内置高频食品库。
• Tier-2（Agent 启发式补全）：若脚本返回 0.0kcal 或明显低估，Agent 必须查阅 references/food_database.md 与生熟重系数，在自然语言末尾追加显式食材克数或热量参数（如补充“熟米饭100g 鸡腿肉80g”），杜绝 0 伪数据上云。
• Tier-3（生理阈值防护）：检测到血糖数据联动记录，触发控糖分析。
• 遵循快速通道协议（fast_record.md），在【每日记录】按时间严格降序（date DESC, time DESC）定位插入新行或原位覆盖更新（旧记录整体下移防误覆盖），并应用四步样式协议；同时实时更新【每日汇总】第 0-14 列。

[CHECKPOINT] [STOP] 危险生理指标拦截：餐后 1h/2h 血糖 > 11.1 mmol/L 或空腹 < 3.9 mmol/L 时，立即暂停常规输出，优先展示临床低血糖急救或高血糖就医提示，待用户确认安全后再同步记录。

步骤 2.1：拍照识别与视觉图像处理规约 (Vision Protocol)

当用户输入包含餐饮图片时，Agent 强制遵循以下视觉解耦流水线：

1. 信源优先级分流：
   - 包装食品：优先识别条形码（直连 Open Food Facts）或背面方框“营养成分表”（OCR 提取标称值）。
   - 散装菜品：启动三阶解耦推理，严禁端到端盲猜总卡路里。
2. 三阶解耦推理流水线：
   - 阶 1（食材分割清单）：分割识别所有可见独立单品（如主食、肉类、蔬菜、补剂）。
   - 阶 2（烹调吸油率判定）：查阅 references/food_database.md 第 5 节，确定附加烹调油与隐形糖（如白灼+0g、清炒+5g油、红烧+12g油+8g糖、裹粉油炸+25g油、红油火锅+35g油）。
   - 阶 3（生物标尺定标）：寻找画面中拳头（熟主食~150g）、掌心（肉类~100g生重）、双手捧（生绿叶菜~100g）、拇指（纯油酱~10g）或外卖餐盒直径（~16cm）推算各食材净重。
3. 单步前置追问模板：
   - 识别到肉类或高脂菜品时，沿决策树发起唯一 1 个单步追问：
   ```text
   为精准核算吸收热量，请确认烹调细节：
   1. (推荐) 偏瘦去皮 / 含骨剔骨 / 清汤轻度涮油 (按标准吸油率核算)
   2. 肥瘦相间带皮 / 纯肉无骨 / 未过水直接食用 (吸油率与脂肪浮动 +30%)
      ```
      - 用户未回复时默认采纳推荐项进行稳健估算。
4. 组装 CLI 管道驱动：
   - 将视觉解耦结果组装为标准食材与克数描述，交由底层确定性脚本执行记录，杜绝大模型数值幻觉。

步骤 3：查看当日剩余预算看板

python scripts/tdoc_sync.py summary

• 输出标准化高密度纯文本看板：已摄入 vs 目标配比、剩余额度、多样性达标（12/25 规则）、宝塔品类覆盖度与纤维状态。
• 若触发延迟升糖（2h >= 1h 且 2h >= 7.0），自动高亮预警并执行餐后散步及下餐低脂排油方案。

步骤 4：智能避雷点餐指引

python scripts/tdoc_sync.py recommend

• 根据当日剩余碳水/脂肪配比与《中国居民膳食指南》推荐红榜合规餐食。
• 遵循标准进食顺序流（蔬菜纤维 -> 优质蛋白 -> 复合慢碳）。
• 强制排除黑榜劣迹店铺。

步骤 5：登记与沉淀高频自学习食材

当用户有自制私房菜、固定减脂便当或未收录的特色饮品时，主动沉淀至本地动态词典：

python scripts/tdoc_sync.py learn-food --name "生椰拿铁" --cal 180 --pro 3.5 --carb 22 --fat 9 --unit-cup 1

• 数据持久化于 ~/.diet_tracker/custom_foods.json。
• 扫码识别（lookup）商品或成功推算成分的生鲜外食亦会自动累计频次并转存该库，实现越用越聪明的闭环体验。

步骤 6：数据对账与自动校准 (Audit Protocol)

定期核验云端明细求和与汇总行数据一致性：

# 检查是否存在数据漂移
python scripts/tdoc_sync.py audit

# 发现偏差时自动校准修复
python scripts/tdoc_sync.py audit --fix

CLI 命令全景速查矩阵

检查点规约 (Checkpoints)

为防止 Agent 自主失控与异常健康决策，必须在下列决策前执行显性拦截：

1. [CHECKPOINT] [STOP] 身体档案与预算覆写：调整身高、体重、目标赤字导致每日热量预算变动 > 100kcal 时，必须输出新旧方案参数对照，经用户确认后执行写入。
2. [CHECKPOINT] [STOP] 临床高危血糖警示：录入血糖读数超出正常波动范围（空腹 < 3.9 或餐后 > 11.1 mmol/L）时，禁止仅输出减脂方案，必须附带医疗警示并要求用户复测确认。
3. [CHECKPOINT] [STOP] 极端摄入偏差确认：单日记录总摄入低于基础代谢（< BMR 或 < 1000kcal），或单餐暴食超出当日预算 80% 时，必须拦截询问是否遗漏餐次或发生摄入偏离。
4. [CHECKPOINT] [STOP] 视觉大热量与重度油脂复核：单餐视觉估算热量 > 800kcal 或识别为红油重脂外食时，在写入云端前展示拆解出的食材与烹饪清单供用户快速核验，待确认后执行记录。

格式规约与排版铁律 (Format Constraints)

1. 腾讯文档单元格排版铁律：
   - 倒序插行与时间降序排版：新增与补记单餐明细强制遵循 date DESC, time DESC 倒序定位算法插入空行写入，按时间严格降序排列，杜绝行号计算覆盖。
   - 日期格式强约束：第一列日期字段强制统一使用 YYYY/MM/DD 字符串（如 2026/10/19），严禁直接写入裸 Excel 序列号。
   - 单元格标准排版协议：

   • 步骤 1：第 0-12 列整体居中，第 5-12 列强制数值格式 General。
   • 步骤 2：第 0 列显式设置日期代码 yyyy/m/d。
   • 步骤 3：第 4 列（食物）设置水平靠左垂直居中。
   • 步骤 4：第 13 列（备注）显式设置水平靠左垂直居中（防表头居中继承）。
   • 第 13 列备注高密度依据协议：
   • 精简严禁牺牲信息表达；完整保留全部食材组成、分量、生熟与可食部转换口径、吸油率及包装标称折算原值。
   • 严格剔除各单项重复的微量营养素加减公式与长篇对话说教（此类分析仅在看板呈现）。
   • 结构范式：[高风险] 估算值：估算依据: 食材1(生熟口径)+食材2(分量/吸油)+... 或 包装标称: 每100ml含...折算。
   • 用户自留区保护铁律：
   • 【每日汇总】子表更新仅覆盖第 0 至 14 列，严禁触碰、清除或覆写第 15 列（纤维状态）与第 16 列（备注）用户手工维护内容。

2. 交互看板输出规约：
   - 每次记录餐次、运动或汇总查询后，必须输出标准化纯文本看板：

   • 标题行：--- 饮食看板 [YYYY/MM/DD 星期X] ---
   • 核心指标：热量、净碳、蛋白（含 MPS 达标餐数）、脂肪、钠摄入、进食窗/运动。
   • 膳食指南指标：食物多样性（达标 $\ge 12$ 种）、平衡膳食宝塔品类覆盖度。
   • 预警与干预：若有高脂高糖标记、延迟升糖、高钠水肿、多样性不足或纤维缺口，必须附加对应干预标签。
   • 严禁随意输出非结构化口水话。

3. 技能发布纪律 (Publish Discipline & Human Gate)：
   - 技能包及相关代码、规约的任何修改 MUST 经过人工（用户）明确审查与确认后，方可执行发布（skillhub publish）。严禁任何未经人工确认的自主发布。

异常与故障恢复矩阵 (Fallback Matrix)

反例与黑名单

以下是本 skill 执行过程中严格禁止的行为：

1. 严禁硬编码明文凭据 — 严禁将任何 Token、Cookie 或密钥写入脚本或文档，统一走环境变量读取。
2. 严禁引入第三方联网依赖 — 脚本严禁 import 需额外 pip 安装的第三方包，确保开箱即用。
3. 严禁推荐黑榜劣迹店铺 — 严格执行避雷名单，严禁向用户推荐重油重盐料理包快餐、植脂末奶茶、幽灵外卖以及用户本地配置（~/.diet_tracker/blacklist.json）登记的劣迹商户。
4. 严禁忽略油脂延迟升糖 — 外食红油麻辣或米乳奶酪类食物必须主动预警，不得静默放过。
5. 严禁跨文档越权读取 — 无论用户个人云端空间存在多少文档，本技能信源必须且只能收敛在绑定的单一《每日饮食记录》工作簿，严禁读取任何其他私有文档或表格。
6. 严禁使用非权威/营销号伪信源 — 食品热量与三大营养素必须严格优先采信食品包装官方营养表、餐饮品牌官方热量计算器以及《中国食物成分表》(CDC)/USDA 权威机构数据库；严禁采信未经核实的营销博主随性拍脑袋数据。
7. 严禁将未核算 0 伪数据上云 — 遇到未知菜品严禁直接把热量 0kcal 写入腾讯文档与每日汇总，必须通过三级流水线拆解或标明待估算。
8. 严禁静默覆盖历史档案 — 严禁在未经用户明确确认的前提下修改或覆写既有身体代谢指标与减脂预算。
9. 严禁覆盖每日汇总用户自留列 — 同步程序严禁清空或重写【每日汇总】子表第 15 列（纤维状态）与第 16 列（备注）。
10. 严禁跳过食材分割直接输出总卡路里 — 视觉模型必须且只能输出“食材 + 烹调方式 + 粗估克数”，严禁直接端到端猜测单餐总卡路里。
11. 严禁在无标尺参照物时假定外卖容器为单人小份 — 遇到无肢体标尺的外卖盒或大盘，必须结合常见餐盒规格（直径15-18cm）进行保底中位数推算。
12. 严禁使用静态年龄导致代谢滞后 — 身体档案必须记录出生年份并基于当前执行日期动态计算实岁，严禁写死固定年龄导致跨年 BMR 停滞。
13. 严禁覆盖式写入腾讯文档 — 写入云端表格必须执行按时间降序（date DESC, time DESC）定位插行或原位幂等覆盖更新，严禁无序覆写导致历史记录丢失。

参考文档

契约自检

• [x] 目录名为小写 kebab-case (smart-diet-tracker)，且与上方 name 逐字符一致
• [x] displayName 统一定名为“中国营养膳食指南”
• [x] description 详尽写明能力边界与触发场景
• [x] 正文无平台专有路径（差异由统一中间层管理）
• [x] 脚本零第三方依赖、零网络动态下载
• [x] 无硬编码宿主机绝对路径、密钥、私有域名
• [x] 遵守零 Emoji 规范