一行一个模块，快速定位。点击「详细文档」列链接查看完整的类/函数/文件说明。
| 模块 | 目录 | 文件数 | 核心文件 | 核心类/函数 | 职责 | 详细文档 |
|---|---|---|---|---|---|---|
| CLI 入口 | main.py |
1 | main.py | main(), run_analysis() |
命令行解析、调度分析/Web/Bot/定时任务 | main.md |
| REST API | api/ |
22 | app.py, deps.py, v1/endpoints/*.py | create_app() + 9 路由 |
FastAPI 路由、可选认证、中间件、long_pool/io_pool | api.md |
| Bot 平台 | bot/ |
14 | platforms/.py, commands/.py, dispatcher.py, models.py | DingTalkStream, FeishuStream |
钉钉/飞书 Stream 客户端、命令分发；models.py re-export stocklens.contracts |
bot.md |
| 模块 | 目录 | 文件数 | 核心文件 | 核心类/函数 | 职责 | 详细文档 |
|---|---|---|---|---|---|---|
| 统一数据层 | tickbridge/ |
30+（核心 / 契约 / 10 数据源 / 适配） | core/manager.py, core/provider.py, contracts/.py, sources/.py | DataFetcherManager（运行中）, DataProvider（Commit 2 实装）, BaseFetcher, DomainFetcher |
多源 fall-over + 目标 cache→DB→source 三级读路径；可独立开源（独立 pyproject + LICENSE）。所有数据获取都走这里；旧 data_provider/ 已删除（1b） |
tickbridge.md |
| 统一搜索层 | querybus/ |
7 providers + cache/manager/filters/reporting | core/provider.py, core/manager.py, providers/*.py | SearchProvider, SearchManager, BaseSearchProvider, InMemoryTTLCache |
多 Provider fall-over + 时间窗过滤 + 通用情报报告渲染；独立可发布（pyproject + LICENSE）。所有 search/news 都走这里 | querybus.md |
| 统一通知层 | pulsefan/ |
10 senders + core/registry/dispatcher/notifier + formatting | core/notifier.py, senders/*.py, config/schema.py | Notifier, ParallelDispatcher, BaseSender, NotificationConfig |
多渠道并行 fan-out + 类型化 NotificationConfig + 内置 markdown/分块/飞书 helpers；独立可发布（pyproject + LICENSE）。所有 push/notification 都走这里 | pulsefan.md |
| 量化计算核 | quantcore/ |
18 (scoring 6 + indicators 6 + stats 3 + backtest 2 + 顶层) | scoring/engine.py, indicators/{trend,bollinger,tech,resample,labels}.py, stats/{risk,correlation}.py, backtest/engine.py | ScoringEngine, BacktestEngine, StockTrendAnalyzer, compute_bollinger, compute_tech_indicators, resample_ohlcv |
纯量化算法（18 评分模型 + 趋势/布林带/Fibonacci/K 线 + Sharpe/Sortino/Beta + 通用 OHLCV resample + 中文标签 + 回测引擎）；零 IO，仅依赖 numpy/pandas；独立可发布（pyproject + LICENSE）。所有纯数学计算都走这里 | quantcore.md |
| 统一缓存层 | kvcache/ |
13 (core 4 + backends 4 + codecs 3 + policies 3 + instrumentation 1) | core/{manager,namespace,protocols,stats}.py, backends/{memory,sqlite,tiered,null}.py | CacheManager, Namespace, MemoryBackend, SqliteBackend, TieredBackend |
唯一缓存实现：门面层手写（namespace + 命中率统计 + SWR 策略）+ 存储层嵌入开源库（cachetools 内存 / diskcache 磁盘）。每个业务模块独立调优 TTL/容量/序列化（配置在 cache_bootstrap.py）。所有缓存都走这里 |
kvcache.md |
| 底层资产 | stocklens/assets/ + assets/ |
2 (类) + 290 (数据) | manager.py | AssetManager 单例 (assets) |
集中管理 catalog/icons/logos；HTTP 暴露 /icons/font/、/logos/ |
assets.md |
| 配置管理 | stocklens/config/ |
10 | settings.py, settings_helpers.py, registry.py, registry_fields.py, llm.py | Config 单例 |
130+ 环境变量、字段注册表（已拆分）、LLM 通道解析、校验 | config.md |
| 跨层契约 | stocklens/contracts/ |
2 | bot_message.py | BotMessage, ChatType |
核心层 ⇄ 适配层共享数据类 | contracts.md |
| 数据库 ORM | stocklens/storage/ |
4 | engine.py, models.py, helpers.py | DatabaseManager 单例 |
SQLAlchemy ORM、表定义、PRAGMA(WAL) 配置、scoring 快照 | storage.md |
| 数据仓库 | stocklens/repositories/ |
10 | *_repo.py | 9 个 Repository 类 | CRUD（含批量 upsert：日线/周线/PE） | storage.md |
| 模块 | 目录 | 文件数 | 核心文件 | 核心类/函数 | 职责 | 详细文档 |
|---|---|---|---|---|---|---|
| 流水线编排 | stocklens/pipeline/ |
8 | orchestrator.py, data_collector.py, stock_indicators.py, us_data_enricher.py, analysis_flow.py, push_handler.py, trading_calendar.py, metrics.py | StockAnalysisPipeline |
流水线（enrich + LLM 并行）、采集、技术指标 helper、US/HK 增强、交易日历 | pipeline.md |
| LLM 分析器 | stocklens/analyzer/ |
5 | llm_analyzer.py, prompt_builder.py, response_parser.py, result_types.py, trend_analyzer.py | GeminiAnalyzer, StockTrendAnalyzer |
Prompt 构建、LLM 调用、响应解析；trend_analyzer.py 是 quantcore.indicators.trend 的薄壳 |
analyzer.md |
| 多 Agent | stocklens/agent/ |
20+ | orchestrator.py, runner.py, factory.py, agents/.py, strategies/.py, tools/*.py | AgentOrchestrator, 5 个 Agent + Strategy |
ReAct 循环、5 Agent 协作、工具池(AGENT_TOOLS)、YAML 策略 | agent.md |
| 评分引擎（薄壳） | stocklens/services/scoring/ |
7 | __init__.py (ScoringService 子类 + CBOE 注入), _cboe_fetcher.py, types/fundamental/valuation/sentiment/technical/engine.py (全是 quantcore re-export) |
ScoringService (= quantcore.scoring.ScoringEngine + CBOE fetcher) |
业务层薄壳；纯算法在 quantcore/scoring/；网络抓 CBOE 留在此 |
services.md + quantcore.md |
| 模块 | 目录 | 文件数 | 核心文件 | 核心类/函数 | 职责 | 详细文档 |
|---|---|---|---|---|---|---|
| 业务服务 | stocklens/services/ |
20+ | scoring/(quantcore 薄壳), task_queue.py, task_service.py, system_config_service.py, bollinger_service.py(IO+缓存薄壳), tech_indicators_service.py(SPY/QQQ 抓取薄壳) 等 | 多个 Service | 任务队列/系统配置/历史/布林带 IO/Finviz/技术指标 IO/社交情绪等；评分与纯指标已下沉到 quantcore | services.md |
| 搜索壳 | stocklens/search/ |
2 | stock_search_service.py, init.py | StockSearchService + STOCK_INTEL_DIMENSIONS + 进程级 singleton |
包装 querybus.SearchProvider：股票特化 query / ETF 检测 / 5 维度并发情报 / 价格兜底 |
search.md |
| 市场环境 | stocklens/market/ |
5 | us_macro.py, us_market_env.py, profile.py, strategy.py | USMacroSnapshot, USMarketEnv |
美股宏观指标、PE 百分位、市场画像/策略 | market.md |
| 模块 | 目录 | 文件数 | 核心文件 | 核心类/函数 | 职责 | 详细文档 |
|---|---|---|---|---|---|---|
| 通知壳 | stocklens/notification/ |
9 + metadata_sections | orchestrator.py, config_adapter.py, report_builder.py, metadata_report.py, report_generators.py | ReportOrchestrator (+ NotificationService 别名) + 12 段元数据报告 |
包装 pulsefan.Notifier：daily/batch/metadata 报告生成 + Bot 会话回复 + summary-only 模式 |
notification.md |
| 组合管理 | stocklens/portfolio/ |
4 | portfolio_service.py, import_service.py, risk_service.py | PortfolioService |
FIFO/均价成本、FX 换算、CSV 导入、风险评估 | portfolio.md |
| 回测系统 | stocklens/backtest/ |
3 | engine.py, backtest_service.py | BacktestEngine, BacktestService |
历史分析事后评估 | backtest.md |
| 认证 | stocklens/auth/ |
2 | authenticator.py | Authenticator |
运行时认证（可选） | api.md |
| Schemas | stocklens/schemas/ |
2 | report_schema.py | 报告 schema | 报告字段约束 | - |
| 工具库 | stocklens/utils/ |
8 | concurrency.py, cache.py, logging_setup.py, data_processing.py, feishu_doc.py(shim), markdown_to_image.py, json_io.py, fail_open.py | get_pool_workers, TTLCache, SQLiteCache |
并发池/缓存/日志/格式化/markdown→图片 | concurrency.md |
| 集成 | stocklens/integrations/ |
1 | feishu_doc.py | FeishuDocManager |
第三方 SaaS SDK 包装（飞书云文档等） | services.md |
| 模块 | 目录 | 文件数 | 用例数 | 职责 |
|---|---|---|---|---|
| 单测 | tests/unit/ |
4 | 99 | scoring 类型/composite score/concurrency/stock_code |
运行：pytest tests/ -q