Sector Analyst 技能实战:在 claude-trading-skills 中构建板块轮动与市场周期定位分析

原创2026-11-15 13:08:541,922 阅读
文章标签:金融科技AI 技能人工智能数据分析

Sector Analyst 技能实战:在 claude-trading-skills 中构建板块轮动与市场周期定位分析

本文以 skills/sector-analyst/SKILL.md 为主线,系统拆解 claude-trading-skills 仓库中 sector-analyst 技能的完整用法:如何仅凭标准库 Python 拉取公开 CSV、生成板块强度排名、周期性/防御性风险偏好评分、超买超卖标记与市场周期相位估计,并进一步结合源码与测试,说明每个阈值、惩罚项和置信度分档背后的实现逻辑。读完你可以独立运行脚本、读懂它输出的每一个字段,并按标准化模板产出一份可被其他技能消费的板块轮动报告。

一、技能定位:为什么板块轮动值得单独成一个技能

sector-analyst 的定位非常明确:把"板块轮动"这一主观性极强的判断,压缩成一组可复现的量化中间结果。SKILL.md 的 Overview 段落给出了它的能力边界——获取板块上升趋势比率(uptrend ratio)数据、给板块排序、计算周期性 vs 防御性风险状况评分、识别超买/超卖、估计市场周期相位;图表图片只作为可选补充,用于提供行业(industry)级别的细节。

这一点在数据结构上有硬证据支撑。在 skills-index.yaml 中,该技能被归类为 category: market-regime、timeframe: weekly、difficulty: intermediate,输入声明为 sector_uptrend_csv 与 chart_image,输出为 rotation_assessment_report。也就是说,CSV 是主输入,图片是次输入。

需要留意一个在仓库中可核验的事实:该条目下的 verification 段全部为 not_verified(instruction_contract、unit_tests、workflow_contract、data_provenance 等均未标注已验证)。这并不代表代码不可用——scripts/tests/ 下确实存在 495 行的单元测试——而是说明该技能尚未走完仓库定义的完整验证流水线。引用其结论时,建议保留这一前提。

二、适用场景与触发方式

SKILL.md 列出了六类触发条件,它们覆盖了从"纯数据驱动"到"图文结合"的完整光谱:

触发场景 是否需要图片 典型用户请求
板块轮动分析 否 "Run a sector rotation analysis"
周期性 vs 防御性定位 否 "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…"
板块维度的情景推演 可选 "…tell me where we are in the market cycle"

前四类只需运行脚本即可得到全部数字依据;第五类才需要读取图片资产。这个设计对 Agent 很重要——它意味着在没有图像能力、或者用户只贴了一段文字提问的环境下,技能仍然能完整工作。

一个容易忽略的约束写在 SKILL.md 的 Important Notes 里:分析思考过程与最终 Markdown 输出都必须使用英文。这与仓库其他技能的语言约定一致,也解释了为什么脚本 format_human() 里的所有标题都是硬编码英文(## Risk Regime、## Cycle Phase Estimate、## Sector Ranking (by uptrend ratio))。

三、环境前提:Python 3.9+ 与零第三方依赖

SKILL.md 的 Prerequisites 只有两条:Python 3.9+、无第三方库、无需 API Key。

这背后是刻意的工程选择:

# skills/sector-analyst/requirements.txt 的全部内容
# stdlib-only: packaged scripts use the Python standard library only.

requirements.txt 没有任何包名,只有一行注释。脚本的 docstring 也明确声明依赖为 urllib, csv, json, argparse, dataclasses。为了在 Python 3.9 上使用 float | None 这类 3.10+ 的联合类型语法,文件顶部加了一行 from __future__ import annotations:

from __future__ import annotations   # analyze_sector_rotation.py:16

这是整个技能可移植性的关键:只要目标机器有 Python 3.9,不需要 pip install、不需要网络代理以外的任何配置,就能跑通。对于打包成 .skill 文件分发(仓库中存在 skill-packages/sector-analyst.skill)尤其重要。

四、数据源:两张 CSV 的分工

4.1 端点与用途

SKILL.md 的 Data Source 段落说明数据来自 TraderMonty 的公开 GitHub 仓库:

  • Sector Summary:sector_summary.csv —— 每个板块的上升趋势比率、趋势方向、斜率与状态
  • Freshness Check:uptrend_ratio_timeseries.csv —— 用 max(date) 验证数据新鲜度

对应的常量定义在源码顶部:

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"
)

