一、项目定位与核心目标

claude-investment-skills 是一个面向 Claude Code 的自托管投资分析技能集(Skills Collection),核心目标是将 SEC(美国证券交易委员会)公开披露文件——主要是 Form 8-K(重大事项报告)与 SC 13D(5% 以上主动持股变动报告)——中蕴含的战略合作信号结构化、自动化地推送到个人投资者的 Telegram 客户端,从而将传统的"彭博终端 → 卖方研报 → Substack → 散户"信息链条压缩为"SEC 9:00 AM 备案 → Bot 9:30 AM 推送"的端到端通道 资料来源:strategic-partner-firehose/README.md:1-15。

整套体系以 strategic-partner-firehose(战略合作 firehose)为旗舰模块,并以 SEC EDGAR 公共接口作为唯一外部数据源。README 通过 CoreWeave(CRWV)案例将价值主张具象化:从 2025-03-31 的 8-K Item 1.01+3.02(OpenAI 以战略股权方式入股 3.5 亿美元)到 2025-06-30 涨幅 +367%,全程均可被本套件机械化捕捉,而无需依赖 Twitter、Substack 等二手解读 资料来源:strategic-partner-firehose/README.md:17-30。

二、整体架构与双路径检测

项目在 v2.4 引入双路径并行检测(Dual-Path Detection)架构,以克服"超大规模云厂商隐去客户名"导致的传统关键词扫描盲区 资料来源:strategic-partner-firehose/README.md:32-50。

flowchart LR
    EDGAR[SEC EDGAR<br/>8-K + 13D] --> Parser[parsers.py<br/>正则提取]
    Parser --> PathA{Path A<br/>注册表匹配}
    Parser --> PathB{Path B<br/>主题分类器}
    PathA -- 命中 Tier-1/2/Sovereign --> AlertA[🤝 STRATEGIC<br/>PARTNER INVESTMENT]
    PathB -- theme_score ≥ 6 --> AlertB[🏭 AI INFRASTRUCTURE<br/>SIGNAL]
    AlertA --> Composite[composite.py<br/>30 天内同 ticker]
    AlertB --> Composite
    Composite -- 双 firehose 同发 --> Mega[🚨🚨🚨 MEGA SIGNAL]
    AlertA --> TG[Telegram Bot]
    AlertB --> TG
    Mega --> TG

• 路径 A(Registry-based):当 8-K 中出现 investor_registry.py 维护的 TIER-1(NVIDIA、Microsoft、Alphabet、Amazon、Meta、Apple、Oracle、SK Telecom、SK Hynix、Samsung、TSMC、SoftBank、ASML 等)、TIER-2(Intel Capital、Qualcomm Ventures 等)、Sovereign(MGX、Mubadala、Saudi PIF、Temasek、GIC、CPPIB)、Smart-VC(a16z、Lux、Sequoia、Founders Fund、Khosla、Coatue、Tiger Global)等实体时,直接触发 🤝 STRATEGIC PARTNER INVESTMENT 告警 资料来源:strategic-partner-firehose/README.md:52-72。
• 路径 B(Theme Classifier):对正文进行 7 个 AI/数据中心关键词类别(核心 AI、数据中心、电力、能源、规模、合同类型、首选供应商)的 0-10 打分,score ≥ 6 触发 🏭 AI INFRASTRUCTURE SIGNAL,用于捕获 POWL(2026 年 5 月 4 亿美元匿名超大规模订单)等隐去客户名的案例 资料来源:strategic-partner-firehose/README.md:74-95。
• 复合信号(MEGA SIGNAL):由 scripts/composite.py 实现,30 天内 insider-firehose(Form 4 内部人买入)与本模块对同一 ticker 同时触发时,输出最强等级告警,1 个 ticker 每 24h 至多 1 次 资料来源:strategic-partner-firehose/README.md:97-115。

三、安装与运行方式

3.1 一次性设置(One-time Setup)

