claude-trading-skills technical-analyst 技能实战:周线图表技术分析与 Shapiro 逆向确认模式

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

claude-trading-skills technical-analyst 技能实战:周线图表技术分析与 Shapiro 逆向确认模式

本篇技术指南聚焦 claude-trading-skills 仓库中的 technical-analyst 技能:它如何把一张周线图拆解为趋势、支撑阻力、均线、成交量与形态五类可复核的证据,如何输出带概率与失效位的情景分析报告,以及它附加的 Contrarian Confirmation Mode(Shapiro 逆向流程第 3 步)如何在“拥挤持仓”背景下用三项严格定义的周线信号给出 CONFIRMED / NOT_CONFIRMED / INSUFFICIENT_DATA 裁决。读完本文,你将能按技能的既定方法论完成一次可审计的图表分析,并能独立运行 check_weekly_price_action.py 得到确定性的机读结论。


一、技能定位:纯图表、周线、概率化

技能元数据在 SKILL.md 的 frontmatter 中定义了触发条件:当需要分析股票、股指、加密货币或外汇的周线价格图表,需要趋势识别、支撑/阻力位、情景规划或概率评估,且要求完全不考虑新闻与基本面时使用本技能。

核心定位可以概括为四条硬约束:

维度 约定 依据
输入 用户提供的周线图表图片(主输入) SKILL.md
时间周期 仅周线,服务中长期视角 technical_analysis_framework.md
数据来源 图表本身,不抓取外部数据、不需要 API Key SKILL.md
输出 reports/ 下的 Markdown 分析报告,含概率情景 SKILL.md

需要注意,技能的“无 API Key”前提针对的是主工作流。它新增的逆向确认模式提供了一个可选的数据驱动兜底脚本,该脚本通过 FMP 接口取周线 OHLCV,因此那条路径需要 FMP_API_KEY(或 --api-key)。这两条路径是并列关系,不是替代关系,后文会分别展开。

五条核心原则

原文档给出的五条原则构成了整篇方法论的“宪法”,test_skill_contract.py 会断言其中的关键短语不得被后续改动侵蚀:

  1. Pure Chart Analysis(纯图表分析):所有结论只基于图中可见的技术数据。
  2. Systematic Approach(系统化):每张图走同一套结构化方法论,而不是凭感觉挑指标。
  3. Objective Assessment(客观评估):聚焦可观察形态,压制主观偏好。
  4. Probabilistic Scenarios(概率情景):把未来表达为带权重的场景,而不是单一预测。
  5. Sequential Processing(串行处理):逐张分析、即时落盘,禁止批量“糊”在一起。

第 5 条在多图场景下尤其重要,它直接决定了报告文件的可追溯性。


二、六步分析工作流

SKILL.md 把一次分析拆成六个可机械执行、也可人工复核的步骤。

Step 1:接收图表

收到一张或多张周线图后,先做三件事:确认所有图片已收到、统计待分析图表数量、记录用户特别关注的点(例如“我关心它能否突破阻力”)。然后逐张进入分析,不允许一次性对多张图交叉推断。

Step 2:加载分析框架

正式看图前,必须先读取 technical_analysis_framework.md。这一步在 Agent 语境下不是形式主义:它保证同一技能在不同会话中读到的判据完全一致,避免“这次用 20 周均线、下次用 30 周均线”的漂移。框架覆盖趋势分类、支撑阻力识别、均线解读、成交量分析、形态与K线、情景与概率赋权、以及分析纪律。

Step 3:六维度系统分析

这一步是整篇文章的技术密度核心,六个子步骤构成一条不可跳步的证据链:

  • 3.1 趋势分析:判定方向(上升/下降/横盘)、强度(强/中/弱)、持续时长与潜在衰竭信号,并检查是更高高点+更高低点,还是更低高点+更低低点。
  • 3.2 支撑与阻力:标注水平支撑、水平阻力、趋势线支撑阻力、支撑阻力角色互换,以及多因子重合的 confluence 区域。
  • 3.3 均线分析:价格相对 20 周、50 周、200 周均线的位置;均线排列(多头/空头/中性);斜率(上行/下行/走平);近期或即将发生的交叉;均线作为动态支撑阻力的表现。
  • 3.4 成交量分析:整体量能趋势;放量点出现的上下文(在支撑处、在阻力处、在突破处);量价是确认还是背离;是否出现量能高潮/衰竭。
  • 3.5 形态与价格行为:反转形态(锤子、射击之星、吞没等)、持续形态(旗形、三角等)、显著K线组合、最近的突破或破位。
  • 3.6 综合观察:把上述要素整合成当前评估,指出最具影响力的因素、冲突信号与模糊之处,并锁定决定后续方向的关键价位。

