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

AI 写作助手前端开发任务清单

1. 文档目标

本文档用于把《AI 写作助手右侧编辑器升级需求文档》进一步拆成前端可直接执行的任务清单。

目标是让前端团队按模块并行推进，最终完成：

• 保留左侧聊天区
• 右侧升级为 Tiptap 写作编辑器
• 支持选区浮层
• 支持润色 / 扩写 / 缩写 / 改语气
• 支持替换 / 插入
• 支持标题 / 列表 / 引用 / 代码块工具条
• UI 参考豆包 + Novel + open-canvas

---

2. 本轮前端改造范围

2.1 保留不动

• 左侧聊天主链路
• 现有线程消息流
• 现有模型选择器
• 现有输入框的 writing_mode 总入口

2.2 重点改造

• 右侧 Artifact 面板承载方式
• 新增独立写作工作区
• 富文本编辑器内核
• 选区浮层
• AI 改写结果预览
• 文档级工具条

---

3. 推荐目录结构

建议新增独立模块目录：

frontend-web/src/open-canvas-writing/
  routes/
    WritingRoutes.tsx
  pages/
    WritingWorkspacePage.tsx
  components/
    WritingShell.tsx
    WritingHeader.tsx
    WritingToolbar.tsx
    WritingEditorPane.tsx
    WritingBubbleMenu.tsx
    WritingAiMenu.tsx
    WritingRewritePreview.tsx
    WritingStatusBar.tsx
    WritingEmptyState.tsx
  editor/
    TiptapEditor.tsx
    TiptapExtensions.ts
    commands.ts
    selection.ts
  context/
    WritingEditorContext.tsx
  hooks/
    useWritingEditor.ts
    useWritingSelection.ts
    useWritingRewrite.ts
    useWritingToolbar.ts
  api/
    rewrite.ts
    documents.ts
  types/
    document.ts
    rewrite.ts
  utils/
    apply-rewrite.ts
    markdown.ts
    editor-style.ts

---

4. 现有代码落点

4.1 需要接入的现有文件

• frontend-web/src/pages/PageRoutes.tsx

  • 增加新写作路由入口

• frontend-web/src/components/workspace/chats/chat-box.tsx

  • 当前双栏布局参考来源
  • 后续决定是否复用布局容器，或在新页面中重建双栏

• frontend-web/src/components/workspace/input-box.tsx

  • 保留 writing_mode
  • 后续可在切换写作模式时跳转到新写作页面

• frontend-web/src/components/workspace/artifacts/context.tsx

  • 仅保留给旧 Artifact 逻辑
  • 不要继续承载写作编辑器状态

4.2 不建议继续沿用的方式

• 不要把编辑器主状态存成 string[] artifacts
• 不要把右侧主体验继续建在 artifact-file-detail.tsx 上
• 不要让 AI 改写结果先回聊天，再由用户手动复制

---

5. 任务分阶段拆解

阶段 A：路由与页面壳

目标

先把新的写作工作区页面立起来，让后续编辑器与交互都有落点。

任务

