Expose long-horizon context diagnostics

Author: Pigbibi

README.md

@@ -45,7 +45,7 @@ Advisor is the final composition layer. Source ownership by horizon is:
 - Medium term (`2-12 weeks`): `theme_momentum_snapshot.json` from `ResearchSignalContextPipelines`, now explicitly marked as `medium_horizon_theme_context`, focused on theme momentum and symbol momentum.
 - Long term (`1-3 years`): `latest_signal.json` / `signal_history/*.json` from `ResearchSignalContextPipelines` as AI shadow context.
 
-Final recommendations are still deterministic Intelligent Advisory outputs. The signal context repository does not directly produce short-term recommendations or replace the final decision engine. Advisor now records separate short/medium/long horizon scores and gates for each final pick; public pages keep the simpler final recommendation layout.
+Final recommendations are still deterministic Intelligent Advisory outputs. The signal context repository does not directly produce short-term recommendations or replace the final decision engine. Advisor records separate short/medium/long horizon scores and gates for each final pick, plus JSON diagnostics that explain whether long-horizon context was actually available. Public pages keep the simpler final recommendation layout and can show a compact long-context symbol strip when no pick's primary bucket is long.
 
 ## Boundary
 

README.zh-CN.md

@@ -33,7 +33,7 @@ QuantStrategyLab 的“智慧投顾研究系统”协调仓库。它把事件证
 - 中线（2-12 周）：`ResearchSignalContextPipelines` 的 `theme_momentum_snapshot.json`，现在明确标记为 `medium_horizon_theme_context`，重点看主题动量和个股动量。
 - 长线（1-3 年）：`ResearchSignalContextPipelines` 的 `latest_signal.json` / `signal_history/*.json`，作为 AI shadow 背景。
 
-最终研究结论仍由本仓库确定性合成。信号上下文仓库不直接输出短线推荐，也不替代本仓库的最终决策。本仓库会为最终推荐记录短/中/长线独立评分和独立门槛，但公开页面仍保持简洁，只展示最终列表、背景、理由和风险。
+最终研究结论仍由本仓库确定性合成。信号上下文仓库不直接输出短线推荐，也不替代本仓库的最终决策。本仓库会为最终推荐记录短/中/长线独立评分和独立门槛，并在 JSON 里记录长线背景是否可用。公开页面仍保持简洁，只展示最终列表、背景、理由和风险；如果没有标的以长线作为主周期，但已经通过长线观察门槛，页面会显示一个简洁的“长线观察”标的条。
 
 ## 当前 MVP
 

docs/advisory_contract.md

@@ -156,6 +156,7 @@ recommendations[]
 watchlist[]
 horizon_buckets.short | medium | long
 horizon_rankings.short | medium | long
