Sector Analyst 技能详解:基于公开 CSV 的板块轮动与市场周期定位分析(claude-trading-skills)

原创2026-11-14 20:55:442,133 阅读
文章标签:金融科技AI 技能人工智能数据分析

Sector Analyst 技能详解:基于公开 CSV 的板块轮动与市场周期定位分析(claude-trading-skills)

本文以 claude-trading-skills 仓库中的 Sector Analyst 技能为对象,系统拆解它如何在不使用任何 API Key 的前提下,从 TraderMonty 公开 CSV 数据集中读取板块上升趋势比率(uptrend ratio),完成板块排名、周期/防御风险状态打分、超买超卖识别与市场周期相位推断,并输出结构化的 Markdown 或 JSON 报告。读完后你将能够独立运行分析脚本、理解每一项打分的计算来源,并按照技能定义的 5 步工作流把定量结果扩展成带概率的场景分析。


1. 技能定位与核心能力

Sector Analyst 的定位是“板块轮动 + 市场周期定位”的分析器。根据技能文档 SKILL.md 的描述,它的能力可以归纳为四件事:

  1. 按 uptrend ratio 对板块做降序排名;
  2. 计算 cyclical(周期)与 defensive(防御)两组的风险状态分(risk regime score);
  3. 标记 ratio 超过或跌落阈值的超买 / 超卖板块;
  4. 估计当前处于市场周期的哪个相位,并给出置信度。

图表图片是可选输入,仅用于在板块之下补充 industry(细分行业)层面的细节,主分析输入始终是 CSV。这一点在日文文档 docs/ja/skills/sector-analyst.md 中有明确表述:“CSV からセクターのアップトレンドデータを取得し(APIキー不要)、補足分析としてチャート画像も受け付けます”。

一个容易被忽略但很实用的特性是零第三方依赖:脚本 analyze_sector_rotation.py 的模块注释直接写明 Dependencies: stdlib only (urllib, csv, json, argparse, dataclasses),requirements.txt 也只有一行注释 # stdlib-only: packaged scripts use the Python standard library only.。这意味着你在任何只装了 Python 3.9+ 的环境里都能直接运行,不会因为 pip install 失败而卡在数据获取环节。


2. 何时使用(以及何时不该用)

日文文档列出的触发场景(docs/ja/skills/sector-analyst.md)可以直接作为意图识别规则使用:

  • 请求板块轮动分析(无需图表图片)
  • 询问周期股与防御股的相对定位
  • 想知道哪些板块处于超买或超卖
  • 需要估计市场周期相位
  • 提供了板块表现图表,希望做补充分析
  • 需要基于板块的情景分析或预测

对应的自然语言请求示例:

「セクターローテーション分析を実行して」        → Run a sector rotation analysis
「シクリカルとディフェンシブ、どちらが優位?」   → Which sectors are leading — cyclical or defensive?
「今買われすぎのセクターはある?」               → Are any sectors overbought right now?
「マーケットサイクルのどのフェーズにいる?」     → What phase of the market cycle are we in?
「このセクターパフォーマンスチャートを分析して」 → Analyze these sector performance charts

边界提示:如果你想做的是“市场宽度(breadth)不依赖板块划分”的整体健康度判断,仓库中的 breadth-chart-analyst 文档明确建议改用 sector-analyst 处理“无宽度图情况下的板块轮动分析”——反过来看,breadth-chart-analyst 负责宽度类指标,Sector Analyst 负责板块层面的相对强弱,两者是互补而非替代关系。


3. 前置条件

项目 要求 依据
Python 3.9+(脚本使用 from __future__ import annotations 兼容 3.9 的 `X None` 注解)
第三方库 无 requirements.txt
API Key 不需要,数据来自公开 GitHub raw CSV SKILL.md
网络 需要能访问 raw.githubusercontent.com;因此属于“在线运行”技能 脚本常量 SECTOR_CSV_URL / UPTREND_CSV_URL
图片能力 可选,仅在补充 industry 级别分析时使用 SKILL.md

注意日文文档的“前提条件”只写了“图像分析功能 / Python 3.9+ 推奨”(docs/ja/skills/sector-analyst.md),但读取 SKILL.md 后可以确认:脚本本身不需要任何图像能力,图像只在可选路径上使用。这是日文精简版与 SKILL 原文之间的一处信息差,实际部署时以 SKILL 为准更稳妥。


