fix: 升级 AlphaSift 并兼容热点详情龙头股字段

[ZhuLinsen]

背景

Fixes #1694。

热点题材详情在 EastMoney 瞬断、旧缓存或 AlphaSift 合约降级路径下，可能只携带 stocks / leader_stocks 其中一个字段。旧合约或旧缓存仍会检查双字段，导致点击“选股 -> 热点题材 -> 概念股”时报“缺失字段：stocks、leader_stocks”。

AlphaSift 最近更新核对

• DSA 原锁定 AlphaSift 14e74fc0819267f7c04c3117a0dd0fe3f9b19404（AlphaSift PR [Bug] [Feature] analyzer.py导入openai库因为环境使用代理而未安装socksio包，导致创建客户端时抛出 ImportError，且报错提示为未安装openai库 #16，Tencent 日 K、Sina snapshot、source health、candidate quote context 等更新）。
• AlphaSift 最新 main 为 377049857cc04175dc3cca62121ee41adec6cdb8（PR Update daily_analysis.yml #19，LLM ranking timeout/max tokens 边界），14e74fc... 仍是其祖先。
• 对照 14e74fc...HEAD 后确认近期新增变更集中在 LLM ranking：LLM_MAX_TOKENS 默认 2048、向 ranker/LiteLLM 透传 max_tokens、timeout 后不再盲目重试无 JSON mode 请求，并关闭 LiteLLM 内层重试。
• 这组更新与 DSA 当前 AlphaSift runtime bridge 相容，风险面较窄，因此本 PR 同步升级 DSA 默认 AlphaSift pin 到 377049857cc04175dc3cca62121ee41adec6cdb8。
• 但升级本身不会解决 [Bug] 缺失字段：stocks、leader_stocks #1694：AlphaSift HotspotSummary 内含 leader_stocks，HotspotDetail 顶层仍是 stocks，hotspot_detail_to_dict() 仍只输出 summary / stocks / timeline / route。因此 DSA 仍需在 API/cache/provider 边界补齐双字段，兼容旧缓存、降级缓存和 AlphaSift summary 内 leader_stocks。

参考：

• ZhuLinsen/alphasift@14e74fc
• ZhuLinsen/alphasift@3770498
• fix: bound LLM ranking timeout work alphasift#19
• https://github.com/ZhuLinsen/alphasift/blob/main/alphasift/hotspot.py

改动

• 在 AlphaSiftService 热点详情返回前统一补齐 stocks 与 leader_stocks 双字段，并按最终 stocks 刷新 stock_count。
• 覆盖详情缓存读写、AlphaSift 合约归一化、DSA EastMoney provider 和自定义 provider 返回路径。
• Web typed API 补充 leaderStocks 可选字段。
• 将 DSA 默认 AlphaSift pin / install allow-list 从 14e74fc... 升级到 377049857cc04175dc3cca62121ee41adec6cdb8，并同步 requirements.txt、src/config.py、.env.example、专题文档和断言测试。
• .env.example 与 docs/alphasift-integration.md 补充 AlphaSift 侧 LLM_MAX_TOKENS、timeout 后不重复 JSON-mode 重试，以及迁移/回退边界。
• 更新 docs/CHANGELOG.md 的 [Unreleased] 条目。

验证

• git diff --check
• /tmp/dsa-verify-venv/bin/python -m pip install --no-deps --force-reinstall 'git+https://github.com/ZhuLinsen/alphasift.git@377049857cc04175dc3cca62121ee41adec6cdb8#egg=alphasift'
• /tmp/dsa-verify-venv/bin/python -m py_compile src/services/alphasift_service.py src/config.py
• /tmp/dsa-verify-venv/bin/python -m pytest tests/test_alphasift_api.py tests/test_config_env_compat.py tests/test_docker_entrypoint.py tests/test_system_config_service.py -q：267 passed, 12 warnings
• /tmp/dsa-verify-venv/bin/python - <<'PY' ... smoke：DEFAULT_ALPHASIFT_INSTALL_SPEC 指向 3770498...、Config.from_env().llm_max_tokens == 2048、rank_candidates_with_metadata 签名含 max_tokens
• cd apps/dsa-web && npm run lint（升级 pin 前，同一 PR 的 Web wrapper 变更）
• cd apps/dsa-web && npm run test -- src/api/__tests__/alphasift.test.ts：10 passed（升级 pin 前，同一 PR 的 Web wrapper 变更）
• cd apps/dsa-web && npm ci && npm run build（升级 pin 前，同一 PR 的 Web wrapper 变更）
• GitHub Actions（d5727d1e）：ai-governance、backend-gate、web-gate、docker-build、PR Review 相关检查均通过