1. Fork 仓库:在 GitHub 上 fork claude-investment-skills 到个人账号下,所有数据处理均在自有 fork 中完成,满足"自托管"原则 资料来源:strategic-partner-firehose/README.md:140-150。
2. Telegram Bot 凭据:在仓库 Settings → Secrets 中配置 TELEGRAM_BOT_TOKEN 与 TELEGRAM_CHAT_ID,两个 firehose 共享同一机器人;详细步骤参见 price-alert/SETUP.md 资料来源:strategic-partner-firehose/README.md:142-150。
3. 启用 GitHub Actions:在 Actions 页面启用 "Strategic Partner Firehose (8-K + 13D Real-Time)" workflow,调度为美东工作日 9:00-19:30 每 30 分钟一次,与 insider-firehose 同频以便复合检测在同一 tick 内完成 资料来源:strategic-partner-firehose/README.md:152-160。

3.2 本地开发与回测

仓库根目录提供 setup.sh 一键脚本,主语言为 Python 3.x(仅依赖标准库 requests/json),测试入口为 strategic-partner-firehose/scripts/tests/test_all.py(32 个单元用例,全部运行 22ms,无网络调用) 资料来源:strategic-partner-firehose/README.md:165-180。price-alert 告警回执则由 Cloudflare Workers 接收,通过 wrangler deploy 部署 资料来源:price-alert/webhook/package.json:1-14。

四、前置依赖清单

资料来源:price-alert/webhook/package.json:1-14 与 strategic-partner-firehose/README.md:140-160。

五、限制与未覆盖范围

当前版本(v2.4,发布日期 2026-05-12)未覆盖以下场景: S-1 IPO 招股说明书(v2.4 计划中,本可提前捕捉 CRWV)、外国发行人 F-1/20-F、非美国交易所(HKEX / LSE / JPX)、SPAC 与加密资产 IPO 资料来源:strategic-partner-firehose/README.md:185-200。金额提取采用保守正则,正文中将表格中"the Investment"等模糊表述视为未触发,可能漏报但不会误报 资料来源:strategic-partner-firehose/README.md:170-180。

参见

• 双路径检测与告警分级
• 复合信号与 insider-firehose 联动
• SEC 8-K / SC 13D 字段参考

总体架构与设计目标

本仓库 claude-investment-skills 由一组自治（self-hosted）的金融监测"Firehose"组成，运行于 GitHub Actions 之上，并以 Telegram 作为统一告警通道。其核心目标是在零售投资者接收到 Substack、Twitter 解读之前，从 SEC EDGAR 公开文件中直接捕获"战略合作 / 内部人买入"等高 α 信号。

整体系统采用 双 Firehose + 复合检测层 + 单输出通道 的三层拓扑：两个并行 Firehose 分别为 strategic-partner-firehose（8-K + SC 13D）与 insider-firehose（Form 4），二者在 cron 节奏上对齐（每 30 分钟一次）以便复合信号（composite.py）可在同一时间窗内交叉比对 30 天内的同标的告警。资料来源：strategic-partner-firehose/README.md:182-198

flowchart LR
    A[SEC EDGAR<br/>8-K / SC 13D / Form 4] --> B[partner_firehose.py<br/>cron 30min]
    A --> C[insider_firehose.py<br/>cron 30min]
    B --> D[investor_registry.py<br/>Path A: 注册表匹配]
    B --> E[classifier.py<br/>Path B: 主题评分 ≥6]
    D --> F[filters.py<br/>mcap + US + amount]
    E --> F
    F --> G[recent_alerts.json<br/>90天保留]
    C --> G
    G --> H[composite.py<br/>同标的 30天 MEGA]
    H --> I[Cloudflare Worker<br/>webhook 包]
    I --> J[Telegram Bot]

数据源层：SEC EDGAR

系统唯一外部数据源是 SEC EDGAR（公开、免费、机器可读），覆盖以下五种文件类型：

资料来源：strategic-partner-firehose/README.md:62-78

设计上明确不覆盖 S-1 招股书（v2.4 计划加入）、HKEX/LSE/JPX 等外国上市、F-1/20-F 外国私人发行人、SPAC 与加密 IPO。资料来源：strategic-partner-firehose/README.md:236-242

组件拓扑与处理流水线

strategic-partner-firehose 子目录内组件按职责分层：