4. 数据源与字段契约

4.1 两个 CSV 的分工

脚本在文件头部定义了两个数据源常量(analyze_sector_rotation.py):

SECTOR_CSV_URL = (
    "https://raw.githubusercontent.com/tradermonty/uptrend-dashboard/main/data/sector_summary.csv"
)
UPTREND_CSV_URL = (
    "https://raw.githubusercontent.com/tradermonty/uptrend-dashboard"
    "/main/data/uptrend_ratio_timeseries.csv"
)
  • sector_summary.csv:主数据,每个板块一行,含 ratio、10MA、trend、slope、status。作为全部分析的输入。
  • uptrend_ratio_timeseries.csv:只用于新鲜度检查——取 date 列的最大值判断数据是否过期,不参与打分。

仓库为该数据源维护了正式的 provider contract,见 config/provider-contracts/trader-monty/uptrend-sector-summary.v1.json:owners 字段列出了 uptrend-analyzer、sector-analyst、theme-detector、breadth-chart-analyst,tier_notes 说明其层级为“raw.githubusercontent.com, no API key; latest snapshot per sector”。这份契约同时给出了字段类型与可空性:Sector/Ratio/Trend/Status 不可为空,10MA/Slope 可空但要求 reject_all_null。这解释了脚本为什么把 10MA 和 Slope 当作可选字段处理。

4.2 列校验:必需列 vs 可选列

脚本用两个集合区分严重级别(analyze_sector_rotation.py):

REQUIRED_COLUMNS = {"Sector", "Ratio"}
EXPECTED_COLUMNS = {"Sector", "Ratio", "10MA", "Trend", "Slope", "Status"}

行为差异很关键:

  • 缺少 Sector 或 Ratio → 抛 ValueError,main() 捕获后以 SystemExit(1) 退出,因为排名和分组打分都依赖这两个字段;
  • 缺少其余列 → 只在 stderr 打印 WARNING: Missing optional columns: [...],分析继续执行。

对应的单元测试明确覆盖了这两种路径:test_analyze_sector_rotation.py 中的 test_missing_required_column_raises(用 pytest.raises(ValueError, match="Sector") 断言)和 test_missing_optional_column_warns(用 capsys.readouterr().err 断言出现 WARNING)。

4.3 行级容错

parse_sector_rows()(analyze_sector_rotation.py)对坏行采取“跳过而非报错”的策略:Sector 为空跳过、Ratio 为空跳过、Ratio 无法转成 float 跳过。测试用例 test_missing_ratio_skips_row、test_non_numeric_ratio_skips_row、test_missing_sector_skips_row 逐一验证了这三种情况都返回空列表而非异常(test_analyze_sector_rotation.py)。

10MA 与 Slope 走 _safe_float(),解析失败返回 None 而不是中断;对应测试 test_missing_optional_fields_use_defaults 断言 ma_10 is None、slope is None、status == ""(test_analyze_sector_rotation.py)。还有一个容易踩坑的细节:CSV 实际列名是 10MA 而不是 MA_10,测试 test_ma_10_parsed_from_10MA_column 专门锁定了这一点(test_analyze_sector_rotation.py)。


5. 快速开始与完整 CLI 参数

日文文档给出的最小命令是(docs/ja/skills/sector-analyst.md):

python3 skills/sector-analyst/scripts/analyze_sector_rotation.py

这是在仓库根目录下执行的写法。如果你已经进入技能目录,则按 SKILL.md 中的相对路径写法:

# 默认:抓取 CSV,打印人类可读的 Markdown 分析
python3 scripts/analyze_sector_rotation.py

# JSON 输出,便于下游技能消费
python3 scripts/analyze_sector_rotation.py --json

# 保存到文件
python3 scripts/analyze_sector_rotation.py --save --output-dir reports/

argparse 定义的全部参数(analyze_sector_rotation.py)如下,其中默认值和含义均取自源码:

参数 类型 默认值 作用
--json flag 关闭 输出 JSON 而非 Markdown
--save flag 关闭 将输出写入文件
--output-dir str reports/ 保存目录,自动 os.makedirs(..., exist_ok=True)
--url str SECTOR_CSV_URL 覆盖板块汇总 CSV 地址
--uptrend-url str UPTREND_CSV_URL 覆盖 freshness 检查用的时间序列 CSV 地址
--timeout int 30 HTTP 超时秒数,同时作用于两个请求

保存文件名由日期和格式决定(analyze_sector_rotation.py):

ext = ".json" if args.json else ".md"
filename = f"sector_rotation_{date.today().isoformat()}{ext}"
# 例:reports/sector_rotation_2026-11-14.md

--url / --uptrend-url 的存在让这份脚本可以离线自测或指向内部镜像:只要目标 CSV 拥有同样的列结构,validate_columns() 的契约就会生效。


6. 输出结构逐段解析

format_human()(analyze_sector_rotation.py)按固定顺序拼装 Markdown。理解每个区块的来源,才能判断一份输出到底可信到什么程度。

6.1 数据日期与新鲜度警告

输出开头先处理 freshness:

> **WARNING**: Data is 12 days old (latest: 2026-11-02)

或无警告时:

> Data as of: 2026-11-13

判定逻辑在 check_freshness()(analyze_sector_rotation.py):取时间序列 CSV 中所有 date 字符串的字典序最大值,按 %Y-%m-%d 解析为日期,与 date.today() 求天数差,超过 FRESHNESS_MAX_DAYS = 5(analyze_sector_rotation.py)即告警。

这里有一个刻意的健壮性设计:freshness 抓取失败不会让整个脚本退出,check_freshness() 在 urllib.error.URLError 或 OSError 时返回 None,main() 只打印 WARNING: Could not check data freshness (continuing) 并继续(analyze_sector_rotation.py)。测试 test_fetch_failure_returns_none 与 test_no_error_log_on_fetch_failure 一起保证了“返回 None 且不写 ERROR 日志”这两个约定(test_analyze_sector_rotation.py)。test_order_independent 则验证了最大日期与行顺序无关。

6.2 Risk Regime 区块

## Risk Regime

**RISK-ON** (score: 78/100)

- Cyclical avg: 24.8%
- Defensive avg: 11.3%
- Difference: 13.5pp
- Commodity avg: 21.0%
- **Late Cycle Flag**: Commodity sectors leading both cyclical and defensive
- **Divergence Flag**: High intra-group spread detected

score 的计算链路是本文最值得关注的部分,见下一节。

6.3 Cycle Phase Estimate 区块

## Cycle Phase Estimate

**Early** (confidence: high)

- Early: 82.5 ←
- Mid: 61.0
- Late: 20.0
- Recession: 15.0

Evidence:
- Leaders in top ranks: Technology, Consumer Cyclical, Industrials, Financial
- Laggards in bottom ranks: Utilities, Consumer Defensive, Healthcare

四个相位的分数与最终选中的相位都会被打印,← 标记当前最佳相位;evidence 只列出“命中的 leaders/laggards”名单,便于复核。

6.4 排名表、趋势摘要、超买超卖

排名表按 ratio 降序(analyze_sector_rotation.py),列固定为 Rank / Sector / Ratio / Trend / Status,其中 ratio_pct 是 ratio * 100 保留一位小数:

| Rank | Sector | Ratio | Trend | Status |
|------|--------|-------|-------|--------|
| 1 | Energy | 46.8% | Up | Overbought |
| 2 | Technology | 34.4% | Down | Normal |

趋势摘要给两个计数:

- Uptrending: 7 sectors
- Downtrending: 4 sectors

超买超卖区块仅在至少一侧命中时才出现,其标题直接暴露阈值:**Overbought** (ratio > 37%) 与 **Oversold** (ratio < 9.7%)。

6.5 JSON 输出模式

format_json()(analyze_sector_rotation.py)输出六个顶层键,ensure_ascii=False 保证非 ASCII 板块名不被转义:

{
  "meta": { "generated_at": "...", "date": "...", "freshness": {...} },
  "groups": {...},
  "cycle_phase": {...},
  "ranking": [...],
  "overbought": [...],
  "oversold": [...],
  "trends": {...}
}

