Claude Trading Skills 技术分析师技能详解:周线图纯技术分析与 Shapiro 逆势确认模式实战

原创2026-11-14 18:43:281,938 阅读
文章标签:金融科技AI 技能人工智能数据分析

Claude Trading Skills 技术分析师技能详解:周线图纯技术分析与 Shapiro 逆势确认模式实战

technical-analyst 是 claude-trading-skills 中负责“看图说话”的技能:它把用户提供的周线图拆解为趋势、支撑阻力、均线、量能与形态五个维度,并输出带概率、目标位与失效位的场景报告。除纯图表分析外,它还内置了一条可选的反向扩展路径——Contrarian Confirmation Mode(Shapiro 第 3 步),用确定性的周线价格行为检测器,判断一个已经拥挤的市场是否正在反转。读完本文,你可以独立完成单图/多图分析、按模板产出可归档报告,并用 CLI 脚本得到可审计的 CONFIRMED / NOT_CONFIRMED / INSUFFICIENT_DATA 结论。

一、这个技能解决什么问题

根据技能定义 SKILL.md,它适用于以下场景:

  • 用户提供周线图表图片(个股、指数、加密货币、外汇),要求技术分析;
  • 需要判断趋势方向、强度与潜在反转点;
  • 需要识别支撑/阻力位与关键价格区间;
  • 需要带具体价格目标的概率化场景规划;
  • 需要排除新闻与基本面影响的、纯图表驱动的客观结论。

技能的核心理念被明确写为五条(SKILL.md):

  1. Pure Chart Analysis:所有结论只基于图表上可见的技术数据;
  2. Systematic Approach:对每张图遵循结构化方法;
  3. Objective Assessment:避免主观偏好,聚焦可观察形态;
  4. Probabilistic Scenarios:把未来表达为概率加权的场景,而非确定性预测;
  5. Sequential Processing:逐张分析、立即归档,不批量处理。

在仓库的技能清单中,该技能被登记为 trade-planning 类别、intermediate 难度、状态 production,输入为 weekly_chart_image,输出为 technical_assessment_report 与 price_action_confirmation_report,并被 earnings-weekly、shapiro-contrarian、stockbee-ep-daily、swing-opportunity-daily 四个工作流引用(skills-index.yaml)。

二、前置条件与环境

原文档给出的前置条件只有两条(docs/en/skills/technical-analyst.md):

条件 说明
图像化图表分析能力 分析对象是用户提供的周线图截图
Python 3.9+ 推荐 用于运行脚本模式的确认检查器

需要补充两点来自仓库的事实:

  • 纯图表模式不需要任何 API Key。技能文档页面标注了 No API 徽章,SKILL.md 也明确写有 “No API Keys Required: This skill analyzes user-provided images; no external data fetches”。
  • 脚本模式(Contrarian Confirmation Mode)才需要 FMP 数据。其唯一运行时依赖是 requests,见 requirements.txt:requests>=2.31.0,该文件由 scripts/check_skill_deps.py 校验。技能索引把 FMP 集成标注为 optional,正是这个区别。

三、快速开始

原文档的 Quick Start 只有一行(docs/en/skills/technical-analyst.md):

Read: references/technical_analysis_framework.md

这行的含义是:动手前先加载方法论文档。对应仓库文件为 references/technical_analysis_framework.md,它规定了趋势分类标准、支撑阻力有效性判据、均线解读规则、量能确认原则、形态识别清单,以及概率分配框架。技能契约测试会强制校验该文件存在且被 SKILL.md 显式命名(test_skill_contract.py),因此“先读框架”不是建议,而是被测试保护的约定。

四、纯图表分析工作流(Steps 1-6)

Step 1:接收图表

  1. 确认已收到全部图表;
  2. 明确待分析图表数量;
  3. 记录用户指定的关注重点;
  4. 按顺序逐张分析。

这一步看似琐碎,但它约束了后续行为:多图不会被合并成一份模糊报告,也不会只分析第一张。

Step 2:加载技术分析框架

在分析任何图之前读取方法论文件。该文件覆盖七个方面:趋势分析与分类、支撑阻力识别、均线解读、量能分析、图形与 K 线形态、场景开发与概率分配、分析纪律与客观性。

Step 3:逐图系统化分析(六个子步骤)

3.1 趋势分析

  • 判断方向:上升、下降、横盘;
  • 评估强度:强、中、弱;
  • 记录趋势持续时间与潜在衰竭信号;
  • 检查更高的高点/低点(HH/HL)或更低的高点/低点(LH/LL)结构。

