Menu
语义分析与项目概览 — 三层降级深度跨语言分析，产出完整项目技术文档和零依赖 RAG 索引。每个模块有职责分析、设计决策、上下游关系。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
上下文园艺师 — 先读项目，再读 CLAUDE.md，逐层审计四层架构（CLAUDE.md → skills/ → hooks/ → memory/）。不做代码修改，只做审查、总结、归纳。生成建议报告，可视化花园输出。
将 repo-decompose 需求树 + mvp-approach 核心路径转化为分阶段可执行的交付计划。每个 Phase 有明确目标、任务清单、验收标准和依赖关系。
代码优化循环总控 — 12 阶段生命周期（2 前置门控 Detect+EnvReady，10 阶段优化闭环 Observe→Understand→Diagnose→Plan→Bound→Fix→Verify→SelfReview→Learn→Decide）。跨 Agent 自适应，环境自动就绪，任务驱动单流程。
基于 knowledge-graph 模块依赖 + mvp-approach 边界条件 + task-graph 任务清单，生成可修改文件白名单和禁止触碰红区。防止 Agent 无意中修改核心模块。
代码知识图谱 — 四层递进分析（符号表→调用链→数据流→模块依赖），产出完整结构化 Markdown 技术文档供 Loop Agent 和开发者阅读。每个文件有详细分析、每段关键代码有决策解释、模块间有影响矩阵。
循环日志管理 — 每个阶段产出结构化 markdown 日志，记录完整分析过程，可追溯、可检索。自动保存到 .loop-log/，支持按阶段/日期/关键词检索。
| name | semantic-rag |
| description | 语义分析与项目概览 — 三层降级深度跨语言分析，产出完整项目技术文档和零依赖 RAG 索引。每个模块有职责分析、设计决策、上下游关系。 |
| argument-hint | explain [repo] | what does [project] do | project overview |
| triggers | ["这个项目是做什么的","解释一下这个仓库","项目架构","认证逻辑在哪"] |
不是写摘要——是写完整的项目技术文档。 两步产出：
docs/loop-docs/project-overview.md — 完整项目概览，每模块一个章节，包含"为什么这样设计".semantic-rag.json — 轻量 RAG 索引，用于快速问答（旧版功能的保留）零外部依赖。 不需要向量数据库、embedding API。
旧版: ≤25 字摘要 + ≤20 文件 + ≤80 行输出 = 敷衍。 新版: 每个模块详细分析 + 全部文件覆盖 + 设计决策解释 = 技术文档。
输出目标: 一个新人接手这个项目，读完 project-overview.md 就能理解项目全貌、架构设计、各模块职责和代码约定。
docs/loop-docs/project-overview.md这是主输出——给 Loop Agent 和开发者阅读的完整项目文档：
# [项目名] 项目技术文档
> 自动生成于 semantic-rag 分析 | 分析时间: ISO8601 | 分析层级: 🔬 L1 精确
---
## 项目身份
| 属性 | 值 |
|---|---|
| 仓库 | owner/repo |
| 一句话定位 | 面向个人投资者的 A 股智能分析系统 |
| 主语言 | Python (75.7%) |
| 辅助语言 | TypeScript (18%), CSS (5%), Shell (1.3%) |
| 运行时 | Python 3.11+ |
| 框架 | FastAPI + litellm |
| 入口 | main.py (CLI), server.py (Web API), webui.py (Gradio) |
| 数据库 | SQLite (SQLAlchemy ORM) |
| 测试框架 | pytest (200+ 测试文件) |
| 分析层级 | 🔬 L1 精确分析 (tree-sitter AST) |
## 架构模式
**分层架构** (自上而下):
入口层 main.py / server.py / webui.py ← 三种启动方式 ↓ 编排层 src/core/pipeline.py ← 分析流水线总控 ↓ 分析层 src/analyzer.py + src/agent/ ← LLM 调用 + 多 Agent 决策 ↓ 服务层 src/services/ (38个) ← 业务逻辑 ↓ 数据层 src/data_provider/ + src/repositories/ ← 数据获取 + 持久化 ↓ 推送层 src/notification_sender/ (14通道) ← 多渠道推送
**核心数据流**: `CLI/Web 触发 → pipeline.run() → 数据获取 → LLM 分析 → 结果格式化 → 多渠道推送`
**设计决策**:
- 为什么用分层架构而非微服务: 个人投资者场景，单体部署足够。分层保证了模块边界清晰但避免了分布式复杂度。
- 为什么 litellm 统一 LLM 后端: 支持 Gemini/OpenAI/DeepSeek 多模型切换，通过配置文件即可更换，不需要改代码。
- 为什么 SQLite 而非 PostgreSQL: 个人用户数据量小（≤10万条），SQLite 零运维成本。SQLAlchemy ORM 保证了将来可无缝切换。
---
## 模块详解
### `src/core/` — 核心引擎
**职责**: 分析流水线的总控和调度——拿到股票列表 → 逐个拉数据 → 调 LLM 分析 → 推送结果。
**规模**: 11 个文件, ~3500 行
| 文件 | 行数 | 职责 | 关键设计 |
|---|---|---|---|
| `pipeline.py` | 450 | 主流水线 `StockAnalysisPipeline` | 使用 generator 模式逐个 yield 结果，支持断点续跑和进度回调 |
| `scheduler.py` | 320 | 定时任务调度 | 基于 `schedule` 库，不支持 cron 表达式——选择了简单性而非灵活性 |
| `market_review.py` | 480 | 大盘复盘分析 | 独立于个股分析——先跑大盘再跑个股，大盘结论注入个股 prompt |
| `trading_calendar.py` | 180 | A 股交易日历 | 使用 `exchange-calendars` 库，兼容上交所/深交所节假日 |
| `config_manager.py` | 350 | 配置分层管理 | 三层优先级: env > config.py > defaults。热加载通过 `@property` 实现 |
**对外接口**: `run_pipeline(config)`, `run_market_review()`, `get_trading_days()`
**依赖方向**: 依赖 `src/llm/`, `src/data_provider/`, `src/notification/`；被 `main.py`, `server.py` 依赖
**修改风险**: `pipeline.py:run()` 是主入口——签名变更影响所有启动路径。修改前需通过 `tests/test_pipeline*.py`。
### `src/analyzer.py` — LLM 分析层
**职责**: 封装 LLM 调用，把技术面+消息面数据组装成 prompt → 调 LLM → 解析 JSON 响应 → `AnalysisResult`。
**规模**: 2598 行（含辅助函数 1507 行在 `analyzer_helpers.py`）
**核心类**: `GeminiAnalyzer` (2280 行)
- `__init__()` — 初始化 litellm 客户端，注册 fallback 模型链
- `analyze()` — 主分析方法: 获取数据 → 构建 prompt → 调 LLM → 解析 → 完整性检查 → 兜底填充
- `_format_prompt()` — 450 行的 prompt 模板——包含技术面/消息面/市场阶段/决策指令
- `_parse_response()` — JSON 解析 + 修复 + 校验的三层防御
- `_call_litellm_impl()` — 多模型 fallback: 主模型 → fallback1 → fallback2 → 报错
**设计决策**:
- 为什么 `analyze()` 方法 270 行: 因为每一步都有错误处理和重试——不是"写得长"而是"防御深"。
- 为什么 litellm 自带 fallback 还要自己封装一层: litellm Router 的 fallback 不支持 per-model 的 `max_tokens` 差异化配置。
- 为什么 prompt 不使用外部模板文件: 模板内嵌在代码中——prompt 变更 = 代码变更 = 有 git 历史可追溯。
**辅助函数** (在 `analyzer_helpers.py`):
- `check_content_integrity()` — 检查 LLM 输出完整性（必填字段、数值范围）
- `apply_placeholder_fill()` — 对缺失的非关键字段填入占位值
- `stabilize_decision_with_structure()` — 用筹码结构数据修正 LLM 情绪化判断
- `normalize_chip_structure_availability()` — 处理数据源不提供筹码数据的降级
### `src/services/` — 业务服务层
**职责**: 38 个服务模块，每个负责一个独立业务能力。
**规模**: 38 个文件, ~12000 行
| 关键服务 | 职责 | 说明 |
|---|---|---|
| `analysis_service.py` | 分析请求调度 | 异步队列 + 并发控制 (Semaphore) |
| `alert_service.py` | 告警规则引擎 | 支持价格/均线/成交量/技术指标多条件组合 |
| `portfolio_service.py` | 持仓管理 | 成本计算、收益统计、仓位建议 |
| `decision_signal_service.py` | 决策信号提取 | 从 LLM 输出中结构化提取买卖信号 |
| `history_service.py` | 历史分析查询 | 支持按日期/股票/信号类型检索历史结果 |
| `report_renderer.py` | Jinja2 模板渲染 | 分离报告格式和数据——新增报告类型只需加模板 |
| `intelligence_service.py` | 舆情聚合 | 多数据源 (Tavily/SerpAPI) 并行搜索 + 去重 |
| `stock_service.py` | 股票信息查询 | 名称→代码解析、板块归属、基本面概况 |
### `src/data_provider/` — 数据获取层
**职责**: 13 个数据源适配器，按优先级 fallback。
**规模**: 14 个文件, ~4500 行
| 适配器 | 优先级 | 数据覆盖 | 备注 |
|---|---|---|---|
| efinance | P0 | A 股实时行情 | 东方财富接口，速度快但偶尔限流 |
| akshare | P1 | A 股全量数据 | 最全面的免费数据源，但稳定性不如商业 API |
| tushare | P2 | A 股专业数据 | 需要 token，数据质量高 |
| yfinance | P4 | 美股/港股 | 雅虎财经，海外市场主力 |
| longbridge | P5 | 美股/港股 | 长桥 OpenAPI，OAuth 认证 |
| baostock | P3 | A 股历史数据 | 适合回测场景 |
**设计决策**:
- 为什么 13 个数据源: 免费数据源没有 SLA——多源 fallback 是生产环境必须的。优先级按稳定性而非覆盖面排序。
- 为什么用 Adapter 模式而非统一接口: 各数据源的字段名、单位、精度都不同——强行统一会丢失信息。Adapter 保留源数据，上层再归一化。
### `src/notification_sender/` — 推送层
**职责**: 14 个推送通道的独立实现。
**规模**: 14 个文件，每个 80-200 行
**架构契约**: 每个 sender 是独立模块——新增通道只需加一个文件，不影响现有通道。
| 通道 | 适用场景 |
|---|---|
| 企业微信 | 中国大陆主流，支持 Markdown + 图片 |
| 飞书 | 支持 Stream 流式推送 |
| Telegram | 海外用户，支持 HTML/Markdown |
| Discord | 社区场景，Webhook |
| 邮件 (SMTP) | 日报推送，支持分组 |
| Pushover/Pushplus/ServerChan/Gotify/Ntfy/Slack... | 小众但完整的覆盖 |
### `src/llm/` — LLM 调用封装
**职责**: litellm 统一后端 + 用量追踪 + 错误恢复。
**规模**: 8 个文件, ~2000 行
**设计决策**:
- `litellm_backend.py` 封装了 litellm completion + stream 两种调用方式
- `generation_backend.py` 定义了抽象接口——如果要换掉 litellm，只需实现这个接口
- `usage.py` 追踪每次调用的 token 消耗，支持按模型/日期/用户维度统计
- `provider_cache.py` 实现 prompt caching hint——对重复的系统 prompt 部分节省 50% token
### `src/agent/` — 多 Agent 策略系统
**职责**: 6 个专业 Agent 并行分析 + 结果聚合。
**规模**: 18 个文件, ~5000 行
| Agent | 职责 | 输入 | 输出 |
|---|---|---|---|
| `decision_agent` | 综合决策 | 所有 Agent 输出 | 最终买卖建议 |
| `intel_agent` | 舆情分析 | 新闻/公告/研报 | 情绪评分 + 风险警报 |
| `portfolio_agent` | 持仓建议 | 当前持仓 + 分析结果 | 仓位调整建议 |
| `risk_agent` | 风险评估 | 波动率/VaR/最大回撤 | 风险等级 + 止损建议 |
| `technical_agent` | 技术分析 | K 线/均线/量能 | 趋势判断 + 形态识别 |
### `src/notification.py` — 通知调度
**职责**: 14 通道的统一调度入口（报告生成已拆到 `notification_reports.py`）。
**规模**: 1024 行（拆分后）
**设计决策**: 报告生成通过 Mixin 模式继承——`NotificationService(ReportGenerationMixin, WechatSender, ...)`。这样 14 个 sender 保持独立，报告格式变更不影响推送通道。
### `src/config.py` — 配置管理
**职责**: 全局配置中心。
**规模**: 3091 行（⚠️ 质量诊断已标记为过大模块）
**设计决策**:
- 为什么 3000 行: 每个配置项有 docstring + 类型注解 + 默认值 + 环境变量映射 + 校验逻辑。是"文档化配置"而非"臃肿"。
- 三层优先级: 环境变量覆盖 → 配置文件 → 代码默认值。通过 `@property` 延迟解析实现热加载。
- 改进建议: 按域拆分为 config/models.py + config/env.py + config/defaults.py。
---
## 技术栈总览
| 层级 | 技术选型 | 为什么选它 |
|---|---|---|
| LLM 调用 | litellm | 统一 30+ LLM 提供商接口，支持 fallback |
| Web 框架 | FastAPI | 异步支持 + 自动 OpenAPI 文档 |
| 前端 | React + Vite | HMR 开发体验 + TypeScript |
| 桌面端 | Electron | 跨平台 + Web 技术栈复用 |
| ORM | SQLAlchemy | Python 生态最成熟的 ORM |
| 数据分析 | pandas + numpy | A 股数据天然是表格数据 |
| 模板引擎 | Jinja2 | 报告渲染——分离格式和数据 |
| Bot 框架 | discord.py + lark-oapi + dingtalk-stream | 每个平台的原生 SDK |
## 代码约定
**命名**: snake_case 全项目统一（变量/函数/文件）
**类型注解**: 所有公共函数有完整类型注解
**错误处理**: try/except + 自定义异常类，在 controller 层统一 catch
**测试**: pytest, 测试文件与源文件同级 `_test.py` 后缀
**注释**: docstring 覆盖所有公共模块/类/函数，内部逻辑用行注释
**提交**: conventional commits (feat/fix/docs/refactor/test/chore)
## 已知技术债
| 问题 | 位置 | 严重度 | 状态 |
|---|---|---|---|
| analyzer.py God class | src/analyzer.py | HIGH | 辅助函数已拆分，核心类待拆分 |
| config.py 过大 | src/config.py | MEDIUM | 待按域拆分 |
| 14 个 sender 无集成测试 | src/notification_sender/ | LOW | 每个至少需 1 个 mock 测试 |
| requirements.txt 无 lock 文件 | requirements.txt | MEDIUM | 已创建 requirements.lock |
| main.py 混合 CLI+初始化+调度 | main.py | MEDIUM | CLI 解析待抽取 |
---
## RAG 索引
零依赖轻量 RAG 索引已生成至 `.semantic-rag.json`。
Chunk 数: [N] | 索引大小: [M] KB
可通过关键词检索快速定位代码位置——"认证逻辑在哪" → 直接返回文件:行号。
| 层级 | 涵盖语言 | 分析粒度 | 可靠性 |
|---|---|---|---|
| L1 | TS, JS, Python, Go, Rust, Java | 函数/类/方法级，读源码写分析 | 高 |
| L2 | C, C++, C#, Kotlin, Swift, PHP, Ruby | 文件级，基于导出符号 + 注释 | 中 |
| L3 | 其他所有语言 | 目录级，README + 结构 | 有限 |
输出中诚实标注: 🔬 L1 精确 / 📄 L2 文件级 / 📁 L3 目录级
事实层级（高→低）:
降权规则: README 声称的模块 → 必须在构建目标中找到 → 才能在文档中列出。否则标注 ⚠️ README 声称但未确认。
下限（低于此值 = 敷衍，不可接受）:
| 文档 | 下限 | 检查方式 |
|---|---|---|
project-overview.md | 每个模块 ≥ 3 个小节（职责/规模、设计决策、依赖方向） | 模块数 × 3 ≤ 实际小节数 |
| 项目身份卡 | 全部 8 个字段非空 | 逐字段检查 |
| 技术栈总览 | ≥ 5 行（每个关键依赖一行 + 选型理由） | 行数 ≥ 5 |
| 代码约定 | ≥ 4 条（命名/类型/错误/测试） | 条目数 ≥ 4 |
| 已知技术债 | 从 quality-audit/diagnose 交叉引用 | 至少引用 quality-audit 的 HIGH 项 |
上限（超过此值 = 膨胀，需拆分）:
| 文档 | 上限 | 超过时操作 |
|---|---|---|
| 单个模块章节 | 60 行 | 拆分到 project-overview-{module}.md，主文档保留 ≤ 20 行摘要 + 引用 |
project-overview.md 整体 | 500 行 | 最多保留前 8 个模块的完整章节，其余只写摘要 + 引用子文档 |
.semantic-rag.json | 1 MB | chunk 数达到上限时，优先保留入口链上的模块 |
规则： 大模块（行数 > 1000 或文件数 > 5）自动触发子文档拆分。小模块（行数 < 200 且文件数 ≤ 2）合并为一个小节。
| # | Agent 借口 | 反驳 |
|---|---|---|
| 1 | "≤25 字摘要够用了" | 25 字说不清一个模块为什么这样设计。技术文档的价值在"为什么"。 |
| 2 | "只看 20 个关键文件就行" | 决定"关键"的标准是入口点依赖链——不在链上的文件可能是死代码，也可能是被遗漏的核心。全量覆盖。 |
| 3 | "L3 语言我完全不懂，跳过" | L3 降级到目录+README。README 总是人类语言。 |
| 4 | "技术文档写太详细了，future loop 用不上" | Fix 阶段需要知道"改了这段代码会影响哪些模块"——这些信息全在模块详解里。 |
| 5 | "架构图用文字描述就行" | 用 ASCII 树状图 + 表格——比图片更 grep 友好，Agent 和人都能直接读。 |
| 6 | "README 降权太严格了，README 通常是对的" | 很多开源项目的 README 是愿望清单而非事实。构建文件不说谎。 |
docs/loop-docs/project-overview.md 已生成style-profile 交叉引用quality-audit 交叉引用.semantic-rag.json 已生成（供快速问答检索）