说明：本机系统 Python 的 anyio 包不完整，后端 pytest 使用 /tmp/dsa-verify-venv 临时 venv 安装项目依赖后执行。未本地执行完整 ./scripts/ci_gate.sh，已以 GitHub Actions backend-gate 作为完整后端 gate 证据。

兼容性与风险

• API 仅新增 leader_stocks 兼容字段，不改变既有 stocks 字段语义。
• 旧缓存只要有 stocks 或 leader_stocks 其中一个字段，就会自动补齐另一个。
• AlphaSift pin 升级只纳入 PR Update daily_analysis.yml #19 的 LLM ranking timeout/max tokens 边界，未改变 DSA provider context、hotspot API shape 或现有 DSA LLM provider/model/base URL 迁移语义。
• 显式写在用户 .env 里的旧 ALPHASIFT_INSTALL_SPEC 不会被静默改写；要使用新 pin 需清理旧覆盖值后重建依赖/重启，或按文档完整回退 requirements.txt + src/config.py + .env.example。
• 未执行真实 EastMoney 在线点击验证，也未执行真实 LLM ranking 网络调用；已用单测覆盖降级/缓存契约，并用本地 smoke 覆盖新 pin 的配置与函数签名。

回滚

常规 revert 本 PR 即可。若只回滚 AlphaSift 版本，需要同时恢复 requirements.txt、src/config.py 的 DEFAULT_ALPHASIFT_INSTALL_SPEC、.env.example 示例和相关测试断言到旧 pin，再重建依赖/镜像/桌面后端产物；仅改 .env 会被当前 install allow-list 拒绝。

[github-actions]

🤖 自动审查报告

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

📁 修改的文件

• 📝 .env.example (+4/-2)
• 📝 apps/dsa-web/src/api/__tests__/alphasift.test.ts (+2/-0)
• 📝 apps/dsa-web/src/api/alphasift.ts (+1/-0)
• 📝 docs/CHANGELOG.md (+2/-1)
• 📝 docs/alphasift-integration.md (+7/-7)
• 📝 requirements.txt (+1/-1)
• 📝 src/config.py (+1/-1)
• 📝 src/services/alphasift_service.py (+41/-7)
• 📝 tests/test_alphasift_api.py (+85/-0)
• 📝 tests/test_docker_entrypoint.py (+1/-1)
• 📝 tests/test_system_config_service.py (+2/-2)

---

🧠 AI 代码审查意见

结论

Ready to Merge

结构化审查结果

必要性

通过

• 明确解决了 Issue [Bug] 缺失字段：stocks、leader_stocks #1694 中描述的“热点题材详情在 EastMoney 瞬断、旧缓存或 AlphaSift 合约降级路径下，可能只携带 stocks / leader_stocks 其中一个字段，导致点击时报缺失字段”的问题。
• 同时，PR 同步升级了 AlphaSift 的默认 pin，纳入了 LLM ranking timeout/max tokens 边界的优化，具有业务价值。

关联性

通过

• PR 描述明确关联到 Issue [Bug] 缺失字段：stocks、leader_stocks #1694（“Fixes [Bug] 缺失字段：stocks、leader_stocks #1694”）。

类型判定

建议类型：fix 和 chore (或 feat)

