Sector Analyst 技能实战:在 claude-trading-skills 中构建板块轮动与市场周期定位分析
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 跳过该行而不是整体报错:
Sector去空白后为空 → 跳过Ratio去空白后为空 → 跳过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"]},
}
打分流程:
- 按
ratio降序排序,取sorted[: n // 2 + 1]为上半区、sorted[n // 2:]为下半区。11 个板块时两者各有 6 个元素,在索引 5 处重叠——这是刻意的宽松处理,允许中位数附近的板块同时被视为"靠前"和"靠后"。 - Leader 命中率(权重 0.4):预期领先板块中有多少落在上半区。
- Laggard 命中率(权重 0.3):预期滞后板块中有多少落在下半区。
- 趋势一致性(权重 0.3):预期领先板块的
trend == "up"、预期滞后板块的trend == "down"的比例,合并计算。 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 个月横向柱状对比,绿色为正收益、红色为负收益:
从这张样例图本身就能演示 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 个下一阶段的可能情景。每个情景必须包含五个要素:
- 描述的周期转换(例如"从 mid 向 late 过渡")
- 可能跑赢的板块
- 可能跑输的板块
- 确认该情景的催化剂或条件
- 概率赋值(依据下一节的分档)
情景需按概率从高到低排列,最后一个是"替代/逆向"情景。
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_pctcycle_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 技能包与工作流中的位置
- skillsets/market-regime.yaml 把 sector-analyst 列为
optional_skills(required 是 market-breadth-analyzer、uptrend-analyzer、exposure-coach) - workflows/multi-asset-opportunity-daily.yaml 同样将其列为
optional_skills - README.md 的技能目录中,其集成需求标注为
chart_imagerequired——注意这与 SKILL.md 中"图片可选、CSV 是主输入"的表述存在张力,实际使用以 SKILL.md 为准
十一、七条分析原则与概率分档
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 且 Downmake_late_cycle_scenario():Energy/Basic Materials 0.40,Technology/Consumer Cyclical 0.10,其余 0.20make_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 对照同一份数据的另一种呈现方式。
