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

Author: ZhuLinsen

docs/CHANGELOG.md

@@ -70,10 +70,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [改进] 🔎 **SerpAPI 正文补抓范围收敛** — 自然搜索结果不再逐条同步抓取网页正文；现在仅对极少数高位且摘要明显不足的结果，在更短超时预算内做延迟补抓，并优先复用 SerpAPI 已返回的结构化摘要，降低搜索链路尾延迟与慢站点放大风险。
 - [修复] A 股和中文股票名称场景下的相关资讯搜索恢复中文优先策略：`search_stock_news()` 现在会在首个 provider 主要返回英文资讯时继续尝试后续引擎，并将同批结果中的中文资讯排到前面；同时非美股查询不再默认沿用 Brave 的 `en/US` 区域语言偏好，避免更新后被英文新闻结果占满。
 - [修复] 飞书群机器人通知现在支持 `FEISHU_WEBHOOK_SECRET` / `FEISHU_WEBHOOK_KEYWORD`，并在 Web 设置与文档中明确区分 Webhook 推送和 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` 应用模式，降低误配导致的推送失败。
-- [修复] `LLM_CHANNELS` 现在会在常见 provider 渠道缺少 `LLM_{NAME}_API_KEY(S)` 时，安全回退读取匹配的 legacy Secrets（如 `DEEPSEEK_API_KEY`、`AIHUBMIX_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`ANTHROPIC_API_KEY`），让 GitHub Actions 可继续使用默认 `.env` 的非敏感渠道结构。
-- [修复] `LLM_CHANNELS` 现在会在常见 provider 渠道缺少 `LLM_{NAME}_API_KEY(S)` 时，安全回退读取匹配的 legacy Secrets（如 `DEEPSEEK_API_KEY`、`AIHUBMIX_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`ANTHROPIC_API_KEY`），让 GitHub Actions 可继续使用默认 `.env` 的非敏感渠道结构。当渠道配置了自定义 `base_url` 时，仅通过严格域名校验匹配 legacy 密钥，防止凭据泄露到非官方端点。
-- [修复] `LLM_CHANNELS` 现在会在常见 provider 渠道缺少 `LLM_{NAME}_API_KEY(S)` 时，安全回退读取匹配的 legacy Secrets（如 `DEEPSEEK_API_KEY`、`AIHUBMIX_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`ANTHROPIC_API_KEY`），让 GitHub Actions 可继续使用默认 `.env` 的非敏感渠道结构。当渠道配置了自定义 `base_url` 时，仅当 URL 使用 HTTPS 协议且通过严格域名校验时才匹配 legacy 密钥，防止凭据通过明文 HTTP 或非官方端点泄露。
-- [文档] 更新中英文 LLM 配置指南与 FAQ，补充 GitHub Actions 下渠道模式复用 legacy Secrets 的用法，并明确自定义渠道仍建议使用 `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`。
+- [修复] `LLM_CHANNELS` 现在会在常见 provider 渠道缺少 `LLM_{NAME}_API_KEY(S)` 时，按 provider/protocol 严格匹配并回退读取 legacy Secrets（如 `DEEPSEEK_API_KEY`、`AIHUBMIX_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`ANTHROPIC_API_KEY`）。仅当 `base_url` 为 HTTPS 且通过域名白名单校验时，或未配置自定义 `base_url` 且与 `LLM_{NAME}_PROTOCOL` 一致时才回退，避免密钥落到不可信端点，兼容 GitHub Actions 复用既有 Secrets。
+- [文档] 更新中英文 LLM 配置指南与 FAQ，补充 GitHub Actions 下渠道模式复用 legacy Secrets 的用法，并明确自定义渠道建议改用 `LITELLM_CONFIG`（高级模型路由配置文件路径）承载自定义配置。
 
 ## [3.11.0] - 2026-03-27
 
@@ -415,7 +413,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - 🤖 **Agent background execution** (#495) — analysis continues when switching pages; badge notification on completion; auto-cancel in-progress stream on session switch
 - 📝 **Report Engine P0** — Pydantic schema validation for LLM JSON; Jinja2 templates (markdown/wechat/brief) with legacy fallback; content integrity checks with retry; brief mode (`REPORT_TYPE=brief`); history signal comparison
 - 📦 **Smart import** — multi-source import from image/CSV/Excel/clipboard; Vision LLM extracts code+name+confidence; name→code resolver (local map + pinyin + AkShare); confidence-tiered confirmation
-- ⚙️ **GitHub Actions LiteLLM config** — workflow supports `LITELLM_CONFIG`/`LITELLM_CONFIG_YAML` for flexible AI provider configuration
+- ⚙️ **GitHub Actions LiteLLM config** — workflow supports `LITELLM_CONFIG` as the custom routing configuration file path for AI provider setup
 - ⚙️ **Config engine refactor & system API** (#602) — unified config registry, validation and API exposure
 - 📖 **LLM configuration guide** — new `docs/LLM_CONFIG_GUIDE.md` covering 3-tier config, quick start, Vision/Agent/troubleshooting
 

docs/FAQ.md

@@ -91,7 +91,10 @@
    - `REPORT_TYPE`
    - `LLM_CHANNELS`、`LLM_{NAME}_BASE_URL`、`LLM_{NAME}_MODELS`
 
-如果你在 GitHub Actions 使用 `LLM_CHANNELS=deepseek,aihubmix` 这类常见 provider 渠道，不必把真实 `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` 写进默认 `.env`；把真实 Key 放在 `DEEPSEEK_API_KEY`、`AIHUBMIX_KEY`（或 `OPENAI_API_KEY`）即可。自定义渠道名仍建议改用 `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`。
+如果你在 GitHub Actions 使用 `LLM_CHANNELS=deepseek,aihubmix` 这类常见 provider 渠道，不必把真实 `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` 写进默认 `.env`；把真实 Key 放在 `DEEPSEEK_API_KEY`、`AIHUBMIX_KEY`（或 `OPENAI_API_KEY`）即可。  
+自定义渠道名可走高级 YAML 配置：  
+- 已提交 `litellm_config.yaml` 到仓库：只需在 `Actions` 中配置 `LITELLM_CONFIG` 指向文件路径（例如 `./litellm_config.yaml`）。  
+- 未提交文件：同时配置 `LITELLM_CONFIG=./litellm_config.yaml`（或其他可写路径）与 `LITELLM_CONFIG_YAML`（Secrets/Variables 中放 YAML 内容），workflow 会在运行时写入文件。
 
 ---
 

docs/FAQ_EN.md

@@ -89,7 +89,10 @@ This document compiles common issues encountered by users and their solutions.
    - `REPORT_TYPE`
    - `LLM_CHANNELS`, `LLM_{NAME}_BASE_URL`, `LLM_{NAME}_MODELS`
 
-If you run `LLM_CHANNELS=deepseek,aihubmix` in GitHub Actions, you do not need to put real `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` values into the default `.env`. Put the real keys in `DEEPSEEK_API_KEY` and `AIHUBMIX_KEY` (or `OPENAI_API_KEY`) instead. Custom channel names should still use `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`.
+If you run `LLM_CHANNELS=deepseek,aihubmix` in GitHub Actions, you do not need to put real `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` values into the default `.env`. Put the real keys in `DEEPSEEK_API_KEY` and `AIHUBMIX_KEY` (or `OPENAI_API_KEY`) instead.  
+For custom channel names, use advanced YAML routing:
+- If you commit `litellm_config.yaml` in the repo: only set `LITELLM_CONFIG` to the file path (for example, `./litellm_config.yaml`).
+- If you do not commit the file: set both `LITELLM_CONFIG=./litellm_config.yaml` (or another writable path) and `LITELLM_CONFIG_YAML` (YAML content in Secrets/Variables), and the workflow will write the file at runtime.
 
 ---
 

docs/LLM_CONFIG_GUIDE.md

@@ -117,11 +117,14 @@ LITELLM_MODEL=ollama/qwen3:8b
 - 如果你通过 OpenAI Compatible 渠道接 MiniMax，请在渠道模型里直接填写 `minimax/<模型名>`，例如 `minimax/MiniMax-M1`。
 - Web 设置页里的主模型、Agent 主模型、Fallback、Vision 下拉会保留这个值原样展示，不会再错误改写成 `openai/minimax/<模型名>`。
 
-> **致命避坑说明**：如果你启用了 `LLM_CHANNELS`，那么你直接写在外面的 `DEEPSEEK_API_KEY` 或 `OPENAI_API_KEY` 将**全部失效（系统一律无视）**！二者**选其一即可**，千万不要既写了新手模式又写了渠道模式结果产生冲突。
+> **关键说明**：当你启用 `LLM_CHANNELS` 后，系统会优先按**渠道模式**运行；对常见 provider 渠道（如 `deepseek`、`aihubmix`、`openai`、`gemini`、`anthropic`）在未配置 `LLM_{NAME}_API_KEY(S)` 时，会按渠道名/官方域名安全回退到对应 legacy Secret（如 `DEEPSEEK_API_KEY(S)`、`AIHUBMIX_KEY / OPENAI_API_KEY(S)`、`GEMINI_API_KEY(S)`、`ANTHROPIC_API_KEY(S)`）。  
+自定义渠道建议走 YAML 高级配置：提交实体 YAML 文件时可仅设置 `LITELLM_CONFIG`；未提交文件时则需加上 `LITELLM_CONFIG_YAML`。
 
 > **GitHub Actions 兼容说明**：渠道模式仍优先于 legacy 模式，但常见 provider 渠道在缺少 `LLM_{NAME}_API_KEY(S)` 时，会按渠道名/官方域名安全回退读取已有 Secrets：`deepseek -> DEEPSEEK_API_KEY(S)`、`aihubmix -> AIHUBMIX_KEY / OPENAI_API_KEY(S)`、`openai -> OPENAI_API_KEY(S)`、`gemini/vertex -> GEMINI_API_KEY(S)`、`anthropic/claude -> ANTHROPIC_API_KEY(S)`。这意味着你可以继续使用默认 `.env` 中的非敏感渠道结构，把真实 Key 放在 GitHub Secrets 里，而不用把真实 `LLM_DEEPSEEK_API_KEY`、`LLM_AIHUBMIX_API_KEY` 写进仓库配置。
 >
-> **边界说明**：这个回退只覆盖常见 provider 渠道名；像 `my_proxy`、`corp_gateway` 这类自定义渠道名在 GitHub Actions 中仍建议改用 `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`，避免 secret 名与渠道名无法自动对齐。
+> **边界说明**：这个回退只覆盖常见 provider 渠道名；像 `my_proxy`、`corp_gateway` 这类自定义渠道名在 GitHub Actions 中无法自动按渠道名映射 legacy Secret。此类场景建议走高级 YAML 模式：
+> - 若你已提交实体 `litellm_config.yaml` 文件：`LITELLM_CONFIG` 只需指向该文件路径（例如 `./litellm_config.yaml`）。
+> - 若你不提交实体文件：`LITELLM_CONFIG` 需提供写入路径，且同时补 `LITELLM_CONFIG_YAML`（可放在 Secrets/Variables），由 workflow 在运行时写入 YAML 内容。
 
 ---
 
@@ -179,17 +182,19 @@ LITELLM_FALLBACK_MODELS=openai/gpt-4o-mini,anthropic/claude-3-5-sonnet
 - `GEMINI_API_KEY`
 - `ANTHROPIC_API_KEY`
 
-这样无需改 workflow，也无需把真实 `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` 写进默认 `.env`。若你使用的是自定义渠道名，则请改用下面的 YAML 高级配置。
+这样无需改 workflow，也无需把真实 `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` 写进默认 `.env`。若你使用的是自定义渠道名，请改用下面的 YAML 高级配置，按实际场景选一：
+- 已提交 `litellm_config.yaml` 到仓库：仅配置 `LITELLM_CONFIG=./litellm_config.yaml`。
+- 未提交文件：配置 `LITELLM_CONFIG=./litellm_config.yaml`（路径）与 `LITELLM_CONFIG_YAML`（YAML 内容，来自 Secrets/Variables）。
 
 1. `Settings` → `Secrets and variables` → `Actions` → `Secret`标签页下的`New repository secret` 或者 `Variables`标签页下的`New repository variable`
 
 2. 按下表配置，只有全部必填配置正确配置，YAML 高级配置模式才可以生效，YAML配置文件的写法，可以参考自带的 `litellm_config.example.yaml`
 
 | Secret 名称 | 说明 | 必填 |
 |------------|------|:----:|
-| `LITELLM_CONFIG` | 高级模型路由配置文件路径，通常配置 `./litellm_config.yaml` | 必填 |
+| `LITELLM_CONFIG` | 高级模型路由配置文件路径（如 `./litellm_config.yaml`） | 必填 |
+| `LITELLM_CONFIG_YAML` | 可选：如未提交实体配置文件，可在 `Actions` Secret/Variable 中放 YAML 内容；workflow 会写入 `LITELLM_CONFIG` 路径 | 可选 |
 | `LITELLM_MODEL` | 默认主模型名称或路由别名 | 必填 |
-| `LITELLM_CONFIG_YAML` | 存放 YAML 配置文件内容，可不在仓库中提交实体文件 | 可选 |
 | `LITELLM_API_KEY` | 用于存储API Key，可在配置文件中引用（环境变量引用方式）。由于GitHub Actions必须要指定导入的环境变量，因此你不能像本地运行模式那样自由命名环境变量 | 可选，必须配置到repository secret中 |
 | `ANTHROPIC_API_KEY` | 如果要多个API Key，这个变量名称也能拿来用 | 可选，必须配置到repository secret中 |
 | `OPENAI_API_KEY` | 同上，可以用来存储API Key | 可选，必须配置到repository secret中 |
@@ -230,7 +235,7 @@ VISION_PROVIDER_PRIORITY=gemini,anthropic,openai
 | 遇到了什么诡异报错？ | 罪魁祸首可能是啥？ | 该怎么收拾它？ |
 |----------------------|----------------------|------------------|
 | **界面提示主模型未配置** | 系统不知道你到底想用哪家的哪个模型 | 在 `.env` 中写上一句明白话：`LITELLM_MODEL=provider/你的模型名`。比如 `openai/gpt-4o-mini` |
-| **我写了好几家的Key，为什么死活只有一个生效？修改还没用？** | 大概率是模式混用，或渠道名和 Secret 名没对齐。 | 本地 / Docker 请优先直接写 `LLM_{NAME}_API_KEY(S)`；GitHub Actions 下，`deepseek` / `aihubmix` / `openai` / `gemini` / `anthropic` 等常见渠道可复用对应 legacy Secrets；自定义渠道请改用 `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`。 |
+| **我写了好几家的Key，为什么死活只有一个生效？修改还没用？** | 大概率是模式混用，或渠道名和 Secret 名没对齐。 | 本地 / Docker 请优先直接写 `LLM_{NAME}_API_KEY(S)`；GitHub Actions 下，`deepseek` / `aihubmix` / `openai` / `gemini` / `anthropic` 等常见渠道可复用对应 legacy Secrets。自定义渠道请走高级 YAML 配置：提交 `litellm_config.yaml` 时只配 `LITELLM_CONFIG`，不提交时再补 `LITELLM_CONFIG_YAML`。 |
 | **错误码报 400 或 401 或 Invalid API Key** | API Key 填错、少复制了一截、账号充值没到账、或者模型名字敲错（极度常见）。 | 1. 检查复制的 Key 前后是否有误填空格。<br> 2. 检查 Base URL 最后是不是少了一个 `/v1`。<br> 3. 检查模型名是否少写了 `openai/` 之类的前缀！ |
 | **转圈转不停，最后报 Timeout / ConnectionRefused 等** | 1. 在国内使用国外原版（像 Google、OpenAI），没开代理被墙了。<br>2. 你买的云服务器压根不能出境。 | 非常推荐使用**国内官方**（如DeepSeek、阿里）或者各种**兼容 OpenAI 的聚合中转接口**。因为中转站把网络问题帮你解决好了。 |
 | **Ollama 报 404、`Could not get model info` 或 `api/generate/api/show`** | 误用 `OPENAI_BASE_URL` 配置 Ollama，系统会错误拼接 URL | 改用 `OLLAMA_API_BASE=http://localhost:11434` 或渠道模式（`LLM_CHANNELS=ollama` + `LLM_OLLAMA_BASE_URL`） |

