#技术架构演进路线

本页描述 Druce 的目标参考架构（五层）与当前 Demo 实现（同步单进程 Streamlit）之间的差距。差距列表区分两类：

• 跨越交付边界的必补项 —— 不补就无法交付初步报告模块。
• 通用 Agent 模板借用的项 —— 听起来生产级，但对投研初步报告场景低收益或过度，可能永远不做。

演进路径只列前者。差距归类与术语定义参见 CONTEXT.md，架构决定参见 docs/adr/。

整个系统可拆分为 五层逻辑架构，从用户交互到数据持久化逐层贯通。

#1. 表现层 – 交互与任务管理

• 核心组件：Streamlit（目标；当前 Demo 同步单进程）
• 承担职责：
  • 多角色工作台（买方研究员/投资经理/个人投资者切换不同视图）—— 目标能力，当前为单研究员自用，见 ADR-0001
  • 异步任务提交与进度轮询（通过轮询 Celery 任务状态或 WebSocket 回调）—— 目标，当前 run_pipeline() 同步执行
  • 报告结果渲染（Markdown/表格/情绪曲线/来源链接）
• 关键设计：
  • 用 session_state 维护会话内的临时状态（如当前自选股列表、上传的文件暂存路径）
  • 与后端通过 RESTful API（由 FastAPI 轻量包裹）交互，解耦 Streamlit 与核心逻辑

#2. Agent 编排层 – 任务理解与调度

• 核心框架：LangChain（LangGraph 扩展）+ MCP 协议
• 内部模块：
  • 意图路由器：根据用户输入分类（广域搜集/私有库问答/社区监控），选择不同 Agent 分支
  • 规划器（Planner）：将复杂查询拆分为 Plan-and-Execute 步骤，如“先搜行业总览 → 再搜头部公司动态 → 最后交叉验证关键数据”
  • 执行器（Executor）：调用工具并管理上下文窗口，使用 ReAct 或 OpenAI Functions 模式
  • 验证器：对搜索结果的来源多样性、时效性、一致性做自动检查，触发补充搜索
  • MCP 服务端/客户端：将搜索工具、知识库检索、文件解析等封装为标准 MCP 接口，方便工具热插拔

#3. 工具层 – 外部能力抽象

• 联网搜索工具：Tavily API / Bing API 封装，支持 site: 语法、日期过滤器、递归深度控制
  • 增加网页正文抓取适配器：对摘要不全的链接，使用 playwright 异步无头浏览器获取全文（需纳入 Celery 异步执行）
  • 内建去重与降噪管道：URL 指纹去重、内容相似度去重（SimHash）、低质站点黑名单
• 私有知识库工具：Chroma + PyPDF + 文本分割器
  • 支持 父子文档检索（Parent Document Retriever）：用小颗粒度检索，返回大颗粒度上下文，保证连贯性
  • 元数据过滤：可依文件来源、日期、研究员筛选
  • 检索后重排序（Reranker）：用轻量 Cross-Encoder 模型提升相关性
• 社区情绪工具：指定站点抓取 + 情感提取管道
  • 封装为“获取雪球热帖”、“提取东财股吧情绪”等工具，返回结构化 JSON（情绪分数、关键词云、异动归因）

#4. 数据与任务层 – 异步、状态持久化

• 任务队列：Celery + Redis —— deprecated，详见 ADR-0002
  • 当前 run_pipeline() 同步链路实测 1-3 分钟，AC-05 的 15 分钟上限已达标
  • 任务队列抽象层对当前 Druce（单用户、1-3 分钟负载）属过度工程
  • 若未来负载真逼近 15 分钟（深搜、多跳、大私有语料），首选 ThreadPoolExecutor + SQLite task 表
• 数据存储：
  • Redis：原承担热门查询缓存 + 任务状态，deprecated 后不再引入
  • PostgreSQL / SQLite：存储最终报告、用户配置、自选股列表、任务历史（Demo 阶段可用 SQLite，成熟后切换）
  • 向量数据库：Chroma 持久化模式，维护私有库索引
• 定时调度：主动感知（Celery Beat）的场景待澄清——若需定时监控社区情绪，可单点评估轻量调度方案，不绑 Celery+Redis

#5. 模型层 – 低成本、多模型路由

