cot-contrarian-detector

COT 逆向交易拥挤度检测器

概述

实现 Jason Shapiro 的 COT（交易者持仓报告）逆向交易流程中的第 1 步：检测大型投机者是否集中在期货市场的一侧。持仓拥挤是逆向交易的前提条件，而不是交易信号——只有在新闻失利和价格走势反转得到确认后，市场才具备交易条件（第 2–3 步）。本技能会引导用户手动完成这些步骤。

核心论点（Shapiro）： 大型投机者（对冲基金、CTA、动量交易者）往往在趋势耗尽时达到最高持仓水平，而非趋势开始时。当他们已经集中在一侧时，统计上更有可能出现下一波大行情击垮他们，而不是让他们进一步获利。要逆向交易的是投机者，而非商业交易者（商业交易者出于结构性原因进行对冲，其持仓并非群体心理信号）。

何时使用此技能

英语：

• “现在投机者集中持仓的是哪些市场？”
• “运行 COT 报告分析” / “显示 COT 持仓极端情况”
• “现在有人在黄金 / 美元 / 债券市场被‘套牢’吗？”
• 用户想寻找逆向期货交易机会
• 用户询问 Jason Shapiro 风格的 COT 筛选

日语：

• 「COTレポートで買われすぎ・売られすぎのポジションを調べて」
• 「投機筋が偏っている市場は？」
• 「ジェイソン・シャピロ式の逆張り分析をして」

请勿在以下情况下使用：

• 用户现在就想要交易信号——仅凭持仓拥挤并不足以采取行动；请参阅下方的防护准则
• 用户询问个股——COT 报告仅涵盖 CFTC 期货市场（指数、利率、外汇、金属、能源、农产品、加密货币），不涵盖单只股票

前提条件

• FMP API 密钥： 必需。设置 FMP_API_KEY 环境变量或传入 --api-key。COT 端点需要 FMP Premium+ 套餐——免费套餐的密钥无法访问。
• Python 3.9+，并已安装 requests。
• API 调用预算： 每个市场调用一次（--core 为 23 次，完整市场范围最多约 65 次）；若未指定 --symbols 或 --core，还需额外调用一次获取市场列表。

工作流

第 1 阶段：运行拥挤度筛选

# Curated core futures universe (23 liquid/representative markets)
python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --core --output-dir reports/

# Explicit symbols
python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --symbols "ES,GC,CL" --output-dir reports/

# Full universe (all ~65 markets FMP's COT list covers)
python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --output-dir reports/

脚本会获取每个市场每周的传统版 COT 报告（大型投机者的多头 / 空头持仓），计算各市场的 156 周（3 年）和 26 周 COT 指数，并对极端情况进行分类：

• CROWDED_LONG — COT 指数 >= 90（接近 3 年净多头峰值）
• CROWDED_SHORT — COT 指数 <= 10（接近 3 年净空头峰值）
• NEUTRAL — 介于两者之间

历史数据不足以计算指数的市场不会被悄悄略过——它们会出现在 skipped 列表中，并附上原因（例如“历史数据不足：40/156 周”）。

第 2 阶段：呈现拥挤度报告

呈现生成的 Markdown 报告，并重点说明：

• 哪些市场属于 CROWDED_LONG / CROWDED_SHORT，以及拥挤程度
• 26 周指数的背景信息（拥挤度是新近形成还是已持续一段时间？）
• 周环比净持仓变化（变化快速的群体更脆弱）
• 方法说明和免责声明——持仓拥挤不是交易信号

阶段 3：手动引导完成步骤 2–5（Shapiro 流程）

对于用户想要进一步分析的任何 CROWDED_LONG / CROWDED_SHORT 市场， 加载 references/shapiro-methodology.md，并引导用户完成剩余 步骤——这些步骤不会自动执行：

1. 拥挤度检测（已完成 — 此技能）
2. 新闻失效 — 使用 WebSearch 检查近期利好拥挤方向的新闻是否未能按 市场参与者的预期推动价格变动（例如，拥挤做多市场未能因利好消息而上涨）。 这是核心优势，也是最重要的人工确认环节。
3. 价格走势确认 — 检查周线图是否出现反转形态，或价格在创出新高/新低时受阻。
4. 入场 — 逆市场拥挤方向入场，将止损设在近期波段极值，并采用较小的固定风险仓位 （参见 position-sizer 技能）。
5. 退出 — 当持仓倾向回归中性（COT Index 回到 50 附近）或触发止损时退出。

切勿仅凭拥挤度就建议入场——必须先由步骤 2 和 3 确认。

输出

• JSON： reports/cot_crowding_<as-of-date>.json — 机器可读文件，包含 run_context 区块（schema_version、params、universe、data_date），以及 markets（排名结果）和 skipped（绝不静默丢弃）。
• Markdown： reports/cot_crowding_<as-of-date>.md — 人类可读报告，包含 Crowded Long / Crowded Short / Full Ranking / Week-over-Week Swings / Skipped Markets / Methodology 各章节。

执行频率

CFTC 在周五美国东部时间约下午 3:30发布 COT 报告，报告中的持仓数据截至 前一个周二——发布时数据总是至少滞后 3 天，到下一个周五时最多滞后 9 天。运行此技能的时机：

• 每周，在周五报告发布后或周末运行，以获取最新情况
• 临时按需，用户询问特定市场的持仓情况时运行——无论如何，底层数据都来自最近一次周五发布的报告

防护原则

• 仅凭拥挤度并非交易信号。 它只是前提条件。除非步骤 2（新闻失效）和步骤 3（价格走势）也根据 references/shapiro-methodology.md 得到确认，否则绝不要建议入场。
• 数据存在滞后。 解读时，COT 持仓数据已滞后 3–9 天；不要将其视为实时信号。
• 反向操作投机者，而非商业交易者。 此技能只分析 非商业（“大型投机者”）持仓——商业套期保值资金流在结构上有所不同，并非反映群体心理的信号。
• 不构成投资建议。 所有输出仅用于研究和教育目的。

资源

references/shapiro-methodology.md

完整的 5 步流程（拥挤度 → 新闻失效 → 价格走势 → 入场 → 退出）、为何将投机者（而非商业交易者）作为反向操作对象、3 天发布滞后的注意事项，以及一张列出此技能自动执行与仍需手动完成事项的表格。引导用户继续完成步骤 1 之后的流程时，加载此文件。

references/cot-index-calculation.md

COT Index 公式、回溯期选择理由（主要采用 156 周 / 以 26 周为参考）、 极值阈值敏感性、未平仓合约量归一化理由、旧版与分类报告的区别（此技能使用旧版报告中的非商业 = 大型投机者字段），以及 scripts/cot_index.py 使用的 FMP COT API 字段名称词汇表。

随附的客户端：scripts/fmp_client.py（生成文件）负责处理 FMP 传输，包括速率限制、单次 429 重试、标头身份验证（密钥绝不会出现在 URL 中），以及对 (data, error) 结果中的 apikey 进行脱敏（Issue #495）。

何时加载参考资料

• 首次使用 / 解释方法： 加载 references/shapiro-methodology.md
• 解释报告中的特定数值： 加载 references/cot-index-calculation.md
• 常规执行： 无需参考资料——脚本会处理拥挤度计算