docs/LLM_CONFIG_GUIDE_EN.md

@@ -117,11 +117,14 @@ LITELLM_MODEL=ollama/qwen3:8b
 - If you access MiniMax through an OpenAI-compatible channel, enter the model as `minimax/<model-name>` in the channel model list, for example `minimax/MiniMax-M1`.
 - The Web settings page now keeps that value unchanged in Primary, Agent Primary, Fallback, and Vision selectors instead of rewriting it to `openai/minimax/<model-name>`.
 
-> **Critical Warning**: If you enable `LLM_CHANNELS`, any standard `DEEPSEEK_API_KEY` or `OPENAI_API_KEY` declared independently will be **completely ignored**. **Use only one mode** to prevent configuration conflicts.
+> **Key Note**: Enabling `LLM_CHANNELS` makes channel mode the primary mode. For common providers (such as `deepseek`, `aihubmix`, `openai`, `gemini`, `anthropic`), if `LLM_{NAME}_API_KEY(S)` is not provided, the system safely falls back to the corresponding legacy secret by channel name/official host (for example, `DEEPSEEK_API_KEY(S)`, `AIHUBMIX_KEY / OPENAI_API_KEY(S)`, `GEMINI_API_KEY(S)`, `ANTHROPIC_API_KEY(S)`).  
+For custom channels, use the advanced YAML path: with committed YAML set only `LITELLM_CONFIG` (file path); without file submission, also provide `LITELLM_CONFIG_YAML`.
 
 > **GitHub Actions Compatibility**: Channels mode still wins over legacy mode, but well-known provider channels can now safely reuse existing Secrets when `LLM_{NAME}_API_KEY(S)` is absent: `deepseek -> DEEPSEEK_API_KEY(S)`, `aihubmix -> AIHUBMIX_KEY / OPENAI_API_KEY(S)`, `openai -> OPENAI_API_KEY(S)`, `gemini/vertex -> GEMINI_API_KEY(S)`, `anthropic/claude -> ANTHROPIC_API_KEY(S)`. This lets you keep only the non-sensitive channel structure in the default `.env` and store real keys in GitHub Secrets instead of writing real `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` values into repo config.
 >
