【山东大学项目实训FinAgent】周报（2026-04-19）：Dataflow分层落地与FastAPI路由解耦

时间：2026-04-19 （一直写在项目个人进度文档里没上传，补传）
项目：FinAgent

---

摘要

本次主要工作是完成FinAgent数据链路的工程化分层，目标是解决两个长期问题：

1. API层与数据源实现耦合高，后续替换或扩展数据源成本大。
2. 图编排、工具调用、数据清洗职责边界不清晰，定位问题链路耗时。

本次改造后，系统形成了清晰的职责闭环：
FastAPI负责任务入口与生命周期，LangGraph负责决策编排，Dataflow负责工具路由，Vendor负责适配，Providers负责真实数据拉取与清洗。

---

一、本周目标、范围与结果

1.1 工作目标

• 建立“任务路由”与“数据路由”双路由模型，避免概念混淆。
• 实现工具方法到vendor实现的统一路由入口。
• 让分析师子图与结构化管线复用同一条数据调用路径。
• 强化可回归能力（provider层smoke可单独验证）。

1.2 本周结果

• 打通dataflows -> vendors -> providers全链路。
• 明确API路由不直接依赖数据源实现。
• 固化runner->analyst_subgraph->analyst_pipeline的执行顺序与数据回流方式。

---

二、核心设计：两类路由彻底解耦

2.1 路由分类

路由类型	入口	负责内容	不负责内容
HTTP路由	POST /api/analysis	鉴权、参数校验、任务触发、状态落盘、结果返回	数据源选择、数据清洗
Dataflow路由	route_to_vendor(...)	工具方法映射、vendor选择、回退策略	任务生命周期管理

结论：HTTP路由是任务编排层，Dataflow路由是数据实现层。

2.2 分层架构图

2.3 关键收益

• 上层图编排不感知底层数据源细节。
• vendor可插拔，具备后续多源扩展能力。
• 数据问题可在provider层快速隔离，不必全链路排查。

---

三、从请求到数据返回：执行时序说明

3.1 端到端时序图

3.2 理解一次工具调用

1. 分析师节点决定触发某个抽象工具（如get_news）。
2. ToolNode执行agents/utils/*_tools.py内薄封装函数。
3. 薄封装统一调用route_to_vendor做方法路由。
4. akshare_vendor调用providers完成拉取与清洗。
5. 结果封装为ToolMessage回到当前分析师节点继续推理。

---

四、Providers 层职责边界与模块现状说明

目录：backend/app/data/providers/

模块	主要职责	典型输入	典型输出
stock_provider.py	OHLCV拉取、列标准化、时间窗口一致性	ticker, start/end date	标准化行情数据
news_provider.py	资讯聚合、去重、时间过滤、严格模式控制	ticker, date range, flags	NewsItem[]
akshare_extras_provider.py	财务、报表、内幕交易等扩展数据	ticker, date scope	结构化字典/列表
social_provider.py	社媒帖子与热词拉取、语义化摘要	ticker	社媒证据结构

重要边界：Providers只处理“数据正确性与格式一致性”，不处理任务状态、不处理图节点流转。

---

五、分析师子图如何消费数据

5.1 主图进入逻辑（runner.py里边）

在analyst节点执行时有两个动作：

1. 调用compile_analyst_subgraph(...).invoke(...)跑完四专科 ReAct。
2. 调用run_analyst_data_pipeline(...)补齐结构化数据块，用于报告拼装与下游阶段消费。

这意味“文本结论”和“结构化证据”分属两条协作链路，但共享同一个dataflow路由体系。

5.2 子图内部执行图

5.3 两层路由在子图中的协同

• 图路由：由条件边决定“继续工具循环”还是“进入下一专科”。
• 数据路由：由 route_to_vendor 决定“工具落到哪个 vendor 实现”。

两者叠加后，既保证了推理流程可控，也保证了数据调用可配置。

---

六、与 API 层的关系（避免误解）

同步场景主路径：

POST /api/analysis ->run_analysis_workflow ->run_analysis_langgraph ->analyst节点 ->analyst_subgraph + analyst_pipeline

API层只负责任务入口，不直接调用AkShare。
异步任务模式变化的是“执行时机与回传方式”，不是数据调用链路。

---

七、本周复盘与下阶段计划

8.1 本周复盘

• 体系化完成数据链路分层。
• 架构层面为多vendor、可观测性、回退策略打下基础。
• 工具调用链与结构化管线实现统一路径，维护成本下降。

8.2 下周计划

• 继续优化分析师阶段输出质量与可解释性。
• 补齐数据层观测指标：成功率、超时率、回退次数。
• 强化回归基线：关键provider与核心节点增加自动化smoke。

---

上一阶段

• [2026-04-04 AKShare 数据接入周报]