hello-agents/Co-creation-projects/lcyting-StockSage-agent

智能股票分析助手

基于HelloAgents智能体协作框架的 A 股投资分析工具，整合行情数据、财务分析、新闻舆情、智能选股、模拟交易等功能，提供数据驱动的投资决策辅助。

⚠️ 免责声明：本工具所有分析结果仅供参考，不构成任何投资建议。投资有风险，入市需谨慎。

---

功能特性

模块	特性	状态
📊 市场行情	个股实时行情、指数行情、板块行情	✅
📈 财务分析	财务指标、公司概况（描述列表排版）、十大股东（多形态表格解析）	✅
📉 股票分析体验	优先加载行情与图表，财务/概况/股东异步加载	✅
🗣️ AI舆情分析	AI 自动搜索资讯并分析市场舆情，流式输出分析结果	✅
📉 AI数据分析	AI 自动查询行情/财务数据并生成分析报告，流式输出	✅
💬 AI对话助手	协调者 Agent 解析用户需求，自动调度子 Agent，流式对话输出	✅
📰 新闻资讯	金融资讯搜索、热点快讯浏览	✅
🔍 智能选股	多条件组合筛选（行情+财务双维度）	✅
🏛️ 巴菲特评估	价值投资框架，ReflectionAgent 反思优化流式生成报告，支持下载 Markdown	✅
⭐ 自选股	妙想自选增/删/查；股票分析页与智能选股结果行「加自选」；移除需二次确认	✅
🏠 仪表盘	启动三线程并行预热（指数/自选/热点），自选直接使用 API 返回价格数据	✅
💰 模拟交易	模拟买入/卖出/撤单、持仓管理、收益曲线；下单/卖出二次确认防误触	✅
📝 历史记录	AI舆情/AI数据/巴菲特/AI对话 四种分析历史按天存储，支持查看/删除	✅
💾 文件缓存	每只股票数据存为独立 JSON 文件，当日免刷新，支持 grep 关键词搜索	✅
🧠 记忆系统	每日首启日期追踪，日切重新拉取仪表盘快照；数据持久化至 data/memory/（JSON，非 HelloAgents MemoryManager）；在已有自选记录的前提下自选数量变化会触发记忆层刷新（前端仍会实时请求自选接口）	✅
⚙️ 偏好设置	投资风格、风险偏好、行业偏好个性化定制	✅
🐳 Docker 部署	一键容器化部署，前后端分离	✅
📦 exe 打包	PyInstaller 打包为独立 exe，免安装 Python/Node.js	✅

---

项目亮点

• 多智能体协作：采用 Reflection（巴菲特评估）+ ReAct（舆情/数据分析/投资顾问）+ 协调者路由；股票分析页各 Tab 可独立流式跑 Agent，AI 对话助手由协调者按需调度子 Agent。选股、自选股、模拟交易由后端 Service 直连 skills/，不经独立 Agent
• AI对话助手：单次 LLM 路由决策（data / sentiment / advisor 组合），子 Agent 非流式跑完后由协调者整合；单维度直接推送结果，多维度由 LLM 流式生成综合答复（含篇幅与字数上限控制，见 agents/coordinator_agent.py、agents/text_truncation.py）
• 流式 AI 分析：舆情分析、数据分析、巴菲特评估均支持 NDJSON 流式输出，实时展示生成过程
• 巴菲特价值投资框架：集成完整价值投资分析体系（8份参考文档），ReflectionAgent 自我反思优化评估报告
• 文件缓存系统：每只股票的所有数据持久化到本地文件，优先读缓存再调 API，支持 grep 风格关键词检索
• 个性化投资分析：支持用户偏好存储（风险偏好、投资风格、行业偏好），经 preference_service 持久化并在 API 层提供上下文
• 全栈一体化：Vue3 前端 + FastAPI 后端 + HelloAgents 智能体 + 东方财富妙想数据，全链路自包含
• 操作安全防护：模拟交易下单/卖出、自选股移除等危险操作均需二次确认

---

技术栈

层级	技术	版本
前端	Vue3 + Element Plus + ECharts	3.x / 2.x / 5.x
后端	FastAPI + Uvicorn	0.110+
数据库	SQLite (SQLAlchemy + aiosqlite)	—
智能体	HelloAgents Optimized	0.2.9
LLM	DeepSeek / OpenAI 兼容 API	—
金融数据	东方财富妙想 API	—

---

快速开始

环境要求

• Python ≥ 3.10
• Node.js ≥ 18
• Docker ≥ 24（可选，生产部署）

配置环境变量

复制 .env.example 为 .env 并填入密钥。本地开发请保持 BACKEND_PORT=8000（与 frontend/vite.config.js 代理一致）；exe 打包运行可改为 5174。常用项如下（完整说明见 .env.example 内注释）：

