feat: improve first-run configuration validation (#1558)

* feat: improve first-run configuration validation

* fix: clarify invalid LLM channel validation

Author: 123kaze

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+- [改进] 首次运行配置校验补充缺失 AI Key、空 STOCK_LIST、Telegram/邮件成对字段和 Webhook URL 前缀诊断。
 - [改进] AlphaSift 选股入口在 Web 侧边栏中移动到“问股”下方，贴近 Agent/研究辅助工作流。
 - [改进] Docker 镜像构建阶段预置默认 AlphaSift 适配层，与桌面发布包一样避免运行期额外安装。
 - [新功能] 新增默认关闭的 AlphaSift 选股页签，通过 `ALPHASIFT_ENABLED` 开启后经由稳定适配层读取策略并执行选股。

docs/full-guide.md

@@ -65,7 +65,7 @@ daily_stock_analysis/
 | `OPENAI_BASE_URL` | OpenAI 兼容 API 地址（如 `https://api.deepseek.com`） | 可选 |
 | `OPENAI_MODEL` | 模型名称（如 `gemini-3.1-pro-preview`、`deepseek-v4-flash`、`gpt-5.5`） | 可选 |
 
-> *注：以上模型 Key / 渠道至少配置一个；推荐优先从 Anspire 或 AIHubMix 这类一 Key 多模型服务开始。
+> *注：以上模型 Key / 渠道至少配置一个；推荐优先从 Anspire 或 AIHubMix 这类一 Key 多模型服务开始。启动时配置校验会在缺少可用 AI 模型 Key 或模型渠道时给出明确错误提示。
 
 #### 通知渠道配置（可同时配置多个，全部推送）
 
@@ -104,7 +104,7 @@ daily_stock_analysis/
 | `CUSTOM_WEBHOOK_BODY_TEMPLATE` | 自定义 Webhook JSON body 模板，适配 AstrBot、NapCat、自建服务等特殊 payload | 可选 |
 | `WEBHOOK_VERIFY_SSL` | 读取该配置的 webhook-style HTTPS 通知请求证书校验（默认 true）。设为 false 可支持自签名证书。警告：关闭有严重安全风险（MITM），仅限可信内网 | 可选 |
 
-> *注：至少配置一个渠道，配置多个则同时推送
+> *注：至少配置一个渠道，配置多个则同时推送。启动时配置校验会提示 Telegram / 邮件成对字段缺失，以及常见 Webhook URL 未以 `http://` 或 `https://` 开头的问题。
 >
 > 当前默认 `00-daily-analysis.yml` 只显式映射固定 Secret / Variable 名称，不会自动把 `STOCK_GROUP_1`、`EMAIL_GROUP_1` 这类任意编号变量导入运行环境。所以分组邮箱功能目前不适用于仓库自带默认 GitHub Actions workflow；它适用于本地 `.env`、Docker，或你自行显式扩展过 `env:` 映射的运行环境。Actions 已显式映射 `CUSTOM_WEBHOOK_BODY_TEMPLATE`、`WEBHOOK_VERIFY_SSL`、`FEISHU_WEBHOOK_SECRET`、`FEISHU_WEBHOOK_KEYWORD`、`PUSHPLUS_TOPIC`、`NTFY_URL`、`NTFY_TOKEN`、`GOTIFY_URL`、`GOTIFY_TOKEN`、P3 通知路由键以及 P4 通知降噪键；`MARKDOWN_TO_IMAGE_CHANNELS` 和 `MERGE_EMAIL_NOTIFICATION` 仍作为行为开关不在默认 workflow 中自动映射。
 

docs/full-guide_EN.md

@@ -65,7 +65,7 @@ Go to your forked repo → `Settings` → `Secrets and variables` → `Actions`
 | `OPENAI_BASE_URL` | OpenAI-compatible API endpoint (e.g., `https://api.deepseek.com`) | Optional |
 | `OPENAI_MODEL` | Model name (e.g., `deepseek-v4-flash`) | Optional |
 
-> *Note: Configure at least one model key or channel. Anspire or AIHubMix is the simplest starting point for one-key multi-model access.
+> *Note: Configure at least one model key or channel. Anspire or AIHubMix is the simplest starting point for one-key multi-model access. Startup validation reports a clear error when no usable AI model key or model channel is configured.
 
 #### Notification Channels (Multiple can be configured, all will receive notifications)
 
@@ -105,7 +105,7 @@ Go to your forked repo → `Settings` → `Secrets and variables` → `Actions`
 | `CUSTOM_WEBHOOK_BODY_TEMPLATE` | Custom Webhook JSON body template for AstrBot, NapCat, or self-hosted services with special payloads | Optional |
 | `WEBHOOK_VERIFY_SSL` | HTTPS certificate verification for webhook-style notification requests that read this setting (default true). Set to false for self-signed certs. WARNING: Disabling has serious security risk (MITM), use only on trusted internal networks | Optional |
 
-> *Note: Configure at least one channel; multiple channels will all receive notifications
+> *Note: Configure at least one channel; multiple channels will all receive notifications. Startup validation reports missing paired Telegram / email fields and common Webhook URLs that do not start with `http://` or `https://`.
 >
 > The default `00-daily-analysis.yml` in this repository only exports fixed Secret / Variable names. Arbitrary numbered env vars such as `STOCK_GROUP_1` and `EMAIL_GROUP_1` are not auto-injected into the job, so grouped email routing is not available in the stock workflow unless you explicitly extend the workflow's `env:` mapping in your own fork. Actions now maps `CUSTOM_WEBHOOK_BODY_TEMPLATE`, `WEBHOOK_VERIFY_SSL`, `FEISHU_WEBHOOK_SECRET`, `FEISHU_WEBHOOK_KEYWORD`, `PUSHPLUS_TOPIC`, `NTFY_URL`, `NTFY_TOKEN`, `GOTIFY_URL`, `GOTIFY_TOKEN`, the P3 notification route keys, and the P4 notification noise-control keys; `MARKDOWN_TO_IMAGE_CHANNELS` and `MERGE_EMAIL_NOTIFICATION` remain behavior toggles outside the default workflow mapping.
 

src/config.py

@@ -651,6 +651,9 @@ class Config:
     llm_models_source: str = "legacy_env"
     # LLM_CHANNELS: list of channel dicts, each with name/base_url/api_keys/models
     llm_channels: List[Dict[str, Any]] = field(default_factory=list)
+    # Raw channel names requested through LLM_CHANNELS, including channels that
+    # were skipped during parsing because required channel fields were missing.
+    llm_channel_names: List[str] = field(default_factory=list)
     # Pre-built LiteLLM Router model_list (populated from channels, YAML, or legacy keys)
     llm_model_list: List[Dict[str, Any]] = field(default_factory=list)
 
@@ -1122,10 +1125,6 @@ def _load_from_env(cls) -> 'Config':
             if (c or "").strip()
         ]
 
