Clarify advisory stock pool format

Author: Pigbibi

README.md

@@ -179,17 +179,17 @@ review_checklist[]
 ```
 
 `theme_first_candidates[]` is an optional display section derived from the
-theme momentum snapshot. It ranks symbols inside strong themes by symbol
-momentum first, then shows whether each candidate already has event confirmation
-or remains a theme-only candidate. It is still research-only and must not encode
-orders, target weights, or account-level advice.
+theme momentum snapshot. Public renderers present it as a 5-10 name "重点股票池":
+industry/theme background, why the name entered the pool, event-confirmation
+state, and key risks. It is still research-only and must not encode orders,
+target weights, or account-level advice.
 
 Default horizon windows:
 
 - short: `1-10 trading days`
 - medium: `2-12 weeks`
 - long: `1-3 years`
-- not_applicable: source check, defer, or monitor only
+- not_applicable: source check, defer, or background tracking only
 
 ## Versioning
 
@@ -242,10 +242,11 @@ python scripts/build_advisory_report.py \
 ```
 
 Theme momentum is display-first context: it highlights strong themes and creates
-a `theme_first_candidates[]` section so AI/high-tech candidates are visible even
-when stable event evidence is still pending. It does not change recommendation
-ratings, scores, allocations, or execution policy. Workflows skip the section
-when the snapshot file is absent.
+a `theme_first_candidates[]` stock-pool section so AI/high-tech candidates are
+visible with industry/theme background and reasons even when stable event
+evidence is still pending. It does not change recommendation ratings, scores,
+allocations, or execution policy. Workflows skip the section when the snapshot
+file is absent.
 
 Yahoo chart downloads are only a temporary fallback.  Do not rely on random free
 proxy pools for the stable pipeline; prefer audited price snapshots, cache files,

README.zh-CN.md

@@ -35,7 +35,7 @@ python scripts/build_advisory_report.py \
 输出包括：
 
 - 推荐标的
-- 推荐等级：重点推荐、观察、先核验来源、暂缓、监控
+- 推荐等级：重点推荐、观察、先核验来源、暂缓、背景跟踪
 - 推荐层级：一级推荐、二级推荐、观察名单、来源核验
 - 适合周期：短线、中线、长线，并明确时间窗口
 - 周期窗口：短线=1-10个交易日，中线=2-12周，长线=1-3年
@@ -158,7 +158,8 @@ python scripts/build_advisory_report.py \
   --output-md data/output/advisory_report.example.md
 ```
 
-主题动量会生成 `theme_first_candidates[]`，让 AI / 高科技等强主题里的候选标的先展示出来。
+主题动量会生成 `theme_first_candidates[]`，公开页面会把它展示为“本期重点股票池”。
+股票池每期保留 5-10 个股票/公司标的，说明行业/主题背景、为什么入选、事件确认状态和主要风险。
 这些候选按主题和个股动量排序，并标明是否已有事件确认；但它们仍然不直接改变推荐评级、分数、仓位或执行状态。
 线上 workflow 如果找不到 `data/output/theme_momentum_snapshot.json`，会自动跳过这个展示区块。
 

docs/advisory_contract.md

@@ -70,6 +70,9 @@ Allowed ratings:
 - `defer`
 - `monitor`
 
+Public Chinese renderers label `monitor` as `背景跟踪` to avoid implying an
+actionable monitoring instruction. It means context-only and not recommended.
+
 Allowed recommendation tiers:
 
 - `tier_1`
@@ -116,9 +119,10 @@ The contract intentionally rejects account-action fields such as `target_weight`
 ## Theme-first Candidate
 
 `theme_first_candidates` is optional and is derived from the theme momentum
-snapshot. It exists to make strong-theme candidates visible before the
-event-confirmed recommendation list. It is still research-only and must not
-contain account-action fields.
+snapshot. Public renderers present it as a 5-10 name stock pool with
+industry/theme background, reasons, event confirmation, and risks. It exists to
+make strong-theme candidates visible before the event-confirmed recommendation
+list. It is still research-only and must not contain account-action fields.
 
 Important fields:
 
@@ -128,10 +132,13 @@ symbol
 candidate_type = theme_first
 primary_theme_id
 primary_theme_name
+industry_background
 symbol_momentum_score
 advisor_status
 source_confirmation
 theme_ids
+recommendation_summary
+risk_summary
 reasons
 risk_notes
 ```