# LLM 大模型（与 HelloAgents 兼容）
LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=sk-your-deepseek-key
LLM_BASE_URL=https://api.deepseek.com
# 可选：单次请求超时（秒）；后端会与更长下限合并，避免 ReAct/对话多轮过早断开
# LLM_TIMEOUT=180

# 巴菲特评估：可选反思轮数（见 .env.example 中 BUFFETT_MAX_REFLECTIONS）

# 东方财富妙想金融数据
MX_APIKEY=your-mx-apikey
# 可选：MX_API_URL、MX_CACHE_TTL_SECONDS、本地回放 MX_REPLAY_FIXTURES 等

# 服务端口：开发模式未设置时后端默认为 8000；PyInstaller exe 未覆盖时默认为 5174（与 run_exe.py 提示一致）
# 若修改 BACKEND_PORT，请同步修改 frontend/vite.config.js 中 dev server 对 /api 的 proxy.target

💡 DeepSeek API: https://platform.deepseek.com
💡 妙想 API: https://dl.dfcfs.com/m/itc4

本地开发启动

后端：

# 安装依赖（与下面等价：也可在仓库根目录执行 pip install -r requirements.txt）
pip install -r backend/requirements.txt

# 启动服务（从项目根目录）
python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload

API 文档：http://localhost:8000/docs

前端：

cd frontend
npm install
npm run dev

前端界面：http://localhost:5173（开发模式自动代理 /api 到后端 8000 端口）

Docker 部署

docker compose up -d

• 前端：http://localhost:8080
• 后端 API：http://localhost:8000/docs

详细部署说明见 DEPLOY.md

exe 独立打包部署

将前后端打包为一个独立 .exe 文件，无需安装 Python/Node.js 即可运行。

环境要求

组件	用途	仅打包时需要？
Python 3.10+	PyInstaller 打包	是
Node.js 18+	前端构建	是
PyInstaller	Python → exe	是

一键打包

# 1. 安装打包依赖
pip install pyinstaller

# 2. 执行打包脚本（从项目根目录）
python scripts/build_exe.py

运行效果

由于加载的数据比较多，最好等待数据预热后再进入界面，并且由于东方财富限制，不能挂梯子，不然会失败。

界面截图未随仓库分发；本地启动后可自行截图，或放入 outputs/screenshots/ 供文档引用。

---

项目结构