• 新增 WritingRoutes.tsx
• 新增 WritingWorkspacePage.tsx
• 在 PageRoutes.tsx 中挂入 page/writing/*
• 确认新页面进入方式
• 确定是：
  • 通过左侧聊天上下文进入
  • 通过 writing_mode 入口进入
  • 或二者都支持

交付物

• 新写作页面能被路由访问
• 页面有基础左右布局和空态

验收

• 打开 page/writing 能进入工作区
• 页面不报错

---

阶段 B：编辑器底座

目标

把右侧正式替换成富文本编辑器。

任务

• 安装 Tiptap 依赖
• 建立 TiptapEditor.tsx
• 建立 TiptapExtensions.ts
• 配置节点：
  • paragraph
  • heading
  • bulletList
  • orderedList
  • listItem
  • blockquote
  • codeBlock
  • hardBreak
• 配置 marks：
  • bold
  • italic
  • underline
  • strike
  • code
• 建立编辑器初始化逻辑
• 建立编辑器销毁逻辑
• 定义最小文档状态

交付物

• 可编辑正文区域
• 初始文档可加载
• 内容可读可写

验收

• 可以直接输入正文
• 可以换行、加标题、切换列表
• 不出现内容错位和明显闪烁

---

阶段 C：主工具栏

目标

右侧具备正式写作工具栏。

任务

• 新增 WritingToolbar.tsx
• 新增 useWritingToolbar.ts
• 实现按钮：
  • 正文
  • H1
  • H2
  • H3
  • 有序列表
  • 无序列表
  • 引用
  • 代码块
  • 加粗
  • 斜体
  • 下划线
  • 删除线
• 处理 active 状态
• 处理不可用状态
• 处理光标块状态联动

交付物

• 主工具栏可用

验收

• 工具条按钮能正确反映当前块状态
• 操作后编辑器内容正确变化

---

阶段 D：选区状态与浮层

目标

实现豆包式选区浮层基础能力。

任务

• 新增 useWritingSelection.ts
• 新增 selection.ts
• 新增 WritingBubbleMenu.tsx
• 基于 Tiptap 监听 selection 变化
• 过滤掉空选区
• 处理多段连续选区
• 浮层按钮：
  • AI 改写
  • 加粗
  • 斜体
  • 标题
  • 复制
• 处理滚动定位
• 处理窗口尺寸变化

交付物

• 选中内容后出现浮层

验收

• 单段可触发
• 多段可触发
• 浮层位置稳定

---

阶段 E：AI 改写菜单

目标

把选区浮层接到 AI 改写工作流。

任务

• 新增 WritingAiMenu.tsx
• 新增 useWritingRewrite.ts
• 新增 api/rewrite.ts
• 实现一级动作：
  • 润色
  • 扩写
  • 缩写
  • 改语气
• 实现改语气二级菜单：
  • 更专业
  • 更口语化
  • 更易读
  • 更学术
  • 更有文采
• 封装请求入参
• 增加 loading 态
• 增加 error 态
• 增加 retry 入口

交付物

• AI 改写菜单和请求链路

验收

• 4 个动作都能发请求
• 改语气的二级菜单可正常展开
• 请求失败时有反馈

---

阶段 F：候选结果预览

目标

把 AI 结果变成“可预览、可决策、可回退”的候选内容。

任务

• 新增 WritingRewritePreview.tsx
• 新增 apply-rewrite.ts
• 显示原文与候选内容
• 提供按钮：
  • 替换
  • 插入
  • 重试
  • 取消
• 用 transaction 应用结果
• 处理应用成功后的焦点与滚动

交付物

• 改写结果预览卡片或面板

验收

• 替换准确
• 插入准确
• 取消后文档保持原样

---

阶段 G：文档状态与容器体验

目标

补齐正式产品的壳层体验。

任务

• 新增 WritingShell.tsx
• 新增 WritingHeader.tsx
• 新增 WritingStatusBar.tsx
• 新增 WritingEmptyState.tsx
• 补充文档标题区域
• 补充文档状态提示
• 补充空态和加载态

交付物

• 页面完整壳层

验收

• 页面不是裸编辑器
• 有完整的文档工作区感

---

阶段 H：视觉打磨

目标

让整体观感接近成熟产品。

任务

• 调整右侧阅读宽度
• 调整字体大小和行高
• 调整段距和标题层级
• 调整工具栏阴影、边框、圆角
• 调整浮层动效
• 调整 AI 预览卡片质感
• 优化深浅色模式兼容

交付物

• 完整视觉优化

验收

• 明显优于当前版本
• 有豆包 / Novel 风格的编辑器质感

---

6. 组件级开发清单

6.1 WritingWorkspacePage.tsx

职责：

• 页面级容器
• 获取线程 / 文档上下文
• 组织左右布局

必须完成：

• 页面初始化
• 与左侧聊天协同
• 右侧编辑区挂载

6.2 WritingShell.tsx

职责：

• 写作工作区总壳层
• 布局标题区、工具栏、正文区、状态区

必须完成：

• 自适应布局
• 桌面端优先
• 窄屏降级

6.3 TiptapEditor.tsx

职责：

• 包装 Tiptap EditorContent
• 负责 editor 实例初始化

必须完成：

• onUpdate
• onSelectionUpdate
• 内容同步

6.4 WritingToolbar.tsx

职责：

• 顶部主工具栏

必须完成：

• 所有基础格式化命令
• 当前状态高亮

6.5 WritingBubbleMenu.tsx

职责：

• 选区浮层

必须完成：

• 跟随选区
• 基础快捷操作
• AI 改写入口

6.6 WritingAiMenu.tsx

职责：

• AI 改写动作菜单

必须完成：

• 一级菜单
• 改语气二级菜单
• 动作触发

6.7 WritingRewritePreview.tsx

职责：

• 展示候选内容

必须完成：

• 替换
• 插入
• 重试
• 取消

---

7. Hook 级开发清单

7.1 useWritingEditor.ts

负责：

• editor 生命周期
• 初始内容装载
• 内容变更同步

7.2 useWritingSelection.ts

负责：

• 当前选区抽取
• 选区文本缓存
• 多段落纯文本拼接

7.3 useWritingRewrite.ts

负责：

• 改写请求
• loading / success / error
• 结果缓存
• 重试

7.4 useWritingToolbar.ts

负责：

• toolbar active 状态
• editor command 映射

---

8. API 对接清单

前端需向后端约定以下接口能力：

• POST /api/writing/rewrite

前端请求内容至少包括：

• threadId
• documentId
• selection.from
• selection.to
• selection.text
• action
• tone
• surroundingContext.before
• surroundingContext.after

前端需处理的返回字段：

• output
• originalSelection
• metadata

---

9. 状态管理建议

建议新增独立 Context：

• WritingEditorContext.tsx

建议持有：

• 当前文档内容
• 当前 editor 实例
• 当前选区
• 当前改写请求状态
• 当前候选结果
• 当前 UI 面板状态

不建议继续复用旧 Artifact Context 的原因：

• 旧 Context 关注文件列表和文件路径
• 新编辑器关注选区、结构、候选结果、应用动作
• 关注点完全不同

---

10. 前端联调检查点

10.1 与后端联调前

• 先用 mock 数据打通浮层和预览
• 先验证替换 / 插入逻辑

10.2 与后端联调时

• 检查多段落选区拼接结果
• 检查 AI 返回内容是否带说明性前缀
• 检查替换后位置是否准确

10.3 联调后

• 验证大段文本性能
• 验证撤销 / 重做
• 验证快速连续触发是否会状态错乱

---

11. 前端测试清单

11.1 功能测试

• 输入正文
• 插入标题
• 切换列表
• 插入引用
• 插入代码块
• 加粗 / 斜体 / 下划线 / 删除线
• 选区浮层显示
• 选区浮层隐藏
• AI 改写菜单打开
• 改语气二级菜单打开
• 改写结果替换
• 改写结果插入
• 改写结果取消

11.2 场景测试

• 单段短文本润色
• 多段文本润色
• 多段文本扩写
• 多段文本缩写
• 多段文本改语气
• 连续两次改写同一段
• 快速切换线程后重新进入

11.3 回归测试

• 左侧聊天是否正常
• 模型切换是否正常
• writing_mode 是否正常
• 原有 artifact 模块是否仍可使用

---

12. 任务优先级

P0

• 路由与页面壳
• Tiptap 接入
• 主工具栏
• 选区浮层
• 改写菜单
• 替换 / 插入

P1

• 页面头部与状态
• 优雅 loading / error / retry
• 多段落稳定性
• UI 打磨

P2

• 空态优化
• 动效优化
• 快捷键支持

---

13. 建议分工

前端 1 号

负责：

• 路由与页面壳
• Tiptap 接入
• 主工具栏

前端 2 号

负责：

• 选区状态
• BubbleMenu
• AI 菜单

前端 3 号

负责：

• 候选结果预览
• 替换 / 插入
• 状态栏与页面体验

联调负责人

负责：

• 前后端请求协议
• 错误态规范
• 多段落测试和回归

---

14. 前端完成定义

满足以下条件可视为前端完成：

• 右侧能作为正式编辑器独立使用
• 选区后可直接发起 AI 改写
• 改写后可替换或插入
• 视觉上明显优于当前版本
• 左侧聊天和现有系统不被破坏

---

15. 下一步建议

前端团队可以按以下顺序开工：

1. 先起页面和路由
2. 再接 Tiptap 与主工具栏
3. 再做选区浮层
4. 再接 AI 菜单和结果预览
5. 最后做视觉打磨

这个顺序风险最小，也最容易在中途验收。