contrarian-setup-gate

逆向设置关卡

概述

将 Jason Shapiro 的 3 步逆向流程输出综合为一个可执行状态。cot-contrarian-detector（步骤 1）标记拥挤持仓，news-reaction-failure-analyzer（步骤 2）检验市场是否未对有利于拥挤一方的消息作出反应，而 technical-analyst 的 contrarian-confirmation 模式（步骤 3）则确认周线价格行为是否显示反转迹象。此关卡读取这三份报告 JSON，并应用一套明确且经过全面测试的优先级规则，生成一个 setup_status；对于任何无法确认的输入，都会附上失败关闭原因。

此关卡不会获取数据、调用 API，也不会进行任何超出验证和合并所提供三个输入之外的计算。它是流水线的综合中心，而不是数据源。

适用场景

• 运行 cot-contrarian-detector 之后（始终必需——这是流水线的入口）
• 流水线中途，仅提供检测器报告时，用于查看 CROWDED 状态及剩余步骤
• 运行 news-reaction-failure-analyzer 之后，用于查看设置是否推进至 WATCHING_PRICE 或被 REJECTED
• 运行 technical-analyst 的 contrarian-confirmation 模式之后，用于查看设置是否达到 READY_FOR_PLAN
• 将某个标的的方向和止损位交给仓位规模计算技能之前

前置条件

• Python 3.9+
• 不需要 API 密钥——此技能完全离线运行
• 被评估标的的 cot-contrarian-detector JSON 报告（必需）
• 可选：同一标的的 news-reaction-failure-analyzer JSON 报告（步骤 2）
• 可选：同一标的的 technical-analyst contrarian-confirmation JSON 报告（步骤 3）

工作流

步骤 1：运行关卡

python3 skills/contrarian-setup-gate/scripts/run_contrarian_setup_gate.py \
  --symbol B6 \
  --detector-json reports/cot_crowding_2026-07-12.json \
  --news-json reports/nrf_B6_2026-07-12.json \
  --price-action-json reports/ta_confirmation_B6_2026-07-12.json \
  --as-of 2026-07-15 \
  --output-dir reports/

--symbol 和 --detector-json 为必需参数；--news-json 和 --price-action-json 为可选参数——省略任一参数即可查看流水线对应阶段的状态。--as-of 为必需参数（不会隐式使用“今天”）：始终根据明确的参考日期评估数据是否过时，从而确保重跑结果可复现。

退出行为有意采用非对称设计：缺少或格式错误的 --as-of（或任何其他 CLI 用法错误）属于操作员配置失误，因此 CLI 会以 2 退出并显示用法文本，且不生成报告。三个不可信报告文件中的问题——无法读取、格式错误、过时或不一致——始终采用失败关闭方式处理：CLI 以 0 退出并生成一份注明原因的报告，与此流水线中的其他所有技能完全相同。

步骤 2：读取设置状态

状态	含义	下一步
READY_FOR_PLAN	三个步骤均已确认；direction、entry_trigger 和 invalidation_level 均已填写	将 direction 和 invalidation_level 交给仓位规模计算技能
WATCHING_PRICE	拥挤持仓和消息均已确认；价格行为仍待确认	运行 technical-analyst 的 contrarian-confirmation 模式
CROWDED	拥挤持仓已确认；消息和／或价格仍待确认	运行 news-reaction-failure-analyzer
REJECTED	拥挤持仓未获确认（分类为 NEUTRAL），或消息／价格结果为 NOT_CONFIRMED	停止——不要针对此标的／方向运行后续步骤
INSUFFICIENT_EVIDENCE	缺少必需输入，输入无法读取、已过时、不一致，或其本身无法得出结论	停止——修复或重新生成所标明的输入，然后重跑

missing_confirmations 列出所有仍构成阻碍的步骤，并附上其 state 和 reason。warnings 不会改变状态——它们会标记值得审查的情况，例如确认信号的置信度为 MEDIUM，或输入接近过时。

步骤 3：仅在 READY_FOR_PLAN 时采取行动

在 READY_FOR_PLAN 状态下，direction（SHORT/LONG，代表人群的反向一侧）、entry_trigger（对确认性周度信号的事实性复述）和 invalidation_level（价格行为报告中的止损参考位）均已填充。gate_confidence 取新闻和价格行为置信度中较弱的一项（HIGH/MEDIUM/LOW——两个上游技能都将 LOW 记录为保留值，但实际上从不发出；门控会接受它并将其排为最低，而不是视为未知值并拒绝）。仓位规模计算是下一阶段的流水线步骤（截至该技能发布时尚未构建——参见代码库工作流文档中的路线图）；此门控绝不会下单或建议下单。

优先级（摘要）

每一步都严格按流水线顺序评估——人群拥挤度、然后新闻、再然后价格行为；每一步都必须完全判定，之后才会查阅下一步的文件。较早步骤的明确判定绝不会因较晚步骤的问题而减弱。