4.2 列契约与两级校验

sector_summary.csv 期望的列被拆成两个集合:

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

validate_columns() 对二者采取不同策略:

  • 缺少 Sector 或 Ratio → 抛 ValueError,main() 捕获后打印 ERROR: 并 SystemExit(1)
  • 缺少 10MA/Trend/Slope/Status → 仅在 stderr 打印 WARNING: Missing optional columns: [...],继续执行

这种"硬校验两列、软提示其余"的设计,与 docs/plans/issue-332-public-csv-contracts.md 中记录的提供方契约演进思路一致:sector summary 的 required_fields 明确覆盖 Sector、Ratio、10MA、Trend、Slope、Status,而下游读取方式基于列名映射。当上游改名时,Ratio 缺失会立刻炸出来,而 Status 缺失不会阻断主流程——因为主流程并不依赖它做计算,只用于表格展示。

10MA 这一列名有个历史包袱:测试专门为此写了一行断言(test_ma_10_parsed_from_10MA_column),因为列名不能以数字开头作为合法标识符,代码里只能通过 row.get("10MA", "") 字符串取值,字段名则映射为 ma_10:

ma_10 = _safe_float(row.get("10MA", ""))
slope = _safe_float(row.get("Slope", ""))

4.3 行级容错

parse_sector_rows() 对每一行做三重过滤,任何一步失败就 continue 跳过该行而不是整体报错:

  1. Sector 去空白后为空 → 跳过
  2. Ratio 去空白后为空 → 跳过
  3. Ratio 无法 float() 转换(例如 N/A)→ 跳过

10MA、Slope 走 _safe_float(),解析失败返回 None,不跳过整行;Trend、Status 缺失则为空字符串。这与测试用例 test_missing_optional_fields_use_defaults 完全对应——只有 {"Sector": "Technology", "Ratio": "0.30"} 两列也能构造出合法的 SectorData。

4.4 新鲜度检查的"非致命"设计

check_freshness() 与主数据抓取在异常处理上刻意不同:

  • 主数据抓取失败 → fetch_csv() 打 ERROR: 并 SystemExit(1)
  • 新鲜度抓取失败 → 捕获 (urllib.error.URLError, OSError) 后静默返回 None,不打日志

main() 里对应的处理是打印 WARNING: Could not check data freshness (continuing)。测试 test_no_error_log_on_fetch_failure 明确断言 stderr 中不得出现 ERROR 字样。逻辑上很合理:新鲜度只是元信息,拿不到就退化为"不做时效提示",不应因此中断整份分析。

判定规则是 FRESHNESS_MAX_DAYS = 5:

days_old = (date.today() - max_date).days
is_fresh = days_old <= FRESHNESS_MAX_DAYS
warning = None if is_fresh else f"Data is {days_old} days old (latest: {max_date_str})"

max(dates) 对字符串取最大值,因此要求日期是 YYYY-MM-DD 格式(后续用 datetime.strptime(..., "%Y-%m-%d") 二次校验,解析失败同样返回 None)。测试 test_order_independent 专门验证了行乱序时仍能取到最新日期。

五、运行脚本:三种输出形态

SKILL.md 给出的是最常用的三条命令:

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

# JSON 输出
python3 scripts/analyze_sector_rotation.py --json

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

在仓库根目录下执行时,路径需按实际位置展开:

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

5.1 完整 CLI 参数表

源码 main() 定义了 6 个参数,比 SKILL.md 展示的更多:

参数 类型 默认值 作用
--json flag False 输出 JSON 而非 Markdown/文本
--output-dir str reports/ --save 时的目标目录,自动 makedirs(exist_ok=True)
--save flag False 将输出写入文件
--url str SECTOR_CSV_URL 自定义板块汇总 CSV 地址
--uptrend-url str UPTREND_CSV_URL 自定义时间序列 CSV 地址(新鲜度用)
--timeout int 30 HTTP 超时秒数,同时作用于两个请求

