MediWise · 饮食追踪 Skill

概述

提供每餐饮食记录、食物条目管理、每日/每周营养摘要、热量趋势分析等功能。与 mediwise-health-tracker 共享数据库，可与 weight-manager 联动形成"饮食 → 热量 → 体重"完整闭环。

本 Skill 只记录和展示饮食数据、数据来源、用户目标差异与记录完整度，不提供营养治疗或饮食指导。内置参考区间只用于客观对比，不据此推荐用户增加、减少或替换食物。

数据模型

diet_records（一餐记录）

diet_items（食物条目）

营养字段的三态语义（饮食数据完整性的基础，读取方必须按此解释）：

NULL 与 0 不可互换：把未知当成 0 会在下游凭空造出「热量收支」。因此按日汇总时，只要当天任一餐的某字段为 NULL，该字段当天的总计就是未知（混合餐次会同时给出已知部分的合计，但不得对外报成完整值），未解析的日期不进入任何平均值分母，只作为「未解析天数」单独报告。逐字段判断，不要只看热量——否则一个未解析的 fat 会被当成 0 系统性拉低三大营养素比例。

功能列表

diet.py — 饮食记录 CRUD

nutrition.py — 营养分析

food_lookup.py — 食物营养查询

数据来源（按优先级）：

1. CFCD6 / cn-brands 本地数据包（可选）：仓库不捆绑这些数据；只有在确认来源授权后，将兼容格式的数据安装到 diet-tracker/data/ 才会启用
2. USDA FoodData Central（在线）：需配置 USDA_API_KEY 环境变量
3. Open Food Facts（在线，包装/品牌食品）：免 Key，但需显式设置 OPENFOODFACTS_ENABLED=1；数据采用 ODbL 1.0，结果会返回产品页和许可证。正式使用应按官方文档填写 API usage form、设置可联系的 User-Agent，并避免搜索即输入等高频调用

food-stats 会返回每个数据源的可用状态、来源网址、许可证和本地数据目录。所有在线来源都可用 MEDIWISE_FOOD_ONLINE_ENABLED=0 强制关闭。远程 API 只收到食物查询词及语言/分页参数，不得发送 owner_id、member_id、餐次记录或健康数据。没有任何来源可用时，查询返回 status: unavailable，不得把“数据源不可用”当成“该食物不存在”。

同一区分在写入路径上逐条透出：add-meal / add-item 的 unresolved_items[].reason 为 unavailable（没有可用数据源）或 not_found（数据源可用但没有这个食物），reason_text 是原始中文说明，action_required 给出对应的追问措辞。两种情形的用户可见说法不同，不得混用。

使用流程

记录一餐的标准流程（不得跳步）：

1. 确认成员身份（通过 mediwise-health-tracker 的 list-members）
2. 逐一查询每种食物的营养数据（food-lookup search，见下方"强制规则"）
3. 用查询到的营养数据调用 add-meal，通过 --items JSON 一次录入多个食物
4. 如需追加食物，使用 add-item 向已有餐次添加
5. 使用 daily-summary 查看当天营养摄入
6. 使用 weekly-summary 或 calorie-trend 查看长期趋势

营养数据强制规则

禁止用 AI 自身知识直接估算营养数值写入数据库。 记录每种食物之前，必须先调用 food-lookup search 查询，用数据库返回的数据填充 --items。

自动填充说明：若 --items 中某条目未提供热量数据，diet.py 会尝试调用本地 food_lookup 数据包补全营养值，并在 note 字段标注 [自动填充] 及数据来源。仓库默认不捆绑本地数据包；数据源不可用时必须请用户补充营养标签或显式配置在线来源，不能凭模型知识写入估算值。

add-meal / add-item 的写入响应契约

餐次照常保存，但营养值不会被编造。 补全失败时营养字段存 NULL（不是 0），并在条目 note 前加 [未解析营养] 标记；note 是给人看的，NULL 是给程序看的。

响应始终包含：

nutrition_status 非 resolved 时必须照 action_required 向用户追问（索取包装营养标签，或说明数据源未配置并提供启用路径），不得把它当成一次普通的成功记录一带而过，更不得用模型知识补一个数值。

补录路径（没有 update-item，条目不可原地修改）：用户给出标签后，用 delete --type item 删掉那条未解析条目，再用 add-item 按标签数值重新加入同一食物。每次条目增删都会重算餐次总计，未解析条目一旦消失，记录级 total_* 即自行恢复为已知值，无需手工修 diet_records。

# 步骤 1：先查每种食物
python3 {baseDir}/scripts/food_lookup.py search --query "炸排骨"
python3 {baseDir}/scripts/food_lookup.py search --query "米饭"

# 步骤 2：用查询结果里的营养数据填 --items，再记录
python3 {baseDir}/scripts/diet.py add-meal \
  --member-id <id> --meal-type lunch --meal-date 2025-03-15 \
  --items '[{"food_name":"炸排骨","amount":150,"unit":"g","calories":298,"protein":21.2,"fat":19.3,"carbs":9.1,"note":"来源:CFCD6"}]'

查询未命中时的处理：

• 结构化来源（本地数据包 → USDA → Open Food Facts）都未找到时，如运行环境具备网页检索能力，只能查询品牌官网、政府/高校数据库或可核验的官方营养标签页，并在 note 保留页面 URL、每 100g/每份基准和访问日期。不得采用博客、营销软文、搜索摘要或模型记忆中的数值。
• 仍无可核验来源时，告知用户“未查到该食物的营养数据”，询问用户是否按包装标签手动输入，或跳过该条目，不得自行估算后直接写入。
• 查到多个候选项时，展示给用户确认，选择最贴近的后再录入。
• 记录时在 note 字段写明数据来源（如"来源：CFCD6"、"来源：用户手动输入"）。

items JSON 格式

--items 参数接受 JSON 数组。所有营养字段必须来自 food-lookup search 的查询结果，不得由 AI 自行估算填充：

[
  {"food_name": "鸡胸脯肉", "amount": 150, "unit": "g", "calories": 158, "protein": 31.6, "fat": 3.2, "carbs": 0.0, "note": "来源:CFCD6"},
  {"food_name": "米饭", "amount": 200, "unit": "g", "calories": 232, "protein": 4.6, "fat": 0.6, "carbs": 51.5, "note": "来源:CFCD6"}
]

自动换算规则：CFCD6/USDA/Open Food Facts 数据按 amount（克）换算；中国品牌/外食本地数据按每份直接使用。使用 Open Food Facts 时应向用户提示其为社区维护数据，并优先核对具体条码对应的产品页。

注意事项

• 当前公开版本只用于个人本地档案；身份隔离由安装时的个人模式和 action 适配层处理，不向普通用户暴露或索取 owner_id。
• 禁止 AI 估算营养数据：所有热量/蛋白质/脂肪/碳水/膳食纤维数值必须来自 food-lookup search，或经用户明确确认的手动输入，不得由 AI 凭自身知识估算后直接写入。
• note 字段必须记录数据来源，便于用户事后核查。
• meal_type 支持: breakfast（早餐）、lunch（午餐）、dinner（晚餐）、snack（加餐/零食）