框架文件对每一维度都给了可判定的判据,而不是形容词。例如支撑有效性的门槛是“至少 2–3 次反弹”,强支撑则是“3 次以上触碰、存在时间以月/年计、触碰时放量、且与其他技术因子重合”;均线方面明确了 20 周≈4 个月、50 周≈1 年、200 周≈4 年的对应关系,黄金交叉定义为 20 周上穿 50 周、死亡交叉为下穿。

Step 4:构造概率情景

每张图必须产出 2–4 个互斥情景,每个情景包含六要素:

  1. 情景名称(如“Bull Case: Breakout Above Resistance”);
  2. 概率估计(全部情景必须合计 100%);
  3. 描述:该情景意味着什么、如何演进;
  4. 支撑因素:至少 2–3 条技术证据;
  5. 目标价位;
  6. 失效位:明确到具体价位的否定条件。

原文档给出的典型分布是:基准情景 40–60%、乐观情景 20–40%、悲观情景 20–40%、备选情景 5–15%,并要求“根据支撑因素强度调整,确保概率真实且合计 100%”。框架文件进一步把概率区间与证据强度绑定:50–70% 对应顺应现有趋势、多因子确认、近期价格行为支持、且有清晰失效位的情景;25–45% 对应需要趋势改变或重大突破的情景;5–20% 对应与多数技术因子相悖但技术上可能的情景。

情景还必须定义失效逻辑:看涨情景的失效是跌破关键支撑,看跌情景的失效是升破关键阻力,区间情景的失效则是任一方向的突破。

Step 5:生成报告

以 analysis_template.md 为模板,报告必须包含十个部分:图表概览、趋势分析、支撑阻力、均线分析、成交量、形态与价格行为、当前市场评估、情景分析、总结、免责声明。

文件命名规则为 [SYMBOL]_technical_analysis_[YYYY-MM-DD].md,例如 SPY_technical_analysis_2025-11-02.md,统一落在 reports/ 目录。

Step 6:多图顺序处理

多张图时,必须“完整跑完 Steps 3–5 并保存第一份报告”后再进入第二张。原文明确写了 Do not batch analyses——批量分析会让后面的图污染前面的判断,也让报告失去单图可追溯性。


三、报告模板的字段级拆解

模板并非一张空表格,它把分析方法论固化成了字段,使报告可被比对、可被下游解析。analysis_template.md 的头部要求四个元字段:代码、周期(固定 Weekly)、分析日期、分析者;正文则用统一结构约束表达:

**Ticker/Symbol**: [Symbol Name]
**Timeframe**: Weekly
**Analysis Date**: [YYYY-MM-DD]
**Analyst**: Claude Technical Analyst

其中“Moving Average Analysis”段落要求逐条声明价格相对 20/50/200 周均线的位置(Above / Below / At),再单独声明排列、斜率、交叉;“Volume Analysis”要求把观察压缩成 3 条要点,并明确给出“成交量是确认还是矛盾”的结论;“Scenario Analysis”要求每个情景都以 ### Scenario N: [Name] - **[XX]% Probability** 的标题格式书写,附支撑因素、目标位与失效位。

这种“字段即契约”的设计有实际收益:当你需要横向比较多只标的的均线结构时,字段位置一致,抽取成本极低。


四、质量标准的三个维度

SKILL.md 把质量要求分成客观性、完整性、清晰性三组,并在框架文件中配套了“常见陷阱”清单。

客观性

  • 只基于图中可观察数据,禁止引入新闻、基本面、情绪;
  • 禁止“I think”“I feel”式表述;
  • 信号模糊时必须显式表达不确定性;
  • 必须同时呈现看涨与看跌可能性,以对抗确认偏误。

完整性

  • 模板十节全部作答,不得留空;
  • 支撑、阻力、目标必须给出具体价位;
  • 概率必须由技术因素支撑,而非拍脑袋;
  • 每个情景都要有失效位;
  • 必须写明分析的局限与前提。

清晰性

  • 术语使用准确;
  • 语言专业、结构逻辑化;
  • 用价位而非“附近”“高位”这类模糊描述;
  • 情景之间必须互斥,不能出现“既可能突破也可能回落”这种互相包含的伪情景。

六个常见陷阱

