wsk/deerflow-code

0 Fork 0

Files

T

fengxiangdebaozi 5c553aae19 文档更新

2026-05-18 09:58:34 +08:00

11 KiB

Raw Permalink Blame History

AI 写作前端改造清单

1. 目标

在不新增第二套页面的前提下，基于现有 open-canvas 页面，把左侧从“单轮聊天输入框”升级为“多 Agent 写作工作台”，右侧继续沿用当前 artifact 编辑与流式预览能力。

当前核心文件：

2. 改造原则

不改右侧主编辑器交互心智
不复制新页面
不破坏现有普通 chat 模式
新增“写作工作流模式”时尽量以增量状态字段和新组件完成
所有 workflow 能力都应允许逐步灰度

3. 推荐前端结构

建议在 frontend-web/src/open-canvas 下新增以下目录：

frontend-web/src/open-canvas/
  workflow/
    api/
      writing-workflow.ts
    components/
      WritingWorkflowEntryForm.tsx
      WritingWorkflowTimeline.tsx
      WritingWorkflowEventList.tsx
      WritingWorkflowArtifactDrawer.tsx
      WritingWorkflowConfirmCard.tsx
      WritingWorkflowHeader.tsx
    contexts/
      WritingWorkflowContext.tsx
    hooks/
      useWritingWorkflow.ts
      useWritingWorkflowEvents.ts
    types/
      workflow.ts
    utils/
      workflow-event.ts

说明：

open-canvas 原有聊天、artifact、editor 目录不重构
以 workflow/ 作为新能力边界，减少对既有文件的侵入

4. 状态设计

4.1 新增的核心状态

建议新增：

workflowMode: "chat" | "writing_pipeline"
workflowRunId: string | null
workflowStage
workflowStatus: "idle" | "running" | "waiting_user" | "completed" | "failed"
workflowEvents: WritingWorkflowEvent[]
workflowArtifacts: WritingWorkflowArtifact[]
workflowPendingAction: WritingPendingAction | null

4.2 推荐类型定义

建议在 workflow/types/workflow.ts 中先定义：

export type WritingWorkflowStage =
  | "idle"
  | "collecting_materials"
  | "generating_outline"
  | "await_outline_confirmation"
  | "writing_draft"
  | "reviewing_draft"
  | "rewriting_draft"
  | "completed"
  | "failed";

export type WritingWorkflowEventType =
  | "workflow_started"
  | "stage_changed"
  | "agent_started"
  | "agent_output_chunk"
  | "artifact_generated"
  | "human_confirmation_required"
  | "retry_scheduled"
  | "workflow_completed"
  | "workflow_failed";

第一版把类型先收紧，后续再扩展。

5. 组件拆分建议

5.1 左侧主面板改造

当前 CanvasChatPanel 建议只承担“模式路由”和布局容器职责，不继续无限堆逻辑。

建议改造为：

chat 模式继续渲染现有消息列表 + 输入框
writing_pipeline 模式渲染新的工作流视图

建议拆分出：

CanvasChatConversation.tsx
CanvasChatInputBox.tsx
CanvasWorkflowPanel.tsx

这样后续不会把 CanvasChatPanel.tsx 变成一个过大的组件。

5.2 新增组件职责

`WritingWorkflowEntryForm.tsx`

负责采集：

主题
文章类型
目标读者
语气风格
目标篇幅
是否需要引用资料
禁写项
补充说明

`WritingWorkflowTimeline.tsx`

负责显示阶段：

研究中
提纲生成中
等待确认提纲
正在写初稿
正在审稿
正在重写
已完成

`WritingWorkflowEventList.tsx`

负责显示细粒度事件：

哪个 Agent 开始执行
当前在处理哪一步
当前产生了什么中间结果
是否重试

`WritingWorkflowArtifactDrawer.tsx`

负责展示中间产物：

素材卡片
提纲
初稿
编辑意见
重写稿

`WritingWorkflowConfirmCard.tsx`

负责展示用户确认点：

确认提纲
驳回提纲并附带修改意见
继续写稿
指定重写章节

6. Context 与 Hook 改造建议

6.1 `CanvasGraphContext`

当前它只维护：

messages
artifact
streamingArtifact
isStreaming

建议不要把 workflow 状态直接塞进现有 CanvasGraphContext，否则会让语义过重。

推荐做法：

保留 CanvasGraphContext 继续服务右侧 artifact 和通用流式状态
新增 WritingWorkflowContext

6.2 `WritingWorkflowContext`

建议承载：

当前 workflow 运行状态
中间产物列表
待确认操作
workflow 事件缓存
启动 / 取消 / 确认 / 重写等 action

6.3 `useCanvasThreadStream`

当前这个 hook 已经负责：

创建 thread
提交消息
接收 thread stream
将 update_artifact 同步到右侧

