---

"龙虾调研"开发复盘：AI自动研报框架的架构设计、难点落地与工程实践

大家好，我是 Lobster Research（龙虾调研）的开发者。本篇从真实开发历程出发，分享一套 AI 研报生成框架从 0 到 1 的架构思路、关键技术难点、落地方案与踩坑经验，面向正在做垂直领域 AI 应用、数据采集、自动化报告、Agent 技能的开发者。

---

一、项目出发点：解决 AI 应用的普遍痛点

在做多个 AI Agent 项目后，我观察到几个高频问题：

1. 大模型擅长理解与生成，但实时/结构化数据获取能力弱，输出容易脱离事实。
2. 数据采集脚本稳定可靠，但不具备总结、写作、逻辑整合能力。
3. 研报/分析类工具要么封闭黑盒，难以二次开发；要么太零散，无法形成流水线。
4. AI 自由生成内容格式不可控，无法直接生成标准 PDF、无法嵌入系统。
5. 面向普通用户的工具太重，面向开发者的框架缺少工程化规范。

基于这些问题，我确定了 Lobster Research 的核心思路：
代码负责确定性数据采集，AI 负责理解性分析整合，报告渲染由代码保证稳定输出。

---

二、整体架构：四阶段分离式设计（核心）

项目最终采用四阶段严格解耦的流水线架构，层与层之间只通过 JSON 通信，不交叉、不渗透。

1. Phase 1：代码驱动数据采集

职责：实时行情、K 线与技术指标、个股/行业/宏观基础数据、多源搜索、市场情绪、新闻资金数据。
输出：固定结构 JSON 文件，存入 output/tasks/任务ID/。
设计原则：

• 所有数据获取由 Python 完成，不依赖任何 AI 能力。
• 统一字段名、统一时间格式、统一涨跌标识、统一异常处理。
• 支持 quick 模式跳过耗时采集，提升快报生成速度。
  解决的问题：数据不可靠、格式混乱、AI 因数据异常导致写作失败。

2. Phase 2：AI 内容整合

职责：读取 Phase 1 数据 → 按报告模板写作 → 输出 5_agent_report_input.json。
设计原则：

• AI 只做内容填充，不采集、不搜索、不控制格式。
• 采用固定章节模板，强制结构稳定。
• 支持两种模式：
  • Agent 模式：外部 Agent 调度填充
  • Alone 模式：直接调用 LLM 自动完成
    解决的问题：AI 输出结构漂移、内容跑题、无法渲染。

3. Phase 3：代码驱动报告生成

职责：读取 AI 写作结果 → 渲染 HTML → 生成 PDF。
技术栈：Jinja2 + 纯 CSS + Playwright。
样式系统：

• 10 套色板
• 3 种渲染：纯色 / 渐变 / 液态光晕
• 3 种布局：圆角 / 方正 / 极简
  解决的问题：报告颜值低、样式不可控、跨平台不一致。

4. Phase 4：模拟持仓与策略进化

职责：基于研报结论自动执行交易决策、记录操作、反思复盘、调整策略参数。
定位：用于展示 Agent 闭环决策能力，非实盘交易建议。

---

三、核心技术难点与落地实现（高密度细节）

1. 多数据源兼容：统一适配与格式收敛

项目接入新浪财经、腾讯财经、AKShare、证券之星、多引擎搜索等多个来源，面临大量差异：

• 股票代码规则不同（sh/sz/hk/us）
• 字段命名不统一
• K 线复权、缺失值处理不同
• 涨跌颜色规则不同
• 接口返回结构随时间变化

最终方案：适配器模式 + 内部统一 Schema

• 每个数据源独立封装，对外提供相同结构。
• 行情、K 线、资金、新闻分别定义标准结构。
• 上层流程不感知底层数据源，便于后续替换/扩展。
  关键处理：
• 统一时间戳为北京时间
• 统一涨跌方向：国内市场红涨绿跌
• 缺失数据自动填充或标记，避免流程中断

2. AI 输出稳定化：从自由生成到结构化填充

早期版本直接使用自由 Prompt，出现大量问题：

• 章节混乱、字数波动巨大
• 关键数据遗漏
• 格式不统一，无法渲染 PDF
• 重复、跑题、幻觉

最终方案：外置模板 + 章节式写作

• 设计 29 套报告模板（7 快报 + 22 研报），全部外置 JSON。
• 每个模板固定：标题、章节、要点、字数、数据要求。
• AI 只填充 content 字段，不控制结构。
• 优先使用 function calling 输出 JSON，无 FC 则降级为可解析 Markdown。
  效果：报告结构稳定性显著提升，可直接进入渲染流程。