框架文件列出的坑值得单列,因为它们几乎覆盖了人工技术分析最常见的失败模式:过度复杂(指标堆到分析瘫痪)、忽略成交量、硬凑形态、忽视周期差异(周线与日线可能给出相反结论)、脱离上下文、以及“过于确定”——市场是概率系统,不是确定系统。


五、Contrarian Confirmation Mode:把图表判读变成可复算的裁决

这是技能中技术含量最高的增量部分,也是唯一具备可执行脚本、机读输出与失败关闭语义的模块。它对应 Jason Shapiro 逆向流程的第 3 步。

5.1 定位:加法模式,不覆盖原工作流

按 SKILL.md 的说明,该模式是 ADDITIVE 的:它只在收到明确的“逆向确认”请求时激活——通常发生在 cot-contrarian-detector(第 1 步)已标记某市场持仓拥挤,且可选地由 news-reaction-failure-analyzer(第 2 步)确认该市场对利好/利空新闻没有反应之后。普通的“帮我分析这张图”请求仍然走前面 Steps 1–6 的原流程。

它要回答的问题很窄:周线图是否已经出现“拥挤方向正在反转”的价格行为证据。候选证据只有三类——周线关键反转、周内假突破极值、以及确认后被打回的失败突破——并且全部可能被“延续否决”推翻。

5.2 输入

  • 拥挤方向:CROWDED_LONG 或 CROWDED_SHORT,来自用户,或来自上一份 cot-contrarian-detector 报告;
  • 图表图片(主输入):用户提供的周线图,按后文的严格定义判读;
  • 脚本兜底(数据驱动):当没有图表、或需要可审计的确定性结果时,运行 check_weekly_price_action.py。

方向约定必须记牢:淡化(fade)一个 CROWDED_LONG 市场,找的是看跌反转证据,观察高点、观察收盘跌破前低、观察上攻失败;CROWDED_SHORT 是完全镜像(把 high↔low、above↔below 互换)。所有比较都是严格不等式:等于前极值不算新极值,收盘价恰好落在前一周低点不算反转,恰好等于突破位不算突破或失败。理由在 contrarian-confirmation-checklist.md 中写得很直白:仅仅“打平”某个价位并未产生新证据。

5.3 窗口术语

窗口 默认值 作用
swing-lookback weeks 13 定义“近期”高低点,驱动周线关键反转的触发
extreme-lookback weeks 52 定义较长周期极值,供假极值、失败突破、延续否决使用;也是置信度 HIGH 的加分条件
signal-recency weeks 4 信号时效窗口,超期信号不构成确认
min_weeks 30 硬下限,完成周数不足即 INSUFFICIENT_DATA

三条容易踩空的语义细节:

  1. “prior N weeks” 永远排除被评估的那一周本身;
  2. 窗口截断按“被评估周”计算,而不是按“整次运行”计算——同一次时效扫描中,不同周可能有不同的可用历史(例如刚好卡在 min_weeks 下限时的 26 周与 29 周),而置信度 HIGH 的 52 周极值条件只读“实际触发的那一周”的窗口大小;
  3. failed_breakout 的 week_of 是失败周,绝不是突破周。

这些默认值在源码中以常量固化:weekly_price_action.py 定义 SWING_LOOKBACK_WEEKS_DEFAULT = 13、EXTREME_LOOKBACK_WEEKS_DEFAULT = 52、SIGNAL_RECENCY_WEEKS_DEFAULT = 4、MIN_WEEKS_DEFAULT = 30,以及 CONFIDENCE_HIGH_EXTREME_WEEKS = 52。

5.4 三项信号检查

检查一:周线关键反转(Weekly Key Reversal)

该周 HIGH 严格大于前 swing-lookback 个完成周的最大 high,且该周 CLOSE 严格低于前一周的 LOW。CROWDED_SHORT 镜像为:新 swing-lookback 低点 + 收盘严格高于前一周 high。

这是唯一引用两个窗口的检查:swing 窗口决定“是否触发”,而更大的 extreme 窗口只用来判断“同一个新高/新低是否也是完整极值窗口的极值”,后者只喂给置信度门,不影响触发本身。

检查二:假极值(Failed Extreme,周内试探失败)

在信号时效窗口内,某周 HIGH 严格突破前 extreme-lookback 的 high,但同一周收盘又回到该 high 之下。与关键反转的区别是:它不要求前一周自身的 low/high 关系,且使用 extreme 窗口而非 swing 窗口。

检查三:失败突破(Failed Breakout,确认后被打回)

