deerflow-code/frontend-web/docs/openCanvas.md

Open Canvas 模式需求拆解文档

1. 文档目标

本文档用于指导 DeerFlow 在现有架构中新增一个 open-canvas 风格的 Canvas 模式。

目标不是直接照搬 langchain-ai/open-canvas 的 Next.js + LangGraph.js 实现，而是在当前项目技术栈内完成一套等价能力的实现：

• 前端：基于 React 19 + Vite + react-router-dom
• 后端：基于 Python + FastAPI + LangGraph
• 模型层：支持云模型与本地模型自由配置
• 状态层：支持结构化 artifact、版本历史、局部改写、快速动作、画布编辑

本文档重点是把需求拆成“可实现、可排期、可验收”的阶段性任务。

---

2. 最终目标

2.1 用户视角目标

用户进入一个新的 Canvas 工作模式后，可以获得与 open-canvas 接近的体验：

• 左侧是聊天区，右侧是 Canvas 编辑区
• 可以从空白文本或代码模板快速开始
• 可以通过聊天让 AI 生成一份结构化 artifact
• 可以对 artifact 整体重写，也可以对选中的局部内容进行改写
• artifact 支持版本历史切换
• artifact 支持文本和代码两种主要类型
• 支持快速动作，例如扩写、压缩、改风格、改语气、加注释、修 bug、换语言
• 支持启用 Web 搜索增强
• 支持切换模型
• 支持使用本地模型，例如 Ollama 或 OpenAI-compatible 本地服务

2.2 工程视角目标

新增的 Canvas 模式需要满足以下工程原则：

• 不破坏现有 DeerFlow 工作区
• 不影响现有基于 artifacts: string[] 的文件产物功能
• 可逐阶段上线
• 前后端状态协议清晰
• 可兼容现有 LangGraph 线程、消息流、认证和模型接口

---

3. 范围定义

3.1 本次需求包含

• 前端新增 open-canvas 专用目录
• 在 PageRoutes.tsx 中引入新的 Canvas 路由
• 前端新增 Canvas 页面、上下文、组件、状态管理
• 后端新增 Canvas 专用线程状态字段
• 后端新增 Canvas Agent 图或在现有 Agent 体系中新增 Canvas 模式分支
• 模型配置统一为 DeerFlow 后端配置驱动
• 支持本地大模型配置与模型列表动态下发
• 支持结构化 artifact 的保存、读取、更新、版本切换

3.2 本次需求不包含

• 一次性复刻 open-canvas 全部 UI 细节
• 完整照搬 Supabase 鉴权体系
• 直接复用 open-canvas 的 Next.js API Route
• 直接运行 open-canvas 的 LangGraph.js 后端
• 首阶段就实现所有快捷动作、所有富文本效果、所有搜索增强能力

3.3 迁移原则

• 借鉴 open-canvas 的能力模型，不直接迁移其运行时架构
• 前端尽量复用其交互设计和数据结构
• 后端以 Python 实现同等能力
• 配置以 DeerFlow 为真源，不以 open-canvas 的 TS 文件为真源

---

4. 总体设计思路

4.1 前端设计思路

在现有 frontend-web/src 下新增一个专用目录，例如：

src/
  open-canvas/
    pages/
    routes/
    components/
    contexts/
    hooks/
    types/
    api/
    utils/
    constants/

建议将 Canvas 模式作为一个独立的页面子系统接入，而不是把现有工作区页面强行改造成 Canvas。

建议路由形式：

• /canvas
• /canvas/:threadId

也可以挂在现有页面布局下，例如：

• /workspace/canvas
• /workspace/canvas/:threadId

推荐优先采用独立一级功能路由：

• 逻辑更清晰
• 状态隔离更容易
• 不容易污染现有 workspace 功能

4.2 后端设计思路

后端不建议直接改造现有通用 Agent 去同时承担全部 Canvas 行为，而是建议采用以下两种方案之一：

方案 A：新增独立 Canvas Assistant

• 新增 canvas_agent
• 使用单独的 LangGraph 状态定义
• 前端调用时通过 assistant_id=canvas_agent

优点：

• 与现有 lead_agent 隔离
• 风险更低
• 更容易对齐 open-canvas 的图结构

缺点：

• 会产生一套新的 Agent 图维护成本

方案 B：在现有 Lead Agent 中增加 Canvas 模式分支

