claude-trading-skills Technical Analyst 技能详解:周线图技术分析与 Shapiro 逆向确认模式

原创2026-11-14 21:14:251,931 阅读
文章标签:金融科技AI 技能人工智能数据分析

claude-trading-skills Technical Analyst 技能详解:周线图技术分析与 Shapiro 逆向确认模式

本文以 claude-trading-skills 仓库中的技术分析技能为核心,讲解如何让 Claude 基于周线图表完成系统化的趋势、支撑阻力、均线与量能分析,并输出带概率的情景规划;同时在需要可复核、可复现的场合,介绍新增的“逆向确认模式”(Shapiro 流程第 3 步)及其命令行实现与输出契约。读完后你将能够独立组织一次完整的单图/多图技术分析,并正确解读 ta_confirmation_* 报告中的 verdict、confidence 与 stop_reference。

1. 技能定位:只吃图表的纯技术分析

该技能的完整定义位于 skills/technical-analyst/SKILL.md,中文站点对应的介绍页是 docs/ja/skills/technical-analyst.md(日文页,结构与英文页 docs/en/skills/technical-analyst.md 一致)。

它做一件事:对周线价格图表(股票、股指、加密货币、外汇对)做全面的技术分析,识别趋势、支撑/阻力位、均线关系与成交量形态,并对未来走势给出带概率的情景。核心约束写在 SKILL.md 的 Core Principles 中:

  1. Pure Chart Analysis:所有结论只基于图表上可见的技术数据;
  2. Systematic Approach:每张图走同一套结构化方法;
  3. Objective Assessment:避免主观偏好,聚焦可观察的形态与数据;
  4. Probabilistic Scenarios:用概率加权情景表达未来可能性,而不是给出确定性预测;
  5. Sequential Processing:逐图分析,立即落盘。

技能前置条件极其轻量:需要用户提供周线图图片(分析对象是图片,不抓取外部行情),并且不需要 API Key。只有当使用下文的脚本回退模式时,才需要 FMP 行情密钥。技能声明推荐 Python 3.9+,脚本运行时依赖仅 requests>=2.31.0(见 skills/technical-analyst/requirements.txt)。

这一点值得强调:文档页把该技能标记为“API 不要”(无需 API),而仓库的 SKILL.md 在 Prerequisites 一节也明确写明 No API Keys Required——因为主路径完全依靠 Claude 的图像理解能力,而不是行情接口。

2. 快速开始

文档给出的最小启动动作就是读取方法论文件:

Read: references/technical_analysis_framework.md

对应仓库路径为 skills/technical-analyst/references/technical_analysis_framework.md。在 Claude Code 环境里,更直接的方式是直接对 Claude 说出任务,例如“分析这张 SPY 周线图”,并把图片一并提供;技能会被 description 字段中的触发条件命中(weekly price charts + technical analysis + without consideration of news or fundamental factors),这一点由契约测试 skills/technical-analyst/scripts/tests/test_skill_contract.py 中的 test_frontmatter_identifies_chart_only_technical_skill 固定下来。

契约测试同时锁定了几条“不可漂移”的约定,理解它们有助于你知道技能的行为边界:

契约 测试用例 含义
必须包含 Chart Images、Pure Chart Analysis、Probabilistic Scenarios test_prompt_contract_requires_chart_input_and_probabilistic_output 图表输入 + 纯技术 + 概率输出三大要素不可删
必须包含 [SYMBOL]_technical_analysis_[YYYY-MM-DD].md 同上 报告命名规则属于对外契约
references/、assets/、scripts/ 四个资源必须存在且在 SKILL.md 中被点名 test_required_framework_and_template_are_present_and_named 资源缺失即视为破坏技能
逆向确认章节必须位于 Example Usage Scenarios 与 Resources 之间 test_contrarian_confirmation_section_present_and_positioned 新增模式不得扰动既有章节锚点

3. 六步工作流

步骤 1:接收图表

当用户提供一张或多张周线图时,先做四件事:确认已收到全部图片、确认待分析图表数量、记录用户指定的关注点(例如“是否突破阻力”)、然后开始逐张分析。原文档在此处刻意没有“批量并行”的选项。

步骤 2:加载技术分析框架

