feat: [issue #1199 PR1] add settings field help dialog infrastructure

[Activer007]

PR Type

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

Background And Problem

当前设置页的配置项主要依赖短描述和外部文档。用户在配置股票列表、LLM 模型、通知渠道、WebUI 监听地址等字段时，无法在页面内直接查看完整说明、配置样
例、影响范围和注意事项。

Issue #1199 希望建设一套可维护的设置项帮助系统，而不是继续依赖 hover tooltip。短说明应常驻展示，详细说明通过 help icon 按需打开，并为后续多语言扩
展预留结构。

本 PR 实现 #1199 中建议 PR 划分的 PR1：基础设施与首批样例。

说明：

• 当前帮助内容主要同步自仓库已有事实源：.env.example、docs/full-guide.md、docs/LLM_CONFIG_GUIDE.md、docs/llm-providers.md、docs/bot/ feishu-bot-config.md、docs/deploy-webui-cloud.md 等。
• 本 PR 新增 docs/settings-help.md，用于约束后续 PR2/PR3 扩展配置帮助时的事实源、字段语义、安全边界和多语言同步规则。
• LLM 相关示例仅用于说明当前项目已文档化的配置格式，不新增第三方模型/API 运行时兼容语义。

Scope Of Change

本 PR 主要修改以下范围：

• 后端配置 schema

  • 为系统配置字段 schema 增加帮助元数据：help_key、examples、docs、warning_codes。
  • 首批为代表字段补充帮助元数据：STOCK_LIST、LITELLM_MODEL、LLM_CHANNELS、FEISHU_WEBHOOK_URL、WEBUI_HOST。

• Web 前端设置页

  • 新增 SettingsHelpButton 帮助按钮和统一帮助弹窗。
  • 接入 SettingsField，设置项标题旁显示 help icon。
  • 移除短描述外层重复 hover tooltip，避免鼠标悬停时展示与页面短说明完全重复的内容。
  • 新增 settingsHelp locale 结构，当前默认中文，预留英文内容结构。
  • 帮助弹窗支持 Esc 关闭、关闭后焦点回到触发按钮、dialog 内 focus trap。
  • 背景点击层不进入 Tab 顺序。

• 文档与变更记录

  • 新增 docs/settings-help.md，说明设置帮助元数据字段、首批覆盖范围、事实源优先级、敏感示例规则和中英文案同步边界。
  • 更新 docs/CHANGELOG.md 的 [Unreleased] 扁平条目。

• 测试

  • 增加配置 registry 和系统配置 API 对帮助元数据的覆盖。
  • 增加 SettingsField 帮助弹窗行为测试。
  • 修复验证过程中暴露的两个 CI 稳定性问题：
    • Bot 自然语言名称解析优先走本地简称匹配，避免离线测试触发 AkShare fallback。
    • 调度时间 provider 测试隔离 _INITIAL_PROCESS_ENV，避免受外部 SCHEDULE_TIME 环境变量影响。

Issue Link

Refs #1199

本 PR 覆盖 issue 中的 PR1 范围；PR2/PR3 的全量配置覆盖和模块级帮助将后续继续补齐。

Verification Commands And Results

实际执行过的验证命令：

.venv/bin/python -m py_compile api/v1/schemas/system_config.py src/core/config_registry.py
.venv/bin/python -m pytest tests/test_config_registry.py tests/test_system_config_api.py
.venv/bin/python -m pytest tests/test_bot_dispatcher_async.py -vv --durations=10
SCHEDULE_TIME=18:00 .venv/bin/python -m pytest tests/
test_main_schedule_mode.py::MainScheduleModeTestCase::test_schedule_time_provider_propagates_config_read_failures -vv
.venv/bin/python -m pytest tests/test_main_schedule_mode.py -vv --durations=10

cd apps/dsa-web && npm run test -- src/components/settings
cd apps/dsa-web && npm run lint
cd apps/dsa-web && npm run build

./scripts/ci_gate.sh

git diff --check

关键输出/结论：

• 后端配置 schema 和 registry 编译通过。
• tests/test_config_registry.py tests/test_system_config_api.py 通过。
• tests/test_bot_dispatcher_async.py 通过，目标名称解析测试已回到本地快速路径。
• tests/test_main_schedule_mode.py 通过；带 SCHEDULE_TIME=18:00 的复现场景也通过。
• Web settings 相关测试通过。
• npm run lint 通过。
• npm run build 通过；仅保留 Vite 既有 chunk size warning。
• ./scripts/ci_gate.sh ： 通过， backend-gate: all checks passed
• git diff --check 通过。

Compatibility And Risk

兼容性影响：

• 系统配置 API 仅追加字段，不移除或重命名现有字段，旧客户端可忽略新增字段。
• 不改变配置保存、校验、运行时优先级、.env 写回或环境变量覆盖语义。
• 帮助内容中的敏感示例使用安全占位符，不暴露真实密钥。
• 前端新增帮助弹窗和 focus trap，不改变配置项输入控件的数据流。
• warning_codes 目前作为后端 schema 元数据透传给前端类型，PR1 不负责渲染所有 warning code；后续 PR 可在统一提示组件中消费这些 code。

潜在风险：

• 当前仅覆盖首批代表字段，其他配置项暂时仍没有详细帮助内容。
• 帮助长文案后续需要随着 .env.example、docs/full-guide.md、docs/LLM_CONFIG_GUIDE.md 等事实源继续维护，避免说明漂移。
• Web 构建仍有既有 chunk size warning，本 PR 未处理代码拆包。

第三方模型 / API 兼容语义：

• 本 PR 不修改第三方模型调用、请求参数、路由前缀、provider fallback 或 LiteLLM 运行时选择逻辑。
• LITELLM_MODEL / LLM_CHANNELS 帮助中的示例同步自当前仓库既有事实源，用于说明配置格式，不新增运行时兼容承诺。
• 当前仓库已文档化的事实源包括：
  • .env.example 中的 LLM 配置示例。
  • docs/full-guide.md 中的 LITELLM_MODEL / LLM_CHANNELS 配置说明。
  • docs/LLM_CONFIG_GUIDE.md 中的三层优先级、Channels、Ollama、DeepSeek、Agent 继承和回退说明。
  • docs/llm-providers.md 中的 provider/channel 配置说明与 Actions 映射边界。
  • DeepSeek 模型名称等信息来自官网：https://api-docs.deepseek.com/zh-cn/
  • Google Gemini 模型名称等信息来自官方开发文档：https://ai.google.dev/gemini-api/docs/models
• 当前仓库运行时约束见 requirements.txt 与 docs/LLM_CONFIG_GUIDE.md
• 本 PR 的验证范围是 schema 透传、前端展示、设置页交互和相关离线测试；没有新增真实第三方模型连通性 smoke，也不声称新增模型/provider 可用性。
• 如果用户按帮助示例配置后遇到第三方模型不可用，应按现有 LLM 配置文档和设置页测试入口排查；恢复方式是还原 .env / 桌面端导入备份 / 清空或改回 LITELLM_MODEL、LLM_CHANNELS、LLM__* 等配置。
• 后续新增或修改具体模型/provider 示例时，需遵循 docs/settings-help.md：可追溯到当前仓库文档或官方来源；否则使用占位符或链接到事实源。

运行时配置保存 / 清理 / 迁移：

• 不会自动改写、清空或迁移用户已有配置。
• 用户恢复原行为的最小方式是 revert 本 PR；无需额外数据迁移。

Rollback Plan

如需回滚，直接 revert this PR 即可。该 PR 不包含数据库迁移，不改写用户 .env，不需要额外配置或数据回滚。

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]