• 在 thread metadata 或 configurable 中增加 ui_mode=canvas
• Agent 根据模式进入 Canvas 路径

优点：

• 统一入口

缺点：

• 会显著增加现有 Agent 复杂度
• 容易影响现有聊天和文件产物模式

推荐先做方案 A。

4.3 模型配置设计思路

模型配置统一以 DeerFlow 后端 config.yaml 为真源。

前端不维护固定模型常量列表，而是通过 /api/models 获取模型能力元数据。

为了实现 open-canvas 风格体验，需要后端模型接口至少返回：

• name
• display_name
• provider
• supports_thinking
• supports_reasoning_effort
• supports_vision
• supports_tool_calling
• supports_artifact_editing
• supports_code_editing
• temperature_range
• max_tokens_range
• base_url_source 或 provider 标识
• is_local

---

5. 与当前项目的关键差异

5.1 当前 DeerFlow 现状

当前 DeerFlow 线程状态中的 artifact 主要是文件路径列表：

• artifacts: string[]

这更接近“生成文件产物”的工作模式。

前端当前 artifact 面板也主要是：

• 文件列表
• 文件详情
• 文件下载/预览

5.2 open-canvas 的关键能力

open-canvas 的核心不是“生成文件”，而是“维护一个结构化的当前文档对象”：

• 一个 conversation 对应一个主 artifact
• artifact 具有类型、标题、内容、版本
• 用户可以选中部分内容让 AI 改写
• 每次改写都会生成新版本

5.3 需要新增的核心能力

为支持 Canvas 模式，需要在 DeerFlow 中新增一套结构化 artifact 状态：

• 当前 artifact
• 当前版本索引
• 历史版本列表
• 选区信息
• 当前编辑模式
• 快速动作状态
• Web 搜索结果状态

---

6. 分阶段实施方案

以下为推荐的 8 个阶段，每个阶段都可单独开发、联调和验收。

---

7. 阶段一：前端路由与目录骨架

7.1 目标

在不影响现有页面的前提下，建立 Canvas 模式的前端骨架。

7.2 需求

• 新增 src/open-canvas/ 目录
• 新增 Canvas 页面路由
• 将路由接入 PageRoutes.tsx
• 提供 Canvas 首页和 Canvas Thread 页
• 支持空状态展示

7.3 建议目录

src/open-canvas/
  api/
    threads.ts
    runs.ts
    models.ts
  components/
    layout/
    chat/
    canvas/
    artifacts/
    quick-actions/
    selectors/
  contexts/
    CanvasThreadContext.tsx
    CanvasGraphContext.tsx
    CanvasUIContext.tsx
  hooks/
    useCanvasThread.ts
    useCanvasStream.ts
    useCanvasArtifact.ts
  pages/
    CanvasHomePage.tsx
    CanvasThreadPage.tsx
  routes/
    OpenCanvasRoutes.tsx
  types/
    artifact.ts
    thread.ts
    model.ts
  utils/
    artifact.ts
    selection.ts
    stream.ts
  constants/
    index.ts

7.4 路由建议