测试 test_valid_json 与 test_json_has_meta_section 断言 ranking、groups、cycle_phase、meta.generated_at 均存在(test_analyze_sector_rotation.py),因此下游消费者可以依赖这套 schema。


7. 源码级原理:三个核心算法

7.1 板块三分组与 risk regime 打分

脚本把 11 个板块硬编码成三组(analyze_sector_rotation.py),并注明与 uptrend-analyzer 的 sector_rotation_calculator.py(L31-47)保持一致:

组别 成员 数量
Cyclical Technology、Consumer Cyclical、Communication Services、Financial、Industrials 5
Defensive Utilities、Consumer Defensive、Healthcare、Real Estate 4
Commodity Energy、Basic Materials 2

注意 Communication Services 被划入 cyclical 组,这与参考文档 sector_rotation.md 中把 Communication Services 归为 defensive 的表述存在差异。写报告时应以脚本的划分(因为分数由它产生)为准,并把这一口径差异当作解释时的注意事项,而不是悄悄混用。

打分流程(analyze_groups(),analyze_sector_rotation.py):

  1. 分别求 cyclical_avg、defensive_avg、commodity_avg;某个板块在本期 CSV 中缺失则不计入该组平均。
  2. difference = cyclical_avg - defensive_avg,经 _difference_to_score() 映射到 0–100 的基础分。
  3. 若 commodity_avg 同时高于 cyclical_avg 与 defensive_avg,置 late_cycle_flag = True,并按超出幅度罚分:超出 > 0.10 罚 -10,否则罚 -5。
  4. 若组内出现离散(divergence_flag),再罚 -5。
  5. score = round(min(100, max(0, base + commodity_penalty + divergence_penalty))),最后映射为 regime 标签。

基础分的分段线性函数(analyze_sector_rotation.py)值得完整列出,因为它是所有分数的来源:

difference 区间 分数公式 区间端点分值
> 0.15 min(100, 90 + (diff - 0.15) / 0.10 * 10) 0.15 → 90,0.25 及以上 → 100
> 0.05 70 + (diff - 0.05) / 0.10 * 19 0.05 → 70,0.15 → 89
> -0.05 45 + (diff + 0.05) / 0.10 * 24 -0.05 → 45,0.05 → 69
> -0.15 20 + (diff + 0.15) / 0.10 * 24 -0.15 → 20,-0.05 → 44
其余 max(0, 19 + (diff + 0.15) / 0.10 * 19) -0.25 → 0

也就是说,cycle 组仅比防御组高 5 个百分点(0.05)时,分数正好落在 70 分边界——这解释了为什么“看似温和的领先”经常直接进入 risk-on 区间。

regime 标签的切分(analyze_sector_rotation.py):

分数 标签
≥ 90 strong risk-on
≥ 70 risk-on
≥ 45 balanced
≥ 20 defensive tilt
< 20 strong risk-off

测试对这条链路做了行为级锁定:全体 ratio 相同 → difference = 0、regime 为 balanced(test_balanced_scenario);周期组 0.35 / 其余 0.10 → regime 落在 risk-on 或 strong risk-on(test_risk_on_scenario);防御组 0.35 / 其余 0.05 → 落在 defensive tilt 或 strong risk-off(test_risk_off_scenario);并且对 0.01/0.10/0.20/0.30/0.45 五档输入断言 0 <= score <= 100(test_score_range_0_to_100,test_analyze_sector_rotation.py)。

7.2 数据不完整时的降级

如果 cyclical 或 defensive 组一个板块都没取到,analyze_groups() 直接返回中性结果:score = 50、regime = "incomplete data"、两个 flag 均为 False(analyze_sector_rotation.py)。这是一个安全默认值——50 分落在 balanced 区间内,不会因为缺数据而误报成 risk-off。遇到 INCOMPLETE DATA 字样时,报告中必须显式声明数据不足,不能把 50 分当成“市场中性”的实证结论。

7.3 组内离散度检测