• 标题 fix: 升级 AlphaSift 并兼容热点详情龙头股字段 以 fix 开头，主要解决了字段缺失的兼容性问题，这与 fix 类型相符。
• 同时，升级 AlphaSift pin (3770498...) 并同步相关配置和文档，这更偏向于 chore 或 feat (引入新版本的改进)。
• CHANGELOG.md 中也分别以 [修复] 和 [改进] 记录了这两部分内容。总体来说，标题的 fix 是合理的，因为解决兼容性问题是主要目标。

描述完整性

完整

• 背景: 详细说明了问题根源（AlphaSift 字段缺失兼容性）和 AlphaSift 上游版本更新的细节。
• 改动: 清晰列出了所有代码、文档和配置层面的变更点。
• 验证命令与结果: 提供了详尽的本地验证步骤和结果，包括 Python 代码编译、Pytest（通过，含 warnings，但可接受）、Web 端 lint/test/build，并明确引用了 GitHub Actions 的所有 gate 检查均通过。特别是，声明了 backend-gate 通过，意味着 ci_gate.sh 或等效检查已在 CI 中执行。
• 兼容性与风险: 全面分析了 API、缓存和 AlphaSift pin 升级的兼容性影响和潜在风险，并评估为低风险。
• 回滚: 提供了明确的回滚方案。
• 用户可见能力: CHANGELOG.md 和 docs/alphasift-integration.md 已同步更新。

风险级别

低

• 关键风险:
  • 代码层面的兼容性逻辑 (_ensure_hotspot_detail_compat_fields) 设计完善，覆盖了缓存读写和 API 返回路径，能有效处理 stocks 或 leader_stocks 字段缺失的情况。
  • AlphaSift pin 升级聚焦于 LLM ranking 的边界处理，与 DSA 现有 provider context 和 hotspot API 契约无破坏性变更。
  • 文档详细说明了 .env 显式覆盖旧 pin 的行为，降低了升级过程中的意外。

必改项

无

建议项

无

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 788dbb4914

ℹ️ 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".

[chatgpt-codex-connector]

Backfill from nested summary leader stocks

When a legacy detail cache or AlphaSift detail payload has the only usable leaders under summary_detail.leader_stocks/summary.leader_stocks rather than top-level leader_stocks, this helper reads only the top-level keys, normalizes both lists to empty, and the later backfill cannot populate stocks or leader_stocks. That leaves the degraded-cache path this change is meant to fix still returning no concept stocks despite the leaders being present in the cached summary; pull the nested summary leader list before falling back to [].

Useful? React with 👍 / 👎.

[ZhuLinsen]

评审结论

• 必要性：通过，修复热点详情在 stocks / leader_stocks 单字段可用时仍被判缺字段的兼容问题，和 #1694 场景匹配。
• 是否有对应 issue：有，Fixes #1694。
• PR 类型：fix，主要是修复 AlphaSift 热点详情字段兼容与缓存/API 返回契约。
• description 完整性：完整，已说明背景、AlphaSift 版本核对、改动范围、验证、兼容性风险和 revert 级回滚方案，符合 AGENTS.md 对用户可见/API 变更的说明要求。
• 是否可直接合入：可，CI 已通过；mergeable_state=blocked 在本仓库分支保护语义下不单独构成阻断。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过，修复热点详情在 stocks / leader_stocks 单字段可用时被判缺字段的问题，并补齐 AlphaSift pin 升级后的契约兼容。
• 是否有对应 issue：有，Fixes #1694。
• PR 类型：fix，主要修复热点详情字段兼容，同时同步默认 AlphaSift 依赖 pin 与相关配置/文档/测试。
• description 完整性：完整，已覆盖背景、关联 issue、AlphaSift 外部提交来源、改动范围、验证证据、兼容性/迁移边界和 revert 级回滚方案；符合 AGENTS.md 对配置、API、用户可见行为和 CHANGELOG 同步的要求。
• 是否可直接合入：可，当前 CI 全部通过；mergeable_state=blocked 属于仓库保护策略，不构成本次代码阻断。AlphaSift/LiteLLM 相关兼容风险已在 PR 描述和文档中说明，并有锁定依赖、函数签名 smoke、单测和回滚路径支撑。

---

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