🤖 自动审查报告

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

📁 修改的文件

• 📝 api/v1/schemas/system_config.py (+11/-0)
• 📝 apps/dsa-web/src/components/settings/SettingsAlert.tsx (+18/-1)
• 📝 apps/dsa-web/src/components/settings/SettingsField.tsx (+11/-6)
• 🆕 apps/dsa-web/src/components/settings/SettingsHelpButton.tsx (+280/-0)
• 📝 apps/dsa-web/src/components/settings/__tests__/SettingsField.test.tsx (+58/-0)
• 📝 apps/dsa-web/src/components/settings/index.ts (+1/-0)
• 🆕 apps/dsa-web/src/locales/settingsHelp.ts (+209/-0)
• 📝 apps/dsa-web/src/pages/SettingsPage.tsx (+8/-1)
• 📝 apps/dsa-web/src/types/systemConfig.ts (+9/-0)
• 📝 bot/dispatcher.py (+6/-1)
• 📝 docs/CHANGELOG.md (+4/-0)
• 🆕 docs/settings-help.md (+51/-0)
• 📝 src/core/config_registry.py (+99/-1)
• 📝 src/services/system_config_service.py (+13/-0)
• 📝 tests/test_bot_dispatcher_async.py (+14/-6)
• 📝 tests/test_config_registry.py (+35/-0)
• 📝 tests/test_main_schedule_mode.py (+5/-1)
• 📝 tests/test_system_config_api.py (+9/-0)
• 📝 tests/test_system_config_service.py (+21/-0)