_calculate_group_divergence() 与 _analyze_group()(analyze_sector_rotation.py)对 cyclical 和 defensive 两组分别计算标准差、极差、离群点和趋势背离:

  • 样本数 < 2 → 直接返回 flagged: False,避免对单点求标准差;
  • 标准差用总体公式 sqrt(sum((r-mean)^2)/n);
  • 离群点判定:abs(ratio - mean) > 1.5 * std_dev 且 std_dev > 0;
  • 趋势“异见者”:组内多数趋势为 up(或 down)时,任何与多数相反的板块被记录;
  • 触发条件:std_dev > 0.08 或 spread > 0.20 或 存在趋势异见者。

测试 test_divergence_flag_high_spread 构造了 Technology=0.45、Industrials=0.05 的极端组合来触发该 flag(test_analyze_sector_rotation.py)。实战含义是:当同属 cyclical 的板块内部方向分裂时,即便组平均分很好看,也应降低对 regime 结论的信任度。

7.4 超买超卖阈值与严格不等号

阈值定义为常量(analyze_sector_rotation.py):

OVERBOUGHT_THRESHOLD = 0.37
OVERSOLD_THRESHOLD = 0.097

判定使用严格不等号:ratio > 0.37 才算超买,ratio < 0.097 才算超卖(analyze_sector_rotation.py)。测试 test_boundary_values 用恰好等于 0.37 和 0.097 的两个板块断言“两者都不触发”(test_analyze_sector_rotation.py)。这不是随手写的边界:它意味着 37.0% 的板块会被报告为 Normal 而非 Overbought,写报告时若自行四舍五入成“约 37% 即超买”就会与脚本输出矛盾。

另外需要注意 elif 结构:一个板块不可能同时被计入超买和超卖,但这也意味着当阈值被配置成重叠区间时只会命中前者。按当前默认值两者无重叠,不存在实际风险。

7.5 周期相位估计的加权评分

estimate_cycle_phase()(analyze_sector_rotation.py)是唯一带有“知识库语义”的模块。每个相位的期望 leaders/laggards 定义在 CYCLE_PHASES(analyze_sector_rotation.py):

相位 Leaders Laggards
early Technology、Consumer Cyclical、Industrials、Financial Utilities、Consumer Defensive、Healthcare
mid Technology、Industrials、Consumer Cyclical、Energy Utilities、Consumer Defensive
late Energy、Basic Materials、Healthcare Technology、Consumer Cyclical、Industrials
recession Utilities、Consumer Defensive、Healthcare Technology、Consumer Cyclical、Industrials、Financial

计算步骤:

  1. 按 ratio 降序后切成上下半区:top_half = 前 n//2 + 1 个,bottom_half = 从 n//2 开始。11 个板块时两者在中间位置有重叠(第 6 名同时属于两个集合),这是刻意的宽松处理,避免中位板块被硬性归边。
  2. 三项子分数:
    • leader_score = 命中的期望 leaders 数 / leaders 总数,权重 0.4;
    • laggard_score = 落在下半区的期望 laggards 数 / laggards 总数,权重 0.3;
    • trend_score = (leaders 中 trend=up 的数量 + laggards 中 trend=down 的数量) / 有数据的总数,权重 0.3。
  3. 总分 = (0.4*leader + 0.3*laggard + 0.3*trend) * 100,四舍五入到一位小数。
  4. 取最高分相位为结果;与第二名分差 gap > 20 → high,gap > 10 → moderate,否则 low。

置信度只反映相位之间的区分度,不反映数据质量。因此“high confidence + 数据已过期 20 天”是完全可能同时出现的组合——这也是为什么工作流第 1 步要求把 freshness 警告一并写进分析。

测试从四个方向校验了这一算法:make_early_cycle_scenario() → phase == "early";make_late_cycle_scenario()(Energy/Basic Materials 0.40,Technology/Consumer Cyclical 0.10)→ "late";make_recession_scenario()(Utilities/Healthcare/Consumer Defensive 0.40,其余 0.08)→ "recession";以及 scores 字典必须同时含四个相位键、evidence 非空(test_analyze_sector_rotation.py)。这些场景构造器位于 helpers.py,也可以直接拿来构造你自己的回归夹具。


8. 五步分析工作流

日文文档 docs/ja/skills/sector-analyst.md 把从脚本输出到最终报告的路径拆成五步。以下在保留原步骤内容的基础上,补齐脚本与知识库的对应关系。

