llm-quant/docs/TODO.md

记住，我们在开发可实战的投资助理工具，其业务水平要处在投资的前列。不要单纯只实现些简单的功能

项目待办清单

用于跟踪现阶段尚未完成或需要后续完善的工作，便于规划优先级。

1. UI 与日志增强

• 今日计划页增加“一键重评估”入口，以及日志钻取 / 历史对比视图（对齐 README 中的架构目标）。
• 回测页面支持多版本实验管理（对比不同提示/温度的收益曲线），与 tuning_results 记录联动。
• Streamlit 聚焦监控场景，补充实时指标面板、异常日志钻取与“仅监控不干预”模式的一键复评策略。

2. 数据与特征层

• 实现 app/features/factors.py 中的 compute_factors()，补齐因子计算与持久化流程。
• 完成 app/ingest/rss.py 的 RSS 拉取与写库逻辑，打通新闻与情绪数据源。
• 强化 DataBroker 的取数校验、缓存与回退策略，确保行情/特征补数统一自动化，减少人工兜底。
• 围绕动量、估值、流动性等核心信号扩展轻量高质量因子集，全部由程序生成，满足端到端自动决策需求。

3. 决策优化与强化学习

• ✅ 扩展 DecisionEnv 的动作空间（提示版本、部门温度、function 调用策略等），不仅限于代理权重调节。
• 引入 Bandit / 贝叶斯优化或 RL 算法探索动作空间，并将 portfolio_snapshots、portfolio_trades 指标纳入奖励约束。
• 将 DecisionEnv 改造为多步 episode，逐日输出状态（行情特征、持仓、风险事件）与动作，充分利用历史序列训练强化学习策略。
• ✅ 基于多步环境接入 PPO / SAC 等连续动作算法，结合收益、回撤、成交成本设定奖励与约束，提升收益最大化的稳定性。
• 在整段回测层面引入并行贝叶斯优化（TPE/BOHB）或其他全局搜索，为强化学习提供高收益初始权重与参数候选。
• 建立离线验证与滚动前向测试流程，对新策略做回测 vs. 实盘对照，防止收益最大化策略过拟合历史数据。
• 构建实时持仓/成交数据写入链路，使线上监控与离线调参共用同一数据源。
• 借鉴 TradingAgents-CN 的做法：拆分环境与策略、提供训练脚本/配置，并输出丰富的评估指标（如 Sharpe、Sortino、基准对比）。
• 完善 BacktestEngine 的成交撮合、风险阈值与指标输出，让回测信号直接对接执行端，形成无人值守的自动闭环。
• 新增多智能体多轮逻辑博弈线路：把投资场景建成重复博弈，设定主持、预测、风险等角色分轮交换信号、提出假设、相互反驳，再由执行代理落地操作；通过信念修正规则与合规约束驱动策略共识，而非依赖优化搜索。

3.2 多智能体多轮逻辑博弈实施方案

1. 角色与知识库建模
   • 定义主持（议程控制）、预测（市场观点）、风险（合规阈值）、执行（指令生成）等核心代理，并划分共享/私有信息。
   • 为每个代理建立信号源与知识库接口（行情、新闻、风险限额），设计可信度权重与更新频率。
   • 预设重复博弈、信号博弈、贝叶斯博弈等多种结构模板，支持根据市场场景切换或组合，保障架构拓展性。
2. 对话协议与消息格式
   • 设计多轮流程：议程发布→观点陈述→证据提交→反驳与驳回→共识决议→执行提示。
   • 约定消息 schema（动作类型、置信度、引用证据）及主持代理的轮次控制逻辑，确保所有代理均可追踪历史发言。
3. 信念修正与逻辑推理引擎
   • 实现迭代信念修正模块，结合可信度权重与显式逻辑规则更新各代理的市场信念。
   • 引入论证框架（Argumentation Framework）或模态逻辑规则库，支持观点检验、冲突解决与风险约束自动否决。
4. 模拟与测试环境
   • 搭建历史回测驱动的多轮博弈仿真环境，让代理在真实行情序列上互动。
   • 编写回放脚本记录每轮对话、信念轨迹与最终行动，产出可视化报告用于策略审查。
5. 执行映射与风控集成
   • 将共识决议映射到具体操作（换仓、对冲、仓位调节），并与 BacktestEngine/实盘执行接口打通。
   • 风险代理负责实时校验 VaR、仓位集中度等阈值，违规时触发主持代理重新议程或引入驳回指令。
6. 监控与评估指标
   • 设计协作质量指标（轮次收敛时间、冲突率、执行合规度）和业绩指标（收益、回撤、超额收益稳定性）。
   • 将指标纳入监控面板，与现有回测、实盘监控体系统一展示。
7. 增量迭代计划
   • 从线下模块联调 → 回测闭环 → 影子运行 → 小资金试点的节奏推进，每阶段设定成功退出标准。
   • 收集各阶段的失败案例与风险事件，迭代规则库、信念修正规则与角色职责。

3.3 代码改造计划（多轮博弈适配）