• 在 PageRoutes.tsx 中新增 canvas/*
• 在 src/open-canvas/routes/OpenCanvasRoutes.tsx 中维护子路由

建议形式：

/canvas
/canvas/:threadId

7.5 验收标准

• 能访问 Canvas 首页
• 能访问指定 thread 的 Canvas 页面
• 不影响现有 workspace/* 与 strategy/*
• 页面有独立布局骨架

---

8. 阶段二：前端 Canvas 布局与交互容器

8.1 目标

先做出“左聊天、右画布”的基础容器，不接真实 AI 改写逻辑。

8.2 需求

• 左侧聊天区
• 右侧画布区
• 支持面板拖拽或折叠
• 初始空状态
• 支持“快速开始”：
  • 新建空白文本 artifact
  • 新建代码 artifact

8.3 组件拆分建议

• CanvasShell
• CanvasSidebar
• CanvasChatPanel
• CanvasArtifactPanel
• CanvasEmptyState
• QuickStartActions

8.4 快速开始能力

用户进入空线程时可以选择：

• 开始写文章
• 开始写代码
• 从模板开始

首版模板可只做最小集：

• 空白文档
• HTML 模板
• React 组件模板
• Python 脚本模板

8.5 验收标准

• 页面可稳定展示双栏布局
• 快速开始能创建前端本地 artifact 状态
• 代码和文本可分别进入不同渲染器

---

9. 阶段三：结构化 Artifact 数据模型

9.1 目标

定义 DeerFlow 的 Canvas Artifact 协议，作为前后端统一契约。

9.2 核心要求

需要支持以下能力：

• 文本 artifact
• 代码 artifact
• 标题
• 当前版本索引
• 版本历史
• 当前选中版本切换
• 后续支持局部高亮编辑

9.3 建议数据结构

type CanvasArtifact = {
  currentIndex: number;
  contents: Array<CanvasArtifactText | CanvasArtifactCode>;
};

type CanvasArtifactText = {
  index: number;
  type: "text";
  title: string;
  fullMarkdown: string;
};

type CanvasArtifactCode = {
  index: number;
  type: "code";
  title: string;
  language: string;
  code: string;
};

9.4 线程状态建议新增字段

前端与后端需共同支持：

• artifact
• highlighted_text
• highlighted_code
• canvas_mode
• web_search_enabled
• web_search_results
• quick_action_id

9.5 与现有 artifacts: string[] 的关系

建议保留现有 artifacts: string[] 不动。

新增字段：

• artifact 用于 Canvas 主文档
• artifacts 继续用于文件产物

这样可以兼容未来“Canvas 生成网页文件、导出文件、保存文件”的场景。

9.6 验收标准

• 前端类型定义完成
• 后端状态字段设计完成
• 确认与现有线程状态兼容

---

10. 阶段四：后端线程状态与 API 扩展

10.1 目标

让后端线程状态可以安全存储和返回 Canvas Artifact。

10.2 需求

• 扩展 Python ThreadState
• 扩展状态序列化逻辑
• 确保 /api/threads/* 返回结构化 artifact
• 确保 LangGraph 流中可带上 artifact 更新

10.3 后端改造点

建议关注以下模块：

• packages/harness/deerflow/agents/thread_state.py
• 线程 state serializer
• app/gateway/routers/threads.py
• 流事件适配层

10.4 注意事项

• 旧线程没有 artifact 字段时必须兼容
• 状态更新不能破坏现有消息结构
• 必须确保 JSON 可序列化

10.5 验收标准

• 新建线程可写入 artifact
• 读取线程时可返回 artifact
• 不影响现有线程读取
• 前端能从线程 state 中恢复 Canvas 内容

---

11. 阶段五：Canvas 专用 Agent 图

11.1 目标

实现与 open-canvas 类似的 AI 路由能力。

11.2 推荐方案

新增 canvas_agent，单独维护图逻辑。

11.3 节点拆分建议

首版建议至少拆成这些节点：

• route_user_intent
• reply_general_input
• generate_artifact
• rewrite_artifact
• update_highlighted_text
• update_highlighted_code
• generate_followup

二期可加：

• rewrite_artifact_theme
• rewrite_code_theme
• change_length
• change_reading_level
• translate_artifact
• add_comments
• add_logs
• fix_bugs
• port_language
• web_search_enrich

11.4 路由逻辑要求

系统需要能判断：

• 用户是在闲聊
• 用户要新生成 artifact
• 用户要整体重写当前 artifact
• 用户要局部修改当前 artifact
• 用户要执行某个快捷动作

11.5 状态输入要求

节点需要读取：

• 当前消息历史
• 当前 artifact
• 当前选区
• 当前模型配置
• Web 搜索开关

11.6 输出要求

节点输出必须能更新：

• messages
• artifact
• web_search_results
• followup

11.7 验收标准

• 能根据输入创建新 artifact
• 能根据输入整体改写 artifact
• 能保留版本历史
• 能在改写后返回自然语言 followup

---

12. 阶段六：前端流式同步与版本管理

12.1 目标

让前端能像 open-canvas 一样在流式过程中更新画布与聊天。

12.2 需求

• 复用现有 LangGraph stream client
• 在 Canvas 模式中解析 artifact 更新
• 支持流式文本更新
• 支持版本切换
• 支持断线后恢复线程状态

12.3 前端状态层建议

• CanvasThreadContext：线程基础信息
• CanvasGraphContext：消息、artifact、streaming 状态
• CanvasUIContext：面板、编辑态、选中态

12.4 关键能力

• 当前版本切换
• 新版本创建后自动定位到最新版本
• 手动编辑内容后保存
• 流结束后线程状态持久化

12.5 验收标准

• 发送消息时聊天和画布可同步更新
• 版本数会增加
• 切换历史版本稳定
• 刷新页面后线程状态能恢复

---

13. 阶段七：局部选区改写

13.1 目标

实现 Canvas 模式最关键的差异化能力之一：选中局部内容进行 AI 改写。

13.2 文本选区需求

• 支持在 Markdown 文本中选择一段文本
• 记录选区位置与原始文本
• 用户发出修改请求后，仅重写该选区
• 将选区结果合并为新版本 artifact

13.3 代码选区需求

• 支持在代码编辑器中选择一段代码
• 记录 start/end index 或行列信息
• AI 只返回替换片段
• 前端或后端负责将新片段拼接回完整代码

13.4 实现建议

首版建议：

• 文本：前端记录纯文本字符位置
• 代码：使用 CodeMirror selection 信息

不建议首版就做复杂块级富文本局部编辑。

13.5 风险

• Markdown 渲染态与源码态位置映射复杂
• 富文本块级位置难维护
• 流式更新中选区同步容易错位

13.6 首版折中方案

首版文本只基于 fullMarkdown 纯文本改写，不做 BlockNote 富文本块定位。

13.7 验收标准

• 文本局部改写成功
• 代码局部改写成功
• 原内容未改动部分保持不变
• 新版本正确入历史

---

14. 阶段八：快捷动作系统

14.1 目标

实现 open-canvas 风格的快捷动作体系。

14.2 首批推荐动作

文本类：

• 扩写
• 精简
• 改正式语气
• 改口语语气
• 改阅读难度
• 翻译

代码类：

• 加注释
• 加日志
• 修复 bug
• 优化代码
• 转换语言

14.3 设计方式

快捷动作不要直接写死在 UI，建议配置化：

• id
• label
• type
• applicable_to
• prompt_template

14.4 后端设计

快捷动作可通过：

• 前端传 quick_action_id
• 后端路由节点根据动作 id 选择 prompt

14.5 验收标准

• 文本动作可执行
• 代码动作可执行
• 结果进入新版本
• 不同动作提示词可扩展

---

15. 阶段九：模型配置统一与本地模型支持

15.1 目标

让 Canvas 模式支持和主系统统一的模型选择，并且能自由配置本地大模型。

15.2 原则

• 后端 config.yaml 为真源
• 前端只展示后端暴露的模型信息
• 不维护一份脱离后端的前端常量模型表

15.3 本地模型支持范围

建议优先支持两类：

• Ollama
• OpenAI-compatible 本地服务
  • LM Studio
  • vLLM
  • LocalAI
  • one-api 风格代理

15.4 后端配置建议

后端模型配置应至少支持：

• name
• display_name
• use
• model
• api_key
• base_url
• supports_vision
• supports_thinking
• supports_tool_calling
• is_local
• canvas_capabilities

15.5 Canvas 模式额外要求

由于不是所有模型都适合 Canvas 改写任务，建议增加能力标识：

• supports_canvas_generation
• supports_canvas_rewrite
• supports_canvas_code_edit
• supports_streaming_text
• supports_streaming_tool_calls

15.6 与 open-canvas 的关系

可以借鉴其命名习惯和能力分层，但不建议直接依赖其 packages/shared/src/models.ts 作为配置源。

15.7 验收标准

• 前端模型选择器可显示后端返回模型
• 可切换本地模型
• Canvas 模式能用本地模型生成和改写

---

16. 阶段十：Web 搜索增强

16.1 目标

实现类似 open-canvas 的可选 Web 搜索增强。

16.2 需求

• UI 提供 Web 搜索开关
• 后端在需要时走搜索节点
• 搜索结果写入线程状态
• 结果可在画布旁侧栏展示

16.3 首版建议

只做：

• 开关
• 搜索结果列表
• 搜索结果用于生成 artifact

暂不做复杂网页抓取编辑链路。

16.4 验收标准

• 打开搜索后可返回搜索结果
• 搜索结果可参与 artifact 生成
• 结果展示不阻塞主画布

---

17. 阶段十一：持久化、导出与文件产物联动

17.1 目标

让 Canvas 文档与 DeerFlow 原有文件能力协同。

17.2 需求

• artifact 持久化在线程 state 中
• 可手动导出为文件
• 可生成真实 HTML/Markdown/代码文件到现有 outputs
• Canvas artifact 与 artifacts: string[] 可双向关联

17.3 推荐能力

• 导出 Markdown
• 导出代码文件
• 另存为 artifact file
• 从 artifact file 回填到 Canvas

17.4 验收标准

• 当前版本可导出
• 导出文件可在现有文件面板查看
• 文件型 artifact 和 Canvas artifact 能共存

---

18. 推荐开发顺序

建议严格按以下顺序推进：

1. 路由和目录骨架
2. Canvas 页面布局
3. 前端 artifact 数据模型
4. 后端线程状态扩展
5. 新建 Canvas Agent 图
6. 前后端流式同步
7. 整体生成与整体改写
8. 局部选区改写
9. 快捷动作
10. 本地模型支持完善
11. Web 搜索增强
12. 导出与文件联动

不要先做局部改写和快捷动作，否则前面的状态与路由契约不稳定，返工会很多。

---

19. 里程碑定义

M1：页面可进入

• 路由接通
• 双栏布局完成
• 本地 mock artifact 可渲染

M2：后端状态打通

• 线程可保存结构化 artifact
• 页面刷新后能恢复

M3：AI 生成可用

• 可新建文本/代码 artifact
• 可整体改写
• 可产生版本历史

M4：核心体验可用

• 选区改写可用
• 快捷动作可用
• 模型切换可用

M5：增强能力完整

• 本地模型支持完善
• Web 搜索增强
• 导出和文件联动

---

20. 风险与难点

20.1 最大难点

• 结构化 artifact 状态从无到有
• 局部选区改写的精确性
• 流式状态与版本管理的一致性
• 不破坏现有 DeerFlow 文件型 artifact 体系

20.2 技术风险

• 线程 state JSON 结构过大
• 大模型对局部改写指令遵循不稳定
• 本地模型 tool calling 与流式能力差异大
• 文本渲染态与源码态位置映射复杂

20.3 规避建议

• 首版只支持 Markdown 源码态编辑，不做复杂富文本编辑
• 首版只支持文本和代码两种 artifact 类型
• 首版先做整体生成和整体改写，再做局部改写
• 本地模型先支持“能生成、能重写”的最小能力，不强求与顶级闭源模型完全同效

---

21. 验收总清单

21.1 前端

• 有独立 Canvas 路由
• 有专用目录和模块边界
• 双栏布局可用
• 文本和代码两类 artifact 可渲染
• 历史版本可切换
• 选区改写可交互
• 快捷动作可触发
• 模型可切换

21.2 后端

• 线程状态支持 artifact
• 新增 canvas_agent 或等价模式
• 生成、重写、局部改写可用
• 流式返回稳定
• 模型列表接口支持 Canvas 能力元数据

21.3 本地模型

• 可配置 Ollama
• 可配置 OpenAI-compatible 本地服务
• 前端可见并可切换
• 至少能完成文本生成和整体改写

---

22. 推荐首版最小可交付范围

如果要控制风险，建议首版只交付以下内容：

• 新增 canvas/* 路由
• 双栏布局
• 结构化 artifact
• canvas_agent
• 文本/代码 artifact 新建
• 整体生成
• 整体改写
• 历史版本切换
• 后端模型动态加载
• Ollama 或本地 OpenAI-compatible 至少一种可用

先不要把以下内容放进首版强制目标：

• 富文本块级精确编辑
• 全量快捷动作
• 复杂 Web 搜索增强
• 多 artifact 并行管理

---

23. 后续实施建议

建议下一步基于本文档继续输出两份落地文档：

23.1 前端实施清单

逐文件列出：

• 要新建哪些文件
• 哪些组件可复用
• 哪些页面要接入路由
• 哪些状态要从现有 hooks 抽离

23.2 后端实施清单

逐模块列出：

• 要改哪些 Python 文件
• 新增哪些状态字段
• 新增哪些 Agent 节点
• 哪些 API 需要扩展

---

24. 结论

这个需求很大，但完全可拆。

正确做法不是“先抄 UI”，而是按下面的主线推进：

• 先建前端 Canvas 子系统
• 再建结构化 artifact 状态
• 再建 Canvas Agent 图
• 再补局部改写和快捷动作
• 最后统一本地模型能力

只要按本文档阶段推进，这个需求是可以落地的，而且能和你现在的 DeerFlow 架构保持长期兼容。