┌─────────────────────────────────────────────────────────────┐
│ 接入层 (Access) │
│ CLI (main.py) · Bot (钉钉/飞书 Stream) · REST API (FastAPI) │
├─────────────────────────────────────────────────────────────┤
│ API 层 (api/) │
│ FastAPI 路由 · 可选认证 · 错误处理中间件 · 依赖注入 │
│ 端点: analysis · agent · history · portfolio · backtest │
│ stocks · system_config · auth · usage │
│ 双 executor: long_pool (LLM/Agent) + io_pool (轻 IO) │
├─────────────────────────────────────────────────────────────┤
│ 契约层 (Contracts) │
│ stocklens/contracts/ — 核心层 ⇄ 适配层共享数据类 │
│ BotMessage / ChatType ; bot/ 与 api/ 反向引用此处 │
├─────────────────────────────────────────────────────────────┤
│ 业务编排层 (Orchestration) │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ StockAnalysisPipeline (核心调度，流水线) │ │
│ │ Phase 1 共享数据预取 → Phase 2 数据预采集 │ │
│ │ Phase 3 enrich 池 + LLM 池 并行运行 │ │
│ │ → 报告保存 → 10 渠道推送 → [可选] 自动回测 │ │
│ └───────────────────────────────────────────────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌───────────────────────┐ │
│ │ Agent 编排器 │ │ LLM 分析器 │ │ 评分引擎 (18 模型) │ │
│ │ 5 Agent 协作 │ │ Prompt 构建 │ │ Piotroski/Altman/... │ │
│ └─────────────┘ └─────────────┘ └───────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 服务层 (Services) │
│ 评分引擎 · 任务队列 · 系统配置 · 历史服务 · 布林带服务 │
│ Finviz · 行业分析 · 社交情绪 · 技术指标 · 报告渲染 │
├─────────────────────────────────────────────────────────────┤
│ 数据层 (Data) │
│ ┌─────────────────────┐ ┌────────────────────────────┐ │
│ │ 10 Data Fetchers │ │ SQLite + SQLAlchemy ORM │ │
│ │ yfinance · xueqiu │ │ PRAGMA WAL/mmap/cache=64MB │ │
│ │ akshare · tushare │ │ ON CONFLICT 批量 upsert │ │
│ │ efinance · baostock │ │ 9 个 Repository │ │
│ │ openbb · twelvedata │ │ TTL(L1) + SQLite(L2) 缓存 │ │
│ │ pytdx · tickflow │ └────────────────────────────┘ │
│ │ (auto failover) │ ┌────────────────────────────┐ │
│ └─────────────────────┘ │ 7 搜索引擎 Provider │ │
│ │ Tavily · SerpAPI · Bocha │ │
│ │ MiniMax · Brave · SearXNG │ │
│ │ AkshareNews │ │
│ └────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 基础设施 (Infrastructure) │
│ utils/concurrency.py — 11 个池统一通过 STOCKLENS_*_WORKERS │
│ utils/cache.py — TTLCache + thread-local SQLiteCache│
│ utils/logging_setup — 文件/控制台双输出 + DEBUG 级日志 │
├─────────────────────────────────────────────────────────────┤
│ 输出层 (Output) │
│ 报告生成器 (Markdown/微信/简报模板，Jinja2) │
│ 10 推送渠道: 微信企业 · 飞书 · Telegram · Email · Discord │
│ Pushover · PushPlus · ServerChan3 · AstrBot │
│ 自定义 Webhook │
├─────────────────────────────────────────────────────────────┤
│ 测试层 (Tests) │
│ tests/unit/ — pytest 246 用例 │
│ scoring helpers · composite score · concurrency · code 归一化│
└─────────────────────────────────────────────────────────────┘
- 10 个 Fetcher 实现统一的
BaseFetcher接口 DataFetcherManager按优先级（{SOURCE}_PRIORITY环境变量）逐个尝试- 每个 Fetcher 声明支持的市场（A/港/美），路由时自动跳过不支持的源
- 熔断机制：连续失败后冷却
CIRCUIT_BREAKER_COOLDOWN秒
三种配置方式（优先级从高到低）：
- LiteLLM YAML —
LITELLM_CONFIG=litellm_config.yaml，完整的 Router 配置 - 多通道环境变量 —
LLM_CHANNELS=deepseek,gemini，每通道独立配置 - Legacy 单 Key —
GEMINI_API_KEY/OPENAI_API_KEY，自动转换为 Router
所有方式最终统一为 LiteLLM Router，支持多模型负载均衡和 fallback。
- 18 个独立模型，每个模型输出标准化分数
- 综合评分公式：宏观 25 + 基本面 20 + 估值 20 + 技术+动量 15 + 困境 10 + 情绪 10（满分 100）
- 评分由 Python 确定性计算，LLM 不可修改，只负责解读
- 已被 246 单测中的 14 用例锁定行为（
tests/unit/test_composite_score.py）
single模式：单个 ReAct Agent，循环调用工具multi模式：编排器协调 5 个专业 Agent- Technical Agent → 技术面分析
- Intel Agent → 情报搜索
- Risk Agent → 风险评估（可一票否决）
- Strategy Agent × N → 策略回测
- Decision Agent → 最终决策
- Agent 工具并行执行（线程池
AGENT_TOOLS，默认 5）
- L1：进程内
TTLCache，热数据秒级访问 - L2：SQLite 持久化缓存，跨进程/重启保留；thread-local 连接复用，避免每次 get/put 重建连接 + PRAGMA
- 缓存 key 基于函数签名 + 参数哈希
- Pipeline 把"数据增强"和"LLM 调用"拆为两个独立线程池
- enrichment 完成一只 → 通过
add_done_callback立即向 LLM 池提交任务 - 消除"全部 enrich 完成才开始 LLM"的空闲等待
- 详见 modules/pipeline.md
DatabaseManager._setup_sqlite_pragmas() 注册 SQLAlchemy connect 事件，每个新物理连接自动应用：
| PRAGMA | 值 | 作用 |
|---|---|---|
journal_mode |
WAL |
写不阻塞读，并发读 2-5× |
synchronous |
NORMAL |
比 FULL 快 ~2× |
busy_timeout |
5000 |
锁竞争最多等 5 秒 |
cache_size |
-64000 |
每连接 64MB 页缓存 |
temp_store |
MEMORY |
临时表/索引内存中 |
foreign_keys |
ON |
启用 FK 约束 |
mmap_size |
268435456 |
256MB 内存映射 |
wal_autocheckpoint |
2000 |
F4: 8 MiB 触发 checkpoint（默认 4 MiB 太频繁） |
optimize |
— | 每次新连接 + atexit 各跑一次，刷新 planner 统计 |
save_dataframe（日线）/ save_weekly_data / save_pe_history 用 SQLite INSERT ... ON CONFLICT DO UPDATE 一次性 upsert，相比逐行 select-then-insert 快 10-20×。
所有 ThreadPoolExecutor 通过 stocklens.utils.concurrency.get_pool_workers(name) 取 worker 数：
STOCKLENS_<NAME>_WORKERS具名覆盖STOCKLENS_DEFAULT_WORKERS全局覆盖os.cpu_count() or 4fallback
11 个池接入：PIPELINE / PREFETCH / DATA_FETCH / DC_IO / US_ENRICH / US_MACRO / AGENT_TOOLS / SEARCH / STOCK_INFO / TASK_QUEUE / TASK_SERVICE。
- 核心层 (
stocklens/) 不依赖适配层 (bot/,api/) BotMessage/ChatType等跨层类型放在stocklens.contractsbot/models.py改为 re-export，保持向后兼容
| 目录 | 模块 | 详细文档 |
|---|---|---|
main.py |
CLI 入口 | modules/main.md |
api/ |
REST API | modules/api.md |
bot/ |
Bot 平台 | modules/bot.md |
tickbridge/ |
统一数据层（独立可发布） | modules/tickbridge.md |
stocklens/contracts/ |
跨层契约 | modules/contracts.md |
stocklens/config/ |
配置管理 | modules/config.md |
stocklens/storage/ |
数据库 ORM | modules/storage.md |
stocklens/pipeline/ |
流水线编排 | modules/pipeline.md |
stocklens/analyzer/ |
LLM 分析器 | modules/analyzer.md |
stocklens/agent/ |
多 Agent | modules/agent.md |
stocklens/services/ |
业务服务 | modules/services.md |
stocklens/search/ |
搜索引擎 | modules/search.md |
stocklens/market/ |
市场环境 | modules/market.md |
stocklens/notification/ |
推送通知 | modules/notification.md |
stocklens/portfolio/ |
组合管理 | modules/portfolio.md |
stocklens/backtest/ |
回测系统 | modules/backtest.md |
stocklens/utils/concurrency.py |
并发池配置 | modules/concurrency.md |
strategies/ |
策略定义 | modules/agent.md |
templates/ |
报告模板 | modules/notification.md |
tests/ |
单测 | （pytest tests/） |