从周报自动化到研发效能分析：为什么我选择 Multi-Agent 架构
研发效能这个场景一开始看起来像“自动写周报”。真正拆开以后，发现写报告只是最后一步，前面还有查数据、读材料、看历史、找行业指标、做趋势判断这些杂活。
比如一个很常见的任务：
结合 Sprint-12 的缺陷数据、测试报告和行业 DORA 指标，生成一次迭代复盘。
这句话背后至少有几件事：查 MySQL 里的缺陷和需求数据，读用户上传的测试报告，搜索行业 benchmark，再把这些材料合并成一份能看的复盘。单靠一个 Prompt 直接写，很容易变成空话；写死一个固定流程，又覆盖不了各种任务变体。
固定图在这里会变别扭
RAG 查询适合固定图，因为流程比较稳定：实体确认、召回、融合、重排、生成。
研发效能分析不太一样。用户有时只要查数据，有时要结合上传文件，有时还要搜外部方法论，有时是周报，有时是事故复盘。工具组合不确定，顺序也不完全固定。
如果用固定 StateGraph 硬编，通常会遇到两个问题：
- 把所有分支都编进去，图会越来越膨胀。
- 只编常见路径，一旦用户任务稍微变化就走不通。
所以这个项目改成主 Agent 动态规划，子 Agent 负责具体专业任务。
flowchart TB
U[用户任务] --> M[主 Agent]
M --> D[Database Agent]
M --> S[Search Agent]
M --> K[Knowledge Agent]
M --> A[Analyst Agent]
M --> W[Writer Agent]
D --> DB[(xiaoneng_db)]
S --> T[Tavily]
K --> R[RAGFlow / 预留]
W --> O[Markdown 报告]
两个项目的取舍差异
这里正好和 RAG 项目形成对比：
| 维度 | RAG 项目 | 研发效能 Agent |
|---|---|---|
| 任务形态 | 知识库问答，路径稳定 | 复合任务，路径不固定 |
| 控制流 | 工程代码决定下一步 | 主 Agent 规划下一步 |
| 风险点 | 串实体、证据不足 | 工具越权、状态不可控 |
| 工程重点 | 召回质量、证据约束 | 工具边界、任务状态、进度反馈 |
这也说明 Multi-Agent 不是默认更高级。只有当任务确实需要动态组合工具，并且每个工具都有清晰边界时，它才值得引入。
第一版的端到端流程
系统入口是 FastAPI。用户提交任务后，接口生成 thread_id，创建任务记录，然后后台异步跑主 Agent。
POST /api/tasks
-> create task: pending
-> schedule run_deep_agent
-> return thread_id
run_deep_agent
-> mark running
-> prepare session dir
-> stream main_agent.astream
-> mark done / error
执行过程中，主 Agent 会根据任务调度子 Agent 或工具。ToolMonitor 会捕获这些事件，通过 WebSocket 推给前端。最后 Writer Agent 生成 Markdown 报告，任务状态变成 done。
技术栈
项目主要组件：
| 组件 | 用途 |
|---|---|
| DeepAgents + LangGraph | 主 Agent、子 Agent 委派、流式执行 |
| FastAPI | 任务提交、状态查询、文件上传下载 |
| WebSocket | 推送工具调用和任务进度 |
MySQL xiaoneng_db | 存研发效能结构化数据 |
| Tavily | 检索行业实践和 benchmark |
| 自定义文件工具 | 读取上传的测试报告、Markdown、Excel 等 |
| Markdown/PDF 工具 | 生成和下载报告 |
第一版重点不是把报告写得多漂亮，而是让整个链路可观察：任务有没有创建，跑到哪个子 Agent，调用了哪个工具，最后结果落在哪个目录。
当前版本的边界
有些地方还只是 MVP：任务状态存在内存里，checkpoint 用的是 InMemorySaver，Knowledge Agent 的 RAGFlow 接入也还属于预留或部分接入。第一版先把主链路跑顺，再补持久化、权限、审计和更稳定的报告验收。
这个项目后面真正值得继续打磨的，不是“再加几个 Agent”，而是让每个 Agent 的职责更窄、工具边界更硬、任务状态更可恢复。
一个任务为什么会拆成多步
以“生成 Sprint-12 复盘报告”为例，它不是一个写作任务，而是一个信息整合任务。
第一步要确定 Sprint-12 是哪个迭代，查需求和缺陷数据。第二步要读取上传的测试报告，里面可能有人工记录的风险点。第三步要补充外部实践，比如 DORA 或缺陷逃逸率相关口径。第四步才是分析：哪些指标异常，异常可能来自哪里。最后才是写报告。
如果把这些全交给一个大 Prompt，它要同时记住数据库 schema、搜索策略、文件读取方式、分析方法和报告格式。Prompt 会很长，工具选择也容易飘。拆成子 Agent 后，每一段都窄一点，错误也更容易定位。
动态规划不等于完全自由
主 Agent 虽然负责规划，但不是没有边界。第一版里给它的任务范围很明确：研发效能分析、周报、迭代复盘、缺陷趋势、报告生成。工具也限制在查库、搜索、读文件和写报告这几类。
这点很重要。Multi-Agent 如果范围太开放，模型会开始做很多项目不支持的事，比如编造系统里没有的数据源，或者调用不该调用的工具。主 Agent 的 Prompt 要把“可以做什么”和“不确定时怎么反馈”写清楚。
为什么保留 RAGFlow 预留位
Knowledge Agent 当前还没有完全闭环，但架构里保留了 RAGFlow/内部知识库位置。原因是研发效能报告里经常需要内部规范：缺陷等级定义、提测流程、复盘模板、发布门禁规则等。
第一版可以先 stub 或半接入，保证主链路跑通。等查库、搜索、文件读取和报告生成稳定以后，再把内部规范接入进来。否则一开始就接太多源，问题排查会很难分层。
判断该不该用 Multi-Agent
不是所有任务都值得走完整主从链路。可以粗略分三档：
| 任务 | 更适合的处理方式 |
|---|---|
| 查询某个指标 | 直接 SQL 工具或单 Agent |
| 读取一个文件并总结 | 文件工具 + Writer 即可 |
| 查库 + 读文件 + 搜索 + 分析 + 写报告 | Multi-Agent 更合适 |
这个判断能避免系统过度设计。多 Agent 会带来延迟、成本和状态复杂度，它应该服务复杂任务，而不是成为默认路径。
第一版先不追求全自动决策
研发效能分析里有些决策其实不适合一开始就完全交给模型。比如“这个迭代质量是否达标”，如果没有团队自己的质量门禁，模型只能根据通用经验给出判断，很容易变成泛泛而谈。
所以第一版更像是“半结构化自动化”：Agent 负责把数据和材料收齐，按比较稳定的结构给出观察和建议；真正的组织口径，比如什么叫严重延期、什么叫缺陷过多、什么叫质量风险高，后续应该逐步沉淀成配置或规则。
这个边界很重要。否则系统会看起来什么都能分析，但实际结论没有团队上下文。
数据源优先级
任务执行时，不同数据源的可信度也不一样。结构化数据库通常优先级最高，因为它来自内部系统；上传的测试报告次之，因为它可能包含人工补充的背景；外部搜索结果更多用于对照和启发，不应该反过来覆盖内部事实。
可以简单按这个顺序处理：
- 先查内部结构化数据，得到事实底座。
- 再读上传材料，补充背景、风险和人工描述。
- 最后检索行业实践，用来补充参考口径。
- 报告里明确哪些是内部数据，哪些是外部参考。
这样报告不容易被外部资料带偏。比如 DORA 指标可以作为对照，但不能直接说团队一定要达到某个行业数字，因为不同团队规模、业务形态和发布节奏都不一样。
为什么这个场景适合做成系列项目
这个项目后续还有很多自然扩展点：接更多研发数据表、补内部规范知识库、沉淀报告模板、增加任务验收、做 SQL 审计和报告引用校验。它不是一个一次性脚本，而是可以慢慢长成研发效能工作台。
第一版选择 Multi-Agent，是因为它先把“开放任务如何拆解”这件事跑通；后续随着高频场景稳定下来，反而可以把一部分能力从 Agent 里沉淀成固定工具和模板。这个方向比一直堆 Agent 更健康。