正式开分析前读取 skills/technical-analyst/references/technical_analysis_framework.md。该文件是整个技能的“方法论内核”,覆盖趋势分析与分类、支撑阻力识别、均线解读、量能分析、形态与 K 线、情景构建与概率分配、以及分析纪律。它并非摘要,而是带着判定标准的操作手册——下一节把其中可量化的部分抽出来。

步骤 3:对每张图做六维系统分析

3.1 趋势分析

框架给出的分类标准是可直接执行的:

  • 上升趋势:更高的高点(HH)与更高的低点(HL);价格位于关键均线上方;均线呈多头排列(短周期 > 长周期)。
  • 下降趋势:更低的高点(LH)与更低的低点(LL);价格位于均线下方;均线呈空头排列。
  • 横盘/区间:没有清晰的高点低点抬升或下移结构;价格在明确的支撑与阻力之间摆动;均线走平或相互缠绕。

强度判据分三档:强趋势(连续 HH/HL 或 LH/LL、回撤浅、量能确认方向)、弱趋势(高低点不规则、回撤超过前一波段 50%、价量背离)。而趋势衰竭信号包括:新高/新低时动能减弱、趋势推进中量能递减、价格距均线过远、以及射击之星/锤子线/吞没形态等反转 K 线。

对应到执行层面,就是记录四件事:方向、强度、已持续时长、潜在衰竭迹象,并检查高低点结构。

3.2 支撑与阻力分析

支撑是历史上买盘阻止进一步下跌的价格区域;阻力是历史上卖盘阻止进一步上涨的价格区域。框架给出了有效性判据:

  • 至少 2–3 次触及并反弹/受阻;
  • 反弹或受阻时出现量能放大;
  • 时间跨度更长(月到年)的位阶权重更高;
  • 整数关口常具心理意义。

类型上要区分三类:水平支撑/阻力(前期低点/高点对齐)、趋势线支撑/阻力(连接更高低点或更低高点)、均线动态支撑/阻力。显著性强弱也有量化提示:3 次以上触及、存在时间长、此前触及时成交量大、与其他技术要素(斐波那契、整数关口、均线)汇聚,则强;仅 1–2 次触及、形成不久、量能低,则弱。

最容易被忽略但必须记录的是角色转换(support-resistance flip):向下破位后,原支撑在回抽时变成阻力;向上突破后,原阻力在回踩时变成支撑。此外要评估多条 S/R 汇聚形成的汇聚区(confluence zone)。

3.3 均线分析

周线图表上的三条关键均线及其含义:

均线 近似跨度 解读
20 周 MA 约 4 个月 短期趋势
50 周 MA 约 1 年 中期趋势
200 周 MA 约 4 年 长期趋势

需要逐一判断:价格相对三条均线的位置(全部在上=强多头结构;全部在下=强空头结构;夹在中间=过渡期、趋势不明);均线排列(多头 20>50>200 且同时上行 / 空头 20<50<200 且同时下行 / 均线压缩收敛常预示方向性大波动);斜率(上行=多头动能、下行=空头动能、走平=盘整);金叉(20 周上穿 50 周)与死叉(20 周下穿 50 周);以及均线是否正在充当动态支撑/阻力——重复在其附近反弹或受阻会提升该均线的重要性。

3.4 成交量分析

量能用来确认价格运动的强度或虚弱,框架给出了四种组合的判读:

  • 价涨量增:健康上升趋势,买盘强;
  • 价跌量增:健康下降趋势,卖盘强;
  • 价涨量减:上升趋势偏弱,缺乏信心;
  • 价跌量减:下跌趋势偏弱,抛压可能衰竭。

关键量能形态包括:支撑位放量反弹(偏多)、阻力位放量受阻(偏空)、突破时放量(确认有效)、突破时缩量(常见假突破)。此外要识别量能趋势(同向递增=确认;同向递减=预警)、量能高潮(极端放量常标记趋势极值,即投降式抛售或亢奋买盘)与量价背离(价创新低而量递减=抛压衰竭;价创新高而量递减=买盘衰竭)。

3.5 形态与价格行为

反转形态(锤子线、看涨吞没、晨星、双底/三底;射击之星、看跌吞没、黄昏星、双顶/三顶)与持续形态(牛旗、上升三角形;熊旗、下降三角形)都要逐一排查,并记录近期是否发生突破或破位。框架还明确了形态的加权条件:出现在关键 S/R、突破时伴量、被均线与趋势结构印证、且发生在更长周期(周线优于日线)。