docs/data_factor_roadmap.zh-CN.md

@@ -164,7 +164,8 @@ Crypto 可作为跨资产风险情绪参考，但暂时不应混入 US equity 
 ## 低风险实施顺序
 
 1. 先让 `QuantAdvisorResearch` 把主题动量放到报告前面：
-   - 新增 `theme_first_candidates[]`。
+   - 新增 `theme_first_candidates[]`，公开展示为“本期重点股票池”。
+   - 每期保留 5-10 个股票/公司标的，说明行业/主题背景、入选原因、事件确认和主要风险。
    - 按主题和个股动量排序，优先展示 AI / 高科技等强主题候选。
    - 事件证据只作为确认项，不再让事件股默认压过强主题候选。
 
@@ -233,6 +234,6 @@ config/symbol_theme_exposure.csv
 
 1. theme membership 先固定，再观察后续表现。
 2. AI 只能输出 `theme_bias` 和 shadow context，不能输出目标仓位。
-3. Advisor 可以把主题 bias 和主题动量作为“主题优先候选”展示入口；一级事件确认推荐仍需要事件证据和来源质量支撑。
+3. Advisor 可以把主题 bias 和主题动量作为“本期重点股票池”展示入口；一级事件确认推荐仍需要事件证据和来源质量支撑。
 4. 每次规则、taxonomy、universe 变更都要记录版本，后续 walk-forward 只能 replay 已保存 artifact。
 5. 不因为 MU、INTC、DELL 或任何短期热门标的临时调权重；如果它们长期有 SEC/IR/政策/需求证据，会通过固定规则自然上升。

docs/notification_format.md

@@ -31,10 +31,11 @@ account suitability, or any account-specific allocation advice.
 主题动量：
 - #1 hbm_memory 分数=2.16 标的=MU
 
-主题优先候选：
-- #1 MU | hbm_memory | 动量=2.93 | 主题候选 | 待事件确认
+本期重点股票池（5-10只，非个性化，不等于买入）：
+- #1 MU | 科技 / HBM and memory cycle | 近3月 +135.6% | 事件：待事件确认 | 结论：主题候选
+  为什么：属于科技 / HBM and memory cycle，主主题排名 #1；个股动量 2.93，近3个月 +135.6%。
 
-推荐摘要：
+推荐/观察摘要：
 - VRT | 二级推荐 | 重点推荐 | 中线 | 分数=0.72
 
 说明：非个性化模型输出；不包含下单、仓位配置或账户级建议。

docs/notification_format.zh-CN.md

@@ -76,10 +76,11 @@ Telegram 适合中等长度，最多展示前 3-5 个推荐：
 主题动量：
 - #1 hbm_memory 分数=2.16 标的=MU
 
-主题优先候选：
-- #1 MU | hbm_memory | 动量=2.93 | 主题候选 | 待事件确认
+本期重点股票池（5-10只，非个性化，不等于买入）：
+- #1 MU | 科技 / HBM and memory cycle | 近3月 +135.6% | 事件：待事件确认 | 结论：主题候选
+  为什么：属于科技 / HBM and memory cycle，主主题排名 #1；个股动量 2.93，近3个月 +135.6%。
 
-推荐摘要：
+推荐/观察摘要：
 - EVT1 | 一级推荐 | 重点推荐 | 中线 | 分数=0.85
 - EVT2 | 一级推荐 | 重点推荐 | 中线 | 分数=0.83
 