-> **Boundary**: This fallback only applies to common provider channel names / official hosts. Custom channel names such as `my_proxy` or `corp_gateway` should still use `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML` in GitHub Actions.
+> **Boundary**: This fallback only applies to common provider channel names / official hosts. For custom channel names such as `my_proxy` or `corp_gateway` in GitHub Actions, use advanced YAML routing:
+> - If you commit an actual `litellm_config.yaml` file: set `LITELLM_CONFIG` to its path (for example, `./litellm_config.yaml`).
+> - If you do not commit a file: set `LITELLM_CONFIG` to the target path and also set `LITELLM_CONFIG_YAML` in Secrets/Variables; the workflow will write the YAML content at runtime.
 
 ---
 
@@ -181,7 +184,9 @@ Store the real keys in GitHub Secrets:
 - `GEMINI_API_KEY`
 - `ANTHROPIC_API_KEY`
 
-This works without changing the workflow and avoids writing real `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` values into the default `.env`. For custom channel names, prefer `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`.
+This works without changing the workflow and avoids writing real `LLM_DEEPSEEK_API_KEY` / `LLM_AIHUBMIX_API_KEY` values into the default `.env`. For custom channel names, use advanced YAML routing and choose one of:
+- If you commit `litellm_config.yaml` in the repo: only set `LITELLM_CONFIG=./litellm_config.yaml`.
+- If you do not commit the file: set both `LITELLM_CONFIG=./litellm_config.yaml` and `LITELLM_CONFIG_YAML` (content via Secrets/Variables).
 
 ---
 
