704 lines
11 KiB
Markdown
704 lines
11 KiB
Markdown
# AI 写作助手前端开发任务清单
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档用于把《AI 写作助手右侧编辑器升级需求文档》进一步拆成前端可直接执行的任务清单。
|
||
|
||
目标是让前端团队按模块并行推进，最终完成：
|
||
|
||
- 保留左侧聊天区
|
||
- 右侧升级为 `Tiptap` 写作编辑器
|
||
- 支持选区浮层
|
||
- 支持润色 / 扩写 / 缩写 / 改语气
|
||
- 支持替换 / 插入
|
||
- 支持标题 / 列表 / 引用 / 代码块工具条
|
||
- UI 参考豆包 + Novel + open-canvas
|
||
|
||
---
|
||
|
||
## 2. 本轮前端改造范围
|
||
|
||
### 2.1 保留不动
|
||
|
||
- 左侧聊天主链路
|
||
- 现有线程消息流
|
||
- 现有模型选择器
|
||
- 现有输入框的 `writing_mode` 总入口
|
||
|
||
### 2.2 重点改造
|
||
|
||
- 右侧 Artifact 面板承载方式
|
||
- 新增独立写作工作区
|
||
- 富文本编辑器内核
|
||
- 选区浮层
|
||
- AI 改写结果预览
|
||
- 文档级工具条
|
||
|
||
---
|
||
|
||
## 3. 推荐目录结构
|
||
|
||
建议新增独立模块目录：
|
||
|
||
```text
|
||
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. 最后做视觉打磨
|
||
|
||
这个顺序风险最小，也最容易在中途验收。
|