Finance Agent

一个面向 A 股研究的多 Agent 投资分析工作台。 先不要克隆！不要克隆！代码有点问题，敬请更新

Finance Agent 试图把投研工作里最耗耐心的部分交给 Agent：从公开市场数据中抽取线索，调用 MCP 工具完成财务、行情与新闻检索，再把分析过程和最终报告以对话式界面呈现出来。

它不是一个简单的“问答 Demo”，而是一个正在演进中的智能投研控制台：后端负责调度 LangGraph/ReAct Agent 与数据工具，前端负责把工具调用、流式正文、K 线图和多轮对话体验组织成一个可观察、可迭代、可继续扩展的研究工作流。

策略 Skill 系统

Finance Agent 在“数据 Agent”之外新增了可配置的投资分析 Skill。数据 Agent 负责取数和形成证据，例如基本面、技术面、新闻和估值报告；Skill 不再重复查询 MCP 数据，而是读取这些已有证据，并按照特定投资方法论生成结构化策略观点。

当前内置 Skill：

• quality_value：质量成长与估值安全边际。它综合盈利质量、成长能力、现金流和资产负债、估值安全边际、技术面买点确认以及新闻风险否决项，输出 strong_buy、buy、hold、sell、strong_sell 五级信号、置信度、满足条件、未满足条件、风险提示和推理说明。

Skill 与原有 Agent 的关系：

• 基本面、技术面、新闻、估值 Agent：面向数据获取和证据生成，可以调用 MCP 工具。
• Skill：面向投资框架解释，只消费四个 Agent 的分析结果，第一版不调用 MCP，不补跑缺失 Agent。
• Summary Agent：CLI 工作流中会读取 Skill 共识并写入最终报告；Web 工作台中 Skill 通过独立面板和 SSE 事件展示，不额外调用 Summary Agent。
• 降级策略：Skill 失败或证据不足不会阻断原有 Agent 输出和报告生成。

flowchart TD
    A[用户问题] --> B[股票标的解析]
    B --> C1[基本面 Agent]
    B --> C2[技术面 Agent]
    B --> C3[新闻 Agent]
    B --> C4[估值 Agent]
    C1 --> D[EvidenceCollector]
    C2 --> D
    C3 --> D
    C4 --> D
    D --> E[SkillRouter]
    E --> F[SkillEvaluator]
    F --> G[SkillConsensus]
    G --> H1[CLI Summary Agent]
    G --> H2[Web Skill Panel SSE]

Loading

Web 使用方式

vue 工作台提供三个 Skill 模式：

• 自动选择：完整股票投资分析场景默认启用 quality_value；只选单个 Agent 或证据不足时会跳过，并显示原因。
• 不使用 Skill：请求中发送 skills: ["none"]，不启动 Skill LLM。
• 质量成长与估值安全边际：显式启用 quality_value。如果只选择部分 Agent，不会偷偷补跑其他 Agent，Skill 会带着缺失证据降级运行。

启动 FastAPI 后端：

cd D:\juliye\toy\gupiao\Finance\vue
conda activate jianji
$env:FINANCE_DIR="D:\juliye\toy\gupiao\Finance"
python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

启动 Vue 前端：

cd D:\juliye\toy\gupiao\Finance\vue
npm run dev

Vite 会将 /api 代理到 http://127.0.0.1:8000。MCP Server 由 Agent/MCP client 在运行时按现有配置启动和复用，不需要手动单独启动。

API 与 SSE

多 Agent Web 接口：

POST /api/run/agents/stream
Content-Type: application/json

请求示例：

{
  "command": "分析贵州茅台的投资价值",
  "target_agents": ["fundamental", "technical", "news", "value"],
  "skills": ["quality_value"]
}

skills 规则：

• 缺失或空数组：自动路由。
• ["none"]：禁用 Skill。
• 具体 Skill ID：显式选择。

新增 SSE 事件：

event: skill_selected
data: {"skills":["quality_value"],"reason":"default_complete_stock_analysis"}

event: skill_start
data: {"skill_id":"quality_value","display_name":"质量成长与估值安全边际"}

event: skill_result
data: {"skill_id":"quality_value","signal":"buy","confidence":0.78}

event: skill_consensus
data: {"status":"available","final_signal":"buy","confidence":0.74}

event: skill_error
data: {"skill_id":"quality_value","message":"局部错误信息"}

原有 status、agent_progress、token、kline、report、done、error 事件语义保持不变。

自定义 SKILL.md

可通过环境变量 FINANCE_SKILL_DIR 指定自定义 Skill 目录。系统会扫描内置 Financial-MCP-Agent/src/skills/builtin/**/SKILL.md 和自定义目录；自定义 Skill 与内置 Skill 同名时，自定义版本覆盖内置版本。

