brucelanlan/augur

🇨🇳 中文 | 🇺🇸 English

⚠️ 仅供学习研究，不构成投资建议。 大师观点是基于公开投资理念的规则化模拟，不代表本人立场；所有分数、Kelly 仓位与估值都依赖数据质量和模型假设。

目录：为什么不一样 · v13 新功能 · 5 分钟上手 · 升级到 v13（含更早版本） · 18 位大师 · Dashboard · 接入 Claude / Agent · CLI 速查 · 功能成熟度 · 数据与隐私 · 开发 · 文档与路线图

---

🤔 为什么 Augur 不一样

大多数 AI 金融工具给你一个答案。Augur 给你的是可复查的研究产物。

---

✨ v13 新功能一览

下面按新用户的实际顺序走一遍：加自选 → 回填财报日期 → 跑财报周期 → 看研究产物 → 打开 Dashboard。v13 的截图都是 2026-10-29 用 AAPL / MSFT / NVDA 的真实数据（实时行情 + SEC EDGAR）运行的结果；按发布节奏推算出来的财报日期在输出和页面上都标为 estimated，不是公司公告的日期。终端截图只截取了输出的主要部分。

1. 加入自选：augur watchlist add

augur watchlist add AAPL
augur watchlist add MSFT
augur watchlist add NVDA

自选列表是财报周期的输入：augur earnings、augur cycle 和 Dashboard 的财报队列都从这里读取股票。

2. 回填财报日期：augur earnings --backfill

从 SEC 8-K（Item 2.02，业绩公告）读取每只自选股过去的财报日期，再按最近几次的发布间隔估算下一次日期，标为 estimated，不会标成"已确认"。你手工写进 /earnings_calendar.json 的条目不会被覆盖。需要联网，并设置 AUGUR_EDGAR_CONTACT_EMAIL；也可以用 -t AAPL 只回填指定股票。截图里每只股票只保留了最近几条日期，较早的日期被折叠成一行；三只股票各有一个 estimated 日期。

3. 一条命令跑完财报周期：augur cycle

对未来 N 天（默认 30 天）内要发财报的每只自选股，依次给出 dossier 就绪状态、dossier、最近两次运行之间的变化和投资论文的变化，最后汇总 ready X/Y 和每只股票的下一步该做什么。它只读本地已保存的状态，不联网；缺什么会直接写出来，并给出补齐的命令。截图用 --days 120 把三只股票的估算日期都纳入窗口；当时三只都还没就绪（缺上一季 guidance 记录和 SEC 证据，MSFT / NVDA 还没有保存的运行），所以汇总是 ready 0/3，后面列出每只股票的下一步。

4. 研究产物：dossier、研究报告与内置 Skill

augur dossier AAPL 生成财报前 dossier；augur report from-run AAPL 基于最近一次运行生成研究报告；augur skill run 一次跑完整个研究流程。

下面这几张截图是 2026-09-17 对 AAPL 的真实运行。此后这些命令的输出格式没有改动，所以沿用原图。

augur skill run earnings-prep AAPL：18 位大师的共识，分歧点逐条引用证据 ID，没有证据支撑的分歧单独标成"evidence gap"，并和上一次运行做对比。下次财报日期取自本地财报日历（可以用上一步的 --backfill 填充），会注明是 confirmed 还是 estimated；日历里没有记录时直接说明，不猜。执行前，执行器先检查每一步要用的能力、网络域名和本地资源是否都在清单里声明过，任何一项不通过都不会开始执行；每次执行存为 RunBundle，可以导出和复查。

augur skill run filing-delta AAPL：自动取最近两份 10-K 的 XBRL 数据，列出变化 ≥5% 的实质性项目，不需要手填 accession 号。另外还有 debt-covenant-review（杠杆与利息覆盖率）和 insider-cluster-review（Form 4 内部人集群）。详见 Skill 使用指南。

augur report from-run AAPL（截图拍摄时命令名还是 augur research-report，输出相同）：多空投票、大师在哪些维度上分歧（每条引用证据 ID，并写出什么事实能消除分歧）、大师一致的地方、缺证据的分歧，以及运行 ID、代码版本、步骤状态和证据覆盖率。

augur risk-review AAPL：对比最近两份 10-K 的风险因素章节，列出新增、删除和措辞升级的风险。基于规则匹配，措辞小改可能同时显示为"新增"和"删除"。

augur eval personas AAPL：用 augur backtest 生成的历史记录，逐个去掉某位大师，看共识 IC 变好还是变差；分数恒定、没有信息量的大师单独列出。远期收益逐日重叠，置信区间偏乐观，只能当筛查，不能直接当权重。augur eval factors 给出每位大师分数作为因子的 IC 与 t 检验。

5. Dashboard