在第 B 周出现一次收盘价突破前 extreme-lookback high 的真实收盘突破(不是周内插针),随后在 ≤3 个完成周内出现一次收盘回到该突破位之下的失败。week_of 记录失败周,突破周只出现在 detail 文本里。

这条规则有三个深意:

  • 只有失败周需要落在时效窗口内,突破周 B 可以更老;
  • 因为 B 天然早于失败周,它永远不会在之后被当成“新收盘极值”而否决自己的信号(无自我否决);
  • 同一突破只有第一次收盘回穿算失败,之后再次回穿不构成第二次独立失败。

清单给出的典型例子是:突破发生在 W 周、失败发生在 W+2 周、之后无更多K线 → CONFIRMED;若 W+3 周(仍在时效窗口内)又创出新收盘高点,则变为 NOT_CONFIRMED,原因 continuation_intact,延续否决生效。

源码中的 3 周限制写入循环上界:for f in range(b + 1, min(b + 3, n - 1) + 1),并在命中第一次失败后 break,从而保证“只认第一次回穿”;候选突破的搜索起点放宽 3 周(b_start = max(0, recency_start - 3)),因为突破周本身可以落在时效窗口之外。

5.5 延续否决(Continuation Veto)

与三项检查完全独立:市场是否在比最新触发信号更晚的周,创出了拥挤方向上的新收盘极值(CROWDED_LONG 看最高收盘价,相对每个被评估周自己的 prior extreme-lookback 收盘窗口;不是周内 high)?

  • 若有信号触发,扫描从该信号 week_of 的下一周开始,因此信号周及其之前的一切都不可能自我否决;
  • 若完全没有信号触发,扫描覆盖整个时效窗口,这样“一路 grinding 创新高、毫无反转迹象”的市场会得到正确的 continuation_intact,而不是泛泛的 no_reversal_evidence。

实现上 detect_continuation() 返回最早符合条件的那一周(延续恢复的时刻),因为裁决只需要知道“信号之后是否发生过延续”。否决的优先级是绝对的:即使三项检查全部触发,只要延续否决成立,结果就是 NOT_CONFIRMED。

5.6 摆动位(Swing Levels)与止损参考

摆动高点的定义是 5 周分形:某完成周的 high 严格大于其左右各 2 个完成周的 high;摆动低点镜像。nearest 取 extreme-lookback 窗口内最近的这类枢轴。

若该窗口内不存在任何分形枢轴,则回退到(更小的)swing-lookback 窗口的最大 high / 最小 low,并标记 fallback: true,让消费方知道这是一个较弱的非分形替代。

stop_reference 跟随淡化方向而不是拥挤方向:淡化 CROWDED_LONG 意味着做空,止损放在上方最近的 swing high;淡化 CROWDED_SHORT 意味着做多,止损放在下方最近的 swing low。源码里这段逻辑只有四行,但它是下游仓位计算唯一的价位输入。

关于分形搜索边界,weekly_price_action.py 有一个容易忽略的细节:一个枢轴需要左右各 2 周,所以 search_end = n - 3——最近可能的枢轴是倒数第三个完成周,而不是最后一周。这个约束保证了“右侧尚未完成”不会制造假枢轴。

5.7 裁决合成(fail-closed)

顺序固定,且尽早返回:

  1. 完成周数 < min_weeks,或没有可用价格源 → INSUFFICIENT_DATA(insufficient_weekly_bars / no_price_source);
  2. 延续否决成立 → NOT_CONFIRMED(continuation_intact),总是优先于已触发的信号;
  3. 否则,三项检查中任意一项在时效窗口内触发 → CONFIRMED,verdict_reason 取最新触发信号对应的短标记(key_reversal / failed_extreme / failed_breakout);
  4. 否则 → NOT_CONFIRMED(no_reversal_evidence)。没有证据永远不等于确认。

多个检测器在同一周触发时的平局,按 _TRIGGER_ORDER 固定顺序打破(关键反转优先),形成确定性结果。

5.8 置信度:为什么单信号 MEDIUM 是“弱证据”

HIGH 的充分条件只有两个,满足其一即可:

  • 时效窗口内至少 2 种不同检测器触发(同一检测器重复触发不重复计数——模块本身每个检测器只上报最新一次触发,所以这是天然成立的);
  • 触发的 weekly_key_reversal 的新高/新低同时是全窗口极值:extreme_window_weeks_used >= 52 且 is_full_window_extreme 为真。

其余为 MEDIUM;LOW 在 v1 中保留、永不输出。

