# InvesResearch Agent · 模块化架构图说明文档 > 面向专业投资人 / 分析师的二级市场调研系统 · A股 / 港股 / 美股 · Skills + MCP · 多 Agent 辩论编排 > > 本文档配套四张架构图(SVG 矢量 + PNG 高清位图),逐图说明每个模块的职责、边界与设计依据。 --- ## 文件清单 | 图号 | 文件名 | 主题 | 尺寸 | |---|---|---|---| | 图 1 | `01-system-overview.{svg,png}` | 系统总览(五层 + Harness) | 1240×1180 / 2480px | | 图 2 | `02-data-layer.{svg,png}` | 数据层:请求生命周期与容灾 | 1240×900 / 2480px | | 图 3 | `03-orchestration.{svg,png}` | Agent 编排:LangGraph 状态机与辩论流 | 1240×980 / 2480px | | 图 4 | `04-skills-mcp.{svg,png}` | Skills + MCP 双层与跨 runtime 调用 | 1240×940 / 2480px | SVG 为矢量源文件,可无限缩放、可二次编辑(改文字 / 配色 / 重新导出);PNG 为 2480px 宽的高清位图,适合直接嵌入文档、PPT 或评审材料。 --- ## 阅读顺序建议 四张图构成一条从「全局」到「局部」的认知路径。建议先看图 1 建立整体心智模型,理解系统分成哪几层、各层之间怎么衔接;再按需深入图 2 到图 4,它们分别放大了三个最关键、也最复杂的模块。之所以拆成四张而非塞进一张总图,是因为数据层的容灾逻辑、编排层的辩论循环、能力层的双层封装,每一块单独展开都需要相当的空间才能讲清楚,挤在一起只会让线条交错、标签重叠,反而看不清。 --- ## 图 1 · 系统总览 这张图回答的是最根本的问题:整个系统由哪几层组成,数据和控制如何在层间流动。系统采用经典的五层分层架构,自上而下分别是接口层、编排层、能力层、工具层、数据层。一个贯穿全图的原则是:数据自下而上流动(数据层取数 → 工具层计算 → 能力层封装 → 编排层调度 → 接口层呈现),而控制自上而下托管(上层调度并约束下层)。 最上面的接口层(L5)是系统对外的所有入口。它的设计要点不在于"有几个入口",而在于同一套底层能力同时服务两类调用方:一类是自有的 Web 工作台、CLI、REST API,另一类是外部的 LLM runtime(Claude Code、Codex、Gemini、Cursor 等)。后者通过 MCP Server 接入——这正是"做成 Skills 让任意 runtime 都能调用"这一核心诉求的落点,图中用虚线框把外部 runtime 标示出来,表示它们不属于本系统但能直接消费本系统的能力。 编排层(L4)是系统的大脑,基于 LangGraph 实现。它内部包含一条完整的多 Agent 协作链:Supervisor 解析意图并路由,分析师组并行取数与诊断,估值师做 DCF 和相对估值,多空辩论(图中橙色高亮,带自循环箭头)让看多看空双方交锋,最后由风控和 PM 综合成结论。这一层底部还嵌了一条虚线条带,标示 Harness 运行时——session 持久化、context-builder、tool-router、credential-proxy、trace、eval/model-router/cost-guard 等子系统。把它单独标出来,是为了强调一个工程理念:Harness 是承载编排的工程骨架,它独立于具体模型演进,模型升级时这层可加可减。 能力层(L3)被特意画成左右并排的两块,因为这是整套设计里最该被一眼看清的工程边界。左边粉色的 L3a 是 Skills,承载"知识与流程"——基本面调研 SOP、DCF 估值流程、行业研究框架、研报写作规范这些稳定到能写下来、几周内都成立的领域知识。右边青色的 L3b 是 MCP 工具,承载"数据与计算"——get_financials、run_dcf、screen_stocks 这些每次调用结果都会变、且需要持有凭证的能力。两块之间有一条"调用"箭头,表示 Skill 在执行流程时会调用 MCP 工具来实际取数和计算。 工具层(L2)是被 MCP 调用的实际计算单元:财务指标计算与估值模型、因子库与回测、NLP 情绪分析、报告引擎。数据层(L1)是整个系统的地基,也是风险最集中的地方,图 2 会专门放大它。这里先给出全貌:三地市场各自的免费数据源、一排容灾组件(熔断、限流、重试、跨源校验),以及底部的三层缓存加真相源和用于 RAG 的向量库。 --- ## 图 2 · 数据层:请求生命周期与容灾 这张图把数据层"拍扁"成一次具体请求的旅程,展示当一个 `get_financials("SH:600519")` 调用进来时,系统是怎么处理的。之所以用"一次请求的生命周期"来讲数据层,是因为数据层的复杂度不在于它有哪些组件,而在于这些组件如何协同应对免费数据源的不稳定。 请求首先进入 DataFetcherManager,这是统一适配器,负责按市场和数据类型做路由。然后请求会自上而下逐层穿透三层缓存:先查进程内的 LRU(最快,小于 1 毫秒,约 34% 命中),再查 Redis(约 5 毫秒,约 39% 命中,这一层还用分布式锁防止缓存击穿),再查 DuckDB/Parquet 加 PostgreSQL 的历史与真相源(约 40 毫秒,约 14% 命中)。只有当三层全部未命中(约 13%)时,才会触达免费 API。 触达 API 时,优先级 failover 加熔断机制开始工作。图右侧展示了两条按市场划分的 provider 链:A 股的 daily_bar 走 tushare → akshare → baostock,三个都处于 CLOSED(正常);美股的 daily_bar 本应走 yfinance,但它因连续限流被熔断(图中用删除线和红色 OPEN 标示),请求自动 failover 到 alphavantage 接管。这就是容灾的核心——单个源失效不影响整体可用性。 图中部单独画出了熔断器的三态流转,这是理解容灾机制的关键。正常时熔断器处于 CLOSED 放行;当某个源连续失败达到阈值(比如 5 次)时转为 OPEN,在冷却期内直接 failover 不再尝试该源;冷却期满后转为 HALF_OPEN 试探性恢复,试探成功则回到 CLOSED,失败则重新 OPEN。这个设计避免了系统在一个已经挂掉的源上反复浪费时间和触发更严重的封禁。 请求成功取回数据后,还要经过最后一段处理:标准化为 Pydantic 模型(以 ticker 加频率为唯一键)、做跨源校验(同一指标在不同源差异超过 10% 时置位 `data_quality_flag` 标志)、按 TTL 回填各层缓存,最后返回给调用方。整个 failover 和缓存过程对上层完全透明——调用方拿到的就是标准化的数据,感知不到底层发生过熔断和切换。 --- ## 图 3 · Agent 编排:LangGraph 状态机与辩论流 这张图放大了编排层,展示多个 Agent 如何被组织成一个可恢复、可观测、可人工介入的工作流。整个流程是一个有向图,每个 Agent 是图中的一个节点。 流程从 Supervisor 开始,它解析用户意图并决定加载哪些 Skill。接着通过 LangGraph 的 Send 原语并行 fan-out 到分析师组——公司分析师做基本面诊断、行业分析师看格局、财务建模师做五年预测、舆情分析师看情绪、宏观分析师看环境,这五个并行执行以节省时间。它们的产出 fan-in 汇聚到估值师,后者做 DCF 和相对估值。 估值环节有一个关键的工程设计:human-in-the-loop interrupt。在深度调研模式下,当估值涉及 WACC、永续增长率这类核心假设时,流程会暂停,等待人工确认假设的合理性,确认后再继续。这是因为这些假设直接决定估值结论,而它们的合理性必须由人来背书——系统可以给出建议值,但不能替用户做这个判断。图中用橙色虚线把这个 HITL 环节单独标示出来。 估值之后进入多空辩论,这是整套编排里信息密度最高的环节,借鉴了 TradingAgents 的设计。Bull 研究员构建看多论点,Bear 研究员构建看空论点,二者结构化地交锋(图中 Bull 和 Bear 之间有双向箭头表示反驳),Neutral 研究员负责仲裁、识别双方分歧的核心。这是一个带计数器的条件循环——只要 `debate_round` 小于设定的最大轮数,流程就回到辩论继续下一轮;达到轮数后才往下走。辩论结束后,Risk Officer 评估尾部风险,PM 综合所有输入产出带评级和目标价的结论,最后由 Report Generator 固化成中英文研报。 图左下角的侧栏展示了 ResearchState 状态 schema 的设计要点:它保持最小、强类型,绝大部分字段是覆盖式的(每个 agent 写自己那块),只有 `debate_messages` 用了 reducer 做累积,因为辩论是逐轮叠加的。`cost_tokens` 字段用于成本护栏,`needs_human_review` 是 interrupt 标志。状态用 PostgresSaver 做 checkpoint,保证任意节点失败都能从断点恢复。 图右下角的侧栏展示了 model routing 的成本控制策略:Supervisor、估值终审、辩论、PM 结论这些关键环节用强模型(贵),而舆情、新闻摘要、格式化、行业检索这些用廉价模型(省),通过 LiteLLM 或 OpenRouter 网关路由并提供 provider 级 failover。`cost_tokens` 触及单会话预算的 80% 时告警,触及 100% 时提前终止并返回已完成的部分结果,目标是把单次深度调研控制在 0.5 美元以内。图最右侧的虚线表示 Quick 模式会跳过辩论和深度估值这条重路径。 --- ## 图 4 · Skills + MCP 双层:一次封装,处处调用 这张图把整套架构里最重要、也最容易被忽视的设计理念讲透:同一套能力包如何通过 Skills 加 MCP 的双层结构,既驱动自有编排器,又被各种外部 LLM runtime 直接调用。 图最上方是各类调用方——自有 Web 工作台(作为编排器 backend)、Claude Code、Codex CLI、Gemini CLI、Cursor,以及其他 32 个以上兼容 Agent Skills 开放标准的工具。它们各自的 Skill 发现路径不同(`.claude/skills/`、`.codex/skills/`、`.gemini/skills/`),但通过 install.sh 自动复制即可适配。关键在于:这些调用方在会话启动时只需读取每个 Skill 的 name 和 description(渐进披露,每个约 100 token),按需才加载完整内容,因此即使装了很多 Skill 也不会撑爆上下文。 图中部是能力包本身,一个单一的 Git 仓库,内部就是那条核心边界:左边粉色的 Skills 承载知识与流程,教 agent"如何思考这个领域";右边青色的 MCP server 承载数据与计算,给 agent"行动的工具与凭证边界"。这里有一个重要的安全设计——凭证由 MCP server 持有,agent 永远看不到数据库密码或数据源 API key。两块之间的 MCP 传输层支持 stdio、SSE、Streamable HTTP,公网部署强制 OAuth 2.1,并内建了若干工程防护:output schema 用 Pydantic 约束、破坏性工具标记触发 HITL、剥离工具返回里的可疑标签以防 tool poisoning、progressive tool discovery 优化 token。 图下方用一条法则把"何时用 Skill、何时用 MCP"这个开发时最容易纠结的问题一锤定音:知识稳定到能写下来、几周内都成立的归 Skill(DCF SOP、调研流程、研报规范、竞品方法论);结果每次调用都变、需要实时访问的归 MCP(取数、跑计算、筛选、检索新闻、向量检索)。 图最底部解释了为什么必须是双层而非单层:纯 MCP 会每次把所有工具描述塞进 context 造成 token 浪费;纯 Skill 又不能直接做网络请求和计算,只能告诉 LLM"该做什么"。两者结合恰好是渐进披露(来自 Skill)加标准化工具调用(来自 MCP)——知识层叠在工具层之上,这也是官方推荐的范式。 --- ## 设计原则速查 整套架构贯穿几条值得反复强调的原则,它们体现在每一张图里。第一是分层解耦:五层各司其职,数据自下而上、控制自上而下,任何一层的内部实现都可以替换而不影响其他层。第二是 Harness 与模型解耦:承载运行的工程骨架独立于具体模型演进,模型升级时骨架可加可减。第三是 Skills 与 MCP 的边界清晰:知识归 Skill、数据计算归 MCP,这条边界让能力既可移植又可实时。第四是容灾内建:数据层用熔断、failover、缓存、跨源校验把免费数据源的不稳定性挡在系统之外。第五是成本与人工介入可控:model routing 控成本,HITL interrupt 在关键假设处让人来背书。 --- ## 二次编辑提示 如果需要修改这些图,直接编辑对应的 SVG 文件即可——所有文字、颜色、坐标都是明文。配色用的是一套语义化的色板:紫色代表编排、粉色代表 Skill、青绿色代表 MCP 与数据、蓝色代表基础设施、橙色代表外部 runtime 与告警状态。改完后用任意 SVG 渲染器(如 `wkhtmltoimage`、`rsvg-convert`、Inkscape,或浏览器)重新导出 PNG。各图的 viewBox 已按内容贴合,新增元素时注意不要超出右边界与底边界。 --- > 免责声明 — 本系统及其产出的所有内容仅用于研究效率提升与教育目的,不构成任何投资建议。投资有风险,决策需谨慎。