institutional-flow-tracker

机构资金流向追踪器

概述

此技能通过分析 SEC 的 13F 文件，追踪机构投资者的活动，识别「聪明钱」流入和流出股票的情况。通过分析机构持仓的季度变化，你可以发现成熟投资者在股价大幅波动前正在增持的股票，或在机构减持时识别潜在风险。

关键洞察： 机构投资者（对冲基金、养老基金、共同基金）管理着数万亿美元资产，并进行广泛研究。他们集体买入和卖出的模式往往会领先重大价格变动 1-3 个季度。

前置条件

• FMP API 密钥： 设置 FMP_API_KEY 环境变量，或向脚本传入 --api-key
• Python 3.9+： 运行分析脚本所需
• 依赖项： pip install requests（脚本会妥善处理依赖项缺失的情况）

何时使用此技能

在以下情况下使用此技能：

• 验证投资想法（检查聪明钱是否认同你的论点）
• 发现新机会（寻找机构正在增持的股票）
• 评估风险（识别机构正在退出的股票）
• 监控投资组合（追踪机构对你持仓的支持情况）
• 跟踪特定投资者（追踪 Warren Buffett、Cathie Wood 等）
• 分析行业轮动（识别机构正在将资金转向何处）

请勿在以下情况下使用：

• 寻找实时日内信号（13F 数据有 45 天的报告延迟）
• 分析微型股（市值低于 1 亿美元，且机构关注度有限）
• 寻找短期交易信号（投资期限少于 3 个月）

数据来源与要求

必需：FMP API 密钥

此技能使用 Financial Modeling Prep（FMP）API 访问 13F 文件数据：

设置：

# Set environment variable (preferred)
export FMP_API_KEY=your_key_here

# Or provide when running scripts
python3 scripts/track_institutional_flow.py --api-key YOUR_KEY

