fix(review-feedback-1245): address latest review comments

Author: ZhuLinsen

docs/full-guide.md

@@ -1011,6 +1011,7 @@ python main.py --debug
 ## 分析决策可操作性
 
 个股报告的操作建议会结合支撑位、压力位、量能/筹码、主力资金流向和风险事件进行校准，避免仅因单日涨跌或评分跨线在“买入/卖出”之间剧烈切换。若价格处在支撑与压力之间且资金流不明确，报告会优先给出“持有、震荡观望、洗盘观察”等中性可执行建议；只有接近支撑确认、有效突破压力且量价/资金配合时才给出买入，跌破关键支撑或主力资金持续流出时才给出卖出/减仓。
+该项调整仅影响决策后处理逻辑，不会变更 LLM 模型、LiteLLM 路由、Provider/Key 的配置与兼容语义。
 
 ## 回测功能
 
@@ -1030,7 +1031,7 @@ python main.py --debug
 |---------|---------|---------|---------|
 | 买入/加仓/strong buy | long | up | 涨幅 ≥ 中性带 |
 | 卖出/减仓/strong sell | cash | down | 跌幅 ≥ 中性带 |
-| 持有/hold | long | not_down | 未显著下跌 |
+| 持有/持有观察/震荡观望/洗盘观察/hold/hold and watch/range-bound watch/shakeout watch | long | not_down | 未显著下跌 |
 | 观望/等待/wait | cash | flat | 价格在中性带内 |
 
 ### 配置

docs/full-guide_EN.md

@@ -857,6 +857,7 @@ You can tune the behavior in `.env`:
 ## Decision Actionability
 
 Single-stock reports calibrate operation advice with support/resistance, volume/chip context, main-force capital flow, and risk events. This reduces direct buy/sell flips caused only by one-day price movement or score thresholds. When price is between support and resistance and capital flow is unclear, the report prefers neutral actionable wording such as hold, range-bound watch, or shakeout watch. Buy calls require support confirmation or a valid resistance breakout with volume/capital-flow confirmation; sell/reduce calls require support failure, sustained outflow, or clearly elevated risk.
+This post-processing update only adjusts advisory wording and stability logic and does not change the configured LLM model/provider routing semantics (including LiteLLM, providers, or API model settings).
 
 ## Backtesting
 
@@ -876,7 +877,7 @@ The backtesting module automatically validates historical AI analysis records ag
 |-----------------|----------|-------------------|---------------|
 | Buy / Add / Strong Buy | long | up | Return >= neutral band |
 | Sell / Reduce / Strong Sell | cash | down | Decline >= neutral band |
-| Hold | long | not_down | No significant decline |
+| Hold / Hold and Watch / Range-bound Watch / Shakeout Watch / Hold and watch | long | not_down | No significant decline |
 | Wait / Observe | cash | flat | Price within neutral band |
 
 ### Configuration

src/analyzer.py

@@ -252,6 +252,30 @@ def _is_value_placeholder(v: Any) -> bool:
     return s in ("", "n/a", "na", "数据缺失", "未知", "data unavailable", "unknown", "tbd")
 
 
+_RISK_WARNING_PLACEHOLDER_TEXTS = {
+    "",
+    "n/a",
+    "na",
+    "none",
+    "null",
+    "unknown",
+    "tbd",
+    "暂无",
+    "待补充",
+    "数据缺失",
+    "未知",
+    "无",
+}
+
+
+def _is_meaningful_text(value: Any) -> bool:
+    text = str(value).strip() if value is not None else ""
+    if not text:
+        return False
+    lowered = text.strip().lower()
+    return lowered not in _RISK_WARNING_PLACEHOLDER_TEXTS
+
+
 def _safe_float(v: Any, default: float = 0.0) -> float:
     """Safely convert to float; return default on failure. Private helper for chip fill."""
     if v is None:
@@ -671,6 +695,8 @@ def stabilize_decision_with_structure(
             and support * 1.03 < current_price < resistance * 0.97
         )
 
