一、项目定位与目标

Deep Research Web UI 是 dzhng/deep-research 的可视化前端实现，对原项目在交互、可用性与部署方面进行了多项改进 资料来源：README.md:1-3。项目提供浏览器端的研究流程编排能力：用户输入研究主题后，AI 会先询问澄清问题，然后自动进行多轮网络搜索，最终输出结构化的研究报告 资料来源：i18n/zh.json:1-180。

整个应用基于 Nuxt 3 框架构建，并通过 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 与学习要点，生成可导出的报告。

flowchart LR
    A[1. 研究主题] --> B[2. 模型反馈]
    B --> C[3. 联网搜索<br/>depth 轮迭代]
    C --> D[4. 研究报告<br/>导出 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。

3.3 多供应商兼容

底层使用纯提示词而非 OpenAI 较新的 Structured Outputs 特性，因此可以兼容更多尚不支持新接口的供应商 资料来源：README.md:12-13`。

资料来源：README.md:18-21 与 README_zh.md:10-12`。

3.4 报告导出与历史

• 报告可导出为 Markdown 或通过浏览器原生打印能力导出为 PDF（v1.1.5 起） 资料来源：社区 Release v1.1.5。
• 报告内置来源引用（citation），与研究阶段收集的 URL 一一对应 资料来源：社区 Release v1.1.7。
• 提供本地历史记录功能，支持导出 / 导入，方便跨设备复用 资料来源：i18n/zh.json:35-55、社区 Issue #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。

整体架构概览

Deep Research Web UI 是 dzhng/deep-research 的可视化前端实现，基于 Nuxt 3 构建。其设计目标是在浏览器侧完成所有 AI 与联网搜索调用，避免后端代理密钥，从而在「客户端模式」下实现隐私安全 (README.md:1-15)。同时，自 v1.2.0 起新增「服务端模式」，允许通过环境变量统一配置 API 密钥，用户无需在浏览器侧填写 (README.md:13-15)。

项目结构由三层组成：

• UI 层：Nuxt 应用页面，包含研究主题输入、模型反馈、联网搜索流程可视化与研究报告输出四个步骤。
• 核心逻辑层 (lib/core)：封装深度研究与反馈生成的算法，由 lib/core/index.ts 统一导出 (lib/core/index.ts:1-4)。
• 共享工具层 (shared)：跨页面复用的工具函数，例如流式 JSON 解析。

flowchart LR
    A[用户输入研究主题] --> B[模型反馈<br/>生成追问]
    B --> C[联网搜索<br/>树状结构]
    C --> D[深度迭代<br/>depth / breadth]
    D --> E[研究报告生成]
    E --> F[导出 Markdown / PDF]

    subgraph 客户端浏览器
    A
    B
    C
    D
    E
    F
    end

    C -. API .-> G[Tavily / Firecrawl<br/>fastCRW / Google PSE]
    B -. API .-> H[OpenAI Compatible<br/>SiliconFlow / InfiniAI<br/>DeepSeek / 302.AI / Ollama]
    E -. API .-> H

核心模块组成

lib/core/index.ts 充当核心逻辑的总入口，对外仅暴露两个模块：deep-research 与 feedback (lib/core/index.ts:1-4)。这种最小化导出策略有助于保持核心库的可移植性，便于未来在 Node CLI、测试或服务端 API 中复用同一份逻辑。

shared/utils/json.ts 提供 parseStreamingJson 生成器，接收来自 AI SDK 的流式片段 (AsyncIterable<TextStreamPart<any>>)，通过累积文本并反复调用 parsePartialJson 实现「边生成边解析」的能力 (shared/utils/json.ts:1-43)。当流结束时若仍无法成功解析，会通过 bad-end 事件通知调用方 (shared/utils/json.ts:40-43)，对应 UI 中常见的「invalidStructuredOutput 模型返回的内容无效或不完整」错误提示 (i18n/zh.json)。

研究流程数据流

研究流程由四个阶段串成 (i18n/zh.json)：

1. 研究主题 (researchTopic)：用户输入主题，配置问题数量 (numOfQuestions)、研究深度 (depth) 与广度 (breadth)，其中广度在每轮迭代中折半 (i18n/zh.json)。
2. 模型反馈 (modelFeedback)：AI 主动生成追问以澄清研究目标；用户提交回答后流入下一阶段。
3. 联网搜索 (webBrowsing)：根据研究目标调用联网搜索服务，按树状结构生成节点；用户可点击节点查看「研究目标 / 访问网址 / 结论」三项详情 (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)。

部署模式与配置

项目支持两种部署模式，可通过 NUXT_PUBLIC_SERVER_MODE 环境变量切换 (README_zh.md)：

服务端模式下，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)。

