claude-trading-skills 逆向确认清单(Shapiro Step 3):周线价格行为、三项信号与 fail-closed 输出契约
claude-trading-skills 逆向确认清单(Shapiro Step 3):周线价格行为、三项信号与 fail-closed 输出契约
在 claude-trading-skills 的 technical-analyst 技能中,Contrarian Confirmation(逆向确认)是一套把「拥挤持仓」转化为可判定结论的机械化流程:先由 cot-contrarian-detector 标记拥挤方向,再由本清单判定周线图上是否真的出现了反转证据。本文以 contrarian-confirmation-checklist.md 为核心骨架,逐条拆解方向约定、窗口语义、三项信号检查、延续性否决、摆动位止损参考、判定合成与输出契约,并结合 weekly_price_action.py 与 check_weekly_price_action.py 给出源码级实现证据,使读者既能在图表面读图,也能在脚本面复现同一判定。
一、这套清单在整条流水线中的位置
逆向确认是 Jason Shapiro 的 COT 逆势流程中的第 3 步,前两步与本步的衔接关系在原文档中有明确定义:
- Step 1:
cot-contrarian-detector判定某个市场是否拥挤(CROWDED_LONG/CROWDED_SHORT/NEUTRAL)。 - Step 2(可选):
news-reaction-failure-analyzer检验市场是否对有利消息失去反应。 - Step 3(本文主题):确认周线图本身是否在价格行为上给出反转证据。
- Step 4 / Step 5:进场计划与离场计划,仍然是手工环节,不在本清单范围内。
因此这套清单的产出被严格限定为「判定(verdict)」,绝不构成交易建议;仓位规模属于 position-sizer / futures-position-sizer 的职责。这一点在 SKILL.md 的 Guardrails 与源码注释中都被反复强调。
双消费者、同一套定义
原文档最关键的架构约束是:
这份清单由两个消费者以完全相同的方式判定:Claude 阅读用户提供的周线图(chart mode,
technical-analyst的主要工作流),以及scripts/check_weekly_price_action.py(data-driven fallback,脚本模式)。定义只写一次、两边同样适用,同一个市场的图面读数与脚本读数应当得到同一结论。当二者不一致时,适用保守优先规则。
这一「单一事实来源 + 双实现」的设计在代码里有对应痕迹:weekly_price_action.py 的模块 docstring 明确写着「No I/O, no network calls」,所有检测器都是纯函数,只接受 dict/list/标量并返回普通值,因此可以离线单测;而 check_weekly_price_action.py 只负责取数、守卫、报告落盘,检测逻辑全部委派给前者的 run_weekly_price_action()。技能契约测试 test_skill_contract.py 还强制要求清单文件与脚本文件同时存在且在 SKILL.md 中被点名引用。
二、方向约定:fade 的是哪一侧
清单的所有规则都先以 CROWDED_LONG 陈述,CROWDED_SHORT 是精确镜像。
| 语境 | CROWDED_LONG(做空逆向) | CROWDED_SHORT(做多逆向) |
|---|---|---|
| 关注的价格极值 | 高点(highs) | 低点(lows) |
| 反转证据一见即用的信号 | 收盘跌破前一周低点 | 收盘突破前一周高点 |
| 失败形态 | 上破阻力后失败 | 下破支撑后失败 |
| 延续性否决的「拥挤方向」 | 新的最高收盘 | 新的最低收盘 |
stop_reference 参考位 |
最近的 swing high(止损在上方) | 最近的 swing low(止损在下方) |
所有比较都是严格不等式(STRICT inequality)。 等于历史极值永远不算新极值;收盘恰好在某一历史价位上,永远不算反转、突破或失败。原文档对此给出的理由是:仅仅「打到」而非「超过」某个价位的市场,并没有真正产生新的证据。
这条约束在源码中是一行行硬编码的比较符:
# weekly_price_action.py#L185-L194
if direction == "CROWDED_LONG":
triggered = (
bar["high"] > max(w["high"] for w in swing_window)
and bar["close"] < prior_bar["low"]
)
else:
triggered = (
bar["low"] < min(w["low"] for w in swing_window)
and bar["close"] > prior_bar["high"]
)
单测对这种严格性做了双向固定,例如 test_weekly_price_action.py:test_equal_to_prior_high_is_not_a_new_high_strict 构造「高点相等但收盘远低于前周低点」的场景,断言不触发;test_close_equal_to_prior_week_low_does_not_trigger_strict 构造「新高成立但收盘恰好等于前周低点」,同样断言不触发。failed_extreme 与 failed_breakout 也有对应用例(test_close_exactly_at_prior_high_does_not_trigger_strict、test_close_equal_to_prior_high_is_not_a_closing_breakout_strict)。
三、窗口术语与「逐评估周截断」
这是整份清单里最容易被误读、也最容易被实现者写错的部分。原文档定义了四个窗口参数:
| 参数 | 默认值 | 含义 |
|---|---|---|
| Swing-lookback weeks | 13 | 定义「近期」高低点,驱动周线关键反转的触发条件 |
| Extreme-lookback weeks | 52 | 定义更长周期的极值,用于 failed-extreme、failed-breakout、延续性否决,以及关键反转的置信度 HIGH 加分条件 |
| Signal-recency weeks | 4 | 超过该周数的信号不构成确认。注意 failed_breakout 只以失败周为信号周 |
min_weeks |
30 | 硬下限:已完成周数少于此值即 INSUFFICIENT_DATA(insufficient_weekly_bars) |
配套有三条硬性语义:
- 「前 N 周」严格排除被评估的那一周本身。 实现见 compute_prior_window():
start = max(0, idx - lookback_weeks)、window = weekly_bars[start:idx],切片右端开区间天然排除idx。 - 窗口截断是「逐评估周」而非「逐运行」。 当某个被评估周之前的历史不足配置窗口时,窗口收缩到实际可用量,并把实际使用量写进该检查自己的结果块(
swing_window_weeks_used/extreme_window_weeks_used/window_weeks_used)。 - 置信度 HIGH 的 52 周极值条件,只读触发周自己使用的窗口大小。 典型场景是在
min_weeks下限附近扫描时,同一轮 recency 扫描里的两个不同周可能分别只有 26 周和 29 周的可用历史。
第 3 点有专门回归测试:test_per_week_differing_available_history_within_recency 分别构造「在第 27 根 bar 处触发」与「在第 30 根 bar 处触发」两种情形,断言 extreme_window_weeks_used 分别为 26 与 29,且两者不相等。另一个测试 test_high_via_52w_extreme_requires_full_untruncated_window 则固定了「历史只有 20 周时该窗口截断为 19,永远达不到 52」的行为。
窗口常量集中在模块顶部,并由 CLI 参数透传,见 weekly_price_action.py#L31-L41 与 check_weekly_price_action.py#L596-L622。
四、三项信号检查
4.1 Weekly Key Reversal(周线关键反转)
判定条件(CROWDED_LONG):
- 本周 HIGH 是新的 swing-lookback 高点——严格大于前 swing-lookback 个已完成周的最高 high;
- 且本周 CLOSE 严格低于前一周的 LOW。
CROWDED_SHORT 镜像:新的 swing-lookback 低点,且收盘严格高于前一周的 HIGH。
这是唯一引用两个窗口的检查:swing 窗口驱动触发本身;更大的 extreme 窗口单独判断同一个新高/新低是否同时构成全窗口极值——这个更强的条件只服务于置信度 HIGH 门槛,从不影响触发与否。源码正是这样分两段写的:detect_weekly_key_reversal() 先用 swing_window 判 triggered,通过之后才计算 is_full_window_extreme。
实现细节上还有两点值得注意:
- 扫描起点是
range(max(recency_start, 1), n)——索引 0 之前没有任何历史,必须从 1 开始,否则「前一周」取不到。 - 命中多个候选周时,报告最近的那一个(
best被循环覆盖),因为一个检查只报告一个信号,而不是列表。
4.2 Failed Extreme(周内刺穿后收回)
在 signal-recency 窗口内,某一周在周内严格上破了前 extreme-lookback 的 HIGH,但同一周的收盘又回到该前高之下——市场推入新领域却在收盘时未能守住。低点方向镜像。
与关键反转的区别被原文档点明:不涉及前一周自身的 high/low,且使用的是 extreme-lookback 窗口而非 swing-lookback 窗口。实现见 detect_failed_extreme(),核心只有三行:算先前的 level,判断 bar["high"] > level and bar["close"] < level,命中则记录 attempted_level 与 window_weeks_used。
4.3 Failed Breakout(先确认、后被否决)
定义:在第 B 周出现收盘站上前 extreme-lookback HIGH 的突破(是真正的收盘突破,不只是周内刺穿),并在随后 ≤3 个已完成周内,出现一次收盘重新跌回该突破位之下。
两条最关键的实现约定:
(1) week_of 是「失败周」,绝不是突破周 B。 突破周只出现在 detail 文本里。这直接影响 recency 窗口的语义——只有失败周需要落在 signal_recency_weeks 内,突破周 B 可以更老。源码里 best = (f_idx, b_idx, level, used),最终 week_of = weekly_bars<a href="https://link.gitcode.com/i/70843836b950b33ab98a6c3522ced163" target="_blank">f_idx]["week_of"],见 [detect_failed_breakout()。
(2) 不会自我否决。 因为突破周按构造必然严格早于它自己的失败周,它永远不可能在之后被当成「新的收盘极值」来否决自己的信号。这一性质在 test_breakout_week_never_self_vetoes 中被显式固定。
另外,「只有突破之后的第一次收盘回穿才算该突破的失败」——源码用 break 实现:
# weekly_price_action.py#L329-L338
for f in range(b + 1, min(b + 3, n - 1) + 1):
bar_f = weekly_bars[f]
if direction == "CROWDED_LONG":
failed = bar_f["close"] < level
else:
failed = bar_f["close"] > level
if failed:
if f >= recency_start and (best is None or f > best[0]):
best = (f, b, level, used)
break # only the FIRST close-back-through after this breakout counts
扫描突破周 B 的起点是 b_start = max(0, recency_start - 3)——B 最多可以比 recency 窗口起点早 3 周,仍然能让失败周落进窗口。超过 3 周的失败则完全不计(test_failure_beyond_3_weeks_does_not_count)。
原文档给的 worked example 值得牢记:
- 突破在第 W 周、失败在第 W+2 周、之后没有新 bar →
CONFIRMED。 - 同样的突破与失败,但在第 W+3 周(仍在 recency 窗口内)创出新的收盘新高 →
NOT_CONFIRMED(continuation_intact),延续性否决生效。
4.4 三项检查的对照表
| 检查 | 触发依据 | 使用的窗口 | week_of 语义 |
结果块专有字段 |
|---|---|---|---|---|
weekly_key_reversal |
新 swing 极值 + 收盘穿越前一周反向价位 | swing(触发)+ extreme(仅置信度) | 反转发生周 | swing_window_weeks_used、extreme_window_weeks_used、is_full_window_extreme |
failed_extreme |
周内破 extreme 价位、同周收盘收回 | extreme | 周内刺穿周 | attempted_level、window_weeks_used |
failed_breakout |
收盘突破 extreme 价位后 ≤3 周收盘跌回 | extreme | 失败周(非突破周) | breakout_level、window_weeks_used |
五、延续性否决(Continuation Veto)
延续性否决独立于三项信号检查:市场是否在拥挤方向上创出了新的收盘极值,且时间上严格比最新的已触发信号更新?
- CROWDED_LONG 关注「新的最高收盘」,参照的是每个被评估周各自的 prior extreme-lookback 收盘窗口(不是周内最高价)。
- 若存在信号,扫描从该信号自己的
week_of之后一周开始——信号周及其之前的一切都不可能自我否决。 - 若完全没有信号触发,扫描覆盖整个 signal-recency 窗口。这样做的目的是让「一路磨着创新高、根本没有反转证据」的市场得到正确的
continuation_intact理由,而不是笼统的no_reversal_evidence。
实现见 detect_continuation(),扫描起点那一行浓缩了上述规则:
scan_start = max(0, (newest_signal_idx + 1) if newest_signal_idx is not None else recency_start)
还有一个易被忽略的细节:该函数返回的是最早满足条件的周(「延续恢复的那一刻」),而不是最近的一周——判定只需要知道信号之后是否重启过延续。若同时有多个检查触发,_newest_triggered() 按 week_of 取最近者,同周并列时按固定顺序 ("weekly_key_reversal", "failed_extreme", "failed_breakout") 破平——武断但确定。
六、Swing Levels:给止损一个可复现的参考位
Swing high 定义为一个已完成周,其 HIGH 严格大于左右各 2 个已完成周的 high(即 5 周分形)。Swing low 在 low 上镜像。nearest 是 extreme-lookback 窗口内最近的这类枢轴。
Fallback:如果该窗口内任何位置都不存在分形枢轴,则退回使用(更小的)swing-lookback 窗口的 max high / min low,并标记 fallback: true,让消费者知道这是较弱的非分形替代物。compute_swing_levels() 中对应 search_end = n - 3(最近可能的枢轴必须在最后一根已完成周之前 2 周),以及 fb_start = max(0, n - swing_lookback_weeks) 的回退窗口。
stop_reference 跟随 fade 方向,而不是拥挤方向:fade 一个拥挤多头意味着做空,止损设在上方最近的 swing HIGH;fade 一个拥挤空头意味着做多,止损设在下方最近的 swing LOW。单测 test_stop_reference_uses_swing_high_for_crowded_long 与 ..._uses_swing_low_for_crowded_short 分别固定了两个方向。
七、判定合成:fail-closed 的四级优先
原文档给出的合成顺序不可调换:
- 已完成周数少于
min_weeks,或没有可用价格源 →INSUFFICIENT_DATA(insufficient_weekly_bars/no_price_source)。 - 延续性否决触发(信号之后出现拥挤方向的新收盘极值,或完全无信号但 recency 窗口内出现新收盘极值)→
NOT_CONFIRMED(continuation_intact)。这一条永远压过已触发的信号。 - 否则,若三项检查中任意一项在 recency 窗口内触发 →
CONFIRMED,verdict_reason取产出最新触发信号的那个检测器(key_reversal/failed_extreme/failed_breakout)。 - 否则 →
NOT_CONFIRMED(no_reversal_evidence)。证据缺失绝不构成确认。
源码即 synthesize_verdict(),四行分支与上表一一对应。
置信度规则
HIGH 当且仅当满足任一:
- recency 窗口内至少有 2 种不同检测器类型触发(同一检测器重复触发不算两次——本模块对每个检测器只报告最近一次触发,因此该条件自动成立);
- 触发的
weekly_key_reversal的新高/新低同时是**完整、未截断(≥52 周)**extreme 窗口的极值,即其自身extreme_window_weeks_used >= 52且is_full_window_extreme == true。
否则 MEDIUM。LOW 保留,v1 永不输出。
实现见 compute_confidence()。注意门槛读的是常量 CONFIDENCE_HIGH_EXTREME_WEEKS = 52,而不是调用方传入的 extreme_lookback_weeks——这样即便有人用非默认窗口运行,门槛也是良定义的(虽然可能不可达),而不是一个会移动的目标。
单信号 MEDIUM 是刻意设计的弱证据。 一次周线关键反转、一次失败极值、或一次失败突破,单独来看只是「值得注意」而非强确认;原文档明确要求把孤立的 MEDIUM 当作继续观察的理由,而不是加仓的理由。confidence 字段被写入 handoff 块正是为了这个目的:下游消费者(contrarian-setup-gate,仓库中尚未构建)可以据此对单信号证据给予比双信号或全窗口证据更保守的权重。
八、输出契约与 INSUFFICIENT_DATA 不变量
脚本模式产出的 YAML 形状如下(图表面镜像同一形状,仅 mode: chart):
symbol: BT
direction: CROWDED_LONG
mode: data # 图面读数时为 "chart"
verdict: CONFIRMED # CONFIRMED | NOT_CONFIRMED | INSUFFICIENT_DATA
confidence: HIGH # HIGH | MEDIUM | LOW(LOW 保留,v1 不输出)
verdict_reason: key_reversal # key_reversal | failed_extreme | failed_breakout |
# continuation_intact | no_reversal_evidence |
# insufficient_weekly_bars | no_price_source | ...
checks:
weekly_key_reversal:
{ triggered, week_of, swing_window_weeks_used,
extreme_window_weeks_used, is_full_window_extreme, detail }
failed_extreme: { triggered, attempted_level, week_of, window_weeks_used, detail }
failed_breakout: { triggered, breakout_level, week_of, window_weeks_used, detail }
continuation: { new_closing_extreme_with_crowd, week_of, window_weeks_used }
swing_levels:
nearest_swing_high: { price, week_of, fallback }
nearest_swing_low: { price, week_of, fallback }
stop_reference: 0.0
weekly_bars_used: 52
last_completed_week: 2026-07-06
handoff: # 由 contrarian-setup-gate (#241) 消费
price_action: { verdict, confidence, stop_reference, report_path }
run_context:
{ price_symbol, price_source, proxy_used, as_of,
lookbacks, recency, min_weeks, detector_json, detector_age_days, schema_version }
输出文件名:ta_confirmation_<SYMBOL>_<as-of>.json 与 ta_confirmation_<SYMBOL>_<as-of>.md,写入 --output-dir(默认 reports/)。命名模式在 SKILL.md 与契约测试中都被固定。
关键不变量:checks 与 swing_levels 恒为 null
只要 verdict: INSUFFICIENT_DATA,checks(以及 swing_levels)就必须是 null,无论具体原因是 no_price_source、insufficient_weekly_bars,还是任何 detector-json 拒绝原因。它绝不是「所有字段为 false 的占位 dict」。
这条不变量的价值在于消费者侧:下游只需看 verdict 一个字段,就能决定 checks.* 是否可安全读取,而不必按 verdict_reason 或「结果由哪条代码路径产生」分支。源码在两条路径上都遵守它:
- run_weekly_price_action() 在
n < min_weeks时返回"checks": None, "swing_levels": None; - CLI 早退路径 _insufficient_data_output() 统一构造同样的形状,
weekly_bars_used: 0、last_completed_week: None、handoff.price_action.stop_reference: None。
测试从两个层面固定该不变量:test_insufficient_data_below_min_weeks 断言纯函数层的 checks is None;CLI 层则有多条 INSUFFICIENT_DATA 端到端用例。
九、图表面走查(Chart-Mode Walkthrough)
当用户提供周线图并要求逆向确认读数(而不是、或不仅是跑脚本)时,按原文档的 5 步执行:
- 确认要 fade 的拥挤方向(
CROWDED_LONG/CROWDED_SHORT)——从用户处取得,或来自先前的cot-contrarian-detector/news-reaction-failure-analyzer结果。 - 目视扫描最近
signal_recency_weeks(默认 4)根周线,按完全相同的严格定义核对三种形态:新的 swing-lookback 极值、收盘穿越前一周反向价位、周内刺穿后失败、3 周内被否的收盘突破。 - 检查第 2 步找到的任何形态之后,市场是否又创出拥挤方向的新收盘极值(延续性否决)。
- 识别最近的 5 周分形 swing high/low 作为止损参考。
- 输出同样的
mode: chartYAML 块,用目视读数填写checks.*;window_weeks_used类字段可以标注为近似(图面无法像脚本那样精确数 bar)——必须在detail中显式说明这一点,而不是编造虚假精度。
第 5 步的「禁止虚假精度」是本清单少见但很重要的自律条款:图面模式允许不精确,但不允许把不精确伪装成精确。
十、保守分歧规则
如果图面模式与脚本模式对同一 symbol/direction 都产出了结果,而判定不一致,最终判定取 NOT_CONFIRMED,verdict_reason: mode_disagreement,并把两份子结果同时附上供用户对照——绝不静默地选择其中一个模式。
如果其中一个模式返回 INSUFFICIENT_DATA,另一个返回干净判定(CONFIRMED 或 NOT_CONFIRMED),则干净判定有效,只需注明另一模式的不足,而不将其视为分歧。
这两条在处理上完全不同:前者是「有争议,降级为不确认」,后者是「一方弃权,另一方继续」。混淆二者会导致可用证据被无谓丢弃,或冲突证据被静默吞掉。
十一、脚本模式实战:CLI、参数与取数回退链
11.1 两条典型调用
方向直接给定(注意 --symbol 既可以是映射过的 COT 代码,也可以直接是普通价格 ticker):
python3 skills/technical-analyst/scripts/check_weekly_price_action.py \
--symbol BT --direction CROWDED_LONG --as-of 2026-07-15 \
--output-dir reports/
方向从 cot-contrarian-detector 的报告里解析:
python3 skills/technical-analyst/scripts/check_weekly_price_action.py \
--symbol BT --detector-json reports/cot_crowding_2026-07-12.json \
--as-of 2026-07-15 --output-dir reports/
运行依赖极简,requirements.txt 只声明 requests>=2.31.0;requests 缺失时 PriceClient.__init__ 会打印带 pip install -r .../requirements.txt 的提示并以退出码 2 结束(check_weekly_price_action.py#L209-L221)。
11.2 完整参数表
| 参数 | 默认值 | 说明 |
|---|---|---|
--symbol |
必填 | COT 代码(走映射)或普通价格 ticker(直接当 FMP 代码用) |
--price-symbol |
无 | 覆盖价格源映射,跳过整条 fallback 链,price_source 记为 explicit_override |
--direction |
无 | CROWDED_LONG / CROWDED_SHORT;与 --detector-json 二选一 |
--detector-json |
无 | cot-contrarian-detector 的 JSON 报告路径 |
--max-detector-age-days |
10 | detector 数据老化的容忍上限(边界值本身被接受) |
--as-of |
今天 | 信息截止日(YYYY-MM-DD),同时是报告文件名后缀 |
--swing-lookback-weeks |
13 | swing 窗口 |
--extreme-lookback-weeks |
52 | extreme 窗口 |
--signal-recency-weeks |
4 | 信号新鲜度窗口 |
--min-weeks |
30 | 已完成周数硬下限,必须 ≥ 1 |
--output-dir |
reports/ |
报告落盘目录 |
--format |
both |
json / md / both |
--api-key |
无 | 覆盖 FMP_API_KEY 环境变量 |
--sleep-seconds |
0.25 | 请求间最小间隔(简单限速) |
--min-weeks 有专门的 argparse 类型校验 _min_weeks_type():若允许 0 或负数,n < min_weeks 的兜底判断会被静默绕过(0 < 0 为 False),空数据就会错报成 NOT_CONFIRMED 而不是 INSUFFICIENT_DATA。测试组 TestMinWeeksValidation 覆盖了 0、负数、非整数三种拒绝路径,以及退出码 2 与错误信息含 min-weeks / >= 1 的断言。
11.3 价格源回退链
脚本使用 FMP 的 stable 全量 EOD 端点,并按 PRICE_SOURCE_CHAINS 逐级回退。映射是 {COT 代码: [(价格代码, 类型, invert), ...]},三元组按顺序尝试,HTTP 错误或行数为 0 都算失败,第一个成功者胜出:
| COT 代码 | 回退链 | 备注 |
|---|---|---|
ES |
ESUSD |
单一期货源 |
NQ |
NQUSD → QQQ |
NQUSD 在该 API key 上返回 402,实际会走 ETF |
YM / QR |
YMUSD/RTYUSD → DIA/IWM |
指数期货 → ETF 代理 |
VX |
VXUSD |
无代理,实测 200/0 行 → no_price_source |
GC / SI |
GCUSD / SIUSD |
贵金属期货 |
HG / PL / PA |
期货 → CPER / PPLT / PALL |
含 ETF 代理 |
CL |
CLUSD → BZUSD → USO |
三级链 |
HO / ZQ |
单一期货源 | 无代理,失败即 no_price_source |
ZT/ZF/ZN/ZB |
期货 → SHY/IEI/IEF/TLT |
国债期货 → 期限相近 ETF |
DX |
DXUSD → UUP |
美元指数 |
B6/E6/J6/S6/D6/A6/N6 |
GBPUSD/EURUSD/JPYUSD/CHFUSD/CADUSD/AUDUSD/NZDUSD |
外汇对 |
BT |
BTCUSD |
加密,含周末 bar |
ZC/ZS/ZM/ZL/ZW |
对应 *USD |
农产品期货 |
模块 docstring(check_weekly_price_action.py#L17-L33)记录了 2026-07 的实测结论:stable/historical-price-eod/full 对 GCUSD、ESUSD、BTCUSD、GBPUSD 以及 ETF 代理 QQQ/IEF/UUP 确认可用;NQUSD 返回 402(与 light 端点同等级限制),因此回退链照常生效。
两个已验证的陷阱:
- 字段名陷阱:
full端点用close,light端点用price。build_sorted_daily_series() 用row.get("close", row.get("price"))防御性兼容两者,缺date/open/high/low或两者皆缺的行直接丢弃,重复日期保留最后一次出现。 - 未映射 symbol 不报错:若
--symbol不在映射表中,chain退化为[(symbol, "direct", False)],即直接当作 FMP ticker 使用。这是刻意的——本技能覆盖股票、指数、加密与外汇,不只服务 COT 跟踪的期货。
11.4 取数窗口与 as-of 无前视
weeks_needed = max(extreme_lookback_weeks, min_weeks) + signal_recency_weeks + WEEKS_FETCH_BUFFER,其中 WEEKS_FETCH_BUFFER = 10。多取 10 周是为了让 52 周 extreme 窗口、recency 窗口与 min_weeks 下限在节假日稀疏的日历下仍有真实周 bar 可用。
as-of 是信息截止日,且截断发生在重采样之前:fetch_price_series() 先 build_sorted_daily_series(),再 <a href="https://link.gitcode.com/i/a9562d1ff5af31f1796006178e20ae8b" target="_blank">b for b in daily_bars if b["date"] <= as_of];某些源若全部 bar 都在 as_of 之后,会按「0 行」同样降级。重采样层 [resample_weekly() 也有第二道闸:日 bar 先按 as_of 过滤,且包含 as_of 的那个 ISO 周总是被排除——它是进行中的周,无论是否已经凑满一周 bar。
这条链路的行为被多组测试锁死:
TestAsOfInformationCutoff::test_daily_bars_never_include_dates_after_as_of断言返回日期恰为前 70 个交易日;test_current_in_progress_week_always_excluded断言只有进行中的一周时返回空列表;test_holiday_short_week_still_counts_as_completed断言历史上一周只有 3 个交易日(节假日缩短)时仍按完整周重采样,不丢弃;test_bt_style_weekend_bars_attribute_to_own_iso_week断言加密 24/7 市场的周日 bar 归属它自己的 Mon–Sun 周,而不是下一周——这使得结果不依赖 FMP 对加密数据采用 UTC 还是 ET 的日界约定。
十二、detector-json 守卫与数据新鲜度
12.1 方向解析的五类拒绝
resolve_direction_from_detector() 处理的是不可信的 JSON:语法合法但形状错误,也绝不允许崩溃。行为按原文档与 docstring 分四组:
- symbol 不在
markets[]中,或出现在skipped[]中 →detector_missing_symbol。 classification == NEUTRAL→not_crowded(fail-closed;只有显式--direction才能覆盖)。若分类既不是NEUTRAL也不是两个CROWDED_*之一 → 同样按detector_missing_symbol拒绝。run_context.data_date缺失/空 →detector_missing_data_date;非字符串 →detector_invalid_data_date;无法解析 →detector_invalid_data_date;晚于--as-of→detector_future_data_date;早于--as-of超过--max-detector-age-days→detector_json_stale。data_date是必填项:run_context.as_of是运行日而非数据 vintage,绝不替代缺失的data_date。- 对每个显式给出的选中市场 row/map vintage 施加同样的日期守卫;旧的遗留报告可以省略 row/map 日期并回退到报告级日期,但显式存在却非法的日期永不回退。
枚举型失败被一个参数化测试矩阵覆盖得很彻底:test_cot_market_vintage.py 用 19 组参数组合固定了 stale / future / missing / invalid 的边界,包括 20260707(整数)、[]、{}、"bad-date"、"2026-07-07T00:00:00Z"(首 10 字符解析保持兼容)等形态。特别值得注意的两条:
test_stale_market_does_not_poison_fresh_other_symbol:某个 symbol 的 row 日期陈旧,不会污染另一个新鲜 symbol 的解析。test_fresh_row_cannot_bypass_stale_report_date:新鲜的 row 日期不能绕过陈旧的报告级data_date。test_vintage_resolution_does_not_mutate_the_input:解析过程不修改入参 dict(比较解析前后序列化结果)。
12.2 选中 COT 市场的新鲜度校验(原文档末节展开)
对选中市场,需要同时校验 run_context.data_date 以及每一处提供的 vintage:markets[].data_date 与 data_provenance.market_data_dates[symbol]。每个值都必须非空、可解析、不晚于 --as-of、且不早于 --as-of 超过 --max-detector-age-days(边界值本身被接受)。审计年龄取最老的合法日期;原始 run context 保持不变。
细则:
- 遗留报告可以省略 row/map 日期并回退到报告日期;
- 显式存在的非法/
null/空日期,或畸形的 provenance/map 容器,一律以既有的 missing / invalid / future / stale 原因码 fail-closed; - 其他 symbol 的 row/map 日期不能替代选中市场的 vintage;
- 既有的「取前 10 个字符解析日期」保持兼容——这不是更严格的完整时间戳或 provenance schema 校验器。
源码对应 _market_vintage_values() 与紧接其后的循环:data_provenance 缺失时直接返回 row 值;容器畸形(不是 dict)返回 None 触发 detector_invalid_data_date;循环内逐个校验并把最老者写入 ctx["data_date"] 与 ctx["detector_age_days"]。测试 test_stale_market_does_not_poison_fresh_other_symbol 同时验证了 data_provenance.market_data_dates 里其他 symbol 的陈旧日期不会影响当前 symbol。
最强的一条保障是 test_cli_emits_stale_refusal_before_any_provider_call:它 monkeypatch 掉 socket.socket.connect,令任何网络尝试抛错,然后断言 CLI 在发起任何 provider 调用之前就产出了 detector_json_stale 报告,且 blocked.assert_not_called() 通过。也就是说,一个陈旧或畸形的 detector 报告不会烧掉一次价格请求。
12.3 JSON 读取的两级失败与脱敏
load_json_file() 返回 (data, error, reason),用 reason 区分两种截然不同的失败:
"unreadable":文件缺失、不可读、非 UTF-8,或本身是目录;"parse_error":文件能打开也能解码,但不是合法 JSON。
关键在于捕获 (OSError, UnicodeError) 而非只捕获 OSError——可读但非 UTF-8 的文件会抛 UnicodeDecodeError,它是 ValueError/UnicodeError 的子类而不是 OSError,早期版本正是因此逃逸并以 traceback 崩溃。MemoryError 等无关异常被刻意不捕获:它们不属于「这个输入有问题」。
API key 脱敏是双层设计(_redact()):基于值的脱敏(主层)+ 基于模式的家族脱敏(次层)。原因是 requests 的异常会把完整请求 URL(含 ?apikey=...)塞进 str();仅靠模式只能抓住带 apikey 标记的形状,而基于值替换(传入已知 secret)也能抓住完全无标记的裸 key。四条正则覆盖 apikey=...、"apikey": "..."、'apikey': '...'、apikey%3D...,单测还额外固定了 apikey = SECRET(带空格)与「纯值、无标记」两种形态。
十三、护栏:这套判定不该被怎么用
原文档列出六条护栏,每条都值得在实盘前后各读一遍:
- 只给判定,永不单独构成交易建议。 它确认的是 5 步中的第 3 步;进场(第 4 步)与离场(第 5 步)仍是手工且仍然必需;仓位规模属于
position-sizer/futures-position-sizer,不属于本清单。 INSUFFICIENT_DATA永不推进流水线。 已完成周数少于min_weeks、无可用价格源、或--detector-json不可读 / 语法非法 / 结构畸形 / 陈旧 / 未来日期 / 携带非CROWDED_*分类,全部 fail-closed(原因分别为detector_json_unreadable/detector_json_parse_error/malformed_detector_json/detector_json_stale/detector_future_data_date/not_crowded)——永不崩溃、永不无报告的裸非零退出、永不在数据不足时强行下结论。- 仅限周线周期。 整套定义完全建立在「已完成 ISO 自然周」上,对日线或日内价格行为不作任何陈述。
- 既有图表分析工作流保持不变。 本模式只在显式的逆向确认请求下启用(通常紧跟
cot-contrarian-detector与/或news-reaction-failure-analyzer);一句普通的「分析这张图」仍然走技能原本的纯技术分析流程(SKILL.md的 Steps 1–6)。这一「不干扰既有流程」的要求被契约测试test_contrarian_confirmation_section_present_and_positioned与test_existing_workflow_identity_phrases_untouched双重固定。 - 单信号 MEDIUM 是弱证据,不可与 HIGH 置信度的「双信号」或「全窗口极值」确认等同看待。
还有一条来自实现的隐含护栏:退出码约定。所有降级输入路径都以 exit 0 + 写出报告结束;只有三种情况例外——缺少 requests(exit 2)、缺少 API key(exit 1)、argparse 参数非法(exit 2)。这意味着任何自动化流水线都可以用「有没有报告文件」而不是「退出码非零」来识别失败,同时真正的基础设施问题仍然会显式报错。
十四、如何自行验证这套实现
该技能的全部逻辑可在离线环境验证。检测器层是纯函数,CLI 层用假的 requests.Session 打桩,因此不会产生真实 FMP 调用:
python3 -m pytest skills/technical-analyst/scripts/tests/test_weekly_price_action.py -v
python3 -m pytest skills/technical-analyst/scripts/tests/test_check_weekly_price_action.py -v
python3 -m pytest skills/technical-analyst/scripts/tests/test_cot_market_vintage.py -v
python3 -m pytest skills/technical-analyst/scripts/tests/test_skill_contract.py -v
- test_weekly_price_action.py 覆盖
build_sorted_daily_series、resample_weekly、compute_prior_window、四个检测器、compute_swing_levels、synthesize_verdict、compute_confidence与顶层编排器;合成 bar 的构造函数make_weekly_bars()会刻意构造「单调且乏味」的序列,让每个用例只需覆写自己关心的 bar。 - test_check_weekly_price_action.py 覆盖价格源回退链(402 落 ETF、0 行推进链、全链失败 →
no_price_source、close/price字段回退)、as-of截断、detector-json 各类拒绝、--min-weeks校验、报告生成与脱敏。 - test_cot_market_vintage.py 覆盖选中市场 vintage 的完整参数矩阵与「拒绝发生在任何网络请求之前」。
结语
这份清单的价值不在于新增了三个指标,而在于把「图表判断」拆成了可被两种消费者一致执行、且默认 fail-closed 的判定程序:方向约定统一镜像、所有比较严格不等、窗口逐周截断并如实报告用量、failed_breakout 的 week_of 明确锚定失败周、延续性否决永远压过已触发信号、INSUFFICIENT_DATA 时 checks 恒为 null、图面与脚本分歧时强制降级为 NOT_CONFIRMED。落地使用时只需记住它的边界:这确认的是 5 步流程的第 3 步,输出是判定而非建议,进场、离场与仓位规模仍在它之外。