Web 界面快速体验：可视化多智能体协作
文档摘要
Web 界面快速体验：可视化多智能体协作 难度：动手 如果你觉得命令行不够直观，Web 应用提供画布式体验：把 Agent 当作节点摆在流程图上，连线后运行，更容易「看见」分析师如何汇入风控与组合管理。对零基础读者，这往往是更友善的入口。本篇结合 与后端架构说明，解释 Web 路线与 CLI 如何共用同一业务内核。 本文你将学到 Web 路线适合什么样的学习目标 前后端分工与启动思路（概念级） 画布上节点与连线的业务含义 在界面中阅读结果时如何沿用「三层读报法」 免责声明 Web 界面与命令行一样，仅用于教育与研究。界面中的运行按钮不会连接券商，不会执行真实交易。任何图表与建议都不构成投资意见。
Web 界面快速体验：可视化多智能体协作
难度：动手
如果你觉得命令行不够直观，Web 应用提供画布式体验：把 Agent 当作节点摆在流程图上，连线后运行，更容易「看见」分析师如何汇入风控与组合管理。对零基础读者，这往往是更友善的入口。本篇结合 app/README.md 与后端架构说明，解释 Web 路线与 CLI 如何共用同一业务内核。
本文你将学到
- Web 路线适合什么样的学习目标
- 前后端分工与启动思路（概念级）
- 画布上节点与连线的业务含义
- 在界面中阅读结果时如何沿用「三层读报法」
免责声明
Web 界面与命令行一样，仅用于教育与研究。界面中的运行按钮不会连接券商，不会执行真实交易。任何图表与建议都不构成投资意见。
为什么值得打开 Web
可视化优势：
- 用拖拽理解「并行分析 → 风控 → 组合」
- 演示给同学或同事时，比滚动终端更易懂
- 减少记忆 CLI 参数的心理负担
- 部分版本支持保存/加载流程图，便于重复实验
不变的事实：底层仍是 LangGraph 工作流 + 同一类 Agent 实现；不会因为界面好看就变成真实交易软件。
系统组成（依据 app 说明）
应用目录文档描述的标准架构：
| 组件 | 技术栈 | 职责 |
|---|---|---|
| 后端 | FastAPI | 提供 REST API，触发对冲基金运行与回测 |
| 前端 | React + Vite | 画布编辑、参数表单、结果展示 |
| 核心库 | 项目根 src/ |
Agent、工作流、回测引擎 |
一键脚本（如 run.sh / run.bat）会检查 Node、Python、Poetry，安装依赖并启动双端。手动路线则分两个终端：后端 uvicorn、前端 npm run dev。本地访问时，前端通常占用 5173 端口，后端 API 占用 8000 端口（以实际配置为准）。
启动思路（概念级，四步）
- 同样先配
.env：与 CLI 完全相同，至少 LLM + 金融数据密钥。 - 安装依赖：根目录 Poetry + 应用前后端各自依赖。
- 启动服务：脚本一键启动，或手动双终端。
- 浏览器打开本地前端：在画布中添加节点并运行。
若遇「uvicorn 找不到」等错误，应用 README 建议清理 Poetry 环境后重装；Python 版本建议 3.11 左右，过新版本偶发兼容问题。
画布上的节点语义
这与 create_workflow（src/main.py）的逻辑一致：
- 多个分析师从
start_node出发（并行分析） - 全部汇入
risk_management_agent - 再进入
portfolio_manager - 最后结束
第一次建议的最小图形：
| 节点类型 | 第一次要不要 |
|---|---|
| 2–4 个分析师 | 要 |
| 风险管理 | 要（或界面规则自动插入） |
| 组合管理 | 要 |
| 一次十几个名人 | 不要 |
若界面允许分析师直连组合管理，后端往往会自动插入风控，避免绕过 remaining_position_limit——这是安全与一致性设计，不是故障。
表单参数与 CLI 的对应关系
Web 表单字段在概念上对应 CLIInputs（src/cli/input.py）：
| 界面概念 | CLI 对应 |
|---|---|
| 股票列表 | --ticker |
| 日期范围 | --start-date / --end-date |
| 分析师多选 | --analysts 或交互复选 |
| 模型选择 | --model / Ollama 开关 |
| 初始资金 | --initial-cash |
| 保证金比例 | --margin-requirement |
区别仅在于：Web 用图形与表单收集，CLI 用 argparse + questionary。提交后，后端组装相同形状的 portfolio 与 AgentState 输入，调用 run_hedge_fund 或 BacktestEngine。
在 Web 里读结果
阅读方法与命令行篇《如何读懂输出结果》完全相同：
- 先看组合管理最终建议（action、quantity、confidence）。
- 点开冲突最大的分析师，阅读 reasoning。
- 确认 quantity 是否被限额压缩——若界面展示风控字段，直接查看
remaining_position_limit；若没有，对比「现金可买股数」与建议 quantity。 - 利用界面按节点展开的优势：比终端表格更易跳转到单个 Agent 输出。
可把 Web 当作「带图形的会议室速记」：节点是发言人，连线是发言顺序，右侧面板是会议纪要。
Web 回测体验
应用后端通常也暴露回测 API，底层实例化 BacktestEngine 并传入 run_hedge_fund。界面上你可能选择起止日期、初始资金后点击运行，最终看到权益曲线或表格化每日交易——语义与 poetry run python src/backtester.py 一致。同样牢记：回测是历史模拟，不是收益保证。
命令行 vs Web：如何选择
| 场景 | 推荐 |
|---|---|
| 第一次验证密钥与依赖 | CLI 更直接 |
| 向非技术同学演示 | Web 更友好 |
| 批量脚本、CI 集成 | CLI |
| 理解节点拓扑 | Web 画布 |
许多学习者两条路都走一遍：CLI 确认「能跑」，Web 确认「看懂结构」。
常见问题
Q：Web 结果与 CLI 不完全相同？
A：若分析师集合、模型、日期、随机种子任一不同，输出会有差异；尽量固定参数做对照。
Q：端口被占用？
A：关闭占用 5173/8000 的旧进程，或修改启动脚本中的端口配置。
Q：前端空白？
A：检查后端是否已启动、浏览器是否访问正确本地端口、控制台是否有跨域报错。
上手章收束
完成本篇后，你应已具备：
- 配置密钥并运行一次分析
- 用三层法阅读 CLI 输出
- 在 Web 画布上理解 Agent 协作拓扑
延伸理解章将深入回测循环与常见疑问，帮助你从「会用」走向「知其所以然」。
请打开延伸理解支柱页：同目录上级中的 04-go-further 文件夹下的《AI 对冲基金延伸理解》。