# 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. 最后做视觉打磨 这个顺序风险最小，也最容易在中途验收。