feat: [issue #1199 PR3] 补齐 Web 设置页实际展示字段帮助信息

[Activer007]

PR Type

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

Background And Problem

Issue #1199 希望提升系统设置页易用性：用户在 Web 设置页配置字段时，可以直接查看用途、取值说明、配置样例、影响范围、注意事项和相关文档链接。

PR1 #1204 已完成设置帮助基础设施与首批样例字段。
PR2 #1328 已完成核心配置覆盖与 LLMChannelEditor 内部字段帮助接入。

本 PR 实现 issue #1199 中的 PR3 registered-field slice / 阶段性补齐：聚焦 Web 设置页中实际展示/可配置字段的 Help 补齐，包括通用配置卡片当前可见字段和 AI legacy 条件可见字段。

本 PR 不声明“全量完成”，不覆盖当前 Web 设置页未展示的 .env 变量，也不处理移动端和视觉体验收口。

Scope Of Change

本 PR 修改范围：

• src/core/config_registry.py

  • 为 PR3 范围内 Web 设置页实际展示/可配置字段补充 help_key、examples、docs、warning_codes。
  • 覆盖 AI legacy、Anspire、数据源/search、Pytdx、通知高级字段等前序 PR 尚未补齐的 registered fields。
  • 合并 upstream/main 后同步覆盖新增的问股可见对话上下文压缩字段：AGENT_CONTEXT_COMPRESSION_ENABLED、AGENT_CONTEXT_COMPRESSION_PROFILE、AGENT_CONTEXT_COMPRESSION_TRIGGER_TOKENS、AGENT_CONTEXT_PROTECTED_TURNS。
  • 复用已有 help key 时保持“后端配置事实 + 前端多语言文案”的结构。
  • 不改变配置保存、校验、运行时优先级、.env 写回、环境变量覆盖或 runtime cleanup 语义。

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

  • 补齐新增 help key 的中英文帮助文案。
  • 修正 AGENT_EVENT_ALERT_RULES_JSON 文案中的 legacy JSON 字段名，使用实际 schema 的 alert_type 和 stock_code。
  • 修正 NOTIFICATION_QUIET_HOURS 文案，明确静默时段内静态通知会被抑制并跳过，不会在窗口结束后补发。
  • 对 LLM provider/model/Base URL 相关帮助文案明确“格式示例 / 既有配置路径示例”边界，不新增可用性承诺。

• tests/test_config_registry.py

  • 增加 Web 设置页可见字段 help metadata 覆盖契约。
  • 验证 registry help key 与前端 locale help key 可互相追踪。
  • 保留 settings.llm_channel.* 作为 PR2 editor-only help key 的例外边界。
  • 合并 upstream/main 后确认新增 Agent context compression 字段也纳入帮助契约。

• docs/settings-help.md

  • 将 PR3 范围明确写成 PR3 registered-field slice / 阶段性补齐。
  • 明确本 PR3 聚焦 Web 设置页实际展示/可配置字段。
  • 明确未在设置页展示的 .env 变量不属于本 PR3 切片范围。
  • 合并 upstream/main 后将 Agent 配置覆盖从 17 字段更新为 21 字段。

• docs/CHANGELOG.md

  • [Unreleased] 追加扁平条目；合并 upstream/main 后仍保持 AGENTS.md 要求的扁平格式，未新增分类标题。

Conflict Resolution Status

已解决与目标分支的冲突 / 过期 base 问题：

• 当前 PR head: 1e1dc7b6 chore: merge upstream main into settings help PR
• 当前 base: e0e5fa68 feat: add #1391 Phase 1 run diagnostics trace plumbing (#1441)
• 合并方式：git merge --no-commit --no-ff upstream/main 后手动补齐语义缺口，再提交 merge commit。
• 合并后检查过冲突标记、help metadata、locale help key、文档锚点和 CHANGELOG 扁平格式。
• 冲突后的关键语义调整是把 upstream 新增的 4 个 Agent context compression 字段纳入 PR3 help metadata / locale / tests / docs 范围。

这次冲突解决没有改动保存、校验、.env 写回、运行时优先级或模型清理逻辑。

Third-party Provider / LiteLLM Evidence And Boundary

本 PR 不新增第三方模型、API、provider fallback、Base URL 路由或 LiteLLM 运行时兼容承诺。UI help 中的 provider/model/Base URL 内容仅用于说明配置格式、既有配置字段和现有文档入口。

当前兼容说明和来源边界：

• LiteLLM 版本窗口来自仓库依赖约束：requirements.txt 中 litellm>=1.80.10,!=1.82.7,!=1.82.8,<2.0.0。
• UI 示例和 registry examples 不代表生产推荐、账号 entitlement、区域可用性、余额权限或 relay gateway 策略保证。
• 具体 provider/model/Base URL 示例若保留，必须能追溯到仓库既有文档或官方来源；无法确认的外部 endpoint 示例使用占位符，例如 https://api.example.com/v1。
• OpenAI-compatible Base URL 必须与 API Key 所属服务匹配；不要混用不同 provider 的 Key 和 Base URL。
• Legacy provider 参数仅用于兼容历史 .env 配置路径；新配置优先使用 LITELLM_MODEL、LITELLM_FALLBACK_MODELS、VISION_MODEL、LLM_TEMPERATURE 或 LLM_CHANNELS。
• 本 PR 未对每个真实 provider 执行在线 smoke；在线可用性仍需用户根据账号、region、endpoint 和当前 provider 文档自行验证。

官方 / 事实源入口：

• LiteLLM OpenAI-compatible routing: https://docs.litellm.ai/docs/providers/openai_compatible
• LiteLLM docs: https://docs.litellm.ai/
• OpenAI Chat Completions API: https://platform.openai.com/docs/api-reference/chat
• DeepSeek API docs: https://api-docs.deepseek.com/
• DashScope OpenAI-compatible mode: https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope
• Moonshot / Kimi compatibility docs: https://platform.moonshot.ai/docs/guide/compatibility
• Anthropic Messages API: https://docs.anthropic.com/en/api/messages
• Gemini OpenAI compatibility docs: https://ai.google.dev/gemini-api/docs/openai
• Gemini model docs: https://ai.google.dev/gemini-api/docs/models
• Cohere docs / LiteLLM provider page: https://docs.cohere.com/ and https://docs.litellm.ai/docs/providers/cohere
• xAI docs / LiteLLM provider page: https://docs.x.ai/docs and https://docs.litellm.ai/docs/providers/xai
• Ollama API docs: https://github.com/ollama/ollama/blob/main/docs/api.md
• 仓库专题文档：docs/LLM_CONFIG_GUIDE.md、docs/LLM_CONFIG_GUIDE_EN.md、docs/llm-providers.md、docs/settings-help.md

Save Path / Cleanup Boundary

本 PR 命中的 LITELLM_MODEL、fallback、Vision、API Base URL、legacy provider 参数等字段只是新增或复用帮助元数据，不进入 Web 保存清理路径。

具体边界：

• help_key、examples、docs、warning_codes 是 registry metadata，旧客户端可以忽略。
• 本 PR 不改 SystemConfigService 的保存、导入、校验、运行时模型清理或 .env 写回逻辑。
• 运行时模型引用清理仍只发生在既有配置保存路径中，目标是 LITELLM_MODEL、AGENT_LITELLM_MODEL、VISION_MODEL、LITELLM_FALLBACK_MODELS 等 stale runtime references。
• OPENAI_BASE_URL、provider API keys、legacy provider model/temperature/max tokens 等字段不会因为本 PR 新增帮助文案而被迁移、过滤或静默清空。
• 旧配置回退路径仍是恢复先前 .env / 桌面端导出配置并刷新设置页；本 PR不引入额外迁移脚本。

Issue Link

Close #1199

本 PR 覆盖 issue #1199 中 PR3 的 Web 设置页实际展示/可配置字段 Help 阶段性补齐范围。PR1-PR3 系列已完成 issue #1199 当前拆分目标。

Verification Commands And Results

冲突解决后重新执行过 / 复核过的验证：

# Python 语法检查
.venv/bin/python -m py_compile src/core/config_registry.py tests/test_config_registry.py
# => PASS

# flake8 严重错误（与 CI pr-review.yml 一致：E9,F63,F7,F82）
.venv/bin/python -m flake8 src/core/config_registry.py tests/test_config_registry.py --select=E9,F63,F7,F82 --count
# => 0

# 后端测试（含帮助契约双向验证和全字段覆盖断言）
.venv/bin/python -m pytest tests/test_config_registry.py -q
# => 37 passed

# System config 回归
.venv/bin/python -m pytest tests/test_system_config_service.py -q
# => 128 passed

# 前端
cd apps/dsa-web && npm run lint
# => PASS

cd apps/dsa-web && npm run build
# => PASS, built in 15.58s

# Diff hygiene
git diff --check
git diff --cached --check
# => PASS

# 后端 gate（需要把 .venv/bin 放入 PATH，确保脚本能找到 flake8）
PATH="/opt/workspace/daily_stock_analysis/.venv/bin:$PATH" ./scripts/ci_gate.sh
# => 2337 passed, 3 deselected, 8 warnings, 215 subtests passed; backend-gate: all checks passed

关键结论：

• 148/148 注册字段均有 help_key、examples、docs。
• 74 个 registry help key 已与 locale 互相追踪；settings.llm_channel.* 仍作为 PR2 editor-only help key 的明确例外。
• 合并 upstream/main 后新增的 4 个 Agent context compression 字段已覆盖 help metadata、中文/英文 locale、测试契约和维护文档。
• docs/CHANGELOG.md 的 [Unreleased] 仍保持扁平条目格式。
• 文档锚点链接已由 tests/test_config_registry.py 覆盖验证。
• GitHub CI 已在 push 后重新触发；以 PR 页面最新 check 结果为准。

Compatibility And Risk

兼容性影响：

• 系统配置 schema 仅追加/补充帮助元数据，旧客户端可忽略新增字段。
• 不改变配置保存、校验、运行时优先级、.env 写回或环境变量覆盖语义。
• 不新增第三方模型、API、provider fallback、Base URL 或 LiteLLM 运行时兼容承诺。
• 帮助文案中的密钥、token、Webhook 等示例均使用占位符。
• Web 设置页未展示的 .env 变量不纳入本 PR3 范围。
• 中英文帮助文案保持同一语义范围。

潜在风险：

• 帮助文案覆盖面扩大，后续配置语义变化时需要同步维护 src/core/config_registry.py、apps/dsa-web/src/locales/settingsHelp.ts 和 docs/settings-help.md。
• 第三方 provider/model/Base URL 示例容易被用户理解为可用性承诺；本 PR 已在帮助维护文档和 PR 描述中明确其仅为格式或既有配置路径示例，实际可用性以官方文档、账号权限和当前 LiteLLM 支持为准。
• 当前 PR 聚焦 registered-field slice，不处理移动端和视觉体验收口。

Rollback Plan

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

若用户已根据帮助文案手动修改 provider/model/Base URL 配置，回滚 PR 不会自动恢复这些手动配置；可通过桌面端导出的配置备份、POST /api/v1/system/config/import，或手动恢复历史 .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]