---

🧠 AI 代码审查意见

结论

Ready to Merge

结构化审查结果

必要性

• 通过
• 理由: PR 描述中明确指出了当前设置页缺乏统一、详细的内置帮助，用户需依赖外部文档或短描述，影响配置效率和用户体验。本 PR 建设可维护的设置项帮助系统，具有明确的业务价值和用户体验提升。

关联性

• 通过
• 证据: PR 标题和描述中明确提及 Refs #1199，并说明本 PR 实现了 Issue [Feature] 提升易用性：系统设置页-配置项 增加说明对话框与配置样例 #1199 中的 PR1 范围。

类型

• 建议类型: feat, docs, test
• 理由:
  • feat: 新增设置项帮助的基础设施和前端弹窗功能。
  • docs: 新增 docs/settings-help.md 并更新 CHANGELOG.md。
  • test: 增加了新的测试用例并修复了两个 CI 稳定性问题。
  • 与 PR 描述中的类型标注完全一致，准确反映了变更内容。

描述完整性

• 完整
• 缺失项: 无。
• 理由:
  • 背景与问题：清晰阐述。
  • 变更范围：详细列出了后端、前端、文档和测试的修改。
  • 验证命令与结果：提供了非常详细的验证命令和预期结果，包括了 py_compile, pytest, npm test, npm lint, npm build 和 scripts/ci_gate.sh 的执行及通过情况。这对于Python后端改动尤为重要。
  • 兼容性与风险：全面评估了兼容性影响和潜在风险，并对第三方模型/API 兼容语义进行了详细说明。
  • 回滚方案：提供了明确的回滚方案。
  • Checklist：所有项均已勾选。
  • CI 检查状态：py_compile 和 Flake8 均已通过，且 PR 描述中明确说明了 ci_gate.sh 通过。

风险级别

• 低
• 关键风险:
  • 本 PR 主要新增功能和基础设施，对现有核心业务逻辑无破坏性改动。
  • 后端仅追加字段，不影响旧客户端兼容性。
  • 前端新增弹窗，并有完善的无障碍处理（Esc 关闭、焦点管理）。
  • 兼容性评估和回滚方案清晰，风险可控。
  • 提到的潜在风险（部分配置项仍无帮助、帮助内容维护负担、Web chunk size warning）属于已知且可接受的范围，不构成当前 PR 的直接风险。

必改项

无。

建议项

无。本次 PR 描述清晰，实现完善，测试充分，无障碍考虑周全，且文档完整，无需额外建议。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过。本 PR 对应 #1199 的设置项帮助体系 PR1，能改善设置页字段说明的可维护性和用户理解成本。
• 是否有对应 issue：有，Refs #1199。
• PR 类型：feat（包含 test），新增设置帮助弹窗/元数据基础设施，并补充对应测试。
• description 完整性：不完整。验证、兼容性、回滚说明整体较完整，但缺少新增 LLM/provider/model 示例的官方来源、当前 LiteLLM/运行时兼容证据，以及 docs/CHANGELOG.md 中非本 PR 条目的范围说明。
• 是否可直接合入：不可。CI 已通过，mergeable_state=blocked 本身不作为阻断；当前阻断点是外部模型/API 语义证据不足，以及 changelog 范围漂移需要收敛。

主要问题

