pp-exchangerate-api

ExchangeRate-API — Printing Press CLI

前提条件：安装 CLI

此 skill 通过 exchangerate-api-pp-cli 二进制文件运行。**在调用此 skill 中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install exchangerate-api --cli-only
   

2. 验证：exchangerate-api-pp-cli --version
3. 确保报告的安装目录位于将调用此 skill 的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/payments/exchangerate-api/cmd/exchangerate-api-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。在验证成功之前，请勿执行 skill 命令。

何时使用此 CLI

当 Agent 或脚本需要实时外汇汇率、多目标货币换算或持久化历史上下文时，请使用 exchangerate-api-pp-cli。如果 Agent 会对相同数据运行多次、配额很重要（免费层每月 1500 次），或者工作流需要依赖本地状态的关注列表、变动报告或交叉汇率矩阵，那么它比一次性 HTTP 调用更合适。将外汇上下文接入 Claude Desktop、Cursor 或 Windsurf 时，请使用 MCP 服务（mcp serve）。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此 CLI 仅提供用于检查、导出、同步和分析的只读命令。

独特功能

这些功能是此 API 的其他工具所不具备的。

可累积的本地状态

• history-cache — 根据之前的 latest 同步记录重建历史外汇汇率；免费层无需消耗 /history 配额即可回溯历史。

  当用户询问过去的汇率，且 API 密钥属于免费层或标准层（这两个层级调用 /history 会返回 plan-upgrade-required）时使用。

  exchangerate-api-pp-cli history-cache USD EUR --since 30d --json
  

• watch check — 为货币对设置变动阈值；一条命令即可报告自上次检查以来哪些货币对越过了阈值。

  可将其用作定期监控（cron/Agent 循环），代替轮询付费提醒服务。

  exchangerate-api-pp-cli watch check --json
  

• drift — 将最新快照与任意历史时点进行比较，并按排名报告波动最大的汇率。

  无需编写自定义分析，即可找出用户关心的异常外汇波动。

  exchangerate-api-pp-cli drift --base USD --since 24h --top 10 --json
  

• pair --as-of — 根据本地快照查询任意历史时间戳的汇率；免费层即可回溯历史。

  在不使用付费 /history 端点的情况下，重建特定时刻的实时汇率。

  exchangerate-api-pp-cli rates pair USD EUR --as-of 1h --json
  

配额分析

• quota burn — 根据 quota_snapshots 拟合趋势，并预测配额是否会在刷新日之前耗尽。

  在部署任何会大量调用 API 的内容之前使用；预测结果会告诉你能否撑过当月。

  exchangerate-api-pp-cli quota burn --json
  

• matrix — 通过一次 latest 调用，显示任意一组货币的完整交叉汇率矩阵：N² 个汇率，仅消耗 1 次配额。

  同时比较多个货币对时使用；可节省配额，并在同步一次后离线运行。

  exchangerate-api-pp-cli matrix USD,EUR,GBP,JPY --base USD --json
  

• convert-batch — 将金额列表传入一条命令；一次获取汇率即可完成全部金额的换算。

  处理大量金额（订单、交易）时使用，避免配额消耗随金额数量线性增长。

  exchangerate-api-pp-cli convert-batch --from USD --to EUR --input /dev/null --json
  

入门

• plan-check — 通过一次低成本请求探测每个受套餐限制的端点；报告你的密钥支持哪个层级。

  在运行 doctor 后立即使用，了解哪些命令可用，而不会遇到 plan-upgrade-required。

  exchangerate-api-pp-cli plan-check --json
  

Agent 原生基础设施

• log show — 每次 convert 调用都会记录日志；可按基准货币、目标货币和时间范围查询日志，以分析重复转换。

  用于提醒 Agent 最近执行过哪些外汇操作，无需再次查询 API。

  exchangerate-api-pp-cli log show --since 7d --json
  

• mcp serve — 每条面向用户的命令都会作为 MCP 工具公开，并为安全查询添加只读注解。

  用于将 Claude/Cursor/Windsurf 接入外汇上下文——目前没有其他 MCP 提供此 API。

  exchangerate-api-pp-cli mcp serve
  

命令参考

API 密钥从 EXCHANGERATE_API_KEY 读取——切勿将其作为位置参数传入。

codes — 支持的货币代码

• exchangerate-api-pp-cli codes — 列出全部 161 个受支持的货币代码

quota — API 配额用量

• exchangerate-api-pp-cli quota — 查看当前配额周期内的剩余请求数
• exchangerate-api-pp-cli quota burn — 根据 quota_snapshots 历史记录预测配额耗尽时间

rates — 实时汇率和货币转换

• exchangerate-api-pp-cli rates latest <base_code> — 获取基准货币的所有汇率
• exchangerate-api-pp-cli rates pair <base_code> <target_code> — 获取两种货币之间的转换汇率
• exchangerate-api-pp-cli rates pair-amount <base_code> <target_code> <amount> — 转换两种货币之间的指定金额
• exchangerate-api-pp-cli rates enriched <base_code> <target_code> — 提供包含地区设置、旗帜和货币显示元数据的货币对转换（Business/Volume 套餐）
• exchangerate-api-pp-cli rates history <base_code> <year> <month> <day> — 获取指定日期的历史汇率（Pro/Business/Volume 套餐）