• 入口：scripts/partner_firehose.py（cron 触发的主入口）
• 解析：scripts/parsers.py（8-K + 13D 正则提取器）
• 注册表：scripts/investor_registry.py（Tier-1 / Tier-2 / SOVEREIGN / SMART_VC 投资者名单及其 2-5 个 SEC 别名变体）
• 过滤：scripts/filters.py（市值 + 美股上市 + 金额三层过滤）
• 评分：scripts/analysis.py（CLI 版 0-10 Partner Score）
• 主题分类：scripts/classifier.py（v2.4 引入，7 个关键词类别的 0-10 主题评分）
• 复合：scripts/composite.py（跨 Firehose 的 MEGA SIGNAL 检测器）
• 状态：strategic_state.json（accession 查重）、recent_alerts.json（90 天告警日志）、composite_state.json（24h 复合告警查重）

资料来源：strategic-partner-firehose/README.md:7-24、:96-116

两条独立检测路径并行运行：Path A 由注册表捕获具名投资者交易（PENG/SK Telecom、CRWV/OpenAI），Path B 由主题评分 ≥6 捕获匿名超大规模客户（POWL、BE、GEV）。任一路径触发即发告警，两条同时触发则告警附 theme_primary/theme_categories 主题标签。资料来源：strategic-partner-firehose/README.md:42-56

跨 Firehose 复合信号与告警输出

composite.py 实现跨 Firehose 的交叉验证：当 strategic-partner-firehose 与 insider-firehose 在同一 ticker 的 30 天窗口内均产生告警时，输出 🚨🚨🚨 MEGA SIGNAL 级别的复合告警，且以 24h/ticker 节流去重。该复合信号在全部 Firehose 告警中占比 <1%，但被仓库定位为"整个工具箱中最强的信号"。资料来源：strategic-partner-firehose/README.md:180-198

告警推送通道由 price-alert/webhook/ 提供：其 package.json 声明一个 Cloudflare Worker（wrangler dev/deploy/tail 脚本），负责接收 Telegram Bot 的 webhook 回调，从而将 JSON 状态写入与告警分发解耦。资料来源：price-alert/webhook/package.json

See Also

• strategic-partner-firehose/SKILL.md — Claude Code 自然语言触发描述
• insider-firehose — Form 4 兄弟 Firehose
• price-alert/SETUP.md — 5 分钟安装指引（Telegram Bot Token 配置）

系统定位与价值主张

火线监控的目标是用最低成本、零授权的途径捕获"上市公司真实发生的事件"，跳过 Substack、Twitter 等二级信息源。README.md 用 CoreWeave（CRWV）作为反推案例：2025-03-31 的 8-K Item 1.01+3.02 已披露 OpenAI 战略入股信号，遵循该火线可在 $40-48 区间得到买入提醒，三个月后股价触及 $187 阶段高点（资料来源：strategic-partner-firehose/README.md:1-30）。整套系统以 GitHub Actions 定时轮询执行，30 分钟一次的节拍与 insider-firehose 对齐，便于后续复合判定；其它配套技能包括 analyze-stock、option-wall-analysis、macro-warning、tax-optimize（资料来源：strategic-partner-firehose/README.md:120-145）。

双通道检测架构

为解决"超大规模客户常以匿名方式出现在 8-K 中"的痛点，v2.4 引入并行双通道：

flowchart LR
  A[SEC EDGAR 8-K / SC 13D] --> B{通道 A<br/>注册表匹配}
  A --> C{通道 B<br/>主题分类器<br/>classifier.py}
  B -->|命中投资者| D[🤝 STRATEGIC PARTNER<br/>0-10 Partner Score]
  C -->|theme_score ≥ 6| E[🏭 AI INFRASTRUCTURE SIGNAL]
  D --> F{复合判定<br/>composite.py}
  E --> F
  F -->|同 ticker 30 天内<br/>insider 买入| G[🚨🚨🚨 MEGA SIGNAL]
  F --> H[Telegram 推送]

通道 A（注册表路径）：scripts/investor_registry.py 维护投资者名单，按四级加权——Tier-1（NVIDIA、Microsoft、SK Telecom 等）、Tier-2、Sovereign（MGX、PIF、Temasek）、Smart-money VC（资料来源：strategic-partner-firehose/README.md:50-72）。