1. [Compatibility blocker] apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：本 PR 在设置帮助中新增了 LITELLM_MODEL / LLM_CHANNELS 的用户可执行语义和具体模型示例，例如 provider/model 格式、DeepSeek/Gemini/Ollama 示例等。结构化检测也标记了外部模型/API 与运行时配置相关风险。PR 描述声明“第三方模型 / API 兼容语义：None”，但当前证据未看到官方来源链接、当前锁定 LiteLLM/运行时兼容验证，或这些示例仅为占位/既有文档同步的明确依据。风险是设置页帮助会成为用户配置依据，一旦模型名、provider 前缀或兼容窗口不准确，会误导用户产生运行时失败。建议补充官方来源与兼容验证，或把示例收敛为非版本化占位并明确不代表可用性背书。
2. [Process blocker] docs/CHANGELOG.md：按 AGENTS.md，用户可见能力变化需要更新 docs/CHANGELOG.md，且 [Unreleased] 应保持扁平条目；但当前 changelog 改动包含大量与本 PR 设置帮助基础设施无关的条目，例如 Webhook、EventMonitor、Anspire、MiniMax、agent_weak、README 同步等内容。风险是 release note 把其他 PR/既有变更重新归入本 PR，造成发布说明漂移和并发冲突。建议只保留本 PR 实际引入的设置帮助、相关测试和本次 CI 稳定性修复条目，或在 PR 中明确这些条目确由本 PR 引入。

---

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

[Activer007]

主要问题

1. [Compatibility blocker] apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：本 PR 在设置帮助中新增了 LITELLM_MODEL / LLM_CHANNELS 的用户可执行语义和具体模型示例，例如 provider/model 格式、DeepSeek/Gemini/Ollama 示例等。结构化检测也标记了外部模型/API 与运行时配置相关风险。PR 描述声明“第三方模型 / API 兼容语义：None”，但当前证据未看到官方来源链接、当前锁定 LiteLLM/运行时兼容验证，或这些示例仅为占位/既有文档同步的明确依据。风险是设置页帮助会成为用户配置依据，一旦模型名、provider 前缀或兼容窗口不准确，会误导用户产生运行时失败。建议补充官方来源与兼容验证，或把示例收敛为非版本化占位并明确不代表可用性背书。

关于帮助信息和具体模型示例的说明：当前帮助内容不是凭空写，基本来自 .env.example、docs/full-guide.md、docs/LLM_CONFIG_GUIDE.md、docs/llm-providers.md、docs/bot/feishu-bot-config.md、docs/deploy-webui-cloud.md 本质上是将文档内容优化并写入对应的配置项帮助窗口中；

如果只是使用占位符，虽然没有问题，但失去了示例和帮助用户的用途；

2. [Process blocker] docs/CHANGELOG.md：按 AGENTS.md，用户可见能力变化需要更新 docs/CHANGELOG.md，且 [Unreleased] 应保持扁平条目；但当前 changelog 改动包含大量与本 PR 设置帮助基础设施无关的条目，例如 Webhook、EventMonitor、Anspire、MiniMax、agent_weak、README 同步等内容。风险是 release note 把其他 PR/既有变更重新归入本 PR，造成发布说明漂移和并发冲突。建议只保留本 PR 实际引入的设置帮助、相关测试和本次 CI 稳定性修复条目，或在 PR 中明确这些条目确由本 PR 引入。

docs/CHANGELOG.md 已经修改；

[ZhuLinsen]

评审结论

• 必要性：通过。对应 #1199 的设置项帮助体系 PR1，能降低配置项理解成本并为后续扩展提供基础设施。
• 是否有对应 issue：有，Refs #1199。
• PR 类型：feat + test。新增设置帮助元数据、前端帮助弹窗，并补充后端/API/前端测试。
• description 完整性：不完整。验证、兼容性、回滚说明较完整，但 LLM/provider/model 示例与 LiteLLM 相关用户可执行语义缺少明确来源和兼容性验证说明。
• 是否可直接合入：不可。CI 已通过，mergeable_state=blocked 本身不作为阻断；当前阻断点是外部模型/API 配置帮助文案的事实来源与兼容性证据不足。

主要问题