• 默认模型：DeepSeek（更优中文能力，成本极低，作为主力）
• 备选路由：当 DeepSeek 不可用时自动降级至 GPT-3.5-turbo
• 模型专用适配：为情感分析、摘要、报告生成等任务编写不同的 System Prompt 模板，保持输出一致

#整体数据流示例（买方研究员生成周报）

以下为目标架构数据流（演进后状态）。当前 app/ 为同步单进程实现，run_pipeline() 同步执行。当前同步数据流参见 数据流。

1. 用户在 Streamlit 输入“生成新能源汽车行业本周动态周报”。
2. 前端将任务提交至 Celery，返回 task_id，界面进入轮询。
3. Worker 中 Agent 规划步骤：
   • 并行搜索“新能源汽车 本周 政策” “销量 周报” “头部公司 动态” 等 6 个方向
   • 对搜索结果去重、抓取正文、LLM 摘要提取关键信息
   • 合并信息，交叉验证事实，发现矛盾则追加搜索
   • 调用模板生成结构化周报（Markdown）
4. 结果存入 PostgreSQL，前端轮询到完成状态后拉取展示。

#与成熟 Agent 的核心差距

当前选型虽能快速验证业务，但距离 7x24 生产级、高可靠、可演进的成熟 Agent 存在以下关键短板。每项标注归类：

• 〔跨越交付边界〕 —— 必补，演进路径收录。
• 〔借用模板〕 —— 通用 Agent 模板项，对投研初步报告场景低收益或过度，可能永远不做。

#1. 状态与记忆 〔借用模板〕

• 现状：Streamlit session_state 仅维持单次会话，无长期记忆。Agent 每次对话独立，不记得上次搜索偏好或用户身份。
• 差距：成熟 Agent 需要持久化的用户画像、对话历史、搜索偏好，并能根据历史交互主动调整策略。需引入对话数据库与记忆管理模块（LangChain 的 Memory 结合持久化存储）。
• 归类理由：投研初步报告每次问题独立、无状态即可；记忆持久化是通用 Agent 模板项。

#2. 多用户与隔离 〔不适用〕

• 现状：单机 Chroma 与 Celery 默认单用户运行，多用户时知识库文件、任务队列、API 密钥完全共享。
• 差距：需要租户隔离：每个用户/团队的私有知识库独立索引，任务队列需按用户分流，计费与 API 配额按用户管控。必须加入用户认证与授权层（如 JWT + 角色控制）。
• 归类理由：grilling round 3 确认 Druce 现阶段是单研究员自用工具，多用户是"有则更好"的未来需求。road-map 用多租户 SaaS 语言描述"多用户"是从通用 Agent 模板抄来的。详见 ADR-0001。

#3. 工具可靠性 & 错误自愈 〔跨越交付边界〕

• 现状：搜索 API 可能限流、目标网站反爬导致抓取失败、PDF 解析出错，当前缺乏系统级容错。
• 差距：成熟 Agent 需实现：
  • 指数退避重试、断路器模式，防止级联失败
  • 工具降级：Bing API 不可用时自动切换 Tavily
  • 异常捕获结构化，将错误作为观测信号反馈给规划器
• 归类理由：投研场景下搜索 API 限流、反爬、PDF 解析出错高频发生，重试/降级/断路器是真收益。

#4. 可观测性与评估 〔借用模板〕

• 现状：无日志聚合、无 Trace，排查 Agent 决策链困难。LLM 输出质量无量化评估。
• 差距：必须建立 LLM 可观测性栈（如 LangSmith、LangFuse），记录每一步的 prompt、工具调用、响应时间。同时建立离线评估数据集（黄金问答集），用于回归测试 prompt 变更是否退化。
• 归类理由：LangFuse Trace 可选；黄金问答集回归对投研场景（每次问题不同、人工看报告即可判断好坏）低收益。

#5. 安全与护栏 〔拆解〕

road-map 原把三件事捆成一条必补，grilling round 3 确认这是模板抄来的捆绑——三件事在投研场景下的必要性不同。拆解如下：

#5a. 金融合规声明 〔跨越交付边界〕

• 差距：输出审计——金融合规检查（如声明"不构成投资建议"）、杜绝诽谤性内容。
• 归类理由：投研报告给客户看时是硬需求，报告渲染层加免责声明即可，工作量小。

#5b. 越狱检测 / 注入防御 〔借用模板〕

