capitol-alpha-terminal

# 国会阿尔法终端（TradePoli） 一个类似彭博终端的仪表板 + MCP 服务器，用于跟踪 **公开披露** 的美国政客股票交易（STOCK 法案备案），对谁值得复制进行排名，通过实盘退出测试每位政客，并可以通过 Alpaca 在严格的安全模型下自动复制选择的政客。 > ⚠️ **这不是内幕数据。** 国会交易披露是公开备案，可能在交易后 **45 天** 才会到达。披露金额为范围，而不是确切大小。这里的一切都是延迟研究数据，而不是财务建议。 **亮点** - 实时交易大厅指挥中心：滚动的市场行情显示，自动刷新 **LIVE FILINGS** 源，具有一键“是否仍然可行？”筛选，30 天国会资金流动板，带有共识检测，以及交互式强制 **交易网络** （每位政客都与其交易的股票相连；可缩放、平移、拖动、点击通过）。 - 每只股票的交易视图：1 年价格图表，每笔国会买入/卖出都在政客实际交易日期绘制。 - **基于真实行为** 的回测：交易日期或备案日期进入，实际披露销售退出，最佳持有扫描，延迟成本比较，以及最佳交易板块（每位政客的最佳交易，附带“备案 +Nd”收据）。 - 按 **复制分数** 排名的排行榜（置信度调整后的今日跟随价值，惩罚延迟备案者和错过退出者）。 - **关注一位政客**：在您的规则下自动复制其备案的每笔买入（权益、最大持有、最大并发、最大接受延迟），并根据其真实记录提供数据驱动的建议。默认干预，退出优先，硬上限，显式确认后启动。 - MCP 服务器，允许 Claude（或任何 MCP 客户端）查询交易、运行回测并生成每日简报。 想从头开始构建自己的版本？请参阅 **[workbook.md](workbook.md)** （设置工作簿 + 完整的构建提示）和 **[docs/REBUILD_SPEC.md](docs/REBUILD_SPEC.md)** （完整的规格）。 ## 内部 ``` apps/ dashboard/ Next.js 15 仪表板（暗色交易终端 UI） mcp-server/ MCP 服务器（stdio + HTTP）和摄取工作器 packages/ shared/ 共享 TypeScript 类型，新鲜度标签，免责声明 db/ Drizzle ORM 模式 + 查询层（PostgreSQL） scoring/ 备案延迟，金额范围，去重哈希，警报评分（0-100） ingestion/ Quiver 适配器，CSV 导入，Yahoo 市场数据，警报管道 ai/ Anthropic 摘要/简报/YouTube 片段 + 法律护栏 tests/ 集成测试（管道，MCP 工具，REST API） ``` ## 先决条件 - Node.js 20+（测试于 22） - 本地运行 PostgreSQL（`.env` 中的 `DATABASE_URL`） - API 密钥（参见 `.env.example`）：Quiver Quantitative（需要实时数据），Anthropic（需要 AI 功能；如果没有，则回退到模板） ## 使用 AI 设置（推荐） 克隆存储库，用 AI 编码代理（Claude Code，Cursor 等）打开它，并粘贴： > 在此存储库中阅读 ONBOARDING.md 并使我具备条件。检查我的先决条件，询问我清单中的 API 密钥（我将粘贴它们），创建我的 `.env`，运行设置，然后启动网络服务器并确认仪表板在 localhost:3000 加载。 代理将引导您完成所有操作：先决条件，密钥，数据库，一年的数据和启动。有关它将执行的操作，请参阅 [ONBOARDING.md](ONBOARDING.md)。 ## 手动设置（一步到位） ```bash npm run setup ``` `npm run setup` 是幂等的，它会完成所有事情：检查 Node/Postgres，安装依赖项，创建 `.env`（如果丢失，则从 `.env.example` 默认数据库用户为您的 OS 用户），创建 `tradepoli` 数据库，应用模式，播种默认值，从 Quiver 拉取约 1 年的备案并预计算排行榜。您可以多次运行它；它只会执行缺少的操作。 **首次运行：** 如果还没有 `.env`，则设置会创建它并停止，以便您可以粘贴 API 密钥（至少 `QUIVER_API_KEY` 和 `ANTHROPIC_API_KEY`），然后再次运行 `npm run setup`。 <details> <summary>手动步骤（设置背后执行的操作）</summary> ```bash npm install # 安装所有工作区 cp .env.example .env # 填写 DATABASE_URL, QUIVER_API_KEY, ANTHROPIC_API_KEY psql -c "CREATE DATABASE tradepoli;" # 或：createdb tradepoli npm run db:push # 创建表 npm run db:seed # 播种示例数据 + 默认设置 npm run ingest -- --since 2025-07-01 --limit 25000 # 约 1 年的备案 npm run leaderboards # 预计算 30/60/90/365 天排行榜 ``` </details> ## 移动到另一台计算机 存储库包含代码；有两样东西 **不** 会传输并且必须重新创建：您的 `.env`（密钥，gitignored）和本地 Postgres 数据（从 Quiver 重新生成）。 **选项 A · 复制文件夹** （最简单，保留您的 `.env`）： 1. 将整个 `tradepoli/` 文件夹复制到新机器（USB，云驱动器，`rsync`）。跳过 `node_modules/` 和 `.next/` 如果可以（它们会重建）。 2. 安装 Node 20+ 和 Postgres，然后启动 Postgres。 3. `npm run setup` （它重用复制的 `.env`；从头重建 `node_modules` 和数据库）。 4. `npm run dev`。 **选项 B · git** （推荐）： ```bash # 在新机器上： git clone https://github.com/daviddme/capitol-alpha-terminal.git tradepoli && cd tradepoli npm run setup # 创建 .env 从 .env.example，然后停止 # 将您的 QUIVER_API_KEY + ANTHROPIC_API_KEY（和其他）粘贴到 .env npm run setup # 完成：DB，摄取，排行榜 npm run dev ``` > `.env` 故意被 gitignore（它包含密钥），因此使用 git 时您在新机器上重新输入密钥。保持您的密钥安全（密码管理器）；`.env.example` 列出每个变量。 无论哪种方式，第一次 `npm run dev` 也会触发工作器为任何剩余的缓存（最佳交易，最佳持有扫描）预热，因此请给它几分钟时间，然后这些页面就会完全填充。 ### 使用 Claude Code 在新机器上继续 两个上下文源让 Claude 可以从上次中断的地方继续： - **[docs/PLATFORM.md](docs/PLATFORM.md)** 随存储库一起提供，是一个持久的设计记录（每个引擎，页面，发现和限制）。首先在新机器上指向它。 - **Claude Code 的项目内存** 生活在存储库外部的 `~/.claude/projects/<project-hash>/memory/`。它不会随着 git 或文件夹复制而传输。要保留累积的笔记，请将该 `memory/` 文件夹复制到新机器上的相同路径（哈希值根据存储库的绝对路径派生，因此请将存储库放在一个可比较的位置，或者让 Claude 从 PLATFORM.md 重新构建上下文）。 - 存储库提供 `.mcp.json`，因此此文件夹中的 Claude Code 自动连接到 `political-trades` MCP 服务器，启动 `npm run dev`（或_stdio_服务器）。 ## 运行 ```bash npm run dev ``` 启动三个进程： - **仪表板** → http://localhost:3000 - **MCP 服务器（HTTP）** → http://localhost:8787/mcp - **工作器** → 每 6 小时摄取 Quiver 数据，每小时重新评分，AI 摘要用于热门交易 ### 将 Claude 连接到 MCP 服务器 ```bash # stdio（推荐；此存储库中的 .mcp.json 自动使用） claude mcp add political-trades -- npx tsx apps/mcp-server/src/stdio.ts # 或 HTTP（在 npm run dev 运行的情况下） claude mcp add --transport http political-trades http://localhost:8787/mcp ``` 然后询问 Claude 类似的问题： *"今日最新的政客交易是什么？"* 或 *"以 YouTube 模式生成今日的每日简报。"* ### MCP 工具 `get_latest_trades`，`search_trades`，`get_politician_profile`，`rank_politicians`，`get_ticker_activity`，`get_alerts`，`generate_daily_briefing`，`create_experiment`，`add_trade_to_experiment`，`generate_youtube_segment`，`manage_watchlist`，`summarize_trade`，`backtest_politician`，`backtest_leaderboard`，`screen_trade`，`get_golden_opportunities`，`autotrade_status` 资源：`political-trades://latest`，`://alerts`，`://watchlist`，`://experiments`，`://daily-briefing`，`://schema` ## 测试 ```bash npm test ``` 106 个测试：单元测试（延迟计算，金额范围，去重哈希，警报评分，回测引擎，筛选分类，AI 护栏）+ 集成测试对抗真实的本地 Postgres（摄取管道，存储的排行榜，自动交易决策管道及其安全不变性，跟随，退出信号，所有 MCP 工具超过真实的客户端/服务器对，REST API 对开发服务器）。 ## 环境变量 参见 `.env.example`。主要变量： | 变量 | 用途 | |---|---| | `DATABASE_URL` | PostgreSQL 连接 | | `QUIVER_API_KEY` | 国会交易实时数据（批量端点） | | `ANTHROPIC_API_KEY` | AI 摘要，简报，控制台，YouTube 片段 | | `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` | 推送警报（给机器人发消息，然后设置聊天 ID） | | `DISCORD_WEBHOOK_URL` / `SLACK_WEBHOOK_URL` | 可选警报通道 | 市场数据是来自非官方的 Yahoo Finance（无密钥，仅限 MVP）。请替换为 Polygon/Tiingo 以进行生产使用。 ## 警报评分 `score = freshness + size + watchlist + cluster + politician - stalePenalty`，限制在 0-100。 新鲜度标签：0-7 天新鲜，8-14 天近期，15-30 天延迟，31-45 天非常延迟，45 天以上过期。 ## 回测（10,000 美元挑战，模拟） 回测页面（F5）模拟复制任何政客披露的买入，账户为 10,000 美元：等额仓位，入场为公开备案后的首次收盘，退场为披露卖出或配置的持有期。您将获得与 SPY 的权益曲线，每个交易绘制一张胜/亏报表，以及延迟比较图表（进入 +0 / +10 / +27 天后每个备案），显示边缘衰减的速度。排行榜对 10 个最活跃的政客运行相同的模拟，并按模拟回报排名。 ```bash npm run backtest -- --politician "Ro Khanna" --lookback 365 --hold 30 --delay 0 ``` 价格历史记录按股票代码缓存在 Postgres（`price_history`）；每日结果缓存在 `backtest_cache`。模拟忽略费用，滑点和股息，并使用非官方的 Yahoo 收盘价。仅用于研究。 ## 排行榜（30/60/90 天，每位政客） 排行榜页面（F6）对窗口中每位披露交易且可交易的政客进行相同的 10,000 美元模拟：相同的起始权益，相同的 1,000 美元仓位大小，相同的入场规则。 30、60 和 90 天的选项卡，政客的权益曲线火花图，以及完整的“如果您复制前 5 名”组合投资组合图表（一个 10,000 美元账户跟随所有 5 名）。前 5 名是事后选择的，因此该图表明确标记为最看涨的情景。 命令中心显示前 5 名预览和组合曲线。 板块每天由工作器（07:15）重新计算，并按需计算： ```bash npm run leaderboards ``` MCP 工具：`get_full_leaderboard`（periodDays：30 | 60 | 90）。 API：`GET /api/leaderboard?period=30`. ## 他们实际的持有期（回测页面） 销售也被披露，因此分析器 FIFO 匹配每个政客的销售备案与其之前购买的相同股票代码（按交易日期）以衡量他们实际的持有行为：中位数/平均持有，分布直方图，以及有多少购买没有披露退出。 退出场景图表包括“他们实际的退出”（跟随他们的销售备案，无时间限制）以及固定持有变体，回测器有退出模式选择器：他们的销售 + 最大持有（默认），仅他们的销售，或仅固定持有。 界面中的注意事项：一个备案 = 一个批次（金额是范围），大约一半的购买没有披露退出。 ## 最佳持有分析（回测页面） 政客很少披露退出，因此回测页面扫描持有期限从 1 到 90 天，以找到边缘实际持续的时间，基于两个基准：他们何时进入（交易日期）和您何时可以进入（备案日期，包括延迟）。 它标记每个的最佳持有时间，显示 15 个最活跃的政客的中位数/平均最佳时间，并绘制三个退出场景的图表，超过相同的入口：标准的 30 天持有，固定持有最佳时间，和完美退出上限（每个仓位在窗口内以峰值收盘价出售，不可能交易，有用作为上限）。 API：`GET /api/backtest/optimal-hold/[politician]` 和 `/api/backtest/optimal-hold/aggregate`. ## 我的权益（F8） 连接 Alpaca 账户后，显示您的实际投资组合历史（1M 每日）和开放仓位。 如果没有账户，它显示一个透明的可共享模拟：一个 10,000 美元账户复制 30 天排行榜前 5 名政客，清晰标注“模拟 · 本该发生”。 也在指挥中心预览。 API：`GET /api/my-equity`. ## Alpaca 可交易性事实检查 披露数据包含无法交易的工具：国债/债券 CUSIPs（91282CGJ4），期权，市政证券，自由文本基金名称和死股票代码。 在任何订单之前进行两层检查： 1. **静态**（始终开启）：符号形状 + 披露的资产类型。 随时使用 `npm run audit:tradability` 审计数据库（目前约 98.7% 的过去 90 天通过；选项/CUSIPs/垃圾邮件失败）。 2. **实时**（当密钥存在时）：`GET /v2/assets` 每符号，缓存在 `asset_checks` 7 天。 捕获退市/重命名股票，并强制支持分数资产用于名义订单。 类别份额符号转换为 Alpaca 的点格式（LEN-B → LEN.B）。 自动交易者拒绝任何失败的符号，原因记录在决策日志中。 ## 自动化（Alpaca + AI 筛选器） 自动化页面（F11）连接 Alpaca 账户（默认为纸质交易；验证密钥后保存，AES 加密 `SECRET_ENCRYPTION_KEY` 设置）和运行新鲜备案的三阶段门槛： 1. **硬性规则**：最大备案年龄（默认为 21 天，计算延迟 + 发布时间），仅买入，关注列表过滤器，最小警报分数，每日订单上限。 2. **漂移筛查**：当前价格与政客的入场收盘价。 在 `maxDriftPct`（10%）之后，移动已经发生，交易被拒绝为 *晚期**。 在/低于 `goldenDriftPct`（2%），包括低于入场价格，这是 **黄金机会**。 3. **Claude 相关性门槛**：一个保守的结构化判决，可以否决但永远不会复活被拒绝的交易。 订单仅在达到/高于 `minAiScore` 时才会通过。 一切从 **干预** 开始：整个管道运行并记录每个决策（包括跳过原因和 AI 否决），无需触及经纪人。 转为实时交易需要启用自动交易，取消干预，**并点击显式实时确认**。 黄金机会也出现在指挥中心和 `get_golden_opportunities` / `screen_trade` / `autotrade_status` MCP 工具上。 您负责使用您的密钥下达订单；这里没有任何财务建议。 ## 实验 创建实验（例如 Preset A：$10,000，复制 30 天内备案的关注列表交易，平等权重），添加交易提醒，跟踪器记录 **您看到备案时的价格**（不是政客的入场价）。 PnL 对实时价格更新，具有 SPY / QQQ / NANC / KRUZ 基准比较和 CSV 导出。 ## 数据限制（阅读此内容后再录制） 1. 备案可能延迟 45 天；一些在 1-2 天内到达。 在 `filing_delay_days` 上进行硬性过滤。 2. 金额范围（$1,001 - $15,000 等）。仓位大小是估计值。 3. Quiver 的 `excess_return` 是他们估计的交易后表现，而不是预测。 4. Yahoo 价格是未经官方的，可能缺少奇怪的股票代码（SPCX 等）。 5. 对 NANC/KRUZ 的研究表明，复制国会不一定能可靠地击败市场风险调整后的回报。诚实的这种不确定性是故事。