--url / --uptrend-url 是本地离线调试的入口:可以指向 file:// 或本地 HTTP 服务,用于在没有外网的环境中复现某一天的数据状态。这也是仓库其他 CSV 消费类技能(如 uptrend-analyzer、theme-detector)共用的测试策略。

5.2 落盘文件命名的一个实际差异

SKILL.md 的 Output Format 段建议交付文件命名为 sector_analysis_YYYY-MM-DD.md;而脚本 --save 的实际实现是:

ext = ".json" if args.json else ".md"
filename = f"sector_rotation_{date.today().isoformat()}{ext}"

即 sector_rotation_2026-11-15.md / .json。两者并不一致。实践中建议:脚本产物按 sector_rotation_* 命名(便于区分机器输出),而 Agent 在 Step 5 手工撰写的最终报告按 SKILL.md 的 sector_analysis_* 命名(区分人工解读后的成品)。同时注意下游 exposure-coach 期望的输入 pattern 是 sector_*.json,两种前缀都能匹配。

5.3 stdout / stderr 的分工

脚本把所有进度信息都打到 stderr,把最终结果打到 stdout:

print("Checking data freshness...", file=sys.stderr)
...
print(f"Parsed {len(sectors)} sectors", file=sys.stderr)
print(output)              # stdout
...
print(f"Saved to {filepath}", file=sys.stderr)

这让 python3 ... --json | jq . 之类的管道操作不会因为进度日志而解析失败——一个很小但很实用的约定。

六、量化内核:五个分析函数的实现细节

这是 SKILL.md 只描述"输出什么"、而没有展开"怎么算"的部分,也是本文补充源码证据的重点。

6.1 板块分类:三组而非两组

SKILL.md 只提到"周期性与防御性",但源码实际维护了三组:

CYCLICAL_SECTORS = ["Technology", "Consumer Cyclical", "Communication Services",
                    "Financial", "Industrials"]          # 5 个
DEFENSIVE_SECTORS = ["Utilities", "Consumer Defensive", "Healthcare",
                     "Real Estate"]                      # 4 个
COMMODITY_SECTORS = ["Energy", "Basic Materials"]         # 2 个

合计 11 个板块,与测试工厂 helpers.py 中的 ALL_SECTORS 完全一致,test_full_set_parses_all_11 也钉住了这个数量。

注释里明确写了这套分类"与 uptrend-analyzer 的 sector_rotation_calculator.py (L31-47) 对齐"。在 skills/uptrend-analyzer/scripts/calculators/sector_rotation_calculator.py 中可以确认三个列表逐字相同。这种对齐是刻意的一致性保证:两个技能对同一份 CSV 算出的风险评分不会因为分类差异而互相矛盾。

一个值得注意的语义分歧:参考知识库 skills/sector-analyst/references/sector_rotation.md 把 Materials 列为周期性、把 Communication Services 列为防御性;而代码把 Basic Materials 划入商品组、Communication Services 划入周期性组。这不是 bug,而是两套不同粒度的模型——知识库描述的是教科书式的周期轮动叙事,代码实现的是可量化打分的近似分组。阅读输出时应以代码分组为准来解释 score,以知识库为参考来解释"为什么这些板块会轮动"。

6.2 风险偏好评分:差值 → 分数 → 状态标签

analyze_groups() 的核心是三步:

第一步,算周期性均值与防御性均值的差:

difference = cyclical_avg - defensive_avg
base_score = _difference_to_score(difference)

第二步,_difference_to_score() 做分段线性映射,注意所有区间均为左开右闭、且段间连续:

difference 区间 分数区间 含义
> 0.15 90 → 100 周期性大幅领先
0.05 ~ 0.15 70 → 89 健康的周期性领先
-0.05 ~ 0.05 45 → 69 均衡
-0.15 ~ -0.05 20 → 44 防御性倾斜
< -0.15 0 → 19 防御性大幅领先