步骤 1:CSV 数据收集

  1. 运行 python3 skills/sector-analyst/scripts/analyze_sector_rotation.py;
  2. 从输出中提取:
    • 按 uptrend ratio 的板块排名
    • 风险状态(cyclical vs defensive)与分数
    • 超买 / 超卖板块
    • 周期相位估计与置信度
  3. 如果出现数据新鲜度警告,必须在分析中注明。

这一步的产出是定量事实,后续三步只允许解释它,不允许覆盖它。

步骤 2:市场周期评估

以脚本的相位估计为起点:

  • 阅读 references/sector_rotation.md 获取周期与轮动框架;
  • 将定量结果与四个相位的预期模式逐一对照:Early Cycle Recovery、Mid Cycle Expansion、Late Cycle、Recession;
  • 加入知识库支撑的定性解释。

若提供了图表图片,则用于补充 industry 级别细节:

  • 从图中抽取行业层面表现数据;
  • 对比 1 周 vs 1 个月表现以确认趋势一致性;
  • 记录板块内部显著走强 / 走弱的特定行业。

仓库在 skills/sector-analyst/assets/ 下提供了三张示例图,用于说明该可选输入的期望格式:sector_performance.jpeg(板块层面 1 周与 1 个月表现)、industory_performance_1.jpeg(跑赢行业)、industory_performance_2.jpeg(跑输行业)。注意文件名中的 industory 是仓库中的实际拼写,引用时不要“纠正”。

示例板块表现图表,展示 1 周与 1 个月两个时间维度的板块相对强弱,可作为 Sector Analyst 的可选图表输入格式参考

步骤 3:现状分析

把观察整合为客观判断:

  • 指出当前表现最接近哪一个周期相位;
  • 强调支撑证据(哪些板块/行业印证该判断);
  • 记录矛盾信号或异常模式;
  • 基于信号一致性评估置信度。

表达上应使用数据驱动的语言和具体的表现数值,例如“Energy 46.8%、Technology 34.4%,而 Utilities 仅 2.7%”,而不是“能源很强”。

步骤 4:情景构建

基于轮动原则与当前定位,为下一阶段构建 2–4 个情景。每个情景必须包含五项:

  • 市场周期的转换描述;
  • 预期跑赢的板块;
  • 预期跑输的板块;
  • 可确认该情景的催化剂或条件;
  • 概率分配(参照 sector_rotation.md 的概率评估框架)。

情景应从概率最高的主情景延伸到替代性 / 逆向情景,不要只写一个方向。

步骤 5:报告生成

产出结构化的 Markdown 文档,六个必需章节见下一节。


9. 报告模板(完整可直接复用)

技能规定的报告文件名约定为 sector_analysis_YYYY-MM-DD.md(SKILL.md)。注意这与脚本 --save 自动生成的文件名 sector_rotation_YYYY-MM-DD.md 不同:前者是人工/模型产出的分析报告,后者是脚本的原始计算结果,两者应并存而非互相覆盖。

六个必需章节:

  1. Executive Summary — 2–3 句概括关键发现
  2. Current Situation — 当前表现模式与周期定位的详细分析
  3. Supporting Evidence — 支撑周期判断的具体板块与行业数据
  4. Scenario Analysis — 2–4 个情景,含说明与概率
  5. Recommended Positioning — 基于情景概率的战略与战术定位建议
  6. Key Risks — 需要监控的风险或矛盾信号

完整结构模板(SKILL.md):

# Sector Performance Analysis - [Date]

## Executive Summary

[2-3 sentences summarizing key findings]

## Current Situation

### Market Cycle Assessment
[Which cycle phase and why]

### Performance Patterns Observed

#### 1-Week Performance
[Analysis of recent performance]

#### 1-Month Performance
[Analysis of medium-term trends]

#### Sector-Level Analysis
[Detailed breakdown by sector]

#### Industry-Level Analysis
[Notable industry-specific observations]

## Supporting Evidence

### Confirming Signals
- [List data points supporting cycle assessment]

### Contradictory Signals
- [List any conflicting indicators]

## Scenario Analysis

### Scenario 1: [Name] (Probability: XX%)
**Description**: [What happens]
**Outperformers**: [Sectors/industries]
**Underperformers**: [Sectors/industries]
**Catalysts**: [What would confirm this scenario]