• 差距：输入检测——敏感主题阻断、注入攻击防御。
• 归类理由：通用 LLM 面向公众产品的语言，对自用工具过度。

#5c. 工具层权限最小化 〔降级为防御编程常识〕

• 差距：禁止访问内网、限制爬虫并发数。
• 归类理由：防御性编程常识，不该作为"差距"单列，从必补清单剔除。

#6. 复杂文档理解 〔跨越交付边界〕

• 现状：仅 PyPDF 处理文本型 PDF，对财报中的表格、扫描件、图表无法理解。
• 差距：成熟 Agent 需引入多模态文档解析（如 Unstructured.io + GPT-4V 解析图表），并支持 .docx、.xlsx 等格式，才能处理真正的内部研报。
• 归类理由：内部研报含表格/扫描件/图表，纯 PyPDF 文本解析不够，是真差距。road-map 原把它捆在演进路径步骤 5"按需扩展"里，等于把真差距降级成可选——这是路径排序错误，应提级。详见 CONTEXT.md「多模态文档」条目。

#7. 主动感知与推送 〔跨越交付边界〕

• 现状：个人投资者需求需要实时提醒，目前依赖前端轮询或人工触发。
• 差距：需要事件驱动架构，通过 Celery Beat 定时执行监控任务，一旦社区情绪异动（如突发暴跌讨论），通过 WebSocket 或消息推送（邮件/微信）实时通知用户。
• 归类理由：对应 PRD 个人投资者"实时提醒、社区情绪监控"场景，Celery Beat 定时监控 + 推送是真差距。road-map 原把它和多模态文档一起捆在步骤 5"按需扩展"——与多模态文档同因，应拆出提级。详见 CONTEXT.md「主动感知与推送」条目。

#8. 成本与性能可控 〔借用模板〕

• 现状：无 Token 用量追踪，无法按任务类型限流，高并发下极易耗尽预算或触发 API 限流。
• 差距：加入成本跟踪器（统计每次调用的 Token 消费），设置单用户/单日预算上限，并对热门查询做语义缓存（Cache 之前的 LLM 响应），大幅降低重复成本。
• 归类理由：DeepSeek 成本已经极低；语义缓存对投研场景（每次问题不同）低收益；Token 追踪可选。整体是通用 Agent 模板项。

---

#演进路径建议

演进路径只列跨越交付边界的必补项，按依赖与收益排序。通用 Agent 模板带来的项（多用户隔离、越狱检测、语义缓存、对话记忆持久化、LangFuse Trace、黄金问答集回归）不在此列——它们对投研初步报告场景低收益或过度，归类理由见上文各差距条目。

1. 工具可靠性 + 合规声明 —— 真差距，立即补

   • 重试 / 降级 / 断路器（差距 3）
   • 报告渲染层加"不构成投资建议"免责声明（差距 5a）

2. 多模态文档解析 —— 真差距，从原步骤 5 提级

   • Unstructured.io + GPT-4V 解析图表、支持 .docx / .xlsx
   • 内部研报含表格 / 扫描件 / 图表，纯 PyPDF 文本解析不够
   • 详见 CONTEXT.md「多模态文档」条目

3. 主动感知与推送 —— 真差距，从原步骤 5 提级

   • 定时监控社区情绪 + WebSocket / 邮件 / 微信推送
   • 对应 PRD 个人投资者"实时提醒、社区情绪监控"场景
   • 调度方案单点评估（轻量定时器即可，不绑 Celery+Redis）
   • 详见 CONTEXT.md「主动感知与推送」条目

已废弃：原步骤 2「异步队列 Celery + Redis」已 deprecated。 AC-05 的 15 分钟上限由当前同步链路（实测 1-3 分钟）满足，异步队列对单用户、1-3 分钟负载属过度工程。 详见 ADR-0002 与 CONTEXT.md「异步执行」条目。

上述路径只列跨越交付边界的必补项。通用 Agent 模板带来的项（多用户隔离、越狱检测、语义缓存、对话记忆持久化）不在此列——它们对投研初步报告场景低收益或过度，详见 CONTEXT.md 各条目与 docs/adr/。

技术栈总览参见 技术栈，核心流程参见 数据流。 差距归类与术语定义参见 CONTEXT.md，架构决定参见 docs/adr/。