YellowBeanie/marketbot
GitHub: YellowBeanie/marketbot
一个基于 Python 标准库构建的 Telegram 金融教学机器人，聚合多源市场与宏观数据生成每日教学简报和波动警报。
Stars: 0 | Forks: 0
# marketbot
**一个 Telegram OSINT + 金融机器人，将市场和宏观数据转化为两段消息的教学摘要 —— 仅供教育目的，非财务建议。**
[](LICENSE)
🇬🇧 **英文** 见下文 · 🇫🇷 [法文版](#français)
## 英文
marketbot 汇总市场和地缘政治数据，计算出跨市场解读，并在每个工作日多次发布
**两段消息的教学摘要**，以及 **波动警报**。它的构建初衷是
**教学**：它解释市场*为何*波动，展示每个数字背后的数学原理，并提供外部链接，让
非交易者也能学习这些概念。
### 功能特性
- **两段消息的摘要**
- **消息 1 —— 简报（事实）：** 报价、跨市场状态解读、来自经济日历的“关注列表”，
以及 **可点击的新闻源链接**。
- **消息 2 —— “深度解析”（洞察层）：** 计算出的带有置信区间的相关性/背离信号、针对上一个交易时段的偏差验证结论、带有教学链接的“今日词汇”表术语，以及 **连续的 FX 感知模拟交易**（5,000 CHF 的虚拟账户，自我评分）。*此消息受控于（`decrypt.enabled`），可以在后台静默运行，同时不断记录其账本数据。*
- **先计算后叙述：** 每个数字都在 Python（`stats.py`, `signals.py`, `verify.py`, `levels.py`, `sim.py`）中计算得出；LLM 仅负责叙述，并且 **来源防护机制会拒绝任何捏造的数字**。
- **警报：** 基于阈值的波动警报，采用按比例递增的重新触发机制（在再次发生波动前不会重复警报）。
- **可靠性：** 原子 cron 锁、摘要去重、新鲜度防护（当报价看起来冻结时发出警告），以及 **FX 感知 CHF 换算**，从而反映真实的货币波动。
- **100 % 标准库：** 无需任何 pip 依赖 —— 由 AST 导入防火墙（`tests/test_no_deps.py`）强制执行。SQLite 存储，一切由 `config.json` 驱动。
### 数据源与功能
marketbot 读取的每个外部数据源，供您逐一探索：
| 数据源 | 数据 | 链接 |
|--------|------|------|
| Yahoo Finance | 报价 + 价格历史（指数、板块、FX、加密货币、大宗商品、利率、VIX） | |
| GDELT | 经过滤的地缘政治事件流 | |
| alternative.me | 加密货币恐惧与贪婪指数 | |
| CFTC COT | 投机者净持仓（每周） | |
| Manifold Markets | 市场隐含的宏观/地缘概率 | |
| FRED (St. Louis Fed) | 宏观系列数据 + 经济日历 | |
| EIA | 美国石油/天然气库存（WTI/Brent 驱动因素） | |
| Telegram Bot API | 消息投递 | |
| Anthropic Claude | 摘要叙述（默认后端） | |
| Google Gemini | 备用叙述后端 | |
### 学习概念
词汇表将每个“今日词汇”链接到通俗易懂的英文解释：
[ATR](https://www.investopedia.com/terms/a/atr.asp) ·
[Beta](https://www.investopedia.com/terms/b/beta.asp) ·
[Contango](https://www.investopedia.com/terms/c/contango.asp) ·
[Correlation](https://www.investopedia.com/terms/c/correlation.asp) ·
[Credit spread](https://www.investopedia.com/terms/c/creditspread.asp) ·
[Percentile](https://www.investopedia.com/terms/p/percentile.asp) ·
[Yield curve](https://www.investopedia.com/terms/y/yieldcurve.asp)
### 架构
```
cron → run.sh {digest|alert} → cli.main (idempotency LOCK)
│
├─ build_snapshot ──(sources/*)──► _merge ──► derive.compute (intermarket read)
│ │ │
│ ▼ ▼
│ store.save_snapshot (SQLite) Snapshot (dataclasses)
│
├─ signals.detect / verify.reconcile ──► render/digest.py (message 1: briefing)
│ └──► render/decrypt.py (message 2: insight + simulation)
└─ alert : render/alert.py (thresholds + re-step) ──► telegram
```
每次运行都会获取市场快照，将其存储，计算跨市场解读和信号，渲染
Telegram 消息，并且（对于摘要）可以附加洞察/模拟消息。有关详细的架构和决策，请参阅
[`DESIGN.md`](DESIGN.md)。
**包结构**（`marketbot/`）：`cli.py`, `schema.py`, `store.py`, `http.py`, `derive.py`,
`stats.py`, `signals.py`, `verify.py`, `levels.py`, `sim.py`, `glossary.py`, `telegram.py`, `llm.py`,
`llm_claude.py`, `lock.py`, `breaker.py`, `config.py`; `render/` (`digest`, `decrypt`, `deterministic`,
`alert`, `common`); `sources/` (`yahoo`, `shadowbroker`, `news_rss`, `sentiment`, `coingecko`,
`cftc_cot`, `manifold`, `fred`, `fred_calendar`, `eia`)。
### 快速开始
```
git clone https://github.com/YellowBeanie/marketbot.git && cd marketbot
cp config.example.json config.json # then edit; config.json is gitignored
```
**配置** —— `config.json` 定义了 `instruments`（名称/Yahoo 代码/类型）、`sources.*.enabled`、
`thresholds`、`models`（摘要后端）、`telegram.markets_chat`（您的群组 ID）以及 `simulation`
配置块。
**密钥**（保存在代码仓库之外，在您的环境中导出）：
```
export TELEGRAM_BOT_TOKEN=... # market bot (digests/alerts)
export GEMINI_API_KEY=... # narration fallback
export FRED_KEY=... EIA_KEY=... # "full" sources
export CLAUDE_CODE_OAUTH_TOKEN=... # optional: durable Claude CLI auth for cron
```
无需安装任何依赖 —— marketbot 仅使用标准库。
### 用法 (CLI)
```
python3 run.py ingest # fetch sources -> snapshot -> SQLite (no send)
python3 run.py show # print the latest stored snapshot
python3 run.py digest # build + send the digest
python3 run.py alert # send an alert if the market moved notably
python3 run.py prune # weekly maintenance (bounds the DB + VACUUM)
```
Flags：`--no-send`（打印但不发布），`--no-lock`（忽略锁，用于手动运行）。在
生产环境中，一个 `run.sh` 包装脚本会加载密钥，然后调用 `run.py`。
### 测试
```
python3 -m unittest discover -s tests # stdlib suite, no network (LLM/sender mocked)
```
测试套件包含一个 **导入防火墙**（`tests/test_no_deps.py`），如果引入了任何非标准库导入，测试就会失败；还有一个 **泄露防护**（`tests/test_no_private_infra.py`），如果发布的文件中出现了私有基础设施信息，测试就会失败。
## 法文
marketbot agrège des données de marché et géopolitiques, en tire une **lecture intermarché**, et publie
un **digest pédagogique en deux messages** plusieurs fois par jour ouvré, plus des **alertes** de
mouvement. Il est conçu pour **expliquer** : *pourquoi* le marché a bougé, avec le calcul derrière chaque
chiffre et des liens pour que même un non-trader comprenne les concepts.
### 功能特性
- **Digest en deux messages**
- **Message 1 — le briefing (les faits) :** cotations, lecture de régime intermarché, liste « à
surveiller » issue du calendrier économique, et **liens cliquables** vers les sources d'actualité.
- **Message 2 — le « décryptage » (couche d'analyse) :** signaux de corrélation/divergence calculés
avec intervalles de confiance, verdict de **vérification du biais** de la séance précédente, « mot du
jour » avec lien pédagogique, et une **simulation de trade suivie, sensible au FX** (compte fictif
5 000 CHF, auto-notée). *Ce message est conditionné (`decrypt.enabled`) et peut tourner en dormance
pendant que son historique s'accumule.*
- **Calculer puis raconter :** chaque chiffre est calculé en Python (`stats.py`, `signals.py`,
`verify.py`, `levels.py`, `sim.py`) ; le LLM ne fait que raconter, et un **garde-fou de provenance
rejette tout nombre inventé**.
- **Alertes :** seuils par type d'instrument avec **re-step proportionnel** (pas de re-alerte tant que ça
n'a pas re-bougé).
- **Fiabilité :** verrou cron atomique, dédup des digests, garde-fou de fraîcheur (WARN si les cotations
semblent gelées), et **conversion CHF sensible au FX**.
- **100 % bibliothèque standard :** aucune dépendance pip — imposé par un pare-feu d'imports
(`tests/test_no_deps.py`). Stockage SQLite, tout piloté par `config.json`.
### Sources 与功能特性
Chaque source externe lue par marketbot, pour l'explorer :
| Source | Donnée | Lien |
|--------|--------|------|
| Yahoo Finance | cotations + historique (indices, secteurs, FX, crypto, matières, taux, VIX) | |
| GDELT | flux d'événements géopolitiques filtré | |
| alternative.me | indice Fear & Greed crypto | |
| CFTC COT | positionnement net des spéculateurs (hebdo) | |
| Manifold Markets | probabilités macro/géo implicites de marché | |
| FRED (Fed de St. Louis) | séries macro + calendrier économique | |
| EIA | stocks pétrole/gaz US (driver WTI/Brent) | |
| API Telegram Bot | envoi des messages | |
| Anthropic Claude | narration du digest (backend par défaut) | |
| Google Gemini | narration de secours | |
### 学习概念
Le glossaire relie chaque « mot du jour » à une explication claire :
[ATR](https://www.investopedia.com/terms/a/atr.asp) ·
[Bêta](https://www.investopedia.com/terms/b/beta.asp) ·
[Contango](https://www.investopedia.com/terms/c/contango.asp) ·
[Corrélation](https://www.investopedia.com/terms/c/correlation.asp) ·
[Spread de crédit](https://www.investopedia.com/terms/c/creditspread.asp) ·
[Percentile](https://www.investopedia.com/terms/p/percentile.asp) ·
[Courbe des taux](https://www.investopedia.com/terms/y/yieldcurve.asp)
### 架构
```
cron → run.sh {digest|alert} → cli.main (VERROU idempotence)
│
├─ build_snapshot ──(sources/*)──► _merge ──► derive.compute (lecture intermarché)
│ │ │
│ ▼ ▼
│ store.save_snapshot (SQLite) Snapshot (dataclasses)
│
├─ signals.detect / verify.reconcile ──► render/digest.py (message 1 : briefing)
│ └──► render/decrypt.py (message 2 : analyse + simulation)
└─ alert : render/alert.py (seuils + re-step) ──► telegram
```
Chaque exécution récupère un instantané, le stocke, calcule la lecture intermarché et les signaux, rend
le(s) message(s) Telegram, et (pour un digest) peut joindre le message d'analyse/simulation. Voir
[`DESIGN.md`](DESIGN.md) pour l'architecture détaillée et les décisions.
### 快速入门
```
git clone https://github.com/YellowBeanie/marketbot.git && cd marketbot
cp config.example.json config.json # puis éditer ; config.json est gitignored
```
**Secrets** (hors-repo, exportés dans l'environnement) : `TELEGRAM_BOT_TOKEN`, `GEMINI_API_KEY`,
`FRED_KEY`, `EIA_KEY`, et optionnellement `CLAUDE_CODE_OAUTH_TOKEN`. Aucune dépendance à installer —
marketbot est 100 % bibliothèque standard.
### 使用 (CLI)
```
python3 run.py ingest # récupère les sources -> snapshot -> SQLite (sans envoi)
python3 run.py show # affiche le dernier snapshot stocké
python3 run.py digest # construit + envoie le digest
python3 run.py alert # envoie une alerte si mouvement notable
python3 run.py prune # maintenance hebdo (borne la base + VACUUM)
```
Options : `--no-send` (affiche sans poster), `--no-lock` (ignore le verrou). En prod, `run.sh` charge les
secrets puis appelle `run.py`.
### 测试
```
python3 -m unittest discover -s tests # suite stdlib, sans réseau (LLM/sender mockés)
```
La suite inclut un **pare-feu d'imports** (`tests/test_no_deps.py`) et un **garde-fou anti-fuite**
(`tests/test_no_private_infra.py`).
### 贡献与许可
欢迎贡献 —— 请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)（安装、测试、stdlib-only 规则，以及 **DCO 签名**）。参与即表示您接受 [行为准则](CODE_OF_CONDUCT.md)。
请通过 [SECURITY.md](SECURITY.md) 私下报告安全问题。
基于 **AGPL-3.0** 许可 —— 详见 [LICENSE](LICENSE)。版权所有 (C) 2026 YellowBeanie。
*教育 / 教学 —— 非财务建议。*
标签：ESC4, OSINT, Python标准库, Telegram机器人, 宏观经济, 逆向工具, 量化交易, 金融数据分析