例如 diff = -0.25 落在最后一段:19 + (-0.25 + 0.15)/0.10 * 19 = 19 - 19 = 0,被 max(0, ...) 兜住。测试 test_score_range_0_to_100 用 ratio 从 0.01 到 0.45 的五组数据遍历,断言分数恒在 [0, 100]。

第三步,_score_to_regime() 把数字翻译成人类可读标签:

分数 regime
>= 90 strong risk-on
>= 70 risk-on
>= 45 balanced
>= 20 defensive tilt
< 20 strong risk-off

6.3 两个负向调整项

基础分之上还有两个惩罚,这是 SKILL.md 完全没有提及但会显著影响结论的机制。

商品板块惩罚(late-cycle 信号):当商品组均值同时高于周期性与防御性均值时,置 late_cycle_flag = True,并按领先幅度扣分:

if commodity_avg > cyclical_avg and commodity_avg > defensive_avg:
    late_cycle_flag = True
    excess = commodity_avg - max(cyclical_avg, defensive_avg)
    commodity_penalty = -10 if excess > 0.10 else -5

含义是:能源与基础材料同时强于两组,历史上更接近周期后段(通胀交易),因此压低"进攻性"评分。测试 test_late_cycle_flag 用 make_late_cycle_scenario()(Energy/Basic Materials 设 0.40,其余 0.20/0.10)验证该标志被置位。

组内分化惩罚:_calculate_group_divergence() 分别检查周期性组与防御性组内部的离散度,任一被"标记"就扣 5 分。标记条件在 _analyze_group():

flagged = std_dev > 0.08 or spread > 0.20 or len(trend_dissenters) > 0

三个判据分别是:组内标准差超过 0.08、极差超过 0.20、或存在趋势方向的"异见者"(多数为 up 而某板块为 down,或反之)。这意味着组均值的代表性不足时会主动降分——如果 Technology 冲到 0.45 而 Industrials 掉到 0.05,虽然组均值可能还行,但结论可信度应打折。test_divergence_flag_high_spread 正是这个场景。

最终合成一行:

score = round(min(100, max(0, base_score + commodity_penalty + divergence_penalty)))

有一个边界行为值得说明:如果周期性或防御性组完全缺数据(cyclical_avg is None or defensive_avg is None),函数直接返回 score: 50、regime: "incomplete data",不做任何推断。这是一个保守的中性降级,避免在数据不完整时给出方向性结论。

6.4 超买超卖:两个绝对阈值

identify_overbought_oversold() 使用固定阈值:

OVERBOUGHT_THRESHOLD = 0.37
OVERSOLD_THRESHOLD = 0.097

判定使用严格不等号:ratio > 0.37 为超买,ratio < 0.097 为超卖。test_boundary_values 明确断言恰好等于 0.37 或 0.097 都不触发标记。在 Markdown 输出中,这两个阈值被格式化为 ratio > 37% 与 ratio < 9.7%。

采用绝对阈值而非分位数,是为了跨日期可比:同一板块在不同日期的 ratio 可以直接和历史阈值对照,而分位数会让"超买"的标准随市场整体水平漂移。代价是这些阈值来自经验设定,仓库中未附带回测依据。

6.5 周期相位估计:三因子加权投票

estimate_cycle_phase() 是本技能最具"模型"色彩的部分。它对四个相位(early、mid、late、recession)分别打分,每个相位都定义了预期领先板块与滞后板块:

CYCLE_PHASES = {
    "early":     {"leaders": ["Technology", "Consumer Cyclical", "Industrials", "Financial"],
                  "laggards": ["Utilities", "Consumer Defensive", "Healthcare"]},
    "mid":       {"leaders": ["Technology", "Industrials", "Consumer Cyclical", "Energy"],
                  "laggards": ["Utilities", "Consumer Defensive"]},
    "late":      {"leaders": ["Energy", "Basic Materials", "Healthcare"],
                  "laggards": ["Technology", "Consumer Cyclical", "Industrials"]},
    "recession": {"leaders": ["Utilities", "Consumer Defensive", "Healthcare"],
                  "laggards": ["Technology", "Consumer Cyclical", "Industrials", "Financial"]},
}