3.6 观察整合

把上述要素整合为一份自洽的现状判断:找出影响该图表最重要的因素、记录矛盾信号与模糊之处、并确定决定后续方向的关键价位。这一步决定了情景分析是否有依据。

步骤 4:构建概率情景

每张图要产出 2–4 个互斥情景。原文档规定每个情景必须含六要素:

  1. 情景名称:清晰描述性标题,例如“看涨情景:突破阻力上行”;
  2. 概率估计:基于技术因素的发生概率,所有情景合计 100%;
  3. 描述:该情景包含什么、会如何展开;
  4. 支撑因素:支持该情景的技术证据,至少 2–3 条;
  5. 目标位:情景实现时的预期价格水平;
  6. 失效位:证伪该情景的具体价格水平。

典型分布为:基准情形 40–60%、看涨情形 20–40%、看跌情形 20–40%、备选情形 5–15%。框架进一步给出了概率标定的锚点:高概率 50–70%(与当前趋势一致、多因子共振、近期价格行为支持、失效位清晰);中概率 25–45%(需要趋势改变或重大突破、仅有部分支撑因素);低概率 5–20%(与多数技术因素相反、需要结构明显变化)。

框架还给了一个可直接套用的示例:结构为“上升趋势、位于全部均线上方、守住支撑”时,看涨延续 60%、区间整理 30%、跌破支撑反转 10%。失效位的定义也随之固定:看涨情景跌破关键支撑即失效,看跌情景站上关键阻力即失效,基准区间情景则以任一侧突破为失效。

步骤 5:生成分析报告

报告必须套用模板 skills/technical-analyst/assets/analysis_template.md,包含全部十个章节:

  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. 情景分析(2–4 个带概率的情景)
  9. 总结(Summary)
  10. 免责声明(Disclaimer)

模板本身是填空式结构,例如均线一节要求逐条填写 Price vs 20-week MA: [Above / Below / At]、Alignment: [Bullish / Bearish / Neutral]、Slope: [Rising / Falling / Flat]、Crossovers;情景一节则固定为 Description / Supporting Factors / Target Levels / Invalidation Level 四段。模板末尾的免责声明文字也值得保留原意:分析仅基于技术图表数据,不考虑基本面、新闻与市场情绪,属于概率性评估而非预测或投资建议。

文件命名规则:[SYMBOL]_technical_analysis_[YYYY-MM-DD].md,例如 SPY_technical_analysis_2025-11-02.md,保存到 reports/ 目录(SKILL.md 的 Output 一节明确写出目录)。

步骤 6:处理多张图表

多图场景的规则是串行的:完成第一张图的步骤 3–5 → 保存报告 → 进入下一张 → 重复,直到全部完成。SKILL.md 用了一句话强调:Do not batch analyses.(不要批量分析),必须先完成并保存一份报告再动下一张。文档中的示例是依次产出 BTC_*.md、ETH_*.md、NDX_*.md 三份报告,最后再统一告知用户。

4. 质量标准的三个维度

原文档第 5 步之外,SKILL.md 的 Quality Standards 用三组要求约束输出质量,这实际上是评审报告时的检查清单:

  • 客观性:结论严格基于可观察的图表数据;不引入新闻、基本面、情绪;不使用“我认为”“我感觉”这类主观表述;信号模糊时明确表达不确定性;同时呈现多空两种可能性以避免确认偏误。
  • 完整性:覆盖模板所有章节;给出具体的支撑、阻力与目标价位;用技术因素论证概率;每个情景都有失效位;注明分析局限。
  • 清晰性:术语使用准确;语言专业;结构合乎逻辑;给出具体价位而非模糊描述;情景之间彼此区分且互斥。

框架最后一节还列了六个常见陷阱:过度复杂化(指标太多导致分析瘫痪)、忽略成交量、强行套形态、忽视周期差异(周线与日线可能矛盾)、脱离上下文、以及过度自信(市场是概率性的,不是决定论的)。

5. 逆向确认模式(Shapiro 第 3 步)

这是该技能最有工程含量的一部分,也是原文档第 6 节的重点。它是一个附加模式(additive mode),与上面的纯图表工作流并行存在:只有当用户明确要求做逆向确认时才生效;一句普通的“分析这张图”依然走步骤 1–6 的原流程。该约束同时被写进 SKILL.md 的 Guardrails 和契约测试 test_existing_workflow_identity_phrases_untouched。