### Scenario 2: [Name] (Probability: XX%)
[Repeat structure]

[Additional scenarios as appropriate]

## Recommended Positioning

### Strategic Positioning (Medium-term)
[Sector allocation recommendations]

### Tactical Positioning (Short-term)
[Specific adjustments or opportunities]

## Key Risks and Monitoring Points

[What to watch that could invalidate the analysis]

---
*Analysis Date: [Date]*
*Data Period: [Timeframe of charts analyzed]*

1-Week / 1-Month 两小节的保留很重要:CSV 数据只提供当下快照,短中期对比只能来自图表图片;如果本次没有提供图片,应在小节内明确写“无图表输入,本节基于单一快照推断”,而不是留空或编造数值。


10. 概率指南与分析原则

概率区间在日文文档与知识库中是一致的(SKILL.md、sector_rotation.md):

概率区间 证据强度
70–85% 强证据:多个跨板块、跨时间框架的确认信号
50–70% 中等证据:有部分确认信号但指标混杂
30–50% 弱证据:信号有限或相互冲突
15–30% 推测性:与当前指标相反但仍有可能

一条硬约束:所有情景的概率之和应约等于 100%。如果四个情景分别给 60/50/40/30,这份概率分配本身就是自相矛盾的,应直接重写。

七条分析原则(SKILL.md):

  1. Objectivity First — 让数据引导结论,而不是先有观点再找数据;
  2. Probabilistic Thinking — 用概率区间表达不确定性;
  3. Multiple Timeframes — 对比 1 周与 1 个月数据确认趋势;
  4. Relative Performance — 关注相对强弱,而非绝对收益;
  5. Breadth Matters — 广泛性变动比孤立变动更有意义;
  6. No Absolutes — 市场很少严格照教科书演绎;
  7. Historical Context — 引用典型轮动规律,同时承认当下的独特性。

第 6 条在实际使用中尤其重要:estimate_cycle_phase() 的四相位模型是一个离散分类器,真实市场经常处在两相位之间的过渡带。当 early 与 mid 分数只差 5 分(confidence: low)时,正确表述是“处于 early→mid 的过渡区”,而不是硬选一个。

知识库 sector_rotation.md 还提供了 industry 层级的细化,例如 Technology 内部“软件/半导体/硬件偏 early-mid 领先,IT 服务/企业软件(经常性收入)偏防御”,Financials 内部“综合银行/投行偏 early,保险/资管偏 mid-late,区域银行/消费金融在衰退中脆弱”(sector_rotation.md)。这些是图表图片补充分析时的解释素材。


11. 验证与自测

技能自带 6 个测试类,覆盖解析、校验、打分、阶段估计与两种输出格式。运行方式(在技能脚本目录下):

cd skills/sector-analyst/scripts && python3 -m pytest tests -q

测试通过 conftest.py 把 scripts/ 与 tests/ 都插入 sys.path,因此 from analyze_sector_rotation import ... 和 from helpers import ... 都能直接工作,无需安装包或设置 PYTHONPATH。

网络调用全部被 mock:test_analyze_sector_rotation.py 用 @patch("analyze_sector_rotation.urllib.request.urlopen") 伪造响应,并通过给 mock 挂上 __enter__ / __exit__ 使 with urllib.request.urlopen(...) 可用。这意味着测试完全离线,适合放进 CI。若你要新增字段或修改阈值,建议先跑一遍这套测试,确认边界行为没有被破坏——尤其是 test_boundary_values 和 test_score_range_0_to_100 这两条最容易被“顺手优化”推翻的断言。

此外,仓库把该数据源纳入了 provider contract 校验体系,相关约定见 docs/dev/provider-contracts.md——该文档把 uptrend-sector-summary 标注为 sector-analyst 等多个技能的共享数据源。如果上游 CSV 结构变化,问题会首先在契约层暴露,而不是等到分析结果异常才被发现。


12. 在更大的工作流中如何使用

skills-index.yaml 把 Sector Analyst 归类为 category: market-regime、operational_role.type: workflow_step、timeframe: weekly、difficulty: intermediate,并声明其 inputs 为 sector_uptrend_csv 与 chart_image,output 为 rotation_assessment_report(见 skills-index.yaml)。

