Baike.dev
Log in
Back to tool/Back to issues
#2071·daily_stock_analysis

feat: 增加多策略综合结果的类型化 API 与 Web/Desktop 展示

Author: xushengasdCreated Jul 23, 2026Updated Aug 23, 2026
Labelsenhancement

功能描述 / Feature Description

Issue #1964 已完成多策略协同分析的核心后端 MVP：

  • PR #2031：结构化 strategy opinion、canonical signal、确定性冲突检测和权威 strategy_synthesis。
  • PR #2062：1–4 个 specialist skill 受控并发、共享超时预算、失败 diagnostics、deliberation 和只读 revision projection。

当前剩余问题主要位于产品展示边界：

  1. Web 只能通过 details.rawResult.dashboard.strategy_synthesis 间接读取内部 payload，缺少正式、类型化的 Report API 字段。
  2. Web/Desktop 尚未提供多策略共识、冲突、支持/反对观点和少数派观点的结构化展示。
  3. 当前 payload 有 supporting_skills / opposing_skills，但缺少面向展示的绝对多/空/中性分布以及确定性选择的主要反对观点。
  4. revision_projection 尚未在 UI 中明确标注为非权威预览，用户无法直观区分最终建议与协同推演结果。

本 Issue 计划通过一个端到端 PR 完成：

后端展示契约 → 类型化 Report API → Web/Desktop 多语言展示 → 测试、文档和截图证据

使用场景 / Use Cases

场景 1：识别中性结果背后的策略分歧

当技术策略看多、资金策略看空、其他策略观望时，最终信号可能为 hold。

用户需要看到：

  • 哪些策略看多；
  • 哪些策略看空；
  • 哪些策略观望；
  • 最终共识等级；
  • 是否存在高级别策略冲突。

前端不能只展示一个“观望”结论，也不能自行从 raw payload 重新计算分组。

场景 2：保留主要少数派观点

当最终信号为 buy 时，如果某个高权重策略给出 sell，系统应明确展示该反对观点及理由，避免综合结果掩盖重要风险。

场景 3：区分最终建议与协同推演

revision_projection 仅用于展示采纳 softened revision 后的预览结果，不是权威最终建议。

Web/Desktop 必须明确标注：

协同推演预览，不改变系统最终建议

期望实现 / Proposed Solution

1. 扩展展示契约

在现有 strategy_synthesis 中追加以下可选字段：

{
  "schema_version": "strategy-synthesis-v1",
  "signal_distribution": {
    "bullish": {
      "count": 1,
      "weight_share": 0.42
    },
    "neutral": {
      "count": 1,
      "weight_share": 0.18
    },
    "bearish": {
      "count": 1,
      "weight_share": 0.4
    }
  },
  "primary_dissent": {
    "skill_id": "capital_flow_v1",
    "agent_name": "skill_capital_flow_v1",
    "signal": "sell",
    "confidence": 0.81,
    "reasoning": "..."
  }
}

Signal Distribution 规则

  • bullish：buy / strong_buy
  • neutral：hold
  • bearish：sell / strong_sell
  • count 只统计 valid opinions。
  • Invalid、timeout、error、no-opinion 不进入任何阵营。
  • weight_share 使用本次聚合中 valid opinions 的实际应用权重归一化。
  • 有效权重总和大于 0 时，各阵营 weight_share 总和应约等于 1。
  • 有效权重总和为 0 时，各阵营 weight_share 为 null，不得使用伪造分母。
  • 后端是唯一计算方；API、Web、Desktop 和 renderer 不得各自重新计算。

Primary Dissent 规则

  • primary_dissent 只能从 opposing_skills 中选择。
  • 排序规则：
    1. 实际应用权重降序；
    2. confidence 降序；
    3. skill_id 升序，保证稳定 tie-break。
  • 没有 opposing opinion 时返回 null。
  • 选择过程必须是确定性的，不调用 LLM。
  • 不覆盖或改变 final_signal。

2. 增加类型化 Report API 投影