augur serve --open 打开 http://localhost:8000。以下截图同样是 2026-10-29 用 AAPL / MSFT / NVDA 真实数据拍摄。

首页：行情和大师概览。侧边栏分为 研究 / 大师 / 工具 / 系统 四组。

/earnings：财报队列，和 augur earnings 读同一份自选与财报日历。每只股票列出 dossier 还缺哪些项，以及补齐每一项的命令；估算出来的日期标为 estimated。

/scorecard：财报后记分卡，对照财报前后两次运行各回答了哪些研究问题。数据不够时显示 unavailable 和原因，不填假内容。截图里就是这种状态：目前 Dashboard 还没有保存"财报前 / 财报后"运行配对的地方，所以还不能生成真正的记分卡（命令行的 augur scorecard 可以用已回答的研究问题做对照）。

/thesis：记录投资论文的催化剂、风险和证伪条件，旁边是待回答的研究问题和决策日志。研究问题保存在本地，augur dossier 也能读到。截图里的论文和问题是拍摄时手工录入的示例，不是研究结论。

/valuation：两阶段 DCF，改动输入即时重算，给出牛 / 基准 / 熊三情景和概率加权公允价值，页面下方还有 WACC × 永续增长率敏感度网格。截图里的参数是示例输入，不是估值结论。

---

🚀 5 分钟上手

需要 Python 3.10+。

git clone https://github.com/BruceLanLan/augur.git && cd augur
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[data]"            # 核心 + yfinance 实时数据
# 可选：pip install -e ".[data,mcp]"  MCP server
#       pip install -e ".[export]"    PDF 导出

# SEC EDGAR 要求请求里带真实联系邮箱（用于美股财报数据）
export AUGUR_EDGAR_CONTACT_EMAIL="[email protected]"

Dashboard：

augur serve --open                 # http://localhost:8000 · ⌘K 命令面板

命令行研究闭环（以下命令均在全新安装上实测通过）：

augur analyze AAPL                 # 18 位大师同时分析 + 加权共识 + Kelly 仓位
augur workflow AAPL                # 带追踪的流水线，保存 RunBundle，末尾打印 Run ID
augur report from-run AAPL         # 基于最近一次运行：共识、分歧图、来源信息
augur export AAPL --format md      # 导出最近一次运行（md / json / evidence-pack / pdf）
augur committee AAPL --preset value -q "护城河是在变宽还是变窄？"
augur valuation AAPL               # 两阶段 DCF，自动取 FCF/股本/净负债并注明来源
augur skill run earnings-prep AAPL # 内置研究 Skill：财报前 dossier（另有 filing-delta 等 3 个）
augur watchlist add AAPL           # 加入自选
augur earnings --backfill          # 从 SEC 8-K 回填自选股的财报日期（需联网）
augur cycle                        # 自选股的财报周期一览：谁准备好了、缺什么、下一步做什么

没有网络？augur analyze NVDA --pe 60 --roe 0.45 可以手动传指标；augur backtest AAPL --demo 使用离线合成数据。augur cycle 只读本地状态，不联网。

---

🔄 从 v12 升级到 v13

v13 是一次清理加一个新功能。不兼容的地方只有下面三项，都在 import 层面，命令行用法不变。

新功能：augur earnings --backfill 从 SEC 8-K（Item 2.02 业绩公告）回填自选股的历史财报日期，并按最近的发布节奏估算下一次日期，标为 estimated，不会标成"已确认"。你手工写进日历的条目会保留。回填之后 augur cycle 就有事件可跑了。

---

🎭 18 位投资大师

规则化实现的投资理念画像，覆盖价值 / 成长 / 宏观 / 中国市场。中国大师输出中文。

共识引擎按置信度、数据覆盖度和行业相关性加权，给出信号、分数、置信度和 Kelly 仓位建议。augur list-personas 查看全部 ID。

---

📊 Dashboard

augur serve 启动后访问 http://localhost:8000。

---

🔌 接入 Claude / Agent

MCP server 提供 14 个工具（含 augur_run_skill 执行内置 Skill）、7 个研究 prompt、5 类只读资源（augur://evidence/{id}、augur://runs/{id}、augur://thesis/{id}、augur://decisions/{id}、augur://ledger/{ticker}/{quarter}），在 mcp 1.x 与 2.x 下都经过真实 stdio 会话验证。

pip install -e ".[data,mcp]"

Claude Desktop 配置示例：

{
  "mcpServers": {
    "augur": { "command": "augur-mcp", "env": { "AUGUR_EDGAR_CONTACT_EMAIL": "[email protected]" } }
  }
}

另有 Hermes / OpenClaw 技能包（src/skills/，见 docs/hermes-setup-guide.md）以及 Telegram / Slack / 飞书 / 微信机器人入口。

---

💻 CLI 速查

