claude-trading-skills technical-analyst 技能实战:周线图表技术分析与 Shapiro 逆向确认模式
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 会断言其中的关键短语不得被后续改动侵蚀:
- Pure Chart Analysis(纯图表分析):所有结论只基于图中可见的技术数据。
- Systematic Approach(系统化):每张图走同一套结构化方法论,而不是凭感觉挑指标。
- Objective Assessment(客观评估):聚焦可观察形态,压制主观偏好。
- Probabilistic Scenarios(概率情景):把未来表达为带权重的场景,而不是单一预测。
- 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 个互斥情景,每个情景包含六要素:
- 情景名称(如“Bull Case: Breakout Above Resistance”);
- 概率估计(全部情景必须合计 100%);
- 描述:该情景意味着什么、如何演进;
- 支撑因素:至少 2–3 条技术证据;
- 目标价位;
- 失效位:明确到具体价位的否定条件。
原文档给出的典型分布是:基准情景 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 |
三条容易踩空的语义细节:
- “prior N weeks” 永远排除被评估的那一周本身;
- 窗口截断按“被评估周”计算,而不是按“整次运行”计算——同一次时效扫描中,不同周可能有不同的可用历史(例如刚好卡在
min_weeks下限时的 26 周与 29 周),而置信度 HIGH 的 52 周极值条件只读“实际触发的那一周”的窗口大小; 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)
顺序固定,且尽早返回:
- 完成周数 <
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)。没有证据永远不等于确认。
多个检测器在同一周触发时的平局,按 _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 交给流水线下一步。
九、局限与正确使用边界
以下几点不是“注意事项”套话,而是这套方法在实现层面就承认的限制:
- 本技能不是预测器。它输出的是带概率与失效位的情景;模板的免责声明明确写着“这是概率评估,不是预测或投资建议”。
- 周线专用。所有定义都按完成的 ISO 日历周表述,对日线或分时价格行为没有任何陈述;混用周期会直接导致结论错位。
- ETD 代理会引入偏差。当
proxy_used: true时,周线级别的高低点比较只能视为近似。 - 数据不足不构成弱结论。
INSUFFICIENT_DATA不是“倾向于不反转”,它就是“无法判断”,且永远不会推进下游流水线。 - 单信号 MEDIUM 必须谨慎对待。它被刻意设计成弱证据,用于触发“继续观察”,而不是“加大仓位”。
- 没有图表时不要假装读过图。若使用脚本兜底,报告里的
mode应为data;若使用图表判读,window_weeks_used允许近似,但必须在detail中显式说明,而不是伪造精度。 - 本模式只确认流程第 3 步。入场、出场与仓位规模都在下游技能与人工决策中完成。
十、小结
technical-analyst 在一个技能里同时提供了两种互补的工作方式:面向单张图片的深度判读(六步工作流 + 十节模板 + 概率情景),以及面向流水线审计的确定性裁决(三项周线信号 + 延续否决 + 分形止损参考 + 机读契约)。
它的设计取向相当克制:所有比较都是严格不等式,所有窗口都回报“实际用了多少”,所有降级输入都失败关闭并留下报告,所有输出都有唯一且稳定的形状。想让这套能力在你的工作流中复现,最短路径是:先读 technical_analysis_framework.md 统一判据,再按 analysis_template.md 固定输出结构;需要机读结论时,直接运行 check_weekly_price_action.py 并消费 reports/ta_confirmation_*.json 中的 verdict 与 handoff.price_action。