cognis-digital/ratewatch

# ratewatch — 宏观与利率 CLI [](https://pypi.org/project/cognis-ratewatch/) [](https://github.com/cognis-digital/ratewatch/actions) [](LICENSE) [](https://github.com/cognis-digital) **宏观与利率 CLI：从公开数据源获取联邦基金利率、CPI、国债收益率以及关键经济日历日期。** `ratewatch` 仅拉取**公开数据** —— 美国财政部每日平价收益率曲线（公开 XML，无需密钥）以及圣路易斯联邦储备银行 **FRED** 时间序列 API（通过 `FRED_API_KEY` 环境变量提供免费密钥，可选）。在没有密钥或使用 `--offline` 的情况下，它会优雅降级到内置的样本数据，因此始终能产生输出。仅使用标准库 —— 无需 pip 依赖。 ## 使用说明 — 逐步指南 1. 从源码**安装**（Python 3.9+）： pip install . 2. **显示**美国国债平价收益率曲线（实时，或使用 `--offline` 获取内置数据）： ratewatch yields --format table 3. **获取** FRED 时间序列（例如联邦基金利率、CPI）： ratewatch series FEDFUNDS --limit 24 --format json 4. **查看**内置日历中即将到来的 FOMC / CPI / NFP 日期： ratewatch calendar --format json 5. **自动化** —— 为仪表板或 CI artifact 编写报告文件： ratewatch yields --format html --out yields.html 此外：`ratewatch mcp`（作为 MCP stdio server 运行）。 ## 领域 **主要领域：** 网络与安全 · **JTF MERIDIAN 部门：** NULLBYTE · SPECTER **主题：** `cognis` `security` `infosec` `cybersecurity` `blue-team` `cli` **Cognis Neural Suite** 的一部分 —— 包含 300 多个源码可用工具，在 JTF MERIDIAN 命令结构下跨越 12 个领域进行组织。请参阅 [GitHub 上的套件](https://github.com/cognis-digital)和 [jtf-meridian](https://github.com/cognis-digital/jtf-meridian) 以了解各部分如何组合。 ## 安装 ``` pip install cognis-ratewatch # 或者，来自此 repo： pip install -e ".[dev]" ``` ## 快速开始 ``` ratewatch --version ratewatch yields --offline # Treasury par-yield curve (bundled sample) ratewatch yields # live Treasury curve (public, no key) ratewatch series FEDFUNDS --offline # Fed funds effective rate ratewatch series CPIAUCSL # CPI (live if FRED_API_KEY set, else sample) ratewatch series DGS10 --offline # 10-Year Treasury (preset) ratewatch calendar # upcoming FOMC / CPI / NFP dates ratewatch calendar --category FOMC --limit 3 ratewatch yields --format json # machine-readable ratewatch series DGS10 --format html --out dgs10.html # styled HTML report ratewatch mcp # expose as an MCP server ``` ### 已知的 FRED 预设序列 这些 ID 带有友好的标签，并随附内置的离线样本数据 （可在 `--offline` 且无密钥的情况下使用）： | 序列 ID | 标签 | |------------|-------| | `FEDFUNDS` | 联邦基金有效利率 | | `CPIAUCSL` | 消费者价格指数 (所有城市消费者, 所有项目) | | `DGS2` | 2年期国债恒定到期收益率 | | `DGS10` | 10年期国债恒定到期收益率 | | `T10Y2Y` | 10年期减2年期国债利差 | | `UNRATE` | 失业率 | | `PCEPILFE` | 核心PCE价格指数 (不含食品和能源) | 任何其他有效的 FRED 序列 ID 同样适用（使用 `FRED_API_KEY` 实时获取）。 ### FRED API 密钥 (可选) `series` 子命令在存在时会使用一个**免费**的 FRED 密钥： ``` export FRED_API_KEY=your_free_key_here # get one at https://fred.stlouisfed.org ratewatch series FEDFUNDS ``` 任何地方都没有提交密钥 —— 它仅从环境中读取。如果没有密钥，`series` 会返回内置的样本数据，并在 `source` 字段中说明。 ## 子命令 | 命令 | 数据源 | 密钥 | |------------|-----------------------------------------------------|-----| | `yields` | 美国财政部每日平价收益率曲线 (公开 XML) | 无 | | `series` | FRED 时间序列 (例如 `FEDFUNDS`, `CPIAUCSL`) | 免费的 `FRED_API_KEY` (可选) | | `calendar` | 内置的 FOMC / CPI / NFP / GDP / PCE 日期 (JSON) | 无 | `--format table` (默认)、`--format json` 或 `--format html`；`--out FILE` 写入磁盘；`--offline` 强制使用内置数据。 ## 离线演示 ``` python -m ratewatch yields --offline bash demos/01-basic/run.sh # full offline walkthrough ``` 请参阅 [`demos/01-basic/SCENARIO.md`](demos/01-basic/SCENARIO.md)。 ## 输出格式 - **表格** (默认) — 易于阅读的终端摘要，包括 2s10s 利差。 - **JSON** — 适用于 pipeline 和 agent 的机器可读格式。 - **HTML** — 一个独立的、带有样式的报告（内联 CSS，无 JS/网络），适用于 `yields`、`series` 和 `calendar`；最新的观测值会被高亮显示。可与 `--out report.html` 搭配使用。 ## 基础构建 / 数据源 - [美国财政部 — 每日国债平价收益率曲线利率](https://home.treasury.gov/resource-center/data-chart-center/interest-rates) — 公开 XML。 - [FRED — 圣路易斯联邦储备银行](https://fred.stlouisfed.org) — 免费 API 密钥。 - [BLS](https://www.bls.gov)、[BEA](https://www.bea.gov)、[联邦储备系统](https://www.federalreserve.gov) — 发布日历。 遗漏了致谢？欢迎提交 PR。 ## 如何融入 Cognis Neural Suite `ratewatch` 是 [Cognis Neural Suite](https://github.com/cognis-digital) 中的一个工具。每个工具都提供了一个 MCP server，因此 [Cognis.Studio](https://cognis.studio) 的 agent 可以将其作为范围内的能力进行调用： ``` {"command": "python", "args": ["-m", "ratewatch", "mcp"]} ``` ## 架构与路线图 - 设计说明：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) ## 互操作性 `ratewatch` 可与包含 300 多个工具的 Cognis 套件组合 —— JSON 输入/输出以及共享的 OpenAI 兼容 `/v1` 主干。请参阅 **[INTEROP.md](INTEROP.md)** 了解套件映射、组合模式和参考技术栈。 ## 集成 通过 [`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `ratewatch` 的发现转发到 STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks。 请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。 ## 许可证 源码可用，基于 **Cognis Open Collaboration License (COCL) v1.0** —— 个人、内部评估、研究和教育用途免费；**商业/生产用途需要许可证** (licensing@cognis.digital)。请参阅 [LICENSE](LICENSE)。 ## 负责任的使用 `ratewatch` 报告公开的宏观经济数据，仅供参考。它**不是投资建议**。在依赖这些数据之前，请务必与官方来源进行核对。 ## 关于 **[Cognis Digital](https://cognis.digital)** — 美国怀俄明州 · *让明天更美好：高级网络安全、AI 创新与区块链专业知识。*

标签：Python, URL抓取, 宏观经济, 数据抓取, 文档结构分析, 无后门, 逆向工具, 金融数据