+horizon_action_buckets.short | medium | long
 ```
 
 Each final pick may carry:
@@ -187,6 +188,25 @@ Scoring and gate intent by horizon:
 
 These fields are audit metadata. Public HTML/RSS/Telegram renderers still show
 only final recommendations, stock background, recommendation reasons, and risks.
+If the primary long bucket is empty but final picks still pass the long-horizon
+`watch` or `recommend` gate, the public HTML may show a compact long-context
+symbol strip instead of exposing internal scores.
+
+## Long-context Diagnostics
+
+`summary` includes long-context health fields so an empty long bucket can be
+debugged without reading renderer code:
+
+```text
+long_context_available
+long_context_symbol_count
+long_context_symbols
+long_context_missing_reason
+```
+
+If `long_context_available=false`, `long_context_missing_reason` should point to
+the first likely ingestion problem, such as missing AI shadow input, a non-long
+`latest_signal` horizon, or missing symbol/theme coverage.
 
 ## Artifact Manifest
 

docs/system_design.md

@@ -62,6 +62,8 @@ execution targets for this advisory pipeline.
 `QuantAdvisorResearch` records per-recommendation `supporting_context`,
 `horizon_scores`, and `horizon_actions` so each final recommendation can be
 traced back to short-, medium-, and long-horizon inputs and gates.
+The report summary also records long-context availability diagnostics. This
+keeps a genuinely weak long signal separate from an upstream ingestion gap.
 
 ## Design Patterns
 
@@ -96,6 +98,8 @@ The public HTML/RSS/Telegram outputs should stay direct:
   and risks;
 - render public recommendations as long-, medium-, and short-horizon columns,
   sorted by each horizon score inside the column;
+- show a compact long-context symbol strip when the primary long bucket is empty
+  but final picks still pass long-horizon watch/recommend gates;
 - hide internal tags such as `source_mode`, mode labels, audience labels, and
   repository names;
 - keep `theme_first_candidates[]`, `horizon_scores`, and `selection_trace` in

docs/system_design.zh-CN.md

@@ -114,13 +114,15 @@ symbol_theme_exposure
 - 长线（1-3 年）：AI shadow 背景层负责，来自 `latest_signal.json` 和 `signal_history/*.json`。
 
 `QuantAdvisorResearch` 只在最后做确定性合成，报告中的 `supporting_context`、`horizon_scores` 和 `horizon_actions` 会记录每个最终推荐用到了短线、中线、长线哪些输入，以及每个周期是否达到推荐或观察门槛。
+报告 summary 还会记录长线背景是否可用，避免把“上游 artifact 缺字段”误读成“长线没有机会”。
 
 ## Theme momentum 展示边界
 
 `QuantAdvisorResearch` 可以消费 `theme_momentum_snapshot.json`，用途分两层：
 
 - 公开页面只展示最终推荐，不展示主题候选池；
 - 公开页面按长线 / 中线 / 短线三列展示，每列内按对应周期分数排序；
+- 如果长线主周期为空，但最终推荐已通过长线观察或推荐门槛，公开页面显示简洁的“长线观察”标的条；
 - JSON/Markdown 保留 `theme_first_candidates[]` 供审计；
 - `final_decisions` 可以把主题动量作为中线评分的重要输入；
 - 基础 `recommendations[]` 评级仍由事件、watchlist 和 AI 背景生成；

src/quant_advisor_research/advisory_report.py

@@ -1328,33 +1328,88 @@ def build_final_decisions(
         horizon: [item["symbol"] for item in recommendations_out if item.get("primary_horizon") == horizon]
         for horizon in ("short", "medium", "long")
     }
+    ranked_by_horizon = {
+        horizon: sorted(
+            picks,
+            key=lambda candidate: (
+                -as_float(candidate.get("horizon_scores", {}).get(horizon, {}).get("score")),
+                str(candidate.get("symbol", "")),
+            ),
+        )
+        for horizon in ("short", "medium", "long")
+    }
     horizon_rankings = {
         horizon: [
             {
                 "symbol": item["symbol"],
                 "score": item["horizon_scores"][horizon]["score"],
                 "action": item["horizon_actions"][horizon],
             }
-            for item in sorted(
-                picks,
-                key=lambda candidate: (
-                    -as_float(candidate.get("horizon_scores", {}).get(horizon, {}).get("score")),
-                    str(candidate.get("symbol", "")),
-                ),
-            )[:max_recommendations]
+            for item in ranked_by_horizon[horizon][:max_recommendations]
         ]
         for horizon in ("short", "medium", "long")
     }
+    horizon_action_buckets = {
+        horizon: {
+            action: [
+                item["symbol"]
+                for item in ranked_by_horizon[horizon]
+                if item["horizon_actions"].get(horizon) == action
+            ][:max_recommendations]
+            for action in ("recommend", "watch")
+        }
+        for horizon in ("short", "medium", "long")
+    }
     return {
         "method": "Final recommendation blend for model scoring.",
         "recommendations": recommendations_out,
         "watchlist": watchlist_out,
         "horizon_buckets": horizon_buckets,
         "horizon_rankings": horizon_rankings,
+        "horizon_action_buckets": horizon_action_buckets,
         "position_policy": "No target shares, position size, portfolio weight, or account-specific allocation is provided.",
     }
 
 
+def long_context_symbols_from_decisions(final_decisions: dict[str, Any]) -> list[str]:
+    symbols: list[str] = []
+    action_buckets = final_decisions.get("horizon_action_buckets", {})
+    long_buckets = action_buckets.get("long", {}) if isinstance(action_buckets, dict) else {}
+    if isinstance(long_buckets, dict):
+        for action in ("recommend", "watch"):
+            for symbol in long_buckets.get(action, []):
+                symbol_text = str(symbol).upper()
+                if symbol_text and symbol_text not in symbols:
+                    symbols.append(symbol_text)
+    if symbols:
+        return symbols
+
+    for section in ("recommendations", "watchlist"):
+        for item in final_decisions.get(section, []):
+            if not isinstance(item, dict):
+                continue
+            symbol_text = str(item.get("symbol", "")).upper()
+            action = str(item.get("horizon_actions", {}).get("long", ""))
+            has_long_context = action in {"recommend", "watch"} or as_float(item.get("long_context_score")) >= 0.35
+            if symbol_text and has_long_context:
+                if symbol_text not in symbols:
+                    symbols.append(symbol_text)
+    return symbols
+
+
+def infer_long_context_missing_reason(ai_signal: dict[str, Any] | None) -> str:
+    if not ai_signal:
+        return "ai_signal_not_available"
+    horizon_text = str(ai_signal.get("horizon", "")).strip()
+    if horizon_text not in {HORIZON_WINDOWS["long"], "1-3 years"}:
+        return "latest_signal_horizon_not_long"
+    if not ai_signal.get("symbol_bias") and not ai_signal.get("theme_bias"):
+        return "latest_signal_lacks_symbol_or_theme_bias"
+    if not ai_signal.get("symbol_bias") and not ai_signal.get("symbol_theme_exposure"):
+        return "latest_signal_lacks_symbol_theme_exposure"
+    return "current_candidates_do_not_meet_long_context_gate"
+
+
 def build_advisory_report(
     *,
     as_of: str,
@@ -1393,7 +1448,7 @@ def build_advisory_report(
         for key in ("symbol_bias", "research_bias", "candidate_bias"):
             symbols |= {symbol.upper() for symbol in normalize_ai_mapping(ai_signal.get(key) or {})}
 
-    recommendations = [
+    all_recommendations = [
         build_recommendation(
             symbol=symbol,
             item=watchlist.get(symbol),
@@ -1403,10 +1458,11 @@ def build_advisory_report(
         )
         for symbol in sorted(symbols)
     ]
-    recommendations.sort(key=lambda rec: (-rec["evidence_score"], rec["risk_score"], rec["symbol"]))
-    recommendations = recommendations[:max_candidates]
-    theme_first_candidates = build_theme_first_candidates(theme_momentum, recommendations)
-    final_decisions = build_final_decisions(recommendations, theme_momentum, market_confirmations)
+    all_recommendations.sort(key=lambda rec: (-rec["evidence_score"], rec["risk_score"], rec["symbol"]))
+    recommendations = all_recommendations[:max_candidates]
+    theme_first_candidates = build_theme_first_candidates(theme_momentum, all_recommendations)
+    final_decisions = build_final_decisions(all_recommendations, theme_momentum, market_confirmations)
+    long_context_symbols = long_context_symbols_from_decisions(final_decisions)
 
     report = {
         "schema_version": "5",
@@ -1424,6 +1480,7 @@ def build_advisory_report(
         },
         "summary": {
             "recommendation_count": len(recommendations),
+            "candidate_universe_count": len(all_recommendations),
             "source_event_count": len(events),
             "ai_regime": ai_signal.get("regime", "not_available") if ai_signal else "not_available",
             "ai_confidence": ai_signal.get("confidence", 0.0) if ai_signal else 0.0,
@@ -1436,6 +1493,12 @@ def build_advisory_report(
             "top_theme_ids": [theme["theme_id"] for theme in theme_momentum_summary["top_themes"]],
             "theme_first_candidate_count": len(theme_first_candidates),
             "market_confirmation_count": len(market_confirmations),
+            "long_context_available": bool(long_context_symbols),
+            "long_context_symbol_count": len(long_context_symbols),
+            "long_context_symbols": long_context_symbols[:12],
+            "long_context_missing_reason": ""
+            if long_context_symbols
+            else infer_long_context_missing_reason(ai_signal),
             "top_theme_candidate_symbols": [item["symbol"] for item in theme_first_candidates[:8]],
             "top_recommended_symbols": [item["symbol"] for item in final_decisions["recommendations"][:5]],
             "review_note": "Intelligent advisory research output. No order, target quantity, account suitability, or portfolio allocation is encoded.",

src/quant_advisor_research/publisher.py

@@ -131,6 +131,30 @@ def ranked_horizon_picks(final_picks: list[dict[str, Any]], horizon: str) -> lis
     return sorted(picks, key=lambda pick: (-horizon_pick_score(pick, horizon), str(pick.get("symbol", ""))))
 
 
+def ranked_secondary_horizon_picks(final_picks: list[dict[str, Any]], horizon: str) -> list[dict[str, Any]]:
+    picks = [
+        pick
+        for pick in final_picks
+        if pick.get("primary_horizon") != horizon
+        and pick.get("horizon_actions", {}).get(horizon) in {"recommend", "watch"}
+    ]
+    return sorted(picks, key=lambda pick: (-horizon_pick_score(pick, horizon), str(pick.get("symbol", ""))))
+
+
+def render_horizon_context_strip(picks: list[dict[str, Any]]) -> str:
+    if not picks:
+        return ""
+    symbols = "".join(
+        f'<span class="context-symbol">{html.escape(str(pick.get("symbol", "")))}</span>' for pick in picks[:5]
+    )
+    return f"""
+    <div class="context-strip">
+      <p>长线观察</p>
+      <div class="context-symbols">{symbols}</div>
+    </div>
+    """
+
+
 def render_final_card(pick: dict[str, Any], *, rank: int) -> str:
     reasons = "".join(f"<li>{html.escape(str(reason))}</li>" for reason in pick.get("why_selected", []))
     return f"""
@@ -166,7 +190,11 @@ def render_final_decisions_html(report: dict[str, Any]) -> str:
             render_final_card(pick, rank=index)
             for index, pick in enumerate(ranked_horizon_picks(final_picks, horizon), start=1)
         ]
-        body = "".join(cards) if cards else '<p class="empty-column">暂无</p>'
+        body = "".join(cards)
+        if not body and horizon == "long":
+            body = render_horizon_context_strip(ranked_secondary_horizon_picks(final_picks, horizon))
+        if not body:
+            body = '<p class="empty-column">暂无</p>'
         columns.append(
             f"""
             <section class="horizon-column horizon-{html.escape(horizon)}">
@@ -416,6 +444,10 @@ def render_report_html(report: dict[str, Any]) -> str:
     .horizon-column-header p {{ margin: 5px 0 0; color: var(--muted); font-size: .88rem; }}
     .horizon-cards {{ display: grid; gap: 13px; }}
     .empty-column {{ margin: 24px 0; color: var(--muted); text-align: center; }}
+    .context-strip {{ border: 1px dashed rgba(15,139,98,.32); border-radius: 20px; padding: 16px; background: rgba(240,253,244,.74); }}
+    .context-strip p {{ margin: 0 0 10px; color: var(--green); font-size: .92rem; font-weight: 850; }}
+    .context-symbols {{ display: flex; flex-wrap: wrap; gap: 8px; }}
+    .context-symbol {{ display: inline-flex; align-items: center; min-height: 30px; padding: 6px 10px; border-radius: 999px; background: #fff; border: 1px solid rgba(15,139,98,.22); color: var(--ink); font-size: .92rem; font-weight: 850; }}
     .final-card {{
       background: rgba(255,255,255,.9);
       border: 1px solid rgba(217,226,239,.95);
@@ -486,11 +518,32 @@ def render_report_html(report: dict[str, Any]) -> str:
 """
 
 
-def format_horizon_summary(report: dict[str, Any]) -> list[tuple[str, str, str, list[str]]]:
+def horizon_summary_symbols(report: dict[str, Any], horizon: str) -> list[str]:
     decisions = report.get("final_decisions", {})
     buckets = decisions.get("horizon_buckets", {}) if isinstance(decisions, dict) else {}
+    primary_symbols = [str(symbol) for symbol in buckets.get(horizon, [])]
+    if primary_symbols:
+        return primary_symbols
+
+    final_picks = [pick for pick in decisions.get("recommendations", []) if isinstance(pick, dict)]
+    secondary_picks = [
+        pick
+        for pick in final_picks
+        if pick.get("horizon_actions", {}).get(horizon) in {"recommend", "watch"}
+    ]
+    return [
+        str(pick.get("symbol", ""))
+        for pick in sorted(
+            secondary_picks,
+            key=lambda item: (-horizon_pick_score(item, horizon), str(item.get("symbol", ""))),
+        )
+        if str(pick.get("symbol", ""))
+    ]
+
+
+def format_horizon_summary(report: dict[str, Any]) -> list[tuple[str, str, str, list[str]]]:
     return [
-        (horizon, label, window, [str(symbol) for symbol in buckets.get(horizon, [])])
+        (horizon, label, window, horizon_summary_symbols(report, horizon))
         for horizon, label, window in HORIZON_COLUMNS
     ]
 

tests/test_advisory_report.py

@@ -307,6 +307,10 @@ def test_theme_bias_can_lift_static_watchlist_item_without_direct_symbol_bias(tm
     assert rec["rating"] == "watch"
     assert rec["evidence_score"] > 4
     assert any("主题=hbm_memory" in reason for reason in rec["reasons"])
+    assert report["summary"]["long_context_available"] is True
+    assert report["summary"]["long_context_missing_reason"] == ""
+    assert "MU" in report["summary"]["long_context_symbols"]
+    assert report["final_decisions"]["horizon_action_buckets"]["long"]["watch"][:1] == ["MU"]
 
 
 def test_theme_momentum_snapshot_is_display_context_not_rating_input(tmp_path: Path) -> None:

tests/test_publisher.py

@@ -150,6 +150,11 @@ def pick(symbol: str, horizon: str, score: float) -> dict:
                 "medium": {"score": score if horizon == "medium" else 0.0},
                 "short": {"score": score if horizon == "short" else 0.0},
             },
+            "horizon_actions": {
+                "long": "recommend" if horizon == "long" else "skip",
+                "medium": "recommend" if horizon == "medium" else "skip",
+                "short": "recommend" if horizon == "short" else "skip",
+            },
             "business_summary": f"{symbol} background",
             "prospect_summary": f"{symbol} reason",
             "why_selected": ["ranked"],
@@ -176,6 +181,44 @@ def pick(symbol: str, horizon: str, score: float) -> dict:
     assert "最终推荐" not in html
 
 
+def test_render_report_html_shows_long_context_when_primary_bucket_is_medium() -> None:
+    report = build_sample_report()
+    report["final_decisions"]["recommendations"] = [
+        {
+            "symbol": "MU",
+            "name": "Micron Technology",
+            "primary_horizon": "medium",
+            "primary_horizon_label": "中线",
+            "primary_horizon_window": "2-12周",
+            "combined_score": 0.9,
+            "source_score": 0.1,
+            "momentum_score": 0.9,
+            "medium_context_score": 0.9,
+            "long_context_score": 0.62,
+            "horizon_scores": {
+                "long": {"score": 0.66},
+                "medium": {"score": 0.9},
+                "short": {"score": 0.1},
+            },
+            "horizon_actions": {
+                "long": "watch",
+                "medium": "recommend",
+                "short": "skip",
+            },
+            "business_summary": "MU background",
+            "prospect_summary": "MU reason",
+            "why_selected": ["ranked"],
+            "risk_summary": "risk",
+        }
+    ]
+
+    html = render_report_html(report)
+
+    assert "长线观察" in html
+    assert '<span class="context-symbol">MU</span>' in html
+    assert "最终推荐" not in html
+
+
 def test_render_report_html_includes_theme_momentum_context() -> None:
     report = build_advisory_report(
         as_of="2026-05-30",