@@ -109,7 +110,7 @@ Subject: 量化模型推荐周度复盘 - 2026-05-30
 - `watch` / 观察：有线索但还需要更多事件、基本面或价格证据。
 - `verify_source` / 先核验来源：低置信来源，不应升级为推荐。
 - `defer` / 暂缓：风险或负面 shadow context 优先。
-- `monitor` / 监控：只保留上下文，不进入推荐区。
+- `monitor` / 背景跟踪：只保留上下文，不进入推荐区。
 
 ## 推荐层级
 
@@ -118,7 +119,7 @@ Subject: 量化模型推荐周度复盘 - 2026-05-30
 - `watchlist` / 观察名单：保留观察，不作为重点推荐。
 - `source_check` / 来源核验：先确认来源再决定是否升级。
 - `defer` / 暂缓：风险优先。
-- `monitor` / 监控：上下文保留。
+- `monitor` / 背景跟踪：上下文保留，不是推荐。
 
 ## 周期原则
 
@@ -154,4 +155,4 @@ Subject: 量化模型推荐周度复盘 - 2026-05-30
 - RSS：`scripts/publish_advisory_site.py` 生成 `feed.xml`。
 - Telegram：可选。如果仓库 secrets 配置了 `TELEGRAM_BOT_TOKEN` 和 `TELEGRAM_CHAT_ID`，`scripts/notify_advisory_telegram.py` 会在 Pages 部署成功后发送短摘要；如果缺少任一 secret，会跳过通知但不让发布失败。
 
-通知仍然只能包含标的、主题优先候选、推荐层级、周期、来源事件数、主题动量、模型分数、理由、风险和完整报告链接；不能包含订单、目标仓位、目标股数、账户适当性或账户级配置建议。
+通知仍然只能包含标的、重点股票池、行业/主题背景、推荐层级、周期、来源事件数、主题动量、模型分数、理由、风险和完整报告链接；不能包含订单、目标仓位、目标股数、账户适当性或账户级配置建议。

src/quant_advisor_research/advisory_report.py

@@ -58,6 +58,30 @@
     "monthly": "月度",
 }
 
+SECTOR_LABELS_ZH = {
+    "technology": "科技",
+    "energy": "能源",
+    "financials": "金融",
+    "healthcare": "医疗",
+    "industrials": "工业",
+    "consumer": "消费",
+    "communication_services": "通信服务",
+    "utilities": "公用事业",
+}
+
+EXCLUDED_THEME_PICK_SYMBOLS = {
+    "DIA",
+    "IWM",
+    "QQQ",
+    "SMH",
+    "SOXL",
+    "SOXX",
+    "SPY",
+    "TQQQ",
+    "XLE",
+    "XLK",
+}
+
 
 @dataclass(frozen=True)
 class Event:
@@ -196,6 +220,23 @@ def as_float(value: Any, *, default: float = 0.0) -> float:
         return default
 
 
+def display_number(value: Any, *, digits: int = 2) -> str:
+    if value in {None, ""}:
+        return "无"
+    return f"{as_float(value):.{digits}f}"
+
+
+def display_percent(value: Any, *, digits: int = 1) -> str:
+    if value in {None, ""}:
+        return "无"
+    return f"{as_float(value) * 100:+.{digits}f}%"
+
+
+def sector_label(value: Any) -> str:
+    text = str(value or "").strip()
+    return SECTOR_LABELS_ZH.get(text, text or "未分类")
+
+
 def normalize_ai_mapping(mapping: Any) -> dict[str, Any]:
     if not isinstance(mapping, dict):
         return {}
