Skip to content

INDEX.md

Latest commit

 

History

History
108 lines (87 loc) · 5.58 KB

INDEX.md

File metadata and controls

108 lines (87 loc) · 5.58 KB
Raw

StockLens 开发文档索引

AI 助手请先读此文件，根据任务类型找到对应文档，按需深入阅读。 不要直接扫描全部源码 — 文档已覆盖所有模块的类、函数、文件信息。

🚨 第一条铁律

任何代码修改都必须在同一次提交里同步更新对应文档。

  • 没有文档更新的代码修改 = 未完成。
  • 完整规则与"代码 → 文档"映射表见：../CLAUDE.md
  • Commit message 里必须出现"文档同步"段落，否则回头补。

上手流程（AI 助手按这个顺序读）

  1. docs/CONTEXT.md — 80% 项目上下文，必读，已自动注入
  2. ../CLAUDE.md — 项目硬性规则 + 代码 ↔ 文档同步映射表（commit 前必看）
  3. 本文件（INDEX.md） — 按任务跳转对应模块文档
  4. docs/MODULES.md — 模块速查表（一行一个，含核心类/职责）
  5. 任务相关的 docs/modules/<x>.md — 深入某个模块
  6. 仅在以上文档不足时才读源码；读完源码请把缺失的信息补回文档

快速导航

我想了解... 读哪个文档
项目压缩上下文（80% 信息一文读完） CONTEXT.md
项目硬性规则 + 代码↔文档同步映射 ../CLAUDE.md
所有模块一览（一行一个，快速定位） MODULES.md
整体架构、分层设计、技术选型 ARCHITECTURE.md
数据从采集到报告的完整流程 DATA_FLOW.md
开发环境、常用命令、Git 规则、文档同步检查表 DEV_GUIDE.md
CLI 入口 & 命令行调度 modules/main.md
配置管理 & 环境变量 modules/config.md
跨层契约（BotMessage 等共享类型） modules/contracts.md
数据库 & ORM 模型 + PRAGMA modules/storage.md
底层资产管理（catalog/icons/logos，AssetManager 类） modules/assets.md
多源数据采集层（独立可发布） modules/tickbridge.md
量化计算核（独立可发布，零 IO） modules/quantcore.md
统一缓存层（cachetools+diskcache 嵌入） modules/kvcache.md
分析流水线编排（含流水线设计） modules/pipeline.md
LLM 分析器 & Prompt 构建 modules/analyzer.md
多 Agent 系统 modules/agent.md
业务服务层（评分/技术指标/行业等） modules/services.md
搜索引擎 & 新闻情报 modules/search.md
市场环境（宏观/PE 百分位） modules/market.md
推送通知（10 种渠道） modules/notification.md
组合管理 modules/portfolio.md
回测系统 modules/backtest.md
FastAPI REST API modules/api.md
钉钉/飞书 Bot modules/bot.md
并发池/线程池可调配置 modules/concurrency.md
跨包工作 spec（前端 / 跨 AI 协作） specs/

项目技术栈

  • 后端：Python 3.9+ / FastAPI / SQLAlchemy / LiteLLM
  • 数据库：SQLite（启用 WAL/mmap，通过 SQLAlchemy ORM）
  • 缓存：进程内 TTL + SQLite L2（thread-local 连接）
  • 测试：pytest（246 用例）

关键入口文件

文件 职责
main.py CLI 入口，命令行参数解析，调度分析/Web/Bot
api/app.py FastAPI 应用工厂；lifespan 创建 long_pool/io_pool
stocklens/config/settings.py Config 单例，130+ 环境变量
stocklens/pipeline/orchestrator.py 分析流水线编排器（核心）
stocklens/pipeline/stock_indicators.py 趋势 + 多周期技术指标 helper
stocklens/analyzer/llm_analyzer.py LLM 分析器
stocklens/agent/orchestrator.py 多 Agent 编排器
tickbridge/core/manager.py 数据源管理器
stocklens/services/scoring/engine.py 量化评分薄壳（实际算法在 quantcore/scoring/engine.py）
quantcore/scoring/engine.py 纯量化评分引擎（ScoringEngine + 18 模型）
stocklens/storage/engine.py DatabaseManager + PRAGMA 配置
stocklens/utils/concurrency.py 并发池配置
stocklens/contracts/ 跨层契约（BotMessage 等）

⚠️ 文档维护规则（强制 — 完整版见 ../CLAUDE.md）

每次修改代码后，必须同步更新对应文档：

  1. docs/modules/{模块名}.md — 新增/删除/修改了类、函数、文件时
  2. docs/MODULES.md — 模块结构变化（新增/删除模块、文件数量变化）时
  3. docs/DATA_FLOW.md — 数据流程变化时
  4. docs/ARCHITECTURE.md — 架构层面变化时
  5. docs/CONTEXT.md — 目录映射变化时
  6. README.md — 顶层架构图、功能亮点、命令行参数变化时

完整的"代码路径 → 文档"映射表见 ../CLAUDE.md。

不更新文档的代码修改视为未完成；commit 前用以下命令自检：

git diff --stat | grep -E "\.(py|j2|yaml)$"   # 代码改动
git diff --stat | grep -E "docs/.*\.md$"      # 文档改动
# 两者都不应为空

测试

pytest tests/ -q              # 全部 246 单测
pytest tests/unit/ -v         # 详细输出

测试入口：tests/unit/{test_scoring_types,test_composite_score,test_concurrency,test_stock_code}.py