卡路里查询（Spoonacular + USDA）

使用 / Usage

• - 入口函数 / Entry functions：scripts/core.py 中的 lookupmeal(text, mealtype) / lookup_food(name, qty, unit)
• 结果为 JSON / Returns JSON：items + totals + questions（最多 2 个追问 / up to 2 follow-up questions）

配置 / Configuration

• - 环境变量 / Env var：SPOONACULARAPIKEY（主数据源）/ USDAFDCAPIKEY（后备）/ SPOONACULARAPIKEY (primary) or USDAFDCAPIKEY (fallback)
• 缓存 / Cache：CALORIESKILLCACHE_DB（默认本地 sqlite / defaults to local sqlite）

结构说明 / Module Structure

• - scripts/core.py：主逻辑（Spoonacular 主路由 + USDA 后备）/ Main logic (Spoonacular primary routing + USDA fallback)
• scripts/spoonacular.py：Spoonacular API 封装 / Spoonacular API wrapper
• scripts/translate.py：中英食物名字典（加速缓存，非主翻译路径）/ CN→EN dictionary (acceleration cache, not the primary translation path)
• scripts/usda_fdc.py：USDA API 封装 + 错误处理 / USDA API wrapper + error handling
• scripts/parser.py：文本解析 / Text parsing
• scripts/units.py：默认换算表（常改）/ Unit conversion & portion defaults
• scripts/cache.py：SQLite 缓存 / SQLite cache
• scripts/cooking.py：烹饪热量修正系数（USDA 数据源）/ Cooking calorie modifiers (USDA source)

行为约束 / Behavior Constraints

• - 缺单位或无法换算：返回 questions 提示补充 / Missing unit or unconvertible: returns questions prompting user
• 401/403/429/5xx：返回明确错误信息（适合直接在 Discord 显示）/ Returns clear error messages (suitable for Discord display)

工作流（含 Sub-agent 翻译 + 分解）/ Workflow (with Sub-agent Translation + Decomposition)

• - sub-agent 描述位于本 skill 的 agents/ 目录 / Sub-agent contracts are in agents/
• agents/calorie-lookup-image-recognizer.md：图像识别 Sub-agent 合约 / Image Recognizer Sub-agent contract
• 非英语输入 → 触发 Decomposer Sub-agent（LLM 翻译 + 分解）/ Non-English input → triggers Decomposer Sub-agent (LLM translation + decomposition)
• 复合菜/套餐/模糊描述 → 触发 Decomposer Sub-agent / Composite dishes / set meals / ambiguous descriptions → triggers Decomposer
• 纯英语简单食材 → 直接调用 lookupmeal / Plain English simple ingredients → calls lookupmeal directly
• 见 / See WORKFLOW.md 与 / and HOOKS.md
• 分解后逐条调用 lookupfood（英文 name），再汇总 totals / After decomposition, calls lookupfood per item (English name), then aggregates totals
• scripts/translate.py 字典仅作为 Python 层的加速缓存，不替代 LLM 翻译 / The dictionary is only an acceleration cache, not a replacement for LLM translation
• 仍缺关键量化 → 追问最多 2 条 / Still missing key quantity data → up to 2 follow-up questions

路径规范 / Path Convention

• - 本 skill 内所有引用均使用相对路径 / All references within this skill use relative paths（例如 / e.g. scripts/core.py、agents/、references/usda_fdc.md）