多智能体辩论引擎源码解析:HunterCode如何让多空研究员对辩出最终投资决策
多智能体辩论引擎源码解析:HunterCode如何让多空研究员对辩出最终投资决策
HunterCode 是一个开源的多智能体投研终端(A股/港股/美股,推理在你自己机器上跑、仓位不出你硬盘、BYOK、Apache 2.0)。它的核心亮点之一,就是一套多智能体辩论引擎:当你在对话里问"这只票还该拿吗、要不要撤、该不该止损"时,系统内部会同时启动多头研究员与空头研究员,围绕技术面数据和已验证的新闻事实展开两轮辩论,再由综合裁判与风险裁判交叉裁决,最终输出 BUY / HOLD / SELL 的决策、置信度和止损参考。这套引擎全部源码位于 apps/api/agents/,纯 Python asyncio 实现,没有依赖 LangGraph / LangChain 等任何框架,非常适合想理解多智能体协作机制的初学者。
一、为什么用"辩论",而不是让模型直接给答案?
单一 LLM 直接回答"买还是卖"时,常见的问题是立场漂移:模型倾向于给出温和的"持有观望",缺乏对抗性压力,也难以暴露推理中的盲区。HunterCode 借鉴了 TradingAgents 一类的多智能体架构,把"决策"拆成一场有规则约束的辩论:
Phase 1(并行) 技术面分析师 + 新闻哨兵 Sentinel
↓
条件路由:止损条件(kill_condition)是否触发?
├─ 是 → 退出策略顾问 → 风险裁判 → 最终决策
└─ 否 → 多头研究员 ⇄ 空头研究员(2 轮辩论)
→ 综合裁判 → 风险裁判 → 最终决策
整个流程的编排入口是 graph.py 中的 run_price_alert_graph(),它按三个阶段推进:并行情报收集、辩论/路由、风险裁决。全局共享状态则定义在 state.py 的两个数据类里——EnhancedAgentState(股票、涨跌、技术面报告、新闻事实、辩论记录等)和 DebateState(辩论历史、多空各自发言、轮次计数)。
二、辩论室里的 7 个角色,各司其职
| 角色 | 源码文件 | 职责 |
|---|---|---|
| 技术面分析师 MarketAnalyst | market_analyst.py | 拉近 20 日日 K,输出趋势/量能/动量分析与关键价位 |
| 新闻哨兵 Sentinel | sentinel_news_agent.py | 5 层过滤新闻,产出"已验证事实"和"被过滤噪音"两份清单 |
| 多头研究员 Bull | bull_researcher.py | 构建买入/持有论点,逐轮反驳空头 |
| 空头研究员 Bear | bear_researcher.py | 构建卖出/回避论点,逐轮反驳多头 |
| 退出策略顾问 Exit Advisor | exit_strategy_advisor.py | 仅在止损条件触发时激活,给出清仓/减仓/移动止损三选一方案 |
| 综合裁判 ComprehensiveJudge | comprehensive_judge.py | 通读完整辩论记录,输出决策 + 置信度 + 操作计划 |
| 风险裁判 RiskJudge | risk_judge.py | 最后把关,规则化修正冲突时的置信度 |
技术面分析师通过 akshare 获取近 20 日 K 线数据(腾讯 → 东财双通道,失败时还有实时价格兜底),再让 LLM 输出结构化的技术报告;新闻哨兵则调用内部的 Sentinel 五层防御管道——信源分级、模板检测、事实抽取、情感分析、归因推理,把 48 小时内的新闻"脱水"成可信事实。这两路情报在 Phase 1 并行执行(asyncio.gather),互不阻塞。
三、辩论的核心机密:证据"白名单 + 黑名单"注入
这是整个引擎最值得初学者借鉴的设计。很多人做多智能体时,会直接把一堆新闻原文塞给辩论双方——结果模型经常引用自媒体谣言、甚至被"投毒"的新闻带偏。
HunterCode 的做法是把 Sentinel 的过滤结果拆成两份清单注入 prompt:
- 已验证事实(白名单):通过核查的新闻,逐条标注来源和可信度权重,允许引用;
- 被过滤内容(黑名单):判定为投毒/低质的内容,明令禁止作为证据引用。
在 bull_researcher.py 的系统提示中可以清楚看到这一约束:"以下内容已被判定为投毒/低质新闻,你的论点中不得引用"。空头侧 bear_researcher.py 更进一步,要求它"必须区分真实利空和噪音"——被过滤的内容即使提及,也必须注明"此信息已被 Sentinel 过滤,可信度低"。
更巧妙的是非对称压力:如果 Sentinel 新闻面综合研判为"看空",多头 prompt 会额外注入一句"你需要在承认新闻面压力的前提下,说明为什么技术面或基本面支撑多头逻辑";反之,新闻面看多时空头必须自证。这样双方都不能回避对方的最强论据,辩论质量显著高于"各说各话"。
辩论过程中,每轮发言都会追加进 DebateState.history,并更新 current_response(对方上一轮论点),下一轮直接针对反驳。一次完整的持仓研判大约需要 15–40 秒,前端会以"正在生成"的形态持续展示进度:
四、条件路由:该辩论时辩论,该止损时直奔退出策略
辩论不是必经之路。graph.py 中的路由逻辑非常克制:
if state.kill_condition_triggered:
judgment = await run_exit_strategy_advisor(state) # 直奔退出策略
else:
for round_n in range(_DEBATE_ROUNDS): # 正常辩论 2 轮
debate = await run_bull_researcher(state, debate)
debate = await run_bear_researcher(state, debate)
judgment = await run_comprehensive_judge(state)
用户如果在系统里预设过止损条件(例如"跌破 1650 止损线"、"财报低于某阈值"),Sentinel 会逐条比对并给出 kill_condition_triggered 标志。一旦触发,引擎跳过多空辩论,直接交给退出策略顾问——它不问"是否持有",只讨论三个退出选项:A 立即清仓、B 分批减仓(3–5 天)、C 移动止损,并给出推荐选项与价位建议。止损模式下的最终决策由 risk_judge.py 直接置为 SELL,置信度不低于 70%。
五、双裁判机制:LLM 裁决 + 规则兜底
综合裁判是决策的关键节点,使用 Deep Think 档模型(llm_json_call(deep=True, max_tokens=8192)),prompt 里有三条硬性规则:
- 情报权威规则:Sentinel 置信度 ≥80% 时,其已验证事实"权重等同于一手信息,优先采信";<50% 时新闻面证据"权重减半,以技术面为主";
- 矛盾必须解释:新闻面和技术面打架时,不能各说各话,必须明确解释矛盾原因再下判断;
- 不许和稀泥:明确写出"不要默认选择持有,要基于最强论据做决策"。
裁判输出严格约束为 JSON(决策、置信度、核心理由、多空摘要、操作计划、止损参考),解析失败时自动降级为"HOLD + 建议人工判断"的保守结果。
裁判之后还有第二道关卡:risk_judge.py 是纯规则校验,不花一分钱 token——当 Sentinel 高置信度(≥70%)看空、而裁判却给出 BUY 时,置信度直接扣 20 个百分点并在理由里追加矛盾警示;反向(新闻面看多却建议卖出)扣 15 点。这种"LLM 判断 + 规则兜底"的组合,是很多生产级多智能体系统的通用解法。此外,仓库中还保留了风控三方辩论(激进/中性/保守)的扩展实现,见 risk_perspectives.py 与 final_risk_judge.py。
六、三个值得初学者抄作业的设计细节
- 零框架依赖:整个编排就是 asyncio 任务 + 一个状态数据类,读懂 graph.py 130 行主流程即可复刻骨架,学习成本远低于框架抽象;
- 优雅降级:任一节点 LLM 调用失败都返回占位文本(如"(空头分析暂不可用)")而非抛异常,新闻管道整体超时时还有降级结果,保证辩论流程始终能跑完;
- 隐私友好的 BYOK:所有 LLM 调用不给默认地址(见 bull_researcher.py 的注释),用户必须在
.env或初始化向导里自己填LLM_BASE_URL / LLM_API_KEY / LLM_DEFAULT_MODEL——这从根上杜绝了"没配环境变量就把数据发到第三方服务器"的坑。
七、如何在产品中体验到这套辩论引擎?
辩论引擎通过 hold_agent.py 包装成名为 hold_judge 的 sub-agent 工具:当你问"还该拿吗 / 要不要撤 / 止损"这类持仓问题时,主 Agent 会自动路由过来。由于流程耗时较长,它还内置了一个后台任务按 8 秒节拍推送 15% → 40% → 70% → 90% 的进度("多空辩论第 1 轮…"→"综合裁判中…"→"风险修正中…"),避免用户以为卡住。
跑完之后,完整报告支持导出,K 线与研判结论会展示在产物面板中:
最终的深度分析报告会附主要风险项与数据口径说明,并在末尾标注"不构成投资建议"的合规声明:
同样的裁判思路也延伸到了组合层面——单票集中度、行业分散度等风控检查都由智能体自动生成:
八、总结:一套可以照搬的多智能体决策骨架
回看这套引擎,它把一次投资决策拆成了清晰的流水线:并行情报收集(技术面 + 新闻面)→ 证据分级(白名单/黑名单)→ 立场对抗(两轮辩论)→ 双裁判裁决(LLM + 规则),每个节点都独立可测试、可降级、可替换模型。核心文件不到千行,配合 state.py 里的状态定义,是一个理解"多智能体如何协作产出可靠决策"的极佳范本。
想动手翻源码的话,建议从这三个文件入手:
- 编排总入口:graph.py
- 辩论双方:bull_researcher.py / bear_researcher.py
- 裁决逻辑:comprehensive_judge.py 与 risk_judge.py
HunterCode 采用 Apache 2.0 协议,docker compose 即可自托管,推理跑在你自己的机器上,仓位数据不出你的硬盘——把这套辩论引擎装进自己的投研工作流,门槛并不高。