-        # 如果没有配置，使用默认的示例股票
-        if not stock_list:
-            stock_list = ['600519', '000001', '300750']
-        
         # === LiteLLM multi-key parsing ===
         # GEMINI_API_KEYS (comma-separated) > GEMINI_API_KEY (single)
         _gemini_keys_raw = os.getenv('GEMINI_API_KEYS', '')
@@ -1235,6 +1234,7 @@ def _load_from_env(cls) -> 'Config':
         litellm_config_path = os.getenv('LITELLM_CONFIG', '').strip() or None
         llm_models_source = "legacy_env"
         llm_channels: List[Dict[str, Any]] = []
+        llm_channel_names: List[str] = []
         llm_model_list: List[Dict[str, Any]] = []
 
         # Priority 1: LITELLM_CONFIG (standard LiteLLM YAML config file)
@@ -1247,6 +1247,11 @@ def _load_from_env(cls) -> 'Config':
         if not llm_model_list:
             _channels_str = os.getenv('LLM_CHANNELS', '').strip()
             if _channels_str:
+                llm_channel_names = [
+                    ch.strip().lower()
+                    for ch in _channels_str.split(',')
+                    if ch.strip()
+                ]
                 llm_channels = cls._parse_llm_channels(_channels_str)
                 llm_model_list = cls._channels_to_model_list(llm_channels)
                 if llm_model_list:
@@ -1435,6 +1440,7 @@ def _load_from_env(cls) -> 'Config':
             litellm_config_path=litellm_config_path,
             llm_models_source=llm_models_source,
             llm_channels=llm_channels,
+            llm_channel_names=llm_channel_names,
             llm_model_list=llm_model_list,
             gemini_api_keys=gemini_api_keys,
             anthropic_api_keys=anthropic_api_keys,
@@ -2376,9 +2382,6 @@ def refresh_stock_list(self) -> None:
             if (c or "").strip()
         ]
 
-        if not stock_list:
-            stock_list = ['000001']
-
         self.stock_list = stock_list
 
     def validate_structured(self) -> List[ConfigIssue]:
@@ -2400,7 +2403,7 @@ def validate_structured(self) -> List[ConfigIssue]:
         if not self.stock_list:
             issues.append(ConfigIssue(
                 severity="error",
-                message="未配置自选股列表 (STOCK_LIST)",
+                message="未配置 STOCK_LIST。请设置至少一个股票代码，例如：600519,hk00700,AAPL。",
                 field="STOCK_LIST",
             ))
         elif self.stock_email_groups:
@@ -2449,14 +2452,36 @@ def validate_structured(self) -> List[ConfigIssue]:
         # direct litellm env path and therefore do not populate llm_model_list.
         has_direct_env_model = bool(self.litellm_model) and _uses_direct_env_provider(self.litellm_model)
         if not self.llm_model_list and not has_direct_env_model:
-            issues.append(ConfigIssue(
-                severity="error",
-                message=(
-                    "未配置任何可用的 AI 模型接入（高级模型路由配置 / 渠道 / API Key），"
-                    "AI 分析功能将不可用"
-                ),
-                field="LITELLM_CONFIG",
-            ))
+            if self.litellm_config_path:
+                issues.append(ConfigIssue(
+                    severity="error",
+                    message=(
+                        "已配置 LITELLM_CONFIG，但未解析出可用模型。"
+                        "请检查 YAML 中的 model_list、litellm_params 和环境变量引用。"
+                    ),
+                    field="LITELLM_CONFIG",
+                ))
+            elif self.llm_channel_names:
+                issues.append(ConfigIssue(
+                    severity="error",
+                    message=(
+                        "已配置 LLM_CHANNELS，但未解析出可用模型渠道。"
+                        "请检查对应 LLM_<CHANNEL>_API_KEY(S)、"
+                        "LLM_<CHANNEL>_MODELS、LLM_<CHANNEL>_PROTOCOL 或 Base URL。"
+                    ),
+                    field="LLM_CHANNELS",
+                ))
+            else:
+                issues.append(ConfigIssue(
+                    severity="error",
+                    message=(
+                        "未配置任何可用的 AI 模型接入。请至少配置 ANSPIRE_API_KEYS、"
+                        "AIHUBMIX_KEY、GEMINI_API_KEY、ANTHROPIC_API_KEY、"
+                        "OPENAI_API_KEY 或 DEEPSEEK_API_KEY 中的一个，或配置 "
+                        "LITELLM_CONFIG / LLM_CHANNELS 可用模型渠道。"
+                    ),
+                    field="LITELLM_CONFIG",
+                ))
         elif not self.litellm_model:
             issues.append(ConfigIssue(
                 severity="info",
@@ -2597,6 +2622,49 @@ def _has_runtime_source_for_model(model: str) -> bool:
                 field="WECHAT_WEBHOOK_URL",
             ))
 
