951 lines
20 KiB
Markdown
951 lines
20 KiB
Markdown
# 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](../src/pages/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` 下新增一个专用目录，例如：
|
||
|
||
```text
|
||
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](../src/pages/PageRoutes.tsx)
|
||
- 提供 Canvas 首页和 Canvas Thread 页
|
||
- 支持空状态展示
|
||
|
||
### 7.3 建议目录
|
||
|
||
```text
|
||
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` 中维护子路由
|
||
|
||
建议形式：
|
||
|
||
```text
|
||
/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 建议数据结构
|
||
|
||
```ts
|
||
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 架构保持长期兼容。
|