feat: [issue #1199/PR2] expand settings help coverage for core config

[Activer007]

PR Body

PR Type

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

Background And Problem

Issue #1199 希望提升系统设置页易用性：用户在配置 AI 模型、LLM Channels、数据源、搜索、通知、WebUI、认证和调度等高频字段时，可以直接在页面内查看用途、取值说明、配置样例、影响范围和注意事项。

PR1 #1204 已完成设置帮助基础设施、首批代表字段和统一帮助风格。本 PR 继续实现 issue #1199 建议拆分中的 PR2：扩展核心配置覆盖，并让 LLMChannelEditor 内部字段接入相同风格。

本 PR 仍保持帮助信息分层原则：后端注册表提供稳定元数据，前端 locale 维护中英文长文案，现有文档继续作为配置事实源。

Scope Of Change

本 PR 是 issue #1199 的 PR2，实现范围与 issue 中“核心配置覆盖”提议对齐：

• AI 模型运行时帮助覆盖：Agent 主模型、fallback 模型、LiteLLM YAML 路由、temperature、provider keys、OpenAI-compatible Base URL。
• LLM Channels 编辑器内部字段帮助覆盖：渠道名、协议、Base URL、API Key、模型列表、能力检测、主模型、Agent 主模型、fallback、Vision、temperature。
• 数据源与搜索帮助覆盖：Tushare、实时行情优先级、实时技术指标、搜索 API Key、SearXNG、筹码分布、新闻窗口。
• 通知帮助覆盖：企业微信 Webhook、Telegram、邮件、Discord/Slack、报告输出、Webhook SSL 校验。
• WebUI / auth / schedule / proxy 帮助覆盖：Host、Port、登录保护、可信反向代理、定时任务、交易日检查、HTTP 代理。

修改文件范围：

• src/core/config_registry.py

  • 为核心配置字段补充帮助元数据：help_key、examples、docs、warning_codes。
  • 覆盖字段包括：AGENT_LITELLM_MODEL、LITELLM_FALLBACK_MODELS、LITELLM_CONFIG、LLM_TEMPERATURE、provider keys、OPENAI_BASE_URL、 TUSHARE_TOKEN、TAVILY_API_KEYS、NEWS_STRATEGY_PROFILE、通知字段、报告字段、WebUI/auth/schedule/proxy 字段等。
  • 将 SCHEDULE_TIME 从必须重启类 warning 中拆出，使帮助元数据与实际 scheduler runtime 行为一致。

• src/services/system_config_service.py

  • 细化 SCHEDULE_TIME 保存后的用户提示：
    • 已运行 schedule 模式会在下一轮检查中自动重建 daily job。
    • 当前进程未以 schedule 模式运行时，本次保存不会启动 scheduler。
  • 不改变配置保存、校验、.env 写回或调度运行逻辑。

• apps/dsa-web/src/components/settings/SettingsHelpButton.tsx

  • 扩展 helpKey、examples、docs 参数，支持 LLMChannelEditor 这类非 schema 字段直接传入帮助内容。

• apps/dsa-web/src/components/settings/LLMChannelEditor.tsx

  • 为编辑器内字段统一接入 SettingsHelpButton / HelpLabel。
  • 覆盖渠道配置字段、能力检测区域和运行时模型参数区域的帮助入口。

• apps/dsa-web/src/locales/settingsHelp.ts

  • 扩展中文与英文帮助文案。
  • 新增 settings.llm_channel.* 编辑器内字段帮助 key，并补齐核心配置字段 locale。

• docs/settings-help.md

  • 更新 PR2 覆盖范围、维护边界、editor-only help key 约定和 WebUI/schedule 重启语义。

• docs/deploy-webui-cloud.md

  • 修正 WebUI host 配置说明，使其与当前启动逻辑一致。

• docs/CHANGELOG.md

  • 在 [Unreleased] 中补充扁平 changelog 条目：
    • [文档] 扩展 Web 设置页帮助信息，补充 Agent 模型、LiteLLM fallback/config/temperature 与 LLM 渠道编辑器字段说明。

• tests/test_config_registry.py

  • 增加 TestSettingsHelpContract，验证 registry help_key 均存在 locale 文案；settings.llm_channel.* 作为 editor-only key 单独允许。
  • 增加 test_restart_warning_codes_match_runtime_behavior，验证 restart_required warning code 与运行时行为一致。
  • 增加 test_admin_auth_help_is_read_only_in_generic_settings，验证通用设置页中的认证开关保持只读。

• tests/test_system_config_api.py、tests/test_system_config_service.py

  • 覆盖 SCHEDULE_TIME 保存提示语义。
  • 覆盖空白 SCHEDULE_TIME 回退到默认 18:00 的提示行为。

• apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx

  • 增加 LLM Channels 编辑器字段帮助弹窗交互测试。

Issue Link

Refs #1199

本 PR 覆盖 issue #1199 中 PR2 的核心配置覆盖范围。后续 PR 可继续补齐 Agent、回测、报告高级字段、日志、数据库、桌面端和更细分部署配置。

Verification Commands And Results

实际执行过 / 已复核的验证命令：

source .venv/bin/activate && python -m py_compile src/core/config_registry.py src/services/system_config_service.py
source .venv/bin/activate && pytest tests/test_config_registry.py tests/test_system_config_api.py tests/test_system_config_service.py -q
git diff --check upstream/main...HEAD

关键输出/结论：

• Python 编译通过。
• 后端配置相关测试通过：183 passed, 35 warnings。
• git diff --check 通过。

参考完整验证结果：

  python -m py_compile src/core/config_registry.py src/services/system_config_service.py
  # ✅ 通过

  pytest tests/test_config_registry.py tests/test_system_config_api.py tests/test_system_config_service.py
  # ✅ 183 passed

  bash scripts/ci_gate.sh
  # ✅ all checks passed

  cd apps/dsa-web && npm run lint
  # ✅ 通过

  cd apps/dsa-web && npm run build
  # ✅ 通过，Vite chunk size warning 为既有提示

Compatibility And Risk

兼容性影响：

• 不改变配置保存、校验、运行时优先级、.env 写回或环境变量覆盖语义。
• 系统配置 schema 仅扩展/补充帮助元数据，旧客户端可继续忽略这些字段。
• LLMChannelEditor 仅增加帮助按钮和说明弹窗，不改变渠道保存、测试、模型发现或运行时模型选择逻辑。
• SCHEDULE_TIME 的保存提示从“启动期调度配置”中拆出，说明已运行 schedule 模式会在下一轮检查中重建 daily job；这与现有 scheduler provider 行为一致，不改变调度实现。
• 帮助文案中的密钥、token、Webhook 等敏感示例均使用占位符。
• LLM 相关帮助内容仅解释当前仓库已存在的配置格式和 UI 行为，不新增模型/provider 可用性承诺。
• 相关事实源仍以 .env.example、docs/full-guide.md、docs/LLM_CONFIG_GUIDE.md、docs/llm-providers.md 和对应官方文档为准。

潜在风险：

• 帮助文案覆盖面扩大，后续配置语义变化时需要同步维护 settingsHelp.ts、docs/settings-help.md 和相关专题文档。
• settings.llm_channel.* 是前端编辑器内部帮助 key，不对应单独 .env 字段；已在维护文档和测试契约中明确边界。
• Web build 仍存在既有 chunk size warning，本 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]