5.1 它在整条流水线中的位置

该模式服务于仓库中的 Shapiro COT 逆向交易工作流 workflows/shapiro-contrarian.yaml,其中第 3 步 Confirm weekly price-action reversal 使用的正是 technical-analyst 技能,消费第 1 步的 cot_crowding_report,产出 price_action_confirmation_report,判定问题为:周线图上是否出现了与拥挤方向相反的反转(关键反转、突破失败、极值失败)且 CONFIRMED、并带有明确的摆动止损?

完整链路是:cot-contrarian-detector(第 1 步,识别拥挤)→ news-reaction-failure-analyzer(第 2 步,可选,确认利好/利空消息未被反应)→ technical-analyst(第 3 步,周线价格行为确认) → contrarian-setup-gate(第 4 步,汇总门禁)→ futures-position-sizer(第 5 步,仓位计算)→ trader-memory-core(第 6 步,登记假设)。工作流的 when_not_to_run 明确写着:绝不能只凭拥挤极值就动手,必须等门禁达到 READY_FOR_PLAN(拥挤、消息失败、价格行为三项全部 CONFIRMED)才能进入仓位计算。

5.2 方向约定与严格不等号

方法论全文见 skills/technical-analyst/references/contrarian-confirmation-checklist.md,它与图表模式共享逐字一致的定义,因此 Claude 读图与脚本计算结果应当一致。

方向约定:淡化 CROWDED_LONG(拥挤做多)意味着在上行极值处或之后寻找看跌反转证据——关注高点、关注收盘跌破前低、关注上攻阻力失败。淡化 CROWDED_SHORT 则是完全镜像。

一条贯穿全文的硬规则:所有比较都是严格不等号。等于前期极值不算新极值;收盘价恰好落在前一位阶上不算反转、突破或失败。理由写得也很明确:仅仅“打平”而非“超越”某个位阶的市场,并没有产生新证据。

5.3 窗口术语

术语 默认值 作用
swing_lookback_weeks(摆动回看周数) 13 定义周线关键反转中“近期高低点”的判定范围
extreme_lookback_weeks(极值回看周数) 52 定义较长周期的极值,用于极值失败、突破失败、续势否决,以及关键反转的“高置信加成”条件
signal_recency_weeks(信号新鲜度周数) 4 早于此窗口的信号不构成确认;突破失败只以失败周计入
min_weeks(最小周数硬下限) 30 已完成周数少于此值即 INSUFFICIENT_DATA(insufficient_weekly_bars)

两条容易踩坑的规则:

  1. “前 N 周”永不包含被评估周本身,永远是紧邻其前的 N 个已完成周。
  2. 窗口截断按被评估周分别进行,而不是按整次运行。同一轮新鲜度扫描中的两个不同周,可用历史长度可能不同(例如恰好卡在 min_weeks 下限时的 26 周与 29 周)。源码 skills/technical-analyst/scripts/weekly_price_action.py 中的 compute_prior_window() 正是这么实现的,并把实际使用长度以 *_window_weeks_used 字段回报;test_per_week_differing_available_history_within_recency 用例专门验证了这个差异(同一序列中分别得到 26 与 29)。

5.4 三个信号检查

① 周线关键反转(weekly key reversal)

该周最高价创出摆动回看新高——严格大于前 swing_lookback_weeks 个已完成周的最高价——且该周**收盘价严格低于前一周的最低价。CROWDED_SHORT 镜像为:创新摆动回看新低 且 收盘严格高于前一周最高价。

这是唯一同时引用两个窗口的检查:摆动窗口决定触发,而(更大的)极值窗口被单独检查,仅用于判断同一个新高/新低是否同时也是整个极值窗口的极值——这个更强的条件只喂给置信度判定,从不影响触发本身。源码中对应 is_full_window_extreme 字段与 detect_weekly_key_reversal()。

② 极值失败(failed extreme,周内戳破后收回)

在信号新鲜度窗口内,某一周严格突破前极值回看窗口的最高价,但收盘又跌回同一前高之下——市场在周内推进到新领域,却没能在收盘守住。空头镜像对应低点。它与关键反转的区别在于:不涉及前一周自身的高低点,且使用的是极值窗口而非摆动窗口。

③ 突破失败(failed breakout,确认后被否)

