# InvesResearch Agent · 系统设计文档(System Design Document)

> 二级市场投研工作台(`web/`)的系统设计 · **版本 v1.0** · 状态:开发就绪草案
>
> 关联文档:[产品 PRD](./product-prd.md) · [工程 PRD](./engineering-prd.md) · [架构决策](./architecture-decisions.md) · [架构图说明](./architecture-notes.md) · [Harness 工程最佳实践](./harness-best-practices.md)
>
> 本文档的定位:架构决策回答"为什么是这套架构",这份系统设计文档回答"这套架构具体长什么样"——组件契约、数据模型、关键时序、部署拓扑与故障模式。它是研发在 architecture-decisions 与 engineering-prd 之间的结构参考。

---

## 1. 系统上下文

InvesResearch Agent 是一个把二级市场深度调研流程自动化的多智能体系统。从外部看,它接收三类输入(一个标的、一个行业关键词、或一段自然语言提问),输出四类产物(结构化报告、可对话的估值模型、量化筛选结果、对话式问答)。它的能力被封装成符合 Agent Skills 开放标准的能力包,既驱动自有 Web 工作台,也能被 Claude Code、Codex、Gemini CLI 等兼容 runtime 直接调用。

系统的外部依赖分三类:数据源(AKShare、Tushare、yfinance、edgartools 等免费/开源源)、模型提供方(Anthropic、DeepSeek、Qwen 等,经 LiteLLM/OpenRouter 网关)、以及部署基础设施(PostgreSQL/TimescaleDB、Redis、向量库)。

---

## 2. 组件分解

系统按五层(见架构说明 §1)展开为下列组件。

### 2.1 L1 数据层组件
核心是一个 `DataAdapter` 抽象与一组 `Provider` 实现。每个数据源实现一个 `Provider` 子类,返回标准化的 Pydantic 模型。一个 `DataFetcherManager` 按"市场 × 数据类型"路由到优先级最高的可用 provider,并维护 failover。路由之上,每个 provider 被一个三态熔断器(CLOSED / OPEN / HALF_OPEN)包裹;退避重试用指数退避加 jitter;限流用 Redis 令牌桶中央化管理。缓存是四层结构:进程内 LRU → Redis(含分布式锁防击穿)→ DuckDB/Parquet → PostgreSQL/TimescaleDB 真相源。

### 2.2 L2 工具层组件
确定性计算能力:DCF 估值引擎(输入假设、输出内在价值与敏感性矩阵)、多因子筛选(接 Qlib Alpha158/360 与 WorldQuant Alpha101)、NLP 情绪分析(FinNLP 管道)、报告引擎(四种模板渲染为 PDF/DOCX)。这一层的特点是"纯函数式、可重放、可单测"。

### 2.3 L3 能力层组件
MCP server(FastMCP 实现)暴露数据与计算工具:`get_financials`、`run_dcf`、`screen_stocks`、`search_news`、`vector_search` 等,每个工具有明确的输入输出 schema 与"是否破坏性、是否可缓存"标记。Skills 包封装流程知识:`company-fundamental-research`、`industry-research`、`dcf-valuation`、`peer-comparison`、`report-writing` 等,每个是一个含 `SKILL.md`(YAML frontmatter + Markdown 正文)的目录。

### 2.4 L4 编排层组件
LangGraph `StateGraph` 实现 `ResearchState`。节点包括 supervisor、五个分析师(company/sector/macro/financial_modeler/sentiment)、valuation、debate、risk_officer、pm、report_generator。分析师组通过 Send 并行 fan-out;估值节点带 interrupt;辩论是带计数器的条件循环;成本由 model routing 控制(强模型只用于规划、估值终审、辩论、PM 结论)。

### 2.5 L5 接口层组件
Next.js 前端 + FastAPI 后端 + SSE 实时进度流。前端按"左侧导航 + 顶部工具栏 + 主工作区 + 可折叠右栏"布局组织。状态栏显示当前 session 的 token 消耗、成本、缓存命中率和数据源健康。

---

## 3. 数据模型(契约)