+        has_telegram_token = bool((self.telegram_bot_token or "").strip())
+        has_telegram_chat_id = bool((self.telegram_chat_id or "").strip())
+        if has_telegram_token != has_telegram_chat_id:
+            issues.append(ConfigIssue(
+                severity="error",
+                message="Telegram 通知配置不完整：TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID 必须同时配置。",
+                field="TELEGRAM_CHAT_ID" if has_telegram_token else "TELEGRAM_BOT_TOKEN",
+            ))
+
+        has_email_sender = bool((self.email_sender or "").strip())
+        has_email_password = bool((self.email_password or "").strip())
+        if has_email_sender != has_email_password:
+            issues.append(ConfigIssue(
+                severity="error",
+                message="邮件通知配置不完整：EMAIL_SENDER 和 EMAIL_PASSWORD 必须同时配置。",
+                field="EMAIL_PASSWORD" if has_email_sender else "EMAIL_SENDER",
+            ))
+
+        def _warn_if_webhook_url_invalid(field: str, value: Optional[str]) -> None:
+            raw_url = (value or "").strip()
+            if not raw_url:
+                return
+            parsed = urlparse(raw_url)
+            if parsed.scheme.lower() in {"http", "https"} and parsed.netloc:
+                return
+            issues.append(ConfigIssue(
+                severity="warning",
+                message=f"{field} 看起来不是有效 URL，请确认是否以 http:// 或 https:// 开头。",
+                field=field,
+            ))
+
+        for field, value in (
+            ("WECHAT_WEBHOOK_URL", self.wechat_webhook_url),
+            ("FEISHU_WEBHOOK_URL", self.feishu_webhook_url),
+            ("DISCORD_WEBHOOK_URL", self.discord_webhook_url),
+            ("SLACK_WEBHOOK_URL", self.slack_webhook_url),
+            ("ASTRBOT_URL", self.astrbot_url),
+        ):
+            _warn_if_webhook_url_invalid(field, value)
+
+        for custom_url in self.custom_webhook_urls:
+            _warn_if_webhook_url_invalid("CUSTOM_WEBHOOK_URLS", custom_url)
+
         if self.ntfy_url and not _has_ntfy_topic_endpoint(self.ntfy_url):
             issues.append(ConfigIssue(
                 severity="error",

tests/test_config_env_compat.py

@@ -431,6 +431,21 @@ def test_runtime_mutable_keys_use_process_env_when_absent_from_file(
 
         self.assertEqual(config.stock_list, ["600519", "000001"])
 
+    def test_refresh_stock_list_preserves_empty_required_config(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            env_path = Path(temp_dir) / ".env"
+            env_path.write_text("STOCK_LIST=\n", encoding="utf-8")
+
+            config = Config(stock_list=["600519"])
+            with patch.dict(os.environ, {"ENV_FILE": str(env_path)}, clear=True):
+                config.refresh_stock_list()
+
+        self.assertEqual(config.stock_list, [])
+        issues = config.validate_structured()
+        self.assertTrue(
+            any(issue.severity == "error" and issue.field == "STOCK_LIST" for issue in issues)
+        )
+
     def test_parse_report_language_accepts_known_alias_without_warning(self) -> None:
         with self.assertNoLogs("src.config", level="WARNING"):
             parsed = Config._parse_report_language("zh-cn")

tests/test_config_validate_structured.py

@@ -118,7 +118,10 @@ def test_empty_stock_list_is_error(self):
         cfg = _make_config(stock_list=[])
         issues = cfg.validate_structured()
         errors = [i for i in issues if i.severity == "error"]
-        assert any("STOCK_LIST" in i.field for i in errors)
+        stock_errors = [i for i in errors if i.field == "STOCK_LIST"]
+        assert stock_errors
+        assert "未配置 STOCK_LIST" in stock_errors[0].message
+        assert "600519,hk00700,AAPL" in stock_errors[0].message
 
     def test_configured_stock_list_no_stock_error(self):
         cfg = _make_config(stock_list=["600519", "000001"])
@@ -188,6 +191,48 @@ def test_no_llm_is_error(self):
         issues = cfg.validate_structured()
         assert any(i.severity == "error" and "AI 模型" in i.message for i in issues)
 
+    def test_validate_missing_all_llm_keys_reports_error(self):
+        cfg = _make_config(
+            llm_model_list=[],
+            litellm_model="",
+            gemini_api_keys=[],
+            anthropic_api_keys=[],
+            openai_api_keys=[],
+            deepseek_api_keys=[],
+            anspire_api_keys=[],
+        )
+
+        issues = cfg.validate_structured()
+
+        error = next(i for i in issues if i.severity == "error" and i.field == "LITELLM_CONFIG")
+        assert "未配置任何可用的 AI 模型接入" in error.message
+        assert "ANSPIRE_API_KEYS" in error.message
+        assert "DEEPSEEK_API_KEY" in error.message
+
+    @patch("src.config.setup_env")
+    @patch.object(Config, "_parse_litellm_yaml", return_value=[])
+    def test_declared_llm_channels_without_models_reports_channel_error(
+        self,
+        _mock_parse_yaml,
+        _mock_setup_env,
+    ):
+        with patch.dict(
+            "os.environ",
+            {
+                "LLM_CHANNELS": "primary",
+                "LLM_PRIMARY_API_KEY": "sk-primary-test-value",
+            },
+            clear=True,
+        ):
+            cfg = Config._load_from_env()
+
+        issues = cfg.validate_structured()
+
+        error = next(i for i in issues if i.severity == "error" and i.field == "LLM_CHANNELS")
+        assert "已配置 LLM_CHANNELS" in error.message
+        assert "LLM_<CHANNEL>_MODELS" in error.message
+        assert not any(i.severity == "error" and i.field == "ANSPIRE_API_KEYS" for i in issues)
+
     def test_llm_channels_only_no_error(self):
         """LLM_CHANNELS populated via llm_model_list must NOT trigger an error.
 
@@ -337,6 +382,61 @@ def test_notification_configured_no_warning(self):
         issues = cfg.validate_structured()
         assert not any(i.severity == "warning" and "通知渠道" in i.message for i in issues)
 
+    @pytest.mark.parametrize(
+        ("kwargs", "missing_field"),
+        [
+            ({"telegram_bot_token": "bot-token", "telegram_chat_id": None}, "TELEGRAM_CHAT_ID"),
+            ({"telegram_bot_token": None, "telegram_chat_id": "123456"}, "TELEGRAM_BOT_TOKEN"),
+        ],
+    )
+    def test_validate_incomplete_telegram_config_reports_error(self, kwargs, missing_field):
+        cfg = _make_config(**kwargs)
+        issues = cfg.validate_structured()
+
+        assert any(
+            i.severity == "error"
+            and i.field == missing_field
+            and "Telegram 通知配置不完整" in i.message
+            for i in issues
+        )
+
+    @pytest.mark.parametrize(
+        ("kwargs", "missing_field"),
+        [
+            ({"email_sender": "sender@example.com", "email_password": None}, "EMAIL_PASSWORD"),
+            ({"email_sender": None, "email_password": "app-password"}, "EMAIL_SENDER"),
+        ],
+    )
+    def test_validate_incomplete_email_config_reports_error(self, kwargs, missing_field):
+        cfg = _make_config(**kwargs)
+        issues = cfg.validate_structured()
+
+        assert any(
+            i.severity == "error"
+            and i.field == missing_field
+            and "邮件通知配置不完整" in i.message
+            for i in issues
+        )
+
+    @pytest.mark.parametrize(
+        ("field", "kwargs"),
+        [
+            ("WECHAT_WEBHOOK_URL", {"wechat_webhook_url": "abc"}),
+            ("FEISHU_WEBHOOK_URL", {"feishu_webhook_url": "xxx"}),
+            ("DISCORD_WEBHOOK_URL", {"discord_webhook_url": "test"}),
+        ],
+    )
+    def test_validate_invalid_webhook_url_reports_warning(self, field, kwargs):
+        cfg = _make_config(**kwargs)
+        issues = cfg.validate_structured()
+
+        assert any(
+            i.severity == "warning"
+            and i.field == field
+            and "http:// 或 https://" in i.message
+            for i in issues
+        )
+
     def test_astrbot_url_counts_as_notification_channel(self):
         cfg = _make_config(
             wechat_webhook_url=None,