🤖 自动审查报告

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

📁 修改的文件

• 📝 apps/dsa-web/src/locales/settingsHelp.ts (+840/-0)
• 📝 docs/CHANGELOG.md (+2/-0)
• 📝 docs/settings-help.md (+12/-1)
• 📝 src/core/config_registry.py (+1118/-9)
• 📝 tests/test_config_registry.py (+105/-0)

---

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

[ZhuLinsen]

评审结论

• 必要性：通过。该 PR 补齐 Web 设置页实际展示字段的帮助信息，符合 issue #1199 的易用性目标，也符合 AGENTS.md 对用户可见能力变更需同步文档与 CHANGELOG 的要求。
• 是否有对应 issue：有，Close #1199。
• PR 类型：feat/docs/test。主要是新增配置帮助元数据与前端中英文帮助文案，并补充注册表覆盖测试和维护文档。
• description 完整性：基本完整。已说明背景、范围、验证、兼容性、风险、回滚方案和 EXTRACT_PROMPT 未变更；缺口是涉及 provider/model/Base URL 示例和 Anspire/OpenAI-compatible 等外部兼容语义时，未附官方来源或仓库内事实来源说明。
• 是否可直接合入：不可。CI 已通过且当前可合并，但仍有外部模型/API 与运行时配置语义的验证缺口需要澄清，避免把未经来源确认的 provider/model/Base URL/默认模型说明通过 Web 设置帮助固化给用户。

