claude-trading-skills 逆向确认清单(Shapiro Step 3):周线价格行为、三项信号与 fail-closed 输出契约

原创2026-11-15 18:17:381,989 阅读
文章标签:金融科技AI 技能人工智能数据分析

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 步,前两步与本步的衔接关系在原文档中有明确定义:

  1. Step 1:cot-contrarian-detector 判定某个市场是否拥挤(CROWDED_LONG / CROWDED_SHORT / NEUTRAL)。
  2. Step 2(可选):news-reaction-failure-analyzer 检验市场是否对有利消息失去反应。
  3. Step 3(本文主题):确认周线图本身是否在价格行为上给出反转证据。
  4. 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)

配套有三条硬性语义:

  1. 「前 N 周」严格排除被评估的那一周本身。 实现见 compute_prior_window():start = max(0, idx - lookback_weeks)、window = weekly_bars[start:idx],切片右端开区间天然排除 idx。
  2. 窗口截断是「逐评估周」而非「逐运行」。 当某个被评估周之前的历史不足配置窗口时,窗口收缩到实际可用量,并把实际使用量写进该检查自己的结果块(swing_window_weeks_used / extreme_window_weeks_used / window_weeks_used)。
  3. 置信度 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 的四级优先

原文档给出的合成顺序不可调换:

  1. 已完成周数少于 min_weeks,或没有可用价格源 → INSUFFICIENT_DATA(insufficient_weekly_bars / no_price_source)。
  2. 延续性否决触发(信号之后出现拥挤方向的新收盘极值,或完全无信号但 recency 窗口内出现新收盘极值)→ NOT_CONFIRMED(continuation_intact)。这一条永远压过已触发的信号。
  3. 否则,若三项检查中任意一项在 recency 窗口内触发 → CONFIRMED,verdict_reason 取产出最新触发信号的那个检测器(key_reversal / failed_extreme / failed_breakout)。
  4. 否则 → 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 步执行:

  1. 确认要 fade 的拥挤方向(CROWDED_LONG / CROWDED_SHORT)——从用户处取得,或来自先前的 cot-contrarian-detector / news-reaction-failure-analyzer 结果。
  2. 目视扫描最近 signal_recency_weeks(默认 4)根周线,按完全相同的严格定义核对三种形态:新的 swing-lookback 极值、收盘穿越前一周反向价位、周内刺穿后失败、3 周内被否的收盘突破。
  3. 检查第 2 步找到的任何形态之后,市场是否又创出拥挤方向的新收盘极值(延续性否决)。
  4. 识别最近的 5 周分形 swing high/low 作为止损参考。
  5. 输出同样的 mode: chart YAML 块,用目视读数填写 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 分四组:

  1. symbol 不在 markets[] 中,或出现在 skipped[] 中 → detector_missing_symbol。
  2. classification == NEUTRAL → not_crowded(fail-closed;只有显式 --direction 才能覆盖)。若分类既不是 NEUTRAL 也不是两个 CROWDED_* 之一 → 同样按 detector_missing_symbol 拒绝。
  3. 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。
  4. 对每个显式给出的选中市场 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(带空格)与「纯值、无标记」两种形态。

十三、护栏:这套判定不该被怎么用

原文档列出六条护栏,每条都值得在实盘前后各读一遍:

  1. 只给判定,永不单独构成交易建议。 它确认的是 5 步中的第 3 步;进场(第 4 步)与离场(第 5 步)仍是手工且仍然必需;仓位规模属于 position-sizer / futures-position-sizer,不属于本清单。
  2. 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)——永不崩溃、永不无报告的裸非零退出、永不在数据不足时强行下结论。
  3. 仅限周线周期。 整套定义完全建立在「已完成 ISO 自然周」上,对日线或日内价格行为不作任何陈述。
  4. 既有图表分析工作流保持不变。 本模式只在显式的逆向确认请求下启用(通常紧跟 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 双重固定。
  5. 单信号 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 步,输出是判定而非建议,进场、离场与仓位规模仍在它之外。

登录后查看全文
claude-trading-skills