建议不要把“多 Agent workflow 状态机”也硬塞进去。

推荐方案：

保留 useCanvasThreadStream 给普通 chat 或兼容旧能力使用
新增 useWritingWorkflow
新增 useWritingWorkflowEvents

分工如下：

useCanvasThreadStream：普通对话流
useWritingWorkflow：创建 workflow、提交表单、触发确认动作
useWritingWorkflowEvents：订阅 workflow 事件流

7. API 接入建议

7.1 前端 API 文件

新增：

workflow/api/writing-workflow.ts

建议暴露方法：

createWorkflow(payload)
startWorkflow(id)
getWorkflow(id)
subscribeWorkflowEvents(id, handlers)
confirmOutline(id, payload)
rewriteSection(id, payload)
approveFinal(id)

7.2 事件流形式

优先级建议：

SSE
流式 HTTP chunk
轮询兜底

理由：

事件驱动比整段消息流更适合 workflow UI
可以更方便映射到时间线和事件列表

8. 与右侧 Artifact 的衔接

8.1 现有优势

当前 CanvasArtifactPanel 已具备：

流式展示内容
最终 artifact 渲染
右侧编辑体验成熟

这意味着多 Agent 工作流不需要再做第二套文章渲染，只要把最终阶段结果推成 artifact 即可。

8.2 建议接法

工作流各阶段结果按两类处理：

中间产物：进入左侧 workflowArtifacts
可阅读正文：同步一份到右侧 artifact

推荐映射：

提纲：可选同步到右侧，供用户预览
初稿：同步到右侧
重写稿：覆盖或新增版本到右侧
终稿：作为最终右侧主版本

8.3 版本策略

建议右侧版本保留：

outline
draft_v1
draft_v2
final

如果现有 artifact 数据结构不方便承载完整版本树，第一版可先保留在 workflowArtifacts 中，右侧只展示当前激活版本。

9. 页面交互流程

9.1 用户首次进入

默认仍是现有 chat 模式
在左侧增加一个显眼切换入口：普通对话 / 写作工作流

9.2 启动写作工作流

用户填写写作任务表单
点击“开始生成”
左侧切换到时间线 + 事件流视图
右侧进入 loading 或素材 / 提纲预览态

9.3 等待提纲确认

时间线停在 await_outline_confirmation
左侧出现确认卡片
用户可执行：
- 通过提纲
- 要求调整提纲
- 追加要求

9.4 生成初稿与审稿

左侧显示 Agent 事件
右侧展示初稿内容
审稿意见在左侧展示，同时高亮需要重写的章节

9.5 完成

左侧显示“终稿已完成”
右侧进入可继续局部 AI 编辑状态

10. 分步开发清单

Step 1：类型与假数据

目标：

先把 workflow 的类型、mock 数据、组件骨架搭好

任务：

新建 workflow/types/workflow.ts
新建 workflow/components/*
用本地 mock 事件驱动时间线和事件流

验收：

不接后端也能在页面中演示完整流程

Step 2：模式切换

目标：

在 CanvasChatPanel 中接入 chat / writing_pipeline 双模式

任务：

拆出 CanvasWorkflowPanel
增加模式切换 UI
保证旧 chat 不回归

验收：

现有功能不受影响
新模式可进入表单页

Step 3：接入 workflow API

目标：

从 mock 切到真实 API

任务：

接 create/start/get/events
实现基础错误态和重试态

验收：

前后端可联调跑一条主链路

Step 4：接入确认节点

目标：

支持提纲确认和指定章节重写

任务：

做确认卡片
做动作回传

验收：

用户能在流程中介入

Step 5：打通右侧版本

目标：

让 workflow 产物稳定进入右侧编辑器

任务：

约定 artifact 映射
接入版本切换或当前版本覆盖

验收：

终稿稳定显示在右侧

11. 建议修改点位

优先涉及文件：

建议新增，不建议重写原有：

open-canvas/workflow/api/writing-workflow.ts
open-canvas/workflow/contexts/WritingWorkflowContext.tsx
open-canvas/workflow/hooks/useWritingWorkflow.ts
open-canvas/workflow/hooks/useWritingWorkflowEvents.ts
open-canvas/workflow/components/*

12. 联调约定

前后端需要尽早统一：

workflow id 命名
stage 枚举
event type 枚举
artifact type 枚举
user action payload
错误码与可恢复动作

建议先由前端与后端共同确认一份 workflow.ts 契约文档，再开工。

13. 最终建议

前端最重要的不是“把 Agent 结果展示出来”，而是把“工作流过程可视化并允许人工介入”做清楚。

第一版建议先保证三件事：

左侧能看见阶段进展
用户能确认提纲
右侧能稳定收到初稿和终稿

只要这三件事稳定，后续再继续加章节重写、评分展示、素材卡片增强，风险会小很多。

11 KiB Raw Permalink Blame History