主要问题

1. [Process blocker] apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：本 PR 新增/扩展了多处用户可执行的 LLM/provider/Base URL/模型名帮助语义，例如 Anspire LLM 网关、legacy provider 参数、OpenAI-compatible Base URL、具体模型示例等。结构化检测也提示存在外部模型/API 兼容风险和运行时配置迁移相关文本。PR 描述声明“不新增第三方模型、API、provider fallback 或 LiteLLM 运行时兼容承诺”，但目前没有给出官方文档链接、当前锁定依赖/运行时兼容验证，或明确说明这些示例均来自既有仓库文档/既有行为且不会改变保存前清理、默认模型、fallback、Vision/API Base URL 迁移逻辑。风险是 Web 帮助会成为用户配置依据，若示例或生命周期/兼容说明不准确，会误导用户配置模型与网关。建议补充来源说明或收窄文案为“示例占位/以 provider 官方文档和当前 LiteLLM 支持为准”，并明确本 PR 未改动任何运行时配置清理或迁移代码。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过；补齐 Web 设置页实际展示字段的帮助信息，符合 issue #1199 的易用性目标和 AGENTS.md 对用户可见变更同步文档/CHANGELOG 的要求。
• 是否有对应 issue：有，Close #1199。
• PR 类型：feat（兼 docs/test）；主要新增配置帮助元数据、前端中英文帮助文案，并补充覆盖测试和维护文档。
• description 完整性：不完整；已覆盖范围、验证、风险和回滚，但缺少 provider/model/Base URL 等外部兼容性来源与当前运行时兼容证据，也未单独说明模型/运行时配置保存清理相关检测项的迁移/回退验证。
• 是否可直接合入：不可；CI 已通过，mergeable_state=blocked 本身不作为阻断，但下面两个兼容性/验证缺口需要先澄清或补证。

