# InvesResearch Agent · 下一步开发计划 > 路线图版本 **v1.0** · 制定日期 **2026-05-29** · 时间窗 **24 周(0→GA)** > > 关联文档:[产品 PRD](./product-prd.md) · [工程 PRD](./engineering-prd.md) · [架构说明](./architecture-notes.md) > > 本文档的目的:把工程 PRD §10 的六个里程碑,转成**可排期、可分工、可验收**的执行计划。 --- ## 0. 当前状态盘点(2026-05-29) 把"已交付"和"待开发"先摆清楚,后面的所有排期才有锚点。 | 维度 | 已交付 ✅ | 待开发 ❌ | |---|---|---| | **对外材料** | 落地页 / 交互 demo / 4 张架构图 / 3 份 PRD / 部署 pipeline(GitHub + Cloudflare) | — | | **数据层 L1** | — | 适配器 / 路由 / 熔断 / 4 层缓存 / 真实数据源接入 | | **工具层 L2** | — | DCF / 因子库 / NLP / 报告引擎(实现) | | **能力层 L3** | — | MCP server(FastMCP)/ Skills 包 | | **编排层 L4** | — | LangGraph 状态机 / 分析师组 / 多空辩论 / HITL interrupt / checkpointer | | **接口层 L5** | 前端原型(纯静态,模拟数据) | API server / SSE 实时流 / 与后端真实联调 | | **运行底座** | — | Postgres+Timescale / Redis / DuckDB / pgvector / Langfuse | | **质量** | — | eval 数据集 / CI 回归 / 安全加固 | **一句话**:对外形象做完了,产品本体还没建。下面 24 周做的是「让 demo 里那条调研流真的能跑起来」。 --- ## 1. 总体节奏(24 周三阶段) 整条路线按工程 PRD §12 的三阶段对齐,M1-M6 落在前 20 周,后 4 周用于 Stage 3 的开源化与生态。 ``` W01─W04 W05─W08 W09─W12 W13─W16 W17─W20 W21─W24 ─────────┬────────┬────────┬────────┬────────┬──────── M1 数据层 ████████│ │ │ │ │ M2 单 Agent+MCP │████████│ │ │ │ M3 多 Agent 编排 │ │████████│ │ │ M4 RAG+舆情 │ │████████│ │ │ (与 M3 并行) M5 报告+前端联调 │ │ │████████│ │ M6 三市场+私有化 │ │ │ │████████│ Stage 3 生态化 │ │ │ │ │████████ ─────────┴────────┴────────┴────────┴────────┴──────── Stage 1 MVP Stage 2 差异化 Stage 3 生态 ``` **节奏要点** - M1 是地基,必须先单独跑通再启动 M2;M2 完成后 M3 / M4 可并行编组。 - M5 是第一个"看得见"的对外里程碑(demo 切真数据),放在 Stage 2 末尾,作为对外发布锚点。 - M6 把多市场扩展和私有化合并到一个里程碑,因为这两件都是"对地基的横向扩展",共享同一批工程改造。 --- ## 2. 六个里程碑详解 每个里程碑按统一格式展开:**目标 · 交付物 · 关键技术 · 验收 · 风险 · 工时**。 ### M1 · 数据层地基 (W01–W04,4 周) **目标** 在一堆不稳定的免费源之上,搭出一个对上层透明、可用率 > 99% 的统一数据服务。这是后续一切的前提,任何延期会向后传导。 **交付物** - `Provider` 抽象基类 + Tushare / AKShare / baostock 三个 A 股 provider - `DataFetcherManager` 市场感知路由(ROUTING_TABLE 配置化) - `CircuitBreaker` 三态熔断器(CLOSED / OPEN / HALF_OPEN) - 四层缓存:cachetools LRU → Redis(含分布式锁) → DuckDB/Parquet → Postgres/TimescaleDB - Redis 令牌桶限流(跨进程共享 Tushare / AKShare 配额) - Pydantic 数据契约:`Security` / `DailyBar` / `Financials` / `Filing` / `NewsItem` - 跨源校验(同指标差异 > 10% 置 `data_quality_flag`) **关键技术** Python 3.12 · asyncio · tenacity · cachetools · Redis 7 · DuckDB · TimescaleDB · Pydantic v2 **验收(Given-When-Then)** - *Given* Tushare 主源正常,*when* 请求 A 股标的的日线,*then* 缓存命中 ≤ 100 ms / 未命中 ≤ 2 s 返回符合 schema 的数据。 - *Given* Tushare 连续 5 次失败,*when* 再次请求,*then* 熔断器进入 OPEN 状态并 failover 到 AKShare,调用方无感知。 - 连续 7 天对 30 支 A 股拉取日线 + 财务,可用率 > 99%,缓存命中率 > 80%,不触发限流封禁。 **风险** - Tushare 2000 积分申请周期(需做学生认证或社区贡献)→ Day 1 立即提交。 - AKShare 对上游 HTML 变动脆弱 → 加入"结构校验"单测,变动时立即告警。 - 一旦延期,M2 必须等,无法并行。 **工时** 1 BE × 4 周 + 0.5 SRE × 2 周(部署 Postgres/Redis/监控) --- ### M2 · 单 Agent + MCP 工具 (W03–W06,4 周,与 M1 重叠 2 周) **目标** 让一个单独的 agent,通过 MCP 拿数据、做基本面调研、产出符合 schema 的结构化结果,全链路在 Langfuse 中可追溯。 **交付物** - FastMCP server(支持 stdio + Streamable HTTP,公网部署 OAuth 2.1) - 核心工具 v1:`get_financials` / `get_quote` / `run_dcf` / `get_company_profile` - Skills 包初版:`fundamentals-research/`(SKILL.md + reference docs + sub-skills) - 凭证代理:API key 仅 MCP server 持有,agent 永远看不到 - Pydantic 原生 structured output(优先级 1:模型原生 schema 约束;退化到 tool calling;最后才 prompted JSON) - Langfuse 自托管 + OpenLLMetry 埋点,每次 LLM/工具调用产生 trace span **关键技术** FastMCP · Pydantic AI · Anthropic SDK · Langfuse · OpenLLMetry **验收** - 单 agent 对 SH:600519 完成基本面调研,产出 `CompanyAnalysis` schema 实例,所有字段非空且通过校验。 - Langfuse trace 中能看到完整调用链:Skill 触发 → MCP 调用 → 数据返回 → LLM 推理 → schema 输出。 - 在 Claude Code / Codex CLI 中安装 Skills 包后,自然语言"调研贵州茅台"可触发同一条流程。 **风险** - MCP spec 仍在演进 → 锁定到当前稳定版本,变更走单独 ADR。 - Skills 跨 runtime 行为差异 → 第一轮只验证 Claude Code,其他 runtime 作为 Stage 3 增强。 **工时** 1 BE × 4 周(W03 起即可开工,M1 完成时已上手两周) --- ### M3 · 多 Agent 辩论编排 (W07–W10,4 周) **目标** 把单 agent 扩展成完整的多 agent 协作链,带可恢复、可观测、可人工介入。 **交付物** - LangGraph `StateGraph` 实现 `ResearchState`(覆盖式字段 + `debate_messages` reducer) - 分析师组通过 `Send` 原语并行 fan-out(company / sector / macro / financial_modeler / sentiment) - 估值节点 + `interrupt` 触发的 HITL(WACC / 永续增长率 / 资本结构假设确认) - 多空辩论循环(Bull ↔ Bear ↔ Neutral,带 `debate_round` 计数器,可配置轮数) - Risk Officer + PM 节点 + Report Generator(占位,等 M5 完整化) - PostgresSaver checkpointer,任意节点失败可从断点恢复 - Model routing(LiteLLM 网关):Supervisor / 估值终审 / 辩论 / PM = 强模型;舆情 / 摘要 / 检索 = 廉价模型 - 单会话 `cost_tokens` 护栏:80% 告警,100% 熔断 **关键技术** LangGraph · PostgresSaver · LiteLLM · Anthropic Opus(关键决策) + Haiku / DeepSeek(检索摘要) **验收** - *Given* 一次深度调研,*when* 流程跑到估值节点,*then* 触发 interrupt,人工确认假设后继续。 - *Given* 流程在辩论第二轮被人为 kill,*when* 用同一 thread_id 重启,*then* 从中断处恢复,已完成节点不重跑。 - 单次深度调研端到端 P95 ≤ 10 分钟,token 成本 ≤ $0.5。 **风险** - 辩论失控(双方各说各话不反驳)→ 在 Bear/Bull prompt 中强制"必须引用对方第 N 条论点反驳",并由 LLM judge 在 eval 中检查反驳率。 - HITL 在生产环境的 UX 问题 → 配合 M5 做前端按钮,但后端先用 CLI 介入方式落地。 **工时** 1 BE + 1 AI Eng × 4 周 --- ### M4 · RAG + 舆情(W07–W10,4 周,与 M3 并行) **目标** 让系统能"看历史研报 / 看新闻 / 看社媒",并把这些非结构化信号纳入辩论。 **交付物** - pgvector 向量库(嵌入模型:bge-large-zh / text-embedding-3-large 双轨) - 文档管道:历史研报(PDF 解析)/ 新闻(AKShare + 雪球 / 财联社爬虫)/ SEC filings(edgartools)→ 分块 → 向量化 - MCP 工具:`vector_search` / `search_news` / `get_sentiment` - 情绪分析(FinNLP 管道,覆盖 Reuters / CNBC / Eastmoney / StockTwits / Reddit) - 量化筛选基础版:Qlib Alpha158 + WorldQuant Alpha101,因子勾选 → 排序股票池 **关键技术** pgvector · LangChain RetrievalQA · FinNLP · Qlib · BeautifulSoup / Playwright(爬虫) **验收** - 检索质量:从历史研报集中检索"宁德时代毛利率分析",前 3 召回的语义相关性人工评分 ≥ 4/5。 - 情绪分析:对 100 条标注新闻准确率 ≥ 0.78(F1)。 - 量化筛选:沪深 300 中按"低 PE + 高 ROE + 正动量"筛选,结果与手动验证一致。 **风险** - 爬虫稳定性 / 反爬 → 用 Playwright + 代理池,关键源做 fallback。 - pgvector 在 500 万向量后查询退化 → 评估迁移到 Qdrant 的触发阈值,提前预留迁移脚本。 **工时** 1 AI Eng + 1 Data Eng × 4 周 --- ### M5 · 报告生成 + 前端真实联调(W11–W14,4 周) **目标** Demo 切换到真实数据,用户能在 Web 上发起调研,看到 agent 实时进度,下载完整研报。这是第一个对外可发布的版本。 **交付物** - 报告生成 Skill(两段式长任务 harness):initializer agent 产出大纲 + 数据清单 → executor agent 增量推进每一节 - 四种模板:Quick Note(2 页)/ Deep Dive(15-30 页)/ Sector Report(20-40 页)/ Earnings Recap(5 页) - PDF + DOCX 导出(WeasyPrint + python-docx),中英文双语,图表内嵌,免责声明强制 - **前端重构**:把当前 `app.html` 的单文件 vanilla → Next.js 应用,但保持视觉一致 - SSE 实时进度流:agent 状态、token 消耗、缓存命中率、各源健康 - 模拟数据全部下线,接入真实 API - 报告库 v1(检索、收藏、版本 diff) **关键技术** Next.js 14 · SSE · WeasyPrint · python-docx · React Query **验收** - 用户在 Web 输入 "贵州茅台",选 Deep 模式,10 分钟内拿到符合 `ResearchReport` schema 的 PDF。 - 调研过程中右侧 Agent 流实时滚动,显示每个分析师的当前状态与产出摘要。 - 在估值假设处弹出 HITL 对话框,用户修改 WACC 后流程继续。 - 同一标的不同时间的报告可做 diff,直观看到观点变化。 **风险** - 前端从 vanilla 迁 Next.js 会让 Cloudflare Pages 的零构建优势失效 → 评估是否拆成 `marketing/`(保留 Pages)+ `app/`(迁 Vercel / Cloudflare Workers)。 - 报告生成是长任务,容易撞模型 context 上限 → 严格走两段式 harness,大纲节点单独子代理。 **工时** 1 FE + 1 BE × 4 周 --- ### M6 · 三市场扩展 + 私有化(W15–W20,6 周) **目标** 从 A 股扩展到港股 + 美股,补齐 eval 与安全,提供机构客户可选的数据不出域部署。 **交付物** - 港股路由:AKShare 主 + Longbridge 备(港交所披露易爬虫) - 美股路由:yfinance + Alpha Vantage(行情)+ edgartools(财务 + 8-K / 10-K) - 复权统一处理(前 / 后 / 不复权)+ 币种标准化(CNY / HKD / USD) - vLLM 部署方案 + Qwen2.5-72B / DeepSeek-V3 推理优化(PagedAttention) - Langfuse 气隙自托管方案 + 私有化部署指南 - 完整 eval 数据集(≥ 50 个调研任务,覆盖三市场 + 多行业 + 边界情况) - CI 回归集成(Braintrust eval-action 或 Langfuse dataset),PR 自动评估 - 安全加固:OWASP MCP Top 10 全部对账 + 第三方 Skill 审计流程 **关键技术** vLLM · Qwen2.5 / DeepSeek · Langfuse Self-Host · Braintrust **验收** - 对 10 支港股 + 10 支美股能在 10 分钟内出 Deep 报告。 - 私有化 demo 环境:气隙部署 vLLM + Langfuse + Postgres,无外网调用完成调研。 - eval 回归:任何 PR 在合并前必须通过基线指标,回归 > 5% 自动 block。 **风险** - edgartools 对最新 XBRL 标签变动的兼容 → 锁定版本,变动走 ADR。 - vLLM 在多卡推理的运维复杂度 → 提供 Docker Compose + Kubernetes Helm 两种模板。 **工时** 全员(2 BE + 1 AI Eng + 1 Data Eng + 1 FE)× 6 周 --- ### Stage 3 · 生态化(W21–W24,4 周) **目标** 把 Skills 包标准化开源,在 Claude Code / Codex / Gemini CLI / Cursor 等 runtime 上验证一致性,启动社区。 **交付物** - Skills 包标准化(Apache-2.0)+ 公开发布到 GitHub - 跨 runtime 安装脚本(自动复制到 `.claude/skills/` `.codex/skills/` `.gemini/skills/`) - CLI:`invesresearch research --depth deep --out report.pdf` - Python SDK + REST API 公开文档(OpenAPI 3.1) - 协作功能 P2:多用户 session 共享 + 评论 + Watchlist 定时调研告警 - 文档站(Mintlify 或 Docusaurus)+ 示例 cookbook **验收** - 在 5 个 runtime 中至少 4 个能直接调用 Skills 完成调研。 - 公开发布 4 周内 GitHub star ≥ 100,5 家企业开始 PoC。 --- ## 3. 关键路径与依赖 ``` M1 ──┬──> M2 ──┬──> M3 ──┐ │ │ ├──> M5 ──> M6 ──> Stage 3 │ └──> M4 ──┘ │ (M1 是单点风险,任何延期向后传导) ``` **关键路径长度** M1(4w) + M2(2w 与 M1 重叠后) + M3(4w) + M5(4w) + M6(6w) = **20 周**(对应 Stage 1+2 完成)。 **最危险节点** M1 数据层 — 免费源不稳定 + Tushare 积分申请周期都可能延误,需要 Day 1 启动并行兜底。 --- ## 4. 团队编组与并行策略 | 阶段 | 周次 | 并行流 1 | 并行流 2 | 并行流 3 | |---|---|---|---|---| | 启动 | W01–W02 | M1 数据层 | (招聘 / 待 M1 接手) | (Tushare 积分 / 资源采购) | | 扩展 | W03–W06 | M1 收尾 | M2 单 Agent+MCP | SRE 部署底座 | | 并行 | W07–W10 | M3 编排 | M4 RAG+舆情 | (设计 M5 UX) | | 联调 | W11–W14 | M5 前后端 | eval 数据集准备 | 安全审计前置 | | 扩展 | W15–W20 | M6 多市场 + 私有化(全员) | | 开源 | W21–W24 | Stage 3 生态化(全员) | **最小可行团队** 2 BE · 1 AI Eng · 1 Data Eng · 1 FE · 0.5 SRE · 0.5 PM = **6 人** 6 个月,可在 W21 完成 Stage 2。 --- ## 5. Sprint Zero:Day-by-Day(W01–W02) 按天分解,确保 Sprint 1 结束时 M1 已有可演示的雏形。 | 天 | 任务 | 产出 | |---|---|---| | **D1** | Monorepo 初始化(`apps/web` `packages/data` `packages/mcp` `packages/skills`)· 配置 ruff / mypy / pre-commit · 提交 Tushare 积分申请 | 仓库骨架 + CI 通过 | | **D2** | Docker Compose 部署 Postgres+TimescaleDB / Redis 7 / Adminer 本地栈 · 配 .env 模板 | 本地栈起得来 | | **D3** | Pydantic schema 编写:`Security` / `DailyBar` / `Financials` / `Filing` / `NewsItem` + 单测 | schema 100% 覆盖 | | **D4–D5** | `Provider` 抽象类 + Tushare provider 完整实现(daily_bar + financials + 健康检查) | Tushare 跑通 | | **D6** | AKShare provider 实现(同接口)· 跨源校验单测(差异 > 10% 触发 flag) | 双源对账通过 | | **D7** | `CircuitBreaker` 三态实现 + tenacity 指数退避 + Redis 令牌桶 | 容灾组件单测通过 | | **D8** | 四层缓存:cachetools LRU → Redis(分布式锁)→ DuckDB/Parquet → Postgres · TTL 策略实现 | 缓存命中率初测 > 50% | | **D9** | `DataFetcherManager` + ROUTING_TABLE 装配 · market-aware dispatch | 端到端可跑 | | **D10** | 集成压测:30 支 A 股连续拉 24 小时 · 监控可用率 / 命中率 / 限流命中 | 数据指标基线 | | **D11–D12** | Langfuse 自托管部署 + OpenLLMetry 埋点 + 基础 Grafana dashboard(可用率 / P95 延迟 / 命中率 / 熔断事件) | 可观测性 v0 | | **D13** | M1 sprint review demo + 数据层 README + ADR-04 / ADR-05 落档 | M1 50% 验收 | | **D14** | 复盘 · M2 启动会(MCP server 设计评审 · Skills 包目录约定) | M2 sprint 计划 | --- ## 6. 风险登记与待决策 ### 高风险登记 | 风险 | 影响 | 缓解 | 责任 | |---|---|---|---| | Tushare 积分申请未通过 | M1 主路径阻塞 | Day 1 提交 + 同时准备 baostock 兜底 | BE Lead | | 免费源被反爬封禁 | 数据可用率下降 | 代理池 + 双源 failover + 全量切到付费源的应急脚本 | SRE | | LLM 成本超 $0.5/次预算 | 商业模式不成立 | Model routing 强制执行 + 缓存命中率提升 + Haiku 替代 | AI Eng | | MCP / Skills spec 演进破坏兼容 | 全栈重构风险 | 锁定 stable 版本 + 包装层隔离 | BE Lead | | 前端 vanilla→Next.js 拖延 | M5 延期 | 提前 W09 启动迁移 spike | FE | | 多空辩论变成"双方各说各话" | 产品价值不成立 | 强约束 prompt + LLM judge eval 检查反驳率 | AI Eng | ### 四个待决策(进开发前必须拍板,来自工程 PRD §11 + 产品 PRD §14) 1. **商业模式与定价** — 按次 / 订阅 / 开源 + 企业版?这直接影响成本护栏的严格度和付费源迁移时机。**截止 W04 决策。** 2. **私有化部署优先级** — 是否必须在 Stage 2 完成?决定 M6 是否提前。**截止 W08 决策。** 3. **免费数据源合规边界** — 法务对"研究用途"和"商业再分发"的界定。**截止 W12 决策**(影响 Stage 3 是否能开源)。 4. **DCF "系统建议值"责任界定** — 默认假设导致决策失误的责任归属,关系到 HITL 强度和免责设计。**截止 M3 启动前(W07)决策**。 --- ## 7. Definition of Done 每个里程碑结束的统一打勾标准,缺一不可: - [ ] 所有交付物有 Pydantic schema / 接口契约,且文档化 - [ ] 单元测试覆盖率 ≥ 80%,关键路径有集成测试 - [ ] Langfuse 中可看到完整 trace,token 归因精确到 agent - [ ] 性能指标达成(P95 延迟、成本、可用率三项) - [ ] 安全:对应 OWASP MCP Top 10 项已对账 - [ ] 文档:README + ADR(如有架构决策)+ 验收 demo 录屏 - [ ] PR 通过 eval 回归,无 > 5% 关键指标退化 --- ## 附录 · 这份计划怎么读 - **如果你是产品 / 利益相关方** → 看 §0 状态盘点 + §1 总体节奏 + §6 决策卡。 - **如果你是工程师** → 看 §2 里程碑详解 + §5 Sprint Zero + §7 DoD。 - **如果你是项目经理** → 看 §1 + §3 关键路径 + §4 团队编组 + §6 风险登记。 配套信息图: - [`/roadmap.html`](../roadmap.html) — 24 周路线图可视化 - [`/docs/flow.html`](./flow.html) — 端到端全流程图示(五层架构 + 6 里程碑 + M1 数据层 + Sprint Zero + 技术栈 + 待决策 + 风险) --- > **免责声明** — 本计划基于 2026-05-29 的产品 PRD v1.0 与工程 PRD v2.0,任何里程碑、工时、决策窗口都可能因团队规模、外部依赖、商业策略调整而变更。所有引用的开源工具版本以官方文档为准。