在第 B 周出现周收盘突破前极值回看最高价(真正的收盘突破,而非周内戳破),并在随后 ≤3 个已完成周内出现周收盘重新跌回同一突破位之下。CROWDED_SHORT 为向下镜像。

这里有一个关键细节:该检查返回的 week_of 是失败周(收盘跌回位阶的那一周),绝不是突破周 B。突破周只出现在 detail 文本里。这带来两个后果:其一,只有失败周需要落在 signal_recency_weeks 内,突破周 B 可以更早;其二,由于突破周按构造必然严格早于失败周,它永远不会在续势否决中被当成“新收盘极值”而否决自己的信号(无自我否决)。源码里的循环 for b in range(b_start, n - 1) 与 b_start = max(0, recency_start - 3) 正是为此把搜索起点提前了 3 周。

另一个规则:给定突破之后只有第一次收盘跌回算作该次突破的失败;之后再跌回同一位置不视为同一突破的第二次独立失败(源码中 break 保证了这一点)。

文档给出的示例:突破发生在 W 周、失败发生在 W+2 周、此后无更多 K 线 → CONFIRMED;同样的突破/失败,但第 W+3 周(仍在新鲜度窗口内)创出新收盘高点 → NOT_CONFIRMED(continuation_intact),续势否决生效。

5.5 续势否决与摆动位阶

续势否决(continuation veto)独立于上述三个检查:市场是否在严格晚于最新触发信号的周,创出了与拥挤方向一致的新收盘极值(CROWDED_LONG 指相对每个被评估周自身的前极值窗口而言的新最高收盘价,不是周内最高价)?

  • 若有信号触发,扫描从该信号 week_of 之后一周开始,因此信号周及其之前的一切都不会自我否决;
  • 若完全无信号触发,扫描覆盖整个新鲜度窗口——这样“一路磨着创新高、毫无反转证据”的市场会得到正确的 continuation_intact 原因,而不是笼统的 no_reversal_evidence。

摆动位阶(swing levels):摆动高点指某个已完成周的最高价严格大于其左右各 2 个已完成周的最高价(5 周分形);摆动低点镜像。nearest 取极值窗口内最近的一个分形枢轴。若该窗口内不存在任何分形枢轴,则退化为摆动回看窗口内的最高价(最低价),并以 fallback: true 标记,提示消费方这是较弱的非分形替代值。

stop_reference 跟随淡化方向而非拥挤方向:淡化拥挤多单意味着做空,止损放在上方最近的摆动高点;淡化拥挤空单意味着做多,止损放在下方最近的摆动低点。源码中 compute_swing_levels() 的 search_end = n - 3 保证枢轴点左右都有 2 周数据可用。

5.6 判定合成(失败关闭优先)与置信度

判定顺序是严格的、失败关闭的:

  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)。证据缺失永不构成确认。

置信度规则:HIGH 当且仅当满足下列任一条件——(a) 新鲜度窗口内至少 2 种不同检测器触发(同一检测器重复触发不算两次;由于本模块每种检测器只报告一个最近触发,这一点是自动成立的);(b) 触发的 weekly_key_reversal 所创的新高/新低同时是完整未截断(≥52 周)极值窗口的极值,即其 extreme_window_weeks_used >= 52 且 is_full_window_extreme 为真。其余为 MEDIUM,LOW 保留、v1 从不输出。

文档特意强调:单信号的 MEDIUM 判定是刻意设定的弱证据。一次周线关键反转、一次极值失败或一次突破失败,单独来看只是“有暗示”而非强确认——应视为继续观察的理由,而不是加大仓位的理由。

5.7 输出契约

脚本模式与图表模式共享同一形状(脚本模式示例,字段来自 SKILL.md 与 checklist 的输出契约一节):

symbol: BT
direction: CROWDED_LONG
mode: data            # 图表读取时为 "chart"
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 }

不变式(invariant):只要 verdict: INSUFFICIENT_DATA,checks 与 swing_levels 一律为 null——无论具体原因是 no_price_source、insufficient_weekly_bars 还是 detector-json 被拒。这样下游消费方只需看 verdict 就能决定是否可以安全读取 checks.*,不必按 verdict_reason 分支。该不变式在源码中被两处保证:CLI 的 _insufficient_data_output() 直接写入 None,纯模块 run_weekly_price_action() 在 n < min_weeks 时同样返回 None;测试 test_insufficient_data_below_min_weeks 显式断言了这一点。

