Fatsecret

核心功能

FatSecret Skill 提供与 FatSecret 官方营养数据库的完整集成，涵盖两大核心场景：只读数据查询（OAuth2）和完整日记功能（OAuth1）。

主要能力包括：

• 食物搜索与营养查询：通过自然语言搜索数百万种食物，获取卡路里、宏量营养素及微量营养素详情
• 条码扫描：支持商品条码直接查询，快速获取包装食品营养信息
• 食谱检索：搜索健康食谱及其详细营养构成
• 饮食日记记录：OAuth1 授权后可向用户 FatSecret 账户添加餐食记录

技术实现特点

该 Skill 采用双认证架构设计，灵活适配不同场景：

• OAuth2（客户端凭证）：无需用户登录，适合纯查询场景，支持食物搜索、条码查找、食谱检索
• OAuth1（三-legged）：需一次性用户授权（PIN码），授予完整日记读写权限

显著优点

1. 数据源权威：直接对接 FatSecret 官方数据库，营养数据覆盖全球食品，更新及时
2. 双模式灵活：根据需求选择免登录查询或完整日记功能，避免过度授权
3. 本地化凭证管理：支持自定义配置目录（FATSECRET_CONFIG_DIR），适配容器化部署
4. 备选数据源：内置 Open Food Facts 客户端，欧洲产品可免认证查询
5. 完善的 CLI 工具：提供 Bash 封装脚本，降低使用门槛

潜在局限与风险

• 认证复杂度：OAuth1 流程需用户手动访问授权页面、输入 PIN，对自动化场景不够友好
• 单位参数易混淆：grams_or_ml 参数为实际数值而非倍数，文档特别强调易出错（如输入 1.56 而非 156 会导致严重记录偏差）
• OAuth1 令牌持久性：令牌长期有效，若泄露需手动撤销，存在一定安全隐患
• IP 限制：部分 FatSecret 套餐需 IP 白名单，可能需配置 SOCKS5 代理

适合人群

• 健身用户、营养师需精确追踪饮食摄入
• 健康类应用开发者需集成权威食品数据库
• 个人用户希望自动化记录餐食至现有 FatSecret 账户

常规风险提示

凭证默认存储于本地 ~/.config/fatsecret/，容器环境需显式配置持久化路径；OAuth1 授权后 Skill 获得用户日记完整读写权限，建议在可信环境使用，卸载时同步删除本地配置并撤销应用授权。

核心用法

FatSecret Skill 是一个专业的营养数据集成工具，通过官方API提供完整的饮食管理功能。用户可通过OAuth2实现免登录的食物搜索、条形码扫描和食谱查询；或通过OAuth1完成一次性授权，解锁饮食日记记录功能。

主要使用场景包括：快速查询食物热量与营养成分（蛋白质、碳水、脂肪、微量元素）、扫描商品条形码获取包装食品信息、搜索健康食谱、以及将每日饮食记录同步至FatSecret个人账户。CLI工具与Agent Helper函数双重支持，既适合命令行用户快速操作，也方便开发者集成至自动化工作流。

显著优点

数据权威性：直接对接FatSecret官方数据库，涵盖数百万种食品与餐厅菜单的营养信息，数据由专业团队维护更新。

双模式认证：OAuth2免登录满足纯查询需求，OAuth1三-legged授权支持完整日记功能，灵活适应不同使用场景。

本地化安全：所有敏感凭证（Consumer Key/Secret、Access Token）均存储于用户本地目录（~/.config/fatsecret/），不上传至第三方服务器，符合隐私保护最佳实践。

扩展兼容：内置Open Food Facts备用接口，针对欧洲市场商品提供免费替代方案，无需额外认证。

容器友好：支持FATSECRET_CONFIG_DIR环境变量自定义配置路径，完美适配Docker与OpenClaw沙盒等容器化部署环境。

潜在缺点与局限性

认证复杂度：OAuth1流程需用户手动访问授权URL、登录账户、获取PIN码并回填，对非技术用户存在学习成本。

地理数据覆盖：FatSecret数据库以北美市场为主，亚洲及欧洲部分地区商品覆盖度有限，需依赖Open Food Facts补充。

速率限制：免费API层级存在调用频率限制，高频批量查询可能触发限流。

令牌持久性：OAuth1令牌长期有效（直至手动撤销），虽便利但增加泄露后的风险敞口。

代理依赖：部分网络环境需配置SOCKS5代理（FATSECRET_PROXY）才能稳定访问，增加部署复杂度。

适合的目标群体

健康管理用户：需要追踪每日热量摄入、监控宏量营养素比例的健身人群与减重用户。

医疗营养场景：营养师、糖尿病或肾病患者的饮食规划辅助工具。

食品开发者：需快速查询竞品营养数据、验证配方成分的食品行业从业者。

自动化工作流：希望将饮食记录集成至个人知识库或健康数据仪表板的效率工具用户。

使用风险

凭证管理风险：Consumer Key/Secret需用户自行保管，泄露可能导致API配额被盗用；建议定期轮换并避免硬编码于共享代码库。

网络稳定性：依赖FatSecret服务器可用性，服务中断时将影响功能；建议关键场景配置Open Food Facts作为降级方案。

数据准确性：第三方食品数据可能存在录入误差，特殊饮食需求（如过敏原、宗教饮食）需人工二次核实。

权限范围：OAuth1授权后Skill获得日记读写权限，用户应在FatSecret账户设置中定期审查授权应用列表，及时撤销不再使用的集成。

容器持久化：Docker环境默认配置目录非持久化，重启后需重新授权；生产部署务必挂载卷至FATSECRET_CONFIG_DIR指定路径。