主要问题

1. apps/dsa-web/src/locales/settingsHelp.ts、src/core/config_registry.py：本 PR 新增/扩展了用户可直接参考的 LLM provider、模型名、Base URL 和 legacy 配置帮助语义，例如主模型示例、Anspire LLM 网关、legacy provider 参数、OpenAI-compatible Base URL 等。PR 描述说明“不为第三方 provider 做保证”，但当前帮助文案会在设置页直接指导用户填写；未看到官方文档/公告来源、当前锁定 LiteLLM/运行时兼容验证或明确的旧配置回退路径。风险是用户复制帮助中的 provider/model/Base URL 后遇到不兼容、废弃或路由失败。建议补充官方来源/兼容验证证据，或把具体外部模型示例收窄为占位符和仓库内已验证示例，并在文档中明确兼容边界。
2. src/core/config_registry.py：结构化检测命中默认模型、运行时模型或保存前清理逻辑相关变化；虽然 PR 描述声明不改变保存、校验、运行时优先级和 .env 写回语义，但目前验证结果主要覆盖 registry help metadata 与构建/CI，未单独证明旧的 LITELLM_MODEL、fallback、Vision、API Base URL 等用户配置在 Web 保存路径中不会被静默清空、过滤或迁移。建议补充对应回归测试或在 PR 描述中给出明确证据；如果确认只是关键词误报，也需要说明检测命中的字段只新增帮助元数据、不进入保存清理路径。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过；补齐 Web 设置页实际展示字段帮助信息，符合 #1199 的易用性目标，也符合 AGENTS.md 对用户可见变更同步文档与 CHANGELOG 的要求。
• 是否有对应 issue：有，Close #1199。
• PR 类型：feat；主要新增配置帮助元数据与前端中英文帮助文案，兼有 docs/test。
• description 完整性：不完整；已覆盖范围、验证、兼容性、风险和回滚，但涉及 provider/model/Base URL/LiteLLM 相关用户可见说明时，仍缺少官方来源链接和当前锁定依赖/运行时兼容验证证据。
• 是否可直接合入：不可；当前 merge 状态存在冲突，且外部模型/API 兼容性证据仍需补齐或收窄说明。

