深入拆解 claude-trading-skills Theme Detector 报告模板:占位符契约、字段语义与渲染实现
深入拆解 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。
因此,从源码结构看,这个模板承担三种角色:
- 结构契约:规定一份完整主题报告应包含哪些章节、哪些表格与哪些字段,供人工或 LLM 撰写报告时对齐;
- 字段词典:
{{heat}}、{{lifecycle}}、{{relative_pe}}等占位符给出了字段的语义边界(如heat是 0-100 分值、lifecycle是枚举字符串); - 对照基准:把模板与
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 子分数。看跌主题的“上行对齐度”是这样得到的:
- 行业按多周期动量排名,排名前半 →
bullish,后半 →bearish(industry_ranker.py 中的rank_direction); - 主题方向 = 成员行业方向的多数票;
- 计算 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[]。这里有两个极易踩的坑,都有测试守着:
- 字段名是
momentum_score,不是composite_score。test_report_generator.py 明确断言:momentum_score=0.89要出现在报告中,且不存在composite_score路径。 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% 失败率通常意味着一个端点持续不可用而另一个成功,真实数据损失低于失败计数。
十二、把模板当契约使用的三个建议
- 写下游渲染器时以 JSON 为准:模板有
{{duration_weeks}}、{{direction_strength}}、{{assessment}}等运行时并不直接产出的字段,硬套会得到空值。用themes.all[]的heat_breakdown/maturity_breakdown/narrative_keyword_score组合,能覆盖模板 90% 的表达力。 - 校验权重时以常量为准:
HEAT_WEIGHTS = 35/20/25/20、LIFECYCLE_WEIGHTS = 25/25/25/15/10。模板 Methodology 段中的 30/25/25/20 是陈旧描述。 - 不要跳过徽章与 Coverage:
[Lifecycle data insufficient]、[Discovered - provisional]、Data Coverage三元组是判断“这个主题能不能用”的第一道过滤,比 Heat 数值本身更能防止误读。
模板的价值不在于被机器渲染,而在于它把“一份可信的主题报告应该长什么样”固化成了可对照的清单;而 report_generator.py 则给出了当前版本的实际答案。把两者对照阅读,你既能拿到字段语义,也能知道哪些语义已经被实现、哪些仍停留在文档层面——这正是把这份模板用在生产管线里最稳妥的方式。
免责声明:Theme Detector 的输出仅用于教育与信息参考,不构成投资建议。主题动量识别的是相对强弱与拥挤度,而非基本面价值;LEAD/LAG 是相对排名,LAG 不等于做空信号。