3. 轻量级 NLP 路由：不依赖模型的意图识别

需求：用户输入自然语言，自动识别：

• 领域：股票 / 行业 / 大盘 / 科技 / 农业等
• 报告类型：快讯 / 快报 / 研报

最终方案：双层关键词匹配

1. 领域路由：main.json 配置关键词集合
2. 报告类型路由：按深度词、长度、意图词判断
   优势：

• 无 Token 消耗
• 响应速度快
• 可热更新、可调试、可解释
• 不依赖模型状态
  优化：持续补充同义词、形近词、口语化表达，提升匹配准确率。

4. PDF 渲染系统：纯 CSS 驱动的高可用样式

需求：美观、稳定、可配置、跨平台一致。
实现方案：

• 使用 CSS 变量定义色板，data-* 属性驱动主题切换。
• liquid 模式使用光晕 + 毛玻璃，仅在支持的渲染环境生效。
• 分页、标题层级、表格、图表容器做专门兼容。
  踩坑内容：
• Playwright 打印模式下渐变、毛玻璃效果可能失效
• 长表格跨页分裂
• 图片尺寸、字体嵌入导致 PDF 过大
• 不同平台渲染行距差异
  解决方案：
• 固定页面宽度
• 强制表格分页兼容
• 使用标准字体
• 简化打印模式下的高级特效

5. 双模式运行：Agent 模式 + Alone 模式

为了同时满足嵌入 Agent 平台和独立运行两种场景，设计双模式：

• Skill 模式：作为外部 Agent 技能，等待 Agent 完成 Phase 2。
• Alone 模式：不依赖任何平台，直接调用 LLM 自动跑完全流程。
  实现：
• 统一入口 main.py
• 配置项 system.run_mode 切换
• 数据流程、渲染流程完全共用
  优势：一套代码支持两种部署形态，开发与生产环境统一。

6. 工程化体系：日志、配置、任务、测试

为支持长期迭代，项目做了完整工程化：

• 日志：LobsterLogger，按天切割，记录关键步骤与异常。
• 配置：所有关键词、模板、路由、API 外置 JSON，不写死代码。
• 任务隔离：每个任务独立目录，互不干扰。
• 测试套件：test.runner 覆盖 CLI、数据采集、样式、报告生成。
• 无状态设计：支持中断、重试、重入，便于服务化部署。

---

四、三次架构重构：从可用到好用

第一阶段（V0.1–V0.6）

单体脚本 + 自由 Prompt，能跑但不稳定，无法扩展，PDF 样式简陋。

第二阶段（V1.0–V1.6）

拆分数据/AI/渲染模块，加入模板与 CLI，结构更清晰，但不支持 Agent。

第三阶段（V2.0–V2.2）

四阶段架构定型，支持 Agent + Alone 双模式，完善样式系统、模拟持仓、日志与测试，达到可开源、可复用、可二次开发标准。

---

五、设计中的取舍与权衡

1. 优先聚焦国内市场
   数据源、股票代码、关键词、提示词均面向 A 股生态，国际化成本较高，后续逐步支持。

2. 先广度后深度
   先覆盖 23 个领域建立框架，再逐步为各领域补充专业数据与深度逻辑。

3. 模板化优于自由生成
   为了稳定性与可渲染性，放弃部分灵活性，保证输出可产品化。

4. 面向开发者优先
   暂不提供 GUI，聚焦 CLI 与 Agent 集成，降低维护成本，提升扩展性。

5. 数据与 AI 强解耦
   不追求端到端黑盒，明确分工，提升可维护性与问题定位效率。

---

六、总结

Lobster Research 的核心价值，并非只是提供投资分析能力，而是提供一套可直接复用的工程化范式：
数据采集 → AI 整合 → 报告渲染 → 闭环扩展。

整个开发过程中，最有价值的收获是：

• 垂直 AI 应用的关键不在模型，而在结构、稳定性、工程化。
• 数据层与 AI 层必须清晰分离，才能保证可靠输出。
• 自动化报告必须走模板 + 代码渲染，才能真正产品化。
• 框架类项目一定要做取舍，聚焦场景，才能做到简洁可用。

希望这些真实的架构思路、技术难点与踩坑经验，能为做同类项目的开发者提供一些参考。

---

项目信息

项目名称：Lobster Research（龙虾调研）
开源地址：https://github.com/hegeo/Lobster-Research
协议：MIT
定位：AI 研报生成框架｜Agent 技能｜自动化报告工具

---