wsk/deerflow-code
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
xuhd-ce
deerflow-code/frontend-web/docs/openCanvas-backend-checklist.md
T
fengxiangdebaozi a0d04cba50 文档修改
2026-05-15 10:42:44 +08:00

1032 lines
19 KiB
Markdown
Raw Permalink Blame History

# Open Canvas 后端实施清单
## 1. 文档目标
本文档是 [openCanvas.md](./openCanvas.md) 的后端落地版清单。
目标是把 Canvas 模式在当前 DeerFlow 后端中的实施工作拆成可以直接排期和执行的任务，覆盖：
- 线程状态扩展
- `canvas_agent` 设计
- LangGraph 节点拆分
- Gateway API 扩展
- 流式输出契约
- 模型配置与本地模型支持
- 结构化 artifact 的持久化
- 测试与验收顺序
本文档默认前端会新增独立的 Canvas 子系统，并通过现有 LangGraph 线程和 Gateway API 与后端通信。
---
## 2. 实施原则
### 2.1 总原则
- 不破坏现有 `lead_agent`
- 不破坏现有 `artifacts: list[str]` 文件产物体系
- 优先增量扩展，不做推倒重构
- 先打通状态和协议，再实现复杂 AI 行为
- 先支持文本/代码双类型，再逐步扩展快捷动作
### 2.2 推荐路线
推荐采用“新增独立 `canvas_agent`”方案，而不是把所有 Canvas 行为塞进现有 `lead_agent`。
推荐原因：
- 风险更低
- 图逻辑更清晰
- 更容易对齐 open-canvas 的状态结构
- 不影响现有 DeerFlow 普通聊天与文件产物模式
### 2.3 后端目标边界
本次后端实施重点是：
- 新增 Canvas 专用线程状态字段
- 新增 Canvas Agent 图
- 新增前端需要的模型能力元数据
- 支持结构化 artifact 在线程状态中读写
本次不要求：
- 完整复刻 open-canvas 的所有 TS 图结构
- 完整复刻 Supabase 相关逻辑
- 把所有模型 provider 完全抽象成统一能力中台
---
## 3. 现有后端基础能力盘点
当前 DeerFlow 后端已经具备非常好的基础设施：
- LangGraph 线程与流式交互
- FastAPI Gateway
- 模型动态配置
- 本地线程状态管理
- Sandbox/工具体系
- 上传与文件 artifact 访问
- Memory 与标题生成
因此 Canvas 模式并不是“从 0 开始做 Agent 平台”，而是“在现有平台上新增一类结构化创作模式”。
---
## 4. 目标代码落点
建议优先关注以下目录：
```text
offline-backend-20260512/backend/
app/gateway/
routers/
deps.py
app.py
packages/harness/deerflow/
agents/
factory.py
thread_state.py
lead_agent/
middlewares/
runtime/
config/
tools/
```
建议为 Canvas 新增或扩展以下区域：
```text
packages/harness/deerflow/
agents/
canvas_agent/
__init__.py
agent.py
prompt.py
state.py
nodes/
route_user_intent.py
generate_artifact.py
rewrite_artifact.py
update_highlighted_text.py
update_highlighted_code.py
generate_followup.py
quick_actions.py
web_search.py
```
如果不想把节点拆得太细，首版也可以把部分逻辑先收在 `agent.py` 里，但建议至少把 `state.py` 和 `prompt.py` 独立出来。
---
## 5. 开发阶段总览
后端建议分为 11 个阶段：
1. 线程状态扩展
2. 结构化 artifact 协议定义
3. `canvas_agent` 接入到 Agent 工厂
4. Canvas 图的最小节点实现
5. Gateway/线程接口兼容
6. 流式状态输出适配
7. 模型能力元数据扩展
8. 本地模型兼容与配置统一
9. 快捷动作与局部改写
10. Web 搜索增强
11. 测试、回归、验收
---
## 6. 阶段一：线程状态扩展
### 6.1 任务目标
让 DeerFlow 的线程状态能原生保存 Canvas 所需的结构化信息。
### 6.2 任务清单
- 扩展 [thread_state.py](../../offline-backend-20260512/backend/packages/harness/deerflow/agents/thread_state.py)
- 定义 Canvas 相关 TypedDict 或 dataclass 结构
- 确保状态字段可序列化
- 不影响现有 `messages/title/artifacts/todos` 逻辑
### 6.3 建议新增字段
在现有 `ThreadState` 上新增：
- `artifact`
- `highlighted_text`
- `highlighted_code`
- `canvas_mode`
- `quick_action_id`
- `web_search_enabled`
- `web_search_results`
### 6.4 建议数据形态
可先采用 JSON-safe dict 结构，而不是在状态层引入过重的复杂对象。
建议：
```python
class CanvasArtifactText(TypedDict):
index: int
type: Literal["text"]
title: str
fullMarkdown: str
class CanvasArtifactCode(TypedDict):
index: int
type: Literal["code"]
title: str
language: str
code: str
class CanvasArtifact(TypedDict):
currentIndex: int
contents: list[CanvasArtifactText | CanvasArtifactCode]
```
### 6.5 与现有 `artifacts` 的关系
必须保留现有：
- `artifacts: list[str]`
新增：
- `artifact: dict | None`
含义区分：
- `artifacts` 表示文件型产物列表
- `artifact` 表示 Canvas 当前主文档
### 6.6 验收标准
- 旧线程无 `artifact` 时不报错
- 新线程可写入 `artifact`
- 线程状态能被 FastAPI 和 LangGraph 正确序列化
---
## 7. 阶段二：结构化 Artifact 协议定义
### 7.1 任务目标
统一前后端对 Canvas artifact 的字段约定。
### 7.2 任务清单
- 在后端建立一份明确的 artifact 协议定义
- 明确字段命名、类型、兼容策略
- 明确版本管理规则
### 7.3 协议要求
必须支持：
- 文本 artifact
- 代码 artifact
- 标题
- 当前版本索引
- 历史版本列表
- 后续支持局部改写
### 7.4 版本规则
- 每次 AI 整体生成，生成 `contents[0]`
- 每次 AI 重写，追加一个新版本
- `currentIndex` 指向当前版本
- 历史版本默认只保留在线程状态中，不额外落库
### 7.5 建议约束
- `index` 从 1 开始
- `currentIndex` 必须落在 `contents` 范围内
- `type` 只允许 `"text"` 或 `"code"`
### 7.6 验收标准
- 前后端字段完全一致
- 状态协议有明确默认值和边界规则
---
## 8. 阶段三：接入 `canvas_agent`
### 8.1 任务目标
在现有 Agent 体系中注册一个独立的 Canvas Agent。
### 8.2 任务清单
- 新建 `packages/harness/deerflow/agents/canvas_agent/`
- 新建 `agent.py`
- 新建 `prompt.py`
- 新建 `state.py`
- 修改 [factory.py](../../offline-backend-20260512/backend/packages/harness/deerflow/agents/factory.py)
### 8.3 注册方式建议
建议将 `canvas_agent` 作为一个显式 assistant id 暴露给 LangGraph 运行时。
前端调用时：
- `assistant_id=canvas_agent`
### 8.4 Agent 设计原则
- Canvas Agent 不负责 DeerFlow 全部工具生态
- 首版专注于：
- 生成文档
- 重写文档
- 局部改写
- 跟进回复
### 8.5 工具策略
首版建议：
- 不强依赖 shell/sandbox
- 不强依赖 present_files
- 先把生成与改写链路做好
后续可以根据需要接入文件导出能力。
### 8.6 验收标准
- `canvas_agent` 可被识别
- 前端能以 assistant id 调用它
- 不影响 `lead_agent`
---
## 9. 阶段四：Canvas 状态与图定义
### 9.1 任务目标
为 Canvas Agent 定义清晰、最小但可扩展的状态结构。
### 9.2 任务清单
- 新建 `canvas_agent/state.py`
- 定义图状态
- 约束与 `ThreadState` 的映射方式
### 9.3 建议状态字段
- `messages`
- `_messages` 或等价内部消息
- `artifact`
- `highlighted_text`
- `highlighted_code`
- `quick_action_id`
- `web_search_enabled`
- `web_search_results`
- `next`
### 9.4 状态设计建议
优先复用 LangGraph 原生消息 reducer。
对结构化字段，尽量采用：
- 可整体替换
- 易序列化
- 无 Python 特殊对象依赖
### 9.5 验收标准
- 状态能驱动 Canvas 节点运行
- 状态可被序列化回线程
---
## 10. 阶段五：Canvas 图最小节点闭环
### 10.1 任务目标
先实现最小闭环，不要一开始就追求 open-canvas 全量功能。
### 10.2 首版最小节点
建议至少实现：
- `route_user_intent`
- `reply_general_input`
- `generate_artifact`
- `rewrite_artifact`
- `generate_followup`
### 10.3 节点职责
#### `route_user_intent`
判断用户当前意图：
- 普通聊天
- 新建 artifact
- 重写当前 artifact
#### `reply_general_input`
仅返回普通消息，不更新 artifact。
#### `generate_artifact`
根据用户需求生成第一版 artifact。
#### `rewrite_artifact`
根据当前 artifact 和用户请求生成新版本。
#### `generate_followup`
在 artifact 更新后补一条自然语言消息。
### 10.4 输出要求
必须至少更新：
- `messages`
- `artifact`
### 10.5 验收标准
- 无 artifact 时能生成新 artifact
- 有 artifact 时能整体重写
- 重写后版本数增加
---
## 11. 阶段六：Prompt 设计与模型调用封装
### 11.1 任务目标
把 Canvas 模式的 prompt 和模型调用逻辑集中管理。
### 11.2 任务清单
- 在 `canvas_agent/prompt.py` 中集中定义 prompt 常量
- 在 `canvas_agent/agent.py` 或节点工具模块中封装模型调用
### 11.3 最少需要的 prompt
- 新建 artifact prompt
- 整体重写 artifact prompt
- 路由判断 prompt
- followup prompt
### 11.4 设计建议
提示词必须显式约束：
- 输出完整文档还是局部片段
- 是否允许修改类型
- 是否允许修改标题
- 对文本和代码的输出格式要求
### 11.5 模型调用封装建议
不要在每个节点里重复拼模型配置。
建议提供统一函数：
- `get_canvas_model(...)`
- `invoke_canvas_model(...)`
### 11.6 验收标准
- prompt 集中管理
- 节点中模型调用逻辑可复用
---
## 12. 阶段七：Gateway 线程接口兼容
### 12.1 任务目标
让前端读取线程状态时能拿到结构化 `artifact`。
### 12.2 任务清单
- 检查 [threads.py](../../offline-backend-20260512/backend/app/gateway/routers/threads.py)
- 扩展线程 state 响应的 `values`
- 确保 `artifact` 字段会被安全返回
### 12.3 要求
- `GET /api/threads/{id}`
- 线程历史
- 状态读取接口
都要兼容 `artifact`
### 12.4 注意事项
- 历史 checkpoint 可能没有 `artifact`
- 旧线程必须兼容
- 结构化字段不能被错误裁剪
### 12.5 验收标准
- 前端取线程时能拿到 `artifact`
- 刷新页面后 Canvas 内容能恢复
---
## 13. 阶段八：流式输出适配
### 13.1 任务目标
让 Canvas 模式的 artifact 能通过 LangGraph 流实时更新。
### 13.2 任务清单
- 检查运行时序列化逻辑
- 确保 `artifact` 在流事件中可见
- 明确前端消费 `values` 还是 `updates`
### 13.3 输出建议
首版允许采用较简单策略：
- 每次节点完成后输出完整 `artifact`
不强制首版做精细的 token 级 artifact 局部流。
### 13.4 原因
完整对象覆盖更新：
- 容易实现
- 容易调试
- 前后端一致性更好
### 13.5 二期方向
后续再考虑：
- 局部 chunk 更新
- 文本与代码差异化流式拼接
### 13.6 验收标准
- 前端发送请求时，artifact 能跟随 run 更新
- 流结束后状态与线程最终值一致
---
## 14. 阶段九：模型接口扩展
### 14.1 任务目标
让前端能拿到适合 Canvas 模式的模型能力信息。
### 14.2 任务清单
- 扩展 [models.py](../../offline-backend-20260512/backend/app/gateway/routers/models.py)
- 扩展模型响应结构
### 14.3 现有字段之外建议新增
- `provider`
- `supports_vision`
- `supports_tool_calling`
- `supports_canvas_generation`
- `supports_canvas_rewrite`
- `supports_canvas_code_edit`
- `supports_streaming_text`
- `supports_streaming_tool_calls`
- `is_local`
- `base_url`
### 14.4 注意事项
不是所有字段都必须从配置文件显式写出。
可以采用：
- 配置直出
- provider 推断
- 默认值补齐
### 14.5 验收标准
- 前端模型选择器能获取足够元数据
- 本地模型和云模型能区分
---
## 15. 阶段十：本地模型支持与配置统一
### 15.1 任务目标
支持像 open-canvas 一样自由配置本地模型，但配置真源在 DeerFlow。
### 15.2 原则
- 以 `config.yaml` 为唯一真源
- 前端不依赖 open-canvas 的 TS 模型表
- 后端负责把配置转换成前端可消费的能力描述
### 15.3 首批支持范围
推荐先支持：
- Ollama
- OpenAI-compatible 本地服务
例如：
- LM Studio
- vLLM
- LocalAI
- One API/OpenAI 兼容代理
### 15.4 配置要求
建议模型配置支持以下字段：
- `name`
- `display_name`
- `use`
- `model`
- `api_key`
- `base_url`
- `supports_vision`
- `supports_thinking`
- `supports_reasoning_effort`
- `supports_tool_calling`
- `is_local`
### 15.5 Canvas 额外能力字段
建议再增加：
- `supports_canvas_generation`
- `supports_canvas_rewrite`
- `supports_canvas_code_edit`
### 15.6 验收标准
- 配置本地模型后 `/api/models` 可见
- `canvas_agent` 可调用本地模型
- 至少文本生成和整体改写可用
---
## 16. 阶段十一：整体重写节点完善
### 16.1 任务目标
让已有 artifact 能被稳定整体重写并产生新版本。
### 16.2 任务清单
- 实现 `rewrite_artifact`
- 明确文本与代码两种重写路径
- 维护标题和类型变更规则
### 16.3 规则建议
- 默认保持当前类型
- 用户明确要求时才允许改类型
- 默认保持标题
- 用户明确换主题时可更新标题
### 16.4 结果写入规则
- 新版本追加到 `contents`
- `currentIndex` 指向新版本
### 16.5 验收标准
- 文本 artifact 整体重写正常
- 代码 artifact 整体重写正常
- 历史版本保留
---
## 17. 阶段十二：局部改写节点
### 17.1 任务目标
支持文本和代码的局部选区修改。
### 17.2 任务清单
- 新增 `update_highlighted_text.py`
- 新增 `update_highlighted_code.py`
- 在状态中消费选区信息
### 17.3 文本局部改写要求
输入：
- 当前 `fullMarkdown`
- 选区起止
- 选中原文
- 用户修改指令
输出：
- 只返回替换片段或返回完整合并后文本
### 17.4 首版建议
首版优先采用“后端返回完整合并后文本”策略。
原因：
- 前端逻辑更轻
- 状态更一致
### 17.5 代码局部改写要求
输入：
- 当前代码全文
- 选区代码片段
- 选区边界
- 用户修改指令
输出：
- 新的完整代码文本
### 17.6 验收标准
- 文本局部改写成功
- 代码局部改写成功
- 未选中区域不被误改
---
## 18. 阶段十三：快捷动作节点
### 18.1 任务目标
支持前端动作栏触发不同的重写行为。
### 18.2 任务清单
- 新增 `quick_actions.py`
- 定义动作 id 到 prompt 的映射
- 在路由节点中识别 `quick_action_id`
### 18.3 首版动作建议
文本：
- `expand`
- `shorten`
- `formalize`
- `casualize`
代码：
- `add_comments`
- `add_logs`
- `fix_bugs`
### 18.4 实现建议
动作不要散落在各节点里硬编码。
建议集中成映射表：
- `action_id -> prompt builder`
### 18.5 验收标准
- 指定动作可触发不同结果
- 动作执行后生成新版本
---
## 19. 阶段十四：Web 搜索增强
### 19.1 任务目标
支持 Canvas 模式在需要时引入搜索结果。
### 19.2 任务清单
- 新增 `web_search.py`
- 消费 `web_search_enabled`
- 将搜索结果写入 `web_search_results`
### 19.3 首版策略
首版只做：
- 打开开关后，生成/重写前先搜索
- 把结果摘要注入 prompt
先不做复杂页面抓取多轮链路。
### 19.4 验收标准
- 开关打开时能引入搜索结果
- 结果可回传前端展示
---
## 20. 阶段十五：线程创建与 metadata 策略
### 20.1 任务目标
让 Canvas 线程在创建和恢复时保留必要上下文。
### 20.2 任务清单
- 约定前端创建 Canvas thread 时写入 metadata
- 后端在 thread search / get 中保留这些 metadata
### 20.3 推荐 metadata
- `ui_mode: "canvas"`
- `agent_id: "canvas_agent"`
- `model_name`
- `canvas_type` 可选
### 20.4 验收标准
- Canvas thread 与普通 thread 可区分
- 恢复线程时前端可据 metadata 恢复 UI
---
## 21. 阶段十六：Gateway 扩展接口评估
### 21.1 任务目标
判断是否需要新增 Canvas 专用 REST API。
### 21.2 原则
能复用现有线程状态与 LangGraph 流，就不要新增太多新接口。
### 21.3 可以先不新增的接口
- Canvas artifact 专用 CRUD
- Canvas 快捷动作专用接口
这些都可以先通过：
- 线程 state
- runs.stream
完成。
### 21.4 可能需要新增的接口
二期如果需要，可增加：
- `GET /api/canvas/models`
- `POST /api/canvas/export`
- `POST /api/canvas/convert-to-file`
### 21.5 验收标准
- 首版尽量少增接口
- 协议尽量复用现有线程与 run 模型
---
## 22. 阶段十七：持久化与导出联动
### 22.1 任务目标
让 Canvas 文档能和现有文件 artifact 体系联动。
### 22.2 任务清单
- 规划导出接口
- 规划 artifact 转文件逻辑
- 规划从 Canvas 生成 outputs 文件
### 22.3 推荐能力
- 保存为 `.md`
- 保存为代码文件
- 将导出文件加入现有 `artifacts: list[str]`
### 22.4 首版建议
这部分不是最早阶段必须做的。
建议等核心 Canvas 生成与重写稳定后再接。
### 22.5 验收标准
- 导出文件能出现在现有 artifact 文件体系中
---
## 23. 测试清单
### 23.1 单元测试建议
优先覆盖：
- artifact 协议校验
- 版本追加逻辑
- 标题/类型变更规则
- 文本局部改写拼接逻辑
- 代码局部改写拼接逻辑
### 23.2 集成测试建议
应覆盖：
- 创建 Canvas thread
- 首次生成 artifact
- 整体重写
- 局部改写
- 模型切换
- 本地模型调用
### 23.3 回归测试重点
重点检查现有功能未被破坏：
- 普通 `lead_agent` 对话
- 文件型 `artifacts`
- uploads
- memory
- scheduled tasks
### 23.4 验收标准
- Canvas 新功能通过
- 现有 DeerFlow 核心路径无回归
---
## 24. 推荐开发顺序
强烈建议按以下顺序推进：
1. 线程状态扩展
2. artifact 协议定稿
3. `canvas_agent` 注册
4. 最小图闭环
5. 线程读取与流式返回
6. 模型接口扩展
7. 整体生成与整体改写
8. 局部改写
9. 快捷动作
10. 本地模型增强
11. Web 搜索增强
12. 导出联动
不要一开始就做：
- 快捷动作全集
- 局部 token 级流式 artifact 更新
- 复杂导出体系
---
## 25. 多人协作拆分建议
### A 组：状态与线程
- `thread_state.py`
- 线程协议
- Gateway 线程兼容
### B 组：Canvas Agent 图
- `canvas_agent`
- prompt
- route/generate/rewrite/followup
### C 组：模型与配置
- `/api/models`
- 本地模型配置
- provider 兼容
### D 组：增强能力
- 局部改写
- 快捷动作
- Web 搜索
---
## 26. 首版最小可交付范围
后端首版建议只交付这些：
- 扩展线程状态支持 `artifact`
- 新增 `canvas_agent`
- 支持文本/代码 artifact 首次生成
- 支持整体重写
- 支持版本历史
- 扩展 `/api/models` 返回 Canvas 能力元数据
- 支持至少一种本地模型接入
首版先不强制：
- 局部高亮改写
- 全量快捷动作
- 搜索增强
- 导出文件联动
---
## 27. 总验收标准
### 27.1 功能层
- 无 artifact 时可生成新文档
- 有 artifact 时可整体重写
- 版本历史可保留
- 前端刷新后可恢复
### 27.2 协议层
- `artifact` 字段稳定
- 流式与最终线程状态一致
- 模型能力字段可用于前端判断
### 27.3 兼容层
- 不破坏 `lead_agent`
- 不破坏现有 `artifacts: list[str]`
- 不破坏现有 Gateway 核心接口
---
## 28. 下一步建议
完成本文档后，建议继续补两份工程文档：
### 28.1 Canvas 状态协议文档
明确：
- `artifact`
- `highlighted_text`
- `highlighted_code`
- `quick_action_id`
- `web_search_results`
的最终 JSON 格式。
### 28.2 Canvas Agent 节点接口文档
逐节点定义：
- 输入字段
- 输出字段
- prompt 责任
- 错误处理
这样进入实际编码时会更顺畅。
Reference in new issue View Git Blame Copy Permalink