1192 lines
22 KiB
Markdown
1192 lines
22 KiB
Markdown
# AI 写作助手右侧编辑器升级需求文档
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档用于指导 DeerFlow 当前 AI 写作助手的第二阶段升级。
|
||
|
||
本次升级不推翻现有整体架构，不重做左侧聊天，不替换 LangGraph 后端，而是在现有 DeerFlow 基础上，把右侧编辑区升级为更接近豆包 AI 写作助手、Novel、open-canvas 风格的 AI 原生写作编辑器。
|
||
|
||
本次需求聚焦四类核心能力：
|
||
|
||
- 选区浮层
|
||
- 润色 / 扩写 / 缩写 / 改语气
|
||
- 替换 / 插入
|
||
- 标题 / 列表 / 引用 / 代码块工具条
|
||
|
||
本次交付目标不是“补几个按钮”，而是把右侧从“结果预览面板”升级成“可直接写、可选区改、可连续编辑、可 AI 辅助重写”的正式写作工作区。
|
||
|
||
---
|
||
|
||
## 2. 总体结论
|
||
|
||
### 2.1 保留不动的部分
|
||
|
||
- 保留现有左侧聊天区
|
||
- 保留现有线程体系
|
||
- 保留现有 LangGraph 后端
|
||
- 保留现有模型配置与模型选择体系
|
||
- 保留现有消息流与线程上下文
|
||
- 保留现有“写作模式”总入口
|
||
|
||
### 2.2 本次替换和新增的部分
|
||
|
||
- 将右侧简易 Artifact 文本查看 / 编辑区升级为 `Tiptap` 富文本编辑器
|
||
- 在右侧新增面向写作场景的 AI 选区改写工作流
|
||
- 为右侧补齐写作工具栏、选区浮层、结果预览、替换 / 插入动作
|
||
- 将当前“生成后查看”的体验改造成“生成、选中、局部重写、继续编辑”的闭环
|
||
|
||
### 2.3 技术选型结论
|
||
|
||
本次默认采用 `Tiptap` 作为右侧编辑器内核。
|
||
|
||
原因：
|
||
|
||
- 更适合做选区级 AI 操作
|
||
- 更适合做浮动菜单和块结构格式工具栏
|
||
- 更适合多段落选区与结构化文本编辑
|
||
- 更适合后续扩展 slash menu、批注、修订记录、评论等能力
|
||
- 与 Novel 和 open-canvas 的交互借鉴路径更贴近
|
||
|
||
`Plate` 作为 UI 参考和交互参考保留，不作为本轮主内核。
|
||
|
||
---
|
||
|
||
## 3. 参考产品与参考源码
|
||
|
||
### 3.1 交互参考
|
||
|
||
- 豆包 AI 写作助手
|
||
- Novel
|
||
- open-canvas
|
||
|
||
### 3.2 借鉴重点
|
||
|
||
- 豆包：选区浮层、AI 改写入口、替换 / 插入、轻量化写作工具条、页面留白和排版气质
|
||
- Novel：文档编辑器产品感、工具条组织、编辑容器、页面视觉层级
|
||
- open-canvas：AI 改写流程、候选内容应用流程、编辑器与聊天协同思路
|
||
|
||
### 3.3 明确不直接照搬的部分
|
||
|
||
- 不直接复制 open-canvas 的 Next.js 页面结构
|
||
- 不直接复制 Novel 的服务端实现
|
||
- 不直接引入整套 Plate 生态替代现有编辑区
|
||
|
||
---
|
||
|
||
## 4. 当前系统现状
|
||
|
||
结合当前代码结构，和本需求直接相关的现状如下：
|
||
|
||
### 4.1 已有接入点
|
||
|
||
- `frontend-web/src/pages/PageRoutes.tsx`
|
||
- 当前已引入 `@/open-canvas/routes/OpenCanvasRoutes`
|
||
- 说明项目已经有独立 Canvas 路由接入能力
|
||
|
||
- `frontend-web/src/components/workspace/chats/chat-box.tsx`
|
||
- 当前左聊天 + 右 Artifact 面板是双栏布局
|
||
- 当前右侧仍然偏 Artifact 文件查看 / 编辑
|
||
|
||
- `frontend-web/src/components/workspace/artifacts/context.tsx`
|
||
- 当前 Artifact 上下文仍以 `string[]` 文件路径为主
|
||
- 不适合直接承载“选区级写作编辑器状态”
|
||
|
||
- `frontend-web/src/components/workspace/input-box.tsx`
|
||
- 已经存在 `writing_mode`
|
||
- 可以作为本次写作助手模式切换的入口保留
|
||
|
||
### 4.2 当前不足
|
||
|
||
- 右侧编辑区更像文件预览器，不像完整写作编辑器
|
||
- 缺少选区工具条
|
||
- 缺少多段落改写能力
|
||
- 缺少 AI 改写候选应用工作流
|
||
- 缺少标题 / 列表 / 引用 / 代码块等正式文档工具
|
||
- 页面视觉上仍偏“工程面板”，产品完成度不足
|
||
|
||
---
|
||
|
||
## 5. 本次需求范围
|
||
|
||
### 5.1 本次必须实现
|
||
|
||
- 基于 `Tiptap` 的右侧富文本编辑器
|
||
- 选区浮层
|
||
- AI 改写动作菜单
|
||
- 润色 / 扩写 / 缩写 / 改语气
|
||
- 改语气二级选项
|
||
- 改写结果预览
|
||
- 替换 / 插入
|
||
- 标题 / 列表 / 引用 / 代码块工具条
|
||
- UI 美化与交互统一
|
||
- 多段落选区改写
|
||
|
||
### 5.2 本次不做
|
||
|
||
- 多人协作
|
||
- 评论系统
|
||
- 修订模式
|
||
- 文档历史对比
|
||
- 图片、表格、附件编辑器
|
||
- 复杂导入导出
|
||
- 全量 Notion 式块拖拽系统
|
||
- slash command
|
||
|
||
### 5.3 下阶段可扩展
|
||
|
||
- slash command
|
||
- 改写历史
|
||
- 修订轨迹
|
||
- 边写边建议
|
||
- 文风模板
|
||
- 批注与审阅
|
||
|
||
---
|
||
|
||
## 6. 产品目标
|
||
|
||
升级完成后，用户应获得以下体验：
|
||
|
||
- 在左侧继续正常聊天
|
||
- 在右侧像正式文档编辑器一样直接书写和改写
|
||
- 选中一句、一段、多段内容后，能立即触发 AI 改写
|
||
- AI 返回结果后，用户能决定“替换原文”还是“插入到后面”
|
||
- 页面视觉上明显从“开发态”升级为“产品态”
|
||
- 对长文写作、改稿、润色、扩写更友好
|
||
|
||
---
|
||
|
||
## 7. 页面与交互结构
|
||
|
||
### 7.1 整体布局
|
||
|
||
继续保留双栏布局：
|
||
|
||
- 左侧：聊天区
|
||
- 右侧：AI 写作编辑器
|
||
|
||
### 7.2 右侧编辑器结构
|
||
|
||
建议右侧拆分为以下区域：
|
||
|
||
1. 文档头部区
|
||
- 文档标题
|
||
- 文档状态
|
||
- 可能的保存提示
|
||
|
||
2. 主工具栏
|
||
- 正文
|
||
- 一级标题
|
||
- 二级标题
|
||
- 三级标题
|
||
- 有序列表
|
||
- 无序列表
|
||
- 引用
|
||
- 代码块
|
||
- 加粗
|
||
- 斜体
|
||
- 下划线
|
||
- 删除线
|
||
|
||
3. 编辑正文区
|
||
- 基于 Tiptap 的可编辑正文
|
||
|
||
4. 选区浮层
|
||
- AI 改写
|
||
- 加粗
|
||
- 斜体
|
||
- 标题
|
||
- 复制
|
||
|
||
5. AI 改写动作菜单
|
||
- 润色
|
||
- 扩写
|
||
- 缩写
|
||
- 改语气
|
||
|
||
6. 改写结果预览区
|
||
- 预览文本
|
||
- 替换
|
||
- 插入
|
||
- 重试
|
||
- 取消
|
||
|
||
### 7.3 目标交互闭环
|
||
|
||
1. 用户在左侧发起写作任务
|
||
2. 右侧生成初稿或打开写作画布
|
||
3. 用户在右侧直接编辑
|
||
4. 用户选中一句或多段
|
||
5. 弹出浮层
|
||
6. 点击 `AI 改写`
|
||
7. 选择 `润色 / 扩写 / 缩写 / 改语气`
|
||
8. 看到候选结果
|
||
9. 选择 `替换` 或 `插入`
|
||
10. 继续写、继续改、继续和左侧聊天协同
|
||
|
||
---
|
||
|
||
## 8. 核心能力详细定义
|
||
|
||
## 8.1 能力一：选区浮层
|
||
|
||
### 目标
|
||
|
||
用户在右侧选中文本后，出现跟随选区的浮层工具条。
|
||
|
||
### 首版必须包含的按钮
|
||
|
||
- AI 改写
|
||
- 加粗
|
||
- 斜体
|
||
- 标题
|
||
- 复制
|
||
|
||
### 行为要求
|
||
|
||
- 只有在有效文本选区存在时显示
|
||
- 选区取消后自动消失
|
||
- 滚动时位置跟随更新
|
||
- 只对右侧编辑器正文区域生效
|
||
- 对跨多个段落的纯文本选区生效
|
||
|
||
### 首版限制
|
||
|
||
- 首版只处理文本选区
|
||
- 不处理跨复杂嵌套节点的高级结构变更
|
||
|
||
### 验收标准
|
||
|
||
- 选中单段文本时能稳定出现
|
||
- 选中连续多段文本时能稳定出现
|
||
- 不遮挡正文主要阅读区域
|
||
|
||
---
|
||
|
||
## 8.2 能力二：AI 改写动作
|
||
|
||
### 目标
|
||
|
||
用户选中内容后，可快速对该内容发起 AI 重写。
|
||
|
||
### 一级动作
|
||
|
||
- 润色
|
||
- 扩写
|
||
- 缩写
|
||
- 改语气
|
||
|
||
### 改语气二级选项
|
||
|
||
- 更专业
|
||
- 更口语化
|
||
- 更易读
|
||
- 更学术
|
||
- 更有文采
|
||
|
||
### 行为要求
|
||
|
||
- 改写动作基于当前选区触发
|
||
- 支持单段落与多段落
|
||
- 支持带少量前后文一起发给后端
|
||
- 改写期间有明显 loading 态
|
||
- 改写失败要有失败提示和重试入口
|
||
|
||
### 提示词策略
|
||
|
||
首版不开放自定义 prompt，只提供预设动作。
|
||
|
||
### 验收标准
|
||
|
||
- 四类一级动作可正常使用
|
||
- 改语气二级菜单可正常展开和触发
|
||
- 多段落改写不会破坏原文结构边界
|
||
|
||
---
|
||
|
||
## 8.3 能力三：替换 / 插入
|
||
|
||
### 目标
|
||
|
||
AI 返回候选内容后，不直接覆盖原文，而是先让用户决策如何应用。
|
||
|
||
### 两种应用方式
|
||
|
||
- 替换：用候选结果替换当前选区
|
||
- 插入：把候选结果插入到选区后面，保留原文
|
||
|
||
### 行为要求
|
||
|
||
- AI 返回结果后先展示预览
|
||
- 默认不自动落文档
|
||
- 支持重试
|
||
- 支持取消
|
||
- 应用动作完成后，编辑器内容与光标位置要合理
|
||
|
||
### 首版简化
|
||
|
||
- 不做复杂 diff 对比
|
||
- 先做“原文 + 候选文”的简单预览卡片
|
||
|
||
### 验收标准
|
||
|
||
- 替换位置准确
|
||
- 插入位置准确
|
||
- 应用后编辑器不丢焦点或出现异常闪动
|
||
|
||
---
|
||
|
||
## 8.4 能力四：主工具栏
|
||
|
||
### 目标
|
||
|
||
让右侧不再只是 AI 输出区，而是正式写作编辑器。
|
||
|
||
### 首版必须支持的结构
|
||
|
||
- 正文
|
||
- 一级标题
|
||
- 二级标题
|
||
- 三级标题
|
||
- 有序列表
|
||
- 无序列表
|
||
- 引用
|
||
- 代码块
|
||
|
||
### 首版必须支持的行内样式
|
||
|
||
- 加粗
|
||
- 斜体
|
||
- 下划线
|
||
- 删除线
|
||
|
||
### 行为要求
|
||
|
||
- 工具条按钮有选中态
|
||
- 光标所在块能正确反映当前结构
|
||
- 对选区和当前块的作用逻辑明确
|
||
- 工具栏与选区浮层不打架
|
||
|
||
### 验收标准
|
||
|
||
- 标题和正文可互相切换
|
||
- 列表、引用、代码块可稳定切换
|
||
- 行内样式不影响 AI 选区改写链路
|
||
|
||
---
|
||
|
||
## 9. 编辑器数据模型
|
||
|
||
### 9.1 前端主状态
|
||
|
||
建议前端编辑器使用 Tiptap JSON 作为内部主状态。
|
||
|
||
建议定义：
|
||
|
||
```ts
|
||
type WritingDocumentState = {
|
||
documentId?: string;
|
||
title: string;
|
||
markdown: string;
|
||
editorJson?: Record<string, unknown>;
|
||
updatedAt?: string;
|
||
};
|
||
```
|
||
|
||
### 9.2 选区状态
|
||
|
||
```ts
|
||
type WritingSelectionState = {
|
||
from: number;
|
||
to: number;
|
||
text: string;
|
||
isCollapsed: boolean;
|
||
blockTypes?: string[];
|
||
};
|
||
```
|
||
|
||
### 9.3 改写动作
|
||
|
||
```ts
|
||
type RewriteAction =
|
||
| "polish"
|
||
| "expand"
|
||
| "shorten"
|
||
| "tone";
|
||
```
|
||
|
||
### 9.4 改语气风格
|
||
|
||
```ts
|
||
type RewriteTone =
|
||
| "professional"
|
||
| "casual"
|
||
| "readable"
|
||
| "academic"
|
||
| "expressive";
|
||
```
|
||
|
||
### 9.5 改写请求
|
||
|
||
```ts
|
||
type RewriteRequest = {
|
||
threadId: string;
|
||
documentId?: string;
|
||
selection: {
|
||
from: number;
|
||
to: number;
|
||
text: string;
|
||
};
|
||
action: RewriteAction;
|
||
tone?: RewriteTone;
|
||
mode?: "preview";
|
||
surroundingContext?: {
|
||
before?: string;
|
||
after?: string;
|
||
};
|
||
};
|
||
```
|
||
|
||
### 9.6 改写响应
|
||
|
||
```ts
|
||
type RewriteResponse = {
|
||
output: string;
|
||
originalSelection: {
|
||
from: number;
|
||
to: number;
|
||
text: string;
|
||
};
|
||
metadata?: {
|
||
action: RewriteAction;
|
||
tone?: RewriteTone;
|
||
model?: string;
|
||
};
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 与现有 DeerFlow 代码结构的对应关系
|
||
|
||
## 10.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
|
||
- 新写作画布建议单独维护自己的 context
|
||
|
||
## 10.2 不建议继续复用的方式
|
||
|
||
- 不建议把 Tiptap 状态直接塞进现有 `string[] artifacts`
|
||
- 不建议继续把右侧主体验建立在“文件详情页”上
|
||
- 不建议把 AI 改写做成单纯聊天消息回传后人工复制
|
||
|
||
---
|
||
|
||
## 11. 前端目录建议
|
||
|
||
建议在 `frontend-web/src` 下新增独立模块目录：
|
||
|
||
```text
|
||
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
|
||
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/
|
||
markdown.ts
|
||
apply-rewrite.ts
|
||
editor-style.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 路由与页面接入要求
|
||
|
||
### 12.1 路由策略
|
||
|
||
建议在现有 `PageRoutes` 体系下增加独立写作工作区页面，而不是塞进已有普通 artifact 面板。
|
||
|
||
### 12.2 接入方式
|
||
|
||
建议新增：
|
||
|
||
- `frontend-web/src/open-canvas-writing/routes/WritingRoutes.tsx`
|
||
- `frontend-web/src/open-canvas-writing/pages/WritingWorkspacePage.tsx`
|
||
|
||
然后在：
|
||
|
||
- `frontend-web/src/pages/PageRoutes.tsx`
|
||
|
||
中引入新的写作助手路由，例如：
|
||
|
||
- `page/writing/*`
|
||
- 或合并到现有 `page/canvas/*` 下的子路由
|
||
|
||
### 12.3 路由设计建议
|
||
|
||
推荐：
|
||
|
||
- `page/writing`
|
||
- 新建写作工作区
|
||
|
||
- `page/writing/:threadId`
|
||
- 进入某个线程对应写作工作区
|
||
|
||
如果你们已经有 `open-canvas` 路由，则建议不要把“豆包式写作编辑器”塞进原实验性画布页面里，而是作为独立子模式接入，避免后续页面职责混乱。
|
||
|
||
---
|
||
|
||
## 13. 前端实施拆解
|
||
|
||
## 13.1 模块 A：编辑器内核接入
|
||
|
||
### 目标
|
||
|
||
让右侧拥有正式可编辑文档能力。
|
||
|
||
### 任务
|
||
|
||
- 安装 Tiptap 基础依赖
|
||
- 接入 `StarterKit`
|
||
- 接入 `Underline`
|
||
- 配置支持：
|
||
- paragraph
|
||
- heading
|
||
- bulletList
|
||
- orderedList
|
||
- blockquote
|
||
- codeBlock
|
||
- bold
|
||
- italic
|
||
- underline
|
||
- strike
|
||
- code
|
||
- 建立受控 / 半受控编辑器状态
|
||
- 实现 Markdown 与 Tiptap JSON 的最小同步策略
|
||
|
||
### 输出物
|
||
|
||
- `TiptapEditor.tsx`
|
||
- `TiptapExtensions.ts`
|
||
- 基础编辑器容器样式
|
||
|
||
### 依赖关系
|
||
|
||
- 无前置依赖，可先开工
|
||
|
||
### 验收标准
|
||
|
||
- 右侧可以像普通文档编辑器一样输入和编辑内容
|
||
|
||
## 13.2 模块 B：主工具栏
|
||
|
||
### 目标
|
||
|
||
补齐写作编辑基础能力。
|
||
|
||
### 任务
|
||
|
||
- 实现标题切换
|
||
- 实现列表切换
|
||
- 实现引用切换
|
||
- 实现代码块切换
|
||
- 实现加粗 / 斜体 / 下划线 / 删除线
|
||
- 工具按钮高亮与禁用态
|
||
- 光标所在块状态识别
|
||
|
||
### 输出物
|
||
|
||
- `WritingToolbar.tsx`
|
||
- `useWritingToolbar.ts`
|
||
|
||
### 依赖关系
|
||
|
||
- 依赖模块 A
|
||
|
||
### 验收标准
|
||
|
||
- 常用写作结构和行内样式均可稳定切换
|
||
|
||
## 13.3 模块 C：选区浮层
|
||
|
||
### 目标
|
||
|
||
选中文本后出现轻量化操作浮层。
|
||
|
||
### 任务
|
||
|
||
- 监听 Tiptap selection
|
||
- 接入 BubbleMenu
|
||
- 处理显示 / 隐藏逻辑
|
||
- 布局 AI 改写、加粗、斜体、标题、复制
|
||
- 处理滚动与定位稳定性
|
||
|
||
### 输出物
|
||
|
||
- `WritingBubbleMenu.tsx`
|
||
- `useWritingSelection.ts`
|
||
- `selection.ts`
|
||
|
||
### 依赖关系
|
||
|
||
- 依赖模块 A
|
||
|
||
### 验收标准
|
||
|
||
- 选区浮层在单段和多段文本上都稳定可用
|
||
|
||
## 13.4 模块 D：AI 改写菜单
|
||
|
||
### 目标
|
||
|
||
把 AI 改写入口真正挂进选区工作流。
|
||
|
||
### 任务
|
||
|
||
- 实现 `AI 改写` 一级入口
|
||
- 实现动作菜单
|
||
- 实现改语气二级菜单
|
||
- 封装改写请求 API
|
||
- 建立 loading / success / error 状态管理
|
||
|
||
### 输出物
|
||
|
||
- `WritingAiMenu.tsx`
|
||
- `useWritingRewrite.ts`
|
||
- `api/rewrite.ts`
|
||
|
||
### 依赖关系
|
||
|
||
- 依赖模块 C
|
||
- 与后端接口联调
|
||
|
||
### 验收标准
|
||
|
||
- 四类改写动作都能从选区直接触发
|
||
|
||
## 13.5 模块 E：候选结果预览与应用
|
||
|
||
### 目标
|
||
|
||
将 AI 改写从“直接灌入文本”升级为“预览后应用”。
|
||
|
||
### 任务
|
||
|
||
- 设计候选结果展示卡
|
||
- 展示原文选区与候选结果
|
||
- 提供：
|
||
- 替换
|
||
- 插入
|
||
- 重试
|
||
- 取消
|
||
- 将候选内容通过 Tiptap transaction 应用到文档
|
||
|
||
### 输出物
|
||
|
||
- `WritingRewritePreview.tsx`
|
||
- `apply-rewrite.ts`
|
||
|
||
### 依赖关系
|
||
|
||
- 依赖模块 D
|
||
|
||
### 验收标准
|
||
|
||
- 替换和插入都能准确写回编辑器
|
||
|
||
## 13.6 模块 F：页面美化
|
||
|
||
### 目标
|
||
|
||
把页面从“工程面板”升级为“成熟产品页面”。
|
||
|
||
### 任务
|
||
|
||
- 调整双栏比例和留白
|
||
- 优化右侧容器背景、阴影、边框、圆角
|
||
- 优化标题层级、正文字号、行高、段距
|
||
- 优化浮层和工具条视觉层级
|
||
- 优化 loading、hover、active 动效
|
||
- 对移动端和窄屏做降级策略
|
||
|
||
### 输出物
|
||
|
||
- `WritingShell.tsx`
|
||
- `WritingHeader.tsx`
|
||
- `WritingStatusBar.tsx`
|
||
- 相关样式变量
|
||
|
||
### 依赖关系
|
||
|
||
- 可与其他模块并行推进
|
||
|
||
### 验收标准
|
||
|
||
- 整体视觉明显接近正式写作产品
|
||
|
||
---
|
||
|
||
## 14. 后端实施拆解
|
||
|
||
## 14.1 总原则
|
||
|
||
后端保留现有 LangGraph 和线程架构，本轮只增加“选区改写型接口 / 节点 / 工具”，不重构整套后端。
|
||
|
||
## 14.2 后端最小职责
|
||
|
||
后端负责：
|
||
|
||
- 接收选区文本
|
||
- 接收动作类型
|
||
- 补足必要上下文
|
||
- 调用模型完成改写
|
||
- 返回候选文本
|
||
|
||
后端首版不负责：
|
||
|
||
- 直接操作 Tiptap JSON
|
||
- 直接做文档 patch
|
||
- 直接做复杂结构变换
|
||
|
||
## 14.3 推荐新增能力
|
||
|
||
- `rewrite_selection`
|
||
- `expand_selection`
|
||
- `shorten_selection`
|
||
- `change_tone`
|
||
|
||
### 统一接口建议
|
||
|
||
更推荐做成一个统一接口：
|
||
|
||
```text
|
||
POST /api/writing/rewrite
|
||
```
|
||
|
||
由请求体中的 `action` 和 `tone` 控制行为。
|
||
|
||
### 请求建议
|
||
|
||
- `threadId`
|
||
- `documentId`
|
||
- `selection.text`
|
||
- `selection.from`
|
||
- `selection.to`
|
||
- `action`
|
||
- `tone`
|
||
- `surroundingContext.before`
|
||
- `surroundingContext.after`
|
||
|
||
### 返回建议
|
||
|
||
- `output`
|
||
- `metadata.action`
|
||
- `metadata.tone`
|
||
- `metadata.model`
|
||
|
||
## 14.4 后端提示词策略
|
||
|
||
首版建议固定模板：
|
||
|
||
- 润色：保持原意，提高表达质量
|
||
- 扩写：在不偏离主题的前提下扩展细节
|
||
- 缩写：压缩表达但保留关键信息
|
||
- 改语气：保持事实不变，调整语言风格
|
||
|
||
统一要求：
|
||
|
||
- 尽量不要引入原文没有的新事实
|
||
- 不输出解释性前缀
|
||
- 直接返回可落文档的正文
|
||
|
||
## 14.5 后端验收标准
|
||
|
||
- 单段落改写稳定
|
||
- 多段落改写稳定
|
||
- 返回结果不夹带解释性废话
|
||
- 失败时能返回可识别错误
|
||
|
||
---
|
||
|
||
## 15. 前后端协议约束
|
||
|
||
### 15.1 首版协议原则
|
||
|
||
- 前端负责编辑器结构和最终写回
|
||
- 后端负责文本重写
|
||
- 前后端暂时通过“纯文本选区 + 上下文”交互
|
||
|
||
### 15.2 为什么不直接传富文本 JSON
|
||
|
||
因为首版最大的目标是稳定闭环，而不是复杂结构编辑。
|
||
|
||
如果一开始就让后端理解完整 Tiptap JSON，会显著增加：
|
||
|
||
- 协议复杂度
|
||
- 结构错位风险
|
||
- 测试成本
|
||
- 联调成本
|
||
|
||
因此首版推荐：
|
||
|
||
- 编辑器内部状态：Tiptap JSON
|
||
- 改写协议：纯文本 + 前后文
|
||
- 最终应用：前端 transaction
|
||
|
||
---
|
||
|
||
## 16. 分阶段实施计划
|
||
|
||
## 阶段 1：编辑器底座
|
||
|
||
### 目标
|
||
|
||
让右侧具备正式写作编辑能力。
|
||
|
||
### 包含内容
|
||
|
||
- Tiptap 接入
|
||
- 标题 / 列表 / 引用 / 代码块
|
||
- 行内样式
|
||
- 初步页面容器
|
||
|
||
### 验收
|
||
|
||
- 右侧能独立承担写作编辑
|
||
|
||
## 阶段 2：选区浮层
|
||
|
||
### 目标
|
||
|
||
把“选中文本后操作”打通。
|
||
|
||
### 包含内容
|
||
|
||
- BubbleMenu
|
||
- AI 改写入口
|
||
- 基础样式按钮
|
||
|
||
### 验收
|
||
|
||
- 单段和多段选区都可稳定触发
|
||
|
||
## 阶段 3：AI 改写
|
||
|
||
### 目标
|
||
|
||
把改写请求与后端串起来。
|
||
|
||
### 包含内容
|
||
|
||
- 润色
|
||
- 扩写
|
||
- 缩写
|
||
- 改语气
|
||
|
||
### 验收
|
||
|
||
- 四类动作都能返回结果
|
||
|
||
## 阶段 4：替换 / 插入
|
||
|
||
### 目标
|
||
|
||
把候选结果稳定应用到文档。
|
||
|
||
### 包含内容
|
||
|
||
- 结果预览
|
||
- 替换
|
||
- 插入
|
||
- 重试
|
||
- 取消
|
||
|
||
### 验收
|
||
|
||
- 改写结果可控落文档
|
||
|
||
## 阶段 5：UI 打磨
|
||
|
||
### 目标
|
||
|
||
让右侧从“能用”升级到“成熟产品感”。
|
||
|
||
### 包含内容
|
||
|
||
- 容器和留白
|
||
- 工具栏设计
|
||
- 浮层风格
|
||
- 字体和排版
|
||
- 动效
|
||
|
||
### 验收
|
||
|
||
- 视觉上明显接近豆包 / Novel 风格
|
||
|
||
---
|
||
|
||
## 17. 可并行分工建议
|
||
|
||
## 17.1 前端 A 组：编辑器底座
|
||
|
||
负责：
|
||
|
||
- Tiptap 接入
|
||
- 主工具栏
|
||
- 结构节点与 marks
|
||
|
||
对应阶段：
|
||
|
||
- 阶段 1
|
||
|
||
## 17.2 前端 B 组：选区交互
|
||
|
||
负责：
|
||
|
||
- 选区监听
|
||
- BubbleMenu
|
||
- AI 改写入口
|
||
|
||
对应阶段：
|
||
|
||
- 阶段 2
|
||
|
||
## 17.3 前端 C 组：候选结果与体验层
|
||
|
||
负责：
|
||
|
||
- 改写结果预览
|
||
- 替换 / 插入
|
||
- loading / error / retry
|
||
- UI 打磨
|
||
|
||
对应阶段：
|
||
|
||
- 阶段 4
|
||
- 阶段 5
|
||
|
||
## 17.4 后端 D 组：改写服务
|
||
|
||
负责：
|
||
|
||
- 统一改写接口
|
||
- LangGraph 节点或工具
|
||
- 提示词
|
||
- 上下文拼接
|
||
|
||
对应阶段：
|
||
|
||
- 阶段 3
|
||
|
||
## 17.5 联调负责人
|
||
|
||
负责：
|
||
|
||
- 协议定稿
|
||
- 错误码和异常约定
|
||
- 多段落选区联调
|
||
- 光标位置 / 替换位置问题兜底
|
||
|
||
---
|
||
|
||
## 18. UI 设计要求
|
||
|
||
### 18.1 风格关键词
|
||
|
||
- 轻
|
||
- 干净
|
||
- 编辑器优先
|
||
- AI 能力明显但不喧宾夺主
|
||
- 有留白
|
||
- 有产品感
|
||
|
||
### 18.2 页面视觉要求
|
||
|
||
- 右侧阅读宽度适中，不可过宽
|
||
- 主文内容器有明确层级
|
||
- 正文行高偏舒展
|
||
- 标题有清晰层级
|
||
- 工具栏不应过厚重
|
||
- 浮层必须轻、准、快
|
||
|
||
### 18.3 动效要求
|
||
|
||
- 浮层出现和消失有轻微过渡
|
||
- AI 改写请求有反馈
|
||
- 替换 / 插入确认有轻量状态切换
|
||
|
||
### 18.4 参考视觉方向
|
||
|
||
- 布局参考 Novel
|
||
- 选区和改写交互参考豆包
|
||
- AI 工作流节奏参考 open-canvas
|
||
|
||
---
|
||
|
||
## 19. 风险与规避方案
|
||
|
||
## 19.1 风险一：现有 Artifact 架构不适合承载写作编辑器
|
||
|
||
### 规避
|
||
|
||
- 不强塞到 `string[] artifacts`
|
||
- 新建独立写作模块和上下文
|
||
|
||
## 19.2 风险二：富文本与 Markdown 同步复杂
|
||
|
||
### 规避
|
||
|
||
- 首版以 Tiptap 内部状态为准
|
||
- 对外只做最小 Markdown 输出
|
||
|
||
## 19.3 风险三：多段落改写后替换位置错乱
|
||
|
||
### 规避
|
||
|
||
- 前端记录稳定选区范围
|
||
- 候选结果应用时使用 Tiptap transaction
|
||
- 首版优先支持连续纯文本段落
|
||
|
||
## 19.4 风险四：AI 返回啰嗦解释文本
|
||
|
||
### 规避
|
||
|
||
- 后端提示词严格约束只返回正文
|
||
- 前端必要时做轻量清洗
|
||
|
||
## 19.5 风险五：UI 做成“功能堆砌”
|
||
|
||
### 规避
|
||
|
||
- 首版只上最核心 4 类能力
|
||
- 不把太多低频按钮塞进第一层工具栏
|
||
|
||
---
|
||
|
||
## 20. 验收标准
|
||
|
||
## 20.1 功能验收
|
||
|
||
- 右侧可直接编辑文档
|
||
- 支持标题 / 列表 / 引用 / 代码块
|
||
- 选中内容后有浮层
|
||
- 支持润色 / 扩写 / 缩写 / 改语气
|
||
- 支持替换 / 插入
|
||
- 支持多段落选区改写
|
||
|
||
## 20.2 交互验收
|
||
|
||
- 浮层位置稳定
|
||
- AI 改写链路顺畅
|
||
- 替换 / 插入后位置正确
|
||
- 不影响左侧聊天流
|
||
|
||
## 20.3 体验验收
|
||
|
||
- 右侧明显比当前版本更成熟
|
||
- 页面更适合长文阅读和改稿
|
||
- 整体交互接近豆包 AI 写作助手
|
||
|
||
---
|
||
|
||
## 21. 首版最小可交付范围
|
||
|
||
如果需要控制风险，建议首版只交付：
|
||
|
||
- Tiptap 接入
|
||
- 主工具栏
|
||
- 选区浮层
|
||
- 润色 / 扩写 / 缩写 / 改语气
|
||
- 替换 / 插入
|
||
- 基础 UI 美化
|
||
|
||
以下能力不要强行塞进首版：
|
||
|
||
- 自定义提示词
|
||
- slash command
|
||
- 修订模式
|
||
- 评论系统
|
||
- 复杂 diff 对比
|
||
- 文档历史版本
|
||
|
||
---
|
||
|
||
## 22. 实施优先级
|
||
|
||
### P0
|
||
|
||
- Tiptap 接入
|
||
- 主工具栏
|
||
- 选区浮层
|
||
- AI 改写接口
|
||
- 替换 / 插入
|
||
|
||
### P1
|
||
|
||
- 页面整体美化
|
||
- 改语气二级菜单
|
||
- 多段落改写稳定性
|
||
- 错误态 / 重试态
|
||
|
||
### P2
|
||
|
||
- 文档状态提示
|
||
- 轻量空态
|
||
- 细节动画
|
||
- 交互易用性优化
|
||
|
||
---
|
||
|
||
## 23. 结论
|
||
|
||
这次升级最合理的路线，不是继续在现有右侧 Artifact 详情页上小修小补，而是正式引入一层写作编辑器能力。
|
||
|
||
最稳妥的做法是：
|
||
|
||
- 保留左侧聊天和现有 LangGraph 后端
|
||
- 在右侧引入 `Tiptap`
|
||
- 先把四个核心能力做深做稳
|
||
- UI 借鉴豆包、Novel、open-canvas 的成熟交互
|
||
|
||
只要按照本文档分阶段推进，这个需求虽然大，但完全可以拆成多组并行、逐步验收、持续落地的工程任务，而不是一次性大爆炸改造。
|