@@ -263,7 +304,7 @@ def strategy_style(item: WatchlistItem | None, events: list[Event], ai_bias: str
 
 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"], "不适用", "该项不是当前推荐，仅用于来源核验、风险暂缓或持续监控。"
+        return "not_applicable", ["not_applicable"], "不适用", "该项不是当前推荐，仅用于来源核验、风险暂缓或背景跟踪。"
     if style == "event_driven":
         return "medium", ["short", "medium"], "中线", "事件驱动主周期为2-12周；1-10个交易日只适合观察催化反应，波动和反转风险更高。"
     if style in {"long_horizon_growth", "value_quality"}:
@@ -279,7 +320,7 @@ def rating_label(rating: str) -> str:
         "watch": "观察",
         "verify_source": "先核验来源",
         "defer": "暂缓",
-        "monitor": "监控",
+        "monitor": "背景跟踪",
     }
     return labels[rating]
 
@@ -310,14 +351,14 @@ def recommendation_tier(rating: str, score: float, confidence: str) -> tuple[str
         return "source_check", "来源核验"
     if rating == "defer":
         return "defer", "暂缓"
-    return "monitor", "监控"
+    return "monitor", "背景跟踪"
 
 
 def build_theme_first_candidates(
     theme_momentum: dict[str, Any] | None,
     recommendations: list[dict[str, Any]],
     *,
-    max_candidates: int = 10,
+    max_candidates: int = 8,
     max_themes: int = 5,
 ) -> list[dict[str, Any]]:
     if not theme_momentum:
@@ -331,12 +372,15 @@ def build_theme_first_candidates(
         theme_rank = int(as_float(theme.get("rank"), default=999))
         theme_id = str(theme.get("theme_id", ""))
         theme_name = str(theme.get("theme_name", ""))
+        theme_sector = str(theme.get("sector", ""))
         theme_score = round(as_float(theme.get("momentum_score")), 6)
         theme_breadth = round(as_float(theme.get("breadth_3m")), 6)
         for item in theme.get("top_symbols", []):
             if not isinstance(item, dict) or not item.get("symbol"):
                 continue
             symbol = str(item["symbol"]).upper()
+            if symbol in EXCLUDED_THEME_PICK_SYMBOLS:
+                continue
             symbol_score = round(as_float(item.get("momentum_score")), 6)
             candidate = by_symbol.setdefault(
                 symbol,
@@ -351,6 +395,7 @@ def build_theme_first_candidates(
                     "best_theme_rank": theme_rank,
                     "primary_theme_id": theme_id,
                     "primary_theme_name": theme_name,
+                    "primary_theme_sector": theme_sector,
                     "primary_theme_score": theme_score,
                     "primary_theme_breadth_3m": theme_breadth,
                     "theme_ids": [],
@@ -366,6 +411,7 @@ def build_theme_first_candidates(
                 candidate["best_theme_rank"] = theme_rank
                 candidate["primary_theme_id"] = theme_id
                 candidate["primary_theme_name"] = theme_name
+                candidate["primary_theme_sector"] = theme_sector
                 candidate["primary_theme_score"] = theme_score
                 candidate["primary_theme_breadth_3m"] = theme_breadth
             if theme_id and theme_id not in candidate["theme_ids"]:
@@ -374,6 +420,7 @@ def build_theme_first_candidates(
                     {
                         "theme_id": theme_id,
                         "theme_name": theme_name,
+                        "sector": theme_sector,
                         "rank": theme_rank,
                         "momentum_score": theme_score,
                         "breadth_3m": theme_breadth,
@@ -402,7 +449,7 @@ def build_theme_first_candidates(
                 source_confirmation = f"已有{rec.get('source_confidence_label', '')}置信事件确认"
         theme_ids = candidate.get("theme_ids", [])
         reasons = [
-            "主题动量排序靠前，适合放入本期主题优先候选池。",
+            "主题和个股动量靠前，适合放入本期主题优先候选池。",
             (
                 f"主主题 #{candidate.get('best_theme_rank')} {candidate.get('primary_theme_id')} "
                 f"主题分数={candidate.get('primary_theme_score')}，3个月广度={candidate.get('primary_theme_breadth_3m')}。"
@@ -411,9 +458,23 @@ def build_theme_first_candidates(
         ]
         if len(theme_ids) > 1:
             reasons.append(f"同时暴露于多个强主题：{', '.join(theme_ids)}。")
+        industry_background = (
+            f"{sector_label(candidate.get('primary_theme_sector'))} / "
+            f"{candidate.get('primary_theme_name') or candidate.get('primary_theme_id')}"
+        )
+        recommendation_summary = (
+            f"属于{industry_background}，主主题排名 #{candidate.get('best_theme_rank')}；"
+            f"个股动量 {display_number(candidate.get('symbol_momentum_score'))}，"
+            f"近3个月 {display_percent(candidate.get('return_3m'))}。"
+        )
+        if len(theme_ids) > 1:
+            recommendation_summary += f" 同时覆盖 {', '.join(theme_ids[:3])} 等主题。"
+        risk_summary = "需复核估值、财报、回撤、流动性和稳定事件证据。"
+        if source_confirmation != "待事件确认":
+            risk_summary = "已有事件确认，但仍需复核估值、财报、回撤和流动性。"
         risk_notes = [
             "该候选来自主题和价格动量排序，不代表个性化建议或下单信号。",
-            "升级为正式推荐前，需要继续复核估值、财报、回撤、流动性和稳定事件证据。",
+            risk_summary,
         ]
         if rec and rec.get("risk_notes"):
             risk_notes.append(str(rec["risk_notes"][0]))
@@ -423,6 +484,9 @@ def build_theme_first_candidates(
                 "rank": index,
                 "advisor_status": advisor_status,
                 "source_confirmation": source_confirmation,
+                "industry_background": industry_background,
+                "recommendation_summary": recommendation_summary,
+                "risk_summary": risk_summary,
                 "reasons": dedupe(reasons),
                 "risk_notes": dedupe(risk_notes),
             }
@@ -691,25 +755,24 @@ def render_markdown(report: dict[str, Any]) -> str:
     ]
     theme_candidates = report.get("theme_first_candidates", [])
     if theme_candidates:
-        lines.extend(["## 主题优先候选", ""])
-        lines.append("- 说明: 该列表按主题/个股动量排序，用于突出 AI 和高科技等强主题候选；不是下单或仓位建议。")
+        lines.extend(["## 本期重点股票池", ""])
+        lines.append("- 先看这里: 每期选出 5-10 个股票/公司标的，说明行业主题、入选理由、事件确认和主要风险。")
+        lines.append("- 边界: 这是非个性化模型股票池，不是买入清单；`待事件确认` 表示稳定事件证据还不足。")
         lines.append("")
         for candidate in theme_candidates:
             lines.extend(
                 [
                     f"### #{candidate.get('rank')} {candidate.get('symbol')} - {candidate.get('advisor_status')}",
                     "",
-                    f"- 主主题: `{candidate.get('primary_theme_id')}` / {candidate.get('primary_theme_name')}",
-                    f"- 个股动量分数: `{candidate.get('symbol_momentum_score')}`",
-                    f"- 3个月收益: `{candidate.get('return_3m', '')}`",
+                    f"- 行业/主题: {candidate.get('industry_background')}",
+                    f"- 主主题: `{candidate.get('primary_theme_id')}`",
+                    f"- 个股动量分数: `{display_number(candidate.get('symbol_momentum_score'))}`",
+                    f"- 近3个月: `{display_percent(candidate.get('return_3m'))}`",
                     f"- 来源确认: `{candidate.get('source_confirmation')}`",
-                    f"- 相关主题: `{', '.join(candidate.get('theme_ids', []))}`",
-                    "- 理由:",
+                    f"- 为什么入选: {candidate.get('recommendation_summary')}",
+                    f"- 主要风险: {candidate.get('risk_summary')}",
                 ]
             )
-            lines.extend(f"  - {reason}" for reason in candidate.get("reasons", []))
-            lines.append("- 风险:")
-            lines.extend(f"  - {risk}" for risk in candidate.get("risk_notes", []))
             lines.append("")
     theme_momentum = report.get("theme_momentum", {})
     if theme_momentum.get("available"):