FMP transport (rate limiting, single 429 retry, apikey header auth so the key never appears in a URL) is owned by the vendored generated `scripts/fmp_client.py` (Issue #495).

API 层级要求：

• 免费层级： 每天 250 次请求（足以每季度分析 20-30 只股票）
• 付费层级： 更高的请求限制，适用于大规模筛选

13F 文件提交时间表：

• 每季度提交一次，须在季度结束后 45 天内提交
• Q1（1 月至 3 月）：须在 5 月中旬前提交
• Q2（4 月至 6 月）：须在 8 月中旬前提交
• Q3（7 月至 9 月）：须在 11 月中旬前提交
• Q4（10 月至 12 月）：须在 2 月中旬前提交

分析工作流

第 1 步：识别机构持仓发生重大变化的股票

运行主要筛选脚本，查找机构活动显著的股票：

快速扫描（按机构持仓变动幅度排列的前 50 只股票）：

python3 scripts/track_institutional_flow.py \
  --top 50 \
  --min-change-percent 10

按行业筛选：

python3 scripts/track_institutional_flow.py \
  --sector Technology \
  --min-institutions 20

自定义筛选：

python3 scripts/track_institutional_flow.py \
  --min-market-cap 2000000000 \
  --min-change-percent 15 \
  --top 100 \
  --output institutional_flow_results.json

输出包括：

• 股票代码和公司名称
• 当前机构持股比例（占流通股的比例）
• 持股数量的环比变化
• 持股机构数量
• 机构数量变化（新增买家与卖家）
• 主要机构持有人

第 2 步：深入分析特定股票

如需详细分析特定股票的机构持股情况：

python3 scripts/analyze_single_stock.py AAPL

生成内容：

• 机构持股的历史趋势（8 个季度）
• 前 20 大机构持有人及其持仓变化
• 持仓集中度分析（前 10 大持有人占机构总持股的比例）
• 最大持有人中的新建仓位、增持仓位和减持仓位
• 基于数据覆盖情况的质量评估与可靠性等级

需要评估的关键指标：

• 持股比例： 机构持股比例较高（>70%）意味着更稳定，但上涨空间有限
• 持股趋势： 持股比例上升 = 看涨，持股比例下降 = 看跌
• 集中度： 集中度较高（前 10 大持有人 > 50%）时，若他们卖出则会带来风险
• 持有人质量： 是否有 Berkshire、Fidelity 等优质长期投资者，而非动量基金

步骤 3：跟踪特定机构投资者

注意：track_institution_portfolio.py 尚未实现。FMP API 按股票（而非机构）组织机构持有人数据，因此仅通过此 API 重建完整投资组合并不实际。

替代方法 — 使用 analyze_single_stock.py 检查特定机构是否持有某只股票：

# Analyze a stock and look for a specific institution in the output
python3 institutional-flow-tracker/scripts/analyze_single_stock.py AAPL
# Then search the report for "Berkshire" or "ARK" in the Top 20 holders table

如需跟踪完整的机构级投资组合，请使用以下外部资源：

1. WhaleWisdom： https://whalewisdom.com（提供免费套餐，可查看 13F 投资组合）
2. SEC EDGAR： https://www.sec.gov/cgi-bin/browse-edgar（官方 13F 文件）
3. DataRoma： https://www.dataroma.com（超级投资者投资组合跟踪器）

步骤 4：解读与行动

阅读参考资料，了解解读指南：

• references/13f_filings_guide.md - 了解 13F 数据及其局限性
• references/institutional_investor_types.md - 不同投资者类型及其策略
• references/interpretation_framework.md - 如何解读机构资金流信号

信号强度框架：

强烈看涨（考虑买入）：

• 机构持股量环比增长 >15%
• 机构数量增加 >10%
• 优质长期投资者增持
• 当前持股比例较低（<40%），仍有增长空间
• 连续多个季度出现增持

温和看涨：

• 机构持股量环比增长 5-15%
• 新买入者和卖出者并存，但净值为正
• 当前持股比例为 40-70%

中性：

• 持股量变化不大（<5%）
• 买入者和卖出者数量相近
• 机构持股基础稳定

温和看跌：

• 机构持股量环比下降 5-15%
• 卖出者多于买入者
• 持股比例较高（>80%），限制了新买入者的空间

强烈看跌（考虑卖出或避开）：

• 机构持股量环比下降 >15%
• 机构数量减少 >10%
• 优质投资者退出持仓
• 连续多个季度出现减持
• 集中度风险（最大持有人卖出大量持仓）

步骤 5：应用于投资组合

对于新建仓位：

1. 对你的选股进行机构分析
2. 寻找确认信号（机构也在增持）
3. 如果出现强烈看跌信号，重新考虑或减小仓位
4. 如果出现强烈看涨信号，可增强对投资论点的信心

对于现有持仓：

1. 在 13F 申报截止日期后进行季度审查
2. 监控减持情况（早期预警系统）
3. 如果机构正在退出，重新评估你的投资论点
4. 如果机构普遍卖出，可考虑减仓

筛选工作流集成：

1. 使用 Value Dividend Screener 或其他筛选器寻找候选标的
2. 对优先候选标的运行 Institutional Flow Tracker
3. 优先考虑机构增持的股票
4. 避开机构减持的股票

输出格式

所有分析都会生成结构化的 Markdown 报告，并保存到仓库根目录：

文件名约定： institutional_flow_analysis_<TICKER/THEME>_<DATE>.md

报告章节：

1. 执行摘要（关键发现）
2. 机构持股趋势（当前与历史对比）
3. 主要持有人及其变动
4. 新买入者与卖出者
5. 集中度分析
6. 解读与建议
7. 数据来源和时间戳

数据可靠性等级

所有分析均包含基于覆盖度的可靠性等级：

• A级： 存在可比较的上一季度数据，且该股票有 >= 50 家机构（13F）持有者。覆盖度高，可放心用于排名。
• B级： 存在可比较的上一季度数据，且该股票有 >= 10 家持有者。可供参考，但覆盖度较低。
• C级： 不存在可比较的上一季度数据（无法衡量变化），或持有者 < 10 家。不纳入筛选结果。

筛选脚本（track_institutional_flow.py）会自动排除 C 级股票。 单只股票分析脚本（analyze_single_stock.py）会显示等级并附上相应警告。

为何看覆盖度，而非逐持有者核对： 指标来自 FMP 的汇总 13F 摘要（institutional-ownership/symbol-positions-summary），该摘要会在数据源端汇总所有申报管理机构的季度环比变化。这取代了已停用的 /api/v3/institutional-holder 数据源；后者在不同季度返回的逐持有者列表不对称（例如，一个季度有 5,415 家持有者，下一季度只有 201 家），需要在客户端进行筛选，以避免百分比变化被夸大。使用经过核对的摘要后，实际仍有参考价值的质量指标就是持有广度（有多少家管理机构持有该股票），以及是否存在可用于衡量变化的上一季度数据——这正是当前等级所反映的内容。

局限性与注意事项

数据滞后：

• 13F 申报有 45 天的报告延迟
• 持仓可能已在申报日期之后发生变化
• 应将其用作确认指标，而非领先信号

覆盖范围：

• 只有管理资产超过 $100M 的机构才必须申报
• 不包括个人投资者和规模较小的基金
• 国际机构可能不会提交 13F 申报

申报规则：

• 仅申报股票多头持仓（不包括空头、期权和债券）
• 持仓数据为季度末时点快照
• 部分持仓可能属于保密信息（延迟披露）

解读：

• 相关性 ≠ 因果关系（即使机构买入，股票仍可能下跌）
• 应考虑整体市场环境和基本面
• 结合技术分析和其他技能

高级用例

内部人士 + 机构组合：

• 寻找内部人士和机构都在买入的股票
• 双方行动一致时，信号尤其有力

板块轮动检测：

• 按板块追踪机构资金流动总量
• 在轮动趋势反映到价格之前识别早期迹象

逆向投资：

• 寻找机构正在卖出的优质股票（可能具有价值）
• 需要有充分的基本面信念

验证聪明资金动向：

• 建立重要仓位前，检查聪明资金是否认同
• 增强信心或发现被忽视的风险

参考资料

references/ 文件夹包含详细指南：

• 13f_filings_guide.md - 关于 13F SEC 申报的综合指南，涵盖申报内容、报告要求和数据质量注意事项
• institutional_investor_types.md - 不同类型的机构投资者（对冲基金、共同基金、养老基金等）、其常见策略以及如何解读其操作
• interpretation_framework.md - 解读机构持股变化的详细框架、信号质量评估，以及如何与其他分析结合

脚本参数

track_institutional_flow.py

用于筛选机构持仓发生显著变化的股票的主脚本。

必需参数：

• --api-key：FMP API 密钥（或设置 FMP_API_KEY 环境变量）

可选参数：

• --top N：按机构持仓变化返回排名前 N 的股票（默认：50）
• --min-change-percent X：机构持股比例变化的最低百分比（默认：10）
• --min-market-cap X：最低市值（美元）（默认：1B）
• --sector NAME：按特定行业筛选
• --min-institutions N：机构持有者的最低数量（默认：10）
• --limit N：从筛选器获取的股票数量（默认：100）。较低的值可节省 API 调用。
• --output FILE：输出 JSON 文件路径
• --output-dir DIR：报告输出目录（默认：reports/）
• --sort-by FIELD：按 'ownership_change' 或 'institution_count_change' 排序

analyze_single_stock.py

深入分析某只股票的机构持仓情况。

必需参数：

• 股票代码（位置参数）
• --api-key：FMP API 密钥（或设置 FMP_API_KEY 环境变量）

可选参数：

• --quarters N：分析的季度数（默认：8，即 2 年）
• --output FILE：Markdown 报告输出路径
• --output-dir DIR：报告输出目录（默认：reports/）
• --compare-to TICKER：将机构持仓情况与另一只股票进行比较（未来功能）

track_institution_portfolio.py

状态：尚未实现

此脚本是一个占位脚本。它会打印替代资源（WhaleWisdom、SEC EDGAR、DataRoma），并以错误代码 1 退出。FMP API 按股票（而非机构）组织机构持有者数据，因此难以完整重建投资组合。

如需跟踪特定机构的投资组合，请使用：

1. WhaleWisdom：https://whalewisdom.com（提供免费套餐）
2. SEC EDGAR：https://www.sec.gov/cgi-bin/browse-edgar
3. DataRoma：https://www.dataroma.com

Data Quality Module (data_quality.py)

由 track_institutional_flow.py 和 analyze_single_stock.py 共用的实用程序模块：

• coverage_grade()： 根据持有者广度和上一季度数据的可用情况评定 A/B/C 级
• 最新已申报季度辅助函数（current_quarter()、iter_quarters()、quarter_end_date()）：回溯至最近一个已申报 13F 数据的季度
• normalize_holder()： 将 extract-analytics/holder 行映射为 {name, shares, change, is_new, is_sold_out}
• is_tradable_stock()： 筛除 ETF、基金和非活跃股票
• deduplicate_share_classes()： 移除 BRK-A/B、GOOG/GOOGL 等重复项

与其他技能集成

Value Dividend Screener + Institutional Flow：

1. Run Value Dividend Screener to find candidates
2. For each candidate, check institutional flow
3. Prioritize stocks with rising institutional ownership

US Stock Analysis + Institutional Flow：

1. Run comprehensive fundamental analysis
2. Validate with institutional ownership trends
3. If institutions are selling, investigate why

Portfolio Manager + Institutional Flow：

1. Fetch current portfolio via Alpaca
2. Run institutional analysis on each holding
3. Flag positions with deteriorating institutional support
4. Consider rebalancing away from distribution

Technical Analyst + Institutional Flow：

1. Identify technical setup (e.g., breakout)
2. Check if institutional buying confirms
3. Higher conviction if both align

最佳实践

1. 季度复核： 设置日历提醒，留意 13F 申报截止日期
2. 多季度趋势： 关注持续趋势（3 个及以上季度），而非一次性变化
3. 重质不重量： 伯克希尔增持 > 100 家小型基金增持
4. 结合背景判断： 下跌股票的机构持仓上升，可能是价值投资者在接下落刀
5. 结合多种信号： 切勿单独使用机构资金流向信号
6. 更新数据： 每个季度在新的 13F 文件申报后重新运行分析

支持与资源

• FMP API 文档：https://financialmodelingprep.com/developer/docs
• SEC 13F 申报数据库：https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&type=13F
• 机构投资者数据库：https://whalewisdom.com（提供免费套餐）

---

注意： 此技能面向长期投资者（3-12 个月的投资周期）。如用于短期交易，请结合技术分析和其他动量指标。