在现有报告结构中追加：

report.details.strategy_synthesis

要求覆盖：

  • 同步分析响应；
  • 异步任务完成结果；
  • 历史报告详情；
  • OpenAPI/Pydantic schema；
  • Web TypeScript 类型。

API 投影至少正式定义：

  • schema_version
  • final_signal
  • weighted_score
  • confidence
  • original_confidence
  • consensus_level
  • conflict_count
  • conflict_severity
  • summary_key
  • summary_params
  • signal_distribution
  • supporting_skills
  • opposing_skills
  • primary_dissent
  • conflicts
  • 可选 deliberation
  • 可选 revision_projection

兼容要求：

  • 复用现有 normalize_strategy_synthesis_payload()，不新增平行 normalization。
  • 旧报告缺失该字段时返回 null 或不设置。
  • 空对象或 malformed 历史 payload 不得导致 API 500。
  • 列表中的非法元素应在后端边界过滤。
  • 保留现有 details.raw_result，不破坏旧客户端。
  • 只投影低敏展示字段，不暴露 raw prompt、完整工具返回、密钥或私密数据。
  • 不新增 API endpoint。

3. Web/Desktop 结构化展示

新增独立报告组件，例如：

StrategySynthesisCard

建议展示顺序：

ReportOverview
→ StrategySynthesisCard
→ ReportStrategy
→ ReportNews

首层展示：

  • 权威 final signal
  • consensus level
  • conflict severity/count
  • valid/invalid strategy count
  • bullish/neutral/bearish 分布

展开区域展示：

  • supporting strategies
  • opposing strategies
  • primary dissent
  • conflict details
  • deliberation summary
  • revision projection

UI 约束：

  • revision_projection 必须明确标记为非权威预览。
  • 不得把策略分歧等级描述成 RiskAgent 风险等级。
  • 不只依赖红色/绿色表达多空，必须同时提供文字、图标或标签。
  • reasoning 较长时默认截断并支持展开。
  • 前端只投影后端契约，不重新计算阵营、权重或主要少数派。
  • Desktop 复用 Web 组件，但必须验证桌面构建和窄窗口布局。

4. 多语言与兼容状态

支持：

  • zh
  • en
  • ko

必须覆盖：

  • 无 strategy_synthesis
  • insufficient
  • 只有一个有效策略
  • 全部策略 invalid
  • 无冲突
  • 高级别冲突
  • 无 opposing opinion
  • 旧报告缺失新增字段
  • malformed payload
  • revision preview 与 final signal 不同
  • 亮色/暗色主题
  • 宽屏/窄屏布局

核心不变量 / Invariants

  • strategy_synthesis 仍由 StrategyEngine/SkillAggregator 确定性生成。
  • LLM dashboard 不能覆盖权威 synthesis。
  • final_signal 不因本 Issue 改变。
  • revision_projection 不覆盖权威结果。
  • RiskAgent veto 保持独立风控边界。
  • Invalid opinions 不进入 Evidence Chain、分布或 primary dissent。
  • Web/Desktop 不从 rawResult.dashboard 自行构造业务结论。
  • AGENT_ARCH=single 和无 specialist opinion 的路径保持兼容。
  • 不重算或回填历史报告。

非目标 / Non-goals

本 Issue 不包含：

  • 数值离散度 σ 或 dispersion_score
  • skill outcome 评价
  • skill 表现统计
  • 动态权重或自动权重校准
  • PR #2069 的 outcome 链路
  • 数据库迁移或历史数据回填
  • 在线 LLM deliberation 默认启用
  • Agent 调度重构
  • 新增 API endpoint
  • provider/model/base URL 修改
  • Markdown、通知或普通报告布局重构

动态 outcome 和权重继续沿 #2058、#2069 及其后续独立 Issue 推进。

️ 建议影响路径 / Suggested Affected Areas

后端：

  • src/agent/skills/aggregator.py
  • src/agent/skills/synthesis.py
  • src/agent/skills/engine.py
  • src/report_language.py
  • api/v1/schemas/history.py
  • api/v1/endpoints/analysis.py
  • api/v1/endpoints/history.py

