摘要。 Macro Terminal 从 CFTC 交易商持仓报告（Commitments of Traders，COT）中读取期货持仓，并将其转化为两样截然不同的东西：一条 净持仓 序列，说明投机资金正倒向哪一边；以及一个 拥挤度 指标，说明这种倒向相对其自身历史有多不寻常。本页记录这些序列背后的口径选择——哪一类资产使用哪个 COT 报告族、哪个交易者分类算作投机者代理口径、净持仓如何标准化、拥挤度 z 分数如何定义（逐成员、带符号、不做混合）、数据更新频率如何，以及覆盖哪些资产族。我们的目标是：读者无需询问我们做了什么，就能凭公开的 CFTC 数据复现这里的每一个数字。
1. 为什么持仓要单列一层
多数宏观指标描述的是 世界的状态——增长、通胀、流动性、信用。持仓描述的是 市场对这个世界所下赌注的状态。两者回答的是不同的问题，把它们混为一谈是最经典的错误。
Macro Terminal 把持仓视为脆弱度指标，而非方向信号。拥挤的持仓不会告诉你趋势错了；它告诉你价格对反向催化剂有多敏感——一次库存意外、一场天气事件、一轮美元波动、一个不及预期的数据。净多头极端、身后却没有新增未平仓合约支撑的趋势，比同样的价格走势叠加参与度扩张要脆弱得多。
这对数据如何接入有直接影响：持仓序列是证据与背景，而不是打分输入。它们可以限定或封顶某个资产观点的信心度；它们本身不产生观点。
2. 用哪个 COT 报告族，以及为什么
CFTC 针对同一批标的市场发布多个并行的报告族。它们对交易者的分类方式不同，因此这些分类不可互换，其历史序列也绝不可拼接。
Macro Terminal 按资产领域选择报告族，而不是采用某个通用默认值：
| 资产领域 | 报告族 | 理由 |
|---|---|---|
| 利率、外汇、股指、VIX | 金融期货交易者报告（TFF） | TFF 的分类专为金融合约设计，且区分资产管理机构与杠杆基金——这一区分对解读投机意图至关重要。 |
| 能源、金属、广义商品 | Disaggregated（分类持仓报告） | 实物商品分类拆分出生产商/贸易商/加工商/终端用户、互换商、管理基金和其他可报告头寸——这正是商品解读所依赖的"套保方 vs 投机方"划分。 |
| 农产品、软商品、畜牧 | Disaggregated | 对这些市场而言，管理基金是最干净的首选投机者代理口径。 |
刻意排除的报告族
- Legacy（传统报告）。 Legacy 的商业/非商业划分与 TFF 或 Disaggregated 的分类不可比。把它掺进来需要额外搭一座分类桥梁，只会增加解释上的模糊性，而没有分析收益。持仓层的任何环节都不使用 Legacy。
- 商品指数交易商补充报告（Supplemental CIT）。 CIT 回答的是另一个问题——指数跟踪型敞口——它不是管理基金的替代品。我们的处理是将其排除在范围之外，而非混入。
只用仅期货，绝不用合并口径
所有持仓序列均使用仅期货（futures-only）数据。不使用期货与期权合并数据，且仅期货观测与合并观测绝不在同一条指标历史内混用。
理由在于可解释性：合并文件把期权头寸折进持仓计数却不披露 delta，于是一个"净多头"数字就混合了直接敞口与方向权重未知的期权衍生敞口。仅期货口径以忽略期权为代价换取序列的干净——对一个脆弱度指标而言这是可接受的交换，因为分布的形状比最后那一单位敞口更重要。
所用数据集：
| 报告族 | 仅期货数据集 |
|---|---|
| Disaggregated | 72hh-3qpy |
| Traders in Financial Futures | gpe5-46if |
两者均由 CFTC 公开报告环境（Public Reporting Environment）提供，且无需 API key。
3. 交易者分类
在每个报告族内部，只保留一个明确界定的交易者分类子集。
TFF（金融合约）
- 杠杆基金 —— 投机者代理口径。交易金融期货的对冲基金、CTA 以及管理基金类账户。
- 资产管理机构在数据源中可得，也可作为背景信息呈现，但它不是证据级分类。
Disaggregated（实物合约）
- 管理基金 —— 投机者代理口径。趋势跟踪者、CTA 和宏观基金。
- 生产商/贸易商/加工商/终端用户 —— 商业套保方。解读为实物套保压力；通常与管理基金方向相反。
- 互换商 —— 指数挂钩与场外对冲流。解读为金融中介与结构性配置敞口。
证据级分类仅限投机者代理口径。 管理基金（Disaggregated）与杠杆基金（TFF）是能够把持仓证据带入资产观点的分类。生产商/贸易商与互换商属于展示与背景：它们能丰富对管理基金极端值的解读，但不独立生成证据。
由于两个报告族的投机者分类承担相同的分析角色，Macro Terminal 将其视为同一个分类槽位——TFF 合约对应杠杆基金，Disaggregated 合约对应管理基金——并逐合约注明，确保这一区分不会丢失。
4. 净持仓：定义与标准化
对于给定的合约与交易者分类：
net = long − short
netPctOi = (long − short) / open_interest_all × 100存储的序列是 netPctOi，以占未平仓合约的百分比表示。
为什么用未平仓合约做标准化。 原始的净合约张数在不同合约之间不可比（铜的 40,000 张净多头与玉米的 40,000 张净多头含义完全不同），在同一合约的不同时期之间也不可比，因为市场规模会漂移。除以总未平仓合约后，序列变成了 占市场的份额——既可跨合约比较，也足够接近平稳，使得历史 z 分数具有意义。
跨期对锁持仓（spreading）不计入 net。 它们在构造上就是方向中性的；把它们加进来只会虚增表面头寸而不增加任何方向性敞口。它们可以作为数据质量的背景字段保留，但绝不进入 net。
未平仓合约的完整性是一道硬闸门。 如果某合约的 open_interest_all 缺失、为零或不可靠，该指标保持待定状态。不存在退回原始净合约张数的兜底方案——一条未经标准化的序列会悄无声息地摧毁整个持仓层所依赖的可比性。
5. 拥挤度：逐成员带符号 z 分数
这是最常被搞错的定义，因此在此精确陈述。
拥挤度 = 单一合约的管理基金（或杠杆基金）
netPctOi的带符号历史 z 分数，在滚动 3 年窗口上计算。
这句话推出三条性质，每一条都是承重的。
5.1 带符号，而非绝对值
z 分数保留其符号。高正值 z 代表多头拥挤；极端负值 z 代表空头拥挤。这是两种不同的市场状态，失效方式也不同——拥挤的多头通过获利了结和止损出局来消化，拥挤的空头则通过空头回补挤压来消化。取 |z| 会把两者压缩成同一个"极端"读数，把信息彻底破坏掉。
5.2 逐成员，而非混合合成值
拥挤度按合约计算和展示。一个商品族的拥挤度视图是一组各自独立的带符号 z 曲线——黄金、白银、铜、铂、钯——而不是一个代表"金属"的平均数。
在族内对 z 分数取平均会掩盖分化，而分化恰恰是最有信息量的情形：黄金多头拥挤、同时铜空头拥挤，与两者都轻微偏多，是截然不同的宏观陈述，然而等权合成值会把这两种情况呈现得一模一样。这也正是金属不设单一族级拥挤度数值的原因——黄金作为货币/实际利率资产交易，铜作为周期需求资产交易，一个混合的"金属拥挤度"数字会断言一个并不存在的共同驱动。
在保留族级合成值的地方，其范围被限制在成员合理共享驱动的同质篮子——谷物（玉米、小麦、大豆）与软商品（咖啡、可可、糖）。即便是这些合成值也附带同质性保留条款，并且是与逐成员曲线并列阅读，而非取而代之。
5.3 等权合成值只有一个合法归宿
混合型拥挤度数字确实有一个正确的位置：跨族系统性总览层——在那里，各商品族（能源、金属、农产品、软商品、畜牧）的管理基金 z 均值被并排比较，用以回答"当下哪一族最拥挤"。这是一个决定往哪里下钻的分诊工具。它属于凌驾于各族之上的系统层——绝不属于任何单一族的卡片内部，因为在那里它会取代它本应概括的逐成员细节。
5.4 窗口
拥挤度窗口为 3 年，以 156 个周度观测实现。CFTC 是规整的周度数据，因此固定的行数就是一个精确的日历窗口而非近似——无需也未使用任何日期感知的插值。
3 年是一个刻意的折中。足够长，使分布覆盖不止一个持仓周期；又足够短，使参照分布仍反映当前的市场结构、参与者构成与合约规模。窗口若长得多，就会拿今天的持仓去对照一个已经不复存在的市场打分。
持仓序列的 z 分数视图与百分位视图使用的是同一个 3 年窗口，因此拥挤度读数与由其派生的证据级信号绝不会在不同的历史长度上计算。
5.5 方向语义：反向（contrarian）
拥挤度以反向语义进入资产证据：
- 高多头百分位 / 高正值 z → 该交易已拥挤 → 映射为 pressure（压力）。
- 出清或净空百分位 / 极端负值 z → 持仓风险已释放 → 映射为 support（支撑）。
趋势确认语义——把净多头上升读作看涨确认——对拥挤度序列明确不予授权。若某条持仓序列确实需要承担趋势确认角色，它必须是一个单独定义的指标，而不是对拥挤度序列的重新诠释。
6. 未平仓合约
未平仓合约承担三个角色，以及一个明确的非角色。
角色：
- 每条净持仓序列的标准化分母（见 §4）。
- 数据质量校验——缺失或不合理的 OI 值会使该合约当周的持仓读数失效。
- 参与度背景，以未平仓合约同比（52 周变化）的形式呈现。
非角色： 单独的未平仓合约绝不作为资产证据，也绝不作为打分输入。它仅用于展示与背景。
未平仓合约同比虽不构成证据却仍占有一席之地，原因在于它能限定趋势质量。价格上涨伴随 OI 扩张，说明有新增资金确认这轮走势。价格上涨但 OI 收缩，则更像空头回补或存量资金轮动——同一张价格图，趋势质量却实质性更弱。OI 快速扩张而价格停滞，意味着分歧扩大，往往预示着后续朝任一方向的解决都会更剧烈。
7. 序列架构
持仓指标分为三层。只有第 1 层被抓取并存储；第 2、3 层由其计算得出。
| 层 | 是什么 | 是否存储 | 如何产生 |
|---|---|---|---|
| L1 —— 合约持仓 | 每个（合约，交易者分类）组合一条 netPctOi 序列，外加每个合约一条 OI 水平值序列 | 存储原始值 | 直接从 CFTC 数据集解析 |
| L2 —— 拥挤度 | L1 投机者序列的带符号滚动 3 年 z 分数 | 派生 | 由已存储的 L1 序列计算 |
| L3 —— 族级聚合 | 族级的投机者净持仓均值、拥挤度 z 均值，或聚合的未平仓合约同比 | 派生 | 跨成员 L1/L2 值聚合 |
把拥挤度保持为已存储原始持仓的派生量而非单独存储的序列，是一条刻意的设计规则，带来两项收益：不产生重复数据；以及无需重新抓取任何一行历史数据即可重新调校或复核拥挤度窗口。只有原始 L1 序列需要历史回填，且回填至少 3 年，使拥挤度窗口从第一天起就是满的。
序列标识符遵循统一约定：持仓用 cftc-<contract>-<category>，未平仓合约用 cftc-<contract>-oi，族级聚合用 cftc-<family>-<metric>。凡使用拥挤度标识符之处，它都是一个指向对应投机者序列 z 分数的标签——它绝不代表另一个被单独存储的值。
8. 更新节奏与新鲜度
CFTC 持仓是带有结构性报送滞后的周度数据。这不是一个需要靠工程手段绕过的缺陷；这是数据集本身的属性，必须让读者看得见。
| 属性 | 取值 |
|---|---|
| 频率 | 周度 |
| 观测日期 | CFTC 报告日——周二收盘时点的持仓 |
| 发布时间 | 通常为美东时间周五下午 |
| 发布时的实际滞后 | 约 3 天 |
| 刷新节奏 | 每周，发布后 |
| 过期阈值 | 14 天 |
这在实践中意味着什么。 当一个持仓读数可见时，它描述的是上一个周二的市场。那个周二到当下之间的任何价格波动都不在这个数字里。对于一个以 3 年分布为参照的脆弱度指标而言，这通常是可以容忍的——拥挤度是以周为单位累积的——但这使持仓不适合用作快速触发器，也意味着这几天之内的一次急剧波动可能已经改变了图景。
处理规则：
- 以 CFTC 报告日为观测日期。不合成任何发布时间戳，因为数据源并未稳定地暴露这一信息。
- 若某个已映射合约不存在当期数据行，则省略该项证据，并将缺口报告为数据缺失。绝不静默沿用上期数值。
- 缺失的周度发布绝不从非官方或第三方镜像回填。官方数据里的缺口就保持为一个可见的缺口。
- 超过 14 天阈值后，序列被标记为过期，而不是当作当前数据呈现。
9. 合约映射与资产族覆盖
每一条上线的持仓序列都被钉死到一个精确的 CFTC 合约上：数据集、合约市场名称、合约市场代码、交易所、仅期货口径，以及具体的多头/空头/未平仓合约字段名。没有任何一条是靠名称模糊匹配得来的。这件事的重要性超出字面——单单一个指数在 CFTC 就有多条近乎同名的数据行（合并版本、行业分项、微型合约、股息合约），而它们承载的持仓完全不同。
两个体现钉死纪律的实例：
| 序列 | 合约数据行 | 数据集 | 所用字段 |
|---|---|---|---|
| S&P 500 持仓 | E-MINI S&P 500 - CHICAGO MERCANTILE EXCHANGE，代码 13874A，市场 CME | gpe5-46if（TFF 仅期货） | report_date_as_yyyy_mm_dd、open_interest_all、lev_money_positions_long、lev_money_positions_short |
| WTI 原油持仓 | WTI-PHYSICAL - NEW YORK MERCANTILE EXCHANGE，代码 067651，市场 NYME | 72hh-3qpy（Disaggregated 仅期货） | report_date_as_yyyy_mm_dd、open_interest_all、m_money_positions_long_all、m_money_positions_short_all |
对 S&P 序列而言，排除项与纳入项一样明确：S&P 500 Consolidated、S&P 行业合约、股息指数合约、S&P 400、S&P GSCI、Micro E-mini S&P 500，以及纳斯达克/道指/罗素/VIX 合约全部排除。对 WTI 而言，Brent、ICE WTI、金融与日历互换数据行、e-mini 原油以及成品油合约全部排除。
覆盖面
| 资产族 | 报告族 | 代表性合约 | 投机者分类 |
|---|---|---|---|
| 股指 | TFF | E-mini S&P 500 | 杠杆基金 |
| 利率 | TFF | 10 年期美债（短端、长端与 SOFR 合约并列参考） | 杠杆基金 |
| 外汇 | TFF | 美元指数、欧元、日元 | 杠杆基金 |
| 能源 | Disaggregated | WTI（Brent、成品油与天然气并列参考） | 管理基金 |
| 金属 | Disaggregated | 铜、黄金、白银（族级视图中含铂/钯） | 管理基金 |
| 农产品 | Disaggregated | 玉米、芝加哥 SRW 小麦、大豆 | 管理基金 |
| 软商品 | Disaggregated | 咖啡 C、可可、11 号糖 | 管理基金 |
| 畜牧 | Disaggregated | 活牛、瘦肉猪 | 管理基金 |
每个实物商品族都通过同样的五个维度呈现，这正是它们能够跨族比较的原因：
- 管理基金净持仓 / OI —— 投机方向
- 生产商/贸易商净持仓 / OI —— 商业套保压力
- 互换商净持仓 / OI —— 指数与场外对冲敞口
- 未平仓合约同比 —— 参与度
- 拥挤度 —— 管理基金净持仓 / OI 的逐成员带符号 3 年 z 分数
外汇持仓序列作为展示与背景呈现，而非资产证据。货币的方向性标注存在真实的歧义——一个"拥挤的美元多头"同时就是若干其他货币上的拥挤空头——本层不会去断言一个自身无法干净定义的 pressure/support 读数。同理，多期限的利率持仓是逐合约阅读，而非合成为一个久期加权篮子，因为把 2 年、10 年、长债和 SOFR 持仓压缩成一个数字需要一个权重选择，而那将是一个假设，不是一次测量。
10. 五个维度如何合起来读
这些维度被设计为成组阅读。单看每一个都很弱；合起来才有分辨力。
- 管理基金净持仓上升、价格上涨、OI 扩张 —— 有参与度支撑的趋势。质量最高的组合。
- 管理基金净持仓极端、价格停滞 —— 边际买家已经进场了。即便没有利空催化剂，获利了结的风险也在上升。
- 管理基金净持仓极度偏空 —— 任何供给冲击或美元反转都可能触发一轮快速的空头回补。拥挤的空头崩解起来极为剧烈。
- 生产商/贸易商净空扩大 —— 价格上涨之后套保压力在累积。这不构成即时利空，但会削弱价格继续单边上行的弹性。
- 互换商与管理基金同向扩张 —— 金融端与指数端的参与正在强化这轮走势。二者背离时，则要回到实物库存、期限结构和指数基金流向去做判断。
- 拥挤度极端而 OI 不予确认 —— 不要把宏观观点外推到单个合约上。这正是持仓最常推翻自上而下论断的情形。
一条长期有效的告诫，之所以重述是因为这是最常见的误用：拥挤度衡量的是脆弱度，不是方向。 高 z 分数不是卖出信号。它说明这笔交易已成共识，因而价格对任何与之矛盾的信息都会反应得比平常更剧烈。
11. 适用范围边界
- 持仓序列仅通过资产证据与展示界面进入产品。它们不是宏观状态打分（macro regime scoring）的输入，也不是美元流动性指数（Dollar Liquidity Index）的输入。
- 只有投机者分类（管理基金 / 杠杆基金）是证据级的。生产商/贸易商、互换商以及单独的未平仓合约均属背景信息。
- 持仓可以对某个资产观点的信心度封顶或加以限定；它本身不确立观点。
- 每个被提升上线的合约，其数据集、市场名称、市场代码与字段名都必须在上线前对照 CFTC 实时元数据完成核验。没有任何序列是通过名称匹配推断出来的。