最小示例：

---
name: my_skill
display_name: 我的投资框架
description: 基于已有 Agent 证据生成结构化策略观点。
version: "1.0"
category: fundamental
aliases:
  - 我的框架
required_agents:
  - fundamental
  - value
default_active: false
user_invocable: true
priority: 20
---

只能基于输入证据分析，不得编造财务指标、新闻和价格。
输出必须符合 SkillOpinion JSON 结构。

单个 Skill 解析失败只记录 warning，不影响应用启动。

安全与限制

• 本项目只用于研究和学习，不执行真实交易，不构成投资建议。
• Skill 输出经过结构化校验，非法 signal 或缺失 signal 不会被静默改成 hold。
• 证据缺失会降低结果可靠性；所有 Skill 都失败时返回 unavailable，不伪造结论。
• Skill 第一版不调用 MCP，不做额外取数，不启动新的 Baostock session。
• 第一版只有 quality_value 一个内置策略，尚未接入历史回测自动调权。

测试命令

$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD='1'
D:\miniconda3\envs\jianji\python.exe -m pytest -p no:cacheprovider --rootdir=Financial-MCP-Agent\tests Financial-MCP-Agent\tests\skills -q

$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD='1'
D:\miniconda3\envs\jianji\python.exe -m pytest -p no:cacheprovider --rootdir=vue\backend\tests vue\backend\tests -q

cd D:\juliye\toy\gupiao\Finance\vue
node tests\skillState.test.mjs
npm run build

更新日志

2026/7/28

完成 quality_value 策略 Skill 的完整闭环接入。

• 新增 Financial-MCP-Agent/src/skills 模块，包含 Skill schema、加载器、注册表、路由器、证据收集、模型评估、共识聚合和服务层。
• 新增内置 quality_value/SKILL.md，将质量成长、现金流、资产负债、估值安全边际、技术确认和新闻风险否决项组织成可配置投资方法论。
• CLI LangGraph 工作流新增 skill_stage，在四个数据 Agent 后运行 Skill，并让 Summary Agent 增加“策略 Skill 评估”章节。
• FastAPI 多 Agent SSE 接入 SkillService，新增 skill_selected、skill_start、skill_result、skill_consensus、skill_error 事件，不改变旧事件语义。
• Vue 工作台新增 Skill 选择器和独立策略面板，支持自动选择、显式关闭和显式启用 quality_value，历史轮次会保存当时的 Skill 快照。
• 补充 Skill 核心、FastAPI SSE 和前端状态测试，验证旧请求兼容、证据不足降级、非法输出不伪造结论以及多轮状态不串线。

2026/6/21

• 初步测试项目。
• 将现有仓库推送到远程仓库。

2026/6/23

排查发现，每个 Agent 自身的 ReAct 循环存在问题。

LangGraph 默认递归限制为 25 步。通过打印工具调用流程日志，确认出现 recursion limit 错误主要有两个原因：

1. 转换内容为 Markdown 文档的工具未下载，导致工具调用报错。
2. Agent 一次会调用多个工具，而这些工具可能触发 Baostock 的并发登录限制，导致部分工具无法正常 login。

同时，提示词中要求 Agent “需要使用不同工具进行组合”，因此 Agent 会持续尝试调用多个工具，最终更容易触发递归步数限制。

2026/6/30

开始使用 uv 管理项目依赖。

2026/7/21

新增 vue 前后端调试控制台，用于在网页端调试 Finance Agent 的单 Agent 流式输出流程。

• 前端使用 Vue、Vite、DaisyUI 构建对话式页面，包含左侧会话边栏、底部输入框和基本面 Agent 输出区。
• 后端使用 FastAPI 提供接口，通过 SSE 将基本面 Agent 的工具调用进度和最终 Markdown 分析内容流式推送到前端。
• 新增基本面 Agent 单独运行入口，便于前端优先调试单 Agent 链路。
• 新增近一个月 K 线展示模块，前端使用 ECharts 渲染后端返回的 K 线数据。
• 新增 Agent 正文回复框和复制按钮，方便复制单次分析结果。
• 新增基本面 Agent 的轻量会话记忆，当前使用 Python 进程内数组保存最近对话，用于支持初步多轮追问。
• 完善 README 首页展示，新增前端截图和项目介绍。

2026/7/22

完善 vue 控制台的真实流式输出和多轮对话体验，当前重点打磨基本面 Agent 链路。

