futures-position-sizer

期货头寸计算器

概述

Shapiro 流程第 4 步：根据账户风险预算和已验证的合约规格（乘数、最小变动价位、每跳价值），将交易方向、入场价和止损价转换为合约数量。这是一个全新的独立技能，与 position-sizer 不同——期货合约是杠杆型、以乘数为基础的工具，不同合约每点对应的美元价值差异很大（ES 波动 $0.25 对应 $12.50，NQ 对应 $5.00，ZB 对应 $31.25）；将用于股票的股数计算器用于期货，会悄无声息地算出错误的头寸规模。

两种头寸规模计算方式：

• 模式 A（显式指定）：直接提供 --symbol --direction --entry --stop。
• 模式 B（关卡交接）：提供 --gate-json <contrarian-setup-gate report> --entry。方向和止损（关卡的 invalidation_level）取自关卡的 READY_FOR_PLAN 报告——计算器绝不会为关卡尚未确认为 READY 的交易设置计算头寸规模；提供 --gate-json 时，也绝不接受同时显式指定 --direction/--stop（若提供关卡报告，则以关卡为准）。

两种模式都必须提供 --entry——本技能和关卡都不会推导入场价；入场价由操作者提供。

适用场景

• contrarian-setup-gate 达到 READY_FOR_PLAN 后，需要根据已确认的方向和止损计算合约数量
• 用户询问“我应该交易多少份 ES/NQ/GC/CL/... 合约？”
• 用户有一个入场价和止损价已知的期货交易想法，希望按风险计算头寸规模
• 用户希望在计算头寸规模前查看某个品种已验证的合约规格（乘数/最小变动价位/每跳价值）（--list-specs）

前置条件

• Python 3.9+，仅使用标准库——无需 API 密钥，完全离线
• 方向、入场价和止损价（模式 A），或 setup_status: READY_FOR_PLAN 的 contrarian-setup-gate JSON 报告（模式 B）
• 对于已验证的 23 个核心市场表之外的品种：需同时提供乘数、最小变动价位和报价货币

工作流

第 1 步：计算头寸规模

模式 A——显式指定：

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ES --direction LONG --entry 5000.25 --stop 4980.00 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

模式 B——关卡交接：

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --gate-json reports/contrarian_setup_gate_B6_2026-07-15.json \
  --entry 1.3400 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

模式 B 中可以省略 --symbol——计算器会从关卡报告中读取。如果两者都提供，则必须一致（否则返回 gate_symbol_mismatch）。提供 --gate-json 时，不接受 --direction/--stop（用法错误，退出码为 2）——只能使用一种模式，不能同时使用。

第 2 步：读取结果

sizing_status	含义
SIZED	contracts >= 1；total_risk_usd/risk_pct_of_account 为实际承担的风险
NO_TRADE	绝不会导致崩溃——始终包含 no_trade_reason。原因说明见下文

对于 risk_below_one_contract 导致的 NO_TRADE 结果，仍会报告完整的风险计算数据（每份合约风险、风险预算、止损距离）——只是按当前风险百分比和止损距离，账户无法承担一份合约。可以考虑选择规模更小的合约（例如微型合约）、在现有风险政策范围内审慎重新评估风险百分比，或放弃这笔交易。止损应保持在交易设置定义的失效位：扩大止损会增加每份合约的风险，使其更难负担；不要仅为了符合预算而收紧止损。

选择更小的合约时，应使用该合约自己的品种代码和已验证规格；如果该合约不在核心表中，则必须同时提供 --multiplier、--tick-size 和 --contract-currency（报价货币非 USD 时还需提供 --fx-rate）。不要调低现有品种的乘数来模拟微型合约。模式 B 中，应使用该较小合约品种对应的 READY_FOR_PLAN 关卡；不要给原关卡改名以绕过品种检查。

第 3 步：检查警告

warnings（顶层列表）不会阻止头寸规模计算——它会标记值得审计的情况：risk_pct_above_2（风险高于 2% 指引）、off_tick_grid_entry/off_tick_grid_stop（债券以外的品种价格不完全符合最小变动价位网格——中间报价可能合理，但值得再次检查）。

第 4 步：查看已验证的合约规格表

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py --list-specs

打印完整的 23 个市场核心表（乘数、最小变动价位、每跳价值、货币、交易所），数据来源为官方交易所合约规格页面；各行的来源 URL 和验证日期见 references/futures-contract-specs.md。

示例：债券期货的非网格价格防护（32 分之一点 -> 十进制）

债券／票据期货（ZT、ZF、ZN、ZB）以点的分数报价（32 分之一点或 32 分之 32 点），通常用撇号表示：110'16 表示 110 + 16/32 = 110.50。如果输入 110.16，把撇号后的数字当作十进制美分来读，这是一个常见且不易察觉的错误，会导致金额计算出错：110.16 根本不在 ZB 的最小变动价位网格（0.03125 = 1/32）上。

