Sector Analyst 技能详解:基于公开 CSV 的板块轮动与市场周期定位分析(claude-trading-skills)
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 的描述,它的能力可以归纳为四件事:
- 按 uptrend ratio 对板块做降序排名;
- 计算 cyclical(周期)与 defensive(防御)两组的风险状态分(risk regime score);
- 标记 ratio 超过或跌落阈值的超买 / 超卖板块;
- 估计当前处于市场周期的哪个相位,并给出置信度。
图表图片是可选输入,仅用于在板块之下补充 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):
- 分别求 cyclical_avg、defensive_avg、commodity_avg;某个板块在本期 CSV 中缺失则不计入该组平均。
difference = cyclical_avg - defensive_avg,经_difference_to_score()映射到 0–100 的基础分。- 若 commodity_avg 同时高于 cyclical_avg 与 defensive_avg,置
late_cycle_flag = True,并按超出幅度罚分:超出> 0.10罚-10,否则罚-5。 - 若组内出现离散(
divergence_flag),再罚-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 |
计算步骤:
- 按 ratio 降序后切成上下半区:
top_half = 前 n//2 + 1 个,bottom_half = 从 n//2 开始。11 个板块时两者在中间位置有重叠(第 6 名同时属于两个集合),这是刻意的宽松处理,避免中位板块被硬性归边。 - 三项子分数:
leader_score = 命中的期望 leaders 数 / leaders 总数,权重 0.4;laggard_score = 落在下半区的期望 laggards 数 / laggards 总数,权重 0.3;trend_score = (leaders 中 trend=up 的数量 + laggards 中 trend=down 的数量) / 有数据的总数,权重 0.3。
- 总分
= (0.4*leader + 0.3*laggard + 0.3*trend) * 100,四舍五入到一位小数。 - 取最高分相位为结果;与第二名分差
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 数据收集
- 运行
python3 skills/sector-analyst/scripts/analyze_sector_rotation.py; - 从输出中提取:
- 按 uptrend ratio 的板块排名
- 风险状态(cyclical vs defensive)与分数
- 超买 / 超卖板块
- 周期相位估计与置信度
- 如果出现数据新鲜度警告,必须在分析中注明。
这一步的产出是定量事实,后续三步只允许解释它,不允许覆盖它。
步骤 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 是仓库中的实际拼写,引用时不要“纠正”。
步骤 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 不同:前者是人工/模型产出的分析报告,后者是脚本的原始计算结果,两者应并存而非互相覆盖。
六个必需章节:
- Executive Summary — 2–3 句概括关键发现
- Current Situation — 当前表现模式与周期定位的详细分析
- Supporting Evidence — 支撑周期判断的具体板块与行业数据
- Scenario Analysis — 2–4 个情景,含说明与概率
- Recommended Positioning — 基于情景概率的战略与战术定位建议
- 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):
- Objectivity First — 让数据引导结论,而不是先有观点再找数据;
- Probabilistic Thinking — 用概率区间表达不确定性;
- Multiple Timeframes — 对比 1 周与 1 个月数据确认趋势;
- Relative Performance — 关注相对强弱,而非绝对收益;
- Breadth Matters — 广泛性变动比孤立变动更有意义;
- No Absolutes — 市场很少严格照教科书演绎;
- 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 提供的相位与行业级知识,这个零依赖脚本足以支撑一套每周可重复执行的板块轮动复盘流程。