通道 B（主题分类路径）：scripts/classifier.py 在 v2.4 新增，对 7 类关键词（数据中心、超大规模、AI、能源、合同体量等）做 0-10 主题打分，分数 ≥ 6 即触发"AI INFRASTRUCTURE SIGNAL"。POWL 案例显示，匿名客户加 "multi-gigawatt behind-the-meter" 文本可拿到 10/10（资料来源：strategic-partner-firehose/README.md:60-90）。

投资者分级与告警触发条件

完整实体别名（每个实体 2-5 个 SEC 备案变体）由 investor_registry.py 正则覆盖。scripts/parsers.py 抽取 8-K Item 1.01/3.02/7.01/8.02 与 SC 13D 字段，scripts/filters.py 执行"美股上市、市值 ≥ 5000 万美元、投资金额 ≥ 5000 万美元"的硬过滤（资料来源：strategic-partner-firehose/README.md:18-44）。

配套技能与部署路径

scripts/partner_firehose.py 是 cron 入口，运行时落盘三类状态文件：strategic_state.json（去重账本）、recent_alerts.json（90 天滚动告警）、composite_state.json（24 小时复合去重）。任何新告警会回查同 ticker 的 insider 记录，命中即升级为 MEGA SIGNAL；按 README.md 估算这类复合告警仅占火线告警总量 < 1%，但置信度最高（资料来源：strategic-partner-firehose/README.md:110-135）。

Telegram 通道复用 price-alert/webhook 下的 Cloudflare Worker，其 package.json 声明基于 wrangler v4 + TypeScript 5.5 + @cloudflare/workers-types，用户只需在 GitHub Secrets 配置 TELEGRAM_BOT_TOKEN 与 TELEGRAM_CHAT_ID 即可复用同一机器人。SETUP.md 提供 5 分钟接入指引，告警触发后的标准动作是 /analyze STOCK → /option-wall STOCK → 仓位 ≤ 1%（资料来源：price-alert/webhook/package.json:1-17、strategic-partner-firehose/README.md:170-195）。

局限与已声明盲区

• S-1 / F-1 / 20-F 不在覆盖范围（v2.4 计划加入 S-1）
• 美元金额抽取正则保守，可能漏掉隐藏在表格中的金额
• 引用 NVIDIA 但金额主体是回购时存在误判概率，已通过过滤管线降低
• 仓库无遥测信标，仅以 GitHub Stars/Forks/Issues 作为采用代理

参见

• 内幕交易火线：insider-firehose（同节拍运行，复合告警的数据源之一）
• 标的深挖：analyze-stock 技能
• 期权异动分析：option-wall-analysis 技能
• 宏观闸门：macro-warning 技能

部署架构总览

strategic-partner-firehose/README.md 描述了一组松耦合但相互依赖的运行时：

• GitHub Actions 定时任务：strategic-partner-firehose 与兄弟技能 insider-firehose 共享同一套 Telegram Bot，两个 workflow 在工作日 9:00–19:30 ET 区间内以 30 分钟 为节拍执行，节拍对齐是 scripts/composite.py 能在同 tick 上交叉查询的硬性前提。
• 本地状态文件：scripts/strategic_state.json 充当去重账本，recent_alerts.json 保留 90 天告警历史供 composite 引擎读取。
• Cloudflare Worker 接收端：price-alert/webhook/package.json 暴露三个标准脚本（dev / deploy / tail），处理来自 Telegram 的 webhook 回推。

flowchart LR
    EDGAR[SEC EDGAR] -- "cron 30 min" --> A[GitHub Actions<br/>strategic-partner-firehose]
    A -- "HTTPS push" --> TG[Telegram Bot API]
    TG -- "webhook" --> W[Cloudflare Worker<br/>price-alert/webhook]
    A <--> S[(strategic_state.json<br/>recent_alerts.json)]
    A <-. "composite cross-check" .-> I[insider-firehose<br/>recent_alerts.json]

Telegram Bot 与 Secrets 部署步骤

README 中 *How to use this skill* 小节给出了最小可用路径（资料来源：strategic-partner-firehose/README.md）：

1. 创建 Bot：按 price-alert/SETUP.md 走一次，拿到 TELEGRAM_BOT_TOKEN 与目标 TELEGRAM_CHAT_ID。
2. 注入 Secrets：在 fork 仓库的 Settings → Secrets and variables → Actions 中分别新增上述两个变量。README 原话 "Set TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID as GitHub Secrets"。
3. 启用 Workflow：在 GitHub Actions 标签页找到 *Strategic Partner Firehose (8-K + 13D Real-Time)* 并点击 Enable。
4. 保持双 firehose 同步：composite.py 需要双方同时活跃；单边启用时，README 所述的 MEGA SIGNAL 路径将永远不会触发。