在估值引擎之外,它最常见的挂载点是多资产机会扫描工作流:workflows/multi-asset-opportunity-daily.yaml 把 sector-analyst 列为 optional_skills,与 market-news-analyst、market-environment-analysis、scenario-analyzer、stanley-druckenmiller-investment 并列;该工作流第 2 步“Detect hot themes + sector rotation”由 theme-detector 承担,Sector Analyst 作为可选的板块轮动补充视角介入(workflows/multi-asset-opportunity-daily.yaml)。同样的定位也出现在 docs/en/workflows.md 与 docs/en/skillsets.md 的“Optional skills”列表中。

这意味着一个务实的组合方式:先用必需技能确定宏观状态与主题,再用 Sector Analyst 检验“板块相对强弱是否支持这个主题”,最后用 scenario-analyzer 把相位判断展开成情景。它的输出(rotation_assessment_report)也可以被 edge-signal-aggregator 这类聚合器消费,相关引用见 docs/en/skills/edge-signal-aggregator.md 中对 reports/sector_analyst_*.json 的说明。

关于成熟度,需要给出一个诚实的提醒:在 skills-index.yaml 中,该技能的 verification 各项(instruction_contract、unit_tests、workflow_contract、end_to_end_replay、data_provenance、financial_logic_review、empirical_validation、security_review)目前均标记为 not_verified。这表示仓库尚未完成正式的验证归档,不代表脚本不可用;脚本本身有完整的单元测试,但“已在真实决策流程中端到端验证”这一层证据目前是缺失的。


13. 已知限制与使用清单

限制:

  • 在线依赖:两个 CSV 都通过 urllib 从 raw.githubusercontent.com 拉取,无网络即无数据。--url / --uptrend-url 是唯一的内网/镜像适配手段。
  • 快照语义:sector_summary.csv 是“每板块最新快照”,没有历史序列,脚本无法自行计算动量变化;跨期对比必须靠多次运行或图表图片。
  • 分组口径固定:11 个板块、三组划分硬编码在脚本常量中,不做行业标准映射,也不覆盖非美股板块(如日本 17 业种)。上游若新增板块,脚本不会自动纳入分组,只会出现在排名表中并在组平均里缺席。
  • 相位模型是启发式:上下半区在偶数/奇数板块数下的边界处理、0.4/0.3/0.3 权重、20/10 分的置信度门槛都是工程化的近似,不是统计拟合的结果。它给出的是“最像哪个相位”,不是概率意义上的分类。
  • 口径差异:脚本把 Communication Services 归为 cyclical,而 sector_rotation.md 将其列在 defensive 之下;报告解释时应说明采用哪一口径。

每次分析前的快速清单:

  • [ ] 是否已记录 Data as of 或 WARNING 的具体日期?
  • [ ] 输出的板块数是否为 11?若少于 11,是否出现 INCOMPLETE DATA?
  • [ ] Difference 的符号与 magnitude 是否与 regime 标签一致?
  • [ ] late_cycle_flag / divergence_flag 是否被写入“矛盾信号”章节?
  • [ ] 相位 confidence 是 high / moderate / low?low 时是否改用了过渡区表述?
  • [ ] 情景概率之和是否约等于 100%?
  • [ ] 报告文件名是否为 sector_analysis_YYYY-MM-DD.md,且与脚本产出的 sector_rotation_YYYY-MM-DD.md 分别存放?

14. 小结

Sector Analyst 的价值不在“预测”,而在把一次板块轮动判断拆成可复核的三段:可复现的 CSV 输入、可解释的打分链路(difference → piecewise score → 惩罚项 → regime)、可约束的输出模板(六章 + 概率区间)。掌握了 analyze_sector_rotation.py 中 _difference_to_score、estimate_cycle_phase 与 _analyze_group 这三处实现,你就能判断任何一份输出中哪些结论来自数据、哪些来自启发式,从而在写报告时既不夸大也不漏报。配合 sector_rotation.md 提供的相位与行业级知识,这个零依赖脚本足以支撑一套每周可重复执行的板块轮动复盘流程。

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