🖥️

报告前端 deep-research

AI 研究报告生成系统的 Next.js 15 前端。提供报告向导、舆情选择、5 步研究流水线、报告展示编辑与导出。支持"proxy"（后端流水线）与"local"（浏览器直连 LLM）两种模式。

Next.js 15 React 19 TypeScript Tailwind 3 Zustand pnpm

本页导航

# 一、5 步研究流水线（核心业务流）

前后端共同实现这条流水线。舆情报告是其特化：跳过提问与现场搜索，直接用采集端已标注的素材。

步骤	名称	说明
1	Ask Questions	LLM 生成关于研究主题的澄清问题
2	Report Plan	LLM 生成带章节的结构化研究大纲
3	SERP Queries	按章节生成搜索查询，执行 web/知识库/API 搜索
4	Search Summary	按任务把搜索结果总结为关键发现
5	Final Report	按章节撰写带引用的完整 Markdown 报告

# 二、前端架构（`src/`）

路由：使用自定义 hash 路由（HashRouter），非标准 Next.js 文件路由。路由：#/（主）、#/no-auth、#/templates、#/templates/create。

`src/api/` — 客户端 API 模块（Axios，调 Python 后端）

文件	职责
`base.ts`	报告 CRUD、流水线步骤、模板、指标（~40 端点）
`knowledge.ts`	知识库搜索（经 `/langwell-api` 代理）
`chat.ts`	报告对话
`customApi.ts`	自定义 API 管理
`sentimentMonitor.ts`	舆情监控服务
`baseRequest.ts`	主 Axios 实例，从 hash 参数读 `token`/`tenantid`

`src/utils/deep-research/` — 本地模式 AI 引擎

index.ts — DeepResearch 类，用 Vercel AI SDK streamText 编排流水线
provider.ts — AI 供应商工厂（Google/OpenAI/Anthropic/DeepSeek/xAI/Mistral/Azure/OpenRouter/Ollama 等）
search.ts — 搜索供应商工厂（Tavily/Firecrawl/Exa/Bocha/SearxNG）
prompts.ts — 从 constants/prompts.ts 模板构造提示词

# 三、状态管理（Zustand `src/store/`）

Store	职责
`global.ts`	UI 状态（当前步骤 1-5、弹窗开关）
`setting.ts`	配置（持久化到 localStorage）：AI 供应商 Key、搜索供应商、语言
`task.ts`	研究会话中枢：报告 ID、大纲、搜索任务、最终报告分节
`chat.ts`	报告对话状态

src/hooks/useDeepResearch.ts 是主编排 hook（~1500 行），管理完整流水线：askQuestions、generateReportPlan、searchResultHandler、writeFinalReport，并连接后端 SSE。

# 四、数据流与代理

Frontend (Next.js) ──rewrites──► Python Backend (FastAPI)
     │
     ├─ /deep-research-api/*   →  报告流水线 API (MongoDB)
     ├─ /langwell-api/*        →  知识库服务
     └─ /api/ai/*              →  AI 供应商代理 (middleware)

src/middleware.ts 拦截 /api/* 作为鉴权代理：校验访问密码、注入服务端 API Key、转发到上游供应商。支持 "local"（浏览器直连）与 "proxy"（服务端 Key）两种模式。

另含 src/libs/mcp-server/：完整的 MCP（Model Context Protocol）服务端实现，支持 SSE 与 StreamableHTTP 传输。

# 五、UI 技术栈

React 19 · Tailwind CSS 3 · shadcn/ui（Radix 基元）· Ant Design（Steps 等）· Lucide 图标 · react-markdown · ECharts · Mermaid · i18next（zh-CN / en-US / es-ES）。

关键环境变量

DEEP_RESEARCH_API（Python 后端 URL）、LANGWELL_DOC_SERVER、NEXT_PUBLIC_BASE_URL=/deep-research-api

运行要求

Node.js ≥ 18.18.0，必须用 pnpm（见 .npmrc、.node-version）

# 六、构建

cd deep-research
pnpm install                  # 安装依赖（用 pnpm，不是 npm/yarn）
pnpm dev                      # Turbopack 开发（先 copy env.tpl → .env.local）
pnpm build                    # 生产构建（标准）
pnpm build:export             # 静态导出（静态托管）
pnpm build:standalone         # standalone（Docker）
pnpm lint                     # ESLint

静态导出模式（build:export）会临时移出 src/app/api 以避免静态构建中出现 API 路由。环境文件：开发 env.tpl → .env.local，生产 env.production.tpl → .env.production。

运行依赖

纯前端，自身不接数据库 / MQ / 对象存储。运行时依赖：① 报告后端 deep-research-python（DEEP_RESEARCH_API，流水线与素材读取）；② 知识库服务（LANGWELL_DOC_SERVER）；③ "local" 模式下由浏览器直连各 AI 供应商。构建期要 Node.js ≥ 18.18.0 + pnpm。