boya357 Frankfurter Data Skill
通过 data-provider 网关访问 Frankfurter 汇率 API。所有调用走 python3 scripts/cli_wrapper.py（内部转发到 scripts/frankfurter-cli），agent 不需要知道 HTTP 细节。
为什么用 Python wrapper？ coze claw 仅在 Python 执行上下文注入托管密钥（
DATA_PROVIDER_API_KEY），直接运行 Go 二进制读不到。wrapper 桥接 env 注入。
何时使用
- 用户查询某种货币对的最新汇率（如"美元兑人民币多少"）
- 用户查询历史某天的汇率（如"去年1月1号的欧元汇率"）
- 用户需要一段时间的汇率走势（时间序列）
- 用户想知道支持哪些货币或数据来源
- 用户需要做货币换算（先查汇率，再计算）
何时不使用
- 需要实时秒级汇率推送（Frankfurter 数据为日频更新）
- 需要加密货币（BTC/ETH 等）汇率 — 仅覆盖法定货币
- 需要银行买入/卖出价 — 仅提供央行参考汇率
快速开始
# 列出所有可用 operation
python3 scripts/cli_wrapper.py list
# 查看某个 op 的入参 schema
python3 scripts/cli_wrapper.py schema rates
# 查最新汇率（默认基准 EUR）
python3 scripts/cli_wrapper.py call rates --param base=USD --param quotes=CNY,EUR,JPY
# 查某天的单一货币对汇率
python3 scripts/cli_wrapper.py call rate --param base=USD --param quote=CNY --param date=2026-01-15
# 查时间序列
python3 scripts/cli_wrapper.py call rates --param base=USD --param quotes=CNY --param from=2026-04-01 --param to=2026-05-01
# 列出所有可用货币
python3 scripts/cli_wrapper.py call currencies
# 查看数据源
python3 scripts/cli_wrapper.py call providers
本地联调时也可以直接运行
./scripts/frankfurter-cli list，但 coze claw 部署必须走python3 scripts/cli_wrapper.py。
环境变量
| 变量 | 必填 | 默认 | 说明 |
|---|---|---|---|
DATA_PROVIDER_API_KEY |
是 | — | data-provider 颁发的 dp_xxx key |
COZE_DATA_GATEWAY_URL |
否 | https://data.coze.cn |
网关域名 |
COZE_DATA_PROVIDER |
否 | frankfurter |
网关 provider 名（联调改 frankfurter-test） |
COZE_DATA_TIMEOUT_SEC |
否 | 30 |
单次调用超时 |
COZE_DATA_X_USE_PPE |
否 | — | 联调泳道开关，设 1 启用 |
COZE_DATA_X_TT_ENV |
否 | — | 联调泳道名 |
凭证不接受命令行参数。
Operations
| Operation | 用途 | 详情 |
|---|---|---|
rates |
查询汇率（最新/历史/时间序列），支持多目标货币 | references/rates.md |
rate |
查询单个货币对汇率 | references/rate.md |
currencies |
列出所有可用货币及数据源覆盖 | references/currencies.md |
currency |
查询单个货币详情 | references/currency.md |
providers |
列出所有汇率数据源（央行） | references/providers.md |
典型查询流程
查询美元兑人民币最新汇率
python3 scripts/cli_wrapper.py call rate --param base=USD --param quote=CNY
查询欧元兑多种货币最新汇率
python3 scripts/cli_wrapper.py call rates --param base=EUR --param quotes=USD,CNY,JPY,GBP
查询某天的历史汇率
python3 scripts/cli_wrapper.py call rates --param base=USD --param quotes=CNY --param date=2025-12-31
查询时间序列（按月降采样）
python3 scripts/cli_wrapper.py call rates --param base=USD --param quotes=CNY --param from=2025-01-01 --param to=2025-12-31 --param group=month
货币换算
Frankfurter 不提供直接换算接口，需要先查汇率再计算：
# 1. 查 USD→CNY 汇率
python3 scripts/cli_wrapper.py call rate --param base=USD --param quote=CNY
# 返回 {"base":"USD","quote":"CNY","date":"2026-05-13","rate":7.24}
# 2. 计算：100 USD = 100 × 7.24 = 724 CNY
Exit Code
| code | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 客户端用法错误（未知子命令 / 缺参 / 格式错） |
| 2 | 鉴权失败（env 缺失或上游 401/403） |
| 3 | 上游业务错误（4xx）— 如货币代码不存在（404）、参数无效（400/422） |
| 4 | 上游服务错误（5xx） |
| 5 | 网络 / 超时 / 协议错 |
错误处理范式
output=$(python3 scripts/cli_wrapper.py call rate --param base=USD --param quote=CNY 2>err.log)
case $? in
0) echo "$output" | jq . ;;
2) echo "鉴权失败，检查 DATA_PROVIDER_API_KEY"; cat err.log ;;
3) echo "上游业务错误（货币不存在/参数无效）"; cat err.log ;;
4) echo "上游服务错误"; cat err.log ;;
5) echo "网络异常，建议重试"; cat err.log ;;
*) echo "用法错"; cat err.log ;;
esac
已知限制
- 汇率为日频更新（央行参考汇率），非实时行情
- 不含加密货币
- 默认基准货币为 EUR，查其他基准需指定
base参数 - 历史数据最早可追溯到 1948 年（取决于数据源）
- 不提供银行买卖价差，仅央行中间价
不要做
- 不要试图绕过 CLI 直接 curl 网关：CLI 处理了鉴权 header 和 exit code 映射
- 不要把 vendor 原始 token 写到任何配置：vendor secret 由网关注入
- 不要修改
scripts/frankfurter-cli的源码（源码在tools/frankfurter-cli/） - 不要修改
scripts/cli_wrapper.py：该脚本是 coze claw env 注入的唯一桥接入口 - 不要在 coze claw 部署时直接运行
./scripts/frankfurter-cli，必须走python3 scripts/cli_wrapper.py
资源索引
- 脚本:见 scripts/cli_wrapper.py(用途:Python wrapper，桥接环境变量注入)
- 脚本:见 scripts/frankfurter-cli(用途:Go CLI二进制，汇率API客户端)
- 参考:见 references/rates.md(用途:汇率查询参数与返回格式)
- 参考:见 references/rate.md(用途:单货币对汇率查询)
- 参考:见 references/currencies.md(用途:货币列表查询)
- 参考:见 references/currency.md(用途:单个货币详情)
- 参考:见 references/providers.md(用途:数据源列表查询)