727 lines
12 KiB
Markdown
727 lines
12 KiB
Markdown
# AI 写作助手后端接口与 Prompt 协议文档
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档用于指导 AI 写作助手第二阶段升级中的后端开发、接口设计、提示词设计和联调约束。
|
||
|
||
本轮后端目标不是重做 DeerFlow 的整体架构，而是在保留现有 Python + LangGraph + 线程体系的基础上，新增一套稳定的“选区改写型能力”，服务前端的 Tiptap 写作编辑器。
|
||
|
||
---
|
||
|
||
## 2. 本轮后端职责
|
||
|
||
后端负责：
|
||
|
||
- 接收当前线程信息
|
||
- 接收用户选区文本
|
||
- 接收改写动作
|
||
- 选取必要上下文
|
||
- 调用模型生成候选改写结果
|
||
- 返回纯净候选文本
|
||
|
||
后端本轮不负责：
|
||
|
||
- 直接编辑 Tiptap JSON
|
||
- 直接操作前端编辑器选区
|
||
- 直接替换前端文档内容
|
||
- 做复杂富文本 patch
|
||
- 做 tracked changes
|
||
|
||
---
|
||
|
||
## 3. 设计原则
|
||
|
||
### 3.1 纯文本协议优先
|
||
|
||
首版只让后端处理：
|
||
|
||
- 选区文本
|
||
- 前后文文本
|
||
- 动作类型
|
||
- 风格参数
|
||
|
||
不让后端直接理解完整富文本 JSON。
|
||
|
||
### 3.2 前端负责应用，后端负责生成
|
||
|
||
- 前端负责选区获取
|
||
- 前端负责候选结果展示
|
||
- 前端负责替换 / 插入
|
||
- 后端只负责“给出候选文本”
|
||
|
||
### 3.3 结果必须可直接落文档
|
||
|
||
后端输出必须尽量是可直接放回编辑器的正文，不应带解释性前缀，例如：
|
||
|
||
- “当然可以，以下是润色版本：”
|
||
- “我帮你改写如下：”
|
||
- “下面是优化后的内容：”
|
||
|
||
这类内容必须禁止。
|
||
|
||
---
|
||
|
||
## 4. 推荐接口设计
|
||
|
||
## 4.1 主接口
|
||
|
||
推荐新增统一接口：
|
||
|
||
```text
|
||
POST /api/writing/rewrite
|
||
```
|
||
|
||
由 `action` 决定具体重写类型。
|
||
|
||
## 4.2 为什么推荐统一接口
|
||
|
||
因为前端交互是一套统一浮层和统一预览面板，拆成多个接口会导致：
|
||
|
||
- 前端判断分支增多
|
||
- 埋点与异常处理分散
|
||
- 后续新增动作不方便扩展
|
||
|
||
统一接口更适合本轮需求。
|
||
|
||
---
|
||
|
||
## 5. 请求体定义
|
||
|
||
建议请求体如下：
|
||
|
||
```json
|
||
{
|
||
"threadId": "string",
|
||
"documentId": "string",
|
||
"selection": {
|
||
"from": 120,
|
||
"to": 260,
|
||
"text": "待改写文本"
|
||
},
|
||
"action": "polish",
|
||
"tone": "professional",
|
||
"surroundingContext": {
|
||
"before": "选区前文",
|
||
"after": "选区后文"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 字段说明
|
||
|
||
### 6.1 `threadId`
|
||
|
||
用途：
|
||
|
||
- 关联当前 DeerFlow 线程
|
||
- 必要时取线程上下文或会话元数据
|
||
|
||
### 6.2 `documentId`
|
||
|
||
用途：
|
||
|
||
- 标识当前右侧文档
|
||
- 首版可选
|
||
- 如果当前系统还没有独立文档 ID，可先允许为空
|
||
|
||
### 6.3 `selection.from` / `selection.to`
|
||
|
||
用途：
|
||
|
||
- 帮助前后端联调排查
|
||
- 首版后端通常不需要真正使用偏移量
|
||
- 建议保留，便于日志定位
|
||
|
||
### 6.4 `selection.text`
|
||
|
||
用途：
|
||
|
||
- 这是本轮最核心输入
|
||
- 后端实际重写的主文本
|
||
|
||
### 6.5 `action`
|
||
|
||
允许值：
|
||
|
||
- `polish`
|
||
- `expand`
|
||
- `shorten`
|
||
- `tone`
|
||
|
||
### 6.6 `tone`
|
||
|
||
仅当 `action = tone` 时使用。
|
||
|
||
建议允许值：
|
||
|
||
- `professional`
|
||
- `casual`
|
||
- `readable`
|
||
- `academic`
|
||
- `expressive`
|
||
|
||
### 6.7 `surroundingContext.before`
|
||
|
||
用途：
|
||
|
||
- 提供选区前文
|
||
- 帮助模型理解语气、主语、叙事连续性
|
||
|
||
建议：
|
||
|
||
- 控制长度
|
||
- 不要塞太多无关上下文
|
||
|
||
### 6.8 `surroundingContext.after`
|
||
|
||
用途：
|
||
|
||
- 提供选区后文
|
||
- 帮助模型在扩写、改语气时与后续内容衔接
|
||
|
||
---
|
||
|
||
## 7. 返回体定义
|
||
|
||
建议返回体如下：
|
||
|
||
```json
|
||
{
|
||
"output": "AI 改写后的候选文本",
|
||
"originalSelection": {
|
||
"from": 120,
|
||
"to": 260,
|
||
"text": "待改写文本"
|
||
},
|
||
"metadata": {
|
||
"action": "polish",
|
||
"tone": null,
|
||
"model": "your-model-name"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 返回字段要求
|
||
|
||
## 8.1 `output`
|
||
|
||
必须：
|
||
|
||
- 只包含候选正文
|
||
- 尽量不夹带解释语
|
||
- 能直接被前端替换或插入
|
||
|
||
## 8.2 `originalSelection`
|
||
|
||
作用：
|
||
|
||
- 前端可以做校验
|
||
- 联调时方便确认是针对哪段文本返回的
|
||
|
||
## 8.3 `metadata`
|
||
|
||
作用：
|
||
|
||
- 便于埋点
|
||
- 便于日志记录
|
||
- 便于问题追踪
|
||
|
||
---
|
||
|
||
## 9. 错误响应规范
|
||
|
||
建议统一错误结构：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "WRITING_REWRITE_FAILED",
|
||
"message": "rewrite failed"
|
||
}
|
||
}
|
||
```
|
||
|
||
建议错误码：
|
||
|
||
- `WRITING_REWRITE_FAILED`
|
||
- `WRITING_INVALID_ACTION`
|
||
- `WRITING_INVALID_TONE`
|
||
- `WRITING_EMPTY_SELECTION`
|
||
- `WRITING_MODEL_UNAVAILABLE`
|
||
- `WRITING_CONTEXT_TOO_LARGE`
|
||
|
||
---
|
||
|
||
## 10. 动作语义定义
|
||
|
||
## 10.1 `polish`
|
||
|
||
目标：
|
||
|
||
- 保持原意
|
||
- 改善表达
|
||
- 提升通顺度、自然度和可读性
|
||
|
||
不应：
|
||
|
||
- 引入新事实
|
||
- 改写成完全不同内容
|
||
|
||
## 10.2 `expand`
|
||
|
||
目标：
|
||
|
||
- 保持主旨
|
||
- 扩充细节
|
||
- 增强画面感、解释性或完整度
|
||
|
||
不应：
|
||
|
||
- 无限制发散
|
||
- 添加明显脱离主题的新内容
|
||
|
||
## 10.3 `shorten`
|
||
|
||
目标：
|
||
|
||
- 压缩篇幅
|
||
- 保留关键信息
|
||
- 减少重复表达
|
||
|
||
不应：
|
||
|
||
- 丢失关键论点
|
||
- 压缩到语义残缺
|
||
|
||
## 10.4 `tone`
|
||
|
||
目标：
|
||
|
||
- 不改变原意
|
||
- 调整语言风格
|
||
|
||
不应：
|
||
|
||
- 改写事实
|
||
- 改写逻辑结构到完全不同
|
||
|
||
---
|
||
|
||
## 11. Prompt 设计原则
|
||
|
||
## 11.1 通用系统约束
|
||
|
||
所有改写类 prompt 都应包含以下约束：
|
||
|
||
- 直接输出最终可用正文
|
||
- 不输出标题，除非原文本身就是标题改写
|
||
- 不输出解释
|
||
- 不输出分析过程
|
||
- 不输出“以下是结果”之类前缀
|
||
- 保持与上下文语气一致
|
||
|
||
## 11.2 上下文使用原则
|
||
|
||
前后文只用于理解，不要求模型重写前后文。
|
||
|
||
明确告诉模型：
|
||
|
||
- 只改写选中文本
|
||
- 前后文仅用于参考衔接
|
||
|
||
## 11.3 长度控制原则
|
||
|
||
- `polish`：长度与原文接近
|
||
- `expand`：长度可明显增加，但不要失控
|
||
- `shorten`：长度明显缩短，但要保留关键信息
|
||
- `tone`：长度尽量与原文接近
|
||
|
||
---
|
||
|
||
## 12. Prompt 模板建议
|
||
|
||
## 12.1 润色模板
|
||
|
||
```text
|
||
你是一名中文写作编辑助手。
|
||
|
||
请在不改变原意的前提下，对“选中文本”进行润色，使表达更自然、更流畅、更清晰。
|
||
|
||
要求：
|
||
1. 保留原文事实和核心意思。
|
||
2. 不要添加原文没有的新事实。
|
||
3. 不要输出解释，不要输出前缀，不要输出分析过程。
|
||
4. 直接输出润色后的正文。
|
||
|
||
前文参考：
|
||
{before}
|
||
|
||
选中文本：
|
||
{selection}
|
||
|
||
后文参考：
|
||
{after}
|
||
```
|
||
|
||
## 12.2 扩写模板
|
||
|
||
```text
|
||
你是一名中文写作编辑助手。
|
||
|
||
请在不偏离主题的前提下，对“选中文本”进行扩写，增加必要细节、画面感或补充说明，使内容更充实。
|
||
|
||
要求：
|
||
1. 保持原文主旨不变。
|
||
2. 增加内容时要自然，不要跑题。
|
||
3. 不要输出解释，不要输出前缀，不要输出分析过程。
|
||
4. 直接输出扩写后的正文。
|
||
|
||
前文参考：
|
||
{before}
|
||
|
||
选中文本：
|
||
{selection}
|
||
|
||
后文参考：
|
||
{after}
|
||
```
|
||
|
||
## 12.3 缩写模板
|
||
|
||
```text
|
||
你是一名中文写作编辑助手。
|
||
|
||
请在保留关键信息和原意的前提下，对“选中文本”进行缩写，使其更精炼。
|
||
|
||
要求：
|
||
1. 不要丢掉核心信息。
|
||
2. 去掉重复、冗余和拖沓表达。
|
||
3. 不要输出解释，不要输出前缀，不要输出分析过程。
|
||
4. 直接输出缩写后的正文。
|
||
|
||
前文参考：
|
||
{before}
|
||
|
||
选中文本：
|
||
{selection}
|
||
|
||
后文参考：
|
||
{after}
|
||
```
|
||
|
||
## 12.4 改语气模板
|
||
|
||
```text
|
||
你是一名中文写作编辑助手。
|
||
|
||
请在不改变原意和事实的前提下，把“选中文本”改写成更{tone_label}的表达方式。
|
||
|
||
要求：
|
||
1. 保持原文信息不变。
|
||
2. 只调整表达风格，不改变事实和逻辑。
|
||
3. 不要输出解释，不要输出前缀，不要输出分析过程。
|
||
4. 直接输出改写后的正文。
|
||
|
||
前文参考：
|
||
{before}
|
||
|
||
选中文本：
|
||
{selection}
|
||
|
||
后文参考：
|
||
{after}
|
||
```
|
||
|
||
---
|
||
|
||
## 13. Tone 映射建议
|
||
|
||
建议前端传标准值，后端映射中文标签：
|
||
|
||
- `professional` -> 专业、正式
|
||
- `casual` -> 口语化、轻松自然
|
||
- `readable` -> 更易读、更清晰
|
||
- `academic` -> 学术、严谨
|
||
- `expressive` -> 更有文采、更有表现力
|
||
|
||
---
|
||
|
||
## 14. 上下文截取策略
|
||
|
||
## 14.1 推荐策略
|
||
|
||
前端传：
|
||
|
||
- 选区前固定长度文本
|
||
- 选区后固定长度文本
|
||
|
||
例如：
|
||
|
||
- 前文 200 到 500 字
|
||
- 后文 200 到 500 字
|
||
|
||
### 原因
|
||
|
||
- 足够帮助模型理解文气和衔接
|
||
- 不会让请求太重
|
||
|
||
## 14.2 不建议
|
||
|
||
- 把整篇长文全量塞进去
|
||
- 把整个线程消息都塞进改写接口
|
||
|
||
如果后端确实要参考线程上下文，也建议只取最近和写作相关的少量消息摘要。
|
||
|
||
---
|
||
|
||
## 15. LangGraph 接入建议
|
||
|
||
## 15.1 推荐接入方式
|
||
|
||
在现有 LangGraph / gateway 架构中新增一个写作改写专用入口。
|
||
|
||
建议二选一：
|
||
|
||
### 方案 A
|
||
|
||
新增专用 router：
|
||
|
||
- `POST /api/writing/rewrite`
|
||
|
||
内部调用现有模型层 / agent 层。
|
||
|
||
### 方案 B
|
||
|
||
新增专用 graph node 或 tool：
|
||
|
||
- `rewrite_selection`
|
||
|
||
再由 router 调用该能力。
|
||
|
||
## 15.2 更推荐方案
|
||
|
||
推荐：
|
||
|
||
- 对外暴露统一 router
|
||
- 内部走已有模型封装或 LangGraph 节点
|
||
|
||
这样前端接口更稳定，后续后端内部重构不会影响前端。
|
||
|
||
---
|
||
|
||
## 16. 后端模块拆解
|
||
|
||
## 16.1 模块 A：接口层
|
||
|
||
负责：
|
||
|
||
- 请求校验
|
||
- 错误响应
|
||
- 参数标准化
|
||
|
||
需要完成：
|
||
|
||
- 统一 rewrite API
|
||
- action / tone 校验
|
||
- 空选区校验
|
||
|
||
## 16.2 模块 B：上下文拼装层
|
||
|
||
负责：
|
||
|
||
- 拼装 before / selection / after
|
||
- 必要时提取线程相关信息
|
||
|
||
需要完成：
|
||
|
||
- 上下文长度控制
|
||
- 清洗空白和异常字符
|
||
|
||
## 16.3 模块 C：Prompt 层
|
||
|
||
负责：
|
||
|
||
- 选择模板
|
||
- 填充 action 和 tone
|
||
|
||
需要完成：
|
||
|
||
- 4 类动作模板
|
||
- tone 映射
|
||
|
||
## 16.4 模块 D：模型调用层
|
||
|
||
负责：
|
||
|
||
- 走现有模型配置体系
|
||
- 执行大模型请求
|
||
|
||
需要完成：
|
||
|
||
- 统一调用入口
|
||
- 模型不可用错误处理
|
||
|
||
## 16.5 模块 E：结果清洗层
|
||
|
||
负责：
|
||
|
||
- 去掉解释性前缀
|
||
- 去掉多余包裹
|
||
- 标准化返回
|
||
|
||
需要完成：
|
||
|
||
- 输出清洗
|
||
- metadata 填充
|
||
|
||
---
|
||
|
||
## 17. 返回结果清洗建议
|
||
|
||
即使 prompt 已经约束，模型仍可能输出：
|
||
|
||
- “以下是润色后的内容：”
|
||
- “当然，这里是改写结果：”
|
||
- “优化如下：”
|
||
|
||
建议后端加一层轻量清洗：
|
||
|
||
- 去掉常见说明性前缀
|
||
- 去掉包裹性 markdown 代码块
|
||
- 去掉多余首尾空白
|
||
|
||
注意：
|
||
|
||
- 清洗必须保守
|
||
- 不要误删正文
|
||
|
||
---
|
||
|
||
## 18. 日志与观测建议
|
||
|
||
建议记录：
|
||
|
||
- `threadId`
|
||
- `documentId`
|
||
- `action`
|
||
- `tone`
|
||
- `selection_length`
|
||
- `before_length`
|
||
- `after_length`
|
||
- `model_name`
|
||
- `latency_ms`
|
||
- `success / fail`
|
||
|
||
不要直接把整段用户正文原文打到普通日志里，避免敏感信息风险。
|
||
|
||
---
|
||
|
||
## 19. 后端测试清单
|
||
|
||
## 19.1 单元测试
|
||
|
||
- action 校验
|
||
- tone 校验
|
||
- 空选区校验
|
||
- prompt 选择逻辑
|
||
- 输出清洗逻辑
|
||
|
||
## 19.2 集成测试
|
||
|
||
- `polish`
|
||
- `expand`
|
||
- `shorten`
|
||
- `tone-professional`
|
||
- `tone-casual`
|
||
- `tone-readable`
|
||
- `tone-academic`
|
||
- `tone-expressive`
|
||
|
||
## 19.3 边界测试
|
||
|
||
- 选区过短
|
||
- 选区过长
|
||
- 前后文为空
|
||
- 多段文本带换行
|
||
- 模型超时
|
||
- 模型不可用
|
||
|
||
---
|
||
|
||
## 20. 联调约束
|
||
|
||
## 20.1 前后端必须统一
|
||
|
||
- `action` 枚举值
|
||
- `tone` 枚举值
|
||
- 错误码
|
||
- 返回体字段名
|
||
|
||
## 20.2 联调重点
|
||
|
||
- 多段落文本中换行保留是否正确
|
||
- AI 返回内容是否适合直接落文档
|
||
- 超时和失败时前端是否能优雅重试
|
||
|
||
## 20.3 联调建议顺序
|
||
|
||
1. 先 mock 返回固定文本
|
||
2. 再接真实模型
|
||
3. 先验证单段落
|
||
4. 再验证多段落
|
||
5. 最后验证大段文本
|
||
|
||
---
|
||
|
||
## 21. 优先级建议
|
||
|
||
### P0
|
||
|
||
- 统一 rewrite API
|
||
- 4 类动作支持
|
||
- 输出纯净正文
|
||
- 错误结构标准化
|
||
|
||
### P1
|
||
|
||
- 输出清洗增强
|
||
- 埋点与日志
|
||
- 上下文截断策略优化
|
||
|
||
### P2
|
||
|
||
- 更细粒度风格控制
|
||
- 结果质量二次校验
|
||
|
||
---
|
||
|
||
## 22. 完成定义
|
||
|
||
后端满足以下条件即可视为本轮完成：
|
||
|
||
- 前端能通过统一接口发起改写
|
||
- 4 类动作均可稳定返回候选文本
|
||
- 返回文本基本可直接用于替换或插入
|
||
- 多段落文本能稳定处理
|
||
- 错误结构规范统一
|
||
|
||
---
|
||
|
||
## 23. 结论
|
||
|
||
本轮后端最重要的，不是做复杂文档结构编辑，而是把“选区改写”做成稳定、可预测、可直接接入前端编辑器的能力。
|
||
|
||
最稳妥的路线是：
|
||
|
||
- 统一接口
|
||
- 统一动作枚举
|
||
- 统一 prompt 模板
|
||
- 统一错误结构
|
||
- 统一输出约束
|
||
|
||
只要这层做稳，前端的 Tiptap 写作编辑器就能很顺畅地完成豆包式“选中即改、预览后应用”的核心体验。
|