可选：若希望本地或私有云运行，可直接克隆仓库并执行 python scripts/partner_firehose.py，此时仍需从环境变量提供 Telegram 凭据（README "How to use this skill"）。

Cloudflare Worker 部署要点

price-alert/webhook/package.json 显示该 worker 是私有 npm 包，依赖固定如下（资料来源：price-alert/webhook/package.json）：

• wrangler ^4.0.0
• typescript ^5.5.0
• @cloudflare/workers-types ^4.20251201.0

部署流程：

• npm install 安装依赖；
• 在 Cloudflare Dashboard 按 worker 代码所需创建 KV / 队列；
• 配置 wrangler.toml 中的 account_id、name、main 与 compatibility_date；
• npm run deploy 发布，npm run tail 拉取实时日志用于排障。

README 在 *User metrics and how to count usage* 中明确强调 "this is self-hosted"，因此 worker 端的所有可观测性数据须由运维方自行保留。

常见故障与排除

strategic-partner-firehose/README.md 在 *What could go wrong* 与 *What's NOT covered* 小节中总结了以下风险（资料来源：strategic-partner-firehose/README.md）：

• 漏报：金额抽取正则偏保守。当 8-K 把金额埋在表格中或仅以 "the Investment" 表述时，告警可能不会触发。
• 误报：罕见但存在——例如 8-K 顺带提及 NVIDIA 作为采购合作方、同时又披露 $200M 股份回购，可能被错误分类为战略投资。
• 范围限制：未覆盖 S-1 招股书（v2.4 add）、F-1 / 20-F 外国发行人、HKEX / LSE / JPX 等非美监管文件，以及 SPAC 与加密 IPO。
• Composite 不触发：多由 insider-firehose 未启用、ticker 不一致或 30 天窗口已过造成；可检查双方 recent_alerts.json 的时间戳字段定位。
• LLM 缺位：v2.4 仍以纯规则匹配为主，对模糊语义的判定能力有限；维护计划中提到 v2.4+ 可能加入 LLM 二阶段复核（README "No semantic understanding"）。

维护与可观测性

README 坦承仓库所有者仅能通过 GitHub Traffic Insights（14 天滚动窗口）、Star / Fork / Issue / PR 等公开信号粗略评估采用率；本地克隆与私有 Actions 运行时对原仓库完全不可见（README "What we cannot see"）。若需更强可观测性，建议在 fork 中：

• 周期性备份 strategic_state.json 与 recent_alerts.json；
• 对 wrangler tail 输出做归档；
• 为关键路径添加可选的运行健康检查端点（仍属自托管范围）。

未来 v2.4 可能加入 OPT-IN 计数信标（STRATEGIC_TELEMETRY_OPT_IN=1），但 README 明确说明 "We have NOT added this"，原因在于多数用户会拒绝且违背自托管理念。

See Also

• skill-strategic-partner-firehose — 技能工作原理与双路径检测
• insider-firehose 部署 — Form 4 监控的兄弟 firehose
• analyze-stock 使用指南 — 告警触发后的尽调流程
• macro-warning 速查 — 仓位决策前的宏观闸门

Pitfall Log / 踩坑日志

项目：ssurmic/claude-investment-skills

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。

1. 安全/权限坑 · 涉及密钥、隐私或敏感领域

• 严重度：high
• 证据强度：source_linked
• 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
• 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
• 证据：packet_text.keyword_scan | https://github.com/ssurmic/claude-investment-skills | matched secret / private key / privacy / trading / finance keyword

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/ssurmic/claude-investment-skills | host_targets=claude_code, claude, cursor

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ssurmic/claude-investment-skills | README/documentation is current enough for a first validation pass.

4. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/ssurmic/claude-investment-skills | matched external service / cloud / webhook / database keyword

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ssurmic/claude-investment-skills | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ssurmic/claude-investment-skills | no_demo; severity=medium

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills | release_recency=unknown