框架给出的判据更具体(technical_analysis_framework.md):

  • 上升趋势:HH + HL 结构、价格位于关键均线上方、均线呈多头排列(短均线 > 长均线);
  • 下降趋势:LH + LL 结构、价格位于关键均线下方、均线呈空头排列;
  • 横盘:无清晰高低点结构、价格在既定支撑阻力间震荡、均线走平或缠绕;
  • 强趋势:连续的高点/低点推进、回撤有限、量能配合方向;
  • 弱趋势:高低点不规则、回撤超过前一段的 50%、价量背离;
  • 衰竭信号:新高/新低动能在衰减、趋势推进中量能萎缩、价格远离均线、出现反转 K 线(射击之星、锤子线、吞没形态)。

3.2 支撑与阻力分析

  • 标注重要水平支撑位与阻力位;
  • 识别趋势线支撑/阻力;
  • 记录支撑与阻力的角色互换;
  • 评估多个 S/R 位重合形成的共振区。

框架中的有效性判据(technical_analysis_framework.md)值得直接照用:

维度 强 弱
触碰次数 3 次以上 1-2 次
存在时间 数月到数年 近期形成
触碰时量能 高 低
共振因素 斐波那契、整数关口、均线等重合 无

同时要注意 support-resistance flip:支撑被向下击穿后,回测时往往转为阻力;阻力被向上突破后,回抽时往往转为支撑。

3.3 均线分析

原文档要求判断价格相对 20 周、50 周、200 周均线的位置、排列、斜率、交叉与动态支撑阻力作用。框架补充了周期含义与关键交叉定义:

  • 20 周均线 ≈ 4 个月,短期趋势;
  • 50 周均线 ≈ 1 年,中期趋势;
  • 200 周均线 ≈ 4 年,长期趋势;
  • Golden Cross:20 周均线上穿 50 周均线;Death Cross:20 周均线下穿 50 周均线;
  • 多头排列:20 周 > 50 周 > 200 周且全部上行;空头排列:20 周 < 50 周 < 200 周且全部下行;
  • 均线压缩/收敛往往先于一次有方向的大幅波动。

3.4 量能分析

  • 判断整体量能趋势(增加、减少、稳定);
  • 识别量能尖峰及其位置(在支撑/阻力处、在突破处);
  • 检查量能是确认价格还是与价格背离;
  • 记录量能高潮或衰竭形态。

框架给出了四象限判读:价涨量增(健康上升)、价跌量增(健康下降)、价涨量缩(上升乏力)、价跌量缩(可能卖压衰竭)。其中一条最实用的规则是:低量突破常常失败。

3.5 图形与价格行为

  • 反转形态:锤子线、射击之星、吞没形态、双底/三底、双顶/三顶、晨星/暮星;
  • 持续形态:牛旗、上升三角形、熊旗、下降三角形;
  • 记录显著 K 线组合与最近的突破/跌破。

框架给出的权重规则是:形态若出现在关键 S/R 处、突破时量能配合、且被均线与趋势结构确认,并且发生周线级别,则可信度更高(周线 > 日线)。

3.6 综合观察

把上述要素整合为一致的当前评估,指出最具影响力的因素、记录信号冲突与模糊之处,并确立“决定未来方向的关键价位”。

Step 4:构建概率化场景

每张图需给出 2-4 个互斥场景,每个场景必须包含六项要素:

  1. Scenario Name:清晰的标题,如 “Bull Case: Breakout Above Resistance”;
  2. Probability Estimate:基于技术因素的概率百分比,所有场景必须合计 100%;
  3. Description:场景内容与展开方式;
  4. Supporting Factors:至少 2-3 条技术证据;
  5. Target Levels:该场景成立时的预期价位;
  6. Invalidation Level:会使该场景失效的具体价位。

典型框架为:Base Case 40-60%、Bull Case 20-40%、Bear Case 20-40%、Alternative Scenario 5-15%。

框架还给了概率分配的三档参考(technical_analysis_framework.md):

概率档 区间 适用条件
高 50-70% 与当前趋势一致,多因子(趋势/S-R/均线/量能)确认,近期价格行为支持,失效位清晰
中 25-45% 需要趋势改变或重大突破,只有部分因子支持,依赖关键位守住或跌破
低 5-20% 与多数技术因子相反,需要结构显著改变

原文还给了一个示例:当前结构为“上升趋势、站上所有均线、守住支撑”,则 Bull Case 60%(趋势完好、守支撑、量能确认)、Base Case 30%(临近阻力、可见获利了结)、Bear Case 10%(暂无反转信号但始终可能)。