Web：

  • apps/dsa-web/src/types/analysis.ts
  • apps/dsa-web/src/components/report/StrategySynthesisCard.tsx
  • apps/dsa-web/src/components/report/ReportSummary.tsx
  • apps/dsa-web/src/components/report/index.ts
  • Web 多语言文案与组件测试

测试和文档：

  • 多策略聚合测试
  • 同步/异步/历史 API 测试
  • Web 组件测试
  • docs/multi-strategy-contract.md
  • docs/CHANGELOG.md

实际实现应优先复用现有模块，避免新增平行契约或无关重构。

✅ 验收标准 / Acceptance Criteria

后端契约

  • schema_version 稳定输出。
  • bullish/neutral/bearish count 正确。
  • Invalid opinions 不进入 signal distribution。
  • weight share 使用本次实际有效权重。
  • 有效权重为零时安全输出 null。
  • 有效权重非零时 weight share 总和约等于 1。
  • primary dissent 只来自 opposing opinions。
  • primary dissent 排序和 tie-break 确定且稳定。
  • 没有 opposing opinion 时 primary dissent 为 null。
  • 新字段不改变 final signal、consensus level 或 conflict detection。

API

  • 同步分析响应包含可选类型化投影。
  • 异步任务完成响应包含相同 shape。
  • 历史详情包含相同 shape。
  • OpenAPI schema 与实际响应一致。
  • TypeScript 类型与后端契约一致。
  • 旧报告和 malformed payload 安全降级。
  • Single-agent 报告保持兼容。

Web/Desktop

  • 正常展示最终信号、共识和冲突。
  • 展示多/空/中性分布。
  • 展示 supporting/opposing strategies。
  • 展示 primary dissent。
  • revision projection 明确标记为非权威预览。
  • 空态、insufficient、全部 invalid 和 legacy 状态正常。
  • zh/en/ko 文案完整。
  • 亮色/暗色主题正常。
  • 宽屏/窄屏和 Desktop 布局正常。
  • 不只依靠红/绿色表达状态。

质量与证据

  • 后端定向测试通过。
  • ./scripts/ci_gate.sh 通过。
  • Web lint/build 通过。
  • Desktop build 通过。
  • docs/multi-strategy-contract.md 已同步。
  • docs/CHANGELOG.md 使用 [Unreleased] 扁平格式更新。
  • PR 描述附 zh/en/ko 代表性页面截图或自动化可视证据。
  • 临时验收截图不加入仓库。

验证建议 / Verification

后端：

python -m py_compile <changed_python_files>
python -m pytest -m "not network" <相关多策略/API/历史报告测试>
./scripts/ci_gate.sh

Web：

cd apps/dsa-web
npm ci
npm run lint
npm run build

Desktop：

cd apps/dsa-desktop
npm install
npm run build

如受平台限制无法完成 Desktop 全量验证，PR 描述必须说明已验证范围和剩余风险。

兼容性与回滚 / Compatibility And Rollback

  • 新字段均为可选追加字段。
  • 旧报告和旧客户端保持兼容。
  • 不修改数据库 schema，不要求数据迁移。
  • UI 仅在存在有效 strategy_synthesis 时展示。
  • 回滚时可整体 revert 对应 PR。
  • 回滚后现有后端综合、Markdown、通知、历史报告和普通 Web 报告继续工作。
  • 已保存历史数据不需要清理或重写。

关联信息 / Related Work

  • 来源 Issue：#1964
  • Phase 1：#2031
  • Phase 2 后端：#2062
  • Skill opinion 样本采集：#2058
  • Skill opinion outcome Draft：#2069

建议后续 PR 使用：

Closes #<本 Issue 编号>
Refs #1964
  • 我愿意亲自或协助贡献该功能的实现

Source: ZhuLinsen/daily_stock_analysis

View original on GitHubView discussion on GitHub