Clarify recommendation horizon windows

Author: Pigbibi

README.md

@@ -97,7 +97,7 @@ Notification channel rules are documented in
 The main JSON artifact is `ModelRecommendationReport`:
 
 ```text
-schema_version = 4
+schema_version = 5
 as_of
 generated_at
 mode = model_recommendations
@@ -120,8 +120,10 @@ recommendation_tier
 recommendation_tier_label
 primary_horizon
 primary_horizon_label
+primary_horizon_window
 horizon_note
 suitable_horizons[]
+suitable_horizon_windows{}
 strategy_style
 score
 evidence_score
@@ -134,6 +136,13 @@ evidence_refs[]
 review_checklist[]
 ```
 
+Default horizon windows:
+
+- short: `1-10 trading days`
+- medium: `2-12 weeks`
+- long: `1-3 years`
+- not_applicable: source check, defer, or monitor only
+
 ## Regulatory Boundary
 
 Even when no orders or allocations are generated, specific securities

README.zh-CN.md

@@ -33,7 +33,8 @@ python scripts/build_advisory_report.py \
 - 推荐标的
 - 推荐等级：重点推荐、观察、先核验来源、暂缓、监控
 - 推荐层级：一级推荐、二级推荐、观察名单、来源核验
-- 适合周期：短线、中线、长线
+- 适合周期：短线、中线、长线，并明确时间窗口
+- 周期窗口：短线=1-10个交易日，中线=2-12周，长线=1-3年
 - 周期说明：短线风险、事件驱动验证周期、长期观察理由
 - 来源可信度：高、中、低、混合、无事件
 - 中长线、价值、事件、宏观等策略风格标签

docs/advisory_contract.md

@@ -5,7 +5,7 @@
 Required top-level fields:
 
 ```text
-schema_version: "4"
+schema_version: "5"
 as_of: ISO date
 generated_at: ISO datetime
 mode: "model_recommendations"
@@ -45,8 +45,10 @@ recommendation_tier
 recommendation_tier_label
 primary_horizon
 primary_horizon_label
+primary_horizon_window
 horizon_note
 suitable_horizons
+suitable_horizon_windows
 strategy_style
 score
 evidence_score
@@ -83,6 +85,13 @@ Allowed horizons:
 - `long`
 - `not_applicable`
 
+Default horizon windows:
+
+- `short`: `1-10个交易日`
+- `medium`: `2-12周`
+- `long`: `1-3年`
+- `not_applicable`: `不适用`
+
 Allowed source confidence values:
 
 - `high`

docs/notification_format.zh-CN.md

@@ -35,8 +35,10 @@ recommendation_tier
 recommendation_tier_label
 primary_horizon
 primary_horizon_label
+primary_horizon_window
 horizon_note
 suitable_horizons[]
+suitable_horizon_windows{}
 strategy_style
 score
 evidence_score
@@ -67,12 +69,12 @@ Telegram 适合中等长度，最多展示前 3-5 个推荐：
 ```text
 Quant Model Recommendations | Weekly | 2026-05-30
 
-1. EVT1 | 一级推荐 | 重点推荐 | 中线 | 来源中 | score 0.85
+1. EVT1 | 一级推荐 | 重点推荐 | 中线(2-12周) | 来源中 | score 0.85
    理由：公开事件 + 披露证据 + AI shadow 仍在观察区间。
-   周期：事件驱动以中线验证为主；短线只适合观察催化反应，波动和反转风险更高。
+   周期：事件驱动主周期为2-12周；1-10个交易日只适合观察催化反应，波动和反转风险更高。
    风险：AI 数据缺口未完全解决。
 
-2. EVT2 | 一级推荐 | 重点推荐 | 中线 | 来源高 | score 0.83
+2. EVT2 | 一级推荐 | 重点推荐 | 中线(2-12周) | 来源高 | score 0.83
    理由：政策资本事件触发，来源置信度高。
    风险：需要复核估值、财报日和最新价格行为。
 
@@ -115,8 +117,14 @@ Subject: Quant Model Recommendations Weekly Review - 2026-05-30
 ## 周期原则
 
 - 主周期只给一个：短线、中线、长线或不适用。
+- 周期窗口必须固定显示：
+  - 短线：`1-10个交易日`
+  - 中线：`2-12周`
+  - 长线：`1-3年`
 - 事件驱动默认以中线为主，短线只作为催化反应观察，不作为自动交易触发。
-- 长线推荐需要更多基本面、AI shadow 和事件持续性支持。
+- 长线推荐主窗口为 `1-3年`，需要更多基本面、AI shadow 和事件持续性支持；超过 3 年应通过年度复盘确认逻辑仍成立。
+- `primary_horizon_window` 必须给出主周期时间范围。
+- `suitable_horizon_windows` 必须给出所有可观察周期的时间范围。
 - `horizon_note` 必须解释为什么适合该周期，以及短线风险在哪里。
 
 ## 禁用表达