清单特别强调:单信号的 MEDIUM 是刻意设计的弱证据。一次关键反转、一次假极值或一次失败突破,单独看只是“值得继续观察”,不足以加大仓位。confidence 被写进 handoff 块,正是为了让下游(contrarian-setup-gate)能区别对待单信号与双信号/全窗口证据。

源码对应 compute_confidence(),其中 52 周门槛读取的是 CONFIDENCE_HIGH_EXTREME_WEEKS 常量而非 extreme_lookback_weeks 参数——这样即便调用方传入非默认的 extreme 窗口,置信度门仍是一个定义明确的(可能不可达的)门槛,而不是浮动目标。

5.9 输出契约

无论图表模式还是脚本模式,输出形状一致:

symbol: BT
direction: CROWDED_LONG
mode: data          # "chart" 表示 Claude 读取用户图表
verdict: CONFIRMED | NOT_CONFIRMED | INSUFFICIENT_DATA
confidence: HIGH | MEDIUM | LOW   # LOW 保留,v1 不输出
verdict_reason: 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,
  }

关键不变量:当 verdict: INSUFFICIENT_DATA 时,checks 与 swing_levels 一律为 null——不论原因是 no_price_source、insufficient_weekly_bars、还是任何 detector-json 拒收原因。下游可以只看 verdict 就决定 checks.* 是否可读,无需对 verdict_reason 分支,更不会拿到一个“全是 false 的占位字典”。这条不变量在 run_weekly_price_action() 与 CLI 的早退路径 _insufficient_data_output() 中同时实现,并有单测覆盖。

报告文件名固定为 ta_confirmation_<SYMBOL>_<as-of>.json 与 ta_confirmation_<SYMBOL>_<as-of>.md,写入 reports/。

5.10 COT 数据时效(vintage)校验

在脚本模式下,拥挤方向通常由上一份 COT 报告提供,因此必须先校验数据新鲜度。规则如下:

  • 校验对象是 run_context.data_date,以及所选市场的每一个显式提供的 vintage:markets[].data_date 与 data_provenance.market_data_dates[symbol];
  • 每个日期必须非空、可解析、不晚于 --as-of,且不早于 --max-detector-age-days 允许的最老边界(恰好等于边界是接受的);
  • 用最老的有效日期作为审计年龄,同时保持原始 run context 不被改写;
  • 历史遗留报告可能缺少行级/映射级日期,此时回退到报告日期;
  • 一旦某个日期字段显式存在但为 null/空/不可解析,或 provenance / map 容器结构损坏,立刻失败关闭,沿用既有 missing / invalid / future / stale 原因码;
  • 其他标的的行级/映射级日期不能替代所选市场的 vintage;
  • 日期解析沿用“取前 10 个字符”的既有兼容行为;这不是更严格的完整时间戳或 provenance schema 校验器。

5.11 保守分歧规则

如果图表模式与脚本模式对同一 symbol/direction 都给出了结果,而裁决不一致,最终裁决为 NOT_CONFIRMED,verdict_reason: mode_disagreement,并把两个子结果一并附上供人工对照——绝不静默地偏向某一种模式。

若一种模式返回 INSUFFICIENT_DATA、另一种返回干净裁决(CONFIRMED 或 NOT_CONFIRMED),则以干净裁决为准,并把另一模式的“数据不足”作为注记,而不是当成分歧处理。

5.12 护栏

  • 只出裁决,本身绝不是交易建议。它确认的是 5 步流程中的第 3 步;入场(第 4 步)与出场(第 5 步)仍需人工完成,仓位规模属于 position-sizer / futures-position-sizer,不属本模式。
  • INSUFFICIENT_DATA 永不推进流水线——对每种降级输入都失败关闭,且始终以退出码 0 结束并写出报告。
  • 仅周线周期。
  • 原图表分析工作流完全不变,本模式仅在明确请求时激活。
  • 单信号 MEDIUM 是刻意偏弱的证据。

六、CLI 实战:参数、调用与失败关闭

6.1 两种调用方式

没有图表、或需要可复算结果时,直接给定方向:

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/

第二种写法是完整 Shapiro 流水线里的标准姿势:--detector-json 提供“要逆着谁”,脚本才知道自己在确认“对什么的反转”。缺方向时脚本不会猜测,而是以 no_direction_provided 失败关闭。

6.2 完整参数表

参数解析位于 parse_arguments(),逐项含义如下:

参数 默认值 说明
--symbol 必填 COT 符号(走映射表)或普通价格 ticker
--price-symbol 无 覆盖价格源映射,直接指定取价符号(跳过回退链)
--direction 无 CROWDED_LONG / CROWDED_SHORT;与 --detector-json 二选一
--detector-json 无 cot-contrarian-detector 的 JSON 报告路径
--max-detector-age-days 10 报告数据日期的最大允许年龄
--as-of 当天 信息截止日(YYYY-MM-DD),同时用于截断与时效判定
--swing-lookback-weeks 13 关键反转的 swing 窗口
--extreme-lookback-weeks 52 极值窗口
--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 有一个专门的类型校验函数 _min_weeks_type():它拒绝 0 与负数。原因写在注释里——若允许 --min-weeks 0,n < min_weeks 这个失败关闭检查会因 0 < 0 为假而失效,近乎空的行情序列会错误地输出 NOT_CONFIRMED 而不是 INSUFFICIENT_DATA。这是一个典型的“参数校验即护栏”示例。

6.3 失败关闭原因码全表

脚本对每一种降级输入都返回 INSUFFICIENT_DATA 并写出报告(退出码 0),而不是抛栈或静默返回非零。可预期出现的原因码包括:

原因码 触发条件
no_direction_provided 既无 --direction 也无 --detector-json
detector_json_unreadable 文件缺失/不可读/非合法 UTF-8
detector_json_parse_error 文件能读但不是合法 JSON
malformed_detector_json JSON 合法但顶层不是对象
detector_missing_symbol symbol 不在 markets[] 中,或出现在 skipped[] 里
not_crowded 该市场 classification 为 NEUTRAL
detector_missing_data_date run_context.data_date 缺失或为空
detector_invalid_data_date 日期非字符串或无法解析
detector_future_data_date 数据日期晚于 --as-of
detector_json_stale 数据日期早于 --max-detector-age-days 允许的边界
no_price_source 回退链全部失败(HTTP 错误或 0 行)
insufficient_weekly_bars 重采样后完成周数 < --min-weeks

两个必须显式区分的失败:load_json_file() 用 reason 标签区分 unreadable 与 parse_error,并同时捕获 (OSError, UnicodeError)——因为“可读但不是 UTF-8”抛的是 UnicodeDecodeError(ValueError/UnicodeError 子类),不是 OSError,此前会让异常穿透并崩溃。MemoryError 等与“输入有问题”无关的异常则被有意放过。

真正会以非零退出码结束的只有两类环境问题:缺少 requests 依赖时 PriceClient 打印安装提示并 sys.exit(2);缺少 FMP API Key 时报错并 sys.exit(1)。这与“输入降级”严格区分:输入降级永远产出报告。

6.4 价格源回退链与代理数据告警

PRICE_SOURCE_CHAINS 为每个 COT 符号列出有序的取价候选,每个条目是 (price_symbol, kind, invert) 三元组,kind 取 futures 或 etf。回退判定规则是:HTTP 错误或返回 0 行即视为该源失败,第一个成功者胜出;--as-of 会在源被判定成功之前先做行级截断,若截断后无数据,等价于 0 行。

映射表覆盖利率(ZT/ZF/ZN/ZB/ZQ)、股指(ES/NQ/YM/QR)、外汇(B6/E6/J6/S6/D6/A6/N6)、贵金属(GC/SI/HG/PL/PA)、能源(CL/NG/RB/HO)、加密(BT)、农产品(ZC/ZS/ZM/ZL/ZW)以及波动率(VX)。其中 NQ→QQQ、YM→DIA、QR→IWM、ZN→IEF、ZB→TLT、DX→UUP 等都是文档化的期货→ETF 兜底;而 VX、HO、ZQ 在注释中被标注为“无代理”,取数失败就落到 no_price_source。

当最终使用的是 ETF 代理时,proxy_used: true 会被写进 run_context,Markdown 报告还会额外渲染一节 Proxy Data Caveat,说明 ETF 代理存在跟踪误差、费用拖累与展期时点差异,周线级别比较只能视为近似。这是本技能中少见的“主动声明数据妥协”的设计,对结论可信度的表达很重要。

