deerflow-code/frontend-web/docs/ai-writing-frontend-refactor-checklist.md

# AI 写作前端改造清单

## 1. 目标

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

当前核心文件：

- [CanvasResizableLayout.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/layout/CanvasResizableLayout.tsx)
- [CanvasChatPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/chat/CanvasChatPanel.tsx)
- [CanvasArtifactPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/artifact/CanvasArtifactPanel.tsx)
- [CanvasGraphContext.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/contexts/CanvasGraphContext.tsx)
- [CanvasStreamContext.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/contexts/CanvasStreamContext.tsx)
- [useCanvasThreadStream.ts](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/hooks/useCanvasThreadStream.ts)
- [runs.ts](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/api/runs.ts)

---

## 2. 改造原则

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

---

## 3. 推荐前端结构

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

```text
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` 中先定义：

```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 事件流形式

优先级建议：

1. `SSE`
2. 流式 HTTP chunk
3. 轮询兜底

理由：

- 事件驱动比整段消息流更适合 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. 建议修改点位

优先涉及文件：

- [CanvasChatPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/chat/CanvasChatPanel.tsx)
- [CanvasGraphContext.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/contexts/CanvasGraphContext.tsx)
- [useCanvasThreadStream.ts](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/hooks/useCanvasThreadStream.ts)
- [CanvasArtifactPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/artifact/CanvasArtifactPanel.tsx)

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

- `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 结果展示出来”，而是把“工作流过程可视化并允许人工介入”做清楚。

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

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

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