# Open Canvas 前端实施清单 ## 1. 文档目标 本文档是 [openCanvas.md](./openCanvas.md) 的前端落地版清单。 目标是把 Canvas 模式拆成可以直接开发的前端任务，覆盖： - 路由接入 - 目录结构 - 页面布局 - 状态管理 - 组件拆分 - 接口适配 - 流式更新 - 版本管理 - 局部改写 - 模型选择 - 验收标准 本文档默认后端会配合新增结构化 `artifact` 字段与 `canvas_agent`。 --- ## 2. 实施原则 ### 2.1 总原则 - 不破坏现有 `workspace` 聊天页面 - 尽量复用现有基础设施 - 先做骨架，再接数据，再接智能行为 - 每一步都能跑、能看、能验收 ### 2.2 可复用的现有能力 当前项目前端已有以下基础设施，可尽量复用： - `react-router-dom` 路由体系 - `WorkspaceLayout` 工作区布局 - `@langchain/langgraph-sdk` 客户端 - `useThreadStream` 的流式线程模式 - 模型列表接口 `/api/models` - 现有认证头注入机制 - `sonner` 提示 - `react-resizable-panels` 双栏/拖拽布局 - `CodeMirror` 代码编辑器 ### 2.3 新增能力的边界 Canvas 模式前端是一个“新子系统”，但不建议做成完全独立的第二套应用。 建议方式： - 复用现有壳层和 API 客户端 - 新建 `src/open-canvas` 目录承载新功能 - 将 Canvas 模式接到现有 Page 层路由里 --- ## 3. 目标目录结构 建议新增如下目录： ```text frontend-web/src/open-canvas/ api/ client.ts models.ts threads.ts runs.ts components/ layout/ CanvasShell.tsx CanvasHeader.tsx CanvasResizableLayout.tsx chat/ CanvasChatPanel.tsx CanvasMessageList.tsx CanvasInputBox.tsx CanvasWelcome.tsx artifact/ CanvasArtifactPanel.tsx CanvasArtifactRenderer.tsx CanvasArtifactHeader.tsx CanvasArtifactVersionNav.tsx CanvasEmptyState.tsx TextArtifactRenderer.tsx CodeArtifactRenderer.tsx selectors/ CanvasModelSelector.tsx CanvasModeSelector.tsx quick-actions/ QuickActionBar.tsx QuickActionButton.tsx web-search/ CanvasWebSearchPanel.tsx contexts/ CanvasThreadContext.tsx CanvasGraphContext.tsx CanvasUIContext.tsx hooks/ useCanvasThread.ts useCanvasStream.ts useCanvasArtifact.ts useCanvasSelection.ts useCanvasQuickActions.ts pages/ CanvasHomePage.tsx CanvasThreadPage.tsx routes/ OpenCanvasRoutes.tsx types/ artifact.ts thread.ts model.ts selection.ts quick-action.ts utils/ artifact.ts selection.ts thread.ts stream.ts quick-actions.ts constants/ index.ts ``` --- ## 4. 开发阶段总览 前端建议分为 10 个实施阶段： 1. 路由与目录骨架 2. Canvas 页面布局 3. 类型与状态协议 4. API 适配层 5. 线程和流式状态接入 6. Artifact 渲染与版本管理 7. 快速开始与空状态 8. 局部选区改写交互 9. 快捷动作系统 10. 模型选择与增强能力接入 建议每个阶段完成后都做一次可视化验收。 --- ## 5. 阶段一：路由与目录骨架 ### 5.1 任务目标 把 Canvas 模式先挂到系统里，确保页面可进入。 ### 5.2 任务清单 - 新建 `src/open-canvas/` 目录 - 新建 `src/open-canvas/routes/OpenCanvasRoutes.tsx` - 新建 `src/open-canvas/pages/CanvasHomePage.tsx` - 新建 `src/open-canvas/pages/CanvasThreadPage.tsx` - 修改 [PageRoutes.tsx](../src/pages/PageRoutes.tsx) ### 5.3 路由建议 建议新增： - `/page/canvas` - `/page/canvas/:thread_id` 建议在 `PageLayout` 内部新增： - `path="canvas/*"` 子路由建议： - `index -> CanvasHomePage` - `:thread_id -> CanvasThreadPage` - `new -> 跳转到 CanvasHomePage 或创建临时线程态` ### 5.4 页面行为要求 `CanvasHomePage`： - 展示 Canvas 欢迎页 - 展示快速开始入口 - 可进入新建文本或代码模式 `CanvasThreadPage`： - 只负责线程级页面装配 - 挂载所有 Canvas 上下文提供器 - 渲染主布局组件 ### 5.5 验收标准 - 访问 `/page/canvas` 正常 - 访问 `/page/canvas/xxx` 正常 - 不影响 `/page/workspace/*` - 页面为独立功能入口 --- ## 6. 阶段二：Canvas 页面布局 ### 6.1 任务目标 先搭出稳定的“左聊天右画布”骨架。 ### 6.2 任务清单 - 新建 `layout/CanvasShell.tsx` - 新建 `layout/CanvasHeader.tsx` - 新建 `layout/CanvasResizableLayout.tsx` - 新建 `chat/CanvasChatPanel.tsx` - 新建 `artifact/CanvasArtifactPanel.tsx` - 新建 `artifact/CanvasEmptyState.tsx` ### 6.3 布局要求 推荐布局： - 顶部：Canvas 标题栏 - 左侧：聊天面板 - 右侧：artifact 面板 - 可选右抽屉：Web 搜索结果 ### 6.4 建议复用 可以优先复用： - `react-resizable-panels` - 现有按钮、分隔线、Tabs、Tooltip 等 UI 组件 ### 6.5 初始状态要求 无 thread 或 thread 中无 artifact 时： - 右侧显示空状态 - 左侧显示欢迎语和快速开始 ### 6.6 验收标准 - 双栏布局稳定 - 可拖拽调整宽度 - 空状态显示正常 - 适配桌面优先，移动端先做降级布局 --- ## 7. 阶段三：类型与状态协议 ### 7.1 任务目标 先把前端需要消费和管理的数据类型定下来。 ### 7.2 任务清单 - 新建 `types/artifact.ts` - 新建 `types/thread.ts` - 新建 `types/model.ts` - 新建 `types/selection.ts` - 新建 `types/quick-action.ts` ### 7.3 必要类型 #### artifact.ts - `CanvasArtifact` - `CanvasArtifactText` - `CanvasArtifactCode` - `CanvasArtifactContent` #### selection.ts - `CanvasTextSelection` - `CanvasCodeSelection` - `CanvasSelectionState` #### thread.ts - `CanvasThreadValues` - `CanvasThreadMetadata` - `CanvasThread` ### 7.4 建议结构 ```ts export type CanvasArtifact = { currentIndex: number; contents: CanvasArtifactContent[]; }; export type CanvasArtifactText = { index: number; type: "text"; title: string; fullMarkdown: string; }; export type CanvasArtifactCode = { index: number; type: "code"; title: string; language: string; code: string; }; ``` ### 7.5 线程值类型建议 ```ts export type CanvasThreadValues = { title?: string; messages?: Message[]; artifact?: CanvasArtifact; web_search_results?: unknown[]; todos?: unknown[]; }; ``` ### 7.6 验收标准 - 所有 Canvas 组件只依赖 `open-canvas/types` - 不把类型散落到页面或组件内部 - 前后端协议字段统一命名 --- ## 8. 阶段四：前端 Context 设计 ### 8.1 任务目标 把 Canvas 的状态拆成职责清晰的三层上下文。 ### 8.2 任务清单 - 新建 `CanvasThreadContext.tsx` - 新建 `CanvasGraphContext.tsx` - 新建 `CanvasUIContext.tsx` ### 8.3 职责划分 #### CanvasThreadContext 负责： - 当前 thread id - thread 基础信息 - thread 创建/切换 - 模型名称 - 模型配置 #### CanvasGraphContext 负责： - messages - artifact - runId - streaming 状态 - error 状态 - 发送消息 - 停止生成 - 切换版本 - 更新 artifact 内容 #### CanvasUIContext 负责： - 面板折叠状态 - 是否正在编辑 - 当前选区 - Web 搜索面板开关 - 快捷动作面板开关 ### 8.4 验收标准 - 页面组件不直接持有大量跨层 useState - 聊天状态和 UI 状态分离 - 线程切换时可安全重置状态 --- ## 9. 阶段五：API 适配层 ### 9.1 任务目标 为 Canvas 模式建立专用的前端 API 包装层。 ### 9.2 任务清单 - 新建 `api/client.ts` - 新建 `api/models.ts` - 新建 `api/threads.ts` - 新建 `api/runs.ts` ### 9.3 设计要求 不要让页面组件直接到处调用现有 `getAPIClient()` 或裸 `fetch`。 建议统一在 `src/open-canvas/api/` 中封装。 ### 9.4 需要封装的能力 #### models.ts - `loadCanvasModels()` - 对现有 `/api/models` 结果做标准化 #### threads.ts - `createCanvasThread()` - `getCanvasThread(threadId)` - `updateCanvasThreadMetadata(threadId, metadata)` - `updateCanvasThreadState(threadId, values)` #### runs.ts - `streamCanvasRun(...)` - `stopCanvasRun(...)` ### 9.5 与现有 API 的关系 底层可以复用： - `src/core/api/api-client.ts` - `src/core/api/fetch-client.ts` 但上层调用应走 Canvas 专用 API。 ### 9.6 验收标准 - 页面层不直接拼接 URL - Canvas API 调用集中管理 - 后续改协议时只动一层 --- ## 10. 阶段六：线程与流式状态接入 ### 10.1 任务目标 让 Canvas 页面能像现有 ChatPage 一样收发消息并接流。 ### 10.2 任务清单 - 新建 `hooks/useCanvasThread.ts` - 新建 `hooks/useCanvasStream.ts` - 新建 `utils/stream.ts` ### 10.3 设计建议 可以参考现有： - [ChatPage.tsx](../src/pages/ChatPage.tsx) - [threads/hooks.ts](../src/core/threads/hooks.ts) 但不要直接把现有 `ChatPage` 复制一份。 ### 10.4 `useCanvasThread` 负责 - 当前 thread id 管理 - 新建/切换 thread - 从 URL 参数恢复 thread ### 10.5 `useCanvasStream` 负责 - 发送消息 - 停止生成 - 处理流式事件 - 更新 `messages` - 更新 `artifact` - 更新 `runId` ### 10.6 流式更新要求 首版可以假设后端在 `values` 或 `updates` 中返回： - `messages` - `artifact` 前端需要： - 新消息追加 - artifact 覆盖或增量更新 - 流结束后保持最终状态 ### 10.7 验收标准 - 能发消息 - 能收到消息 - 能实时更新 artifact - 停止按钮可用 --- ## 11. 阶段七：Artifact 渲染器 ### 11.1 任务目标 实现文本/代码两类 artifact 的基础渲染与切换。 ### 11.2 任务清单 - 新建 `artifact/CanvasArtifactRenderer.tsx` - 新建 `artifact/CanvasArtifactHeader.tsx` - 新建 `artifact/CanvasArtifactVersionNav.tsx` - 新建 `artifact/TextArtifactRenderer.tsx` - 新建 `artifact/CodeArtifactRenderer.tsx` ### 11.3 组件职责 #### CanvasArtifactRenderer - 判断当前 artifact 是否存在 - 判断当前内容是文本还是代码 - 分发到具体渲染器 #### CanvasArtifactHeader - 显示标题 - 显示保存状态 - 显示版本导航 #### CanvasArtifactVersionNav - 上一个版本 - 下一个版本 - 当前版本号 #### TextArtifactRenderer - 渲染 markdown 内容 - 支持编辑模式 - 支持文本选区 #### CodeArtifactRenderer - 使用 CodeMirror - 支持语言模式切换 - 支持代码选区 ### 11.4 首版策略 文本首版建议： - 编辑态用 textarea 或现有 markdown 编辑器 - 展示态用现有 markdown renderer 代码首版建议： - 直接复用现有 CodeMirror 基础能力 ### 11.5 验收标准 - 文本 artifact 可看可编辑 - 代码 artifact 可看可编辑 - 版本切换正确 - 标题与当前版本一致 --- ## 12. 阶段八：快速开始与空状态 ### 12.1 任务目标 让用户在没有任何 artifact 时也能顺畅开始。 ### 12.2 任务清单 - 新建 `chat/CanvasWelcome.tsx` - 在 `CanvasHomePage` 中增加快速开始面板 - 在 `CanvasThreadPage` 空状态时提供快速开始 ### 12.3 快速开始项建议 - 空白文本 - 空白代码 - React 组件模板 - HTML 页面模板 - Python 脚本模板 ### 12.4 行为要求 点击后： - 创建本地前端 artifact 草稿 - 必要时自动创建 thread - 自动进入编辑态 ### 12.5 验收标准 - 不发消息也能先建立 artifact - 新建文本/代码入口可用 - 初始编辑体验完整 --- ## 13. 阶段九：Artifact 版本管理 ### 13.1 任务目标 让每次 AI 生成或修改都成为一个新版本。 ### 13.2 任务清单 - 新建 `hooks/useCanvasArtifact.ts` - 新建 `utils/artifact.ts` ### 13.3 必要能力 - 获取当前版本内容 - 切换版本 - 更新当前版本内容 - 追加新版本 - 判断 artifact 是否为空 ### 13.4 推荐工具函数 - `getCurrentArtifactContent(artifact)` - `setCurrentArtifactIndex(artifact, index)` - `appendArtifactVersion(artifact, content)` - `replaceCurrentArtifactContent(artifact, content)` - `isTextArtifact(content)` - `isCodeArtifact(content)` ### 13.5 注意事项 - 前端切版本不能直接修改原对象引用 - 每次更新要创建新对象，避免渲染异常 ### 13.6 验收标准 - AI 更新后版本数增加 - 手动切换历史版本稳定 - 当前版本高亮正确 --- ## 14. 阶段十：局部选区交互 ### 14.1 任务目标 实现局部改写所需的前端选区采集与展示。 ### 14.2 任务清单 - 新建 `hooks/useCanvasSelection.ts` - 新建 `utils/selection.ts` ### 14.3 文本选区需求 - 获取选中起止位置 - 获取选中文本 - 在 UI 上显示“已选中某段内容” - 支持清除选区 ### 14.4 代码选区需求 - 获取 CodeMirror 选区 - 保存选中代码内容 - 保存 start/end 或行列信息 ### 14.5 交互建议 可以在选区出现后展示浮层或工具条： - 改写 - 精简 - 扩写 - 解释 首版先只保留： - “对所选内容进行修改” 的统一入口 ### 14.6 验收标准 - 文本选区可读 - 代码选区可读 - 选区状态可清空 - 切换版本或 thread 时选区自动重置 --- ## 15. 阶段十一：聊天面板适配 ### 15.1 任务目标 实现 Canvas 模式专用聊天面板，不直接塞回现有 ChatBox。 ### 15.2 任务清单 - 新建 `chat/CanvasMessageList.tsx` - 新建 `chat/CanvasInputBox.tsx` - 新建 `chat/CanvasChatPanel.tsx` ### 15.3 设计建议 可以参考现有 ChatPage 的结构，但建议把 Canvas 模式聊天区做成更轻量版本。 ### 15.4 必要功能 - 展示消息列表 - 展示生成中状态 - 提交输入 - 停止生成 - 显示模型选择器 - 显示 Web 搜索开关 ### 15.5 可以复用 - 现有消息渲染组件中的部分能力 - 现有 InputBox 的一部分交互逻辑 ### 15.6 不建议直接复用 - 当前工作区的文件 artifact 面板耦合 - 当前以文件产物为中心的 ChatBox 结构 ### 15.7 验收标准 - Canvas 聊天区独立可用 - 能与 artifact 面板联动 - 布局不受现有文件 artifact 影响 --- ## 16. 阶段十二：模型选择器 ### 16.1 任务目标 让 Canvas 模式可以使用 DeerFlow 的动态模型列表。 ### 16.2 任务清单 - 新建 `selectors/CanvasModelSelector.tsx` - 在 `api/models.ts` 中做标准化 ### 16.3 UI 要求 - 显示模型名 - 显示是否本地模型 - 显示是否支持视觉/推理/Canvas ### 16.4 状态要求 - 当前 thread 记录 `model_name` - 必要时记录 `model_config` - 切换 thread 时能恢复模型 ### 16.5 首版能力 首版可以只做： - 下拉选择模型 - 将模型信息写入 thread metadata 或 run configurable ### 16.6 验收标准 - 模型列表正确展示 - 切换模型后发消息使用新模型 - 本地模型与云模型能在 UI 中区分 --- ## 17. 阶段十三：快捷动作栏 ### 17.1 任务目标 实现 artifact 上方或下方的快捷动作入口。 ### 17.2 任务清单 - 新建 `quick-actions/QuickActionBar.tsx` - 新建 `quick-actions/QuickActionButton.tsx` - 新建 `hooks/useCanvasQuickActions.ts` - 新建 `utils/quick-actions.ts` ### 17.3 首版动作建议 文本类： - 扩写 - 精简 - 改正式 - 改口语 代码类： - 加注释 - 加日志 - 修 bug ### 17.4 行为要求 点击动作后： - 写入 `quick_action_id` - 触发一次 Canvas run - 生成新的 artifact 版本 ### 17.5 验收标准 - 动作栏根据 artifact 类型动态变化 - 动作点击后有效果 - 新版本正确生成 --- ## 18. 阶段十四：Web 搜索面板 ### 18.1 任务目标 为后续搜索增强预留 UI 和交互位置。 ### 18.2 任务清单 - 新建 `web-search/CanvasWebSearchPanel.tsx` - 在 `CanvasUIContext` 中增加开关状态 ### 18.3 首版要求 - 只做抽屉面板 - 可展示结构化搜索结果列表 - 可开关显示 ### 18.4 二期能力 - 支持点击来源预览 - 支持从结果插入上下文 ### 18.5 验收标准 - 面板开关正常 - 搜索结果区域可承载数据 --- ## 19. 阶段十五：页面装配 ### 19.1 任务目标 将所有子模块整合到页面中。 ### 19.2 任务清单 `CanvasHomePage.tsx`： - 欢迎页 - 快速开始 - 最近 Canvas 线程入口 `CanvasThreadPage.tsx`： - 解析 route params - 挂载 `CanvasThreadContext` - 挂载 `CanvasGraphContext` - 挂载 `CanvasUIContext` - 渲染 `CanvasShell` ### 19.3 结构建议 ```tsx ``` ### 19.4 验收标准 - 页面层只负责装配，不承载复杂业务逻辑 - 子组件依赖上下文而不是层层 props drilling --- ## 20. 推荐逐文件实施顺序 建议按这个顺序建文件： 1. `routes/OpenCanvasRoutes.tsx` 2. `pages/CanvasHomePage.tsx` 3. `pages/CanvasThreadPage.tsx` 4. `types/*` 5. `contexts/CanvasThreadContext.tsx` 6. `contexts/CanvasUIContext.tsx` 7. `contexts/CanvasGraphContext.tsx` 8. `layout/CanvasShell.tsx` 9. `layout/CanvasResizableLayout.tsx` 10. `artifact/CanvasEmptyState.tsx` 11. `artifact/CanvasArtifactRenderer.tsx` 12. `artifact/TextArtifactRenderer.tsx` 13. `artifact/CodeArtifactRenderer.tsx` 14. `chat/CanvasChatPanel.tsx` 15. `chat/CanvasInputBox.tsx` 16. `api/*` 17. `hooks/useCanvasStream.ts` 18. `hooks/useCanvasSelection.ts` 19. `quick-actions/*` 20. `web-search/*` --- ## 21. 开发任务拆分建议 如果多人协作，建议这样拆： ### A 组：页面与路由 - 路由接入 - 页面骨架 - 主布局 ### B 组：artifact 视图 - artifact 类型 - 渲染器 - 版本导航 - 代码/文本编辑器 ### C 组：聊天与流式 - thread 管理 - stream 接入 - 消息面板 - 模型切换 ### D 组：增强交互 - 选区 - 快捷动作 - 搜索面板 --- ## 22. 每阶段验收清单 ### 22.1 阶段一到三 - 路由正常 - 空页面正常 - 类型编译通过 - 目录结构清晰 ### 22.2 阶段四到六 - thread 可创建/读取 - 消息可发送 - artifact 可展示 - 流式结果可更新 ### 22.3 阶段七到九 - 文本/代码 artifact 渲染正确 - 版本导航正确 - 快速开始可用 - 模型选择可用 ### 22.4 阶段十到十四 - 局部选区可采集 - 快捷动作可触发 - 搜索面板可显示 - 各功能互不冲突 --- ## 23. 风险点与规避方式 ### 23.1 不要直接复制现有 ChatPage 原因： - 现有页面与文件 artifact 耦合较重 - Canvas 需要结构化 artifact 而不是文件列表 ### 23.2 不要把所有状态都放一个 Context 原因： - 更新频率高 - 容易导致全树重渲染 ### 23.3 不要先做复杂富文本 原因： - 选区映射复杂 - 首版容易卡在编辑器实现而不是业务链路 建议先以： - `fullMarkdown` - `textarea/markdown renderer` 作为最小闭环。 ### 23.4 不要前端硬编码模型表 原因： - 后端才是真源 - 后期本地模型和自定义 provider 会频繁变化 --- ## 24. 首版最小可交付范围 前端首版建议只交付这些： - `canvas/*` 路由 - Canvas 双栏布局 - 文本/代码 artifact 渲染 - 模型选择器 - 流式聊天 - artifact 版本切换 - 快速开始 首版先不强制包含： - 复杂文本局部高亮浮层 - 复杂快捷动作配置中心 - 高级 Web 搜索结果联动 --- ## 25. 下一步建议 完成本文档后，建议继续产出两份更细的执行文件： ### 25.1 前端文件创建顺序清单 按天或按 PR 颗粒度，列出： - 每一批次新建哪些文件 - 每一批次修改哪些已有文件 ### 25.2 前端组件接口文档 列出关键组件 props： - `CanvasShell` - `CanvasChatPanel` - `CanvasArtifactRenderer` - `CanvasModelSelector` 这样正式开工时会更顺畅。 --- ## 26. 参考源码映射 前端实施清单建议补充对 `langchain-ai/open-canvas` 源码的“映射式参考”，但不建议把源码大段粘贴进本文档。 推荐做法是： - 记录参考文件路径 - 说明它解决了什么问题 - 说明在 DeerFlow 前端里应该落到哪个模块 - 只摘能力点，不摘整段实现 这样做的原因： - 文档更清晰 - 不会把 Next.js 运行时细节误当成可直接迁移代码 - 后续维护更轻 ### 26.1 推荐参考文件总览 以下文件最值得作为前端实现参考： - `apps/web/src/contexts/GraphContext.tsx` - `apps/web/src/components/canvas/canvas.tsx` - `apps/web/src/components/artifacts/ArtifactRenderer.tsx` - `apps/web/src/components/artifacts/TextRenderer.tsx` - `apps/web/src/components/artifacts/CodeRenderer.tsx` - `apps/web/src/contexts/ThreadProvider.tsx` - `apps/web/src/contexts/AssistantContext.tsx` - `apps/web/src/hooks/useRuns.tsx` - `apps/web/src/types.ts` - `packages/shared/src/types.ts` - `packages/shared/src/models.ts` - `packages/shared/src/utils/artifacts.ts` ### 26.2 逐文件映射建议 #### `apps/web/src/contexts/GraphContext.tsx` 参考价值： - 这是 open-canvas 前端最核心的状态管理文件之一 - 管理消息、artifact、流式状态、保存状态、版本切换、局部更新 - 处理流中 artifact 更新和 thread 切换 DeerFlow 对应落点： - `src/open-canvas/contexts/CanvasGraphContext.tsx` - `src/open-canvas/hooks/useCanvasStream.ts` - `src/open-canvas/utils/stream.ts` - `src/open-canvas/utils/artifact.ts` 重点借鉴内容： - artifact 如何作为线程主状态存在 - 流式过程中如何同步 messages 与 artifact - 切换 thread 时如何恢复状态 - 如何维护“当前版本”和“已保存状态” 不建议直接照搬的部分： - 与 Next.js、`nuqs`、open-canvas 内部 hook 耦合的代码 - 与其后端返回格式强绑定的处理逻辑 #### `apps/web/src/components/canvas/canvas.tsx` 参考价值： - Open Canvas 的主页面装配组件 - 管理左聊天右画布布局 - 定义快速开始逻辑 - 管理 chat collapsed、artifact 初始创建 DeerFlow 对应落点： - `src/open-canvas/components/layout/CanvasShell.tsx` - `src/open-canvas/components/layout/CanvasResizableLayout.tsx` - `src/open-canvas/pages/CanvasThreadPage.tsx` 重点借鉴内容： - 快速开始时如何创建文本或代码 artifact - 左右双栏如何组织 - 页面级状态和上下文边界怎么划分 不建议直接照搬的部分： - Next 路由参数逻辑 - 与 open-canvas ThreadProvider 强耦合的状态恢复代码 #### `apps/web/src/components/artifacts/ArtifactRenderer.tsx` 参考价值： - 负责 artifact 总渲染分发 - 根据当前版本内容选择文本或代码渲染器 - 负责版本导航和选区交互挂钩 DeerFlow 对应落点： - `src/open-canvas/components/artifact/CanvasArtifactRenderer.tsx` - `src/open-canvas/components/artifact/CanvasArtifactHeader.tsx` - `src/open-canvas/components/artifact/CanvasArtifactVersionNav.tsx` 重点借鉴内容： - 当前 artifact 的统一入口组件结构 - 版本导航和正文渲染如何组合 - 文本/代码视图如何统一被包装 #### `apps/web/src/components/artifacts/TextRenderer.tsx` 参考价值： - 负责文本 artifact 的渲染与编辑 - 处理 markdown 内容、更新、局部交互 DeerFlow 对应落点： - `src/open-canvas/components/artifact/TextArtifactRenderer.tsx` - `src/open-canvas/hooks/useCanvasSelection.ts` 重点借鉴内容： - 文本 artifact 的编辑态与展示态切换 - 当前版本内容如何回写到状态 - 局部选区的挂接点 实现上的取舍建议： - DeerFlow 首版不要追求和 open-canvas 一样复杂的富文本块级编辑 - 建议先用 `fullMarkdown` + markdown renderer + 简单编辑态完成闭环 #### `apps/web/src/components/artifacts/CodeRenderer.tsx` 参考价值： - 负责代码 artifact 的渲染与编辑 - 与 CodeMirror 集成 - 管理代码内容更新 DeerFlow 对应落点： - `src/open-canvas/components/artifact/CodeArtifactRenderer.tsx` 重点借鉴内容： - 代码 artifact 如何绑定语言 - 代码编辑结果如何同步回 artifact 状态 - 局部代码选区的接入位置 #### `apps/web/src/contexts/ThreadProvider.tsx` 参考价值： - 负责 thread 与模型相关状态 - 管理 thread 切换和 thread 级配置 DeerFlow 对应落点： - `src/open-canvas/contexts/CanvasThreadContext.tsx` - `src/open-canvas/hooks/useCanvasThread.ts` 重点借鉴内容： - 当前 thread id 的管理方式 - thread metadata 与 model state 的关系 - 页面恢复 thread 时的上下文同步 #### `apps/web/src/contexts/AssistantContext.tsx` 参考价值： - 管理 assistant 选择 - 管理与 assistant 相关的 thread 行为 DeerFlow 对应落点： - DeerFlow 首版可以弱化这部分 - 如果首版只有 `canvas_agent` 一个固定 assistant，可只保留最小 assistant 绑定能力 重点借鉴内容： - thread 与 assistant 的耦合方式 #### `apps/web/src/hooks/useRuns.tsx` 参考价值： - 管理 run 相关行为 DeerFlow 对应落点： - `src/open-canvas/api/runs.ts` - `src/open-canvas/hooks/useCanvasStream.ts` 重点借鉴内容： - run 行为与页面状态的解耦方式 #### `apps/web/src/types.ts` 参考价值： - 保存了一部分 artifact 和消息类型定义 DeerFlow 对应落点： - `src/open-canvas/types/artifact.ts` - `src/open-canvas/types/thread.ts` 重点借鉴内容： - artifact 的前端表达方式 注意： - 更建议以 `packages/shared/src/types.ts` 为主参考，而不是这个文件 - 因为 `src/types.ts` 里同时包含了部分历史兼容结构 #### `packages/shared/src/types.ts` 参考价值： - 这是 open-canvas 中最重要的共享类型来源之一 - 定义了 `ArtifactV3`、代码/文本内容、选择区和其他共享结构 DeerFlow 对应落点： - `src/open-canvas/types/artifact.ts` - `src/open-canvas/types/selection.ts` - 可作为前后端协议设计的主要参考 重点借鉴内容： - `ArtifactV3` 结构 - 文本/代码 artifact 类型边界 - 与版本管理有关的字段组织方式 建议： - DeerFlow 可以参考其字段设计 - 但不要机械复制所有字段，保留适合当前项目的最小集 #### `packages/shared/src/models.ts` 参考价值： - 展示了 open-canvas 如何组织前端模型列表和模型能力 DeerFlow 对应落点： - `src/open-canvas/types/model.ts` - `src/open-canvas/api/models.ts` - `src/open-canvas/components/selectors/CanvasModelSelector.tsx` 重点借鉴内容： - 模型展示结构 - provider 概念 - 各模型能力标签的前端呈现思路 注意： - 不应作为 DeerFlow 的模型配置真源 - DeerFlow 必须以自己后端 `/api/models` 为真源 #### `packages/shared/src/utils/artifacts.ts` 参考价值： - 里面有 artifact 类型判断和内容获取工具 DeerFlow 对应落点： - `src/open-canvas/utils/artifact.ts` 重点借鉴内容： - 获取当前版本内容 - 判断当前 artifact 是文本还是代码 - 为渲染器和快捷动作提供统一入口 ### 26.3 可以直接参考但不要直接迁移的部分 以下内容可以借鉴思路，但不建议直接搬代码： - Next.js 路由和页面结构 - `src/app/api/*` 目录中的 API Route - Supabase SSR 和服务端 session 相关代码 - `next/navigation` 相关逻辑 - `middleware.ts` 原因： - DeerFlow 前端是 `React 19 + Vite + react-router-dom` - 这些代码依赖 Next.js 运行时 ### 26.4 建议的使用方式 开发时推荐这样使用参考源码： 1. 先按本文档实现 DeerFlow 自己的模块边界 2. 遇到某个具体功能点时，再去查对应 open-canvas 文件 3. 提炼实现思路，重写到 DeerFlow 的目录结构中 4. 不要复制包含 Next.js 运行时依赖的代码 ### 26.5 推荐补充动作 如果后面要正式进入实现阶段，建议再单独新增一份源码映射文档，例如： - `frontend-web/docs/openCanvas-source-map.md` 里面可以更细地记录： - open-canvas 文件路径 - DeerFlow 对应目标文件 - 迁移策略 - 是否可直接借鉴 - 是否需要重写