国际化与前端结构

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)。新增荷兰语翻译 (NL) 于 v1.1.3 发布。前端的 serverMode 命名空间用于在服务端模式下提示用户「当前配置由服务器管理员设置」，加载失败时给出 loadFailed 提示 (i18n/en.json)。

常见失败模式与社区反馈

• CORS 跨域被拦截：当 API 提供商未配置允许跨域时，浏览器会阻断请求；前端通过 error.requestBlockedByCORS 文案引导用户更换供应商 (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 — 项目概览与供应商列表
• lib/core/index.ts — 核心逻辑入口
• shared/utils/json.ts — 流式 JSON 解析实现
• edgeone.json — EdgeOne Pages 部署配置

概述

AI 服务商集成是 Deep Research Web UI 的核心能力之一，它把不同厂商的大模型 API 统一封装到前端可调用的接口中，使用户能够通过浏览器或服务端配置接入多种 AI 推理服务。本项目使用纯提示词（prompts）而非结构化输出（Structured Outputs）等较新特性，从而保证与尚未跟进 OpenAI 最新能力的更多厂商兼容 资料来源：README.md。

核心入口由 lib/core/index.ts 统一对外暴露，文件中再导出 deep-research 与 feedback 等模块：

// Re-export all core functionality
export * from './deep-research'
export * from './feedback'

资料来源：lib/core/index.ts:1-3。

支持的服务商

当前 Deep Research Web UI 已通过统一的"OpenAI 兼容协议"适配多家人工智能服务商。项目在 README 中列出了下述受支持的供应商：

资料来源：README.md、README_zh.md、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。该模式适合静态部署（如 pnpm generate 输出或 EdgeOne Pages）：

{
  "name": "deep-research-web",
  "buildCommand": "pnpm generate:optimize",
  "outputDirectory": ".output/public",
  "nodeVersion": "20.18.0"
}

资料来源：edgeone.json。

服务端模式（Server Mode）

v1.2.0 引入了服务端模式：API key 以环境变量形式注入，部署后用户无需在 UI 中配置密钥 资料来源：README.md。典型 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

NUXT_WEB_SEARCH_API_KEY 支持为 Tavily、Google PSE 等传入逗号分隔的多个密钥以实现轮询（key rotation），参考社区 PR #76 / #77 资料来源：README_zh.md。i18n/en.json 中定义了 serverMode 字段（如 aiProvider、aiModel、webSearchProvider、searchLanguage），用于在界面上呈现"由服务器管理员设置"的相关提示。

AI 设置项

设置面板中的 AI 配置项在 i18n 资源中具有统一定义：

资料来源：i18n/zh.json、i18n/en.json。

v1.1.5 修复了"contextSize"未正确应用的 Bug；v1.1.8 改进了在没有填写 API key 时仍尝试拉取模型列表的能力 资料来源：README.md。

流式响应与结构化解析

AI 在执行"追问→搜索→总结"链路时，需要在前端实时解析模型流式输出。shared/utils/json.ts 提供了基于 parsePartialJson 与 zod schema 的流式解析能力，能够区分 reasoning、text-delta、error 等事件，并对残缺 JSON 做容错（repaired-parse / successful-parse）：

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。

这套机制同时支持推理模型（如 DeepSeek R1）和普通对话模型：当模型输出 reasoning 类型时，前端可单独展示"思考中"状态，i18n/zh.json 中通过 modelThinking 与 modelThinkingComplete 进行了本地化。如果最终未能解析成功，将抛出 bad-end 事件，UI 给出"无效或不完整"的提示，提示用户更换为更大或更"聪明"的模型 资料来源：i18n/zh.json。

常见问题

• CORS 拦截：当选择某些小众 AI 服务商时，浏览器端直接请求可能被 CORS 策略阻止，i18n 中专门给出了 requestBlockedByCORS 错误提示，建议用户更换服务或联系服务方 资料来源：i18n/en.json。
• Azure OpenAI 适配：社区反馈拼接 base URL 时未考虑 Azure 的 api-version 概念，会出现"资源不存在"错误，相关讨论见 issue #70 资料来源：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。

See Also

• README.md — 项目主文档
• README_zh.md — 中文文档（含环境变量清单）
• i18n/zh.json — 中文界面文案与 AI Provider 选项
• i18n/en.json — 英文界面文案，含 Server Mode 配置说明
• shared/utils/json.ts — 流式 JSON 解析器
• lib/core/index.ts — 核心模块入口
• edgeone.json — EdgeOne Pages 静态部署配置

概述

deep-research-web-ui 是 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]。

