wsk/deerflow-code

0 Fork 0

Files

T

fengxiangdebaozi a0d04cba50 文档修改

2026-05-15 10:42:44 +08:00

27 KiB

Raw Blame History

Open Canvas 前端实施清单

1. 文档目标

本文档是 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. 目标目录结构

建议新增如下目录：

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 个实施阶段：

路由与目录骨架
Canvas 页面布局
类型与状态协议
API 适配层
线程和流式状态接入
Artifact 渲染与版本管理
快速开始与空状态
局部选区改写交互
快捷动作系统
模型选择与增强能力接入

建议每个阶段完成后都做一次可视化验收。

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

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 建议结构

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 线程值类型建议

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 复制一份。

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 结构建议

<CanvasThreadProvider>
  <CanvasGraphProvider>
    <CanvasUIProvider>
      <CanvasShell />
    </CanvasUIProvider>
  </CanvasGraphProvider>
</CanvasThreadProvider>

19.4 验收标准

页面层只负责装配，不承载复杂业务逻辑
子组件依赖上下文而不是层层 props drilling

20. 推荐逐文件实施顺序

建议按这个顺序建文件：

routes/OpenCanvasRoutes.tsx
pages/CanvasHomePage.tsx
pages/CanvasThreadPage.tsx
types/*
contexts/CanvasThreadContext.tsx
contexts/CanvasUIContext.tsx
contexts/CanvasGraphContext.tsx
layout/CanvasShell.tsx
layout/CanvasResizableLayout.tsx
artifact/CanvasEmptyState.tsx
artifact/CanvasArtifactRenderer.tsx
artifact/TextArtifactRenderer.tsx
artifact/CodeArtifactRenderer.tsx
chat/CanvasChatPanel.tsx
chat/CanvasInputBox.tsx
api/*
hooks/useCanvasStream.ts
hooks/useCanvasSelection.ts
quick-actions/*
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 建议的使用方式

开发时推荐这样使用参考源码：

先按本文档实现 DeerFlow 自己的模块边界
遇到某个具体功能点时，再去查对应 open-canvas 文件
提炼实现思路，重写到 DeerFlow 的目录结构中
不要复制包含 Next.js 运行时依赖的代码

26.5 推荐补充动作

如果后面要正式进入实现阶段，建议再单独新增一份源码映射文档，例如：

frontend-web/docs/openCanvas-source-map.md

里面可以更细地记录：

open-canvas 文件路径
DeerFlow 对应目标文件
迁移策略
是否可直接借鉴
是否需要重写

27 KiB Raw Blame History Unescape Escape

Open Canvas 前端实施清单

1. 文档目标

2. 实施原则

2.1 总原则

2.2 可复用的现有能力

2.3 新增能力的边界

3. 目标目录结构

4. 开发阶段总览

5. 阶段一：路由与目录骨架

5.1 任务目标

5.2 任务清单

5.3 路由建议

5.4 页面行为要求

5.5 验收标准

6. 阶段二：Canvas 页面布局

6.1 任务目标

6.2 任务清单

6.3 布局要求

6.4 建议复用

6.5 初始状态要求

6.6 验收标准

7. 阶段三：类型与状态协议

7.1 任务目标

7.2 任务清单

7.3 必要类型

artifact.ts

selection.ts

thread.ts

7.4 建议结构

7.5 线程值类型建议

7.6 验收标准

8. 阶段四：前端 Context 设计

8.1 任务目标

8.2 任务清单

8.3 职责划分

CanvasThreadContext

CanvasGraphContext

CanvasUIContext

8.4 验收标准

9. 阶段五：API 适配层

9.1 任务目标

9.2 任务清单

9.3 设计要求

9.4 需要封装的能力

models.ts

threads.ts

runs.ts

9.5 与现有 API 的关系

9.6 验收标准

10. 阶段六：线程与流式状态接入

10.1 任务目标

10.2 任务清单

10.3 设计建议

10.4 useCanvasThread 负责

10.5 useCanvasStream 负责

10.6 流式更新要求

10.7 验收标准

11. 阶段七：Artifact 渲染器

11.1 任务目标

11.2 任务清单

11.3 组件职责

CanvasArtifactRenderer

CanvasArtifactHeader

CanvasArtifactVersionNav

TextArtifactRenderer

CodeArtifactRenderer

11.4 首版策略

11.5 验收标准

12. 阶段八：快速开始与空状态

12.1 任务目标

12.2 任务清单

12.3 快速开始项建议

12.4 行为要求

12.5 验收标准

13. 阶段九：Artifact 版本管理

13.1 任务目标

13.2 任务清单

13.3 必要能力

13.4 推荐工具函数

27 KiB

Raw Blame History

10.4 `useCanvasThread` 负责

10.5 `useCanvasStream` 负责

`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`