🤖 自动审查报告

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

📁 修改的文件

• 📝 apps/dsa-web/src/components/settings/LLMChannelEditor.tsx (+153/-12)
• 📝 apps/dsa-web/src/components/settings/SettingsHelpButton.tsx (+9/-3)
• 📝 apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx (+37/-0)
• 📝 apps/dsa-web/src/locales/settingsHelp.ts (+658/-28)
• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/deploy-webui-cloud.md (+1/-1)
• 📝 docs/settings-help.md (+25/-3)
• 📝 src/core/config_registry.py (+578/-0)
• 📝 src/services/system_config_service.py (+12/-3)
• 📝 tests/test_config_registry.py (+77/-1)
• 📝 tests/test_system_config_api.py (+26/-1)
• 📝 tests/test_system_config_service.py (+34/-1)

---

🧠 AI 代码审查意见

结论

Ready to Merge

审查结果

必要性

通过
PR 明确指出了提升系统设置页易用性的目标 (Issue #1199)，旨在为用户提供高频配置字段的用途、取值说明、配置样例、影响范围和注意事项。这具有清晰的业务价值，有助于降低用户配置门槛，避免无效重构。

关联性

通过
PR 描述中明确关联了 Issue #1199 (Refs #1199)，并说明了本 PR 覆盖了该 Issue 中 PR2 的核心配置范围。

类型

建议类型为 feat, docs, test，与 PR 实际变更内容（扩展帮助功能、更新文档、新增测试）完全匹配。

描述完整性

完整
PR 描述非常详细和完整，涵盖了背景、问题、变更范围、修改文件列表、Issue 链接、验证命令与结果、兼容性与风险、回滚方案及 Checklist。特别值得肯定的是，验证结果中明确包含了 bash scripts/ci_gate.sh 的执行情况，符合审查要求。

风险级别

低
本 PR 主要围绕配置帮助信息的扩展和前端 UI 增强，不涉及核心业务逻辑、数据库迁移或底层架构的重大修改。兼容性影响已充分评估，且回滚方案简单直接。SCHEDULE_TIME 的提示优化也与现有调度器行为一致。

必改项

无

建议项

1. 关于 pytest 警告： 验证结果中提到了 pytest 有“35 warnings”。虽然 PR 描述已注明“后端配置相关测试通过：183 passed, 35 warnings”且这不构成阻断，但长期来看，可以考虑在后续工作中逐步消除这些警告，以保持代码库的整洁性并避免潜在问题。
2. LLM_CHANNEL_HELP_DOCS 的位置： 在 apps/dsa-web/src/components/settings/LLMChannelEditor.tsx 中定义 LLM_CHANNEL_HELP_DOCS 是合适的，因为这些文档链接专门针对 LLM Channel。如果未来有其他独立的配置区域也需要类似其独有的外部文档链接列表，可以考虑将这类“专属外部文档链接”的模式抽象出来，或者保持当前组件内部定义的简洁性。目前保持现状是完全可接受的。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过。Issue #1199 要求扩展设置页帮助覆盖，本 PR 继续补齐核心配置与 LLM Channels 编辑器字段，动机明确。
• 是否有对应 issue：有，Refs #1199。
• PR 类型：feat/docs/test。主要是用户可见的设置帮助能力扩展，同时补充文档与契约测试。
• description 完整性：完整。已说明背景、范围、验证、兼容性、风险、回滚方案，并符合 AGENTS.md 对用户可见变更同步 docs/CHANGELOG.md 和专题文档的要求。
• 是否可直接合入：可。当前 CI 全部通过，改动范围与 issue/描述一致，未发现阻断性正确性或兼容性问题；mergeable_state=blocked 在本仓库保护策略下不单独构成不可合入理由。

主要问题

1. [Nice to have] apps/dsa-web/src/locales/settingsHelp.ts 新增了多处 provider/model/Base URL/LiteLLM 相关帮助文案和示例，PR 描述说明这些不新增运行时承诺、事实源仍以后续文档为准；结合当前 diff 看更像帮助说明扩展而非运行时变更，不作为阻断。但因结构化检测命中了外部模型/API 兼容风险，建议后续维护时在 docs/settings-help.md 或相关专题文档中补一个“外部 provider/model 示例不保证长期可用，以官方文档和当前依赖版本为准”的统一说明，降低示例随服务商变化漂移的风险。

---

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

[massif-01]

@Activer007 great job 😁

[Activer007]

@Activer007 great job 😁

thanks 😃