架构与配置

数据流概览

flowchart LR
    UI[用户界面<br/>研究主题表单] --> Core[lib/core<br/>deep-research]
    Core --> Search[searchProvider<br/>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 暴露以下选项：

并发数提示文案明确说明：限制同时进行的搜索数量可以避免被 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]

已知问题与故障排查

autoUpdate 模块会在检测到新版本时弹出提示，建议自部署用户重新拉取镜像以获得修复 资料来源：[i18n/en.json:71-95]。

See Also

• GitHub 仓库主页
• README_zh.md — 完整中文部署与使用指南
• Issue #75 Tavily Key 轮询
• Issue #73 Firecrawl rate limit

概述

Deep Research Web UI 是一个基于 Nuxt 构建的可视化前端，为 dzhng/deep-research 提供完整的浏览器端交互层。其核心特性之一是以树状结构实时可视化整个搜索研究过程，使用户能够观察 AI 如何自主分解问题、迭代查询并产出最终报告 资料来源：README.md:1-15。

前端采用按步骤分阶段展示的交互模式：研究主题输入 → 模型反馈确认 → 联网搜索过程 → 最终报告输出。该流程在界面文案中分为四个阶段（"1. 研究主题"到"4. 研究报告"），用户能够完整跟踪从提问到成稿的每一步 资料来源：i18n/zh.json:104-180。

概述

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。

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 中声明了构建命令 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 中的类型定义：

资料来源：README_zh.md:92-115、shared/types/config.ts:1-30。

Provider 枚举值

ConfigAiProvider 与 ConfigWebSearchProvider 是联合类型，定义了受支持的供应商取值。资料来源：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 建议将所有配置项改为环境变量部署，以便在 Docker 下换浏览器或分享给他人时无需重复填 Key，最终在 v1.2.0 中以 “服务端模式” 实现。
• #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）：

# 本地开发，访问 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、i18n/en.json。

See Also

• AI Provider 与 Web Search Provider 接入指南 （建议补充）
• 搜索流程树状可视化 （建议补充）
• 历史记录与导入导出 （建议补充）

配置系统概览

Deep Research Web UI 提供两套并行的配置通路：客户端模式（Client Mode）下配置完全保存在浏览器本地（localStorage），所有 API 请求也从浏览器直发；服务端模式（Server Mode）下则由部署方通过环境变量注入，终端用户无需也无法修改任何密钥。两种模式共享同一份类型定义，便于维护与扩展。

在 shared/types/config.ts 中定义了 ServerRuntimeConfig 与 PublicRuntimeConfig 两套接口：

• ServerRuntimeConfig 仅在服务端可见，包含 aiApiKey、aiApiBase、webSearchApiKey 等敏感字段；
• PublicRuntimeConfig 暴露给浏览器，只包含供应商、模型、并发数等非敏感项，以便前端在不泄露密钥的前提下渲染配置界面。

字段示例（含 tavilyAdvancedSearch、tavilySearchTopic、googlePseId 等）直接来源于 shared/types/config.ts 的类型定义，体现了对多供应商、多参数配置的统一抽象。

关键环境变量

服务端模式通过 Nuxt 的 runtimeConfig 注入，下表汇总了 README_zh.md 中列出的核心变量：

资料来源：README_zh.md 中的“服务端模式”章节。其中特别说明：NUXT_WEB_SEARCH_API_KEY 支持以逗号分隔的多个密钥轮询，这是社区 #75 议题（Tavily Key 轮询）落地后的实现，相关 PR 已被合并。

客户端状态管理

前端使用 Pinia 风格的 store 进行状态管理，主入口为 app/stores/config.ts。在客户端模式下，store 会在应用启动时从 localStorage 读取历史配置并回填表单，UI 提示文案“所有设置本地保存”也来自 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 的 webBrowsing 命名空间；
• report：最终生成的 Markdown 报告；
• 元信息：depth、breadth、numOfQuestions 等可在列表中展示的轻量摘要。

导入 / 导出

历史记录面板（app/components/History/HistoryModal.vue）通过 app/composables/useHistory.ts 暴露的 exportHistory / importHistory 完成 JSON 序列化与反序列化：