+        has_significant_risk = _has_structural_risk_alert(result)
+
         if decision_type == "buy":
             if near_resistance and flow_bias != "inflow":
                 _downgrade_to_structural_hold(
@@ -706,7 +732,7 @@ def stabilize_decision_with_structure(
                     flow_bias=flow_bias,
                 )
         elif decision_type == "sell":
-            if near_support and flow_bias != "outflow":
+            if near_support and (flow_bias != "outflow") and not has_significant_risk:
                 _downgrade_to_structural_hold(
                     result,
                     language,
@@ -717,7 +743,7 @@ def stabilize_decision_with_structure(
                     resistance=resistance,
                     flow_bias=flow_bias,
                 )
-            elif flow_bias == "inflow" and not broke_support:
+            elif flow_bias == "inflow" and not broke_support and not has_significant_risk:
                 _downgrade_to_structural_hold(
                     result,
                     language,
@@ -752,10 +778,44 @@ def stabilize_decision_with_structure(
                     resistance=resistance,
                     flow_bias=flow_bias,
                 )
+        _sync_stability_dashboard_fields(result)
     except Exception as exc:
         logger.warning("[decision_stability] skipped: %s", exc)
 
 
+def _has_structural_risk_alert(result: "AnalysisResult") -> bool:
+    dashboard = result.dashboard if isinstance(result.dashboard, dict) else {}
+
+    risk_text = getattr(result, "risk_warning", "")
+    if _is_meaningful_text(risk_text):
+        return True
+
+    intelligence = dashboard.get("intelligence") if isinstance(dashboard, dict) else None
+    if isinstance(intelligence, dict):
+        risk_alerts = intelligence.get("risk_alerts")
+        if isinstance(risk_alerts, str):
+            if _is_meaningful_text(risk_alerts):
+                return True
+        elif isinstance(risk_alerts, (list, tuple, set)):
+            if any(_is_meaningful_text(item) for item in risk_alerts):
+                return True
+
+    core_conclusion = dashboard.get("core_conclusion") if isinstance(dashboard, dict) else None
+    if isinstance(core_conclusion, dict):
+        signal_type = str(core_conclusion.get("signal_type", "")).strip()
+        if "风险" in signal_type:
+            return True
+    return False
+
+
+def _sync_stability_dashboard_fields(result: "AnalysisResult") -> None:
+    dashboard = result.dashboard if isinstance(result.dashboard, dict) else {}
+    result.dashboard = dashboard
+    dashboard["sentiment_score"] = getattr(result, "sentiment_score", None)
+    dashboard["operation_advice"] = getattr(result, "operation_advice", None)
+    dashboard["decision_type"] = getattr(result, "decision_type", None)
+
+
 def _as_dict_for_decision_guard(value: Any) -> Dict[str, Any]:
     if isinstance(value, dict):
         return value

src/core/backtest_engine.py

@@ -9,6 +9,7 @@
 
 from dataclasses import dataclass
 from datetime import date
+import re
 from typing import Any, Dict, Iterable, List, Optional, Protocol, Sequence
 
 
@@ -72,7 +73,13 @@ class BacktestEngine:
     )
     _HOLD_KEYWORDS = (
         "持有",
+        "震荡观望",
+        "洗盘观察",
+        "持有观察",
         "hold",
+        "range-bound watch",
+        "shakeout watch",
+        "hold and watch",
     )
     _WAIT_KEYWORDS = (
         "观望",
@@ -109,7 +116,9 @@ def infer_position_recommendation(cls, operation_advice: Optional[str]) -> str:
         Priority: bearish/wait -> cash, bullish/hold -> long, unrecognized -> cash.
         """
         text = cls._normalize_text(operation_advice)
-        if cls._matches_intent(text, cls._BEARISH_KEYWORDS) or cls._matches_intent(text, cls._WAIT_KEYWORDS):
+        if cls._matches_intent(text, cls._BEARISH_KEYWORDS):
+            return "cash"
+        if cls._matches_intent(text, cls._WAIT_KEYWORDS):
             return "cash"
         if cls._matches_intent(text, cls._BULLISH_KEYWORDS) or cls._matches_intent(text, cls._HOLD_KEYWORDS):
             return "long"
@@ -363,14 +372,39 @@ def _matches_intent(cls, text: str, keywords: Sequence[str]) -> bool:
         if not text:
             return False
         for kw in keywords:
+            if not kw:
+                continue
             if text == kw:
                 return True
-        for kw in keywords:
-            idx = text.find(kw)
-            if idx == -1:
+
+            keyword = kw.lower().strip()
+            if not keyword:
                 continue
-            if not cls._is_negated(text[:idx]):
-                return True
+
+            # Use word-boundary matching for ASCII keywords to avoid
+            # false positives such as "watch" matching "wait".
+            if bool(re.search(r"[a-z]", keyword)):
+                match = re.search(
+                    rf"(?<![a-zA-Z0-9_]){re.escape(keyword)}(?![a-zA-Z0-9_])",
+                    text,
+                )
+                if not match:
+                    continue
+                if not cls._is_negated(text[: match.start()]):
+                    return True
+                continue
+
+            # For non-ASCII terms (Chinese), avoid matching fragments embedded
+            # in another Chinese word to reduce false positives.
+            if re.search(r"[\u4e00-\u9fff]", keyword):
+                match = re.search(
+                    rf"(?<![\u4e00-\u9fff]){re.escape(keyword)}(?![\u4e00-\u9fff])",
+                    text,
+                )
+                if match and not cls._is_negated(text[: match.start()]):
+                    return True
+                continue
+
         return False
 
     @classmethod

tests/test_agent_pipeline.py

@@ -1294,6 +1294,98 @@ def test_analyze_with_agent_uses_resolved_name_for_news_persistence(self):
             saved_kwargs = pipeline.db.save_news_intel.call_args.kwargs
             self.assertEqual(saved_kwargs["name"], "科创芯片ETF")
 
+    def test_analyze_with_agent_keeps_dashboard_top_level_fields_after_stability(self):
+        """Decision stability downgrade in agent flow should sync dashboard and top-level decision fields."""
+        with patch('src.core.pipeline.get_config') as mock_config, \
+             patch('src.core.pipeline.get_db'), \
+             patch('src.core.pipeline.DataFetcherManager'), \
+             patch('src.core.pipeline.GeminiAnalyzer'), \
+             patch('src.core.pipeline.NotificationService'), \
+             patch('src.core.pipeline.SearchService'), \
+             patch('src.agent.factory.build_agent_executor') as mock_build_executor:
+
+            mock_cfg = MagicMock()
+            mock_cfg.max_workers = 2
+            mock_cfg.agent_mode = True
+            mock_cfg.agent_max_steps = 10
+            mock_cfg.agent_skills = []
+            mock_cfg.bocha_api_keys = []
+            mock_cfg.tavily_api_keys = []
+            mock_cfg.brave_api_keys = []
+            mock_cfg.serpapi_keys = []
+            mock_cfg.searxng_base_urls = []
+            mock_cfg.searxng_public_instances_enabled = False
+            mock_cfg.news_max_age_days = 7
+            mock_cfg.enable_realtime_quote = True
+            mock_cfg.enable_chip_distribution = True
+            mock_cfg.realtime_source_priority = []
+            mock_cfg.save_context_snapshot = False
+            mock_cfg.report_language = "zh"
+            mock_cfg.agent_orchestrator_timeout_s = 600
+            mock_config.return_value = mock_cfg
+
+            from src.core.pipeline import StockAnalysisPipeline
+            from src.agent.executor import AgentResult
+            from src.enums import ReportType
+            from src.stock_analyzer import TrendAnalysisResult, TrendStatus, BuySignal
+            pipeline = StockAnalysisPipeline(config=mock_cfg)
+
+            agent_result = AgentResult(
+                success=True,
+                content="{}",
+                dashboard={
+                    "sentiment_score": 30,
+                    "trend_prediction": "震荡",
+                    "operation_advice": "卖出",
+                    "decision_type": "sell",
+                    "analysis_summary": "原始建议",
+                    "dashboard": {
+                        "core_conclusion": {"one_sentence": "初始结论"},
+                    },
+                },
+                provider="gemini",
+            )
+            mock_executor = MagicMock()
+            mock_executor.run.return_value = agent_result
+            mock_build_executor.return_value = mock_executor
+
+            trend_result = TrendAnalysisResult(
+                code="002812",
+                trend_status=TrendStatus.BULL,
+                buy_signal=BuySignal.SELL,
+                signal_score=30,
+                support_levels=[30.0],
+                resistance_levels=[34.0],
+            )
+            fundamental_context = {
+                "capital_flow": {
+                    "status": "ok",
+                    "data": {
+                        "stock_flow": {
+                            "main_net_inflow": 800_000,
+                        }
+                    },
+                }
+            }
+
+            result = pipeline._analyze_with_agent(
+                code="002812",
+                report_type=ReportType.SIMPLE,
+                query_id="q-agent-stability",
+                stock_name="恩捷股份",
+                realtime_quote={"price": 30.4, "change_pct": -2.1},
+                chip_data=None,
+                fundamental_context=fundamental_context,
+                trend_result=trend_result,
+            )
+
+            self.assertIsNotNone(result)
+            self.assertEqual(result.decision_type, "hold")
+            self.assertEqual(result.operation_advice, "洗盘观察")
+            self.assertEqual(result.dashboard.get("decision_type"), "hold")
+            self.assertEqual(result.dashboard.get("operation_advice"), "洗盘观察")
+            self.assertEqual(result.dashboard.get("sentiment_score"), result.sentiment_score)
+
 
 # ============================================================
 # Agent construction chain (real objects, mocked LLM)

tests/test_backtest_engine.py

@@ -75,6 +75,34 @@ def test_wait_maps_to_cash_and_flat_direction(self):
         self.assertEqual(res["direction_expected"], "flat")
         self.assertEqual(res["outcome"], "loss")
 
+    def test_range_bound_watch_is_treated_as_hold_long_path(self):
+        self.assertEqual(
+            BacktestEngine.infer_position_recommendation("震荡观望"),
+            "long",
+        )
+        self.assertEqual(
+            BacktestEngine.infer_direction_expected("Range-bound watch"),
+            "not_down",
+        )
+        self.assertEqual(
+            BacktestEngine.infer_position_recommendation("Range-bound watch"),
+            "long",
+        )
+
+    def test_shakeout_watch_is_treated_as_hold_long_path(self):
+        self.assertEqual(
+            BacktestEngine.infer_position_recommendation("洗盘观察"),
+            "long",
+        )
+        self.assertEqual(
+            BacktestEngine.infer_direction_expected("Shakeout watch"),
+            "not_down",
+        )
+        self.assertEqual(
+            BacktestEngine.infer_position_recommendation("Hold and watch"),
+            "long",
+        )
+
     def test_hold_win_when_flat(self):
         cfg = EvaluationConfig(eval_window_days=3, neutral_band_pct=2.0)
         bars = self._bars(date(2024, 1, 1), [100.5, 100.2, 101], highs=[101, 101, 101], lows=[99.8, 99.9, 100])

tests/test_decision_stability.py

@@ -179,6 +179,27 @@ def test_downgrades_sell_near_support_without_sustained_outflow() -> None:
     assert "不宜仅因单日下跌直接卖出" in result.risk_warning
 
 
+def test_preserves_sell_signal_when_significant_risk_exists_near_support() -> None:
+    result = _result(
+        decision_type="sell",
+        operation_advice="卖出",
+        score=30,
+        current_price=30.4,
+        change_pct=-2.1,
+    )
+    result.risk_warning = "重大利空消息：公司发布重大减持计划"
+    result.dashboard["intelligence"] = {"risk_alerts": ["股东高位减持预告"]}
+
+    stabilize_decision_with_structure(
+        result,
+        SimpleNamespace(support_levels=[30.0], resistance_levels=[34.0]),
+        _fund_flow(main=800_000, five_day=1_200_000),
+    )
+
+    assert result.decision_type == "sell"
+    assert result.operation_advice == "卖出"
+
+
 def test_refines_hold_pullback_near_support_as_shakeout_watch() -> None:
     result = _result(
         decision_type="hold",