主要问题

1. [Process blocker] 当前 PR 与目标分支存在冲突，结构化事实显示“当前不能直接合并”。在解决冲突并确认冲突后的 diff 未改变本次帮助文案、测试契约和 CHANGELOG 格式前，不能直接合入。
2. [Process blocker] apps/dsa-web/src/locales/settingsHelp.ts 和 src/core/config_registry.py 新增了 LLM provider/model/Base URL/LiteLLM 相关帮助与示例，PR 描述虽声明不新增运行时兼容承诺，但未附对应 provider/LiteLLM 官方来源链接，也未提供当前依赖版本下这些示例格式的兼容验证证据。风险是用户会把 UI 内帮助示例理解为当前可用配置承诺；建议补充来源与验证，或把示例进一步收窄为“格式示例/以现有文档为准”的非具体模型示例。
3. [Nice to have] docs/settings-help.md 已说明本次是 PR3 registered-field slice，docs/CHANGELOG.md 也按 AGENTS.md 的 [Unreleased] 扁平格式追加了条目；README 未更新可以接受。合并前建议在冲突解决后再确认中英文帮助文案、文档锚点和测试断言仍一致。

---

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

[Activer007]

主要问题

1. [Process blocker] 当前 PR 与目标分支存在冲突，结构化事实显示“当前不能直接合并”。在解决冲突并确认冲突后的 diff 未改变本次帮助文案、测试契约和 CHANGELOG 格式前，不能直接合入。
2. [Process blocker] apps/dsa-web/src/locales/settingsHelp.ts 和 src/core/config_registry.py 新增了 LLM provider/model/Base URL/LiteLLM 相关帮助与示例，PR 描述虽声明不新增运行时兼容承诺，但未附对应 provider/LiteLLM 官方来源链接，也未提供当前依赖版本下这些示例格式的兼容验证证据。风险是用户会把 UI 内帮助示例理解为当前可用配置承诺；建议补充来源与验证，或把示例进一步收窄为“格式示例/以现有文档为准”的非具体模型示例。
3. [Nice to have] docs/settings-help.md 已说明本次是 PR3 registered-field slice，docs/CHANGELOG.md 也按 AGENTS.md 的 [Unreleased] 扁平格式追加了条目；README 未更新可以接受。合并前建议在冲突解决后再确认中英文帮助文案、文档锚点和测试断言仍一致。

已经解决PR冲突，并重新修改PR描述；

[ZhuLinsen]

评审结论

• 必要性：通过；补齐 Web 设置页实际展示字段的帮助信息，符合 #1199 的易用性目标，也符合 AGENTS.md 对用户可见变更同步文档与 CHANGELOG 的要求。
• 是否有对应 issue：有，Close #1199。
• PR 类型：feat；主要新增配置帮助元数据与前端中英文帮助文案，兼有 docs/test。
• description 完整性：完整；已说明范围、非目标、外部 provider/model/Base URL 边界、验证结果、兼容性风险、回滚方案和 EXTRACT_PROMPT 未变更。
• 是否可直接合入：可；当前 CI 为 success，mergeable_state=unknown 不能单独视为阻断，且本 PR 对模型/provider/Base URL 相关内容已限定为帮助文案和既有配置说明，没有引入保存、清理、迁移或运行时优先级变更。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过；补齐 Web 设置页实际展示字段帮助信息，符合 #1199 的易用性目标和 AGENTS.md 对用户可见变更同步文档/CHANGELOG 的要求。
• 是否有对应 issue：有，Close #1199。
• PR 类型：feat；主要新增配置帮助元数据和前端中英文帮助文案，兼有 docs/test。
• description 完整性：完整；已说明范围、非目标、外部 provider/model/Base URL 边界、验证结果、兼容性风险、回滚方案和 EXTRACT_PROMPT 未变更。
• 是否可直接合入：可；当前 CI 为 success，未发现冲突、行为正确性阻断或 AGENTS.md 流程阻断点，mergeable_state=blocked 不单独构成不可合入理由，按仓库保护规则由具备权限的维护者合入即可。

---

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