claude-trading-skills Technical Analyst 技能详解:周线图技术分析与 Shapiro 逆向确认模式
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 中:
- Pure Chart Analysis:所有结论只基于图表上可见的技术数据;
- Systematic Approach:每张图走同一套结构化方法;
- Objective Assessment:避免主观偏好,聚焦可观察的形态与数据;
- Probabilistic Scenarios:用概率加权情景表达未来可能性,而不是给出确定性预测;
- 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 个互斥情景。原文档规定每个情景必须含六要素:
- 情景名称:清晰描述性标题,例如“看涨情景:突破阻力上行”;
- 概率估计:基于技术因素的发生概率,所有情景合计 100%;
- 描述:该情景包含什么、会如何展开;
- 支撑因素:支持该情景的技术证据,至少 2–3 条;
- 目标位:情景实现时的预期价格水平;
- 失效位:证伪该情景的具体价格水平。
典型分布为:基准情形 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,包含全部十个章节:
- 图表概览(Chart Overview)
- 趋势分析(Trend Analysis)
- 支撑与阻力位(Support and Resistance Levels)
- 均线分析(Moving Average Analysis)
- 成交量分析(Volume Analysis)
- 形态与价格行为(Chart Patterns and Price Action)
- 当前市场评估(Current Market Assessment)
- 情景分析(2–4 个带概率的情景)
- 总结(Summary)
- 免责声明(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) |
两条容易踩坑的规则:
- “前 N 周”永不包含被评估周本身,永远是紧邻其前的 N 个已完成周。
- 窗口截断按被评估周分别进行,而不是按整次运行。同一轮新鲜度扫描中的两个不同周,可用历史长度可能不同(例如恰好卡在
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 判定合成(失败关闭优先)与置信度
判定顺序是严格的、失败关闭的:
- 已完成周数少于
min_weeks,或无可用价格源 →INSUFFICIENT_DATA(insufficient_weekly_bars/no_price_source)。 - 续势否决生效(最新信号之后出现与拥挤方向一致的新收盘极值;或在新鲜度窗口内根本无信号但仍在创新收盘极值)→
NOT_CONFIRMED(continuation_intact)。这一条永远优先于已触发的信号。 - 否则,若三个检查中有任一在新鲜度窗口内触发 →
CONFIRMED,verdict_reason取产生最新触发信号的检测器(key_reversal/failed_extreme/failed_breakout)。 - 否则 →
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)机制有两层:
- 先截断,后重采样:
fetch_price_series()在把某个源判定为成功之前,先过滤掉b["date"] > as_of的日线;resample_weekly()内部也再次丢弃晚于as_of的 K 线。 - 当前进行中的 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 层。负责方向解析、价格抓取与回退、退避重试、脱敏、报告生成与退出码管理,然后把数据喂给纯模块。
这种分层直接体现在测试布局上:
- skills/technical-analyst/scripts/tests/test_weekly_price_action.py:867 行的纯逻辑测试,用合成周线覆盖“等于不是超越”“信号超出新鲜度窗口不算”“突破周不得成为
week_of”“突破周不得自我否决”“截断窗口无法达成高置信”等边界。 - skills/technical-analyst/scripts/tests/test_check_weekly_price_action.py:用假的
requests.Session打桩,测试回退链、detector-json 守卫、脱敏与报告生成,不发起真实网络请求。 - skills/technical-analyst/scripts/tests/test_skill_contract.py:锁定 SKILL.md 的提示词契约。
运行测试的方式(与测试文件头部注释一致):
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. 相关资源
- 技能定义与提示词契约:skills/technical-analyst/SKILL.md
- 技术分析方法论:skills/technical-analyst/references/technical_analysis_framework.md
- 逆向确认清单(图表模式与脚本模式共享的定义):skills/technical-analyst/references/contrarian-confirmation-checklist.md
- 报告模板:skills/technical-analyst/assets/analysis_template.md
- 确定性计算模块:skills/technical-analyst/scripts/weekly_price_action.py
- 数据驱动 CLI:skills/technical-analyst/scripts/check_weekly_price_action.py
- 所在工作流:workflows/shapiro-contrarian.yaml
- 站点文档页(日文):docs/ja/skills/technical-analyst.md
- 站点文档页(英文):docs/en/skills/technical-analyst.md
免责声明:本文描述的分析方法与输出均为基于技术图表数据的概率性评估,不考虑基本面因素、新闻或市场情绪,不构成预测或投资建议。所有概率都是基于技术因素的估计,并会随新数据变化。逆向确认模式的输出仅为流程判定,本身绝不是交易建议;进出场规划与仓位大小属于下游技能的职责。