# WRONG -- 110.16 is not on the 1/32 grid; this is almost certainly a
# mistyped "110'16" (which means 110.50). Exits 2, no report written:
python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ZB --direction LONG --entry 110.16 --stop 108.00 \
  --account-size 100000 --risk-pct 1.0

# CORRECT -- decimal points, not the raw 32nds digits:
python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ZB --direction LONG --entry 110.50 --stop 108.00 \
  --account-size 100000 --risk-pct 1.0

表中的其他所有代码都以普通十进制点数报价；此类价格不在网格上的情况（例如中间价）只会触发软性 off_tick_grid_* 警告，不会拒绝。

输出约定

当 --format json|both 时，将 futures_position_size_<SYMBOL>_<as-of>.json 写入 --output-dir；当 --format text|both 时，将格式化摘要打印到 stdout。--as-of 默认为今天（这是一个供操作人员使用的仓位规模计算工具，不是回测工具）。

schema_version: "1.0"
symbol: ES
direction: LONG
sizing_status: SIZED | NO_TRADE
no_trade_reason: null | risk_below_one_contract | gate_not_ready | gate_symbol_mismatch | ...
entry: 5000.25
stop: 4980.00
stop_distance_points: 20.25
stop_distance_ticks: 81
contract_spec: {multiplier: 50, tick_size: 0.25, tick_value: 12.5, currency: USD, source: cme, verified: "2026-07-17"}
risk_per_contract_usd: 1012.50
risk_budget_usd: 2000.00
contracts: 1
total_risk_usd: 1012.50
risk_pct_of_account: 1.01
max_contracts_cap_applied: false
fx_rate_used: 1.0
margin_note: "Exchange margin requirements are broker/time-dependent and NOT computed here; verify initial/maintenance margin with your broker."
gate: {report_path, setup_status, gate_confidence, warnings}   # mode B only
warnings: []
run_context: {symbol, as_of, schema_version, skill}

防护措施

1. 没有明确的止损价，绝不计算仓位。 模式 A 必须提供 --stop；模式 B 在防护流程本身报告 READY_FOR_PLAN 且提供有效的 invalidation_level 之前，拒绝计算仓位（gate_not_ready）。
2. 向下取整，绝不进位——通过精确计算确保结果准确，不使用 epsilon。 contracts = floor(risk_budget / risk_per_contract) 使用精确有理数运算（Python 的 Fraction，而非浮点除法）计算，因此按构造可保证 contracts * risk_per_contract <= risk_budget——不需要 epsilon 调整，没有浮点表示边界问题，也不会超过预算。此外，如果计算出的数量在经济上不合理（例如乘数覆盖值小到离谱），也会直接拒绝。合约数为零是合法的、故障关闭的 NO_TRADE 结果，不是错误。
3. 两类故障关闭情形，依据错误值的来源分别处理。 由操作人员导致的问题（例如明确指定的 --stop 位于 --entry 错误一侧、止损距离小于一个最小变动价位、债券价格输入不在最小变动价位网格上）属于用法错误：退出码为 2，不写入报告。来自不可信防护报告文件的值（模式 B 的止损）出现同类问题时，则返回故障关闭的 NO_TRADE 结果：退出码为 0，并且会写入报告，说明原因——绝不会因防护文件无效或尚未就绪而崩溃，与此流程中的其他所有技能保持一致。
4. 债券类非网格价格会被直接拒绝，而非发出警告。 ZT/ZF/ZN/ZB 以 32 分之一点／64 分之一点格式报价；价格不在最小变动价位网格上，几乎可以肯定是记法输入错误，若据此计算仓位，会悄无声息地导致金额计算出错。其他所有代码只会触发警告。
5. 绝不计算保证金。 margin_note 是固定且不会过时的提醒——保证金要求取决于经纪商和时间；此工具不会估算保证金。
6. 考虑货币差异。 核心表中的所有代码均以 USD 报价（已通过覆盖全表的单元测试确认），包括 CME 外汇期货；其合约规模以外币计价（例如 B6 的 GBP 62,500），但交易和结算均以 USD 进行。以非 USD 货币报价的代码（通过 --contract-currency 覆盖）必须明确指定 --fx-rate——不会静默使用默认值。
7. 不构成投资建议。 此技能根据操作人员提供或由防护流程确认的输入执行基于风险的算术计算；它不会推荐交易、方向或入场点。

资源

• scripts/futures_position_sizer.py -- 命令行界面：参数解析、强化的 gate-json 加载（通过迭代式全文件扫描处理 unreadable / parse_error（包括 RecursionError）/ non_finite）、报告生成
• scripts/futures_sizing.py -- 纯仓位计算核心：数值验证器、经核实的 23 个市场合约规格表、风险计算、向下取整算法、最小变动价位网格保护，以及 gate 报告格式规范化
• references/futures-contract-specs.md -- 经核实的合约规格表，包含每行对应的官方来源 URL 和验证日期
• references/sizing-methodology.md -- 公式、精确有理数向下取整算法的原理、失败时关闭的退出码约定，以及计算示例（ES 多头、通过 gate 移交的 B6 空头）