模块 docstring 还记录了一个字段陷阱(对应仓库 #245 缺陷类):stable/historical-price-eod/full 用 close 字段,而 light 端点用 price。build_sorted_daily_series() 对两者都做防御性接受;同时它会丢弃缺少 date、open、high、low 或同时缺 close/price 的行,重复日期保留最后一条。

6.5 请求健壮性与密钥脱敏

_request_with_backoff() 对 429 与 5xx 做指数退避重试(默认最多 4 次,初始 1s),对 401/402/403/404 等非可重试 4xx 立即失败——因为这里的 402 是常规且预期的情况(意味着该源受限,应推进回退链),重试毫无意义。

脱敏采用双层策略:基于值(把已知 secret 直接替换成 ***REDACTED***)为主,基于模式(apikey=...、JSON 形式的 "apikey":"..."、URL 编码的 apikey%3d...)为辅。原因写在 check_weekly_price_action.py 的注释里:requests 的异常文本会内嵌完整请求 URL(含 ?apikey=...),仅靠模式匹配只能覆盖带 apikey 标记的形态,而仅靠值替换又可能漏掉变形写法,两层同时施加才足够。

6.6 取数窗口的算法

脚本并不按“自然年”取数,而是按窗口需求反推:

weeks_needed = max(extreme_lookback_weeks, min_weeks) + signal_recency_weeks + WEEKS_FETCH_BUFFER
from_date = as_of_date - timedelta(weeks=weeks_needed)

WEEKS_FETCH_BUFFER = 10 是为节假日稀疏日历预留的缓冲,保证 52 周极值窗口、时效窗口与 min_weeks 下限都有真实周线可用。这里不做前视取数(与新闻反应类技能的事件对齐需求不同),因为本脚本纯历史,且 --as-of 截断发生在“源是否成功”的判定之前。


七、底层实现:纯函数模块如何保证“图表模式与脚本模式判读一致”

方法论的可信度最终取决于实现是否严守定义。weekly_price_action.py 是一个零 I/O、零网络的纯函数模块,所有函数只接受 dict/list/标量并返回普通值,因此可以离线单测——这也是“图表模式与脚本模式判读一致”能够被验证的前提。

7.1 重采样:周线是怎么“切”出来的

resample_weekly() 的规则相当克制,但每条都有明确理由:

  • 先截断再重采样:任何 date > as_of 的日线先被丢弃,避免前视;
  • 含 as_of 的 ISO 周永远排除:它是进行中的周,无论已有多少根日线;被截止日切得不完整的周按“不完整”丢弃;
  • 非 as_of 周的节假日缩短周仍算完成周,正常聚合;
  • 加密/7×24 市场(如 BT):周日归属它自己的 Mon–Sun 周,而不是下一周,因此不受 FMP 的 UTC / ET 日界约定影响;
  • 聚合结果为 open 取首根、high 取最大、low 取最小、close 取末根、volume 求和,week_of 记为 ISO 周一日期。

对应测试覆盖了五种情形:基础 OHLCV 聚合、进行中周被排除、截止日落在周中导致整周被丢弃、节假日缩短周仍计入、以及 BT 风格周末K线归周的正确性(含“周日是本周最后一天”的两种 as_of 位置)。

7.2 窗口与检测器

compute_prior_window(bars, idx, lookback) 是全局唯一的窗口函数:start = max(0, idx - lookback),返回 bars[start:idx] 与实际长度。这个“按被评估周截断、并回报实际长度”的设计,直接支撑了前文提到的“window truncation is per-evaluated-week”语义,也解释了为什么 swing_window_weeks_used / extreme_window_weeks_used / window_weeks_used 会出现在每个检查块里——报告实际用了多少历史,而不是报告配置了多少。

三个检测器共享同一套扫描骨架:先算 recency_start = max(0, n - signal_recency_weeks),再在窗口内正序扫描,命中多个候选取最近一个(每个检测器只上报一次触发)。detect_weekly_key_reversal() 的循环起点额外取 max(recency_start, 1),因为第 0 周没有“前一周”可比。

7.3 测试即规范

skills/technical-analyst/scripts/tests/ 下四个测试文件分别守住不同层次的契约:

  • test_weekly_price_action.py 覆盖纯函数:重采样语义、窗口截断、三个检测器的严格不等式、week_of = 失败周、3 周失败上限、延续否决无自我否决、分形枢轴与回退、裁决合成优先级、置信度双路径。其中若干用例如“等于前高不算新高”“收盘恰好等于前一周低点不触发”“突破周永不作为 week_of 上报”“at least 2 distinct detector types → HIGH”直接就是方法论条款的可执行版本。
  • test_check_weekly_price_action.py 用假的 requests.Session 覆盖 CLI 逻辑:回退链、402 降级到 ETF 代理、0 行视为失败、detector-json 守卫、脱敏、报告生成,不发起真实网络请求。
  • test_cot_market_vintage.py 专门针对 §5.10 的 vintage 校验矩阵。
  • test_skill_contract.py 守住文档契约:frontmatter 必须声明“weekly price charts”与“without consideration of news or fundamental factors”;四个资源文件必须存在且被 SKILL.md 引用;逆向确认章节必须位于 ## Example Usage Scenarios 与 ## Resources 之间,且输出契约中的 CONFIRMED、weekly_key_reversal、stop_reference、handoff 等 token 与 ta_confirmation_<SYMBOL>_<as-of>.json 命名必须出现。最后两条断言(Chart Images、Pure Chart Analysis、Probabilistic Scenarios 仍逐字存在)是“不回归”守卫——新增模式不得侵蚀原有技能身份。

运行方式:

python3 -m pytest skills/technical-analyst/scripts/tests/ -v

运行时依赖只有 requests>=2.31.0,见 requirements.txt;安装方式为:

pip install -r skills/technical-analyst/requirements.txt

八、三种典型使用姿势

原文档给出了三个使用示例,可以直接映射为可复用的提示词模板。

示例一:单图分析

用户:“请分析这张标普 500 的周线图”
[提供图表图片]

技能的动作序列是:确认收到 → 读取框架文件 → 系统化五维分析 → 发展 3 个情景(例如 55% 看涨延续、30% 整理、15% 反转)→ 用模板生成报告 → 存为 SPY_technical_analysis_2025-11-02.md。

示例二:多图分析

用户:“分析这三张图:比特币、以太坊、纳斯达克”
[提供 3 张图片]

必须逐张走完整流程并保存,得到 BTC_...、ETH_...、NDX_... 三份报告,最后统一告知完成。这里的关键是“逐张完成再下一张”,而不是并行推断后统一输出。

示例三:聚焦型请求

用户:“我特别关心这只股票能否突破阻力,分析这张图”
[提供图表图片]

仍然执行完整系统分析,但在阻力位与突破概率上加重笔墨,情景设计围绕“突破 vs 被拒绝”展开,概率赋值明确引用成交量、趋势强度与距阻力位的距离。

示例四(新增能力):逆向确认

用户:“B6 刚被 COT 检测器标为 CROWDED_LONG,第 3 步确认一下周线价格行为”

此时才进入 Contrarian Confirmation Mode:优先用图表按三项检查判读,或以 --detector-json 运行脚本,输出 ta_confirmation_B6_<as-of>.json,verdict 与 stop_reference 通过 handoff.price_action 交给流水线下一步。


九、局限与正确使用边界

以下几点不是“注意事项”套话,而是这套方法在实现层面就承认的限制:

  1. 本技能不是预测器。它输出的是带概率与失效位的情景;模板的免责声明明确写着“这是概率评估,不是预测或投资建议”。
  2. 周线专用。所有定义都按完成的 ISO 日历周表述,对日线或分时价格行为没有任何陈述;混用周期会直接导致结论错位。
  3. ETD 代理会引入偏差。当 proxy_used: true 时,周线级别的高低点比较只能视为近似。
  4. 数据不足不构成弱结论。INSUFFICIENT_DATA 不是“倾向于不反转”,它就是“无法判断”,且永远不会推进下游流水线。
  5. 单信号 MEDIUM 必须谨慎对待。它被刻意设计成弱证据,用于触发“继续观察”,而不是“加大仓位”。
  6. 没有图表时不要假装读过图。若使用脚本兜底,报告里的 mode 应为 data;若使用图表判读,window_weeks_used 允许近似,但必须在 detail 中显式说明,而不是伪造精度。
  7. 本模式只确认流程第 3 步。入场、出场与仓位规模都在下游技能与人工决策中完成。

十、小结

technical-analyst 在一个技能里同时提供了两种互补的工作方式:面向单张图片的深度判读(六步工作流 + 十节模板 + 概率情景),以及面向流水线审计的确定性裁决(三项周线信号 + 延续否决 + 分形止损参考 + 机读契约)。

它的设计取向相当克制:所有比较都是严格不等式,所有窗口都回报“实际用了多少”,所有降级输入都失败关闭并留下报告,所有输出都有唯一且稳定的形状。想让这套能力在你的工作流中复现,最短路径是:先读 technical_analysis_framework.md 统一判据,再按 analysis_template.md 固定输出结构;需要机读结论时,直接运行 check_weekly_price_action.py 并消费 reports/ta_confirmation_*.json 中的 verdict 与 handoff.price_action。

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