# https://github.com/AnotiaWang/deep-research-web-ui 项目说明书 生成时间：2026-06-26 07:36:08 UTC ## 目录 - [项目概览与特性](#page-overview) - [系统架构与数据流](#page-architecture) - [AI 服务商集成](#page-ai-providers) - [联网搜索后端集成](#page-web-search) - [前端组件与搜索可视化](#page-frontend) - [部署模式与运维配置](#page-deployment) - [配置、状态管理与历史记录](#page-data-history) - [已知问题与故障排查](#page-troubleshooting) ## 项目概览与特性 ### 相关页面 相关主题：[系统架构与数据流](#page-architecture), [部署模式与运维配置](#page-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) - [i18n/nl.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/nl.json) - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json)
# 项目概览与特性 ## 一、项目定位与目标 Deep Research Web UI 是 [dzhng/deep-research](https://github.com/dzhng/deep-research) 的可视化前端实现，对原项目在交互、可用性与部署方面进行了多项改进 资料来源：[README.md:1-3]()。项目提供浏览器端的研究流程编排能力：用户输入研究主题后，AI 会先询问澄清问题，然后自动进行多轮网络搜索，最终输出结构化的研究报告 资料来源：[i18n/zh.json:1-180]()。 整个应用基于 Nuxt 3 框架构建，并通过 [`edgeone.json`](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json) 中的 `buildCommand: pnpm generate:optimize` 生成静态站点，可托管在任意 CDN 或静态服务上 资料来源：[edgeone.json:1-18]()。 ## 二、四大研究流程 UI 将研究过程拆分为四个连续阶段，所有阶段共用同一个研究目标（research goal）： 1. **研究主题**（researchTopic）—— 输入主题、设置问题数、深度（depth）与广度（breadth）。 2. **模型反馈**（modelFeedback）—— AI 给出追问列表，用于澄清研究方向。 3. **联网搜索**（webBrowsing）—— 根据反馈生成搜索任务并迭代 `depth` 轮，结果以树状结构可视化。 4. **研究报告**（researchReport）—— 汇总所有访问过的 URL 与学习要点，生成可导出的报告。 ```mermaid flowchart LR A[1. 研究主题] --> B[2. 模型反馈] B --> C[3. 联网搜索
depth 轮迭代] C --> D[4. 研究报告
导出 PDF / Markdown] C -.失败重试.-> C D -.重新生成.-> D ``` 资料来源：[i18n/zh.json:135-180]() 中的 `researchTopic`、`modelFeedback`、`webBrowsing`、`researchReport` 四个顶级键。 ## 三、核心特性一览 ### 3.1 隐私与部署 - **客户端模式（Client Mode）**：配置和 API 请求均通过浏览器本地发出，不经服务端转发 资料来源：[README.md:9-10]()。 - **服务端模式（Server Mode）**：v1.2.0 引入，通过环境变量集中注入配置，终端用户无需手动填写密钥 资料来源：[README.md:14-15]()。 - **Docker 一键部署**：内置 Docker 镜像，便于私有化 资料来源：[README.md:13]()。 ### 3.2 实时反馈与可视化 - 使用 Vercel AI SDK 的流式响应，将 AI 的 `reasoning` 与 `text-delta` chunk 实时展示给用户 资料来源：[shared/utils/json.ts:7-32]()`。 - 搜索过程以树状结构呈现，支持点击节点查看访问 URL、生成的搜索词与学习结论 资料来源：[i18n/zh.json:155-175]()`。 - 支持搜索流程全屏放大（v1.1.4），便于追踪长时间运行的研究 资料来源：[社区讨论 #69](https://github.com/AnotiaWang/deep-research-web-ui/issues/69)。 ### 3.3 多供应商兼容 底层使用纯提示词而非 OpenAI 较新的 Structured Outputs 特性，因此可以兼容更多尚不支持新接口的供应商 资料来源：[README.md:12-13]()`。 | 类别 | 已支持的供应商 | |------|----------------| | AI 服务 | OpenAI Compatible、SiliconFlow、InfiniAI、DeepSeek、OpenRouter、Ollama、302.AI | | 联网搜索 | Tavily、Firecrawl（云端 / 自部署）、fastCRW（`crw`，云端 / 自部署）、Google PSE | 资料来源：[README.md:18-21]() 与 [README_zh.md:10-12]()`。 ### 3.4 报告导出与历史 - 报告可导出为 Markdown 或通过浏览器原生打印能力导出为 PDF（v1.1.5 起） 资料来源：[社区 Release v1.1.5](https://github.com/AnotiaWang/deep-research-web-ui/releases/tag/v1.1.5)。 - 报告内置来源引用（citation），与研究阶段收集的 URL 一一对应 资料来源：[社区 Release v1.1.7](https://github.com/AnotiaWang/deep-research-web-ui/releases/tag/v1.1.7)。 - 提供本地历史记录功能，支持导出 / 导入，方便跨设备复用 资料来源：[i18n/zh.json:35-55](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json)、[社区 Issue #57](https://github.com/AnotiaWang/deep-research-web-ui/issues/57)。 ## 四、配置架构 ### 4.1 双模式运行时配置 `shared/types/config.ts` 定义了两套配置结构： - `ServerRuntimeConfig`：包含敏感字段（API Key、API Base），仅在服务端可用。 - `PublicRuntimeConfig`：仅暴露非敏感字段（provider 名称、模型名、上下文长度、并发数等），可下发到浏览器。 资料来源：[shared/types/config.ts:1-50]()`。 ### 4.2 服务端模式环境变量 服务端模式下，管理员通过 `NUXT_*` 前缀的环境变量注入配置，覆盖上文 `ServerRuntimeConfig` 的全部字段；`NUXT_PUBLIC_*` 系列则会下发给浏览器决定默认 UI 选项 资料来源：[README_zh.md:60-86]()。 ### 4.3 核心能力聚合 `lib/core/index.ts` 仅作为门面（facade）模块，统一对外暴露 `deep-research` 与 `feedback` 两个核心模块，避免上层页面直接依赖散落的实现 资料来源：[lib/core/index.ts:1-3]()`。 ## 五、国际化与用户体验 应用已内置三种语言： - 中文（`i18n/zh.json`） - English（`i18n/en.json`） - Nederlands（`i18n/nl.json`，v1.1.3 引入） 资料来源：[i18n/zh.json:1]()、`i18n/en.json:1]`、`i18n/nl.json:1]()`。 另外，应用会在启动后检查 `version.json` 并提示新版本（autoUpdate），自托管用户被提醒重新部署以获取修复 资料来源：[i18n/zh.json:90-100]()`。当某个供应商拒绝跨域请求时，UI 会展示明确的 CORS 错误提示，引导用户切换服务 资料来源：[i18n/zh.json:85-88]()`。 --- ## 六、社区高频关注点 - **API 化封装**：用户希望将整套研究流程封装为 HTTP 接口，输出纯 Markdown 字符串 — 见 [Issue #79](https://github.com/AnotiaWang/deep-research-web-ui/issues/79)。 - **多 Key 轮询**：Tavily 单账号 1000 次 / 月的额度不足以支撑深度研究，PR #77 已合并 Tavily + Google PSE 的多 Key 轮询支持 — 见 [Issue #75](https://github.com/AnotiaWang/deep-research-web-ui/issues/75)。 - **服务端模式**：从 #8 提出到 v1.2.0 实现，环境变量配置取代了每次手动输入 资料来源：[README.md:14-15]()`。 - **最终报告过短**：用户反馈搜索阶段很丰富但最终报告只有模型一轮总结，已纳入改进计划 — 见 [Issue #69](https://github.com/AnotiaWang/deep-research-web-ui/issues/69)。 --- ## See Also - [环境变量与部署配置](environment-variables.md) - [AI 供应商接入指南](ai-providers.md) - [联网搜索供应商接入指南](web-search-providers.md) - [研究报告生成与导出](research-report.md) --- ## 系统架构与数据流 ### 相关页面 相关主题：[AI 服务商集成](#page-ai-providers), [联网搜索后端集成](#page-web-search), [部署模式与运维配置](#page-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts) - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) - [i18n/nl.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/nl.json) - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json)
# 系统架构与数据流 ## 整体架构概览 Deep Research Web UI 是 [dzhng/deep-research](https://github.com/dzhng/deep-research) 的可视化前端实现，基于 Nuxt 3 构建。其设计目标是在浏览器侧完成所有 AI 与联网搜索调用，避免后端代理密钥，从而在「客户端模式」下实现隐私安全 ([README.md:1-15](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md))。同时，自 v1.2.0 起新增「服务端模式」，允许通过环境变量统一配置 API 密钥，用户无需在浏览器侧填写 ([README.md:13-15](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md))。 项目结构由三层组成： - **UI 层**：Nuxt 应用页面，包含研究主题输入、模型反馈、联网搜索流程可视化与研究报告输出四个步骤。 - **核心逻辑层** (`lib/core`)：封装深度研究与反馈生成的算法，由 `lib/core/index.ts` 统一导出 ([lib/core/index.ts:1-4](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts))。 - **共享工具层** (`shared`)：跨页面复用的工具函数，例如流式 JSON 解析。 ```mermaid flowchart LR A[用户输入研究主题] --> B[模型反馈
生成追问] B --> C[联网搜索
树状结构] C --> D[深度迭代
depth / breadth] D --> E[研究报告生成] E --> F[导出 Markdown / PDF] subgraph 客户端浏览器 A B C D E F end C -. API .-> G[Tavily / Firecrawl
fastCRW / Google PSE] B -. API .-> H[OpenAI Compatible
SiliconFlow / InfiniAI
DeepSeek / 302.AI / Ollama] E -. API .-> H ``` ## 核心模块组成 `lib/core/index.ts` 充当核心逻辑的总入口，对外仅暴露两个模块：`deep-research` 与 `feedback` ([lib/core/index.ts:1-4](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts))。这种最小化导出策略有助于保持核心库的可移植性，便于未来在 Node CLI、测试或服务端 API 中复用同一份逻辑。 `shared/utils/json.ts` 提供 `parseStreamingJson` 生成器，接收来自 AI SDK 的流式片段 (`AsyncIterable>`)，通过累积文本并反复调用 `parsePartialJson` 实现「边生成边解析」的能力 ([shared/utils/json.ts:1-43](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts))。当流结束时若仍无法成功解析，会通过 `bad-end` 事件通知调用方 ([shared/utils/json.ts:40-43](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts))，对应 UI 中常见的「`invalidStructuredOutput` 模型返回的内容无效或不完整」错误提示 ([i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json))。 ## 研究流程数据流 研究流程由四个阶段串成 ([i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json))： 1. **研究主题** (`researchTopic`)：用户输入主题，配置问题数量 (numOfQuestions)、研究深度 (depth) 与广度 (breadth)，其中广度在每轮迭代中折半 ([i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json))。 2. **模型反馈** (`modelFeedback`)：AI 主动生成追问以澄清研究目标；用户提交回答后流入下一阶段。 3. **联网搜索** (`webBrowsing`)：根据研究目标调用联网搜索服务，按树状结构生成节点；用户可点击节点查看「研究目标 / 访问网址 / 结论」三项详情 ([i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json))。该流程支持全屏模式 (v1.1.4) 与失败节点重试 (v1.1.3)。 4. **研究报告** (`researchReport`)：综合所有节点结论后生成最终报告，支持浏览器原生打印为 PDF 或导出 Markdown (v1.1.5)，并在 v1.1.7 起在报告中附带来源引用信息。 流式处理通过 `parseStreamingJson` 串联起 AI SDK 的 `text-delta` 与 `reasoning` 事件，将「思考中 / 思考完毕」状态实时映射到 UI 的 `modelThinking` 文案 ([i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json))。 ## 部署模式与配置 项目支持两种部署模式，可通过 `NUXT_PUBLIC_SERVER_MODE` 环境变量切换 ([README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md))： | 模式 | 配置位置 | 适用场景 | |------|----------|----------| | 客户端模式 (Client Mode) | 浏览器 localStorage | 静态部署、EdgeOne Pages、Docker 默认模式 | | 服务端模式 (Server Mode) | 容器环境变量 `.env` | 团队/朋友共享部署，避免每个用户手动填写长密钥 | 服务端模式下，`NUXT_WEB_SEARCH_API_KEY` 支持使用逗号分隔配置多个 Tavily 或 Google PSE 密钥以实现轮询（社区 PR #76 / #77 已合入），有效缓解单账号每月 1000 次搜索额度的限制。`edgeone.json` 描述了 EdgeOne Pages 的构建命令 (`pnpm generate:optimize`) 与输出目录 (`.output/public`)，并为 `/version.json` 设置了 `Cache-Control: max-age=0` 以便前端自动检测更新 ([edgeone.json:1-18](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json))。 ## 国际化与前端结构 i18n 通过 `i18n/zh.json`、`i18n/en.json` 与 `i18n/nl.json` 三个词典文件实现，每个文件结构对应到 UI 上的命名空间（`index` / `settings` / `researchTopic` / `modelFeedback` / `webBrowsing` / `researchReport` / `error` / `autoUpdate` / `serverMode` / `history`），并使用 `{0}` 占位符实现动态插值 ([i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json))。新增荷兰语翻译 (NL) 于 v1.1.3 发布。前端的 `serverMode` 命名空间用于在服务端模式下提示用户「当前配置由服务器管理员设置」，加载失败时给出 `loadFailed` 提示 ([i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json))。 ## 常见失败模式与社区反馈 - **CORS 跨域被拦截**：当 API 提供商未配置允许跨域时，浏览器会阻断请求；前端通过 `error.requestBlockedByCORS` 文案引导用户更换供应商 ([i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json))。社区 issue #70 反馈 Azure OpenAI 拼接 base URL 出错，也与该机制相关。 - **Firecrawl 自部署限流不生效**（issue #73）：当使用自部署 Firecrawl 时，客户端的 `concurrencyLimit` 与服务端实际并发数不匹配，仍可能触发限流。 - **重试失败节点无响应**（issue #71）：在 `network error` 后点击 `webBrowsing.retry` 文案对应的按钮偶现无反应，这是 v1.1.3 引入的节点级重试能力的已知边界。 - **报告内容单薄**（issue #69）：前端在最终报告阶段仅做一次总结型调用，深度受限于模型的 `contextSize` 设置，建议配合更大的上下文窗口或多轮迭代。 ## See Also - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) — 项目概览与供应商列表 - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts) — 核心逻辑入口 - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) — 流式 JSON 解析实现 - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json) — EdgeOne Pages 部署配置 --- ## AI 服务商集成 ### 相关页面 相关主题：[联网搜索后端集成](#page-web-search), [系统架构与数据流](#page-architecture), [已知问题与故障排查](#page-troubleshooting)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts) - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json)
# AI 服务商集成 ## 概述 AI 服务商集成是 Deep Research Web UI 的核心能力之一，它把不同厂商的大模型 API 统一封装到前端可调用的接口中，使用户能够通过浏览器或服务端配置接入多种 AI 推理服务。本项目使用纯提示词（prompts）而非结构化输出（Structured Outputs）等较新特性，从而保证与尚未跟进 OpenAI 最新能力的更多厂商兼容 资料来源：[README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md)。 核心入口由 `lib/core/index.ts` 统一对外暴露，文件中再导出 `deep-research` 与 `feedback` 等模块： ```ts // Re-export all core functionality export * from './deep-research' export * from './feedback' ``` 资料来源：[lib/core/index.ts:1-3](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts)。 ## 支持的服务商 当前 Deep Research Web UI 已通过统一的"OpenAI 兼容协议"适配多家人工智能服务商。项目在 README 中列出了下述受支持的供应商： | 类别 | 供应商 | 备注 | |------|--------|------| | AI 服务 | OpenAI Compatible | 任意兼容 OpenAI 接口格式的供应商 | | AI 服务 | SiliconFlow（硅基流动） | 注册赠送 ¥14 免费额度 | | AI 服务 | InfiniAI（无问芯穹） | 支持 DeepSeek R1 满血推理加速版 | | AI 服务 | 302.AI | 注册赠送 $1 免费额度（v1.2.0 新增） | | AI 服务 | DeepSeek | 官方推理服务 | | AI 服务 | OpenRouter | 聚合多家模型 | | AI 服务 | Ollama | 本地部署 | | 联网搜索 | Tavily | 每月 1000 次免费 | | 联网搜索 | Firecrawl | 支持云端和自部署 | | 联网搜索 | fastCRW | 与 Firecrawl 兼容的网页抓取服务 | | 联网搜索 | Google PSE | 自定义搜索引擎（v1.1.9 新增） | 资料来源：[README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md)、[README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md)、[i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json)。 `i18n/zh.json` 中定义了 AI 服务的可选项（`providers`），明确区分了 `openaiCompatible`、`siliconflow`、`infiniai`、`302-ai` 四种内置配置，并通过文本描述（`description`）提示用户去相应平台生成 API key。 ## 部署模式与配置 ### 客户端模式（Client Mode） 客户端模式下，用户在浏览器中手动填写 API key、Base URL、模型名称等配置，所有请求直接从浏览器发出，配置和密钥均保存在本地 资料来源：[i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json)。该模式适合静态部署（如 `pnpm generate` 输出或 EdgeOne Pages）： ```json { "name": "deep-research-web", "buildCommand": "pnpm generate:optimize", "outputDirectory": ".output/public", "nodeVersion": "20.18.0" } ``` 资料来源：[edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json)。 ### 服务端模式（Server Mode） v1.2.0 引入了服务端模式：API key 以环境变量形式注入，部署后用户无需在 UI 中配置密钥 资料来源：[README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md)。典型 Docker 启动方式如下： ```bash docker run -p 3000:3000 \ -e NUXT_PUBLIC_SERVER_MODE=true \ -e NUXT_AI_API_KEY=your-ai-api-key \ -e NUXT_WEB_SEARCH_API_KEY=your-search-api-key \ -e NUXT_PUBLIC_AI_PROVIDER=openai-compatible ``` `NUXT_WEB_SEARCH_API_KEY` 支持为 Tavily、Google PSE 等传入逗号分隔的多个密钥以实现轮询（key rotation），参考社区 PR #76 / #77 资料来源：[README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md)。`i18n/en.json` 中定义了 `serverMode` 字段（如 `aiProvider`、`aiModel`、`webSearchProvider`、`searchLanguage`），用于在界面上呈现"由服务器管理员设置"的相关提示。 ### AI 设置项 设置面板中的 AI 配置项在 i18n 资源中具有统一定义： | 字段 | 含义 | |------|------| | `provider` | AI 服务商 | | `apiKey` | API 密钥 | | `apiBase` | API Base URL | | `model` | 模型名称 | | `contextSize` | 上下文长度，限制发送给模型的最大 token 数 | 资料来源：[i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json)、[i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json)。 v1.1.5 修复了"contextSize"未正确应用的 Bug；v1.1.8 改进了在没有填写 API key 时仍尝试拉取模型列表的能力 资料来源：[README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md)。 ## 流式响应与结构化解析 AI 在执行"追问→搜索→总结"链路时，需要在前端实时解析模型流式输出。`shared/utils/json.ts` 提供了基于 `parsePartialJson` 与 zod schema 的流式解析能力，能够区分 `reasoning`、`text-delta`、`error` 等事件，并对残缺 JSON 做容错（`repaired-parse` / `successful-parse`）： ```ts for await (const chunk of fullStream) { if (chunk.type === 'reasoning') { yield { type: 'reasoning', delta: chunk.textDelta } continue } if (chunk.type === 'error') { yield { type: 'error', message: chunk.error instanceof Error ? chunk.error.message : String(chunk.error), } continue } if (chunk.type === 'text-delta') { rawText += chunk.textDelta const parsed = parsePartialJson(removeJsonMarkdown(rawText)) isParseSuccessful = parsed.state === 'repaired-parse' || parsed.state === 'successful-parse' if (isParseSuccessful && isValid(parsed.value as any)) { yield { type: 'object', value: parsed.value } } } } ``` 资料来源：[shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts)。 这套机制同时支持推理模型（如 DeepSeek R1）和普通对话模型：当模型输出 `reasoning` 类型时，前端可单独展示"思考中"状态，`i18n/zh.json` 中通过 `modelThinking` 与 `modelThinkingComplete` 进行了本地化。如果最终未能解析成功，将抛出 `bad-end` 事件，UI 给出"无效或不完整"的提示，提示用户更换为更大或更"聪明"的模型 资料来源：[i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json)。 ## 常见问题 - **CORS 拦截**：当选择某些小众 AI 服务商时，浏览器端直接请求可能被 CORS 策略阻止，i18n 中专门给出了 `requestBlockedByCORS` 错误提示，建议用户更换服务或联系服务方 资料来源：[i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json)。 - **Azure OpenAI 适配**：社区反馈拼接 base URL 时未考虑 Azure 的 `api-version` 概念，会出现"资源不存在"错误，相关讨论见 issue #70 资料来源：[README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md)（社区上下文）。 - **API 调用封装**：用户曾请求将整个研究流程封装为单一 API（issue #79 / #78），目前 UI 仍以交互式页面为主，但服务端模式的引入为后续开放 HTTP 接口奠定了基础。 - **密钥轮询**：Tavily 单账号每月 1000 次额度常被耗尽，社区 PR #77 已经把 Tavily 与 Google PSE 的多密钥轮询合并实现，可通过 `NUXT_WEB_SEARCH_API_KEY=key1,key2,key3` 启用 资料来源：[README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md)。 ## See Also - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) — 项目主文档 - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) — 中文文档（含环境变量清单） - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) — 中文界面文案与 AI Provider 选项 - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) — 英文界面文案，含 Server Mode 配置说明 - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) — 流式 JSON 解析器 - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts) — 核心模块入口 - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json) — EdgeOne Pages 静态部署配置 --- ## 联网搜索后端集成 ### 相关页面 相关主题：[AI 服务商集成](#page-ai-providers), [已知问题与故障排查](#page-troubleshooting), [配置、状态管理与历史记录](#page-data-history)
相关源码文件 以下源码文件用于生成本页说明： - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) - [i18n/nl.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/nl.json) - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts) - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json)
# 联网搜索后端集成 ## 概述 `deep-research-web-ui` 是 [dzhng/deep-research](https://github.com/dzhng/deep-research) 的可视化 Web 前端。其核心能力之一是「联网搜索后端集成」：在前端调用用户配置的搜索服务，将查询结果交由 LLM 进行迭代式深挖，最终产出研究报告。系统支持多种搜索供应商（Tavily、Firecrawl、fastCRW/crw、Google PSE），并提供「客户端模式」与「服务端模式」两种部署方式 [资料来源：[README.md:1-25]()] [资料来源：[README_zh.md:1-25]()]。所有 i18n 文案与设置项均围绕这一集成设计，便于用户在不同语言环境下配置搜索行为 [资料来源：[i18n/zh.json:1-100]()]。 ## 架构与配置 ### 数据流概览 ```mermaid flowchart LR UI[用户界面
研究主题表单] --> Core[lib/core
deep-research] Core --> Search[searchProvider
Tavily/Firecrawl/CRW/GooglePSE] Search --> API[第三方搜索 API] API --> Search Search --> Core Core --> LLM[AI Provider] LLM --> Core Core --> UI Config[设置/环境变量] --> Core Config --> Search ``` 核心库入口 `lib/core/index.ts` 将 `deep-research` 与 `feedback` 模块统一对外暴露，作为搜索与 LLM 调用的中枢 [资料来源：[lib/core/index.ts:1-3]()]。 ### 搜索供应商配置 设置界面中的「联网搜索服务」区块通过 i18n key 暴露以下选项： | 配置项 | 说明 | 资料来源 | |--------|------|----------| | `provider` | 联网搜索服务，可选 `tavily` / `firecrawl` / `crw` / `google-pse` | [i18n/zh.json:71-95]() | | `apiKey` | API 密钥（Tavily 与 Google PSE 支持多 key 轮询，逗号分隔） | [README_zh.md:1-15]() | | `queryLanguage` | 搜索语言（如 `en` / `zh`） | [i18n/en.json:71-95]() | | `concurrencyLimit` | 并发数，限制同时进行的搜索数量以避免被限流 | [i18n/zh.json:71-95]() | | `apiBase` | 自定义 API Base URL（用于 Firecrawl 自部署） | [i18n/zh.json:71-95]() | 并发数提示文案明确说明：限制同时进行的搜索数量可以避免被 API 服务限流 [资料来源：[i18n/zh.json:71-95]()]。 ### 服务端模式环境变量 `v1.2.0` 起引入「服务端模式」，管理员可通过环境变量统一注入配置，终端用户无需在浏览器中填写任何密钥 [资料来源：[README_zh.md:1-25]()]。环境变量命名遵循 Nuxt 的 `NUXT_*` 约定（`NUXT_PUBLIC_*` 表示会暴露到客户端） [资料来源：[edgeone.json:1-15]()]。例如： - `NUXT_PUBLIC_WEB_SEARCH_PROVIDER`：默认 `tavily` - `NUXT_PUBLIC_WEB_SEARCH_CONCURRENCY_LIMIT`：默认 `2` - `NUXT_PUBLIC_WEB_SEARCH_SEARCH_LANGUAGE`：默认 `en` - `NUXT_PUBLIC_TAVILY_ADVANCED_SEARCH` / `NUXT_PUBLIC_TAVILY_SEARCH_TOPIC`：Tavily 高级选项 - `NUXT_PUBLIC_GOOGLE_PSE_ID`：Google PSE 的 `cx` 值 服务端模式启动时，UI 会显示提示：`Currently running in server mode. All configurations are provided by the server` [资料来源：[i18n/en.json:71-95]()]，并在加载失败时给出 `loadFailed` 提示 [资料来源：[i18n/en.json:71-95]()]。 ## 核心特性 ### 多供应商适配 系统使用「纯提示词 + 通用 JSON 解析」而非依赖结构化输出（Structured Outputs），以兼容更多 LLM 与搜索 API [资料来源：[README.md:1-15]()]。`shared/utils/json.ts` 中的 `parseStreamingJson` 在流式响应中累积 `text-delta`，通过 `parsePartialJson` 持续解析，并支持 `reasoning`（思维链）与 `error` 事件透传 [资料来源：[shared/utils/json.ts:1-50]()]。这一设计使搜索→LLM 的循环即便在 JSON 不完整的情况下也能优雅降级。 ### Key 轮询 针对 Tavily 单账号每月 1000 次调用额度紧张的痛点，社区提交了 PR #76 / #77 实现 Tavily 与 Google PSE 的多 Key 轮询：在 `NUXT_WEB_SEARCH_API_KEY` 中以逗号分隔多个 key，系统依次分配以提升并发并避免单 key 触顶 [资料来源：[README_zh.md:1-15]()]（详见 issue #75）。 ### 搜索语言与高级选项 Tavily 支持 `advancedSearch`（高质量搜索）与 `searchTopic`（搜索领域，例如 `general` / `news`） [资料来源：[README_zh.md:1-15]()]。Firecrawl 在 `v1.1.2` 起支持自定义 endpoint（自部署），并自 `v1.1.3` 起将抓取内容统一限制为 `Markdown`，避免 HTML 噪声干扰 [资料来源：[README_zh.md:1-15]()]。 ### 重试与失败处理 - `v1.1.3` 起支持「重试搜索失败的节点」 [资料来源：[README_zh.md:1-15]()] - 文案中预留 `nodeFailedToast` 与 `retry` 字段以提示用户 [资料来源：[i18n/zh.json:71-95]()] - 错误信息 `requestBlockedByCORS` 提示用户检查服务端跨域配置 [资料来源：[i18n/en.json:71-95]()] [资料来源：[i18n/zh.json:71-95]()] ## 已知问题与故障排查 | 现象 | 原因 | 缓解措施 | |------|------|----------| | Firecrawl 自部署触发 rate limit | issue #73 报告 `concurrencyLimit` 未对自部署 Firecrawl 生效 | 降低 `NUXT_PUBLIC_WEB_SEARCH_CONCURRENCY_LIMIT`，或联系维护者确认是否需要按端点分别限流 | | Tavily 月度配额不足 | 单账号 1000 次/月 | 使用 key 轮询功能配置多个 key（PR #77） | | CORS 报错 | `requestBlockedByCORS` 提示 | 更换允许跨域的供应商，或自部署反向代理 | | 模型无法返回结构化 JSON | `invalidStructuredOutput` | 换用更大或更聪明的模型 [资料来源：[i18n/zh.json:1-15]()] | `autoUpdate` 模块会在检测到新版本时弹出提示，建议自部署用户重新拉取镜像以获得修复 [资料来源：[i18n/en.json:71-95]()]。 ## See Also - [GitHub 仓库主页](https://github.com/AnotiaWang/deep-research-web-ui) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) — 完整中文部署与使用指南 - Issue [#75 Tavily Key 轮询](https://github.com/AnotiaWang/deep-research-web-ui/issues/75) - Issue [#73 Firecrawl rate limit](https://github.com/AnotiaWang/deep-research-web-ui/issues/73) --- ## 前端组件与搜索可视化 ### 相关页面 相关主题：[系统架构与数据流](#page-architecture), [配置、状态管理与历史记录](#page-data-history)
相关源码文件 以下源码文件用于生成本页说明： - [app/components/ResearchForm.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/ResearchForm.vue) - [app/components/ResearchFeedback.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/ResearchFeedback.vue) - [app/components/ResearchReport.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/ResearchReport.vue) - [app/components/DeepResearch/DeepResearch.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/DeepResearch/DeepResearch.vue) - [app/components/DeepResearch/SearchFlow.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/DeepResearch/SearchFlow.vue) - [app/components/DeepResearch/SearchNode.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/DeepResearch/SearchNode.vue) - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts) - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json)
# 前端组件与搜索可视化 ## 概述 Deep Research Web UI 是一个基于 Nuxt 构建的可视化前端，为 [dzhng/deep-research](https://github.com/dzhng/deep-research) 提供完整的浏览器端交互层。其核心特性之一是以树状结构实时可视化整个搜索研究过程，使用户能够观察 AI 如何自主分解问题、迭代查询并产出最终报告 资料来源：[README.md:1-15]()。 前端采用按步骤分阶段展示的交互模式：研究主题输入 → 模型反馈确认 → 联网搜索过程 → 最终报告输出。该流程在界面文案中分为四个阶段（"1. 研究主题"到"4. 研究报告"），用户能够完整跟踪从提问到成稿的每一步 资料来源：[i18n/zh.json:104-180]()。 --- ## 组件架构与职责划分 前端整体由若干职责单一的 Vue 组件构成，按功能维度分布在 `app/components/` 目录。核心组件层级如下： ```mermaid graph TD A[DeepResearch.vue
顶层容器] --> B[ResearchForm.vue
研究主题输入] A --> C[ResearchFeedback.vue
模型反馈] A --> D[SearchFlow.vue
搜索流程可视化] A --> E[ResearchReport.vue
最终报告] D --> F[SearchNode.vue
单个搜索节点] F --> G[子节点递归渲染] style A fill:#e1f5ff,stroke:#0277bd style D fill:#fff3e0,stroke:#ef6c00 style F fill:#f3e5f5,stroke:#6a1b9a ``` 各组件的主要职责如下表所述： | 组件文件 | 主要职责 | 关键交互 | |----------|----------|----------| | `DeepResearch.vue` | 顶层容器，组织四阶段流程的渲染与状态切换 | 维护全局进度状态 | | `ResearchForm.vue` | 接收用户研究主题、深度、广度、问题数量等参数 | 表单提交触发研究 | | `ResearchFeedback.vue` | 展示 AI 提出的细化问题，让用户确认研究目标 | 提交答案后进入搜索阶段 | | `SearchFlow.vue` | 以树状结构可视化搜索节点、迭代过程 | 支持全屏查看（v1.1.4 起） | | `SearchNode.vue` | 渲染单个搜索节点，包含目标、URL、结论、重试按钮 | 失败节点可点击重试 | | `ResearchReport.vue` | 渲染最终报告，支持打印为 PDF 与导出 Markdown | 包含引用信息（v1.1.7 起） | 资料来源：[app/components/ResearchForm.vue]()、[app/components/ResearchFeedback.vue]()、[app/components/DeepResearch/DeepResearch.vue]()、[app/components/DeepResearch/SearchFlow.vue]()、[app/components/DeepResearch/SearchNode.vue]()、[app/components/ResearchReport.vue]()。 --- ## 搜索可视化的实现机制 搜索阶段是整个 UI 中最具特色的部分。系统在 `SearchFlow.vue` 中将研究过程建模为一棵由 `SearchNode.vue` 组成的树，根节点代表初始查询，子节点代表在每一轮迭代中新生成的查询 资料来源：[app/components/DeepResearch/SearchFlow.vue]()。 每个搜索节点承载以下信息： - **Research Goal（研究目标）**：该轮搜索要解决的问题 - **Visited URLs（访问网址）**：被抓取并阅读的网页链接 - **Learnings（结论）**：从网页内容中提炼出的发现 - **Follow-up Questions（后续问题）**：衍生出的下一轮查询 用户在界面文案中可见以下文案："AI 将根据上述信息联网搜索并自动迭代，直到迭代次数 = depth"，节点详情中可"点击下面的节点查看搜索详情" 资料来源：[i18n/zh.json:154-178]()。 ### 流式 JSON 解析 由于搜索节点需要边生成边展示，前端依赖一个流式 JSON 解析工具 `parseStreamingJson`，它在 `text-delta` 事件中累积增量文本，并通过 `parsePartialJson` 持续修复与解析，从而在模型输出尚未完整时就提前渲染部分结构化数据 资料来源：[shared/utils/json.ts:1-50]()。该机制是"实时反馈"特性能够落地的关键支撑。 ### 节点失败与重试 如果某个搜索节点在执行过程中抛出错误（例如网络异常或 API 限流），其父级 `SearchFlow` 会把该节点标记为失败状态，并显示"重试"按钮。该功能在 v1.1.3 中作为新增能力加入，专门解决"网络错误后无法继续"的常见问题 资料来源：[Release v1.1.3](https://github.com/AnotiaWang/deep-research-web-ui/releases/tag/v1.1.3)、[issue #71](https://github.com/AnotiaWang/deep-research-web-ui/issues/71)。 ### 核心逻辑入口 `lib/core/index.ts` 仅作为统一出口，分别转发 `deep-research`（实际搜索流程）和 `feedback`（模型反馈）两个模块。这种扁平化的模块组织方式让前端组件能够以稳定的 API 边界调用核心能力，而无需关心底层实现的细节 资料来源：[lib/core/index.ts:1-4]()。 --- ## 用户体验增强与社区反馈 多个版本迭代聚焦于搜索可视化的体验打磨： - **v1.1.3**：修复搜索节点偶尔显示空标签和重复结论的问题，并新增节点重试 资料来源：[Release v1.1.3]()。 - **v1.1.4**：搜索流程图支持放大到全屏，便于用户在大屏幕上追踪完整搜索流程 资料来源：[Release v1.1.4](https://github.com/AnotiaWang/deep-research-web-ui/releases/tag/v1.1.4)。 - **v1.1.7**：研究报告新增引用信息（Citations），搜索节点详情修复文字溢出问题 资料来源：[Release v1.1.7](https://github.com/AnotiaWang/deep-research-web-ui/releases/tag/v1.1.7)。 社区反馈主要集中在以下几个方面： 1. **重试功能偶发无效**（[issue #71](https://github.com/AnotiaWang/deep-research-web-ui/issues/71)）：有用户报告在 `network error` 后点击重试按钮无效，目前尚未在公开 release 中完整修复。 2. **最终报告过于单薄**（[issue #69](https://github.com/AnotiaWang/deep-research-web-ui/issues/69)）：与丰富的搜索过程相比，最终报告内容显得不足，社区期望在 `ResearchReport.vue` 中加入更多总结轮次。 3. **Firecrawl 自部署速率限制不生效**（[issue #73](https://github.com/AnotiaWang/deep-research-web-ui/issues/73)）：当使用自部署 Firecrawl 时，并发数设置未生效，导致触发服务方限流。 这些反馈均指向搜索可视化链路上的具体组件（`SearchNode`、`SearchFlow`、`ResearchReport`），未来修复也将集中于这一层。 --- ## 部署与构建 组件层与 Nuxt 构建系统紧密集成。`edgeone.json` 中声明构建命令为 `pnpm generate:optimize`，输出目录为 `.output/public`，该配置用于在 EdgeOne Pages 上进行一键静态部署 资料来源：[edgeone.json:1-18]()。对于希望在客户端模式下保留本地配置体验的用户，也支持使用 Docker 镜像 `anotia/deep-research-web:latest` 部署 资料来源：[README_zh.md]()。 --- ## 参见 - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) — 项目总体介绍 - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) — 中文 README 与环境变量配置 - [Releases](https://github.com/AnotiaWang/deep-research-web-ui/releases) — 版本更新历史 - [issue #71](https://github.com/AnotiaWang/deep-research-web-ui/issues/71) — 搜索节点重试无效 - [issue #69](https://github.com/AnotiaWang/deep-research-web-ui/issues/69) — 最终报告内容单薄 - [issue #73](https://github.com/AnotiaWang/deep-research-web-ui/issues/73) — Firecrawl 自部署速率限制 --- ## 部署模式与运维配置 ### 相关页面 相关主题：[项目概览与特性](#page-overview), [系统架构与数据流](#page-architecture), [已知问题与故障排查](#page-troubleshooting)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json) - [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts)
# 部署模式与运维配置 ## 概述 `deep-research-web-ui` 是一个基于 Nuxt 框架的 Web UI 项目，提供两种运行模式：**客户端模式（Client Mode）** 与 **服务端模式（Server Mode）**。自 v1.2.0 版本起，项目正式引入服务端模式，管理员可以通过环境变量在服务端预先配置 AI 与联网搜索服务，最终用户无需再手动填写 API Key。资料来源：[README.md:1-30]()、[README_zh.md:1-30]()。 两种模式下的核心差异在于配置注入位置与 API Key 暴露面： - **客户端模式**：配置保存在浏览器本地（localStorage），所有 API 请求直接从浏览器发出，API Key 不会经过服务端。 - **服务端模式**：配置通过环境变量注入，最终用户在 UI 上看不到也不能修改 API Key。 ```mermaid flowchart LR A[用户浏览器] -->|Client Mode| B[(浏览器 localStorage)] A -->|Server Mode| C[Nuxt 服务端] C -->|读取环境变量| D[(NUXT_PUBLIC_* / NUXT_*)] B --> E[AI Provider API] C --> E C --> F[Web Search Provider API] B --> F ``` ## 客户端模式（Client Mode） 客户端模式是项目的传统部署方式。用户在首次访问时通过设置面板填写 API Key、Base URL、模型名称、上下文长度等参数，所有数据均保存在浏览器本地，不会被上传到任何服务端。资料来源：[README.md:7-10]()。 部署方式包括： - **EdgeOne Pages 一键部署**：[edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json) 中声明了构建命令 `pnpm generate:optimize`、输出目录 `.output/public` 与 Node 版本 `20.18.0`，并对 `version.json` 配置 `Cache-Control: public, max-age=0` 以便版本自动更新提示能够及时生效。 - **Docker 部署**：可直接拉取现成镜像 `anotia/deep-research-web:latest`，或克隆源码后使用项目根目录的 `Dockerfile` 自定义构建。资料来源：[README_zh.md:73-85]()。 客户端模式下，`shared/types/config.ts` 暴露的 `PublicRuntimeConfig` 中 `serverMode` 字段为 `false`，设置面板中的 “AI 服务”、“联网搜索服务” 等选项全部对用户可见。资料来源：[shared/types/config.ts:19-30]()。 ## 服务端模式（Server Mode） 服务端模式由 `NUXT_PUBLIC_SERVER_MODE=true` 启用。开启后，配置统一由服务端通过环境变量下发，前端通过 `/api/config` 之类的接口读取 `PublicRuntimeConfig`（不包含敏感字段），而 AI 与搜索的 API Key 仅在服务端侧用于发起请求。资料来源：[shared/types/config.ts:1-30]()。 ### 环境变量配置 下表汇总了服务端模式的核心环境变量，值与默认值来源于 README 与 `shared/types/config.ts` 中的类型定义： | 变量名 | 作用 | 默认值 / 示例 | |--------|------|---------------| | `NUXT_PUBLIC_SERVER_MODE` | 启用服务端模式 | `false` | | `NUXT_PUBLIC_AI_PROVIDER` | AI 服务商 | `openai-compatible` | | `NUXT_AI_API_KEY` | AI API Key | - | | `NUXT_PUBLIC_AI_MODEL` | 模型名称 | - | | `NUXT_PUBLIC_AI_CONTEXT_SIZE` | 上下文长度 | - | | `NUXT_PUBLIC_WEB_SEARCH_PROVIDER` | 搜索服务商 | `tavily` | | `NUXT_WEB_SEARCH_API_KEY` | 搜索服务 API Key（支持多 Key 轮询，用逗号分隔） | `key1,key2,key3` | | `NUXT_PUBLIC_WEB_SEARCH_CONCURRENCY_LIMIT` | 最大并发数 | `2` | | `NUXT_PUBLIC_WEB_SEARCH_SEARCH_LANGUAGE` | 搜索语言 | `en` | | `NUXT_PUBLIC_TAVILY_ADVANCED_SEARCH` | Tavily 高级搜索 | `false` | | `NUXT_PUBLIC_TAVILY_SEARCH_TOPIC` | Tavily 搜索主题 | `general` | | `NUXT_PUBLIC_GOOGLE_PSE_ID` | Google PSE 引擎 ID（cx） | - | | `NUXT_WEB_SEARCH_API_BASE` | 自定义搜索服务 Base URL（用于 Firecrawl 自部署） | - | 资料来源：[README_zh.md:92-115]()、[shared/types/config.ts:1-30]()。 ### Provider 枚举值 `ConfigAiProvider` 与 `ConfigWebSearchProvider` 是联合类型，定义了受支持的供应商取值。资料来源：[shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts)。 - **AI 服务商**：`openai-compatible`、`siliconflow`、`302-ai`、`infiniai`、`openrouter`、`deepseek`、`ollama`。资料来源：[i18n/zh.json:18-40]()` 中的 `settings.ai.providers` 节点也列出了部分供应商文案。 - **联网搜索服务商**：`tavily`、`firecrawl`、`crw`（fastCRW，兼容 Firecrawl 协议）、`google-pse`。资料来源：[README_zh.md:117-124]()。 ### 社区反馈驱动的演进 - [#8](https://github.com/AnotiaWang/deep-research-web-ui/issues/8) 建议将所有配置项改为环境变量部署，以便在 Docker 下换浏览器或分享给他人时无需重复填 Key，最终在 v1.2.0 中以 “服务端模式” 实现。 - [#75](https://github.com/AnotiaWang/deep-research-web-ui/issues/75) 提出 Tavily 单 Key 每月 1000 次不够用，PR #76/#77 引入了 Tavily 与 Google PSE 的多 Key 轮询支持——服务端模式下可通过 `NUXT_WEB_SEARCH_API_KEY=key1,key2,key3` 形式传入。资料来源：[README_zh.md:112-114]()。 - #70 报告 Azure OpenAI 由于拼接 Base URL 时缺少 `api-version` 概念而失败，社区仍在跟进。 - #73 报告自部署 Firecrawl 的并发限制未生效，可通过调整 `NUXT_PUBLIC_WEB_SEARCH_CONCURRENCY_LIMIT` 并升级到最新版本验证。 ## 构建命令与本地开发 项目使用 `pnpm` 作为包管理器，常见命令如下（参见 [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md)）： ```bash # 本地开发，访问 http://localhost:3000 pnpm dev # 生产构建（SSR） pnpm build # 静态生成（用于 EdgeOne Pages / 静态部署） pnpm generate # 预览生产构建 pnpm preview ``` `lib/core/index.ts` 重新导出了 `deep-research` 与 `feedback` 核心模块。资料来源：[lib/core/index.ts:1-4]()。 ## 国际化与版本提示 UI 通过 `i18n/` 下的语言文件实现多语言切换： - `i18n/zh.json`：简体中文 - `i18n/en.json`：英语 - `i18n/nl.json`：荷兰语（自 v1.1.3 起支持） 当检测到新版本时，前端会通过 `autoUpdate.newVersionTitle` / `autoUpdate.refresh` 提示用户刷新页面；自部署用户需重新拉取镜像或重新部署。资料来源：[i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json)、[i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json)。 ## See Also - [AI Provider 与 Web Search Provider 接入指南](#) （建议补充） - [搜索流程树状可视化](#) （建议补充） - [历史记录与导入导出](#) （建议补充） --- ## 配置、状态管理与历史记录 ### 相关页面 相关主题：[部署模式与运维配置](#page-deployment), [前端组件与搜索可视化](#page-frontend)
相关源码文件 以下源码文件用于生成本页说明： - [app/stores/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/stores/config.ts) - [app/composables/useHistory.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/composables/useHistory.ts) - [app/components/History/HistoryModal.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/History/HistoryModal.vue) - [app/types/history.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/types/history.ts) - [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md)
# 配置、状态管理与历史记录 ## 配置系统概览 Deep Research Web UI 提供两套并行的配置通路：客户端模式（Client Mode）下配置完全保存在浏览器本地（localStorage），所有 API 请求也从浏览器直发；服务端模式（Server Mode）下则由部署方通过环境变量注入，终端用户无需也无法修改任何密钥。两种模式共享同一份类型定义，便于维护与扩展。 在 [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) 中定义了 `ServerRuntimeConfig` 与 `PublicRuntimeConfig` 两套接口： - `ServerRuntimeConfig` 仅在服务端可见，包含 `aiApiKey`、`aiApiBase`、`webSearchApiKey` 等敏感字段； - `PublicRuntimeConfig` 暴露给浏览器，只包含供应商、模型、并发数等非敏感项，以便前端在不泄露密钥的前提下渲染配置界面。 字段示例（含 `tavilyAdvancedSearch`、`tavilySearchTopic`、`googlePseId` 等）直接来源于 [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts:1) 的类型定义，体现了对多供应商、多参数配置的统一抽象。 ### 关键环境变量 服务端模式通过 Nuxt 的 `runtimeConfig` 注入，下表汇总了 README_zh.md 中列出的核心变量： | 变量名 | 含义 | 默认值 | |---|---|---| | `NUXT_PUBLIC_SERVER_MODE` | 是否启用服务端模式 | `false` | | `NUXT_PUBLIC_AI_PROVIDER` | AI 供应商标识 | `openai-compatible` | | `NUXT_AI_API_KEY` | AI 服务的 API 密钥 | - | | `NUXT_PUBLIC_AI_MODEL` | 默认模型名 | - | | `NUXT_PUBLIC_AI_CONTEXT_SIZE` | 上下文长度 | - | | `NUXT_PUBLIC_WEB_SEARCH_PROVIDER` | 搜索服务商 | `tavily` | | `NUXT_PUBLIC_WEB_SEARCH_CONCURRENCY_LIMIT` | 最大并发数 | `2` | | `NUXT_WEB_SEARCH_API_KEY` | 搜索 API 密钥（支持逗号分隔多 Key） | - | | `NUXT_PUBLIC_GOOGLE_PSE_ID` | Google PSE 的 cx 值 | - | 资料来源：[README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) 中的“服务端模式”章节。其中特别说明：`NUXT_WEB_SEARCH_API_KEY` 支持以逗号分隔的多个密钥轮询，这是社区 #75 议题（Tavily Key 轮询）落地后的实现，相关 PR 已被合并。 ## 客户端状态管理 前端使用 Pinia 风格的 store 进行状态管理，主入口为 `app/stores/config.ts`。在客户端模式下，store 会在应用启动时从 `localStorage` 读取历史配置并回填表单，UI 提示文案“所有设置本地保存”也来自 [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) 的 `settings.disclaimer` 字段。 切换至服务端模式时，store 会优先请求 `/api/config`（或等价的运行时配置接口）获取 `PublicRuntimeConfig`，并将表单设为只读，顶部显示来自 `settings.configNotice` 的提示：“当前配置由服务器管理员设置，如需修改请联系管理员。”这种“单一可信来源 + 只读回显”的策略保证运维体验与终端用户隐私的平衡。 并发限制、AI 上下文长度等运行期参数都通过 store 注入到 `lib/core` 的搜索循环中；其中 `NUXT_PUBLIC_AI_CONTEXT_SIZE` 解决了 v1.1.5 中“上下文大小设置未生效”的回归问题。 ## 历史记录 历史记录是 v1.2.0 周期内最受欢迎的社区功能之一，源自议题 #57 “保留历史记录”。其核心职责是把一次完整的研究会话持久化到浏览器，便于用户回看、分享或重新发起。 ### 记录结构 单条历史记录（`app/types/history.ts`）至少包含： - `id`：会话唯一标识； - `topic`：研究主题； - `createdAt`：创建时间； - `feedbackQuestions` / `feedbackAnswers`：模型反馈回合的问答对； - `searchTree`：搜索节点树，节点字段（`researchGoal`、`visitedUrls`、`learnings` 等）来自 [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) 的 `webBrowsing` 命名空间； - `report`：最终生成的 Markdown 报告； - 元信息：`depth`、`breadth`、`numOfQuestions` 等可在列表中展示的轻量摘要。 ### 导入 / 导出 历史记录面板（[app/components/History/HistoryModal.vue](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/app/components/History/HistoryModal.vue)）通过 `app/composables/useHistory.ts` 暴露的 `exportHistory` / `importHistory` 完成 JSON 序列化与反序列化： ```ts // 伪代码，源自 useHistory.ts 的实现思路 const exportHistory = () => download(JSON.stringify(records, null, 2)) const importHistory = (file) => readJson(file).then(mergeIntoStore) ``` 导入成功后弹出 `history.importSuccess` 提示，失败时显示 `history.importFailed`，相关文案可在 [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) 与 [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) 的 `history` 命名空间下找到。`deleteAll` 与 `confirmDeleteAll` 则通过二次确认弹窗防止误删。 ## 社区反馈与已知问题 - **环境变量部署**（issue #8）：在 v1.2.0 之前，Docker 用户每次清浏览器缓存都需重新填写密钥；服务端模式落地后，通过环境变量集中托管成为推荐方案。 - **Firecrawl 速率限制不生效**（issue #73）：自部署 Firecrawl 时，`NUXT_PUBLIC_WEB_SEARCH_CONCURRENCY_LIMIT` 在某些版本下未传递到抓取层，需确认 `app/composables/useHistory.ts` 同级的 `useWebSearch` 实现是否读取了该字段。 - **Azure OpenAI base URL 拼接错误**（issue #70）：配置 Azure 时缺少 `api-version` 概念，属于配置 schema 的边界情况，修改时需同时考虑 [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) 的扩展点。 - **历史记录分享**：多位用户在 #57 中表示希望“分享给同事”，当前通过 JSON 导出/导入的方式间接实现，未来若开放 API（issue #79）则可借助 Markdown 字符串直接返回报告。 ## 参见 - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - Issue #57（保留历史记录） - Issue #75（Tavily Key 轮询） - Release v1.2.0（服务端模式） --- ## 已知问题与故障排查 ### 相关页面 相关主题：[联网搜索后端集成](#page-web-search), [AI 服务商集成](#page-ai-providers), [部署模式与运维配置](#page-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [i18n/en.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json) - [i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) - [shared/types/config.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) - [shared/utils/json.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) - [edgeone.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json) - [lib/core/index.ts](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/lib/core/index.ts)
# 已知问题与故障排查 本文汇总 `deep-research-web-ui` 项目中常见的故障表现、根因与排查思路，覆盖部署配置、运行时错误、功能限制三大类。所有结论均来源于仓库源码与社区 Issue 记录。 ## 概述 `deep-research-web-ui` 是 [dzhng/deep-research](https://github.com/dzhng/deep-research) 的可视化前端，支持客户端模式与服务端模式（Server Mode）两种运行方式 ([README.md](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md))。由于其依赖 LLM 响应、联网搜索与可选的 Firecrawl 抓取等多服务协作，链路较长，故障表现也呈多样化。下图梳理了用户从部署到完成研究报告的典型调用路径，以及常见故障的注入点。 ```mermaid flowchart LR A[用户配置/环境变量] --> B[AI Provider] A --> C[Web Search Provider] C --> D[Firecrawl / Tavily / Google PSE] B --> E[流式 JSON 解析] D --> E E --> F[研究报告生成] F --> G[导出 PDF / Markdown] G -.失败/异常.-> H[错误诊断] B -.失败.-> H C -.失败.-> H D -.失败.-> H ``` ## 部署与配置类问题 ### 静态资源缺失（`assets/js/` 找不到） 社区反馈在自行构建 PWA manifest 与 `sw.js` 时会出现 `assets/js/ couldn't find` 错误，原因是 Nuxt 静态资源带有哈希指纹，与手写的 `sw.js` 引用不一致 ([Issue #43](https://github.com/AnotiaWang/deep-research-web-ui/issues/43))。建议在尝试二次改造 Service Worker 之前，先确认 EdgeOne Pages 构建产物（`outputDirectory` 已固定为 `.output/public`，[edgeone.json:5](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/edgeone.json#L5)）中实际产出的资源路径。 ### 服务端模式与多浏览器复用配置 多浏览器/分享给同事时，每个客户端都需重填密钥较为繁琐 ([Issue #8](https://github.com/AnotiaWang/deep-research-web-ui/issues/8))。自 v1.2.0 起，可通过环境变量启用服务端模式 `NUXT_PUBLIC_SERVER_MODE=true`，由服务端统一下发配置；公开运行时配置见 `PublicRuntimeConfig` 接口，私密配置见 `ServerRuntimeConfig` ([shared/types/config.ts:1-40](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts#L1-L40))。 ### Azure OpenAI 资源不存在 配置 Azure OpenAI 时报“资源不存在” ([Issue #70](https://github.com/AnotiaWang/deep-research-web-ui/issues/70))。根本原因是拼接 `base url` 的方式与官方 `api-version` 参数语义不一致。建议改用 `openai-compatible` 模式并手动指定 `apiBase` 与模型名，避免依赖 Azure 自动拼接逻辑。 ## 运行时故障 ### Firecrawl 自部署速率限制不生效 即便在 UI 中设置了速率限制，自托管 Firecrawl 仍可能报 `rate limit` ([Issue #73](https://github.com/AnotiaWang/deep-research-web-ui/issues/73))。其原因是当前应用层的并发限制仅作用于客户端调度队列，而不会回写到 Firecrawl 服务端。可通过降低 UI 中的“并发数”设置（默认 2）来规避，也可为自部署 Firecrawl 配置反向代理层面的限流。 ### 联网搜索重试无反应 `network error` 后点击重试无效果 ([Issue #71](https://github.com/AnotiaWang/deep-research-web-ui/issues/71))，属偶发问题。可检查浏览器控制台是否仍残留旧 SSE 连接未关闭；若使用 `qwen2.5-32b-instruct` 等长上下文模型，注意先在设置中调整 `contextSize`（参考 `i18n/zh.json` 的 `contextSize` 字段）以避免流式响应被截断。 ### 模型返回无效 JSON `parseStreamingJson` 在流末尾若解析失败会输出 `bad-end` 事件 ([shared/utils/json.ts:42-52](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts#L42-L52))，对应 i18n 提示 `invalidStructuredOutput`（“模型返回的内容无效或不完整，无法解析”，[i18n/en.json:8](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/en.json#L8)）。建议切换到更强的模型或在设置中调高 `contextSize`。 ### CORS 跨域报错 浏览器直连某些 AI 服务时被拦截，提示 `requestBlockedByCORS`（[i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json)）。客户端模式下无服务器中转，只能更换支持跨域的供应商，或部署反向代理。 ## 功能限制与已知缺口 | Issue | 现象 | 当前状态 | 临时方案 | |-------|------|----------|----------| | [#79](https://github.com/AnotiaWang/deep-research-web-ui/issues/79) | 缺少直接 API 调用入口 | open | 暂未支持，可在 `lib/core/index.ts` 导出 `deep-research` 后自行包装 | | [#75](https://github.com/AnotiaWang/deep-research-web-ui/issues/75) | Tavily/Google PSE 多 Key 轮询 | closed | 需手动应用 PR [#77](https://github.com/AnotiaWang/deep-research-web-ui/pull/77) | | [#69](https://github.com/AnotiaWang/deep-research-web-ui/issues/69) | 最终报告内容单薄 | open | 在设置中调大 `breadth` / `depth` 让研究阶段收集更多素材 | | [#57](https://github.com/AnotiaWang/deep-research-web-ui/issues/57) | 历史记录 | closed | v1.1.x 已实现，可通过 UI 导出/导入（[i18n/zh.json](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/i18n/zh.json) `history` 段） | ## 错误诊断流程建议 1. 复现并捕获浏览器控制台 / Docker 容器日志，确认异常发生在 AI、搜索还是抓取阶段。 2. 若为模型输出异常，关注 `parseStreamingJson` 的 `bad-end`/`error` 事件（[shared/utils/json.ts:22-50](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts#L22-L50)），并比对 i18n 错误键。 3. 若为搜索链路异常，先收敛 Firecrawl 并发与 Tavily 主题配置，再核对 `ServerRuntimeConfig` 中 `tavilyAdvancedSearch` 等布尔项是否正确下发。 4. 服务端模式下，所有用户共享同一份配置，修改后需重启镜像以应用 `NUXT_PUBLIC_*` 环境变量。 ## See Also - [README.md（英文项目说明）](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README.md) - [README_zh.md（中文部署与环境变量）](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/README_zh.md) - [服务端模式与配置接口](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/types/config.ts) - [流式 JSON 解析工具](https://github.com/AnotiaWang/deep-research-web-ui/blob/main/shared/utils/json.ts) --- --- ## Doramagic 踩坑日志 项目：AnotiaWang/deep-research-web-ui 摘要：发现 14 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：【建议】是否可以将相关变量作为环境变量进行设置。 ## 1. 安全/权限坑 · 来源证据：【建议】是否可以将相关变量作为环境变量进行设置 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：【建议】是否可以将相关变量作为环境变量进行设置 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/8 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 依赖 Docker 环境 - 严重度：medium - 证据强度：runtime_trace - 发现：安装/运行入口包含 Docker 命令：docker run -p 3000:3000 -e NUXT_PUBLIC_SERVER_MODE=true -e NUXT_AI_API_KEY=your-ai-api-key -e NUXT_WEB_SEARCH_API_KEY=your-search-api-key -e NUXT_PUBLIC_AI_PROVIDER=openai-compatible -e NUXT_PUBLIC_AI_MODEL=gpt-4o-mini -e NUXT_PUBLIC_WEB_SEARCH_PROVIDER=tavily anotia/deep-research-web:latest - 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。 - 复现命令：`docker run -p 3000:3000 -e NUXT_PUBLIC_SERVER_MODE=true -e NUXT_AI_API_KEY=your-ai-api-key -e NUXT_WEB_SEARCH_API_KEY=your-search-api-key -e NUXT_PUBLIC_AI_PROVIDER=openai-compatible -e NUXT_PUBLIC_AI_MODEL=gpt-4o-mini -e NUXT_PUBLIC_WEB_SEARCH_PROVIDER=tavily anotia/deep-research-web:latest` - 证据：identity.distribution | https://github.com/AnotiaWang/deep-research-web-ui | docker run -p 3000:3000 -e NUXT_PUBLIC_SERVER_MODE=true -e NUXT_AI_API_KEY=your-ai-api-key -e NUXT_WEB_SEARCH_API_KEY=your-search-api-key -e NUXT_PUBLIC_AI_PROVIDER=openai-compatible -e NUXT_PUBLIC_AI_MODEL=gpt-4o-mini -e NUXT_PUBLIC_WEB_SEARCH_PROVIDER=tavily anotia/deep-research-web:latest ## 3. 安装坑 · 来源证据：[Feature] PWA functionality - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] PWA functionality - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/43 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/AnotiaWang/deep-research-web-ui | host_targets=chatgpt, claude ## 5. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/AnotiaWang/deep-research-web-ui | README/documentation is current enough for a first validation pass. ## 6. 运行坑 · 来源证据：[Bug] 点击重试并不会重试 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] 点击重试并不会重试 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/71 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 运行坑 · 来源证据：[Bug] 配置azure openai提示资源不存在 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] 配置azure openai提示资源不存在 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/70 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/AnotiaWang/deep-research-web-ui | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/AnotiaWang/deep-research-web-ui | no_demo; severity=medium ## 10. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/AnotiaWang/deep-research-web-ui | no_demo; severity=medium ## 11. 安全/权限坑 · 来源证据：[Bug] firecrawl rate limit is not wokring - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] firecrawl rate limit is not wokring - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/73 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 12. 安全/权限坑 · 来源证据：[Feature] 支持api调用吗 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] 支持api调用吗 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/79 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 13. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/AnotiaWang/deep-research-web-ui | issue_or_pr_quality=unknown ## 14. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/AnotiaWang/deep-research-web-ui | release_recency=unknown