文件命名:ta_confirmation_<SYMBOL>_<as-of>.json 与 ta_confirmation_<SYMBOL>_<as-of>.md,写入 reports/。Markdown 报告由 generate_markdown_report() 生成,包含 Verdict、Checks 表格(三检查 + 续势否决)、Swing Levels、可选 Proxy Data Caveat 与 Methodology 段落。

5.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/

CLI 参数一览(默认值取自 skills/technical-analyst/scripts/check_weekly_price_action.py 的 parse_arguments()):

参数 默认值 说明
--symbol 必填 COT 符号(有映射)或普通价格代码
--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(_min_weeks_type 校验)
--output-dir reports/ 输出目录
--format both json / md / both
--api-key 无 优先于环境变量 FMP_API_KEY
--sleep-seconds 0.25 API 调用间最小间隔

--min-weeks 的类型校验值得单独说明:源码注释指出,如果不做 ≥1 校验,--min-weeks 0 会让 n < min_weeks 这个下限判断失效(0 < 0 为假),从而在近乎空数据上错误地输出 NOT_CONFIRMED 而不是 INSUFFICIENT_DATA。这是典型的失败关闭设计细节。

5.9 数据来源:期货到 ETF 的回退链

脚本通过 FMP 的 stable/historical-price-eod/full 接口获取日线 OHLCV,再用 PRICE_SOURCE_CHAINS 做逐级回退。映射表覆盖约 30 个 COT 符号,例如:

"ES": [("ESUSD", "futures", False)],
"NQ": [("NQUSD", "futures", False), ("QQQ", "etf", False)],
"YM": [("YMUSD", "futures", False), ("DIA", "etf", False)],
"QR": [("RTYUSD", "futures", False), ("IWM", "etf", False)],
"ZN": [("ZNUSD", "futures", False), ("IEF", "etf", False)],
"CL": [("CLUSD", "futures", False), ("BZUSD", "futures", False), ("USO", "etf", False)],
"DX": [("DXUSD", "futures", False), ("UUP", "etf", False)],
"BT": [("BTCUSD", "futures", False)],

规则是:按顺序尝试每个 (price_symbol, kind, invert),HTTP 错误或返回 0 行即视为该源失败,首个成功者胜出。有些符号在特定密钥下会返回 402(如源码注释记录的 NQUSD),此时回退链会落到 ETF 代理;而 VX、HO、ZQ 没有代理,只能落到 no_price_source。

当使用了 ETF 代理时,run_context.proxy_used 为真,Markdown 报告会插入一段 Proxy Data Caveat:ETF 代理相对真实期货合约存在跟踪误差、费用拖累与展期时点差异,因此周线位阶比较应视为近似值。

