内容
# 铁锈弗雷德
[](https://github.com/ojhermann-org/ferric-fred/actions/workflows/ci.yml)
[](#license)
[](https://glama.ai/mcp/servers/ojhermann-org/ferric-fred)
一个为 [FRED](https://fred.stlouisfed.org/)（圣路易斯联邦储备银行的联邦储备经济数据服务）构建的强类型化 Rust 客户端，以及在此基础上构建的命令行界面（带有 TUI 图表）和 MCP 服务器。
> `ferric`（铁氧化物 → *rust*）+ `FRED`。铁锈般坚固、类型安全的经济数据访问。
## 工作空间
一个包含三个 crates 的 Cargo 工作空间 — 每个都有自己的 README（crates.io / docs.rs 着陆页），详细介绍了使用方法：
| Crate | 二进制文件 | 描述 | 详情 |
|-------|------------|------------|---------|
| `ferric-fred` | — | 强类型化的异步 FRED 客户端 | [README](crates/ferric-fred/README.md) · [docs.rs](https://docs.rs/ferric-fred) |
| `ferric-fred-cli` | `fred` | 命令行工具，带有 `ratatui` TUI 图表 | [README](crates/ferric-fred-cli/README.md) |
| `ferric-fred-mcp` | `fred-mcp` | MCP 服务器，暴露 FRED 数据给 MCP 客户端 | [README](crates/ferric-fred-mcp/README.md) |
已发布版本（这些徽章是真实性的来源 — crate 版本独立管理，因此它们可能会不同步）：
[](https://crates.io/crates/ferric-fred)
[](https://crates.io/crates/ferric-fred-cli)
[](https://crates.io/crates/ferric-fred-mcp)
消费者依赖库的路径，因此库中的重大更改无法在不更新消费者的情况下编译通过 — 这种编译时耦合是主要的“保持同步”保证（版本在上面管理；参见 ADR）。
## 功能覆盖
库封装了 **所有 FRED 读取端点** — 系列和观察（包括 ALFRED 按时间点 / 老旧数据，通过实时窗口）、搜索、类别、发布（包括嵌套的发布表树，可选的内联观察值）、来源和标签 — 以及 **GeoFRED / 地图 API**（区域数据和地理形状文件，用于映射，[ADR-0025](docs/adr/0025-geofred-maps-api.md)）— 在符合人体工程学的构建器后面，带有新类型标识符、FRED 封闭值集的键控枚举、非恐慌错误分类和 **自动分页**（`Paginate::send_all`遍历端点到穷尽，`Paginate::stream` 惰性生成；CLI 上为 `--all`）。参见 [ADR-0020](docs/adr/0020-auto-pagination.md) 和 [ADR-0021](docs/adr/0021-streaming-pagination.md)。
GeoFRED 支持涵盖 **库**、**CLI**（`fred geofred`）和 **MCP**（`get_regional_data`、`get_series_data`、`get_series_group`）层。唯一的例外是地理 `shapes/file` 端点，它仅限于库/CLI — 大型的投射-GeoJSON 块对于 MCP 工具调用者来说是糟糕的体验 ([ADR-0025](docs/adr/0025-geofred-maps-api.md))。
选择一个入口点：
- **库** — `cargo add ferric-fred`；从您自己的代码中进行类型安全的异步访问。参见 [crate README](crates/ferric-fred/README.md) 和 [docs.rs](https://docs.rs/ferric-fred)。
- **CLI** (`fred`) — `cargo install ferric-fred-cli`；搜索、显示元数据、打印或 **绘制** 终端中的观察结果、浏览类别、发布、来源和标签，并拉取 **GeoFRED** 区域数据和地图形状 (`fred geofred`)。参见 [crate README](crates/ferric-fred-cli/README.md) 或 `fred <command> --help`。
- **MCP 服务器** (`fred-mcp`) — `cargo install ferric-fred-mcp`；**34 种工具**通过 stdio 覆盖相同的读取表面，适用于具有 MCP 功能的客户端 ([ADR-0010](docs/adr/0010-mcp-server-design.md))。每个工具都声明输入和输出模式以及行为注释 ([ADR-0023](docs/adr/0023-mcp-output-schemas.md))。参见 [crate README](crates/ferric-fred-mcp/README.md)。
MCP 服务器在 [Glama](https://glama.ai/mcp/servers/ojhermann-org/ferric-fred) 上列出并评分：
[](https://glama.ai/mcp/servers/ojhermann-org/ferric-fred)
## 开发
Nix flake 提供了一个可复制的工具链 (`nix develop` 或 `direnv allow` 一次)，但该项目也使用普通的 Rust 工具链构建 — Nix 提供环境，而不是构建 ([ADR-0008](docs/adr/0008-nix-flake-dev-environment.md))。
贡献者设置、fmt/clippy/test **门控**、跟踪的 git 钩子和添加端点的流程都位于 **[CONTRIBUTING.md](CONTRIBUTING.md)** 中。CI（`ci.yml`）在每次推送和 PR 上运行相同的离线门控；一个休眠的 `live.yml` 在配置了 Infisical 机器标识后运行实时 FRED 测试 ([ADR-0016](docs/adr/0016-ci-live-tests-machine-identity.md))。
### 基准测试
来自组织技术雷达试点 ([ADR-0026](docs/adr/0026-perf-tooling-pilot.md)，问题 #42) 的性能工具：
```sh
# 反序列化微基准（divan）— 观察结果解析热路径。
cargo bench -p ferric-fred --bench deserialization
# 在 criterion 下执行相同的工作量（divan-vs-criterion 基线）。
cargo bench -p ferric-fred --bench deserialization_criterion
# 无头 `fred chart` 渲染成本（divan + ratatui TestBackend，无 tty）。
cargo bench -p ferric-fred-cli --bench render
# CLI 墙上时钟计时（hyperfine）：启动 + 实时获取和渲染。
# 基准测试需要 FRED_API_KEY；启动运行离线。
scripts/bench-cli.sh # 添加 --json DIR 以导出 hyperfine JSON
```
CI 在每个 PR 上保持基准测试编译（`cargo bench --no-run`），一个单独的 `bench.yml` 将结果上传到 [Bencher](https://bencher.dev)（托管项目 `ferric-fred`）以跟踪它们并在 PR 上标记回归。Bencher 没有 divan 适配器，因此它会消耗 *criterion* 镜像 (`rust_criterion`) 和 *hyperfine* 启动 (`shell_hyperfine`)；divan 保留为快速本地工具。`BENCHER_API_TOKEN` 来自 Infisical，因此上传在机器标识配置之前是一个 no-op — 参见 [ADR-0026](docs/adr/0026-perf-tooling-pilot.md)。
## 机密
客户端从 `FRED_API_KEY` 环境变量中读取一个免费的 **FRED API 密钥**（在 <https://fredaccount.stlouisfed.org/apikeys> 获取）。在本地，机密通过 [Infisical](https://infisical.com) + direnv ([ADR-0009](docs/adr/0009-secret-management-infisical-direnv.md)) 注入：
```sh
cp .envrc.example .envrc # 本地、git-ignored 入口点
infisical login # 用户身份验证（打开浏览器）
infisical init # 链接此目录 → 项目
direnv allow # 加载 shell + 在 cd-in 时注入机密
```
使用 `infisical secrets set FRED_API_KEY="…" --env=dev --path=/shared` 存储密钥。如果没有 Infisical？只需直接在 git-ignored `.envrc` 中设置：`export FRED_API_KEY="…"` — 库只读取环境变量，没有 Infisical 依赖。
## 架构决策
设计决策记录为 [`docs/adr/`](docs/adr/) 中的 ADR。从 [索引](docs/adr/README.md) 开始。
## 许可证
在 **MIT OR Apache-2.0** 下双重许可，根据您的选择 — Rust 生态系统的默认 ([ADR-0006](docs/adr/0006-license.md))。参见 [`LICENSE-MIT`](LICENSE-MIT) 和 [`LICENSE-APACHE`](LICENSE-APACHE)。除非您另有说明，否则您提交的任何贡献都根据相同的双重条款许可（参见 [`CONTRIBUTING.md`](CONTRIBUTING.md))。
这涵盖 *我们的代码*；FRED 数据本身受圣路易斯联邦储备银行的使用条款约束，您提供自己的 API 密钥 — 项目不提供数据和密钥。