智能股票分析器/
├── README.md
├── README_EN.md
├── requirements.txt              # 根目录聚合依赖（指向 backend/requirements.txt）
├── run_exe.py                    # exe 打包运行入口
├── scripts/
│   └── build_exe.py              # PyInstaller 打包脚本
├── data/                         # 数据目录（运行时自动创建）
│   ├── stock_cache/              #   文件缓存（每只股票独立 JSON）
│   └── memory/                   #   记忆系统状态（dashboard_state.json）
├── outputs/                      # 可选：本地报告/截图输出目录
├── backend/                      # 🖥️ 后端 FastAPI
│   ├── app/
│   │   ├── main.py               #   应用入口 + 生命周期
│   │   ├── config.py             #   配置管理
│   │   ├── api/                  #   API 路由模块
│   │   │   ├── chat.py           #     AI 对话助手流式接口
│   │   │   ├── sentiment.py      #     AI 舆情流式（实现约定路径）
│   │   │   ├── data_analysis.py  #     AI 数据流式（实现约定路径）
│   │   │   ├── agent_api.py      #     舆情/数据流式实现 + /agent 兼容路径
│   │   │   ├── history.py        #     分析历史记录 CRUD
│   │   │   ├── system_browser.py #     exe/桌面：后端唤起系统浏览器打开外链
│   │   │   ├── cache_api.py      #     文件缓存管理/grep搜索
│   │   │   └── ...               #     market/financial/news/screener 等
│   │   ├── services/             #   业务逻辑层
│   │   │   ├── chat_service.py   #     对话助手调度（协调者流式）
│   │   │   ├── memory_service.py #     记忆系统（日切+仪表盘预热等）
│   │   │   ├── stock_file_cache.py#    文件缓存（grep搜索支持）
│   │   │   ├── history_service.py#     历史记录 CRUD
│   │   │   ├── screener_service.py#    智能选股（直连 skills/mx-xuangu）
│   │   │   ├── watchlist_service.py#   自选股（直连 skills/mx-zixuan）
│   │   │   ├── simulation_service.py#  模拟交易（直连 skills/mx-moni）
│   │   │   ├── preference_service.py#  用户偏好 CRUD / 上下文
│   │   │   └── ...               #     market / news / buffett 等
│   │   ├── models/               #   数据模型
│   │   │   ├── report.py         #     AnalysisReport
│   │   │   ├── history_models.py #     分析历史 ORM（SQLite）
│   │   │   ├── history.py        #     兼容 re-export AnalysisHistory
│   │   │   ├── memory_models.py  #     MemorySnapshot 等记忆数据结构
│   │   │   └── preference.py     #     UserPreference
│   │   ├── middleware/           #   中间件占位（骨架，main 中未注册）
│   │   └── utils/                #   工具
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/                     # 🎨 前端 Vue3
│   ├── src/
│   │   ├── views/                #   页面视图
│   │   │   ├── Dashboard.vue     #     仪表盘（自选直接价格展示）
│   │   │   ├── StockAnalysis.vue #     股票分析（6 Tab）
│   │   │   ├── StockScreener.vue #     智能选股
│   │   │   ├── NewsCenter.vue    #     新闻资讯
│   │   │   └── Simulation.vue    #     模拟交易（二次确认）
│   │   ├── components/           #   公共组件
│   │   │   ├── StreamOutput.vue  #     流式输出通用组件
│   │   │   ├── AIAnalysisPanel.vue#    AI分析面板
│   │   │   ├── ChatAssistant.vue #     AI对话助手
│   │   │   ├── HistoryDrawer.vue #     历史记录抽屉
│   │   │   └── NewsDetailDrawer.vue#   新闻详情
│   │   ├── api/                  #   Axios 封装
│   │   ├── router/               #   Vue Router
│   │   └── store/                #   Pinia 状态管理
│   ├── Dockerfile
│   ├── nginx.conf
│   └── package.json
│
├── agents/                       # 🤖 智能体层（仅 AI 分析 / 对话）
│   ├── agent_system.py           #   统一 Agent 管理与流式调度
│   ├── coordinator_agent.py      #   AI对话助手（路由 LLM + 子Agent顺序调用 + 整合流式）
│   ├── text_truncation.py        #   协调者输出自然边界截断
│   ├── advisor_agent.py          #   巴菲特评估 Agent（Reflection+流式）
│   ├── general_advisor_agent.py  #   普通投资顾问 Agent（ReAct）
│   ├── sentiment_agent.py        #   舆情分析 Agent（ReAct + 流式）
│   ├── data_analysis_agent.py    #   数据分析 Agent（ReAct + 流式）
│   ├── tests/                    #   智能体层单元测试
│   └── tools/                    #   ReAct 工具封装（供上述 Agent 使用）
│       ├── mx_data_tool.py       #     金融数据 → skills/金融数据
│       └── mx_search_tool.py     #     资讯搜索 → skills/资讯搜索
│
├── HelloAgents Optimized/        # 🧩 多智能体框架（StockSage 精简版）
│   └── hello_agents/
│       ├── core/                 #   LLM、Config、Agent 基类、ConversationManager 等
│       └── agents/               #   ReActAgent、ReflectionAgent（本应用实际使用）
│
├── skills/                       # 🔧 东方财富妙想 Skill（业务 API 直连层）
│   ├── 金融数据/mx-data
│   ├── 资讯搜索/mx-search
│   ├── 智能选股/mx-xuangu
│   ├── 自选股管理/mx-zixuan
│   ├── 模拟组合管理/mx-moni
│   └── 巴菲特投资思维/           #   价值投资参考文档
│
├── docker-compose.yml
├── DEPLOY.md
└── .env.example

---

API 路由概览

路由组	前缀	说明
System	/api/v1/system	GET /health、GET /config（在 main.py 注册）；POST /open-external-url 由 system_browser.py 注册在同前缀下，供 exe 场景唤起本机浏览器打开 http(s) 链接
Market	/api/v1/market	个股行情、指数、板块
Financial	/api/v1/financial	财务指标、公司概况、股东
Analysis	/api/v1/analysis	个股深度报告 POST /report/{code}、GET /report/{report_id}、列表 GET /reports
News	/api/v1/news	资讯搜索、舆情分析、热点
Screener	/api/v1/screener	条件选股、筛选条件
Watchlist	/api/v1/watchlist	自选股增删查
Simulation	/api/v1/simulation	模拟交易（买卖/撤单/持仓）
Buffett	/api/v1/buffett	巴菲特评估（Reflection / advisor 流式生成，历史类型 buffett）
Preferences	/api/v1/preferences	用户投资偏好 CRUD
Chat	/api/v1/chat	AI对话助手 NDJSON 流式 POST /stream
Sentiment	/api/v1/sentiment	AI 舆情 POST /analyze/stream（实现方案约定路径）
Data analysis	/api/v1/data-analysis	AI 数据分析 POST /analyze/stream（实现方案约定路径）
Agent（兼容）	/api/v1/agent	与上语义相同：POST /sentiment/stream、POST /data-analysis/stream
History	/api/v1/history	分析历史列表/详情/删除/清空；type 含 sentiment / data_analysis / buffett / chat
Cache	/api/v1/cache	文件缓存 grep / 统计 / 清除