@@ -216,7 +221,7 @@ Afraid you got the config wrong? Type the following commands in your terminal to
 | Weird Error You Got? | Likely Culprit | How to Fix It? |
 |----------------------|----------------|----------------|
 | **The UI says the primary model is not configured** | The system doesn't know which provider/model you want to use. | Add a clear instruction in `.env`: `LITELLM_MODEL=provider/your_model_name`. Example: `openai/gpt-4o-mini`. |
-| **I added multiple provider Keys, why is only one working?** | Usually you mixed config modes, or your channel name does not match a supported fallback mapping. | For local / Docker, prefer explicit `LLM_{NAME}_API_KEY(S)`. In GitHub Actions, common provider channel names such as `deepseek` / `aihubmix` / `openai` / `gemini` / `anthropic` can reuse matching legacy Secrets. Custom channel names should switch to `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`. |
+| **I added multiple provider Keys, why is only one working?** | Usually you mixed config modes, or your channel name does not match a supported fallback mapping. | For local / Docker, prefer explicit `LLM_{NAME}_API_KEY(S)`. In GitHub Actions, common provider channel names such as `deepseek` / `aihubmix` / `openai` / `gemini` / `anthropic` can reuse matching legacy Secrets. Custom channel names should use advanced YAML routing: commit `litellm_config.yaml` and set only `LITELLM_CONFIG`, or set both `LITELLM_CONFIG` + `LITELLM_CONFIG_YAML`. |
 | **Returns 400, 401, or Invalid API Key** | The API Key is wrong, copied incompletely, account lacks credits, or you mistyped the model name (extremely common). | 1. Ensure there are no spaces at the start/end of your Key.<br> 2. Ensure your Base URL ends with `/v1`.<br> 3. Check if you forgot the `openai/` prefix on the model name! |
 | **Spins endlessly, eventually hits Timeout/ConnectionRefused** | You are using restricted APIs (like Google/OpenAI) in a blocked region without a proxy, or your cloud server lacks external internet access. | Highly recommend using **official regional APIs** (like DeepSeek) or **OpenAI-compatible relay platforms**. Third-party platforms bypass these network constraints. |
 | **Ollama returns 404, `Could not get model info`, or `api/generate/api/show`** | Using `OPENAI_BASE_URL` for Ollama makes the system concatenate URLs incorrectly | Use `OLLAMA_API_BASE=http://localhost:11434` or channel mode (`LLM_CHANNELS=ollama` + `LLM_OLLAMA_BASE_URL`) instead |