FatSecret 营养数据 API

与 FatSecret 完全集成，支持食物数据查询和饮食日记记录。

⚠️ 认证方式

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

方式	使用场景	需要用户登录	功能
OAuth2 (客户端凭证)	只读访问	❌ 否	食物搜索、条形码查询、食谱
OAuth1 (三方授权)

完整访问 | ✅ 是（一次性 PIN 码） | 以上所有功能 + 饮食日记记录 |

如何选择？

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

🚀 快速开始

1. 获取 API 凭证

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

2. 保存凭证

bash mkdir -p ~/.config/fatsecret cat > ~/.config/fatsecret/config.json << EOF { consumer_key: 你的消费者密钥, consumer_secret: 你的消费者密钥密码 } EOF

3. 安装依赖

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

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

bash

立即可以搜索

./scripts/fatsecret-cli.sh search 鸡胸肉

4b. 饮食日记记录（OAuth1）- 一次性用户授权

bash

运行认证流程

./scripts/fatsecret-cli.sh auth

按照提示操作：

1. 访问授权 URL

2. 使用 FatSecret 账号登录

3. 授权应用

4. 输入显示的 PIN 码

现在可以记录食物了

./scripts/fatsecret-cli.sh quick 鸡蛋 3 早餐

📋 CLI 命令

命令	需要认证	描述
search <查询词>	OAuth2	搜索食物
barcode <条码>

OAuth2 | 条形码查询 | | recipes <查询词> | OAuth2 | 搜索食谱 | | auth | - | 运行 OAuth1 认证 | | log | OAuth1 | 添加食物到饮食日记（交互式） | | quick <食物> [数量] [餐次] | OAuth1 | 快速记录到饮食日记 |

🤖 智能体集成

适用于 OpenClaw 智能体

python
from scripts.fatsecretagenthelper import (
getauthenticationflow,
completeauthenticationflow,
saveusercredentials
)

检查认证状态

state = getauthenticationflow()

if state[status] == need_credentials:
# 向用户请求 Consumer Key/Secret
# 使用 saveusercredentials(key, secret) 保存
pass

elif state[status] == need_authorization:
# 向用户显示授权 URL
url = state[authorization_url]
# 用户访问 URL，授权，获取 PIN 码
# 使用 completeauthenticationflow(pin) 完成
pass

elif state[status] == already_authenticated:
# 准备使用饮食日记功能
from scripts.fatsecretdiarysimple import quick_log
quick_log(鸡蛋, quantity=3, meal=早餐)

智能体辅助函数

函数	描述
getauthenticationflow()	检查状态，返回下一步操作
saveusercredentials(key, secret)

保存 API 凭证 | | completeauthenticationflow(pin) | 使用 PIN 码完成 OAuth1 认证 | | quick_log(food, qty, meal) | 记录食物到饮食日记 | | logfood(foodid, servingid, gramsor_ml, meal, name) | 精确记录 | | search_food(query, tokens) | 搜索食物 |

⚠️ 重要提示：gramsorml 的使用方法

gramsorml 参数（在 FatSecret API 中称为 numberofunits）是实际数量，而不是倍数！

python

❌ 错误 - 这只会记录 1.56 克（7 千卡）！

logfood(foodid, serving100gid, 1.56, 早餐, 饼干)

✅ 正确 - 这会记录 156 克（741 千卡）

logfood(foodid, serving100gid, 156, 早餐, 饼干)

示例：

你想要的数量	份量类型	gramsorml 值
156 克饼干	100克 份量	156
200 毫升牛奶

100毫升 份量 | 200 |
| 3 个鸡蛋 | 1个大鸡蛋 份量 | 3 |
| 2 片面包 | 1片 份量 | 2 |

🔐 凭证存储

所有凭证和令牌都存储在本地：

文件	内容	创建方式
$CONFIGDIR/config.json	Consumer Key/Secret	用户（手动）
$CONFIGDIR/oauth1accesstokens.json

OAuth1 访问令牌 | auth 命令 |
| $CONFIG_DIR/token.json | OAuth2 令牌（自动刷新） | OAuth2 客户端 |

其中 $CONFIGDIR 默认为 ~/.config/fatsecret，如果设置了 FATSECRETCONFIG_DIR 环境变量则使用该值。

要撤销访问权限： 删除配置文件夹，并在你的 FatSecret 账号设置中撤销应用访问权限。

🐳 容器/Docker 环境

在容器化环境（Docker、OpenClaw 沙箱）中，~/.config/ 可能在重启后不会持久保存。使用 FATSECRETCONFIGDIR 指向持久化卷：

bash

将环境变量设置为持久化目录

export FATSECRETCONFIGDIR=/home/node/clawd/config/fatsecret

或者在命令前添加前缀

FATSECRETCONFIGDIR=/persistent/path ./scripts/fatsecret-cli.sh auth

OpenClaw 示例 - 添加到你的 shell 初始化文件或 AGENTS.md：
bash
export FATSECRETCONFIGDIR=/home/node/clawd/config/fatsecret

🌐 代理配置（可选）

某些 FatSecret API 套餐需要 IP 白名单。如果需要，设置代理：

bash

环境变量

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（无需认证）：

python
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 三方认证
│ ├── fatsecretagenthelper.py # 智能体辅助函数
│ ├── fatsecretdiarysimple.py # 饮食日记记录（OAuth1）
│ ├── fatsecret_client.py # OAuth2 客户端（只读）
│ └── openfoodfacts_client.py # Open Food Facts 客户端
└── examples/
└── agentusageexample.py # 智能体集成示例

⚠️ 安全说明

1. 1. 凭证存储在本地 ~/.config/fatsecret/ 目录中