alpha-analyst 把「分析师级」个股研究的流程工程化:给它一个美股 ticker,它产出一份九节研究备忘——executive summary / financial snapshot / catalysts / DCF 与可比公司估值 / earnings-call 语气变化 / bull-bear / risks——每一个含数字的主张都绑回一条带来源的引用。
核心原则是「LLM 是写手,不是知道分子」:数字全部来自确定性代码与公开数据源(SEC、Yahoo、FRED、Google News),LLM 只负责行文。默认配置用确定性的 mock 写手 + 仓库自带离线 fixtures,零 API key、零出网就能跑通全流程、跑绿全部测试。
给谁用:想读「数字可追溯」研究产出的投研读者;想把多 agent 流水线工程化的开发者。
- 🧮 Decimal DCF 引擎 — 显式预测期 + Gordon 终值 + 敏感性表;终值增速 ≥ WACC、负现金流、缺数据均为显式校验与降级,全程
decimal.Decimal。 →src/alpha_analyst/core/dcf.py - 📊 可比公司估值 — 同行倍数中位数 + 隐含市值;口径诚实标注(如
ocf_multiple明示为 EV/EBITDA 代理)。 →src/alpha_analyst/core/comps.py - 🌐 统一数据层 — Provider 接口 + 注册表 + 磁盘缓存,超时/重试/退避内建;keyless 源覆盖 SEC companyfacts、SEC EDGAR、Yahoo chart、FRED、Google News,缺失数据集自动降级到离线 fixtures。 →
src/alpha_analyst/data/ - 🤖 五路研究 agent + 恶魔代言人 — news / filings / market / earnings / alt-data 并发执行,随后一轮对抗性质询(质询复用原来源引用,不新造证据)。 →
src/alpha_analyst/agents/ - 🔍 引用纪律单一实现 — 事实表(F1…Fn)→ 逐节校验 → 引用导出 → 审计;正文出现数字必须带
[F#],未知标签或「有数字无引用」判失败并自动降级该小节。 →src/alpha_analyst/core/citations.py - 🧪 离线优先、可测 —
ALPHA_DATA_MODE=offline+ALPHA_LLM_MODE=mock全链路可跑;135 条 pytest 全绿,网络调用在传输层用 respx 拦截,测试套件永不出网。 →tests/ - 🗂️ 配置集中 — 数据集→provider 映射与 SEC CIK 表、任务→模型映射、全部环境变量分别收敛到
configs/与.env.example,业务代码不直接读环境变量。 →configs/ - 🖥️ CLI 三件套 —
research(Markdown 或--json)/audit(引用审计,失败退出码 1)/sources(provider 与 fixture 覆盖)。 →src/alpha_analyst/__main__.py
# 0. 克隆并安装(仅 pydantic / pydantic-settings / PyYAML / httpx;Python 3.11+)
git clone https://github.com/lss680455-create/alpha-analyst.git
cd alpha-analyst
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# 1. 零 key、零出网跑一份研究备忘(使用仓库自带离线 fixtures)
ALPHA_DATA_MODE=offline ALPHA_LLM_MODE=mock python run.py research AAPL输出一份九节 Markdown 备忘。落盘与其它命令:
ALPHA_DATA_MODE=offline ALPHA_LLM_MODE=mock python run.py research AAPL > memo.md
ALPHA_DATA_MODE=offline ALPHA_LLM_MODE=mock python run.py audit AAPL跑研究 / 审引用 / 看数据源
python run.py research AAPL # 九节备忘(Markdown)
python run.py research AAPL --json # 结构化 run JSON(含全部 agent 输出与事实表)
python run.py audit AAPL # 引用审计:失效引用时退出码 1
python run.py sources # 已注册 provider、数据集映射、fixture 覆盖抓取真实数据落成离线 fixtures(需要网络;如走上游代理可用 ALPHA_HTTP_PROXY)
python scripts/fetch_fixtures.py --ticker AAPL --peers MSFT,GOOGL,META,NVDA,DELL跑测试(离线,无需 key)
python -m pytest -q # 135 passed关键环境变量(完整清单见 .env.example)
| 变量 | 取值 | 说明 |
|---|---|---|
ALPHA_DATA_MODE |
offline / auto / live |
数据来源:只读 fixtures / 先 live 后降级 / 只打真实接口 |
ALPHA_LLM_MODE |
mock / litellm |
mock 为确定性模板写手;litellm 接任意 LiteLLM 支持的模型 |
ALPHA_HTTP_PROXY |
如 socks5h://127.0.0.1:10808 |
出网代理(仅数据抓取;socks5 需 httpx[socks]) |
ALPHA_EDGAR_USER_AGENT |
YourApp (you@example.com) |
SEC 要求的可识别 User-Agent |
ALPHA_CACHE_DIR / ALPHA_CACHE_TTL_SECONDS |
路径 / 秒 | live 抓取的磁盘缓存 |
ALPHA_MAX_COST_PER_ANALYSIS |
美元 | 成本护栏(仅 litellm 模式生效) |
flowchart LR
A[Yahoo / SEC / FRED / Google News] -->|live| G[DataGateway<br/>provider 注册表 + 缓存]
F[(离线 fixtures)] -->|offline| G
G --> N[news] & FI[filings] & M[market] & E[earnings] & AD[alt-data]
N & FI & M & E & AD --> FACTS[事实表 F1…Fn<br/>core.citations]
FACTS --> DC[Decimal DCF] & CP[comps]
DC & CP --> DA[恶魔代言人<br/>对抗性质询]
DA --> S[合成器<br/>LLM = 写手]
FACTS --> S
S --> V{引用校验}
V -->|通过| R[九节备忘<br/>Markdown / JSON]
V -->|失败小节| D[显式降级]
D --> R
分层职责:
- data/ — 数据层。Provider 接口 + 注册表 + 磁盘缓存;live 源与离线 fixtures 同构,
DataGateway按 mode 择优并降级。 - core/ — 纯逻辑层。DCF、comps、引用纪律、展示格式化,无 I/O、无 LLM,全部可单测。
- agents/ — 研究层。五个数据 agent 只做「抓取 → 找结论」,LLM(或 mock 写手)只出现在需要语言能力的位置;错误不抛出,随输出上报。
- orchestrator/ — 编排层。依赖注入的流水线:并发跑 agent → 构造事实表 → 情景估值(base / bull / bear)→ 质询 → 合成。
- report/ — 渲染层。
ResearchRun→ Markdown(备忘 + 引用清单 + 附录)或结构化 JSON。
仓库目录:
alpha-analyst/
├── src/alpha_analyst/
│ ├── config.py # 集中配置(env + YAML,含 .env 支持)
│ ├── schemas.py # 跨层数据模型(Decimal 金额 + Source 溯源)
│ ├── data/ # Provider / 注册表 / 缓存 / fixtures
│ ├── core/ # DCF / comps / 引用纪律 / 格式化(纯逻辑)
│ ├── agents/ # 数据 agent + 恶魔代言人 + 合成器 + MockLLM
│ ├── orchestrator/ # 流水线编排(依赖注入)
│ ├── report/ # Markdown / JSON 渲染
│ └── __main__.py # CLI:research / audit / sources
├── configs/ # sources.yaml(数据源 + CIK)/ models.yaml
├── scripts/fetch_fixtures.py
├── examples/ # 离线 demo 产物 + fixture 清单
├── tests/ # 离线测试(respx 拦截全部网络)
└── docs/assets/hero.svg
- 离线 demo 备忘(
ALPHA_DATA_MODE=offline ALPHA_LLM_MODE=mock产出):examples/offline-demo/AAPL_memo.md - 结构化运行 JSON:
examples/offline-demo/AAPL_run.json - fixture 清单(逐条注明来源与 live / derived / sample):
examples/fixture-manifest.json
| 文档 | 内容 |
|---|---|
CHANGELOG.md |
版本变更、架构重构要点与上游 commit 记录 |
configs/sources.yaml |
数据集 → provider 映射、SEC CIK 表 |
configs/models.yaml |
LLM 任务 → 模型映射(litellm 模式) |
.env.example |
全部环境变量与说明 |
tests/ |
135 条离线测试:DCF/comps/引用纪律/数据层/CLI 的口径即文档 |
本项目为研究与工程示范,不构成任何投资建议。数据来自公开接口(SEC、Yahoo、FRED、Google News),准确性以官方来源为准;sample 数据仅用于演示链路。
Apache-2.0 · 数字可追溯,观点可辩论。
本项目基于开源项目 AlphaAnalyst(Apache-2.0)重构与增强。