DeerFlow 前端工程开发指南基于frontend/AGENTS.md的架构、命令体系与 AI Agent 协作规范【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow导读DeerFlow 的前端是一个基于 Next.js 16 构建的 Agent 系统 Web 界面通过 LangGraph SDK 与后端进行线程化对话、流式响应与制品artifact交互。本文以 frontend/AGENTS.md 为骨架系统梳理其架构分层、源码目录约定、完整命令体系、Rstest/Playwright 双轨测试策略、环境变量与代理配置以及为 AI 编码助手Claude Code、Codex 等设计的协作规范。读完你不仅能快速上手pnpm dev还能理解每个目录、每条命令、每个测试文件背后的设计意图具备独立向该工程提交高质量改动、或为其他 Agent 工程撰写同类开发指引的能力。一、AGENTS.md 是什么AI 协作的唯一事实来源在 DeerFlow 仓库中frontend/AGENTS.md并不仅是一份人类开发者阅读的 README。它的核心定位在文档首段即被点明它为 AI 编码 AgentClaude Code、Codex 及其他在操作 DeerFlow 前端时提供指引是唯一事实来源source of truth同目录的 frontend/CLAUDE.md 仅通过AGENTS.md将其导入。这一设计解决了多 Agent 协作场景下的文档同步难题指引只维护一份Claude Code 用 CLAUDE.md 作为入口、Codex 与通用 Agent 直接读取 AGENTS.md二者指向同一份内容避免多份文档漂移失同步。若你以 AI Agent 身份在本工程内开发第一件事就是完整通读该文件若你是维护者也应遵循其贡献规范一节的约定在架构、命令或约定变化时同步更新它详见后文。从仓库结构看这一分层指引思路被延续到了更深一层frontend/AGENTS.md明确写到src/下存在更细粒度的 frontend/src/AGENTS.md将本文件中的前端各分区再行拆分供聚焦某目录开发时按需查阅。二、项目概览一个有状态对话式 Agent Web 界面2.1 它在整个系统中扮演的角色DeerFlow 前端是一个面向 AI Agent 系统的 Web 界面它并不自行驱动 Agent而是通过LangGraph SDK与基于 LangGraph 的后端通信对外提供基于线程thread的 AI 对话创建会话、发送消息、接收流式响应线程级/goal完成条件用户可为单个线程设定完成目标并跟踪其状态制品artifacts后端 Agent 产出的文件/代码等前端负责展示与管理技能与工具skills/tools系统的交互入口。文档给出了一幅非常凝练的架构图Frontend (Next.js) ──▶ LangGraph SDK ──▶ LangGraph Backend (lead_agent) ├── Sub-Agents └── Tools Skills即前端是瘦客户端它只负责编排对话、渲染流式结果真正的 Agent 编排、工具调用、技能执行都发生在后端的lead_agent及其子 Agent 中。这也解释了为什么前端核心代码src/core/里大量模块都与如何调用后端 API、如何解析流式事件、如何恢复线程状态相关。2.2 技术栈与版本要求文档明确列出了当前栈及运行前提这些信息与 frontend/package.json 中的声明相互印证类别版本 / 要求说明框架Next.js 16package.json 中为next^16.2.11App Router 架构含 i18n 与 rewritesUI 框架React 19react^19.0.0服务端组件与客户端组件混用语言TypeScript 5.8typescript^5.8.2tsc --noEmit做类型检查样式Tailwind CSS 4tailwindcss^4.0.15v4import语法 CSS 变量主题包管理pnpm 10.26.2packageManager字段锁定workspace 内安装使用pnpm运行时Node.js 22、pnpm 10.26.2低于该版本可能无法正常构建2.3 核心依赖及其分工frontend/AGENTS.md强调的四组核心依赖构成了应用的能力底座依赖版本职责langchain/langgraph-sdk^1.5.3Agent 编排与流式通信的唯一通道连接后端langchain/core^1.1.15LangChain/LangGraph 的基础类型与构建块tanstack/react-query^5.90.17服务端状态管理请求缓存、失效、重试UI 体系Shadcn UI、MagicUI、React Bits、Vercel AI SDK组件全部由 registry 自动生成禁止手改结合 frontend/src/core/api/index.ts重新导出api-client以及 frontend/src/core/api 目录下的api-client.ts、stream-mode.ts、fetcher.ts等文件可以看出LangGraph 客户端单例是被core/各业务域threads、artifacts、memory…共享的底层设施core/api之上才是一个个业务领域模块。三、源码布局src/按领域组织而非按类型组织这是整个工程最值得学习的部分。frontend/AGENTS.md给出的目录约定打破了常见全部放 components/ 下的写法改用领域化 少量共享层结构顶层目录内容与职责app/Next.js App Router 页面与 API Route Handlerscomponents/React 组件其中ui/Shadcn与ai-elements/Vercel AI SDK自动生成、ESLint 忽略、禁止手改workspace/聊天页组件、landing/落地页、docs/MDX 渲染组件为手写core/业务逻辑核心。文档列举了大量领域threads/创建/流式/状态、api/LangGraph 客户端单例、agents/自定义 Agent、subagents/运行时 worker 目录与管理变更、auth/、artifacts/、channels/IM 连接、integrations/Lark CLI 等托管三方集成、i18n/en-US、zh-CN、memory/、skills/、messages/、mcp/、models/、input-polish/发送前草稿改写 API、voice-input/浏览器语音识别、suggestions/、tasks/、todos/、tools/、workspace-changes/run 级变更文件摘要与 diff 拉取、config/、notification/、blog/等另有rehype/、streamdown/渲染助手与utils/hooks/共享 React Hookslib/工具函数如由 clsx tailwind-merge 实现的cn()content/MDX 内容博客、文档由应用渲染styles/全局 CSSTailwind v4import CSS 变量主题typings/环境ambientTypeScript 声明根级还有两个关键文件frontend/src/env.js环境变量校验详见第六节与mdx-components.tsMDX 组件映射。从实际目录看如 frontend/src/core 下存在threads/、channels/、memory/、skills/、mcp/、scheduled-tasks/、subagent-batches/等文档所述与仓库实现一致。这种核心代码与页面解耦的布局使单元测试可以纯粹针对core/逻辑运行而无需渲染 DOM对应下文 Rstest 的 node 环境设计。3.1app/下的主要路由文档详列了 App Router 中的关键路由据此可快速定位页面代码/—— 落地页landing/showcase/[thread_id]—— 白名单公开的只读演示页/workspace/chats/[thread_id]—— 需要认证的聊天工作台实际路径见 frontend/src/app/workspace/chats/workspace/agents/[agent_name]与/workspace/agents/new—— 自定义 Agent 的查看与新建/artifacts/view—— 无浏览器镶边chrome-free的窗口用面板自带渲染器渲染单个 Markdown 制品/blog/…与/[lang]/docs/…—— 博客与多语言文档站(auth)/{login,setup,auth/callback}—— 登录、初始化与 OAuth 回调流/api/…Route Handlers例如/api/memory。四、命令体系从开发到发布的完整脚本frontend/AGENTS.md的 Commands 表与 frontend/package.json 的 scripts 一一对应是前端开发最常用的操作入口命令作用备注pnpm dev启动开发服务器默认使用Webpack打包pnpm build生产构建next build文档额外指出可用NEXT_CONFIG_BUILD_OUTPUTstandalone产出 standalone 产物pnpm checkLint 类型检查eslint . tsc --noEmit提交前必跑pnpm lint仅 ESLintpnpm lint:fixESLint 自动修复pnpm formatPrettier 检查实际应用用pnpm format:writepnpm testRstest 单元测试pnpm test:e2ePlaywright E2EChromiumpnpm typechecktsc --noEmitpnpm start启动生产服务器两个值得注意的工程化细节开发期默认用 Webpack。当需要诊断本地 Next.js 打包器问题时可通过环境变量DEER_FLOW_DEV_BUNDLERturbo搭配pnpm dev临时切到 Turbopack。这避免了默认开启 Turbopack 导致难以复现 Webpack 场景问题的调试困境——把非默认打包器当作诊断手段而非默认值。pnpm check是提交闸门。它把 ESLint 与全量类型检查串成一条命令配合贡献规范中提交前运行的要求保证任何 Agent 改动在进入仓库前先过静态检查。五、双轨测试策略Rstest 单元测试 Playwright E2EDeerFlow 前端的测试体系设计得很克制能用纯逻辑测试就不渲染 DOM能 mock 后端就不起真服务。理解这一原则才能正确地把测试写进正确的轨道。5.1 Rstest按环境拆分两个 project单元测试位于tests/unit/目录结构镜像src/例如tests/unit/core/api/stream-mode.test.ts测试src/core/api/stream-mode.ts通过/路径别名导入被测源码。Rstest 在 frontend/rstest.config.ts 中定义了两个 project这是理解整个单测体系的关键project环境匹配文件适用对象node纯node*.test.ts/*.test.tsx纯逻辑测试几乎覆盖全量套件domhappy-dom*.dom.test.ts/*.dom.test.tsx需要document的测试两类文件的命名规则本身就是一种声明需要真实 React 行为effect 顺序、卸载清理、store 变化触发重渲染的 Hook通过testing-library/react的renderHook驱动必须放入.dom.test.*文件而不是在 node 测试里 mockreact需要渲染组件的测试同理。设计动机在文档与配置注释中都写得很直白DOM 环境的运行开销约为 node 套件的 3 倍因此凡不渲染的测试都不应升舱到 DOM 环境。把测试成本显式写进工程文档能让后续贡献者自动形成默认纯逻辑、按需 DOM的成本意识。配置中还有一个值得借鉴的细节bundleDependencies: [streamdown, katex]—— 因为 Streamdown 会以副作用形式引入 KaTeX CSS打包这两个依赖可让 Rsbuild 处理该 CSS 导入而不是让 Node 直接加载它。5.2 Playwright E2E全量 mock 后端E2E 测试位于tests/e2e/由 frontend/playwright.config.ts 驱动仅 Chromium 桌面浏览器 project通过page.route()网络拦截 mock 全部后端 API测试真实页面交互导航、聊天输入、流式响应因此 E2E 无需真实后端即可稳定运行webServer 默认执行next build next start并注入SKIP_ENV_VALIDATION1与DEER_FLOW_AUTH_DISABLED1环境变量跳过环境变量校验、关闭认证专为测试铺路支持PLAYWRIGHT_BASE_URL指向已运行服务以及PLAYWRIGHT_SKIP_WEB_SERVER1跳过内置启动CI 下workers1、失败重试 2 次、使用 github reporter本地默认 html reportertrace: on-first-retry便于诊断。这条E2E 也 mock 后端的路线与架构一致前端真正需要自证的是页面逻辑与流式渲染正确而不是后端的真实行为——后者属于后端 E2E 的职责边界。六、环境变量与网络配置nginx 优先、直连兜底前端环境配置体现了生产默认走反代、开发可直连的哲学是排查页面不响应类问题时的必读内容。6.1 两个可选的 API 地址NEXT_PUBLIC_BACKEND_BASE_URLhttp://localhost:8001 NEXT_PUBLIC_LANGGRAPH_BASE_URLhttp://localhost:8001/api文档明确指出这两个变量可以留空标准make dev/ Docker 流程中nginx 对外提供/api/langgraph/*公共前缀并改写转发到 Gateway 的原生/api/*路由因此本地开发无须手工配置。从 frontend/next.config.js 的rewrites()实现可以印证这一设计当NEXT_PUBLIC_LANGGRAPH_BASE_URL未设置时把/api/langgraph与/api/langgraph/:path*重写到内部网关地址当NEXT_PUBLIC_BACKEND_BASE_URL未设置时把/api/agents、/api/skills以及其余全部网关 APImodels、threads、memory、mcp、artifacts、uploads、suggestions、runs 等通过/api/:path*兜底重写内部网关默认取DEER_FLOW_INTERNAL_GATEWAY_BASE_URL缺省回退到http://127.0.0.1:8001注释特别提醒LangGraph 兼容路由的 rewrite 必须排在网关原生/api/:path*兜底之前以保持其公共前缀。也就是说变量一旦显式设置前端便绕过 nginx/rewrite 直连指定后端否则全部请求收敛到 Next 的 rewrites 层。排查登录后无响应等联通问题时先分清请求走的是反代还是直连。6.2 环境变量校验t3-env zodfrontend/src/env.js 基于t3-oss/env-nextjs与 zod 对服务端、客户端变量做 schema 校验服务端GITHUB_OAUTH_TOKEN、NODE_ENV枚举 development/test/production客户端NEXT_PUBLIC_*前缀才能暴露给浏览器NEXT_PUBLIC_BACKEND_BASE_URL、NEXT_PUBLIC_LANGGRAPH_BASE_URL、NEXT_PUBLIC_STATIC_WEBSITE_ONLY通过SKIP_ENV_VALIDATION可跳过校验Docker 构建场景emptyStringAsUndefined: true—— 空字符串按未定义处理避免误触发必填校验。6.3DEER_FLOW_DEV_ALLOWED_ORIGINS非 localhost 开发的关键当开发服务器需通过局域网地址或反向代理主机名访问而非 localhost时必须设置DEER_FLOW_DEV_ALLOWED_ORIGINS192.168.1.20,my-proxy.internal逗号分隔填写完整 URL 也会被自动规约为纯 host。它喂给 Next 的allowedDevOrigins用于门控/_next/*、字体与 HMR 资源。缺少它会发生什么这些资源请求返回 403页面虽完成 SSR 但永远无法水合hydrate——页面看起来渲染了但包括登录表单在内的所有交互都无响应。其解析逻辑在 frontend/src/dev-origins.js 中实现得相当细致normalizeHost()会剥离 scheme、去掉/?后的路径段、单独处理 IPv6 括号字面量且只在恰好一个冒号host:port时剥离端口避免误伤裸 IPv6。注释点明了陷阱Next 只按 host 匹配带 scheme/端口/路径的条目无法命中任何请求。同时该配置仅开发期生效生产构建会忽略它——这是一个应当写进任何 Agent 工程常见坑清单的配置。七、代码风格约定让 AI Agent 产出可预测的代码frontend/AGENTS.md的 Code Style 一节短小但对 Agent 极其关键——它把审美问题转化为可执行的机械规则约定规则导入顺序builtin → external → internal → parent → sibling组内按字母序组间空行类型导入使用内联类型导入import { type Foo }未使用变量前缀_显式声明有意不用条件类名用cn()来自/lib/utils封装 clsx tailwind-merge路径别名/*映射src/*生成组件ui/与ai-elements/由 Shadcn、MagicUI、React Bits、Vercel AI SDK 的 registry 生成不要手改二者也被 ESLint 忽略对 AI 编码助手而言这些规则直接决定了 diff 是否可被人类审查者接受尤其生成组件不改、导入分组有序两条能显著减少 Agent 改动带来的无谓冲突。八、贡献规范与前端资源预算门禁pnpm perf:check文档给出了向 DeerFlow 前端添加功能的标准动作序列这本质上也是 AI Agent 的开发流程 checklist遵循既有的src/结构新业务逻辑进core/对应领域补充 TypeScript 类型与完善的错误处理在tests/unit/写单测pnpm test在tests/e2e/写 E2Epnpm test:e2e提交前运行pnpm check当架构、命令或约定变化时同步更新本文档AGENTS.md 自身处于版本管理之下。一个容易被忽视的高价值命令是pnpm perf:check对应 package.json 中node scripts/measure-route-assets.mjs --check。文档说明了它的完整机制从一个正常生产构建开始测量/login再以 static-demo 模式构建由 fixture 支撑的 workspace 路由在临时本地端口启动生产服务器测量代表性路由实际引用的唯一 JavaScript 与 CSS 文件详细结果写入.next/performance-results.json将总计与 frontend/performance-budgets.json 中的预算例如/login的 CSS 170KB / JS 850KB/workspace/chats的 CSS 190KB / JS 1750KBdeep chat 页 JS 上限 4100KB比对失败即告警。文档给出的处置原则是预算失败时应修复路由归属或代码拆分点而不是上调上限确需提高上限必须记录并评审被实测出的劣化回归。这种预算文件 归因命令 升级审批的组合比单纯口头要求注意包体积可靠得多是值得在文章里单独强调的工程实践。九、为贡献者与 Agent 提炼的实用清单综合 frontend/AGENTS.md 全篇可沉淀出四条在 DeerFlow 前端高效工作的实用结论先读文档再动手AGENTS.md 是唯一事实来源src/AGENTS.md提供分区细节架构演进时这些文档会被要求同步更新。按域落代码、按需选测试环境业务逻辑进core/对应领域不渲染的测试写*.test.tsnode涉及真实 React 行为的 Hook/组件才写*.dom.test.tshappy-domE2E 一律 mock 后端。提交前跑pnpm check预算靠pnpm perf:check前者拦静态错误后者拦路由体积劣化。联通问题先查环境默认反代路径下不需要设置任何NEXT_PUBLIC_*一旦页面 SSR 成功却无法交互优先检查是否为非 localhost 访问且缺少DEER_FLOW_DEV_ALLOWED_ORIGINS所致403 水合失败相关校验入口见 frontend/src/env.js 与 frontend/src/dev-origins.js。若需进一步理解后端侧能力可继续阅读 backend/docs/API.md 与 backend/docs/ARCHITECTURE.md结合本仓库根目录 frontend/README.md 与本篇共同构成 DeerFlow 前端的完整认知地图。【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
