深入拆解 claude-trading-skills Theme Detector 报告模板:占位符契约、字段语义与渲染实现

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

深入拆解 claude-trading-skills Theme Detector 报告模板:占位符契约、字段语义与渲染实现

Theme Detector 是 claude-trading-skills 中负责跨行业主题识别的技能,它会输出 JSON 与 Markdown 两份结果。其中 report_template.md 是这份 Markdown 报告的“契约文档”——它用 {{placeholder}} 与 {{#each}} 语法定义了报告应有的 7 大区块、每张表的列结构和每个字段的含义。本文以该模板为主线,逐节拆解每个占位符背后的取值逻辑,并结合 report_generator.py 与 theme_detection_methodology.md 说明模板与运行时实现的对应关系、已知差异,以及如何正确消费这份报告。

一、模板在当前仓库中的定位

先给出一个关键事实,避免读者误解:当前仓库并没有引入 Mustache/Handlebars 之类的模板引擎来渲染这个文件。

  • 用 search_in_files 检索 report_template,在 scripts/ 目录下没有任何命中,唯一引用出现在 SKILL.md 的 Assets 说明中:“Markdown template for report generation with placeholder format”。
  • 真正的 Markdown 文本由 generate_markdown_report() 用 Python 列表逐行拼装生成,入口在 theme_detector.py。

因此,从源码结构看,这个模板承担三种角色:

  1. 结构契约:规定一份完整主题报告应包含哪些章节、哪些表格与哪些字段,供人工或 LLM 撰写报告时对齐;
  2. 字段词典:{{heat}}、{{lifecycle}}、{{relative_pe}} 等占位符给出了字段的语义边界(如 heat 是 0-100 分值、lifecycle 是枚举字符串);
  3. 对照基准:把模板与 report_generator.py 的 9 个章节逐条比对,可以清晰看出“文档期望”与“当前实现”的差异,这对下游程序化消费报告尤其重要。

二、报告头部元数据块

模板开篇是 7 行键值对:

**Date:** {{date}}
**Mode:** {{mode}}
**Themes Analyzed:** {{themes_analyzed}}
**Industries Scanned:** {{industries_scanned}}
**Total Stocks:** {{total_stocks}}
**Uptrend Data:** {{uptrend_data_status}}
**Execution Time:** {{execution_time}}

每个字段的来源与语义如下:

占位符 含义 实际数据来源
{{date}} 运行日期 由 --as-of-date 决定的运行日,或系统当前日期
{{mode}} FINVIZ 运行模式 metadata.data_mode / metadata.finviz_mode,取值 public 或 elite
{{themes_analyzed}} 实际分析主题数 summary.total_themes
{{industries_scanned}} 扫描行业数 metadata.data_sources.finviz_industries(Elite 模式下约 145 个 FINVIZ 行业)
{{total_stocks}} 参与分析的股票数 metadata.data_sources.yfinance_stocks 等计数
{{uptrend_data_status}} uptrend-dashboard 数据是否可用 metadata.data_sources 中的 uptrend 状态;缺失时会降级为 FINVIZ 价格与 SMA200 的替代口径
{{execution_time}} 执行耗时 脚本计时结果;Elite 约 2-3 分钟,公共抓取约 5-8 分钟

在真实 JSON 中,这些元信息集中在 metadata 对象里,SKILL.md 给出的示例结构为:

"metadata": {
  "generated_at": "2026-04-18 10:30:00",
  "data_mode": "full",
  "finviz_mode": "elite",
  "fmp_available": true,
  "max_themes": 14,
  "max_stocks_per_theme": 5,
  "data_sources": {
    "finviz_industries": 152,
    "yfinance_stocks": 68,
    "etf_volume": 24
  }
}

而运行时 Markdown 的头部只保留两行——**Generated:** 与 **Themes Detected:** N (X leading, Y lagging),见 report_generator.py。这意味着:如果你要一份完整头部,得从 JSON 的 metadata 自行补齐,模板就是那张“该补哪些字段”的清单。

三、第 1 节:Theme Dashboard

| Rank | Theme | Direction | Heat | Lifecycle | Confidence |
|------|-------|-----------|------|-----------|------------|
|{{#each top_themes}}
| {{rank}} | {{name}} | {{direction_emoji}} {{direction}} | {{heat}}/100 | {{lifecycle}} | {{confidence}} |
{{/each}}

紧随其后的图例是理解整份报告的关键:

**Legend:** Direction: LEAD/LAG (Dashboard), ^/v (Summary) | Heat: 0-100 scale |
Lifecycle: Emerging/Accelerating/Trending/Mature/Exhausting

三处显示约定分别对应源码中的三个函数:

  • LEAD / LAG:_direction_label() 把 "bullish" 映射为 LEAD、"bearish" 映射为 LAG。函数注释明确指出:之所以不用 BULL/BEAR,是因为方向由匹配行业的相对表现决定,而不是绝对涨跌。一个 LAG 主题完全可能录得正收益,它只是跑输其他主题——它是减配候选,不是做空信号。
  • ^ / v:_direction_arrow() 用于紧凑的汇总表,输出 ^、v 或 -(未知)。
  • Heat 0-100:由 heat_calculator.py 计算的 heat 字段,方向中性。

此外,运行时 Dashboard 表格比模板多了 Origin 与 Match 两列,并用文本进度条可视化热度,见 report_generator.py 与 _heat_bar():

def _heat_bar(heat: float) -> str:
    if heat >= 80.0: return "████"
    elif heat >= 60.0: return "███░"
    elif heat >= 40.0: return "██░░"
    elif heat >= 20.0: return "█░░░"
    else: return "░░░░"

Origin 列由 _origin_label() 渲染:seed → Seed(来自 YAML 预定义),vertical → Vertical,discovered → *NEW*(自动聚类发现的临时主题),未知值回退为 Seed。写入模板时,若要保留这一信息,应扩展 {{origin}} 占位符。

四、第 2 节:Bullish Themes Detail(模板中最重的分析块)

模板用 {{#each bullish_themes}} 循环生成每个主题的详情,包含 6 个子块。以下逐块对照实现。

4.1 标题与三维标签

### {{name}} - Heat: {{heat}}/100

**Direction:** Bullish ({{direction_strength}}) | **Lifecycle:** {{lifecycle}} | **Confidence:** {{confidence}}

direction_strength 在方法论文档里是 Strong 之类的定性描述,但当前 report_generator.py 的详情块输出的是 Direction: LEAD,并不输出 strength 字段。如果下游需要强度分级,应自行从 heat_breakdown.breadth_signal 派生,或按 _heat_subscore_interpretation() 的阈值(≥75 strong、≥50 moderate、≥25 weak、其余 very weak)标注。

4.2 Heat Components:模板权重与源码权重不一致

模板写的是:

- Momentum: {{momentum}}/100
- Volume: {{volume}}/100
- Uptrend: {{uptrend}}/100
- Breadth: {{breadth}}/100

同文件第 133 行的 Methodology 又写为:

- **Theme Heat** (0-100): Momentum (30%) + Volume (25%) + Uptrend (25%) + Breadth (20%)

但仓库中作为唯一事实来源的常量是 heat_calculator.py:

HEAT_WEIGHTS = {
    "momentum_strength": 0.35,
    "volume_intensity": 0.20,
    "uptrend_signal": 0.25,
    "breadth_signal": 0.20,
}

即真实权重为 35 / 20 / 25 / 20,与方法论文档一致,而与模板第 133 行的 30/25/25/20 不一致。结论:以 HEAT_WEIGHTS 为准,模板的百分比一行存在陈旧描述。这是一个典型的“文档-代码漂移”案例,写报告时若照抄模板会得到错误权重。

各子分数量化公式(均来自源码,与 theme_detection_methodology.md 一致):

子分数 公式 中位/示例
Momentum `100 / (1 + exp(-2*(ln(1+ wr
Volume min(100, sqrt(max(0, ratio-0.8)) / sqrt(1.2) * 100),ratio = vol_20d/vol_60d 1.2 → ~58;2.0 → 100
Uptrend min(80, ratio*100) + 10(ratio>ma_10) + 10(slope>0),按权重平均;看跌主题取 100 - score 无数据返回 None
Breadth min(100, ratio^2.5 * 80 + min(20, industry_count*2)) 0.9 → ~61;1.0 → 80

重要实现细节:缺失子分数不会按 50 分兜底。calculate_theme_heat_detailed() 只在可用分量上做加权归一,并同时返回 coverage、missing_components:

available = {k: v for k, v in components.items() if v is not None}
score = sum(available[k] * weights[k] for k in available) / total_weight
return score, total_weight / total_possible

这比“缺失即中性”更保守:数据不足会降低 heat_coverage,而不是伪造一个中间值。

4.3 Lifecycle Factors:五个因子与 25/25/25/15/10 权重

- Duration: {{duration_weeks}} weeks
- Extremity clustering: {{extremity_pct}}%
- Relative P/E: {{relative_pe}}x
- ETF proliferation: {{etf_count}} ETFs (score: {{etf_score}}/100)
- Narrative: {{narrative_assessment}}

对应 lifecycle_calculator.py 的权重表:

LIFECYCLE_WEIGHTS = {
    "duration": 0.25, "extremity": 0.25, "price_extreme": 0.25,
    "valuation": 0.15, "etf_proliferation": 0.10,
}

模板缺了 price_extreme(52 周极值饱和度)这一项——它是 25% 权重的独立因子,公式为 min(100, pct*200),看跌主题用距 52 周低点 ≤5% 的占比。

各因子的脚本实现口径:

  • Duration:源码并非按“连续周数”精确计数,而是按 4 个时间窗打分——perf_1m/3m/6m/1y 中每个满足 >2%(看跌为 <-2%)的窗口计 25 分,上限 100。模板的 {{duration_weeks}} 更接近主题历史(--history-file)中的观测周数,两者不要混用。
  • Extremity:源码用 RSI 极值占比(看涨 RSI>70、看跌 RSI<30)而非模板描述的 52 周高低点距离,pct * 200 截断到 100。
  • Valuation:relative_pe = avg_theme_pe / sp500_pe,由 FMP 提供,缺失时退化为 FINVIZ forward P/E。分段:<0.8 低估、0.8-1.0 合理、1.0-1.4 偏高、1.4-2.0 高估、>2.0 极端。
  • ETF proliferation:查静态目录 thematic_etf_catalog.md,阶梯评分见 etf_proliferation_score():0→0、1→20、≤3→40、≤6→60、≤10→80、>10→100。ETF 越多,说明散户与机构关注度越高,主题越拥挤。
  • Narrative:模板要求填定性结论(Strong/Moderate/Weak),源码中不参与 maturity 计算,属于 Claude 在 Step 4 用 WebSearch 人工补充的层级;离线场景可用 --narrative-scores 传入 JSON 分值。

阶段划分按 maturity 分值切段:0-20 Emerging、20-40 Accelerating、40-60 Trending、60-80 Mature、80-100 Exhausting。

4.4 Top Industries / Top Movers / Proxy ETFs

- {{name}}: {{change_pct}}% ({{stock_count}} stocks, uptrend {{uptrend_ratio}}%)
- {{ticker}}: {{change_pct}}% | Vol: {{relative_volume}}x
**Proxy ETFs:** {{proxy_etfs}}

这三块的字段分别来自行业聚合、代表性个股与主题配置:

  • stock_count、uptrend_ratio 来自行业级聚合;
  • relative_volume 为当日成交量与均量之比;
  • proxy_etfs 在 themes.yaml 中逐主题预定义,例如 AI 主题为 [SMH, SOXX, AIQ, BOTZ],清洁能源为 [ICLN, QCLN, TAN, LIT]。

实际 Markdown 里,代表性个股会带数据来源标签,由 _format_stock_list() 渲染:

标签 含义
[Fe] FINVIZ Elite 数据
[Fp] FINVIZ 公共抓取
[E] ETF 持仓反查
[S] 静态配置(themes.yaml)
[?] 未知来源

例如 NVDA[Fe], AAPL[E], XOM[S]。这在模板里没有体现,但当你要判断“这只股票是不是真的被数据支撑”时,标签至关重要——[S] 只是配置文件里写死的样本,不是当日扫描结果。

4.5 Assessment 与两个质量徽章

{{assessment}} 是留给作者的自由文本结论。运行时实现还会在两个条件下插入警示块,见 report_generator.py:

> **[Lifecycle data insufficient]** Stock-level lifecycle components are missing or partial;
> maturity uses available components and coverage metadata.

> **[Discovered - provisional]** Theme name and boundaries are auto-generated.

前者对应 lifecycle_data_quality == "insufficient"(个股级生命周期数据缺失),后者对应 theme_origin == "discovered"(主题名与边界由算法生成,name_confidence 通常为 medium)。这两条徽章对应的测试断言在 test_report_generator.py,可以确认其为显式契约而非偶发输出。

此外,实际详情块会打印 Data Coverage 三元组:

- **Data Coverage:** Heat 100%, Lifecycle 60%, Leadership 0%

当 heat_coverage < 0.75 或 maturity_coverage < 0.60 时,_assess_data_quality() 会追加数据质量旗标。这是模板未覆盖但非常实用的“置信度辅助读数”。

五、第 3 节:Bearish Themes Detail 的方向感知差异

- Momentum: {{momentum}}/100
- Volume: {{volume}}/100
- Downtrend: {{downtrend}}/100
- Breadth: {{breadth}}/100

看跌块与看涨块只差一个分量名:{{uptrend}} → {{downtrend}},行业表也只列 downtrend_ratio,个股表用 bottom_stocks(Worst Performers)。

需要理解的是,源码中并没有一个独立的 downtrend 子分数。看跌主题的“上行对齐度”是这样得到的:

  1. 行业按多周期动量排名,排名前半 → bullish,后半 → bearish(industry_ranker.py 中的 rank_direction);
  2. 主题方向 = 成员行业方向的多数票;
  3. 计算 uptrend 分量时,若 is_bearish 为真则取 100 - 加权平均;breadth 的“方向对齐”则统计加权回报为负的行业占比。

因此模板里的 {{downtrend}} 应理解为“反向的 uptrend 分量”,数值越高代表下行压力越集中,而不是另一套独立指标。

六、第 4 节:All Themes Summary 宽表

| Theme | Direction | Heat | Momentum | Volume | Uptrend | Breadth | Lifecycle | Confidence |

这是一张“所有主题 + 全部分量”的横向对照表,用于横向比较。运行时同名章节(## 6. All Themes Summary)采用的是更精简的列:# | Theme | Dir | Heat | Maturity | Stage | Industries,其中行业列只显示前 3 个,其余折叠为 (+N),见 report_generator.py。

若你需要模板那种完整宽表,直接从 JSON 的 themes.all[] 取字段即可:heat、heat_breakdown.*、maturity、stage、confidence。注意代码中把成熟度字段命名为 maturity,而模板列名写的是 Lifecycle——同名不同词,写映射逻辑时要对齐。

七、第 5 节:Industry Rankings(Top 10 / Bottom 10)

| Rank | Industry | Sector | Change % | Rel. Volume | Uptrend Ratio | Theme |
| {{rank}} | {{name}} | {{sector}} | {{change_pct}}% | {{rel_volume}}x | {{uptrend_ratio}}% | {{theme}} |

对应 JSON 的 industry_rankings.top[] 与 .bottom[]。这里有两个极易踩的坑,都有测试守着:

  1. 字段名是 momentum_score,不是 composite_score。test_report_generator.py 明确断言:momentum_score=0.89 要出现在报告中,且不存在 composite_score 路径。
  2. perf_* 已是百分点,不可再乘 100。同文件 test_industry_perf_not_multiplied 断言出现 +5.0% 且不出现 500.0%。FINVIZ 客户端返回的是小数比率(0.05),转换在管线边界只做一次,见 _convert_perf_to_pct()。

sector 字段由 _add_sector_info() 从 INDUSTRY_TO_SECTOR 映射表补齐,未命中时填 Unknown。theme 列则是该行业被归入的主题名,一行业可命中多主题时以主主题展示。

运行时实现把榜单扩展为 Top/Bottom 各 15 行,并改用 Perf 1W / Perf 1M / Perf 3M / Score 四列(report_generator.py),比模板的两列(Change %、Rel. Volume)信息更密。模板这里其实是更旧的口径。

八、第 6 节:Sector Uptrend Ratios

| Sector | Uptrend Ratio | Avg Change % | Dominant Theme | Direction |

该表依赖 uptrend-dashboard 的 3 点技术评估输出。3 点定义为:价格 > 50 日均线、50 日均线 > 200 日均线、200 日均线向上。全满足为确认上升趋势,全不满足为确认下降趋势。

运行时表结构略有不同,见 report_generator.py:

Sector Ratio 10MA Slope Trend Date

格式化规则:ratio 与 ma_10 乘 100 显示为百分比,slope 用 +.4f 带符号显示,缺失统一为 N/A。

这一节还是时效性检查的落点。_assess_data_quality() 会先检查 latest_date 是否晚于报告基准日,再按 XNYS 交易日计算陈旧度:

if latest > current_date:
    flags.append(f"Uptrend data for {sector} is dated after the report as-of")
age = count_sessions("XNYS", latest, current_date, include_start=False, include_end=True)
if age > 3:
    flags.append(f"Uptrend data for {sector} is {age} sessions old")

对应的测试 test_report_freshness_uses_xnys_sessions 覆盖了两条分支。这说明该表不是“有数就贴上”,而是带门槛的证据:超过 3 个交易日就明确标记过期。

九、第 7 节:Methodology Notes 与三维评分模型

模板末尾的说明块是全篇可信度的支撑:

**Scoring Model:** 3-Dimensional (Heat x Lifecycle x Confidence)
- **Theme Heat** (0-100): Momentum (30%) + Volume (25%) + Uptrend (25%) + Breadth (20%)
- **Lifecycle**: Duration + Extremity clustering + Valuation + ETF proliferation + Narrative saturation
- **Confidence**: Quantitative breadth + Cross-sector confirmation + Narrative verification

**Data Sources:**
- FINVIZ {{mode}} (industry performance, volume, 52-week data)
{{#if uptrend_data}} - uptrend-dashboard (3-point technical evaluation) {{/if}}
{{#if fmp_data}} - FMP API (P/E ratios for valuation analysis) {{/if}}
- WebSearch (narrative confirmation for top themes)

**Limitations:**
- Theme definitions are static (predefined in cross_sector_themes.md)
- {{mode_limitation}}
- Duration tracking requires historical baseline data
- Narrative assessment is subjective

{{#if}} 条件渲染意味着:数据源清单是随运行环境动态变化的,缺 uptrend 就整行消失,缺 FMP 就不提 P/E。这比固定罗列更诚实。{{mode_limitation}} 则用于注入模式特有缺陷,例如公共模式“每行业仅约 20 只股票,可能漏掉小市值信号”。

9.1 热度的真实权重(再次强调)

模板正文与源码冲突,以源码为准:

theme_heat = momentum*0.35 + volume*0.20 + uptrend*0.25 + breadth*0.20

9.2 置信度的三层叠加规则

模板只写“Quantitative breadth + Cross-sector confirmation + Narrative verification”,具体合成逻辑在 scorer.py:

confirmed_count = sum([quant_confirmed, breadth_confirmed, narrative_confirmed])
if confirmed_count >= 3: level = "High"
elif confirmed_count >= 2: level = "Medium"
else: level = "Low"
if stale_data_penalty and level != "Low":
    level = "Medium" if level == "High" else "Low"
for _ in range(min(max(coverage_penalty_count, 0), 2)):
    ...  # 每级降一档,最多降两级

也就是说:三层确认计数决定基准档;陈旧数据降一档;覆盖度不足最多再降两档。而脚本输出的置信度上限是 Medium——High 只能由 Claude 的 WebSearch 叙事确认环节提升。这一点在 SKILL.md 的 Step 4 中有明确映射表:量化高 + 叙事强 = High;量化高 + 叙事弱 = Medium(动量背离预警);量化低 + 叙事强 = Medium(叙事可能领先价格)。

9.3 Limitations 的源码级印证

模板列出的四条限制都能在实现中找到痕迹,可放心引用:

  • 主题定义静态:themes.yaml 中 cross_sector 列表硬编码主题与关键词,另有 cross_sector_min_matches: 2、vertical_min_industries: 3 两个阈值控制匹配严格度。新主题只能靠 --discover-themes 临时聚类,且带 *NEW* 临时徽章。
  • 模式限制:见上文的公共模式股票数与延迟(15 分钟延迟 vs Elite 实时)。
  • 时长需历史基线:--history-file 未提供时无法计算 heat_delta_1d、heat_z_20d、prior_observations。
  • 叙事主观:--narrative-scores 是离线 JSON 输入,缺失时 narrative_keyword_score 为 null 且只降低 theme_match_coverage,不会让整次运行失败。

十、模板占位符与运行时字段的完整映射

把前面的逐节分析汇总成一张迁移表,方便你写下游渲染器或数据校验脚本:

模板占位符 JSON 路径 是否存在于运行时 Markdown 备注
{{date}} / {{execution_time}} metadata.generated_at 部分(仅 Generated) 需从 JSON 补
{{mode}} metadata.finviz_mode 否 —
{{heat}} themes[].heat 是 0-100
{{direction_emoji}} 由 direction 派生 是(LEAD/LAG、^/v) 见 _direction_label / _direction_arrow
{{lifecycle}} themes[].stage 是 字段名不一致
{{confidence}} themes[].confidence 是 Low/Medium/High
{{momentum}} heat_breakdown.momentum_strength 是 —
{{volume}} heat_breakdown.volume_intensity 是 —
{{uptrend}} / {{downtrend}} heat_breakdown.uptrend_signal 是 看跌为反向值
{{breadth}} heat_breakdown.breadth_signal 是 —
{{duration_weeks}} maturity_breakdown.duration / 历史观测 部分 口径与模板不同
{{extremity_pct}} maturity_breakdown.extremity 部分 实现用 RSI 极值
{{relative_pe}} maturity_breakdown.valuation 部分 依赖 FMP
{{etf_count}} / {{etf_score}} maturity_breakdown.etf_proliferation 部分 静态目录
{{narrative_assessment}} narrative_keyword_score / 人工结论 否 WebSearch 层
{{proxy_etfs}} themes[].proxy_etfs 是 —
{{origin}} themes[].theme_origin 是(模板无此列) Seed/Vertical/*NEW*
{{match}} themes[].theme_match_score 是(模板无此列) 证据质量分,非推荐

一句话总结这张表:模板覆盖了字段语义,运行时实现覆盖了字段子集并追加了 Origin/Match/Coverage 三类新信息;两者在权重与部分口径上存在漂移,且以源码为准。

十一、实操:从运行到拿到报告

11.1 安装与最小运行

pip install -r skills/theme-detector/requirements.txt

python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

带 Elite 密钥与自定义详情数量:

python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key "$FINVIZ_API_KEY" \
  --fmp-api-key "$FMP_API_KEY" \
  --top 5 \
  --max-themes 14 \
  --max-stocks-per-theme 10 \
  --output-dir reports/

--top 直接决定模板中 {{#each bullish_themes}} / {{#each bearish_themes}} 的循环长度:generate_markdown_report(json_report, top_n_detail=args.top),默认 3,对应章节标题 Leading Themes (Top 3)。相关行为由 test_report_generator.py 覆盖,包括 top_n_detail=1 时只保留热度最高的一个主题。

11.2 文件命名与定位

save_reports() 使用 theme_detector_%Y-%m-%d_%H%M%S 时间戳,并自动创建输出目录:

ls -lt reports/theme_detector_*.json | head -1
ls -lt reports/theme_detector_*.md   | head -1

JSON 写入时带 indent=2 与 default=str,因此日期对象会被安全序列化为字符串(测试 test_json_serializable)。

11.3 常用可选参数(与报告内容强相关)

参数 默认 对报告的影响
--top 3 详情章节的主题数量
--max-themes 10 themes.all 上限
--max-stocks-per-theme 10 代表性个股数量
--themes-config 内置 替换主题定义,需 PyYAML
--discover-themes 关 生成 *NEW* 临时主题
--dynamic-stocks 关 用 FINVIZ 筛选器动态选股,替代静态样本
--dynamic-min-cap small 动态选股最小市值(micro/small/mid)
--scan-hits 无 注入 5D+20%、EP9M 等领导力证据
--narrative-scores 无 离线叙事评分,影响 theme_match_score
--history-file <output-dir>/theme_detector_history.json 驱动 “What Changed Today”
--no-history-update 关 只读历史,不写入本次观测
--as-of-date 无 严格 YYYY-MM-DD 上限,非当日会 fail closed

--as-of-date 需要特别说明:FINVIZ、报价、profile 与 uptrend 输入都是实时数据而非 PIT 快照,因此传入非当前日期会直接失败,而不是产出看似“历史回放”的报告。theme_detector.py 用 _as_of_date_arg() 做零填充格式校验。

11.4 报告质量旗标怎么读

生成的 Markdown 末章会以 ### Data Quality Flags 列出问题,来源是 _assess_data_quality()。常见旗标与处理建议:

旗标片段 含义 建议
No themes detected - check FINVIZ connectivity 主题列表为空 先查 FINVIZ 连通性与密钥
Industry rankings unavailable 行业榜为空 同上,报告不可用于选股
Sector uptrend data unavailable uptrend CSV 抓取失败 报告缺少广度上下文
Uptrend data for X is N sessions old 数据陈旧 >3 个交易日 降低对 Sector 章的依赖
Uptrend data ... dated after the report as-of 未来数据 检查 --as-of-date 与源日期
Heat component coverage low for N theme(s) heat_coverage < 0.75 热度可信度下降
Lifecycle component coverage low for N theme(s) maturity_coverage < 0.60 阶段判断仅供参考
Stock leadership scan hits unavailable 未提供 --scan-hits 领导力证据未混入热度
FMP API: X/Y calls failed (Z%) 失败率 >20% ≥40% 时通常只是双端点中一个不可用

最后一条的注释值得记住:FMP 采用 stable → v3 的双端点回退,约 50% 失败率通常意味着一个端点持续不可用而另一个成功,真实数据损失低于失败计数。

十二、把模板当契约使用的三个建议

  1. 写下游渲染器时以 JSON 为准:模板有 {{duration_weeks}}、{{direction_strength}}、{{assessment}} 等运行时并不直接产出的字段,硬套会得到空值。用 themes.all[] 的 heat_breakdown / maturity_breakdown / narrative_keyword_score 组合,能覆盖模板 90% 的表达力。
  2. 校验权重时以常量为准:HEAT_WEIGHTS = 35/20/25/20、LIFECYCLE_WEIGHTS = 25/25/25/15/10。模板 Methodology 段中的 30/25/25/20 是陈旧描述。
  3. 不要跳过徽章与 Coverage:[Lifecycle data insufficient]、[Discovered - provisional]、Data Coverage 三元组是判断“这个主题能不能用”的第一道过滤,比 Heat 数值本身更能防止误读。

模板的价值不在于被机器渲染,而在于它把“一份可信的主题报告应该长什么样”固化成了可对照的清单;而 report_generator.py 则给出了当前版本的实际答案。把两者对照阅读,你既能拿到字段语义,也能知道哪些语义已经被实现、哪些仍停留在文档层面——这正是把这份模板用在生产管线里最稳妥的方式。

免责声明:Theme Detector 的输出仅用于教育与信息参考,不构成投资建议。主题动量识别的是相对强弱与拥挤度,而非基本面价值;LEAD/LAG 是相对排名,LAG 不等于做空信号。

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