打分流程:

  1. 按 ratio 降序排序,取 sorted[: n // 2 + 1] 为上半区、sorted[n // 2:] 为下半区。11 个板块时两者各有 6 个元素,在索引 5 处重叠——这是刻意的宽松处理,允许中位数附近的板块同时被视为"靠前"和"靠后"。
  2. Leader 命中率(权重 0.4):预期领先板块中有多少落在上半区。
  3. Laggard 命中率(权重 0.3):预期滞后板块中有多少落在下半区。
  4. 趋势一致性(权重 0.3):预期领先板块的 trend == "up"、预期滞后板块的 trend == "down" 的比例,合并计算。
  5. total = leader_score * 0.4 + laggard_score * 0.3 + trend_score * 0.3,放大 100 后保留一位小数。

置信度不看绝对分数,而看第一名与第二名的分差:

gap = best_score - second_score
if gap > 20:    confidence = "high"
elif gap > 10:  confidence = "moderate"
else:           confidence = "low"

这是一个务实的设计:如果 early 得 75 分但 mid 也得 70 分,说明数据本身就处在两个相位之间,硬给高置信度反而是误导。测试 test_confidence_high_when_clear 对早期周期场景只断言 in ("high", "moderate"),可见作者对"完全清晰"也保持克制。

最后函数还会生成人类可读的 evidence 列表,形如 Leaders in top ranks: Technology, Industrials,直接进入 Markdown 输出的 Evidence: 区块。

6.6 趋势汇总

analyze_trends() 最简单,只统计 trend.lower() == "up" / "down" 的板块数量与名单。注意它只统计这两个值,如果上游出现 flat 或空字符串,该板块既不计入上升也不计入下降——因此 uptrend_count + downtrend_count 未必等于 11。

七、五步分析工作流:从数字到判断

SKILL.md 的 Analysis Workflow 是整个技能的灵魂,它把脚本输出与人类判断衔接起来。

Step 1:CSV 数据采集

运行脚本后,需要从输出中提取四项内容:板块排名、风险状况与分数、超买/超卖板块、周期相位与置信度。若出现数据新鲜度警告,必须在分析中标注。这一点在 format_human() 中有对应的渲染逻辑:

if freshness.get("warning"):
    lines.append(f"> **WARNING**: {freshness['warning']}")
else:
    lines.append(f"> Data as of: {freshness['date']}")

警告以引用块形式出现在报告顶部,视觉上不可能被忽略。

Step 2:市场周期评估

以脚本的相位估计为起点而非终点。需要打开 skills/sector-analyst/references/sector_rotation.md,把量化结果与四个相位的教科书特征逐一对照:

相位 关键经济特征 预期领先 预期落后
Early Cycle Recovery GDP 由负转正、利率低位、信贷转松 Technology、Consumer Cyclical、Industrials、Financial、Real Estate Utilities、Consumer Defensive、Healthcare
Mid Cycle Expansion GDP 强劲、就业加速、利率自低位上行 Technology、Industrials、Consumer Discretionary、Materials、Energy Utilities、Consumer Staples、Telecom
Late Cycle GDP 减速但仍正、通胀压力累积、信贷收紧 Energy、Materials、Financials、Healthcare、Consumer Staples Technology、Consumer Discretionary、Real Estate、Industrials
Recession GDP 收缩、失业上升、央行降息 Utilities、Consumer Staples、Healthcare、Communication Services Financials、Consumer Discretionary、Industrials、Materials、Energy、Real Estate

如果用户提供了图表,此时再用它补充行业级细节:从图中读取行业表现、比较 1 周与 1 个月的一致性、标注板块内部的强弱分化。

图片输入的期望格式可以参考仓库自带样例。下图是 skills/sector-analyst/assets/sector_performance.jpeg,展示 11 个板块的 1 周与 1 个月横向柱状对比,绿色为正收益、红色为负收益:

板块 1 周与 1 个月表现对比示例图,11 个板块的横向柱状图,用于 sector-analyst 的可选图像补充分析

从这张样例图本身就能演示 Step 2 的核心手法——跨时间框架一致性检验:Technology 在 1 周(+2.21)与 1 个月(+4)都居首,属于强一致;Consumer Cyclical 在 1 周排第二(+1.52)但 1 个月仅 +0.24,属于短期脉冲而非趋势;Utilities 在 1 周为 -2.16 却在 1 个月为 +1.97,属于中期改善但短期回调。这种"1 周 vs 1 个月"的分歧,正是 SKILL.md 要求"Compare 1-week vs 1-month performance for trend consistency"的原因。另外两张样例 skills/sector-analyst/assets/industory_performance_1.jpeg 与 skills/sector-analyst/assets/industory_performance_2.jpeg 分别演示行业级强势与弱势榜单,用于 Step 2 的行业细分环节。

Step 3:现状分析

把观察综合成客观判断:当前表现最像哪个相位、有哪些板块/行业支持这个看法、有哪些矛盾信号、信号一致性如何。SKILL.md 强调使用"数据驱动的语言并引用具体表现数字"——避免"市场似乎正在轮动"这类无锚定表述,改用"周期性均值领先防御性 12.4 个百分点、评分 82 对应 risk-on"。

Step 4:情景推演

基于轮动原理与当前定位,展开 2~4 个下一阶段的可能情景。每个情景必须包含五个要素:

  1. 描述的周期转换(例如"从 mid 向 late 过渡")
  2. 可能跑赢的板块
  3. 可能跑输的板块
  4. 确认该情景的催化剂或条件
  5. 概率赋值(依据下一节的分档)

情景需按概率从高到低排列,最后一个是"替代/逆向"情景。

Step 5:输出生成

六个必需章节(Executive Summary、Current Situation、Supporting Evidence、Scenario Analysis、Recommended Positioning、Key Risks)以及下面给出的模板。

八、标准化输出模板

SKILL.md 提供了一个可直接套用的 Markdown 骨架,建议原样保留章节层级,因为下游读取与人工复核都依赖这个结构:

# 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]*

其中 Supporting Evidence 拆成 Confirming / Contradictory 两栏是这份模板最有价值的约束——它强制作者主动寻找反证,而不是单向堆砌支持自己结论的证据。

九、机器可读输出:JSON 结构

当需要把结果交给其他技能时,--json 才是正确的选择。format_json() 产出的结构为:

{
  "meta": {
    "generated_at": "2026-11-15T07:34:07",
    "date": "2026-11-15",
    "freshness": {"date": "2026-11-14", "is_fresh": true, "warning": null}
  },
  "groups": {
    "cyclical_avg": 0.2812, "cyclical_avg_pct": 28.1,
    "defensive_avg": 0.1543, "defensive_avg_pct": 15.4,
    "commodity_avg": 0.22, "commodity_avg_pct": 22.0,
    "difference": 0.1269, "difference_pct": 12.7,
    "score": 84, "regime": "risk-on",
    "late_cycle_flag": false, "commodity_penalty": 0,
    "divergence_flag": false, "divergence_penalty": 0
  },
  "cycle_phase": {
    "phase": "early", "confidence": "moderate",
    "scores": {"early": 78.5, "mid": 62.0, "late": 31.5, "recession": 18.0},
    "evidence": ["Leaders in top ranks: Technology, Industrials, Financial"]
  },
  "ranking": [
    {"rank": 1, "sector": "Technology", "ratio": 0.3512, "ratio_pct": 35.1,
     "trend": "Up", "slope": 0.008, "status": "Above MA"}
  ],
  "overbought": [],
  "oversold": [],
  "trends": {"uptrend_count": 7, "downtrend_count": 4,
             "uptrend_sectors": ["..."], "downtrend_sectors": ["..."]}
}

注意几个细节:

  • groups 里同时保留了原始小数(cyclical_avg)与百分比(cyclical_avg_pct),前者用于二次计算、后者用于展示
  • ranking 保留了 ratio(0.3512)与 ratio_pct(35.1)双份,rank 从 1 开始
  • overbought / oversold 是对象数组而非字符串数组,含 sector、ratio、ratio_pct
  • cycle_phase.scores 保留全部四个相位分数,而不只是最优相位——这让下游可以自行判断"接近程度"
  • meta.freshness 为 null 时表示新鲜度检查失败,与"数据是新鲜的"是两种不同状态

ensure_ascii=False 保证非 ASCII 内容不被转义;indent=2 保证可读性。测试 test_valid_json 与 test_json_has_meta_section 分别钉住了顶层键与 meta.generated_at 的存在。

十、与其他技能的集成路径

sector-analyst 不是孤立工具,它在仓库中有明确的上游/下游关系。

10.1 与 uptrend-analyzer 的一致性

两者读取同一份 CSV、使用同一套板块分组与评分公式。差别在于 uptrend-analyzer 的 sector_rotation_calculator.py 输出的是 signal 字符串(如 INCOMPLETE DATA: Cannot calculate rotation (neutral default)),而 sector-analyst 输出 regime 标签并额外加上排序、超买超卖与周期相位估计。可以把 sector-analyst 理解为"uptrend-analyzer 板块模块 + 周期相位推理 + 报告生成器"的超集。

10.2 作为 exposure-coach 的输入

skills/exposure-coach/SKILL.md 的输入表中明确列出 sector-analyst | sector_*.json | Sector performance rankings,并给出调用示例:

python3 skills/exposure-coach/scripts/calculate_exposure.py \
  --sector reports/sector_latest.json \
  ...

在 skills/exposure-coach/scripts/calculate_exposure.py 中,sector 维度的权重是 0.05(与 theme、ftd 同级)。extract_sector_score() 的读取逻辑是:优先直接取 sector_score 字段;否则在同时存在 dispersion 与 leadership 时按规则映射。这意味着 sector-analyst 的 JSON 并没有 sector_score 字段——若要让它直接喂给 exposure-coach,需要在中间层做一次映射,或者由 Agent 在报告中显式给出 sector_score。这是一个集成层面的真实缺口,值得在使用时注意。

10.3 技能包与工作流中的位置

十一、七条分析原则与概率分档

SKILL.md 的 Key Analysis Principles 不是装饰性条款,每一条都能对上具体实现:

原则 对应的工程约束
Objectivity First 脚本只输出数字与标签,判断权留给 Agent 的 Step 3
Probabilistic Thinking 情景必须给概率区间,而非单一结论
Multiple Timeframes 输出模板强制拆出 1-Week 与 1-Month 两个子节
Relative Performance 全部指标基于 uptrend ratio 与组间差值,而非绝对收益率
Breadth Matters 组内分化(std_dev/spread/趋势异见)会触发扣分
No Absolutes 置信度看分差而非绝对分,low 是合法结论
Historical Context 相位定义来自 sector_rotation.md 的框架,但允许"不完全吻合"

概率分档(Probability Guidelines)与知识库中的 Probability Assessment Framework 完全对齐:

概率区间 证据强度 判定标准
70–85% 强证据 多个板块与多个时间框架的确认信号
50–70% 中等证据 有部分确认信号但指标混合
30–50% 弱证据 信号有限或相互冲突
15–30% 投机性 与当前指标相反但并非不可能

所有情景概率之和应约等于 100%。知识库额外给出了四个校准维度:轮动信号一致性、表现模式的广度、与宏观经济指标的对齐度、历史先例的强度。

十二、测试与验证现状

虽然 skills-index.yaml 将该技能的验证状态标为全 not_verified,但代码层面已有相当完整的单元测试,可作为理解行为的活文档。

测试组织在 skills/sector-analyst/scripts/tests/ 下,conftest.py 通过向 sys.path 插入 scripts/ 与 tests/ 目录,使测试可以直接 from analyze_sector_rotation import ...,无需安装包:

sys.path.insert(0, str(_scripts_dir))
sys.path.insert(0, str(_tests_dir))

测试类与覆盖点:

测试类 覆盖内容
TestParseSectorRows 正常解析、10MA 列名、11 板块全集、空/非数值/缺 Sector 的跳过、可选字段默认值
TestValidateColumns 必需列缺失抛错、可选列缺失仅告警、空输入不报错
TestRankSectors 降序排名、ratio_pct 换算、空输入
TestAnalyzeGroups 均衡/risk-on/risk-off 三场景、商品均值、late-cycle 标志、分数边界、分化标志
TestOverboughtOversold 超买、超卖、正常区间、阈值边界不触发
TestAnalyzeTrends 全上升、混合趋势计数
TestEstimateCyclePhase early/late/recession 三场景识别、置信度、四相位分数齐全、evidence 非空
TestFormatHuman 必需章节存在、新鲜度警告渲染
TestFormatJson JSON 可解析、含 meta.generated_at
TestFetchCsv mock urlopen 的成功/失败/空响应
TestCheckFreshness 新鲜/过期/失败返回 None/失败不打 ERROR/乱序取最大日期/空时间序列

helpers.py 提供了三个场景工厂,实际上就是三类典型市场的"标准答案":

  • make_early_cycle_scenario():周期性 5 板块 0.35 且 Up,其余 0.10 且 Down
  • make_late_cycle_scenario():Energy/Basic Materials 0.40,Technology/Consumer Cyclical 0.10,其余 0.20
  • make_recession_scenario():Utilities/Healthcare/Consumer Defensive 0.40,其余 0.08

这三个工厂配合 estimate_cycle_phase() 的断言,构成了相位识别逻辑的回归基线。如果你要改动 CYCLE_PHASES 的定义,直接跑这套测试就能知道是否破坏了原有判别能力。

运行方式(在技能目录内):

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

更完整的仓库级测试入口见 scripts/run_all_tests.sh 与 CI 测试矩阵 scripts/ci_test_matrix.py。

十三、实操中的故障排查清单

把 SKILL.md 的 Important Notes 与源码的异常分支合并起来,可得到一份排错对照表:

现象 根因 依据
stderr 出现 ERROR: Failed to fetch ... 且退出码 1 网络不可达或 URL 失效 fetch_csv() 捕获 URLError 后 SystemExit(1)
stderr 出现 ERROR: Missing required columns: ['Ratio'] 上游 CSV schema 变更 validate_columns() 抛 ValueError
stderr 出现 ERROR: No valid sector data found 所有行都被过滤(空 Sector / 空 Ratio / 非数值 Ratio) main() 中 if not sectors
只看到 WARNING: Could not check data freshness (continuing) 时间序列 CSV 抓取失败,但不影响主分析 check_freshness() 返回 None
报告顶部出现 > **WARNING**: Data is N days old 数据超过 5 天未更新 FRESHNESS_MAX_DAYS = 5
regime 为 incomplete data,score 为 50 周期性或防御性组完全缺数据 analyze_groups() 的提前返回分支
相位置信度恒为 low 两个相位分数接近(gap ≤ 10) estimate_cycle_phase() 分档
排名表里 Trend 为空 CSV 缺 Trend 列或该行该字段为空 parse_sector_rows() 用 "" 兜底

另外两条来自 SKILL.md 的注意事项值得反复强调:每次分析都应查阅 sector_rotation.md 知识库(否则相位判断会退化为纯数字匹配,失去对"为何轮动"的解释力);新数据到来时应更新概率评估(概率是对当前证据的表达,不是一次性结论)。

十四、小结

sector-analyst 的价值在于把板块轮动这一高度依赖主观判断的领域,拆成了一段可复现的流水线:两张公开 CSV → 11 个板块的比率 → 三组均值差分 → 分段线性评分 → 两个惩罚项修正 → 四个相位的加权投票 → 结构化的 Markdown 或 JSON。SKILL.md 定义了这条流水线的接口与输出标准,而 analyze_sector_rotation.py 给出了每个阈值的具体实现。

实际使用时的三条经验:其一,把脚本输出当作证据集合而非结论,Step 3 的综合判断不可省略;其二,注意 score 会因商品板块领先和组内分化而被主动下调,这是设计意图而非计算噪声;其三,需要喂给 exposure-coach 等下游技能时,留意 sector_score 字段的映射缺口,必要时在中间层补齐。延伸阅读可从 skills/sector-analyst/references/sector_rotation.md 的周期框架与行业级细分入手,配合 skills/uptrend-analyzer/SKILL.md 对照同一份数据的另一种呈现方式。

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