注意,原文档中的写作模板只有 3 个场景槽位加 1 个可选槽位,与“2-4 个场景”的要求一致:

### Scenario 1: [Scenario Name] - **[XX]% Probability**
**Description**: [What this scenario entails]
**Supporting Factors**:
- [Factor 1]
- [Factor 2]
- [Factor 3]
**Target Levels**: [Upside or downside targets if this scenario plays out]
**Invalidation Level**: [Price level that would negate this scenario]

Step 5:生成分析报告

使用 assets/analysis_template.md 作为模板,报告必须包含 10 个章节:

  1. Chart Overview
  2. Trend Analysis
  3. Support and Resistance Levels
  4. Moving Average Analysis
  5. Volume Analysis
  6. Chart Patterns and Price Action
  7. Current Market Assessment
  8. Scenario Analysis(2-4 个带概率的场景)
  9. Summary
  10. Disclaimer

模板的头部固定为四个字段:

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

文件命名规范:<a href="https://link.gitcode.com/i/ea9996d92b5959532ce6e19b22a40c47" target="_blank">SYMBOL]_technical_analysis_[YYYY-MM-DD].md,例如 SPY_technical_analysis_2025-11-02.md,保存到 reports/ 目录。命名规则同时被 SKILL.md 和技能契约测试引用([test_skill_contract.py),属于稳定接口而非随手约定。

第 10 节的免责声明文本本身也是契约的一部分,建议原样保留:

This analysis is based purely on technical chart data and does not consider fundamental factors, news, or market sentiment. It represents a probabilistic assessment of potential scenarios, not a prediction or investment recommendation.

Step 6:多图时重复

多图场景下,先完整跑完 Step 3-5 并保存第一份报告,再进入下一张。原文明确要求 “Do not batch analyses”——一份报告落盘后再开始下一张。SKILL.md 的三个示例(单图分析、三图分析、带焦点问题的分析)展示了期望的节奏:三图分析会依次产出 BTC_*、ETH_*、NDX_* 三份独立报告,最后统一告知用户完成。

五、质量控制要求

原文档把质量标准拆成三组(见 SKILL.md),这是判断一份输出“合不合格”的清单。

客观性

  • 严格基于可观察的图表数据;
  • 不引入新闻、基本面、市场情绪;
  • 不使用 “I think / I feel” 这类主观措辞;
  • 信号模糊时明确表达不确定性;
  • 同时呈现多空两种可能,避免确认偏误。

完整性

  • 覆盖模板的全部章节;
  • 支撑、阻力、目标位都给出具体价格(而非“附近”“一带”);
  • 概率估计必须有技术因子支撑;
  • 每个场景都要有失效位;
  • 注明分析的局限与前提。

清晰性

  • 术语使用准确;
  • 语言专业、结构合乎逻辑;
  • 场景之间必须彼此区分、互斥。

框架还列出六个常见陷阱:过度复杂化(指标过多导致分析瘫痪)、忽略量能、强行套形态、忽视时间周期差异、忽略整体市场背景、过度确定。

六、Contrarian Confirmation Mode(Shapiro 第 3 步)

这是原文档第 5 节的内容,也是本技能唯一的“非纯图表”扩展。它的定位很明确:叠加模式(ADDITIVE mode),只有当用户显式请求“逆势确认”时才启用;一句普通的“分析这张图”仍然走上面 Steps 1-6 的原始流程。

6.1 它在五步流程中的位置

依据 references/contrarian-confirmation-checklist.md:

步骤 技能 作用
1 cot-contrarian-detector 用 COT 指数找出拥挤市场(CROWDED_LONG / CROWDED_SHORT)
2 news-reaction-failure-analyzer(可选) 判断价格是否对有利于 crowd 方向的新闻“无反应”
3 technical-analyst(本模式) 确认周线图上是否出现反转的价格行为证据
4 contrarian-setup-gate 汇总前三步,决定是否 READY_FOR_PLAN
5 手工 + position-sizer / futures-position-sizer 入场、出场规划与仓位计算

工作流编排文件 workflows/shapiro-contrarian.yaml 把第 3 步的决策问题写成:“周线图上是否存在与 crowd 方向相反的反转(key reversal、failed breakout、failed extreme)且判定为 CONFIRMED,并有明确的摆动止损位?NOT_CONFIRMED / INSUFFICIENT_DATA 一律拒绝。”该步消费 cot_crowding_report,产出 price_action_confirmation_report。

需要强调:这一步只给结论,不给交易建议。入场(第 4 步)与出场(第 5 步)仍为人工,仓位属于下游技能。

6.2 方向约定与严格不等式

  • 淡化 CROWDED_LONG:在上行极值处或之后寻找看跌反转证据——关注高点、关注收盘跌破前低、关注冲击阻力失败。
  • 淡化 CROWDED_SHORT:完全镜像——关注低点、关注收盘突破前高、关注跌破支撑失败。
  • 所有比较都是严格不等式:等于前极值不算新极值;恰好收在前价位上不算反转、突破或失败。理由写得很直白——只是“追平”而非“超越”某个价位,并没有产生新证据。

脚本层面对此有直接对应实现(weekly_price_action.py):判定使用 bar["high"] > max(...) 与 bar["close"] < prior_bar["low"],均为 > / <,而非 >= / <=。

6.3 窗口术语与截断规则

参数 默认值 作用
swing-lookback weeks 13 定义“近期”高低点,驱动周线关键反转触发
extreme-lookback weeks 52 定义更长周期的极值,用于 failed extreme、failed breakout、continuation veto,以及关键反转的 confidence-HIGH 加成
signal-recency weeks 4 早于该窗口的信号不构成确认
min_weeks 30 硬下限,低于此直接 INSUFFICIENT_DATA

两条容易被忽略但会影响结论的规则:

  1. prior weeks 严格排除被评估周本身——“前 N 个已完成周”永远指被测周之前的 N 个完成周。代码中由 compute_prior_window() 实现为 weekly_bars<a href="https://link.gitcode.com/i/ea520dd6f0f4cab1c8405868e1365f91" target="_blank">max(0, idx-lookback):idx]([weekly_price_action.py)。
  2. 窗口截断是“按被评估周”而非“按运行”。若某个被评估周之前的完成周不足配置窗口,则截断为可用数量;同一次 recency 扫描中两个不同的周可能有不同的历史长度(例如刚好卡在 min_weeks 下限附近的 26 周与 29 周)。因此 confidence-HIGH 的 52 周极值条件,读取的是那一个触发周实际使用的窗口大小,不是别的周的值。

6.4 三个信号检测器 + 一个否决项

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

CROWDED_LONG 形式:该周高点是新的 swing-lookback 高点(严格大于前 swing-lookback 完成周的最大高点)且该周收盘严格低于前一周的低点。CROWDED_SHORT 镜像:新 swing-lookback 低点且收盘严格高于前一周高点。

这是唯一引用两个窗口的检查:swing-lookback 窗口驱动触发本身;更大的 extreme-lookback 窗口被单独检查,只用于判断同一个新高/新低是否也是全窗口极值——这个更强的条件只喂给 confidence-HIGH 门槛,从不影响触发与否。

检查 2:Failed Extreme(周内试探失败)

在 signal-recency 窗口内,某周严格上穿前 extreme-lookback 高点,但收盘回到该高点下方。与关键反转的区别:不要求前一周自身的高低点条件,且使用 extreme-lookback 窗口而非 swing-lookback 窗口。

检查 3:Failed Breakout(确认后被打回)

某周出现收盘价高于前 extreme-lookback 高点的真实收盘突破(不是周内刺穿),随后在 ≤3 个完成周内出现收盘回到该突破位下方的周。

这里有一个关键实现细节:week_of 记录的是失败周,绝不是突破周。代码里对每个突破周 b 只向 b+1..b+3 扫描,并在第一个回收收盘处 break(weekly_price_action.py),即“某次突破只有第一次回收算作它的失败”。这条设计同时解决两个问题:

  • recency 只约束失败周,突破周可以更老;
  • 由于突破周天然早于失败周,它永远不会被后续 continuation 检查误判为“新收盘极值”而自我否决。

原文给了演进示例:突破在 W 周、失败在 W+2 周、之后无新数据 → CONFIRMED;同样的突破与失败,但 W+3 周又创出新高收盘(仍在 recency 内)→ NOT_CONFIRMED (continuation_intact),否决生效。

否决项:Continuation Veto

独立于三个检查:市场是否在crowd 方向上创出新的收盘极值(CROWDED_LONG 取每个被评估周自身前 extreme-lookback 窗口内收盘价的最大值比较,不是周内高点),且严格比最新触发的信号更近?

  • 若有信号触发,扫描从该信号 week_of 的下一周开始,因此信号周本身(以及更早的任何周,包括 failed_breakout 的突破周)都无法自我否决;
  • 若完全没有信号触发,则扫描覆盖整个 signal-recency 窗口。这样“一路创新高、毫无反转证据”的市场会得到正确的 continuation_intact,而不是笼统的 no_reversal_evidence。

代码里这个语义由 detect_continuation() 的 scan_start = max(0, newest_signal_idx + 1 or recency_start) 实现,并返回最早的符合条件的周(表示“延续恢复的那一刻”),而非最近一周。

摆动位:5 周分形枢轴

Swing high = 某完成周的高点严格高于其左右各 2 个完成周的高点(5 周分形);swing low 镜像。nearest 取 extreme-lookback 窗口内最近的此类枢轴。

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

stop_reference 跟随淡化方向,而不是 crowd 方向:淡化拥挤多头(即做空)时,止损在上方,取最近 swing high;淡化拥挤空头(即做多)时,止损在下方,取最近 swing low。测试用例逐一验证了这两种映射(test_weekly_price_action.py)。

代码中还有一个边界条件:最新可能的枢轴是最后一个完成周之前的 2 周,因为枢轴需要右侧 2 个完成周(search_end = n - 3)。

6.5 结论合成(fail-closed)

判定顺序是硬性的(weekly_price_action.py):

  1. 完成周少于 min_weeks,或没有可用价格源 → INSUFFICIENT_DATA(insufficient_weekly_bars / no_price_source);
  2. Continuation veto 触发 → NOT_CONFIRMED (continuation_intact),永远优先于已触发的信号;
  3. 否则,若三个检查中任意一个在 recency 窗口内触发 → CONFIRMED,verdict_reason 命名为产生最新触发信号的检测器(key_reversal / failed_extreme / failed_breakout);
  4. 否则 → NOT_CONFIRMED (no_reversal_evidence)。证据缺失永不等于确认。

其中第 3 步的“最新”由 _newest_triggered() 实现:比较各检测器的 week_of 索引取最大;同一周并列时按 _TRIGGER_ORDER(key reversal 优先)确定性打破平局。

6.6 置信度规则

confidence 为 HIGH 当且仅当满足其一:

  • recency 窗口内至少 2 个不同类型的检测器触发(同一检测器重复触发不重复计数;由于模块本身每个检测器只报告一次触发,这是自动成立的);
  • 触发的 weekly_key_reversal 的新高/新低同时是完整未截断(≥52 周) extreme-lookback 窗口的极值——即 extreme_window_weeks_used >= 52 且 is_full_window_extreme 为真。

其余情况为 MEDIUM。LOW 保留、v1 从不输出。

这里的实现细节值得注意:CONFIDENCE_HIGH_EXTREME_WEEKS = 52 是一个独立常量,不是直接读取 extreme_lookback_weeks。这样即使调用方传入非默认的 extreme-lookback,门槛仍有明确定义(尽管可能不可达),不会变成移动靶。

原文对 MEDIUM 的语义给了明确警告:单信号的 MEDIUM 是刻意偏弱的证据。一次关键反转、一次极值失败或一次突破失败,单独看只是“值得继续观察”,不构成“可以加大仓位”的理由。confidence 字段之所以被带进 handoff,正是为了让下游(contrarian-setup-gate)能区别对待单信号证据与双信号/全窗口极值证据。

6.7 输出契约

symbol: BT
direction: CROWDED_LONG
mode: data # "chart" for a Claude chart-image read
verdict: CONFIRMED | NOT_CONFIRMED | INSUFFICIENT_DATA
confidence: HIGH | MEDIUM | LOW # LOW reserved, never emitted in 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: # consumed by 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 拒绝理由)。这不是一个“所有字段都为 false 的占位字典”。下游消费方只需检查 verdict,就能决定是否安全读取 checks.*,无需按 verdict_reason 分支。该不变量在纯计算层与 CLI 的所有提前退出路径上被统一执行,并有专门测试断言 checks is None(test_weekly_price_action.py)。

6.8 图表优先,脚本兜底

图表图片始终是主输入,这与技能身份一致。只有在以下情形才运行脚本(替代或并行于读图):

  • 用户没有提供图表;
  • 需要可审计、确定性的结果。

直接指定方向:

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/

脚本通过有文档的“期货 → ETF”回退链获取周线重采样 OHLC,在重采样之前先把日线截断到 --as-of(无前视),并在以下情况 fail-closed 到 INSUFFICIENT_DATA,永不崩溃:--detector-json 缺失/陈旧/结构损坏、价格历史过短(--min-weeks,默认 30)、无可用价格源。

产物为 ta_confirmation_<SYMBOL>_<as-of>.json 与 .md,保存到 reports/。Markdown 报告固定包含 Verdict、Checks 表、Swing Levels、Methodology;若使用了 ETF 代理,还会追加一段 Proxy Data Caveat,说明代理存在跟踪误差、费率拖累与展期时点差异,周线级别比较应视为近似。

6.9 保守分歧规则

如果图表模式与脚本模式对同一 symbol/direction 都给出了结论且互相矛盾,最终结论取 NOT_CONFIRMED,verdict_reason: mode_disagreement,并把两份子结果一并附上供人工复核——绝不静默偏好某一种模式。

如果一个模式是 INSUFFICIENT_DATA、另一个给出了干净结论,则以干净结论为准,并记录另一模式的数据不足,而不是把它当作分歧。

七、脚本参数与内部实现细节

7.1 命令行参数全景

参数定义见 check_weekly_price_action.py:

参数 默认值 说明
--symbol 必填 COT 符号(若在映射表中)或普通价格 ticker
--price-symbol 无 覆盖价格源映射,跳过整条回退链(kind 记为 explicit_override)
--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 关键反转的“近期”窗口
--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 用自定义 argparse 类型 _min_weeks_type 校验必须为 ≥ 1 的整数。原因写在注释里:若不校验,--min-weeks 0 会让 n < min_weeks 这个下限判断中的 0 < 0 为假,从而把空数据或近空数据错误地输出为 NOT_CONFIRMED 而不是 INSUFFICIENT_DATA。

API Key 的解析顺序是 --api-key → 环境变量 FMP_API_KEY;两者都没有时会打印 FMP_API_KEY 未设置的警告,最终以 exit 1 结束(这是唯一非零退出场景,其余降级路径均 exit 0 并写出报告)。

7.2 价格源回退链

PRICE_SOURCE_CHAINS 是以 COT 符号为键的有序列表,元素为 (price_symbol, kind, invert)(check_weekly_price_action.py)。策略是:按顺序尝试,HTTP 错误或 rows == 0 都算失败,第一个成功者胜出。例如:

"NQ": [("NQUSD", "futures", False), ("QQQ", "etf", False)],
"GC": [("GCUSD", "futures", False)],
"CL": [("CLUSD", "futures", False), ("BZUSD", "futures", False), ("USO", "etf", False)],
"BT": [("BTCUSD", "futures", False)],
"VX": [("VXUSD", "futures", False)],  # 200/0 rows on this key -> no_price_source

几个来自源码注释的实证细节:

  • 数据端点是 FMP stable 的 historical-price-eod/full,返回 date/open/high/low/close/volume;已验证 GCUSD、ESUSD、BTCUSD、GBPUSD 以及 ETF 代理 QQQ/IEF/UUP 可用;NQUSD 在该 key 上返回 402(与 light 端点相同的层级限制),因此回退链生效;
  • 字段名陷阱:full 端点用 close,light 端点用 price。build_sorted_daily_series() 对两者都做防御性接受(row.get("close", row.get("price")));
  • 与 news-reaction-failure-analyzer 不同,--symbol 不限于 COT 期货符号:若不在映射表中,会直接当作普通 FMP 价格 ticker(如个股或 ETF),这与本技能覆盖股票、指数、加密、外汇的定位一致;
  • 该映射表是 news-reaction-failure-analyzer 中 PRICE_SOURCE_CHAINS 的自包含副本,遵循仓库“不跨技能 import”的约定。

7.3 无前视与周线重采样

resample_weekly() 的语义在源码注释里定义得非常清楚(weekly_price_action.py):

  1. 先把所有 date > as_of 的日线丢弃(这就是“信息截止”而非“事后对齐”);
  2. 按 ISO 日历周(周一至周日)分组;
  3. 包含 as_of 的那一周永远被排除——它是进行中的周,即使已经积累了一整周的 bar 也一样(被截止日切碎的周视为不完整而丢弃;不是 as_of 周的假日缩短周属于完成周,正常重采样);
  4. 加密等 7×24 市场可能含周末 bar,bar 的 ISO 周直接从其自身 date 取(周日属于它自己的周一至周日那一周,绝不归入下一周),因此不受 FMP 加密数据的 UTC/ET 日界约定影响;
  5. 每周聚合为 {week_of, open, high, low, close, volume},其中 week_of 为该周周一日期,open 取首根、high 取最大、low 取最小、close 取末根、volume 求和。

CLI 侧的取数窗口也值得知道:

weeks_needed = max(args.extreme_lookback_weeks, args.min_weeks) \
             + args.signal_recency_weeks + WEEKS_FETCH_BUFFER   # buffer = 10
from_date = as_of - timedelta(weeks=weeks_needed)

额外 10 周的缓冲是为了在假日稀薄的日历下,extreme-lookback 窗口、recency 窗口与 min_weeks 下限仍有真实周线可用。

7.4 检测器-报告解析与 fail-closed 理由码

当使用 --detector-json 时,resolve_direction_from_detector() 依次执行(check_weekly_price_action.py):

情形 verdict_reason
文件不可读(缺失/非 UTF-8 等) detector_json_unreadable
文件可读但不是合法 JSON detector_json_parse_error
顶层不是对象(形状错误) malformed_detector_json
symbol 不在 markets[] 中,或出现在 skipped[] 中 detector_missing_symbol
run_context.data_date 缺失/为空 detector_missing_data_date
data_date 不是字符串或无法解析 detector_invalid_data_date
data_date 晚于 --as-of detector_future_data_date
data_date 早于 --max-detector-age-days detector_json_stale
classification 为 NEUTRAL not_crowded
classification 不是 CROWDED_LONG / CROWDED_SHORT detector_missing_symbol
既无 --direction 也无 --detector-json no_direction_provided
整条价格链全部失败 no_price_source
可用完成周 < min_weeks insufficient_weekly_bars

仓储层面对“选定市场数据新鲜度”的规则(原文档第 5 节首段专门描述过)是:除 run_context.data_date 外,还要校验所选市场的 markets[].data_date 与 data_provenance.market_data_dates[symbol]。每个都必须非空、可解析、不晚于 --as-of、且不早于 --max-detector-age-days(边界自身被接受)。取校验通过的日期中最老的一个用于审计年龄,同时保持原始 run context 不变。历史遗留报告可以省略行/映射日期并回退到报告日期;但只要日期存在且非法/为 null/为空,或 provenance 与映射容器结构损坏,就以现有的 missing/invalid/future/stale 理由码 fail-closed。其他 symbol 的行/映射日期不能替代所选市场的 vintage。日期解析沿用前 10 个字符,因此兼容既有行为——这不是一个更严格的全时间戳或 provenance schema 校验器。

7.5 脱敏

脚本对 API Key 做双层脱敏(check_weekly_price_action.py):

  • 值匹配(主):把已知 secret 字符串直接替换为 ***REDACTED***;
  • 模式族(辅):用 4 条正则覆盖 apikey=...、"apikey": "..."、'apikey': '...'、apikey%3d...。

必要性来自 requests 的异常会内嵌完整请求 URL(含 ?apikey=...):仅靠模式匹配只能拦住带 “apikey” 标记的形态,无标记的裸 key 只能靠值匹配兜住。两层都上,任一层单独都不够。

7.6 重试策略

_request_with_backoff() 对 429 与 5xx 做指数退避重试(默认 4 次重试、基础延迟 1.0 秒、每次翻倍),其余 4xx(401/402/403/404…)立即失败。注释点明了理由:这里的 402 是预期中的常规情况(它用于推进回退链),不值得重试。

八、两种模式的取舍与协作

维度 纯图表模式 Contrarian Confirmation Mode
触发条件 任意“分析这张周线图”请求 显式逆势确认请求
主输入 用户提供的周线图图片 图表(主)/ FMP 周线数据(兜底)
输出 10 节 Markdown 分析报告 JSON + Markdown 结论报告
文件命名 [SYMBOL]_technical_analysis_[YYYY-MM-DD].md ta_confirmation_<SYMBOL>_<as-of>.json/.md
是否需要 API 否 是(FMP)
结论形态 2-4 个概率场景 + 目标位/失效位 三值结论 + 置信度 + 止损参考

两者并非替代关系:图表模式回答“这张图的概率图景是什么”,确认模式回答“crowd 是否正在被打脸”。当两者对同一标的给出结论且冲突时,走保守分歧规则,最终落到 NOT_CONFIRMED。

图表模式的输出也被其他工作流直接复用:earnings-weekly、stockbee-ep-daily、swing-opportunity-daily 都把 technical-analyst 列在 required_skills 中,并把图表分析结果作为其决策链的一个步骤;skillsets/swing-opportunity.yaml 也将其列入技能集合。

九、护栏清单

来自原文档的 Guardrails 一节,逐条都有代码或结构支撑:

  • 只给结论,永不单独作为交易建议。该模式确认的是五步中的第 3 步;入场与出场仍需人工,仓位属于 position-sizer / futures-position-sizer。
  • INSUFFICIENT_DATA 永不推进流程。任何降级输入都 fail-closed,且始终 exit 0 并写出报告——不会崩溃、不会只给非零退出而无产物、不会在数据不足时强行给结论。
  • 仅限周线。整套定义基于已完成的 ISO 日历周,对日线或日内价格行为不作任何表述。
  • 原有图表分析流程不变。本模式只在显式逆势确认请求下启用。
  • 单信号 MEDIUM 是弱证据。不应与高置信度的双信号或全窗口极值确认等同看待。

十、资源清单与自测方式

技能打包的四个资源及其用途(SKILL.md):

资源 用途
references/technical_analysis_framework.md 分析前必读,确保系统化与客观性
assets/analysis_template.md 每份报告都套用的结构模板
references/contrarian-confirmation-checklist.md 产出确认结论前必读;图表模式与脚本模式必须判定一致
scripts/check_weekly_price_action.py 数据驱动的兜底 CLI

技能在仓库中同时提供可下载的打包产物 skill-packages/technical-analyst.skill,适合脱离仓库做独立安装;独立安装后运行脚本时,先安装 requirements.txt 中的依赖。

自测分两个层次,均不访问网络:

# 纯计算层:重采样、四个检测器、摆动位、结论与置信度
python3 -m pytest skills/technical-analyst/scripts/tests/test_weekly_price_action.py -v

# CLI 层:回退链、as-of 截断、detector-json 守卫、脱敏、报告生成
python3 -m pytest skills/technical-analyst/scripts/tests/test_check_weekly_price_action.py -v

# 技能契约:frontmatter、资源存在性、输出契约字段、文件名模式
python3 -m pytest skills/technical-analyst/scripts/tests/test_skill_contract.py -v

CLI 测试用假的 requests.Session 打桩,覆盖了 402 回退到 ETF 代理、rows == 0 视为失败并推进链条、全链失败落到 no_price_source、close/price 字段双支持、以及“日线绝不包含 as_of 之后的日期”等关键行为。纯计算层测试则覆盖了分形枢轴检测、多枢轴取最近、无枢轴回退、stop_reference 的方向映射,以及置信度的 52 周全窗口门槛(extreme_window_weeks_used = 40 无法达到 HIGH)。

十一、从一个真实调用链看整体设计

把上面的碎片串起来,一次完整的逆势确认调用是这样的:

  1. cot-contrarian-detector 产出 reports/cot_crowding_2026-07-12.json,其中某市场的 classification 为 CROWDED_LONG,run_context.data_date 为 2026-07-08(周二 COT 数据);
  2. technical-analyst 收到显式确认请求,用户指定 --as-of 2026-07-15;
  3. CLI 先解析 detector 报告:symbol 命中、classification 合法、data_date 不晚于 as_of 且未超过 10 天 → 方向确定为 CROWDED_LONG;
  4. 取数窗口 = max(52, 30) + 4 + 10 = 66 周,from = 2026-07-15 - 66 周,to = 2026-07-15;
  5. 按回退链取到日线,先截断到 2026-07-15,再重采样为周线,剔除包含 2026-07-15 的进行中周;
  6. 完成周数 ≥ 30,依次跑关键反转、极值失败、突破失败三个检测器,再用最新触发信号的位置去跑 continuation 否决;
  7. 计算 5 周分形摆动位与 stop_reference,合成 verdict / confidence / verdict_reason;
  8. 写出 reports/ta_confirmation_BT_2026-07-15.json 与 .md,其中 handoff.price_action 携带 verdict、confidence、stop_reference、report_path,交给第 4 步的 contrarian-setup-gate 消费。

如果要同时用读图模式交叉验证,就把同一 symbol/direction 的图表判读结果按同一套严格定义填成 mode: chart 的 YAML 块。图表模式无法像脚本那样精确数 bar,因此 window_weeks_used 允许是近似值——正确做法是在 detail 里显式说明这一点,而不是伪造精度。两份结果一旦矛盾,按保守分歧规则落到 NOT_CONFIRMED (mode_disagreement) 并附上双方结果。

这套设计的价值在于:同一条方法论被写了一次,却被两个执行者(读图的模型与确定性的脚本)以逐字一致的定义执行。方法论在 contrarian-confirmation-checklist.md 中定义,纯计算模块在 weekly_price_action.py 中实现,CLI 在 check_weekly_price_action.py 中负责数据与 I/O,三者通过输出契约与不变量彼此解耦。也正因如此,它可以安全地作为自动化流程中的一个 decision_gate: true 步骤存在——要么给出可审计的三值结论,要么明确承认数据不足。

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