所有跨模块流动的数据用 Pydantic 模型定义,它们既是运行时校验器,也是文档与测试基准。标的统一为 `MARKET:TICKER` 形式(如 `SH:600519`、`HK:00700`、`US:AAPL`)。核心模型包括 `Security`(标的标识)、`DailyBar`(日线,带 `adjust` 复权类型与 `source` 来源)、`FinancialStatement`(财务三表,带 `data_quality_flag` 跨源校验标记)、`ValuationAssumptions`(DCF 假设,HITL 复核对象)、`DCFResult`(含分年 FCF 与敏感性矩阵)、`ResearchReport`(报告,`disclaimer` 字段强制非空)。

两个关键设计点:`FinancialStatement.data_quality_flag` 在同一指标跨源差异 > 10% 时置位,提醒上层与用户该数据存疑;`ResearchReport.disclaimer` 从数据模型层面保证每份报告都带免责声明。完整 Pydantic 定义见工程 PRD §4。

---

## 4. 关键时序

### 4.1 深度调研时序
用户发起 → 前端经 SSE 建立进度通道 → FastAPI 创建 session(Postgres checkpointer 落盘)→ supervisor 解析意图、加载 Skill → 分析师组并行取数(经 MCP → 数据层四层缓存 → 命中则 100ms 内、未命中则触达免费 API)→ 估值节点 interrupt 暂停等人工确认 WACC/永续增长率 → 多空辩论循环 → 风控 → PM → 报告生成 → SSE 推送各节点状态直至完成。

### 4.2 数据容灾时序
请求某 A 股日线 → 路由表选 Tushare(主)→ Tushare 连续失败达阈值 → 熔断器 OPEN → 自动 failover 到 AKShare → 调用方无感知拿到数据 → Langfuse 记录一次熔断事件 → 冷却期满熔断器 HALF_OPEN 试探恢复。

---

## 5. 部署拓扑

标准部署:前端静态资源(Next.js 构建产物或纯静态 demo)→ CDN/Pages;FastAPI 应用 → 容器;PostgreSQL/TimescaleDB、Redis、向量库(pgvector 起步,Qdrant 上量)→ 托管或自建;MCP server 本地或容器内运行(本地 MCP 在沙箱隔离)。可观测性用 Langfuse 自托管 + OpenLLMetry 埋点。

机构私有化部署:为有"数据不出域"硬约束的客户预留 vLLM + 开源权重模型(Qwen/DeepSeek)+ 气隙自托管 Langfuse 的方案。

---

## 6. 故障模式与降级

| 故障 | 检测 | 降级策略 |
|---|---|---|
| 数据源失效 | 熔断器连续失败计数 | failover 到下一优先级 provider;全失效则返回缓存 + 标记 stale |
| 模型 provider 宕机 | 网关健康检查 | LiteLLM/OpenRouter provider 级 failover 切换 |
| 上下文接近上限 | 估算窗口利用率 90% 触发、75% 预警 | 两阶段压缩:先截断过大工具返回,再摘要中间内容保留头尾 |
| 单会话成本超预算 | 每节点后更新 `cost_tokens` | 80% 告警,100% 提前终止并返回已完成的部分结果 |
| 子代理失败 | 子图异常 | 子代理隔离,单个失败不拖垮编排,可从 checkpoint 重跑 |

---

## 7. 非功能指标(摘要)

深度调研端到端 P95 ≤ 10 分钟,快速调研 ≤ 4 分钟,缓存命中响应 ≤ 100ms,支持 ≥ 20 并发会话;单次深度调研 token 成本 ≤ 0.5 美元;单市场单源数据可用率 > 99%,缓存命中率 > 80%;100% 的 LLM/工具调用有 trace 覆盖;Skill 调用成功率 MVP ≥ 90% / 差异化 ≥ 95%。完整指标见工程 PRD 附录 B。

---

> **免责声明** — 本系统及其产出仅用于研究效率提升与教育目的,不构成任何投资建议。系统输出受底层模型、温度、数据质量等非确定性因素影响,不保证准确性。所引技术基准为 2025–2026 年快照,实施前请核对官方文档。