• 基本面 Agent 改为通过 LangGraph/ReAct 的真实消息流输出 token，前端使用 @microsoft/fetch-event-source 增量接收并渲染 Markdown。
• FastAPI 后端新增直接 SSE 流式接口，统一返回 status、agent_progress、token、kline、done、error 等事件。
• 前端新增请求取消、重复发送保护、生成中按钮禁用/取消、自动滚动到最新输出等交互。
• 改造基本面 Agent 的会话输入方式：参考多轮聊天项目，将最近历史转换为 HumanMessage / AIMessage 后与当前问题一起传入模型，而不是只做单轮问答。
• 优化股票标的识别逻辑，避免把“科创板”“创业板”“主板”等市场板块误判为公司名；支持“拿这支来说”“该股”“这家公司”等追问表达沿用上一轮股票。
• K 线图改为后端事件驱动渲染：后端根据当前标的或明确追问返回近一个月 K 线，普通闲聊不会误触发示例股票代码绘图。
• 前端归档单轮回复时同步保存 K 线快照，追问或感谢类回复不会清空上一轮图表。
• 优化聊天式布局，移除多余报告卡片，调整回复框、复制按钮、时间戳、侧边栏和底部输入框的显示效果。

2026/7/23

继续重构基本面 Agent 的 K 线渲染链路，将图表从“后端结束后自动补图”升级为 Agent 主动调用的结构化工具输出。

• 新增 MCP 工具 get_stock_kline_data，复用现有 Baostock DataSource、登录锁和 MCP Server，返回股票代码、近 30 个交易日 OHLCV、最新交易日和区间摘要等结构化数据。
• 基本面 Agent 将 K 线工具加入白名单，并在提示词中约束调用边界：完整分析或近期走势问题可调用，感谢、寒暄、纯概念问题不调用，默认周期固定为 30 个交易日。
• 流式链路新增 ToolMessage 监听：识别 get_stock_kline_data 工具结果后发送 kline_data，FastAPI 再转换为前端已有的 kline SSE 事件。
• 删除 /api/run/fundamental/stream 中根据报告正文或历史标的自动补 K 线的逻辑，避免 Agent 未调用工具时页面仍出现旧图。
• 前端将回复内容保存为按顺序排列的 blocks，K 线图作为当前轮自己的 kline block 插入；历史轮次和当前轮不再共用全局 K 线状态。
• 新增独立 KlineChart.vue 组件管理 ECharts 生命周期，并通过 tool_call_id 去重，防止同一次工具调用重复渲染图表。
• 补充走势类历史追问识别，支持“它最近走势怎么样”这类多轮问题复用上一轮股票标的并触发 K 线工具。

2026/7/24

将 vue 调试控制台从单基本面 Agent 扩展为多 Agent 流式工作台，并增加用户显式选择本轮参与 Agent 的路由机制。

• 技术面、新闻和估值 Agent 新增真实 astream 流式输出入口，复用统一的 token、工具进度和异常事件协议。
• FastAPI 新增多 Agent SSE 聚合接口 /api/run/agents/stream，可并发转发基本面、技术面、新闻和估值 Agent 的结构化事件。
• 前端新增四个 Agent 状态/导航卡片，按 data.agent 将 Markdown、工具进度、K 线和错误 block 分流保存到对应 Agent。
• 新增“发送给”接收者选择栏，支持本轮显式选择 1 到 4 个 Agent；首次默认全选，首次成功后自动收缩为当前查看的 Agent。
• 后端请求体支持 target_agents，只为本轮实际选择的 Agent 创建任务；保留旧 agent_mode 字段兼容历史调试入口。
• 前端区分 activeAgentId 与 selectedAgentIds：前者控制当前查看内容，后者控制下一轮发送对象，运行中切换卡片不会改变已启动的 Agent 集合。
• 新增 Agent 回复轮次分隔 block，避免追问内容粘到旧回答末尾；取消、异常和完成状态只影响本轮实际参与的 Agent。

使用 uv 安装项目依赖

克隆项目后，进入项目根目录：

cd stock-agent

创建虚拟环境：

uv venv

激活虚拟环境：

source .venv/bin/activate

使用 uv 安装依赖：

uv pip install -r requirements.txt

运行项目

复制 .env 文件

cd stock-agent/Financial-MCP-Agent
cp .env.example .env

将 .env文件中的 key 和 url 换成个人的 key 和 url,以及使用的模型。

修改 mcp-tools的路径： 在 stock-agent/Financial-MCP-Agent/src/tools/mcp_config.py下: r"/Users/mac/Finance/stock-agent/a-share-mcp-is-just-i-need",

模块化运行基本面agent测试：

cd Financial-MCP-Agent
python -m src.agents.fundamental_agent

windows下运行所有agent测试:

cd Financial-MCP-Agent
python -m src.main --command "帮我看看茅台(600519)这只股票值得投资吗"