1. 首先且仅评估人群拥挤度：INVALID/INSUFFICIENT 拥挤度始终为 INSUFFICIENT_EVIDENCE；NOT_CONFIRMED（NEUTRAL）分类始终为 REJECTED，无论任何下游文件的状态或损坏情况如何。
2. 若人群拥挤度为 CONFIRMED，则接下来单独评估新闻：INVALID（无法读取、格式错误、过时、标的代码不匹配、方向不匹配、不支持的架构）会导致 INSUFFICIENT_EVIDENCE；NOT_CONFIRMED 会导致 REJECTED；INSUFFICIENT 会导致 INSUFFICIENT_EVIDENCE——在以上所有情况下，决策时都不会检查价格行为。
3. 新闻一旦为 CONFIRMED（或在乱序使用时为 PENDING），最后评估价格行为，并按相同的四种情况判定。若在新闻之前运行价格行为（流水线使用顺序错误），状态最高只能为 CROWDED，并附带警告——即使顺序错误，NOT_CONFIRMED 的价格行为判定仍会导致 REJECT，因为该分支仍会完整评估价格行为。
4. 人群拥挤度已确认，两个下游步骤均为待处理 -> CROWDED。
5. 人群拥挤度和新闻均已确认，价格行为待处理 -> WATCHING_PRICE。
6. 三项均已确认 -> READY_FOR_PLAN。

完整决策表（所有可达的 {crowding} x {news} x {price-action} 状态组合）、原因标记词汇表及示例，请参见 references/gate-decision-table.md。

输出约定

脚本会将 contrarian_setup_gate_<SYMBOL>_<as-of>.json 和 .md 写入 --output-dir：

symbol: B6
setup_status: READY_FOR_PLAN | WATCHING_PRICE | CROWDED | REJECTED | INSUFFICIENT_EVIDENCE
direction: SHORT | LONG | null
gate_confidence: HIGH | MEDIUM | LOW | null
entry_trigger: string | null
invalidation_level: number | null
missing_confirmations: [{step, state, reason}, ...]
warnings: [string, ...]
inputs:
  crowding: {state, classification, data_date, age_days, report_path}
  news_failure: {state, verdict, confidence, verdict_reason, as_of, age_days, report_path}
  price_action: {state, verdict, confidence, verdict_reason, stop_reference, as_of, age_days, report_path}
run_context: {symbol, as_of, max_detector_age_days, max_report_age_days, schema_version, skill}

每个输入的 state 均为 CONFIRMED、NOT_CONFIRMED、INSUFFICIENT、PENDING（未提供报告）或 INVALID（已提供报告但不可用——无法读取、格式错误、过时或与其他输入不一致；始终带有明确命名的原因）。

防护措施

1. 绝不下单或建议下单。 READY_FOR_PLAN 是此技能能达到的最远状态。下单和仓位规模是后续需要单独决定的事项。
2. INSUFFICIENT_EVIDENCE 和 REJECTED 永远不会推进。 任何警告、置信度或部分输入都不会让状态超出优先级规则允许的范围。
3. 始终对所有输入采取失败关闭策略。 无法读取、格式错误、已过时、标的代码不匹配或枚举值未知的报告绝不会被视为通过，而是会被明确标记，并阻止或降级状态。这包括价格行为报告的 verdict_reason（须根据 technical-analyst 实际使用的确认信号词汇进行允许列表校验，而不只是检查类型），以及其 stop_reference（必须是有限正数，不能是非有限数、零、负数或布尔值）。在这三个报告文件中的任何一个进入此项校验之前，CLI 也会直接拒绝其中包含非有限数（Infinity/-Infinity/NaN）的文件，拒绝原因是 <input>_non_finite。这也包括解析时溢出的普通格式数字（如 1e309），无论该数字是否出现在门控逻辑读取的字段中——这可确保即使面对恶意输入，每份报告仍是有效且完整的 JSON 文件。
4. READY_FOR_PLAN 始终包含可用计划。 状态为 READY_FOR_PLAN 时，entry_trigger 保证非空，且 invalidation_level 保证为有限正数；输入校验和防御性不变量检查都会强制执行此要求。
5. 不构成投资建议。 entry_trigger 和 invalidation_level 是对上游价格行为报告中事实的原样复述，并非建议。

资源

• scripts/run_contrarian_setup_gate.py —— CLI：强化的 JSON 加载（无法读取 / 解析错误，包括 RecursionError / 通过迭代式全文件扫描检测非有限数），生成报告
• scripts/gate_logic.py —— 纯合成核心：规范化（包括检测格式错误的结构）、一致性检查、优先级状态机
• references/gate-decision-table.md —— 完整决策表、原因标记词汇表、示例（包括实际的 B6 REJECTED 案例）