fix: 修正 LLM 渠道测试请求被拦截误报为网络异常 (#1223)

[massif-01]

PR Type

• fix
• feat
• refactor
• docs
• chore
• test

Background And Problem

Issue #1223 反馈 LLM 渠道测试遇到 Your request was blocked 等服务商或中转网关主动拦截错误时，会被误归类为网络异常或未知错误。这样会引导用户优先排查 Base URL、代理、TLS 等本地网络问题，而不是账号风控、地域限制、代理商网关策略、内容安全策略或请求来源限制。

本 PR 将这类明确的 blocked 文案拆成独立诊断，避免与通用网络、鉴权或模型不可用错误混淆。

Scope Of Change

• 后端 src/services/system_config_service.py
  • 新增保守的 blocked 信号识别。
  • 在异常分类和 /models HTTP 错误分类中新增 request_blocked / provider_blocked。
  • 保持 quota/billing/rate 优先于 blocked，blocked 优先于通用 401/403 auth 与 forbidden/authentication 兜底。
• 后端测试 tests/test_system_config_service.py
  • 覆盖 Issue 原始文案、403 blocked、forbidden+blocked、明确 blocked 信号、quota/rate 优先级和负例。
• Web apps/dsa-web/src/components/settings/LLMChannelEditor.tsx
  • 新增“请求被拦截”标签和 provider_blocked 排障提示。
• Web 测试 apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx
  • 覆盖 blocked 提示，并断言不显示网络排障和模型列表调整建议。
• 文档
  • 更新 docs/CHANGELOG.md、docs/llm-providers.md、docs/LLM_CONFIG_GUIDE.md、docs/LLM_CONFIG_GUIDE_EN.md。
  • 未更新 README.md，因为这不是首页级能力变化。

Issue Link

Fixes #1223

Verification Commands And Results

python -m pytest tests/test_system_config_service.py tests/test_system_config_api.py -q
python -m py_compile src/services/system_config_service.py
./scripts/ci_gate.sh
cd apps/dsa-web && npm ci
cd apps/dsa-web && npm run test -- LLMChannelEditor.test.tsx
cd apps/dsa-web && npm run lint
cd apps/dsa-web && npm run build
git diff --check

关键输出/结论：

• python -m pytest tests/test_system_config_service.py tests/test_system_config_api.py -q：119 passed。
• python -m py_compile src/services/system_config_service.py：通过。
• ./scripts/ci_gate.sh：backend-gate: all checks passed，1731 passed, 2 deselected, 47 warnings, 151 subtests passed。
• npm ci：安装完成；npm audit 汇总提示 10 个既有依赖漏洞，本 PR 未改动依赖。
• npm run test -- LLMChannelEditor.test.tsx：37 passed。
• npm run lint：通过。
• npm run build：通过；保留项目既有的 Vite chunk size warning。
• git diff --check：通过。

Compatibility And Risk

• API 响应结构不变，仅新增诊断枚举值：error_code=request_blocked、details.reason=provider_blocked。
• 不修改请求参数、Base URL 规范化、模型规范化、配置保存、.env、迁移或回填逻辑；旧配置不会被自动改写或清空。
• 这不是第三方模型/API 参数或路由前缀兼容规则变更，因此没有新增官方 provider 约束；只是对运行时错误文案进行更精确的本地诊断分类。
• 风险：少数外部脚本如果依赖旧的 network_error 对 blocked 场景自动重试，修复后会收到 request_blocked 且 retryable=false。这是纠正误判，但属于可见行为变化。
• 误判风险通过保守 token 降低：不匹配裸 blocked，也不使用宽泛的 request was blocked 子串。

Rollback Plan

最小回滚方式是 revert this PR。无需额外回滚配置、数据库、.env 或用户数据；回滚后 blocked 文案会恢复到旧的网络/鉴权/未知兜底分类。

EXTRACT_PROMPT Change (if applicable)

未修改 src/services/image_stock_extractor.py 或 EXTRACT_PROMPT。

展开 / Expand: Full EXTRACT_PROMPT

N/A

Checklist

• 本 PR 有明确动机和业务价值 / This PR has a clear motivation and value
• 已提供可复现的验证命令与结果 / Reproducible verification commands and results are included
• 已评估兼容性与风险 / Compatibility and risk have been assessed
• 已提供回滚方案 / A rollback plan is provided
• 若涉及用户可见变更，已同步更新相关文档与 docs/CHANGELOG.md；README.md 仅在首页级信息变化时更新，细节优先写入 docs/*.md / If user-visible changes are included, relevant docs and docs/CHANGELOG.md are updated; README.md is updated only for homepage-level changes, with details kept in docs/*.md

[github-actions]

🤖 自动审查报告

项目	结果
📊 变更文件	8 个
➕ 新增行数	127 行
➖ 删除行数	5 行
🔍 静态检查	✅ 通过
🧠 AI 审查	✅ 已完成

📁 修改的文件

• 📝 apps/dsa-web/src/components/settings/LLMChannelEditor.tsx (+2/-0)
• 📝 apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx (+40/-0)
• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/LLM_CONFIG_GUIDE.md (+1/-0)
• 📝 docs/LLM_CONFIG_GUIDE_EN.md (+1/-0)
• 📝 docs/llm-providers.md (+2/-1)
• 📝 src/services/system_config_service.py (+56/-3)
• 📝 tests/test_system_config_service.py (+24/-1)

---

🧠 AI 代码审查意见

结论

Ready to Merge

结构化结果

• 必要性：通过。此 PR 解决了 LLM 渠道测试中“请求被拦截”类错误被误报为通用网络异常的问题，这种误报会严重误导用户排查方向。通过引入更精确的诊断分类和排障提示，它极大地提升了用户体验和故障排除效率，具有明确的业务价值。

• 关联性：通过。PR 描述明确指出 "Fixes [Bug] LLM 渠道测试将 Your request was blocked 误报为网络异常 #1223"，与关联 Issue 一致，追溯性良好。

• 类型：建议类型为 fix, docs, test。PR 的实际修改内容（修正错误分类、更新文档、增加测试）与所选类型完美匹配。

• 描述完整性：完整。PR 描述涵盖了背景、问题、变更范围、详细的验证命令与结果（包括 Python 后端和前端的测试、lint、build 结果，以及 CI gate 的执行情况）、兼容性风险评估和回滚方案。信息非常全面且准确，无需补充。

• 风险级别：低。

  • 关键风险：此 PR 引入了新的错误码 request_blocked 和 provider_blocked。这意味着如果外部自动化脚本之前依赖旧的 network_error 标识来对“请求被拦截”场景进行重试，在更新后将收到 request_blocked 且 retryable=false，可能需要相应调整其重试逻辑。PR 描述中已充分评估并接受此行为变化，并强调这是对误判的纠正，风险可控。

• 必改项：无。

• 建议项：无。此 PR 的代码质量、测试覆盖、文档更新和描述完整性都非常出色，无需额外建议。

代码与文档审查细节

1. 后端代码 (src/services/system_config_service.py)：

   • 新增了 _has_request_blocked_signal 和 _has_transport_blocked_signal 静态方法，用于区分服务商/网关策略拦截（如“Your request was blocked”、“请求被拦截”）和传输层/本地网络拦截（如“connection blocked”、“firewall blocked”）。匹配的关键词保守且精准，避免误判。
   • 在 classify_http_error 和 classify_litellm_exception 方法中，request_blocked 的诊断优先级被合理地置于通用鉴权错误（401/403）之前，确保了更具体的错误能被优先识别和报告。
   • 对传输层拦截（_has_transport_blocked_signal）导致的 network_error 设置 retryable=True，而对服务商策略拦截（_has_request_blocked_signal）导致的 request_blocked 设置 retryable=False。这一区分是准确且符合实际排障逻辑的，帮助用户判断是否应立即重试。
   • 代码逻辑清晰，易于理解和维护。

2. 后端测试 (tests/test_system_config_service.py)：

   • 新增了大量测试用例，全面覆盖了多种 blocked 场景，包括不同的错误信息、HTTP 状态码 (403)、与 quota/rate 错误优先级测试，以及负面测试（确保不误报）。测试覆盖充分，有力地验证了新的诊断逻辑的正确性。

3. 前端代码 (apps/dsa-web/src/components/settings/LLMChannelEditor.tsx)：

   • 前端 UI 响应增加了 LLM_ERROR_LABELS 中的 请求被拦截 标签，并在 LLM_REASON_HINTS 中为 provider_blocked 提供了详细、有指导性的排障提示（如检查账号风控、地域限制、模型权限等），直接解决了用户面临的排查困境。

4. 前端测试 (apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx)：

   • 新增的 UI 测试用例验证了 provider_blocked 提示的正确显示，并且关键性地断言了不显示不相关的网络排障和模型列表调整建议，保证了用户排障信息的聚焦性和准确性。

5. 文档 (docs/*.md)：

   • docs/CHANGELOG.md 已同步更新，准确记录了本次修复。
   • docs/LLM_CONFIG_GUIDE.md 和 docs/LLM_CONFIG_GUIDE_EN.md 新增了关于 details.reason=provider_blocked 的解释和排障指导，确保了用户在配置过程中能够获取最新的诊断信息。
   • docs/llm-providers.md 在诊断表格中新增了 provider_blocked 的条目，并更新了相关说明，进一步完善了错误诊断文档。
   • README.md 未更新的理由（非首页级能力变化）是合理的。

CI 检查状态

• 静态检查总体结果: ✅ 通过
• Python 语法检查 (py_compile): ✅ 通过
• Flake8 严重错误检查 (E9/F63/F7/F82): ✅ 通过
• PR 描述中明确提供了 ./scripts/ci_gate.sh (backend-gate: all checks passed) 以及前端 npm run test、npm run lint、npm run build 等所有关键验证命令的成功输出，CI 覆盖全面且已通过。

---

💡 提示: 请确保代码已通过本地测试，并遵循项目代码规范。

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bb7cb6ae0a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ZhuLinsen]

评审结论

• 必要性：通过。Issue #1223 指向的误分类会直接误导用户排查方向，本 PR 将 provider/gateway blocked 独立诊断有明确修复价值。
• 是否有对应 issue：有，Fixes #1223。
• PR 类型：fix/test/docs。后端错误分类、Web 提示、回归测试与 LLM 配置文档均有同步更新。
• description 完整性：完整。已说明动机、改动范围、兼容性风险、未更新 README 的原因、验证命令结果和最小回滚方式，符合 AGENTS.md 对用户可见行为与 changelog 的要求。
• 是否可直接合入：可。当前 CI 为 success，改动面覆盖后端分类、Web 展示、测试和中英文文档；mergeable_state=blocked 在本仓库规则下不单独构成阻断。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

评审结论

• 必要性：通过。Issue #1223 的误分类会误导用户排查方向，拆分 provider/gateway blocked 诊断有明确修复价值。
• 是否有对应 issue：有，Fixes #1223。
• PR 类型：fix/test/docs + 修正后端错误分类、补充 Web 提示与回归测试，并同步 LLM 配置文档和 changelog。
• description 完整性：完整。已覆盖动机、范围、兼容性影响、README 未更新原因、验证命令结果和 revert 级回滚方案，符合 AGENTS.md 对用户可见行为变更的要求。
• 是否可直接合入：可。当前 CI 为 success，mergeable_state=blocked 在本仓库保护规则下不单独构成阻断；未发现必须修改的正确性问题。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

评审结论

• 必要性：通过。Issue #1223 指向的 blocked 文案误分类会误导用户排查方向，拆分为独立诊断有明确修复价值。
• 是否有对应 issue：有，Fixes #1223。
• PR 类型：fix/docs/test + 后端错误分类修复、Web 提示补充、回归测试与 LLM 配置文档同步。
• description 完整性：完整。已说明动机、范围、兼容性影响、README 未更新原因、验证命令结果和 revert 级回滚方案，符合 AGENTS.md 对用户可见行为、文档和 docs/CHANGELOG.md 的要求。
• 是否可直接合入：可。当前 CI 为 success；结合完整改动文件与 diff，本 PR 未修改 provider/model/Base URL/SDK 依赖默认值，也未改配置保存、迁移或清理逻辑；已有测试覆盖 blocked、quota/rate 优先级以及 firewall/network 负例，前序 review 指出的 firewall 误判风险已修正。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。