# 分析
augur analyze AAPL [--persona buffett] [--json]
augur workflow TSLA --steps fetch,analyze,consensus,committee,debate,sentiment
augur committee NVDA --agents buffett,munger,dalio
augur batch AAPL MSFT NVDA

# 研究产物
augur report from-run AAPL [--format json]    # 共识 + 证据化分歧图 + 来源与耗时
augur export AAPL --format md|json|evidence-pack|pdf [-o 路径] [--run-id ...]
augur records verify-pack pack.zip              # 校验证据包每个文件的 SHA-256
augur dossier AAPL                              # 财报前 dossier
augur valuation AAPL [--fcf 100e9 --shares 15e9 --growth 0.08 --wacc 0.10]
augur risk-review AAPL                          # 最近两份 10-K 的风险因素新增/删除/措辞升级
augur records ledger AAPL                       # 最近两次分析运行之间变了什么
augur thesis-delta AAPL                         # 当前有效论点 vs 最近两次运行（离线）
augur scorecard AAPL [--pre RUN --post RUN]     # 财报后记分卡：研究问题的事前回答 vs 事后结果
augur cycle [--days 30] [--format markdown]     # 观察列表跑一遍财报研究闭环：就绪度/dossier/ledger/论点变化
augur filing-delta AAPL --new q3.json --prev q2.json

# 内置研究 Skill（执行前检查权限，结果存为 RunBundle）
augur skill list · augur skill show filing-delta
augur skill run earnings-prep|filing-delta|debt-covenant-review|insider-cluster-review AAPL

# 评估（基于 augur backtest 生成的回测记录）
augur backtest AAPL --days 120 [--demo] · augur eval ic
augur eval personas AAPL [--horizon 20]         # 共识 IC、命中率、逐个剔除大师的边际贡献
augur eval factors AAPL                         # 每位大师分数作为因子的 IC、t 值、p 值

# 研究记录
augur records decisions list|resolve|report     # 决策结果与胜率
augur records comments add|list|resolve         # 对运行 / 论点 / 决策 / 证据的评论
augur records citations report|list|accept|reject|fixed # 引用纠错队列
augur records audit [--action ...]              # 审计日志

# 数据
augur fetch AAPL · augur sentiment AAPL · augur insider AAPL · augur earnings --days 30 · augur doctor
augur earnings --backfill          # 从 SEC 8-K Item 2.02 回填财报日历：历史日期 + 一个按节奏估算的下次日期（标 estimated，不覆盖手写条目）

# 监控与服务
augur watchlist add AAPL · augur watchlist show · augur watchlist watch AAPL NVDA --interval 60
augur cron run · augur cron start
augur serve [--port 8000] · augur mcp-server · augur skill profiles · augur skill compat

augur --help 列出全部 38 个顶层命令（pip 安装时隐藏 augur update，是 37 个）。从 v12.2 起相关命令按组归类（watchlist / cron / report / records / eval / skill）；旧的平铺名（如 watchlist-add、research-report、ic-report、ledger）在下一个大版本前仍可用，不出现在 --help 里，执行时会在 stderr 打印一行新写法提示。augur report AAPL 用法不变，等同于 augur report run AAPL。

---

🧭 功能成熟度

如实标注，避免把"有代码"当成"能用"。

---

🔒 数据与隐私

• 所有状态保存在本地数据目录（默认 ~/.augur，AUGUR_DATA_DIR 可改）。没有遥测；默认单用户、无需注册（可选开启多用户模式 AUGUR_MULTI_USER=1）。
• 会发出的网络请求：行情与基本面（yfinance、SEC EDGAR）；可选的 LLM 调用（仅在你配置 API key 并启用相关功能时）；Dashboard 页面从 jsDelivr CDN 加载 Chart.js。
• Dashboard 默认只监听本机。需要对外暴露时先设 AUGUR_API_TOKEN，详见 docs/self-hosted-guide.md。

主要环境变量：

---

🔧 开发

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,data,mcp]" "ruff>=0.16,<0.17" build

make verify     # 一条命令：全量测试 + ruff + 构建 wheel/sdist 并输出 sha256
make lint       # ruff（规则集固定为 E4/E7/E9/F）
make test-wheel # 在全新虚拟环境里安装构建产物并做冒烟检查

• 测试使用独立的临时 AUGUR_DATA_DIR，不会写入你的 ~/.augur；在完全断网的环境下也能全部通过。
• CI（.github/workflows/）：Tests 在 Python 3.10 / 3.11 / 3.12 上跑全量测试并断言收集数；Hermetic Smoke 从 wheel 和 sdist 分别全新安装并跑 ruff 与 pip-audit。
• 贡献方式见 CONTRIBUTING.md。

---

📚 文档与路线图

---

📝 更新日志

---