// 伪代码，源自 useHistory.ts 的实现思路
const exportHistory = () => download(JSON.stringify(records, null, 2))
const importHistory = (file) => readJson(file).then(mergeIntoStore)

导入成功后弹出 history.importSuccess 提示，失败时显示 history.importFailed，相关文案可在 i18n/zh.json 与 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 的扩展点。
• 历史记录分享：多位用户在 #57 中表示希望“分享给同事”，当前通过 JSON 导出/导入的方式间接实现，未来若开放 API（issue #79）则可借助 Markdown 字符串直接返回报告。

参见

• README_zh.md
• shared/types/config.ts
• i18n/zh.json
• Issue #57（保留历史记录）
• Issue #75（Tavily Key 轮询）
• Release v1.2.0（服务端模式）

概述

deep-research-web-ui 是 dzhng/deep-research 的可视化前端，支持客户端模式与服务端模式（Server Mode）两种运行方式 (README.md)。由于其依赖 LLM 响应、联网搜索与可选的 Firecrawl 抓取等多服务协作，链路较长，故障表现也呈多样化。下图梳理了用户从部署到完成研究报告的典型调用路径，以及常见故障的注入点。

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)。建议在尝试二次改造 Service Worker 之前，先确认 EdgeOne Pages 构建产物（outputDirectory 已固定为 .output/public，edgeone.json:5）中实际产出的资源路径。

服务端模式与多浏览器复用配置

多浏览器/分享给同事时，每个客户端都需重填密钥较为繁琐 (Issue #8)。自 v1.2.0 起，可通过环境变量启用服务端模式 NUXT_PUBLIC_SERVER_MODE=true，由服务端统一下发配置；公开运行时配置见 PublicRuntimeConfig 接口，私密配置见 ServerRuntimeConfig (shared/types/config.ts:1-40)。

Azure OpenAI 资源不存在

配置 Azure OpenAI 时报“资源不存在” (Issue #70)。根本原因是拼接 base url 的方式与官方 api-version 参数语义不一致。建议改用 openai-compatible 模式并手动指定 apiBase 与模型名，避免依赖 Azure 自动拼接逻辑。

运行时故障

Firecrawl 自部署速率限制不生效

即便在 UI 中设置了速率限制，自托管 Firecrawl 仍可能报 rate limit (Issue #73)。其原因是当前应用层的并发限制仅作用于客户端调度队列，而不会回写到 Firecrawl 服务端。可通过降低 UI 中的“并发数”设置（默认 2）来规避，也可为自部署 Firecrawl 配置反向代理层面的限流。

联网搜索重试无反应

network error 后点击重试无效果 (Issue #71)，属偶发问题。可检查浏览器控制台是否仍残留旧 SSE 连接未关闭；若使用 qwen2.5-32b-instruct 等长上下文模型，注意先在设置中调整 contextSize（参考 i18n/zh.json 的 contextSize 字段）以避免流式响应被截断。

模型返回无效 JSON

parseStreamingJson 在流末尾若解析失败会输出 bad-end 事件 (shared/utils/json.ts:42-52)，对应 i18n 提示 invalidStructuredOutput（“模型返回的内容无效或不完整，无法解析”，i18n/en.json:8）。建议切换到更强的模型或在设置中调高 contextSize。

CORS 跨域报错

浏览器直连某些 AI 服务时被拦截，提示 requestBlockedByCORS（i18n/zh.json）。客户端模式下无服务器中转，只能更换支持跨域的供应商，或部署反向代理。

功能限制与已知缺口

错误诊断流程建议

1. 复现并捕获浏览器控制台 / Docker 容器日志，确认异常发生在 AI、搜索还是抓取阶段。
2. 若为模型输出异常，关注 parseStreamingJson 的 bad-end/error 事件（shared/utils/json.ts:22-50），并比对 i18n 错误键。
3. 若为搜索链路异常，先收敛 Firecrawl 并发与 Tavily 主题配置，再核对 ServerRuntimeConfig 中 tavilyAdvancedSearch 等布尔项是否正确下发。
4. 服务端模式下，所有用户共享同一份配置，修改后需重启镜像以应用 NUXT_PUBLIC_* 环境变量。

See Also

• README.md（英文项目说明）
• README_zh.md（中文部署与环境变量）
• 服务端模式与配置接口
• 流式 JSON 解析工具

Pitfall Log / 踩坑日志

项目：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