菜单
仓库架构分析 — 架构/数据/逻辑三层并行分析，产出完整架构文档（架构图+文件级分析+代码决策+模块影响矩阵）。下游 mvp-approach 的输入源。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
上下文园艺师 — 先读项目，再读 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/，支持按阶段/日期/关键词检索。
基于 SOC 职业分类
| name | repo-decompose |
| description | 仓库架构分析 — 架构/数据/逻辑三层并行分析，产出完整架构文档（架构图+文件级分析+代码决策+模块影响矩阵）。下游 mvp-approach 的输入源。 |
| argument-hint | decompose https://github.com/owner/repo | split [repo] requirements | architecture analysis |
| dependencies | {"downstream":["knowledge-graph","semantic-rag"],"upstream":[]} |
将 GitHub 仓库的系统级理解转化为完整架构文档。
旧版输出: 三层需求树 JSON (REQ-A1, REQ-D1...) — 太抽象，Loop 后续阶段无法使用。
新版输出: docs/loop-docs/architecture.md — 完整架构文档，每模块有架构图、文件分析、代码决策解释。
输出目标: 一个架构师接手这个项目，读完 architecture.md 就能画出完整的系统架构图。
| 文件 | 内容 |
|---|---|
docs/loop-docs/architecture.md | 主架构文档 — 分层架构图 + 模块详解 + 证据矩阵 |
docs/loop-docs/file-index.md | 全文件索引 — 每个文件: 做什么、为什么这样写、和其他文件的联系 |
1. 解析仓库路径 → 浅克隆 (--depth 1)
2. 统计文件数 → 确定规模级别 (S/M/L/XL)
3. 检测语言/框架/build 系统
4. 定位入口文件
| 级别 | 源文件数 | 分析策略 |
|---|---|---|
| S | < 100 | 全文件逐一分析 |
| M | 100 - 500 | 按目录分组，每组一个子任务 |
| L | 500 - 2000 | 架构层全量 + 数据/逻辑层按域拆分 |
| XL | > 2000 | 架构层全量，数据/逻辑层选核心路径 |
目标: 识别模块边界、依赖方向、关键抽象、入口点。
产出（写入 architecture.md 的架构层章节）:
## 架构层
### 系统架构图
┌─────────────────────────────────────────────────────────────┐ │ 入口层 │ │ main.py (CLI) server.py (Web API) webui.py (Gradio) │ └─────────┬──────────────────┬──────────────────┬─────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 编排层 │ │ src/core/pipeline.py │ │ StockAnalysisPipeline.run() — 分析流水线总控 │ └──┬──────────┬──────────┬──────────┬──────────┬──────────────┘ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐ │ LLM │ │数据源│ │Agent │ │服务层│ │ 通知推送 │ │ 分析 │ │获取 │ │决策 │ │38个 │ │ 14通道 │ └──────┘ └──────┘ └──────┘ └──────┘ └──────────┘
### 模块边界
| 模块 | 路径 | 职责 | 文件数 | 行数 | 关键入口 |
|---|---|---|---|---|---|
| 核心引擎 | src/core/ | 分析流水线总控 | 11 | 3500 | pipeline.py:run() |
| LLM 分析 | src/analyzer.py | LLM 调用 + 解析 | 2 | 4100 | GeminiAnalyzer.analyze() |
| 多 Agent | src/agent/ | 6 Agent 并行决策 | 18 | 5000 | orchestrator.py |
| 业务服务 | src/services/ | 38 个独立服务 | 38 | 12000 | analysis_service.py |
| 数据获取 | src/data_provider/ | 13 数据源适配器 | 14 | 4500 | base.py |
| 数据持久化 | src/repositories/ | SQLAlchemy ORM 层 | 8 | 1500 | base repository |
| 通知调度 | src/notification.py | 14 通道统一入口 | 2 | 2651 | NotificationService.send() |
| 通知通道 | src/notification_sender/ | 14 个独立 sender | 14 | 2000 | 各自的 send() |
| LLM 封装 | src/llm/ | litellm 统一后端 | 8 | 2000 | litellm_backend.py |
| 配置 | src/config.py | 全局配置中心 | 1 | 3091 | Config 类 |
| Web API | api/ | FastAPI 路由 | 20 | 4000 | app.py |
| Bot | bot/ | 多平台 Bot 适配 | 10 | 2000 | dispatcher.py |
### 依赖方向
main.py ├── src/core/pipeline.py │ ├── src/data_provider/ ← 数据获取 │ ├── src/analyzer.py ← LLM 分析 │ │ └── src/llm/ ← LLM 后端 │ ├── src/agent/ ← 多 Agent │ └── src/notification.py ← 通知调度 │ └── src/notification_sender/ ← 14 通道 └── src/config.py ← 全局配置
依赖规则:
### 证据矩阵
**每个模块的"存在证据"——不只是代码，还有构建文件和配置:**
| 模块 | 证据文件 | 证据类型 | 入口函数 | 被依赖方 | 核心路径 |
|---|---|---|---|---|---|
| analyzer | src/analyzer.py:1746 | 源码 | GeminiAnalyzer.__init__() | pipeline | ✅ 是 |
| pipeline | src/core/pipeline.py:1 | 源码 | StockAnalysisPipeline | main.py, server.py | ✅ 是 |
| notification | src/notification.py:170 | 源码 | NotificationService.__init__() | pipeline | ✅ 是 |
| data_provider | src/data_provider/base.py | 源码 + requirements.txt | DataFetcher | pipeline | ✅ 是 |
| llm | src/llm/litellm_backend.py | 源码 + requirements.txt (litellm>=1.80) | LiteLLMGenerationBackend | analyzer | ✅ 是 |
| webui_frontend | src/webui_frontend.py | 源码 | Gradio UI | main.py --webui | 🟡 支撑 |
| feishu_doc | src/feishu_doc.py | 源码 | 飞书文档导出 | main.py --export | ✂️ 可砍 |
| md2img | src/md2img.py | 源码 | Markdown→图片 | notification (微信) | 🟡 支撑 |
数据层产出（写入 architecture.md）:
## 数据层
### 核心数据模型
#### AnalysisResult — 分析结果（28 字段）
**定义**: `src/analyzer.py:1557`
**生命周期**: LLM 生成 → 完整性校验 → 占位填充 → 决策稳定化 → 格式化输出
**消费者**: pipeline, notification, history_service, decision_signal_extractor
**字段分类**:
| 类别 | 字段 | 来源 |
|---|---|---|
| 基础信息 | code, name, success, error_message | 必填，pipeline 传入 |
| 核心指标 | sentiment_score, operation_advice, trend_prediction | LLM 输出 |
| 决策仪表盘 | dashboard (core_conclusion, battle_plan, intelligence, data_perspective) | LLM 输出 → parsed JSON |
| 详细分析 | technical_analysis, fundamental_analysis, news_summary | LLM 输出 |
| 市场快照 | market_snapshot | 数据源实时数据 |
| 审计 | model_used, llm_usage, provider_trace | LLM 调用元数据 |
#### MarketSnapshot — 实时行情
**定义**: `src/data_provider/realtime_types.py`
**用途**: 在分析时注入 prompt，在报告中展示
### 数据流转
数据源 (13 个 adapter) ↓ 优先级 fallback: efinance → akshare → tushare → ... data_provider (统一接口) ↓ dict/Dataclass pipeline (组装 context) ↓ context dict analyzer (构建 prompt) ↓ prompt string LLM (生成分析) ↓ JSON response analyzer._parse_response() (解析 + 校验) ↓ AnalysisResult pipeline (后处理) ↓ ├─→ notification (格式化 → 推送) ├─→ repositories (持久化到 SQLite) └─→ decision_signal_extractor (提取交易信号)
### 存储策略
| 数据类型 | 存储位置 | ORM 模型 | 索引 | 清理策略 |
|---|---|---|---|---|
| 分析结果 | SQLite → analysis_results | AnalysisRecord | (code, created_at) | 保留 90 天 |
| 决策信号 | SQLite → decision_signals | DecisionSignal | (code, created_at) | 保留 180 天 |
| 告警记录 | SQLite → alerts | AlertRecord | (code, triggered_at) | 保留 30 天 |
| 股票信息 | 内存 + stock_index.json | — | code lookup | 启动时加载 |
| LLM 用量 | SQLite → llm_usage | LLMUsageRecord | (model, date) | 保留 365 天 |
1. 触发 (CLI / Web / Scheduler)
2. pipeline.run(config)
2.1 加载配置 + 初始化日志
2.2 获取股票列表 (从自选股或参数)
2.3 大盘分析 (market_review — 可选)
2.4 对每只股票:
a. 获取技术面数据 (data_provider)
b. 获取消息面数据 (search_service)
c. 构建分析上下文 (analysis_context_builder)
d. 调用 LLM 分析 (analyzer.analyze)
e. 后处理 (decision_stability, phase_guardrail)
f. 持久化 (repositories)
g. 推送 (notification.send)
3. 输出汇总报告
| 决策点 | 位置 | 条件 | 处理 |
|---|---|---|---|
| 数据源选择 | data_provider/base.py | 按优先级尝试 | 失败 → 下一个 adapter |
| LLM 模型选择 | analyzer.py:_init_litellm | 配置 → 环境变量 | 主模型 → fallback1 → fallback2 |
| 是否推送 | notification.py:send_with_results | 渠道配置 + 推送时间 | 工作时间推送, 非工作时间静默 |
| 告警触发 | services/alert_service.py | 条件表达式求值 | 满足 → 推送到配置渠道 |
| 噪声抑制 | notification_noise.py | 同股票 5 分钟内重复推送 | 冷却期内跳过 |
层次化错误处理:
L1 — 数据获取失败:
efinance 超时 → akshare fallback → tushare fallback → N/A 标记
L2 — LLM 调用失败:
主模型 429 → 等待 retry → fallback 模型 → 所有模型失败 → 跳过该股 (不阻塞整批)
L3 — 解析失败:
JSON 不合法 → json_repair 修复 → 仍失败 → 文本正则提取 → 仍失败 → 兜底填充
L4 — 推送失败:
单通道失败 → 记录日志 → 不影响其他通道 → 不影响分析结果持久化
所有异常在 pipeline 层有统一 catch——单只股票失败不影响批处理继续。
docs/loop-docs/file-index.md — 按目录组织的完整文件索引:
# 文件索引
## src/analyzer.py (2598 行)
**职责**: LLM 分析主模块
**入口类**: GeminiAnalyzer (2280 行)
**关键方法**:
- `analyze()` (L2866-3138): 主分析流程 — 获取数据→构建 prompt→调 LLM→解析→完整性检查
- `_format_prompt()` (L3140-3590): 450行 prompt 模板——为什么长: 技术面+消息面+市场阶段+决策指令 需覆盖全部场景
- `_parse_response()` (L3778-3891): 三层解析防御——JSON 解析→修复→文本正则提取
- `_call_litellm_impl()` (L2603-2828): 多模型 fallback 封装
**依赖**: src/llm/, src/config/, src/report_language/, src/schemas/
**被依赖**: src/core/pipeline.py, src/services/analysis_service.py
**修改注意事项**: analyze() 签名变更影响 pipeline; _format_prompt() 变更影响所有股票分析质量
**历史**: 辅助函数已拆分到 analyzer_helpers.py (1507 行)，核心类待拆分
## src/core/pipeline.py (450 行)
[同样的格式...]
... (所有源文件)
---
## 文档规模约束
**下限（低于此值 = 敷衍，不可接受）:**
| 文档 | 下限 | 检查方式 |
|---|---|---|
| `architecture.md` | 架构图 + 证据矩阵 + 数据流 + 决策点 + 错误处理 | 5 个必须章节全部非空 |
| 架构图 | ASCII 图覆盖全部顶级模块 | 模块数 = 图中节点数 |
| 证据矩阵 | 每个模块一行（证据文件/入口/被依赖方/核心路径） | 矩阵行数 = 模块数 |
| 数据流图 | 从数据源到最终输出的完整路径 | ≥ 3 层转换 |
| 关键决策点 | ≥ 3 个运行时决策（if/switch 分支） | 条目数 ≥ 3 |
| `file-index.md` | 每个源文件 ≥ 5 行（职责/关键方法/依赖/被依赖/修改注意事项） | 行数 / 文件数 ≥ 5 |
**上限（超过此值 = 膨胀，需拆分）:**
| 文档 | 上限 | 超过时操作 |
|---|---|---|
| `architecture.md` 整体 | 600 行 | 拆分到 `architecture-layer-{n}.md`，主文档只保留架构图 + 模块总表 + 引用 |
| `file-index.md` 整体 | 1000 行 | 按目录拆分 `file-index-{dir}.md`，主文档保留目录级索引 |
| 单个文件分析 | 15 行 | 超过说明在写论文而非分析——压缩到 15 行以内 |
**规则：** 文件分析控制在 5-15 行。5 行是下限（必须覆盖 5 个字段），15 行是上限（不要在 50 行的文件上写 30 行分析）。
---
## 反合理化表
| # | Agent 借口 | 反驳 |
|---|---|---|
| 1 | "架构图用文字描述一下就行" | ASCII 架构图是给 Agent 和人都能直接读的——比图片更 grep 友好。文字描述替代不了可视化的模块关系。 |
| 2 | "证据矩阵写太详细了，列出模块名就够了" | 模块名不证明它真的存在。构建文件+源码入口+被依赖方三重验证——否则 README 愿望清单混入事实。 |
| 3 | "文件太多了，只分析关键文件" | "关键文件"的判断依赖入口点依赖链——不在链上的文件可能是遗漏的核心，也可能是死代码。全量覆盖才能区分。 |
| 4 | "代码决策解释是可选的分析" | 代码决策解释是 Fix 阶段最重要的输入——知道"为什么这样写"才能判断"能不能改"。 |
| 5 | "数据流图用列表就行" | ASCII 流程图比列表更能展示数据在模块间的流转方向和转换节点。 |
## 验证清单
- [ ] `docs/loop-docs/architecture.md` 已生成
- [ ] 架构图使用 ASCII 树状图，模块边界清晰
- [ ] 证据矩阵覆盖每个模块（证据文件 + 入口函数 + 被依赖方）
- [ ] README 声称的能力全部通过构建文件交叉验证
- [ ] 数据流图包含从数据源到最终输出的完整路径
- [ ] 关键决策点表格覆盖所有运行时分支
- [ ] 错误处理策略分 L1-L4 层次
- [ ] `docs/loop-docs/file-index.md` 覆盖全部源文件
- [ ] 每个文件分析包含: 职责/关键方法/依赖/被依赖/修改注意事项
- [ ] 交叉引用 knowledge-graph 和 semantic-rag 的结论