查找合适的命令

知道要执行什么操作，但不知道该用哪个命令时，可直接询问 CLI：

exchangerate-api-pp-cli which "<capability in your own words>"

which 会根据此 CLI 精选的功能索引，将自然语言功能查询解析为最匹配的命令。退出代码 0 表示至少找到一项匹配；退出代码 2 表示没有可信的匹配结果——可改用 --help，或使用范围更窄的查询。

示例

在脚本中进行一次性转换

exchangerate-api-pp-cli convert 1000 USD EUR --json --select conversion_result

只返回转换后的数字，便于后续通过管道传递。

每日同步 + 波动报告（cron）

exchangerate-api-pp-cli sync-rates --base USD && exchangerate-api-pp-cli drift --base USD --since 24h --top 10 --json

记录今日汇率，并显示与上一份快照相比变动最大的货币。

部署前检查配额

exchangerate-api-pp-cli quota burn --json --select projected_exhaustion,requests_remaining

根据近期用量预测月度配额耗尽时间。

投资组合交叉汇率矩阵

exchangerate-api-pp-cli matrix USD,EUR,GBP,JPY,CHF,CAD --base USD --csv

一次 API 调用即可生成完整的 N×N 矩阵；可直接通过管道导入电子表格。

监控货币对并在汇率变动时发出提醒

exchangerate-api-pp-cli watch add USD EUR --threshold 1.0 && exchangerate-api-pp-cli watch check --json

设置阈值；后续调用 watch check 时，会标记越过阈值的货币对。

身份验证设置

从 ExchangeRate-API 控制面板（https://app.exchangerate-api.com/）设置 EXCHANGERATE_API_KEY。所有命令都会通过 https://v6.exchangerate-api.com/v6/{key}/... 发送请求。open 命令使用无需密钥的 https://open.er-api.com/v6/latest/{base} 端点；如果重新分发其输出，必须注明来源为 'Rates By Exchange Rate API'。

运行 exchangerate-api-pp-cli doctor 验证设置。

Agent 模式

为任意命令添加 --agent。该参数会展开为：--json --compact --no-input --no-color --yes。

• 便于管道处理 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 可保留部分字段。点分路径可深入嵌套结构；数组会逐个元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

  exchangerate-api-pp-cli codes --agent --select supported_codes
  

• 可预览 — --dry-run 会显示请求，但不会发送

• 支持离线使用 — 有本地 SQLite 存储时，同步/搜索命令可使用该存储

• 非交互式 — 不会提出提示，所有输入均通过标志传入

• 只读 — 不要使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、订购、发送或其他会修改数据的请求

响应封装

读取本地存储或 API 的命令会将输出封装在溯源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时来源还是本地来源。只有当 stdout 是终端且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要仅打印到 stderr；管道/Agent 消费者以及显式格式运行都会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现这个 CLI 有不妥之处时，请记录下来：

exchangerate-api-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
exchangerate-api-pp-cli feedback --stdin < notes.txt
exchangerate-api-pp-cli feedback list --json --limit 10

条目会存储在本地 ~/.exchangerate-api-pp-cli/feedback.jsonl。除非设置了 EXCHANGERATE_API_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 EXCHANGERATE_API_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认行为仅保存在本地。

写下让你感到意外的地方，而不是 bug 报告。简短、具体、一行即可：这才是日积月累的关键。

输出交付

每个命令都接受 --deliver <sink>。输出会发送到指定的 sink，同时输出到 stdout 或替代 stdout，这样 Agent 就能路由命令结果，而不必手动通过管道传递。支持三种 sink：

Sink	效果
stdout	默认；仅写入 stdout
file:<path>	原子地将输出写入 <path>（tmp + rename）
webhook:<url>	将输出正文 POST 到 URL（当使用 --compact 时，类型为 application/json 或 application/x-ndjson）

不支持的 scheme 会被拒绝，并返回列出支持项的结构化错误。Webhook 失败时会返回非零状态，并在 stderr 记录 URL 和 HTTP 状态。

命名配置

配置是已保存的一组标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，就可以使用它——这就是 HeyGen 的 “Beacon” 模式。

exchangerate-api-pp-cli profile save briefing --json
exchangerate-api-pp-cli --profile briefing codes
exchangerate-api-pp-cli profile list --json
exchangerate-api-pp-cli profile show briefing
exchangerate-api-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便具备自省能力的 Agent 在运行时发现它们。

退出代码

Code	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 exchangerate-api-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上方的先决条件
3. 其他任何内容 → 直接使用（将其作为带 --agent 的 CLI 命令执行）

MCP 服务安装

从此 CLI 发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册它：

claude mcp add exchangerate-api-pp-mcp -- exchangerate-api-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which exchangerate-api-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   exchangerate-api-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：exchangerate-api-pp-cli <command> --help。