FatSecret 营养 API

与 FatSecret 完整集成，支持食物数据查询及日记记录功能。

⚠️ 认证方式

本技能支持两种认证方式，适用于不同使用场景：

如何选择？

• 仅需搜索食物？ → 使用 OAuth2（更简单，无需用户登录）
• 需向用户日记中记录食物？ → 使用 OAuth1（需用户授权）

🚀 快速开始

1. 获取 API 凭据

1. 访问 https://platform.fatsecret.com
2. 注册一个应用
3. 复制你的 Consumer Key 和 Consumer Secret

2. 保存凭据

mkdir -p ~/.config/fatsecret
cat > ~/.config/fatsecret/config.json << EOF
{
  "consumer_key": "YOUR_CONSUMER_KEY",
  "consumer_secret": "YOUR_CONSUMER_SECRET"
}
EOF

3. 安装依赖

cd /path/to/fatsecret-skill
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4a. 只读模式（OAuth2）——无需用户登录

# 搜索功能立即可用
./scripts/fatsecret-cli.sh search "chicken breast"

4b. 日记记录模式（OAuth1）——一次性用户授权

# 运行认证流程
./scripts/fatsecret-cli.sh auth

# 按提示操作：
# 1. 访问授权 URL
# 2. 使用 FatSecret 账户登录
# 3. 授权该应用
# 4. 输入显示的 PIN 码

# 此后即可记录食物
./scripts/fatsecret-cli.sh quick egg 3 Breakfast

📋 CLI 命令

🤖 Agent 集成

适用于 OpenClaw Agents

from scripts.fatsecret_agent_helper import (
    get_authentication_flow,
    complete_authentication_flow,
    save_user_credentials
)

# 检查认证状态
state = get_authentication_flow()

if state["status"] == "need_credentials":
    # 提示用户输入 Consumer Key / Secret
    # 使用 save_user_credentials(key, secret) 保存
    pass

elif state["status"] == "need_authorization":
    # 向用户展示授权 URL
    url = state["authorization_url"]
    # 用户访问该 URL，完成授权并获取 PIN
    # 使用 complete_authentication_flow(pin) 完成认证
    pass

elif state["status"] == "already_authenticated":
    # 可直接调用日记相关功能
    from scripts.fatsecret_diary_simple import quick_log
    quick_log("egg", quantity=3, meal="Breakfast")

Agent 辅助函数

⚠️ 重要提示：grams_or_ml 参数说明

grams_or_ml 参数（FatSecret API 中称为 number_of_units）表示实际重量或体积值，而非倍数！

# ❌ 错误 —— 此处仅记录了 1.56 克（7 kcal）！
log_food(food_id, serving_100g_id, 1.56, "Breakfast", "Cookies")

# ✅ 正确 —— 此处记录了 156 克（741 kcal）
log_food(food_id, serving_100g_id, 156, "Breakfast", "Cookies")

示例：

🔐 凭据存储

所有凭据和令牌均本地存储：

其中 $CONFIG_DIR 默认为 ~/.config/fatsecret；若设置了环境变量 FATSECRET_CONFIG_DIR，则以该值为准。

撤销访问权限方法： 删除配置目录，并在 FatSecret 账户设置中撤销该应用的访问权限。

🐳 容器 / Docker 环境

在容器化环境（Docker、OpenClaw sandbox）中，~/.config/ 目录可能无法在重启后持久保留。请使用 FATSECRET_CONFIG_DIR 指向一个持久化卷：

# 设置环境变量指向持久化目录
export FATSECRET_CONFIG_DIR="/home/node/clawd/config/fatsecret"

# 或在命令前加前缀
FATSECRET_CONFIG_DIR="/persistent/path" ./scripts/fatsecret-cli.sh auth

OpenClaw 示例 —— 添加到 shell 初始化脚本或 AGENTS.md 中：

export FATSECRET_CONFIG_DIR="/home/node/clawd/config/fatsecret"

🌐 代理配置（可选）

部分 FatSecret API 套餐要求 IP 白名单。如需使用代理，请配置如下：

# 环境变量方式
export FATSECRET_PROXY="socks5://127.0.0.1:1080"

# 或在 config.json 中配置
{
  "consumer_key": "...",
  "consumer_secret": "...",
  "proxy": "socks5://127.0.0.1:1080"
}

若无需代理： 本技能可在无代理情况下正常运行。仅当 FatSecret 封禁了你的 IP 时才需要配置代理。

🌍 Open Food Facts（替代方案）

针对欧洲地区商品，可使用免费的 Open Food Facts API（无需认证）：

from scripts.openfoodfacts_client import OpenFoodFactsClient

off = OpenFoodFactsClient(country="it")
products = off.search("barilla")
product = off.get_product("8076800105735")  # 条形码

📁 文件结构

fatsecret/
├── SKILL.md                      # 本文档
├── README.md                     # GitHub / ClawHub 项目说明
├── requirements.txt              # Python 依赖：requests、requests[socks]
├── scripts/
│   ├── fatsecret-cli.sh          # 主 CLI 脚本（bash 包装器）
│   ├── fatsecret_auth.py         # OAuth1 三段式认证
│   ├── fatsecret_agent_helper.py # Agent 辅助函数
│   ├── fatsecret_diary_simple.py # 日记记录（OAuth1）
│   ├── fatsecret_client.py       # OAuth2 客户端（只读）
│   └── openfoodfacts_client.py   # Open Food Facts 客户端
└── examples/
    └── agent_usage_example.py    # Agent 集成示例

⚠️ 安全说明

1. 凭据本地存储于 ~/.config/fatsecret/ 目录中
2. OAuth1 令牌不会过期，除非你主动撤销
3. OAuth1 授予对 FatSecret 日记的完整访问权限（读 + 写）
4. 安全卸载方式： 删除 ~/.config/fatsecret/ 并在 FatSecret 账户设置中撤销该应用权限

🔗 参考资料

• FatSecret API 文档：https://platform.fatsecret.com/docs
• OAuth1 指南：https://platform.fatsecret.com/docs/guides/authentication/oauth1/three-legged
• Open Food Facts API：https://wiki.openfoodfacts.org/API

更新日志

v1.0.1（2026-02-20）

• 修复 OAuth2 客户端 —— 当前统一使用 OAuth1 处理全部操作（包括食物搜索与日记记录）
• 统一认证流程：单一 OAuth1 流程同时支持读取与写入操作
• 移除已失效的 OAuth2 实现