StockLens 是一个 AI 驱动的股票分析系统，覆盖 A 股 / 港股 / 美股，端到端自动化完成「数据抓取 → 量化评分 → LLM 解读 → 多渠道推送 → 事后回测」全链路。
一句话定位：把"机构级量化研究"压缩成"个人也能跑"的开源系统。
| 痛点 | StockLens 做法 |
|---|---|
| 数据源单一，A/港/美 要装一堆 SDK | 10 个数据源统一 API 接入，按优先级 failover + 熔断 |
| 量化指标散落在各种 Excel / 脚本 | 18 个学术模型固化成代码，结果可复现、可回测 |
| AI 直接给买卖建议容易"胡说" | 评分由 Python 确定性计算，LLM 只负责"解读"已算好的分数 |
| 多平台推送要写 10 套代码 | 1 个 Notifier 接口，10 个渠道并行扇出 |
| 历史决策没法事后复盘 | 每次分析自动入库，T+N 自动回测打分 |
- 🌏 三市场全覆盖 — A 股 / 港股 / 美股行情、基本面、筹码、宏观统一接入
- 🧮 18 模型量化评分引擎 — Piotroski / Altman Z / Ohlson O / Rule of 40 / Magic Formula / Beneish M / DuPont / SCTR …，综合评分 0–100，确定性计算、LLM 不可篡改
- 🤖 多 Agent 协作决策 —
single（ReAct）/multi（编排器协调 技术 / 情报 / 风控 / 策略 / 决策 5 个 Agent），风控 Agent 可一票否决 - 📰 多源情报搜索 — 7 个搜索引擎 Provider 聚合新闻 / 机构观点 / 风险排查，3 维度并行
- 📊 11 套自然语言策略 — 均线金叉、放量突破、缠论、波浪、龙头、情绪周期…（YAML 可自定义）
- 🔌 10 渠道推送 — 微信企业 / 飞书 / Telegram / Email / Discord / Pushover / PushPlus / ServerChan3 / AstrBot / 自定义 Webhook
- 🖥️ Web UI 行情热力图 — Jinja2 + 原生 JS，零打包步骤，开箱即用
- ⚡ 流水线并行编排 — 数据增强与 LLM 调用拆为双线程池，
add_done_callback消除空闲等待 - 🗄️ SQLite 全速优化 — WAL / mmap 256MB / 64MB 页缓存 / 批量 upsert，单机即跑
┌─────────────────────────────────────────────────────────────┐
│ 接入层 (Access) │
│ Web UI (热力图) · REST API (FastAPI) · Bot (钉钉/飞书) │
├─────────────────────────────────────────────────────────────┤
│ 业务编排层 (stocklens) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ StockAnalysisPipeline (核心调度流水线) │ │
│ │ 共享预取 → 数据采集 → enrich+LLM 并行 → 推送 → 回测 │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────────┐ │
│ │ Agent 编排│ │ LLM 分析器│ │ 评分引擎 (18 模型, 0-100) │ │
│ │ 5 Agent │ │ Prompt 构建│ │ Piotroski/Altman/... │ │
│ └──────────┘ └──────────┘ └──────────────────────────┘ │
├──────────────┬──────────────┬──────────────┬────────────────┤
│ quantcore │ tickbridge │ querybus │ pulsefan │
│ (纯算法) │ (数据源) │ (搜索) │ (推送) │
│ 18 评分模型 │ 10 Fetcher │ 7 Provider │ 10 渠道扇出 │
│ 零 IO 零依赖 │ failover+熔断│ 2 级缓存 │ 单一 Notifier │
├──────────────┴──────────────┴──────────────┴────────────────┤
│ 4 个核心包互不引用 (单向依赖 stocklens) · kvcache 缓存 │
├─────────────────────────────────────────────────────────────┤
│ SQLite + SQLAlchemy ORM · WAL/mmap · 9 Repository │
└─────────────────────────────────────────────────────────────┘
五个独立可发布的核心包（
quantcore/tickbridge/querybus/pulsefan/kvcache）各自零回边依赖，可单独抽离复用。
触发 → Phase 1 共享预取(指数/宏观/新闻)
→ Phase 2 数据采集(10 Fetcher failover → SQLite upsert)
→ Phase 3 enrich + LLM 双线程池并行
├─ enrich: 实时行情 / 筹码 / 基本面 / 趋势指标 / 情报搜索 / 18 模型评分
└─ LLM: PromptBuilder → LiteLLM Router → JSON 解析 → 入库
→ Phase 4 汇总报告 → 10 渠道并行推送
→ Phase 5 自动回测(T+N 事后评估, 可选)
评分由 Python 确定性计算，LLM 不可修改，只负责解读。综合评分满分 100：
| 维度 | 权重 | 模型 |
|---|---|---|
| 宏观 + 市场状态 | 25 | 宏观周期 / 市场状态 |
| 基本面 | 20 | Piotroski F-Score / Altman Z / Ohlson O / Beneish M / 盈余质量 / DuPont |
| 估值 | 20 | PEG / Rule of 40 / Magic Formula / 派息安全 |
| 技术 + 动量 | 15 | SCTR / 动量 / 盈利惊喜 |
| 困境反转 | 10 | Ohlson O / 困境指标 |
| 情绪 | 10 | 机构持股 / 期权情绪 / 做空 / 社交情绪 |
| 层 | 选型 |
|---|---|
| 语言 | Python 3.9+ |
| Web | FastAPI + Uvicorn（uvloop 加速） |
| 数据库 | SQLite + SQLAlchemy ORM（WAL / mmap / 64MB cache） |
| 缓存 | 进程内 TTL（L1）+ SQLite 持久化（L2，thread-local） |
| LLM 路由 | LiteLLM Router（OpenAI / Anthropic / Gemini / DeepSeek 多通道 + fallback） |
| 高性能 | orjson · msgspec · polars · zstandard · rapidfuzz |
| 可靠性 | tenacity 重试 · pybreaker 熔断 · slowapi 限流 |
| 测试 | pytest（246+ 用例）· ruff · pre-commit |
| 前端 | Jinja2 模板 + 原生 JS（无 SPA，零打包） |
| 部署 | python main.py 一键启动 · Docker Compose |
git clone https://github.com/W-M-R/StockLens.git
cd StockLens
cp .env.example .env编辑 .env，至少填两项：
# 自选股（A 股 / 港股 / 美股混填）
STOCK_LIST=AAPL,NVDA,600519,hk00700
# 任选一种 LLM
LLM_CHANNELS=deepseek
LLM_DEEPSEEK_BASE_URL=https://api.deepseek.com
LLM_DEEPSEEK_API_KEY=sk-xxx
LLM_DEEPSEEK_MODELS=deepseek-chat
LITELLM_MODEL=openai/deepseek-chatpip install -e ".[all]" # 安装依赖（含数据源/搜索/bot/extras/dev）
python main.py # 启动 Web 服务
# 浏览器打开 http://localhost:8000 （API 文档 /docs）docker compose up -d --build
docker compose logs -f stocklensCompose 启动两个服务：
tickbridge（行情数据守护进程，唯一写库）+stocklens（API + 热力图 UI，经 HTTP 读数据）。
StockLens 通过 .env 配置一切（详见 .env.example）。最常用的几类：
| 类别 | 关键变量 | 说明 |
|---|---|---|
| 自选股 | STOCK_LIST |
逗号分隔，支持 A/港/美 |
| LLM | LLM_CHANNELS / LITELLM_MODEL |
多通道 + 主/备模型 |
| 数据源优先级 | YFINANCE_PRIORITY 等 |
数字越小优先级越高 |
| 数据源 Token | TUSHARE_TOKEN / TWELVEDATA_API_KEY |
按需开启 |
| 搜索引擎 | TAVILY_API_KEYS / BRAVE_API_KEYS 等 |
任选配置 |
| 推送渠道 | WECHAT_WEBHOOK_URL / TELEGRAM_BOT_TOKEN 等 |
按需开启 |
| Agent 模式 | AGENT_MODE / AGENT_ARCH |
single(ReAct) / multi(编排器) |
| 报告 | REPORT_TYPE / REPORT_SUMMARY_ONLY |
simple / full / brief |
| Web 认证 | ADMIN_AUTH_ENABLED / ADMIN_PASSWORD |
可选 |
StockLens/
├── main.py # Web 服务入口 (FastAPI + 可选 Bot Stream)
├── api/ # REST API 层 (FastAPI 路由 / 中间件 / 认证)
├── bot/ # Bot 适配层 (钉钉 / 飞书 Stream)
├── stocklens/ # 业务编排层
│ ├── pipeline/ # 核心分析流水线
│ ├── agent/ # 多 Agent 编排 + 工具
│ ├── analyzer/ # LLM 分析器 + Prompt 构建
│ ├── services/ # 评分/任务队列/配置/历史等服务
│ ├── search/ # 股票情报搜索服务
│ ├── notification/ # 报告编排 + 推送适配
│ ├── portfolio/ # 组合管理
│ ├── backtest/ # 事后回测
│ ├── storage/ # SQLite ORM + Repository
│ ├── contracts/ # 跨层共享数据类
│ └── config/ # 配置 + 环境校验
├── strategies/ # 11 套自然语言策略 (YAML, 可自定义)
├── templates/ # 报告 Jinja2 模板
├── web/ # 热力图 Web UI (Jinja2 + 原生 JS)
├── alembic/ # 数据库迁移
├── tests/ # pytest 测试
├── docs/ # 架构 / 数据流 / 模块文档 / ADR
├── docker-compose.yml
└── pyproject.toml
完整文档位于 docs/，按任务查阅，无需扫描源码：
- 架构总览 — 分层架构 + 10 项关键设计决策
- 数据流 — 完整分析流水线 + 20 张表说明
- 策略指南 — 11 套策略用法
- 评分验证 — IC / 胜率 / 共线性
- 数据源能力矩阵 — 各 Fetcher 覆盖范围
- ADR 架构决策 — 不可逆设计决策记录
pip install -e ".[all]"
pre-commit install # 安装 git hooks (ruff + 文件大小守卫)
pytest tests/ -q # 全量测试
pytest tests/ --cov --cov-report=term-missing # 覆盖率
python scripts/check_file_size.py # 文件大小检查工程纪律（CI 强制）：
- 所有源码注释 / docstring / 日志 / 字符串字面量必须英文（开源面向全球）
- 改代码必须同提交更新对应文档（Code → Doc 同步）
- ORM 变更必须同提交 Alembic 迁移
- 单文件硬上限 1500 行，新增模块 >800 行需说明
- 每个 commit 以
Changelog: <摘要>结尾
详见 CLAUDE.md。
- 更多数据源接入（Finnhub / Polygon / Tiingo）
- 策略回测自动加权 (
AGENT_STRATEGY_AUTOWEIGHT) - 事件驱动实时告警 (
AGENT_EVENT_MONITOR_ENABLED) - 更多 K 线形态识别
- 组合层面风险归因
MIT © 2024-2026 W-M-R
⭐ 觉得有用就点个 Star 吧 · PR / Issue 欢迎贡献