1. 架构基线评估
   • ✅ 绘制代理/部门/回测调用图并补充日志字段（见 docs/architecture_call_graph.md）。
   • ✅ 定义多轮博弈上下文结构（消息历史、信念状态、引用证据），输出数据类与通信协议草稿。
   • ✅ 在 app/agents/protocols.py 基础上补充主持/执行状态管理，实现 DialogueTrace 与部门上下文的对接路径。
   • ✅ 扩展 Decision.rounds 与 RoundSummary 采集策略，用于串联部门结论与多轮议程结果。
   • ✅ 基于 ProtocolHost 设计主持驱动的议程模板，明确多结构策略扩展方式。
   • ✅ 扩展主持对风险复核、执行总结等议程的支持，规划风控代理与回滚逻辑。
   • ✅ 落地风险议程触发条件（冲突阈值、风控代理信号、外部警报），同步更新回测策略。
   • ✅ 结合 docs/RISK_AGENT_PLAN.md 明确 RiskAgent 升级里程碑、数据接口及前端展示需求。
   • ✅ 定义 risk_assessment 数据结构（状态、原因、建议动作），在决策输出与存储层保持一致。
   • ✅ 将风险建议与执行回合对齐，执行阶段识别 risk_adjusted 并记录原始动作。
2. 数据与因子重构
   • ✅ 拆分 DataBroker 查询层（BrokerQueryEngine），补数逻辑独立于查询管道。
   • ⏳ 按主题拆分因子模块，存储缺口/异常标签。
   • ✅ load_market_data() 标注缺失字段并写入原始日志（missing_fields、derived_fields）。
   • ✅ 维护博弈结构 → 数据 scope 映射（app/agents/scopes.py，BacktestEngine.required_fields）。
   • ✅ 基于 _RefreshCoordinator 落地刷新队列与监控事件，拆分查询与补数路径。
   • ✅ 暴露 DataBroker.register_refresh_callback() 钩子，结合监控系统记录补数进度与失败重试。
   • ⏳ 统一补数回调日志格式（LOG_EXTRA.stage=data_broker），为后续指标预留数据源。
3. 多轮博弈框架
   • ✅ 在 app/agents/game.py 抽象 GameProtocol 接口，扩展 Decision 记录多轮对话。
   • ✅ 实现主持调度器驱动议程（信息→陈述→反驳→共识→执行），挂载风险复核机制。
   • ✅ 引入基础信念修正规则（app/agents/beliefs.py），汇总信念并记录冲突。
4. 执行与回测集成
   • ✅ 将回测循环改造成“每日多轮→执行摘要”，完成风控校验与冲突重议流程。
   • ⏳ 擦合订单映射层，明确多轮结果对应目标仓位、执行节奏、异常回滚策略。
   • ✅ 回测执行根据 risk_assessment 调整动作与目标权重，记录执行状态。
5. 监控与可视化
   • ⏳ 在数据库/UI 增补轮次日志、信念轨迹、冲突原因与执行结果的可视化。
   • ⏳ 定义多结构绩效指标并纳入监控面板（回测视图已提供风险事件统计与分布图）。
   • ⏳ 补充补数回调监控告警策略（成功率、排队时长、重试次数）。
   • ✅ 回测视图展示 _risk_assessment 与 execution_status，后续扩展到实时监控面板。
   • ⏳ 完善风险告警（alerts.backtest_risk）阈值与通知策略并扩展至实盘。
6. 测试与迭代治理
   • ⏳ 构建历史行情驱动的多轮仿真回放，覆盖结构切换与异常场景。
   • 新增单元/集成测试：议程流程、信念修正、补数竞态、执行映射。
   • ✅ 风险执行集成测试完成（tests/test_decision_risk_integration.py），验证风险调节与执行日志。
   • 规划上线节奏：线下 PoC → 回测闭环 → 影子运行 → 小资金试点，记录失败案例反馈改进。
   • 在测试计划中涵盖风险/执行议程的触发条件与回滚路径，确保主持扩展的行为可验证。
   • 新增针对风险复核和执行议程的集成测试场景，覆盖“冲突→复核→执行/回滚”链路。
   • 对照 docs/RISK_AGENT_PLAN.md 拆解阶段性验收项：数据校验、监控指标、影子运行报告。
   • 为 risk_assessment 输出设计单元测试（冲突触发、无冲突、外部告警模拟），确保状态与原因正确覆盖。
   • 编写执行阶段测试，验证 risk_adjusted 状态下的目标仓位与日志记录。

3.1 实施步骤（建议顺序）

1. 环境重构：扩展 DecisionEnv 支持逐日状态/动作/奖励，完善 BacktestEngine 的状态保存与恢复接口，并补充必要的数据库读写钩子。
2. 训练基线：实现基于多步环境的 PPO（或 SAC）训练脚本，定义网络结构、奖励项（收益/回撤/成交成本）和超参，先在小规模标的上验证收敛。
3. 全局搜索：在整段回测模式下并行运行 TPE/BOHB 等贝叶斯优化，产出高收益参数作为 RL 的初始化权重或候选策略。
4. 验证闭环：搭建滚动前向测试流水线，自动记录训练策略的回测表现与准实时对照，接入监控面板并输出风险/收益指标。
5. 上线准备：结合实时持仓/成交链路，完善回滚与安全阈值机制，准备 A/B 或影子跟投实验，确认收益最大化策略的稳健性。

4. 测试与验证

• 补充部门上下文构造、多模型调用、回测指标生成等核心路径的单元 / 集成测试。
• 建立决策流程的回归测试用例，确保提示模板或配置调整后行为可复现。
• 编写示例 Notebook / end-to-end 教程，参照 TradingAgents-CN 的教学方式，覆盖“数据→回测→调参→评估”全流程。
• 针对数据摄取、策略主干与回测指标建立自动化验证管线，作为无人干预运行的质量护栏。

5. 文档同步

• 随功能推进，更新 README 与讨论文档，确保描述与实际实现保持一致。

6. LLM 协同与配置

• 精简 Provider 列表、强化 function-calling 架构，完善降级和重试策略，并用配置化的角色提示与数据 Scope 提高模型行为可控性。

（最后更新：2025-09-29）