1. [Compatibility blocker] apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：本 PR 新增了 LITELLM_MODEL / LLM_CHANNELS 的用户可执行帮助语义和具体示例，例如 provider/model 格式、DeepSeek/Gemini/Ollama 示例、渠道优先级说明等。虽然 PR 描述声明“不修改第三方模型调用语义”，但这些内容会直接指导用户在 Web 设置页填写模型、provider、Base URL 相关配置；结构化检测也已标记外部模型/API 与运行时配置风险。当前描述没有给出对应官方来源链接、当前锁定 LiteLLM/运行时兼容验证、以及旧配置/错误示例的回退说明。风险是用户按帮助弹窗填写后可能保存不可用或不兼容的模型配置。建议补齐具体来源与验证证据，或将示例收敛为仓库内已验证、已文档化的通用格式。
2. [Process blocker] docs/CHANGELOG.md 已按 AGENTS.md 更新，但本次是用户可见的设置页交互与帮助体系变更，除 changelog 外未看到对应 docs/* 专题文档说明新增帮助元数据字段、首批覆盖范围、后续维护来源或文案同步规则。已有通用配置文档可以作为事实源，但本次新增的 in-app help 维护语义尚未说明，后续 PR2/PR3 扩展时容易出现文案漂移。建议补一段轻量专题说明或在现有设置/WebUI 文档中说明维护边界。

---

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

[Activer007]

主要问题

1. [Compatibility blocker] apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：本 PR 新增了 LITELLM_MODEL / LLM_CHANNELS 的用户可执行帮助语义和具体示例，例如 provider/model 格式、DeepSeek/Gemini/Ollama 示例、渠道优先级说明等。虽然 PR 描述声明“不修改第三方模型调用语义”，但这些内容会直接指导用户在 Web 设置页填写模型、provider、Base URL 相关配置；结构化检测也已标记外部模型/API 与运行时配置风险。当前描述没有给出对应官方来源链接、当前锁定 LiteLLM/运行时兼容验证、以及旧配置/错误示例的回退说明。风险是用户按帮助弹窗填写后可能保存不可用或不兼容的模型配置。建议补齐具体来源与验证证据，或将示例收敛为仓库内已验证、已文档化的通用格式。

2. [Process blocker] docs/CHANGELOG.md 已按 AGENTS.md 更新，但本次是用户可见的设置页交互与帮助体系变更，除 changelog 外未看到对应 docs/* 专题文档说明新增帮助元数据字段、首批覆盖范围、后续维护来源或文案同步规则。已有通用配置文档可以作为事实源，但本次新增的 in-app help 维护语义尚未说明，后续 PR2/PR3 扩展时容易出现文案漂移。建议补一段轻量专题说明或在现有设置/WebUI 文档中说明维护边界。

已经补充和修改 PR 描述，增加 docs/settings-help.md 文档

[ZhuLinsen]

评审结论

• 必要性：通过。对应 #1199 的设置项帮助体系 PR1，能降低设置页配置项理解成本并为后续扩展提供基础设施。
• 是否有对应 issue：有，Refs #1199。
• PR 类型：feat（兼具 docs/test），新增设置帮助元数据、前端帮助弹窗和对应文档/测试。
• description 完整性：不完整。验证、兼容性、回滚说明整体充分，但缺少本 PR 新暴露 WEBUI_HOST 可编辑入口后“保存不会动态重绑当前 WebUI 监听地址、需要重启生效”的用户提示/验证说明。
• 是否可直接合入：不可。CI 已通过，mergeable_state=blocked 本身不作为阻断；当前阻断点是 WEBUI_HOST 被新增为可编辑配置后存在运行时生效语义误导。

主要问题

1. [Correctness blocker] src/core/config_registry.py、apps/dsa-web/src/locales/settingsHelp.ts、src/services/system_config_service.py：本 PR 新增注册并展示 WEBUI_HOST，帮助文案说明它控制 WebUI 监听地址、云服务器/外部访问通常使用 0.0.0.0。但当前服务监听地址是在进程启动时传给 uvicorn.run 的，设置页保存只会写入 .env 并重载配置对象，不会让已运行的 WebUI/API 进程重新 bind host。现有 _build_explainability_warnings 只覆盖部分启动期配置，未覆盖 WEBUI_HOST，测试也未验证该提示。风险是用户在 Web 设置页保存 WEBUI_HOST=0.0.0.0 后看到“配置已更新/已重载”，但公网/局域网访问仍不会生效，直到重启进程。建议要么本 PR 暂不暴露该字段，要么将 WEBUI_HOST 明确纳入启动期配置提示，在帮助文案和保存 warning 中说明需重启，并补对应回归测试；WEBUI_PORT 已有类似旧模式，本 PR 不应继续扩大这个误导面。

---

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

[Activer007]

1. [Correctness blocker] src/core/config_registry.py、apps/dsa-web/src/locales/settingsHelp.ts、src/services/system_config_service.py：本 PR 新增注册并展示 WEBUI_HOST，帮助文案说明它控制 WebUI 监听地址、云服务器/外部访问通常使用 0.0.0.0。但当前服务监听地址是在进程启动时传给 uvicorn.run 的，设置页保存只会写入 .env 并重载配置对象，不会让已运行的 WebUI/API 进程重新 bind host。现有 _build_explainability_warnings 只覆盖部分启动期配置，未覆盖 WEBUI_HOST，测试也未验证该提示。风险是用户在 Web 设置页保存 WEBUI_HOST=0.0.0.0 后看到“配置已更新/已重载”，但公网/局域网访问仍不会生效，直到重启进程。建议要么本 PR 暂不暴露该字段，要么将 WEBUI_HOST 明确纳入启动期配置提示，在帮助文案和保存 warning 中说明需重启，并补对应回归测试；WEBUI_PORT 已有类似旧模式，本 PR 不应继续扩大这个误导面。

针对 WEBUI_HOST 指出的 correctness blocker，已补充启动期配置说明与保存 warning：

• src/services/system_config_service.py
  • 将 WEBUI_HOST / WEBUI_PORT 纳入启动期监听配置提示。
  • 保存后明确提示：已写入 .env，但当前 WebUI/API 进程不会重新绑定监听地址或端口，需要重启进程、Docker 容器或服务管理器后生效。
• apps/dsa-web/src/locales/settingsHelp.ts
  • 中英文帮助文案均补充说明：WEBUI_HOST 仅在进程启动读取时影响 bind host。
  • 设置页保存不会让当前运行进程 rebind，需要重启后生效。
• src/core/config_registry.py
  • WEBUI_HOST.warning_codes 增加 restart_required。
• tests/test_system_config_service.py
  • 新增回归测试，覆盖保存 WEBUI_HOST / WEBUI_PORT 时返回启动期监听配置 warning。

另外，同 commit 中也修正了设置页保存成功 toast 的可读性问题：

• 在 SettingsAlert 中新增 presentation="toast" 统一样式。
• toast 使用更不透明背景，并参考帮助窗口顶部高光条样式增加顶部亮色渐变条。
• 页面只声明 presentation="toast"，避免局部散落样式。

[ZhuLinsen]

评审结论

• 必要性：通过。本 PR 对应 #1199 的设置项帮助体系 PR1，能降低设置页配置理解成本并建立后续扩展基础设施。
• 是否有对应 issue：有，Refs #1199。
• PR 类型：feat（兼具 docs/test），新增设置帮助元数据、前端帮助弹窗、维护文档和相关测试。
• description 完整性：不完整。验证、兼容性、回滚说明整体充分，但 LLM/provider/model 示例仍缺少官方来源链接与当前 LiteLLM/运行时兼容证据。
• 是否可直接合入：不可。docker-build 仍在进行中，且 LLM 帮助文案中的用户可执行模型/provider 示例还存在兼容性证据缺口。

主要问题

1. [Compatibility blocker] apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：设置帮助中直接展示了 LITELLM_MODEL / LLM_CHANNELS 的 provider/model 格式、DeepSeek/Gemini/Ollama 示例、Base URL 配置方式和渠道优先级说明。这些内容会指导用户填写运行时配置；结构化检测也标记了外部模型/API 兼容风险。PR 描述已说明不修改运行时调用逻辑，也给出了仓库内事实源，但仍未附对应官方来源链接、当前锁定 LiteLLM/运行时兼容验证证据。按仓库 AGENTS.md 对配置语义、三方依赖和用户可见能力的要求，这部分需要补齐来源或收窄为不承诺具体可用性的占位示例后再合入。
2. [Process blocker] 当前 CI 仍未全部完成：docker-build 状态为 in_progress。根据仓库验证矩阵，docker-build 属于阻断项；即使 backend-gate、web-gate、ai-governance 已通过，也应等待该检查完成后再判断最终可合入性。

---

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

[Activer007]

1. [Compatibility blocker] apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：设置帮助中直接展示了 LITELLM_MODEL / LLM_CHANNELS 的 provider/model 格式、DeepSeek/Gemini/Ollama 示例、Base URL 配置方式和渠道优先级说明。这些内容会指导用户填写运行时配置；结构化检测也标记了外部模型/API 兼容风险。PR 描述已说明不修改运行时调用逻辑，也给出了仓库内事实源，但仍未附对应官方来源链接、当前锁定 LiteLLM/运行时兼容验证证据。按仓库 AGENTS.md 对配置语义、三方依赖和用户可见能力的要求，这部分需要补齐来源或收窄为不承诺具体可用性的占位示例后再合入。

我们当前的帮助说明来源于具体的文档解释，我们的项目并没有第三方的官方说明和文档，我们自己的文档即为官方文档；

2. [Process blocker] 当前 CI 仍未全部完成：docker-build 状态为 in_progress。根据仓库验证矩阵，docker-build 属于阻断项；即使 backend-gate、web-gate、ai-governance 已通过，也应等待该检查完成后再判断最终可合入性。

docker-build 已经完成；

[ZhuLinsen]

跟进结论

• 结论：部分接受 + PR 描述已补充“不修改运行时调用逻辑”和仓库内事实源，通用 LLM 渠道/优先级语义可以收缩为既有模式延续，但设置页新增的具体模型示例仍是用户可执行配置提示，证据还不够闭环。
• 是否仍有阻断：有 + CI 已全部通过且 mergeable_state=blocked 不单独构成阻断，但 LLM 帮助文案中具体 provider/model 示例仍缺少可追溯来源或兼容性说明，可能误导用户按当前 UI 示例直接配置不可用模型。

说明

1. apps/dsa-web/src/locales/settingsHelp.ts：LITELLM_MODEL 帮助文案直接推荐 deepseek/deepseek-v4-flash、gemini/gemini-3.1-pro-preview、ollama/qwen3:8b，这些不是单纯内部字段说明，而是设置页里会指导用户填写的具体运行时值；当前讨论只说明“同步自仓库既有事实源”，还没有证明这些具体模型名在当前 LiteLLM/项目运行时下仍可用。
2. src/core/config_registry.py 与前端帮助文案共同把 LITELLM_MODEL / LLM_CHANNELS 作为首批帮助元数据暴露给系统配置 API 和 Web 设置页；因此这里的风险应收窄为“新增 UI 帮助语义中的具体外部模型示例缺少来源/兼容证据”，而不是继续笼统说 PR 修改了第三方调用逻辑。
3. WEBUI_HOST 争议点目前可以关闭：最新快照中的 apps/dsa-web/src/locales/settingsHelp.ts 已明确写出设置页保存只写入 .env 并重载配置对象，不会让当前进程重新绑定监听地址，且提示修改后需要重启进程、容器或服务管理器。
4. 当前 CI 状态为 success；ai-governance、backend-gate、docker-build、web-gate 均已通过。当前阻断不来自 CI，也不来自分支保护状态。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过。本 PR 对应 #1199 的设置项帮助系统 PR1，新增 schema 元数据、前端帮助弹窗和维护文档，有明确用户价值。
• 是否有对应 issue：有，Refs #1199。
• PR 类型：feat + docs + test，核心是新增设置帮助基础设施，同时补充文档与测试。
• description 完整性：完整。已说明范围、验证命令、兼容性、外部模型/API 示例来源、运行时配置不迁移不清理，以及 revert 级回滚方案，符合本仓库 AGENTS.md 对用户可见变更、文档和 CHANGELOG 的要求。
• 是否可直接合入：不可。当前结构化事实显示 PR 与目标分支存在冲突，需先解决冲突后再确认 CI 结果；除冲突外，未发现新的明确阻断性实现问题。

主要问题

1. [Process blocker] 当前 merge 状态为存在冲突，当前不能直接合并。CI 已通过，但冲突解决后可能改变最终 diff，需要在 resolved 后重新确认受影响文件与 CI 状态。

---

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

[Activer007]

主要问题

1. [Process blocker] 当前 merge 状态为存在冲突，当前不能直接合并。CI 已通过，但冲突解决后可能改变最终 diff，需要在 resolved 后重新确认受影响文件与 CI 状态。

已经解决冲突，并提交

[ZhuLinsen]

评审结论

• 必要性：通过，本 PR 对应 #1199 的设置项帮助基础设施，能降低 Web 设置页配置理解成本并为后续覆盖更多字段铺底。
• 是否有对应 issue：有，Refs #1199。
• PR 类型：feat（兼具 docs/test），新增配置帮助元数据、前端帮助弹窗、维护文档和对应测试。
• description 完整性：完整，已说明范围、验证结果、兼容性、外部模型/API 示例来源、运行时配置不迁移不清理，以及 revert 级回滚方案，符合 AGENTS.md 对用户可见变更、文档与 CHANGELOG 的要求。
• 是否可直接合入：可，当前 CI 为 success，冲突已解决；mergeable_state=blocked 仅表示分支保护/权限限制，不单独构成阻断。

---

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