脚本的模块 docstring 还记录了两个实测细节:full 端点用 close 字段,而 light 端点用 price 字段(源码称之为 #245 bug class 的字段名陷阱);build_sorted_daily_series() 对两者做防御性兼容,test_accepts_price_field_fallback 覆盖了这条。

另外,--symbol 并不限于 COT 期货符号:若不在映射表中,回退链会把它当作普通 FMP 价格代码处理([(symbol, "direct", False)]),毕竟该技能本身覆盖股票、股指、加密货币与外汇。

5.10 无前视与失败关闭

脚本的防前视(no lookahead)机制有两层:

  1. 先截断,后重采样:fetch_price_series() 在把某个源判定为成功之前,先过滤掉 b["date"] > as_of 的日线;resample_weekly() 内部也再次丢弃晚于 as_of 的 K 线。
  2. 当前进行中的 ISO 周一律排除:resample_weekly() 计算 as_of 所属的 ISO 周并跳过它——无论该周是否已经攒满 5 个交易日。而非 as_of 周即便是节假日缩短的 3 天周,也属于已完成周,正常重采样。测试 test_current_in_progress_week_always_excluded、test_as_of_truncation_before_resample_drops_partial_week、test_holiday_short_week_still_counts_as_completed 分别钉住了这三条。加密货币的周末 K 线按其自身日期归入本 Mon–Sun 周(周日不归入下一周),test_bt_style_weekend_bars_attribute_to_own_iso_week 覆盖。

抓取窗口长度的计算也值得注意:

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

WEEKS_FETCH_BUFFER = 10 这 10 周缓冲是为节假日稀疏的日历预留的,确保极值窗口、新鲜度窗口与 min_weeks 下限都有真实周线可用。

失败关闭是这一层的核心哲学:--detector-json 缺失/不可读、语法非法、结构畸形、陈旧、未来日期、分类不是 CROWDED_*,或价格历史不足 --min-weeks,或没有可用价格源——一律不崩溃,改写 INSUFFICIENT_DATA 报告并以退出码 0 结束。对应的 verdict_reason 分别是 detector_json_unreadable / detector_json_parse_error / malformed_detector_json / detector_json_stale / detector_future_data_date / not_crowded / insufficient_weekly_bars / no_price_source。

源码里甚至记录了两轮评审发现的回归点:load_json_file() 过去对“文件不可读”和“JSON 非法”两种情况都不区分原因标签、直接退出 1 且不写报告;以及非 UTF-8 文件会抛 UnicodeDecodeError(属于 ValueError/UnicodeError 而非 OSError)从而越出异常捕获导致 traceback。最终捕获的异常类型定为 (OSError, UnicodeError),并刻意不捕获 MemoryError——因为那不属于“输入有问题”。

请求层还有一层保护:_request_with_backoff() 对 429 与 5xx 做最多 4 次指数退避重试,而 401/402/403/404 等不可重试的 4xx 立即失败——其中 402 是预期内的常态(用于推进回退链),重试它没有意义。

5.11 密钥脱敏:双层策略

requests 的异常字符串会把完整请求 URL(含 ?apikey=...)嵌进去。源码的 _redact() 因此采用双层:值替换为主(传入已知的 secret,用 ***REDACTED*** 替换),模式族为辅(四条正则覆盖 apikey=...、"apikey":"..."、'apikey':'...'、URL 编码的 apikey%3d...)。注释明确说明:仅靠模式只能命中带 apikey 标记的形态,仅靠值替换又漏掉未知形态,两者缺一不可。

5.12 COT 市场数据新鲜度校验

这是较新加入的一段校验逻辑(原文档第 6 节开头有对应描述)。除了报告级的 run_context.data_date,还要检查所选市场的 markets[].data_date 与 data_provenance.market_data_dates[symbol]。每个日期都必须:非空、可解析、不晚于 --as-of、且不早于 --max-detector-age-days(边界日期本身被接受)。审计年龄取所有已校验日期中最老的那个,而原始 run context 不被修改。

旧格式报告可能缺少行级/映射级日期,此时回退到报告日期;但显式存在的 null、空串或非法日期,以及畸形的 provenance/map 容器,一律失败关闭,沿用既有的 missing/invalid/future/stale 原因码。其他符号的行级/映射级日期不会替代所选市场的版本。解析沿用既有的“取前 10 个字符”日期解析,因此这不是一个更严格的全时间戳或 provenance schema 校验器——这一点在文档中被显式声明为兼容性约束。

源码对应实现是 _market_vintage_values() 与 resolve_direction_from_detector():前者在字段缺失时返回已有值列表,在容器类型错误时返回 None(触发 detector_invalid_data_date);后者在遍历候选日期时,会把更老的日期写回 ctx["data_date"] 与 ctx["detector_age_days"]。

5.13 图表模式与脚本模式的分歧规则

两种模式可能对同一 symbol/direction 给出不同结论。此时采用保守优先规则:

  • 两者都有结论且不一致 → 最终判定为 NOT_CONFIRMED,verdict_reason: mode_disagreement,并附上两个子结果供人工并排复核,绝不静默偏好某一模式;
  • 一方为 INSUFFICIENT_DATA、另一方为干净结论 → 干净结论成立,并把另一方的“数据不足”作为注解记录,而不是当作分歧。

图表模式的操作步骤也被固定下来:确认要淡化的拥挤方向 → 用与脚本完全相同的严格定义,在最近 signal_recency_weeks(默认 4)根周线中目视扫描三种形态 → 检查是否有比第 2 步发现更新的、与拥挤方向一致的收盘极值(续势否决)→ 找出最近的摆动高/低点作为止损参考 → 输出同样 mode: chart 的 YAML 块。文档特别允许图表模式的 window_weeks_used 是近似值——但要求在 detail 中明确标注这一点,而不是伪造虚假精度。

5.14 护栏

七条护栏必须与结论一起被理解:

  • 只给判定,本身绝不是交易建议。这确认的是 5 步流程中的第 3 步;进出场规划仍需人工完成,仓位大小属于 position-sizer / futures-position-sizer。
  • INSUFFICIENT_DATA 永不推进流水线,所有劣化输入都失败关闭,且始终以退出码 0 写出报告。
  • 仅限周线周期,方法论完全以已完成的 ISO 日历周定义,不涉及日线或日内。
  • 既有图表分析工作流不变,本模式仅在明确请求逆向确认时激活。
  • 单信号 MEDIUM 是刻意设定的弱证据,不得与 HIGH(双信号或全窗口极值)等价看待。

6. 源码结构导读:纯计算与 I/O 的分层

该技能的脚本层刻意分成两个文件,边界清晰:

  • skills/technical-analyst/scripts/weekly_price_action.py:纯函数模块,无 I/O、无网络。所有函数只接收 dict/list/标量并返回普通值,因此可以完全离线单测。对外接口包括 build_sorted_daily_series()、resample_weekly()、compute_prior_window()、detect_weekly_key_reversal()、detect_failed_extreme()、detect_failed_breakout()、detect_continuation()、compute_swing_levels()、synthesize_verdict()、compute_confidence() 与顶层编排 run_weekly_price_action()。常量 SWING_LOOKBACK_WEEKS_DEFAULT = 13、EXTREME_LOOKBACK_WEEKS_DEFAULT = 52、SIGNAL_RECENCY_WEEKS_DEFAULT = 4、MIN_WEEKS_DEFAULT = 30、CONFIDENCE_HIGH_EXTREME_WEEKS = 52 都定义在这里。
  • skills/technical-analyst/scripts/check_weekly_price_action.py:CLI 与 I/O 层。负责方向解析、价格抓取与回退、退避重试、脱敏、报告生成与退出码管理,然后把数据喂给纯模块。

这种分层直接体现在测试布局上:

运行测试的方式(与测试文件头部注释一致):

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

一个容易被忽略的实现细节:CONFIDENCE_HIGH_EXTREME_WEEKS = 52 是独立常量,而不是直接读取调用方传入的 extreme_lookback_weeks。源码注释解释了原因——这样即使调用方用了非默认的极值窗口,高置信门槛仍是良定义(尽管可能无法达成),而不是一个移动靶。实践中调用方应按默认 52 周运行。

7. 实践建议

把读图与脚本当作互补,而不是替代。 图表模式能捕捉脚本无法量化的东西(K 线形态、量价配合的质感、趋势线的贴合度);脚本模式能提供可审计、可复现、可入库的确定性结论。文档的设计意图就是两者判定一致、分歧时保守处理。

关注 verdict_reason 而不是只看 verdict。 CONFIRMED + key_reversal 与 CONFIRMED + failed_extreme 说的是不同性质的市场行为;NOT_CONFIRMED + continuation_intact(市场仍在为拥挤方付钱)与 NOT_CONFIRMED + no_reversal_evidence(只是没证据)在流程含义上也完全不同。

把 MEDIUM 当作“继续观察”,把 HIGH 当作“有分量”。 单信号弱证据的设定是刻意的——这也是为什么 confidence 字段要一路带进 handoff 块。

检查 proxy_used。 当回退到 ETF 代理时,周线位阶的精确比较会失真,报告里的 Proxy Data Caveat 必须在解读时被读到。

理解 INSUFFICIENT_DATA 是功能而非故障。 它意味着输入已劣化(历史太短、价格源缺失、检测器报告不可用或过期),流水线在此停止是设计目标。想排查原因,读 verdict_reason 与 run_context 就够了。

报告命名与落盘位置是契约的一部分。 技术分析报告固定为 [SYMBOL]_technical_analysis_[YYYY-MM-DD].md,逆向确认报告固定为 ta_confirmation_<SYMBOL>_<as-of>.json/.md,均写入 reports/。下游技能与工作流正是按这些模式去寻找产物。

8. 相关资源


免责声明:本文描述的分析方法与输出均为基于技术图表数据的概率性评估,不考虑基本面因素、新闻或市场情绪,不构成预测或投资建议。所有概率都是基于技术因素的估计,并会随新数据变化。逆向确认模式的输出仅为流程判定,本身绝不是交易建议;进出场规划与仓位大小属于下游技能的职责。

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