完整 Swagger 文档：开发默认 http://localhost:8000/docs（端口以 .env 中 BACKEND_PORT 为准）

---

智能体协作流程

AI 对话助手流程

用户对话消息
    │
    ▼
协调者（路由 LLM，单行关键字）
    │ none → 一般对话（协调者 LLM 流式回复，或股票上下文引导）
    │ data / sentiment / advisor 或其组合
    ▼
子 Agent 顺序执行（非流式，带字数上限）
    ├── data → run_data_analysis
    ├── sentiment → run_sentiment
    └── advisor → 将已有 data/sentiment 摘要写入顾问提示 → run_advisor
    │
    ▼
面向用户的流式输出
    ├── 仅单一子 Agent → 直接推送该结果（截断至上限）
    └── 多 Agent → 协调者 LLM stream_invoke 整合为结构化答复

巴菲特评估流程

用户点击「生成巴菲特评估报告」
    │
    ▼
advisor_agent (ReflectionAgent)
    │ 收集行情/财务/舆情数据
    ├── 初始分析 → 护城河/管理层/安全边际
    ├── 自我反思 → 数据准确性/逻辑自洽性
    └── 迭代优化 → 完善报告
    │
    ▼
流式输出最终评估报告 + 自动保存历史

业务 API 与 Agent 分工

能力	实现路径
AI 舆情 / 数据分析 / 对话 / 巴菲特评估	agents/* + HelloAgents（ReAct / Reflection / 协调者）
智能选股 / 自选股 / 模拟交易 / 行情资讯查询	backend/app/services/* → skills/*（妙想 API）
用户偏好	preference_service + /api/v1/preferences

---

股票分析页结构

进入个股分析（/analysis 或 /analysis/:code，:code 可选）时，共 6 个 Tab：

Tab	内容	说明
📊 行情图表	ECharts K线 + 行情明细	优先加载
📈 财务数据	财务指标卡片 + 公司概况 + 十大股东	异步加载
🗣️ AI舆情分析	AI 自动搜索资讯分析市场情绪	流式输出
📉 AI数据分析	AI 查询行情/财务并生成报告	流式输出
🧠 巴菲特评估	ReflectionAgent 反思优化评估	流式输出
💬 AI对话助手	自由对话，自动调度子 Agent	流式输出

每个分析 Tab 均支持查看历史记录和下载报告。

---

文件缓存系统

所有股票数据自动持久化到 data/stock_cache/{股票代码}/ 目录：

data/stock_cache/
  _index.json           # 主索引
  600519/
    quote.json          # 行情数据
    financial.json      # 财务指标
    profile.json        # 公司概况
    holders.json        # 十大股东
    sentiment.json      # 舆情分析
    news.json           # 相关资讯（如有）

• 当日缓存直接返回，不限小时数；跨天数据超 24h 自动过期
• 未命中时才调用 API 并自动写回文件
• 支持 GET /api/v1/cache/search?keyword=贵州茅台 grep 风格关键词检索
• 服务重启后缓存持久保留

---

预留配置（当前未接入）

.env.example 中的 Redis、JWT 变量已在 config.py 预留，当前版本未使用（缓存走妙想进程内 TTL + 文件缓存；API 无登录鉴权）。接入计划见下方「未来计划」。

未来计划

• 增加技术指标分析（MACD、KDJ、RSI 等）
• 实现用户认证系统（JWT Token，配置项已预留）
• 添加投资组合优化算法（马科维茨模型）
• 增加 A 股交易日历和节假日判断
• 添加策略回测引擎
• 增加历史记录全文搜索

---

贡献指南

欢迎提出 Issue 和 Pull Request！

开发流程

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/your-feature
3. 提交修改：git commit -m "feat: 功能描述"
4. 推送到分支：git push origin feature/your-feature
5. 创建 Pull Request

提交规范

类型	说明
feat	新增功能
fix	修复 bug
docs	文档更新
style	代码格式调整（不影响功能）
refactor	代码重构
test	测试相关
chore	其他修改（如依赖更新）

PR 自检清单

• 代码能够正常运行，没有报错
• 相关文档已更新
• 有清晰的使用示例（如适用）
• 代码有适当的中文注释
• 处理了常见的异常情况

---

许可证

MIT License

---

作者

- GitHub: [@lcyting](https://github.com/lcyting)
- Email: lcy154745@163.com

---

致谢

• 感谢 Hello-Agents 提供的多智能体框架
• 感谢 Datawhale 开源学习社区
• 感谢 agi-queen 的开源bft-skills
• 感谢东方财富妙想 API 提供的金融数据服务
• 感谢所有GitHub开源贡献者