src/quant_advisor_research/advisory_report.py

@@ -43,6 +43,13 @@
     "negative": -3,
 }
 
+HORIZON_WINDOWS = {
+    "short": "1-10个交易日",
+    "medium": "2-12周",
+    "long": "1-3年",
+    "not_applicable": "不适用",
+}
+
 
 @dataclass(frozen=True)
 class Event:
@@ -151,12 +158,12 @@ def horizon_fit(style: str, rating: str) -> tuple[str, list[str], str, str]:
     if rating in {"verify_source", "defer", "monitor"}:
         return "not_applicable", ["not_applicable"], "不适用", "该项不是当前推荐，仅用于来源核验、风险暂缓或持续监控。"
     if style == "event_driven":
-        return "medium", ["short", "medium"], "中线", "事件驱动以中线验证为主；短线只适合观察催化反应，波动和反转风险更高。"
+        return "medium", ["short", "medium"], "中线", "事件驱动主周期为2-12周；1-10个交易日只适合观察催化反应，波动和反转风险更高。"
     if style in {"long_horizon_growth", "value_quality"}:
-        return "long", ["medium", "long"], "长线", "更适合用中长期基本面和趋势验证，不适合按短线噪声频繁切换。"
+        return "long", ["medium", "long"], "长线", "主周期为1-3年，更适合用基本面、产业趋势和事件持续性验证；超过3年需要年度复盘确认逻辑仍成立。"
     if style == "macro_context":
-        return "medium", ["medium"], "中线", "宏观和政策背景更适合中线观察，需要结合市场环境复核。"
-    return "medium", ["medium"], "中线", "默认按中线研究处理，等待更多证据后再调整周期判断。"
+        return "medium", ["medium"], "中线", "主周期为2-12周，宏观和政策背景需要结合市场环境复核。"
+    return "medium", ["medium"], "中线", "默认按2-12周中线研究处理，等待更多证据后再调整周期判断。"
 
 
 def rating_label(rating: str) -> str:
@@ -273,6 +280,8 @@ def build_recommendation(
     style = strategy_style(item, events, ai_bias)
     score = round(clamp((evidence_score - risk_score + 8) / 24, 0.05, 0.85), 2)
     primary_horizon, suitable_horizons, primary_horizon_label, horizon_note = horizon_fit(style, rating)
+    primary_horizon_window = HORIZON_WINDOWS[primary_horizon]
+    suitable_horizon_windows = {horizon: HORIZON_WINDOWS[horizon] for horizon in suitable_horizons}
     confidence, confidence_label = source_confidence(events)
     tier, tier_label = recommendation_tier(rating, score, confidence)
 
@@ -305,8 +314,10 @@ def build_recommendation(
         "recommendation_tier_label": tier_label,
         "primary_horizon": primary_horizon,
         "primary_horizon_label": primary_horizon_label,
+        "primary_horizon_window": primary_horizon_window,
         "horizon_note": horizon_note,
         "suitable_horizons": suitable_horizons,
+        "suitable_horizon_windows": suitable_horizon_windows,
         "strategy_style": style,
         "score": score,
         "evidence_score": int(evidence_score),
@@ -371,7 +382,7 @@ def build_advisory_report(
     recommendations = recommendations[:max_candidates]
 
     report = {
-        "schema_version": "4",
+        "schema_version": "5",
         "as_of": as_of_date.isoformat(),
         "generated_at": utc_now_iso(),
         "mode": "model_recommendations",
@@ -430,7 +441,11 @@ def render_markdown(report: dict[str, Any]) -> str:
                 f"### {rec['symbol']} - {rec['rating_label']}",
                 "",
                 f"- 推荐层级: `{rec['recommendation_tier_label']}`",
-                f"- 适合周期: `{rec['primary_horizon_label']}`",
+                f"- 适合周期: `{rec['primary_horizon_label']}({rec['primary_horizon_window']})`",
+                "- 可观察周期: "
+                + ", ".join(
+                    f"`{horizon}={window}`" for horizon, window in rec["suitable_horizon_windows"].items()
+                ),
                 f"- 周期说明: {rec['horizon_note']}",
                 f"- Strategy style: `{rec['strategy_style']}`",
                 f"- Model score: `{rec['score']}`",

src/quant_advisor_research/contracts.py

@@ -97,8 +97,8 @@ def validate_advisory_report(payload: Mapping[str, Any]) -> None:
     if missing:
         raise AdvisoryValidationError(f"missing required keys: {', '.join(missing)}")
 
-    if payload["schema_version"] != "4":
-        raise AdvisoryValidationError("schema_version must be '4'")
+    if payload["schema_version"] != "5":
+        raise AdvisoryValidationError("schema_version must be '5'")
     _require_iso_date(payload["as_of"], "as_of")
     _require_iso_datetime(payload["generated_at"], "generated_at")
     if payload["mode"] != "model_recommendations":
@@ -127,8 +127,10 @@ def validate_advisory_report(payload: Mapping[str, Any]) -> None:
             "recommendation_tier_label",
             "primary_horizon",
             "primary_horizon_label",
+            "primary_horizon_window",
             "horizon_note",
             "suitable_horizons",
+            "suitable_horizon_windows",
             "strategy_style",
             "score",
             "evidence_score",
@@ -152,10 +154,18 @@ def validate_advisory_report(payload: Mapping[str, Any]) -> None:
         if rec["primary_horizon"] not in ALLOWED_HORIZONS:
             raise AdvisoryValidationError(f"recommendations[{index}].primary_horizon is not allowed")
         _require_string(rec["primary_horizon_label"], f"recommendations[{index}].primary_horizon_label")
+        _require_string(rec["primary_horizon_window"], f"recommendations[{index}].primary_horizon_window")
         _require_string(rec["horizon_note"], f"recommendations[{index}].horizon_note")
         horizons = _require_sequence(rec["suitable_horizons"], f"recommendations[{index}].suitable_horizons")
         if any(horizon not in ALLOWED_HORIZONS for horizon in horizons):
             raise AdvisoryValidationError(f"recommendations[{index}].suitable_horizons contains an unsupported horizon")
+        horizon_windows = _require_mapping(
+            rec["suitable_horizon_windows"], f"recommendations[{index}].suitable_horizon_windows"
+        )
+        for horizon in horizons:
+            _require_string(
+                horizon_windows.get(horizon), f"recommendations[{index}].suitable_horizon_windows.{horizon}"
+            )
         if rec["strategy_style"] not in ALLOWED_STRATEGY_STYLES:
             raise AdvisoryValidationError(f"recommendations[{index}].strategy_style is not allowed")
         _require_number_0_1(rec["score"], f"recommendations[{index}].score")

src/quant_advisor_research/publisher.py

@@ -53,6 +53,7 @@ def render_report_html(report: dict[str, Any]) -> str:
               </header>
               <dl>
                 <div><dt>Horizon</dt><dd>{html.escape(rec['primary_horizon_label'])}</dd></div>
+                <div><dt>Window</dt><dd>{html.escape(rec['primary_horizon_window'])}</dd></div>
                 <div><dt>Tier</dt><dd>{html.escape(rec['recommendation_tier_label'])}</dd></div>
                 <div><dt>Source</dt><dd>{html.escape(rec['source_confidence_label'])}</dd></div>
                 <div><dt>Style</dt><dd>{html.escape(rec['strategy_style'])}</dd></div>

tests/test_advisory_report.py

@@ -75,7 +75,9 @@ def test_high_evidence_events_generate_recommendations_with_horizon() -> None:
     assert by_symbol["EVT1"]["recommendation_tier"] == "tier_1"
     assert by_symbol["EVT1"]["recommendation_tier_label"] == "一级推荐"
     assert by_symbol["EVT1"]["primary_horizon"] in {"short", "medium", "long"}
-    assert "短线" in by_symbol["EVT1"]["horizon_note"]
+    assert by_symbol["EVT1"]["primary_horizon_window"] == "2-12周"
+    assert by_symbol["EVT1"]["suitable_horizon_windows"]["short"] == "1-10个交易日"
+    assert "1-10个交易日" in by_symbol["EVT1"]["horizon_note"]
     assert by_symbol["EVT1"]["source_confidence"] == "medium"
     assert by_symbol["EVT1"]["reasons"]
 
@@ -118,6 +120,22 @@ def test_mixed_confidence_recommendation_is_not_tier_one(tmp_path: Path) -> None
     assert rec["recommendation_tier"] == "tier_2"
 
 
+def test_long_horizon_window_is_measured_in_years() -> None:
+    report = build_advisory_report(
+        as_of="2026-05-30",
+        cadence="weekly",
+        political_events_path=ROOT / "examples/political_events.example.csv",
+        political_watchlist_path=ROOT / "examples/political_watchlist.example.csv",
+        ai_signal_path=ROOT / "examples/ai_long_horizon_signal.example.json",
+    )
+
+    by_symbol = {item["symbol"]: item for item in report["recommendations"]}
+
+    assert by_symbol["IDX1"]["primary_horizon"] == "long"
+    assert by_symbol["IDX1"]["primary_horizon_window"] == "1-3年"
+    assert "超过3年" in by_symbol["IDX1"]["horizon_note"]
+
+
 def test_contract_rejects_execution_enabled_report() -> None:
     report = build_advisory_report(
         as_of="2026-05-30",