823 lines
32 KiB
Markdown
823 lines
32 KiB
Markdown
# 沙箱统一写作管线：可实现开发方案
|
||
|
||
> 状态：设计稿；本文件只定义实施方案，不包含本轮业务代码改动。
|
||
> 覆盖范围：普通沙箱 Markdown、深度研究 `report.md`、现有 Markdown 编辑器的选区/段落改写。
|
||
|
||
## 1. 目标与结论
|
||
|
||
目标不是再增加一个“AI 写作页面”，而是将现有的四类能力统一为一个安全、可流式、可追溯的**文档改写管线**：
|
||
|
||
1. Markdown 编辑器选区改写；
|
||
2. Markdown 编辑器段落改写；
|
||
3. 深度研究报告的局部候选改写；
|
||
4. 沙箱中 Markdown 文件的全文改写。
|
||
|
||
该管线负责固定原文版本、构造上下文、逐 token 输出、校验 Markdown、生成可核验 diff、按策略提交，以及在全文覆盖时保存可撤销版本。
|
||
|
||
结论：需求可行，现有工程已有足够的复用基础：
|
||
|
||
- `frontend-web/src/open-canvas/components/artifact/MarkdownAiEditor.tsx` 已具备局部改写弹窗与人工“替换/插入/重试/追问”交互。
|
||
- `frontend-web/src/open-canvas/hooks/useWritingRewrite.ts` 与 `frontend-web/src/open-canvas/api/rewrite.ts` 已具备 SSE 文本流消费。
|
||
- `offline-backend-20260512/backend/app/gateway/routers/writing.py` 已具备模型流式读取实现。
|
||
- `offline-backend-20260512/backend/app/gateway/routers/deep_research.py` 已具备报告哈希、候选内容和用户确认应用机制。
|
||
- `frontend-web/src/components/workspace/messages/message-list.tsx`、`MessageGroup.tsx` 已可承载普通对话的工具步骤条、流式消息和文件卡片。
|
||
- `frontend-web/src/pages/deep-research/DeepResearchWorkbench.tsx` 已经通过虚拟消息把研究进度接入普通 `MessageList`。
|
||
|
||
因此应该复用这些基础，建设一个执行内核；不能为全文改写另建独立聊天列表或独立写作流。
|
||
|
||
## 2. 产品边界与交互策略
|
||
|
||
### 2.1 支持范围
|
||
|
||
第一版仅对 `.md`、`.markdown` 文件显示“AI 全文改写”按钮。
|
||
|
||
不支持 PDF、DOCX、HTML、图片和二进制文件；不在改写过程中发起新的联网搜索；超大文件不静默截断后覆盖，而是提示用户选择章节改写。
|
||
|
||
### 2.2 范围、模式和提交策略
|
||
|
||
| 入口 | 文本范围 | 管线模式 | 提交策略 | 展示位置 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 编辑器气泡菜单 | 当前选区 | `selection` | `preview_only` | 现有改写预览弹窗 |
|
||
| 编辑器段落菜单 | 当前段落 | `paragraph` | `preview_only` | 现有改写预览弹窗 |
|
||
| 深度研究“改写第一段/章节” | 被解析出的报告片段 | `report_section` | `manual_apply` | 普通消息列表候选稿 + 确认卡 |
|
||
| 文件右上角“AI 全文改写” | 当前完整 Markdown | `document` | `auto_commit_after_validation` | 普通消息列表步骤条 + 右侧沙箱 |
|
||
|
||
统一内核中的枚举：
|
||
|
||
~~~python
|
||
class RewriteMode(str, Enum):
|
||
SELECTION = "selection"
|
||
PARAGRAPH = "paragraph"
|
||
REPORT_SECTION = "report_section"
|
||
DOCUMENT = "document"
|
||
|
||
class CommitPolicy(str, Enum):
|
||
PREVIEW_ONLY = "preview_only"
|
||
MANUAL_APPLY = "manual_apply"
|
||
AUTO_COMMIT_AFTER_VALIDATION = "auto_commit_after_validation"
|
||
~~~
|
||
|
||
这三类策略必须严格区分：
|
||
|
||
- `preview_only`：只生成候选，前端编辑器确认后才改本地 TipTap 文档；不写真实沙箱文件。
|
||
- `manual_apply`：后端保留基准哈希和候选片段，用户点确认后才将该片段应用进研究报告。
|
||
- `auto_commit_after_validation`：全文生成完成并校验通过后，后端进行一次带哈希校验的原子覆盖；同时保存可撤销版本。
|
||
|
||
### 2.3 局部编辑器：保持当前体验
|
||
|
||
现有文件：
|
||
|
||
- `frontend-web/src/open-canvas/components/artifact/MarkdownAiEditor.tsx`
|
||
- `frontend-web/src/open-canvas/hooks/useWritingRewrite.ts`
|
||
- `frontend-web/src/open-canvas/api/rewrite.ts`
|
||
- `offline-backend-20260512/backend/app/gateway/routers/writing.py`
|
||
|
||
局部改写仍然是：
|
||
|
||
1. 选中文字或打开段落菜单；
|
||
2. 选择润色、扩写、缩写、改写等动作；
|
||
3. 在现有弹窗中流式出现候选；
|
||
4. 用户手动选择替换、插入、重试或继续追问。
|
||
|
||
不要让局部改写每次都往普通消息列表插完整步骤条，否则频繁编辑会淹没聊天历史。它只共享底层管线，不共享全文改写的消息展示方式。
|
||
|
||
需要补充本地版本保护：发起请求时保存当前完整编辑器文本哈希、选区 `from/to` 和选区文本；用户点击“替换原文”前再次检查该范围仍匹配。若用户已修改原文，提示“原文已变化，请重新生成候选稿”，禁止将过期候选替换到错误位置。
|
||
|
||
### 2.4 右上角“AI 全文改写”
|
||
|
||
宿主文件：
|
||
|
||
- `frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx`
|
||
|
||
新增独立图标按钮，位置在右上角文件操作区，靠近保存、复制、下载一类操作。它**不能**替代页面中间当前 Sparkles 编辑模式：
|
||
|
||
| 控件 | 职责 |
|
||
| --- | --- |
|
||
| 中部 Sparkles/编辑模式 | 打开 `MarkdownAiEditor`，处理选区和段落 |
|
||
| 新增右上角 AI 全文改写 | 对整个 Markdown 发起后台全文重写任务 |
|
||
|
||
建议显示条件：
|
||
|
||
~~~ts
|
||
const canUseFullDocumentRewrite =
|
||
isMarkdownFile &&
|
||
canEditArtifact &&
|
||
!isSkillFile &&
|
||
!isMock &&
|
||
!useWriteFileStreaming &&
|
||
!hasLocalEdits;
|
||
~~~
|
||
|
||
若 `hasLocalEdits` 为真，按钮置灰并提示“请先保存当前修改后再进行全文改写”。后端全文任务从真实文件读取快照，不能在用户本地还有未保存修改时读取旧版本并最终覆盖新修改。
|
||
|
||
用户体验：
|
||
|
||
1. 点击按钮，打开简洁配置弹窗。
|
||
2. 弹窗显示文件名、原文字数；用户填写改写要求、选择模型、选择风格。
|
||
3. 点击开始，左侧普通消息列表创建一组步骤条。
|
||
4. 右侧沙箱自动切到源码视图，先显示“正在准备临时草稿，原文件尚未修改”。
|
||
5. 新 Markdown 从空临时草稿开始逐 token 写入右侧代码区域。
|
||
6. 校验通过后，后端原子替换真实内容；前端再同步真实 Artifact 缓存。
|
||
7. 左侧保留最终对比总结、查看 diff 按钮和撤销按钮。
|
||
|
||
任务进行中，同一个文件的保存、直接编辑、局部编辑和再次全文改写必须禁用；其他文件不受影响。
|
||
|
||
### 2.5 深度研究报告的约束
|
||
|
||
普通 Markdown 和深度研究报告使用同一管线，但不能使用同一上下文策略：
|
||
|
||
| 能力 | 普通沙箱 Markdown | 深度研究 report.md |
|
||
| --- | --- | --- |
|
||
| 输入上下文 | 原文 + 用户指令 | 原文 + 当前会话已选资料 |
|
||
| 联网 | 不联网 | 不联网 |
|
||
| 事实约束 | 不新增无依据事实 | 只能引用已选资料，禁止编造 |
|
||
| 引用校验 | 可选 | 必须校验来源 ID 白名单 |
|
||
| 最终存储 | Artifact 文件 | 研究 session 的 `report_markdown` |
|
||
| 局部改写 | 编辑器确认 | 现有确认卡片 |
|
||
|
||
深度研究右侧的 `report.md` 是由 `ResearchSandboxPanel.tsx` 以虚拟 `write_file` 方式展示的；它不能当作普通磁盘 Artifact 直接写入。全文任务必须通过研究 session 更新 `report_markdown`，并使 `report_html` 缓存失效。
|
||
|
||
## 3. 总体架构
|
||
|
||
~~~mermaid
|
||
flowchart LR
|
||
A["MarkdownAiEditor<br/>选区 / 段落"] --> P
|
||
B["ArtifactFileDetail<br/>AI 全文改写"] --> P
|
||
C["DeepResearch<br/>局部 / 全文"] --> P
|
||
|
||
P["Document Rewrite Pipeline<br/>冻结版本 → 构造上下文 → 流式生成<br/>校验 → 差异总结 → 按策略提交"]
|
||
|
||
P --> I["InlineDocumentSource"]
|
||
P --> F["ArtifactDocumentSource"]
|
||
P --> R["DeepResearchReportSource"]
|
||
|
||
P --> E["可恢复 SSE 事件 / Job"]
|
||
E --> L["普通 MessageList"]
|
||
E --> S["右侧沙箱临时草稿"]
|
||
P --> V["内容哈希、版本快照、原子提交"]
|
||
~~~
|
||
|
||
设计原则：
|
||
|
||
1. 纯执行内核不依赖 FastAPI、路由、用户身份或操作系统路径。
|
||
2. 鉴权、线程路径解析、研究 session 获取只在 `app` 层的来源适配器中完成。
|
||
3. 完整文档任务使用持久化后台 Job；局部弹窗可维持单次 SSE，避免过度持久化。
|
||
4. 全文流式过程中只写临时草稿；真实内容只在最终 compare-and-swap 成功时改变。
|
||
|
||
不要直接把现有完整“AI 写作 Agent”塞进改写按钮。那个流程适合从主题写新文章，可能包含大纲、资料和章节生命周期；本需求是严格以当前文档为基准改写。第一版复用它的流式视觉表达和消息列表能力，但使用专门的文档改写执行内核。
|
||
|
||
## 4. 后端模块设计
|
||
|
||
### 4.1 目录与职责
|
||
|
||
建议新增：
|
||
|
||
~~~text
|
||
offline-backend-20260512/backend/
|
||
├─ packages/harness/deerflow/
|
||
│ ├─ document_rewrite/
|
||
│ │ ├─ __init__.py
|
||
│ │ ├─ models.py # 请求、事件、校验、差异领域模型
|
||
│ │ ├─ ports.py # Source / Model / Store 协议
|
||
│ │ ├─ pipeline.py # 统一编排，不导入 app.*
|
||
│ │ ├─ prompt_builder.py # 普通与深度研究提示词
|
||
│ │ ├─ validation.py # Markdown / 引用 / 截断检查
|
||
│ │ └─ diff_summary.py # 字数、标题、块、引用差异
|
||
│ └─ persistence/
|
||
│ └─ document_rewrites/
|
||
│ ├─ base.py
|
||
│ ├─ model.py
|
||
│ └─ sql.py
|
||
├─ app/gateway/
|
||
│ ├─ routers/document_rewrites.py
|
||
│ ├─ document_rewrite_sources.py
|
||
│ └─ document_rewrite_executor.py
|
||
└─ packages/harness/deerflow/persistence/migrations/versions/
|
||
└─ <next_revision>_document_rewrites.py
|
||
~~~
|
||
|
||
`packages/harness/deerflow/document_rewrite` 不能导入 `app.*`，以符合项目 harness→app import firewall。`app/gateway/document_rewrite_sources.py` 负责把已鉴权的 Artifact/研究会话包装成内核端口。
|
||
|
||
### 4.2 来源端口
|
||
|
||
~~~python
|
||
class DocumentSource(Protocol):
|
||
async def read_snapshot(self) -> DocumentSnapshot: ...
|
||
async def read_current_hash(self) -> str: ...
|
||
async def commit_if_unchanged(
|
||
self,
|
||
*,
|
||
expected_hash: str,
|
||
content: str,
|
||
metadata: CommitMetadata,
|
||
) -> CommitResult: ...
|
||
async def restore_if_unchanged(
|
||
self,
|
||
*,
|
||
expected_hash: str,
|
||
content: str,
|
||
) -> CommitResult: ...
|
||
~~~
|
||
|
||
三种实现：
|
||
|
||
| 适配器 | 使用场景 | 读取方式 | 提交方式 |
|
||
| --- | --- | --- | --- |
|
||
| `InlineDocumentSource` | 选区/段落候选 | 前端编辑器快照 | 不提交 |
|
||
| `ArtifactDocumentSource` | 普通 Markdown | 复用 Artifact 权限与虚拟路径解析 | 同目录临时文件 + `os.replace` |
|
||
| `DeepResearchReportSource` | 研究报告 | session `report_markdown` + 已选来源 | 数据库哈希条件更新 |
|
||
|
||
`ArtifactDocumentSource` 必须复用 `app/gateway/routers/artifacts.py` 中已有的线程访问校验、虚拟路径解析逻辑，绝不允许请求体传入任意本机绝对路径。
|
||
|
||
### 4.3 持久化 Job、事件和版本
|
||
|
||
全文改写使用持久化 Job，参考 `app/gateway/deep_research_job_executor.py` 的后台任务、租约、取消监听和事件重放模式。
|
||
|
||
#### document_rewrite_jobs
|
||
|
||
| 字段 | 作用 |
|
||
| --- | --- |
|
||
| `id` | `drw_xxx` Job ID |
|
||
| `user_id` | 发起人 |
|
||
| `source_kind` | `artifact` / `deep_research_report` |
|
||
| `thread_id`、`artifact_path` | 普通文件来源 |
|
||
| `research_session_id` | 研究报告来源 |
|
||
| `presentation_thread_id` | 普通消息列表归属 |
|
||
| `mode`、`commit_policy` | 范围和提交语义 |
|
||
| `instruction`、`style`、`model_name` | 用户配置 |
|
||
| `base_sha256` | 原文冻结哈希 |
|
||
| `draft_content`、`draft_sha256` | 临时流式草稿 |
|
||
| `status`、`stage` | 生命周期 |
|
||
| `validation_json`、`diff_summary_json` | 可展示结果 |
|
||
| `committed_sha256` | 成功提交后的哈希 |
|
||
| `error_message`、时间字段 | 错误、审计、取消 |
|
||
|
||
#### document_rewrite_events
|
||
|
||
至少包含 `job_id`、`seq`、`event_type`、`stage`、`payload_json`、`created_at`。`seq` 用于断线重连时通过 `after_seq` 重放。
|
||
|
||
不必将每个 token 单独入库：每 250ms 或每积累 4KB 持久化一次 `draft_content`；状态转换、警告、完成、冲突、取消必须立即写事件。重连时先发送最新草稿快照，再发送快照序号后的增量事件。
|
||
|
||
#### document_rewrite_versions
|
||
|
||
保存真实全文覆盖前的原文版本，字段包含 `job_id`、`source_identity`、`version_no`、`content`、`sha256`、`reason`、`created_at`。初版每个文档保留最近 20 个版本即可。
|
||
|
||
索引要求：
|
||
|
||
- `(user_id, presentation_thread_id, created_at DESC)`：恢复历史消息。
|
||
- 真实来源标识 + 活跃状态：防止同一文档并行两个全文改写。
|
||
|
||
### 4.4 Job 状态机
|
||
|
||
~~~mermaid
|
||
stateDiagram-v2
|
||
[*] --> queued
|
||
queued --> snapshotting
|
||
snapshotting --> generating
|
||
generating --> validating
|
||
validating --> comparing
|
||
comparing --> committing
|
||
committing --> completed
|
||
completed --> reverted
|
||
|
||
queued --> cancelled
|
||
generating --> cancelled
|
||
snapshotting --> failed
|
||
generating --> failed
|
||
validating --> failed
|
||
committing --> conflict
|
||
committing --> failed
|
||
~~~
|
||
|
||
状态约束：
|
||
|
||
- 同一真实文档只允许一个活跃 Job。
|
||
- 生成期间取消、异常、断线，真实文档绝不能变化。
|
||
- 提交前重新读取当前哈希；与 `base_sha256` 不一致时进入 `conflict`，草稿保留但不覆盖。
|
||
|
||
### 4.5 API 与 SSE 契约
|
||
|
||
创建全文任务：
|
||
|
||
~~~http
|
||
POST /api/document-rewrites
|
||
Content-Type: application/json
|
||
~~~
|
||
|
||
普通 Artifact 请求：
|
||
|
||
~~~json
|
||
{
|
||
"source": {
|
||
"kind": "artifact",
|
||
"thread_id": "thread_xxx",
|
||
"path": "/mnt/user-data/outputs/report.md"
|
||
},
|
||
"presentation_thread_id": "thread_xxx",
|
||
"mode": "document",
|
||
"instruction": "统一为正式行业分析语气，减少重复，不新增外部事实",
|
||
"style": "formal_analysis",
|
||
"model_name": "system_default"
|
||
}
|
||
~~~
|
||
|
||
深度研究请求：
|
||
|
||
~~~json
|
||
{
|
||
"source": {
|
||
"kind": "deep_research_report",
|
||
"session_id": "drs_xxx"
|
||
},
|
||
"presentation_thread_id": "collector_thread_xxx",
|
||
"mode": "document",
|
||
"instruction": "重新组织全文逻辑，保留全部可用引用",
|
||
"style": "formal_analysis",
|
||
"model_name": "system_default"
|
||
}
|
||
~~~
|
||
|
||
其他接口：
|
||
|
||
~~~text
|
||
GET /api/document-rewrites/{job_id}
|
||
GET /api/document-rewrites/{job_id}/stream?after_seq=42
|
||
POST /api/document-rewrites/{job_id}/cancel
|
||
POST /api/document-rewrites/{job_id}/undo
|
||
GET /api/document-rewrites?presentation_thread_id={thread_id}
|
||
~~~
|
||
|
||
SSE 事件：
|
||
|
||
| 事件 | 关键数据 | 前端动作 |
|
||
| --- | --- | --- |
|
||
| `job_started` | 文件名、模式 | 建立步骤条 |
|
||
| `snapshot_fixed` | 原文字数、哈希 | 完成“固定原文版本” |
|
||
| `requirements_resolved` | 模型、风格、要求 | 完成“理解改写要求” |
|
||
| `rewrite_delta` | `delta`、累计字符数 | 追加右侧临时草稿 |
|
||
| `validation_started` | 校验项 | 进入校验步骤 |
|
||
| `validation_completed` | passed、warnings | 显示校验结果 |
|
||
| `comparison_ready` | `DiffSummary` | 渲染总结数据 |
|
||
| `commit_started` | 无 | 显示安全替换中 |
|
||
| `committed` | 最终哈希、版本 ID | 刷新真实文件缓存 |
|
||
| `completed` | 完整结果 | 固化历史步骤条 |
|
||
| `conflict` / `error` / `cancelled` | 原因 | 恢复原文显示，不保存草稿 |
|
||
|
||
局部改写兼容方案：
|
||
|
||
- `POST /api/writing/rewrite` 的请求和 SSE 格式先不变。
|
||
- `writing.py` 内部逐步把 prompt、模型流、基础 Markdown 校验下沉给统一管线的 `preview_only` 分支。
|
||
- 深度研究 `/sessions/{id}/rewrite/stream` 和确认候选接口也先保持 URL、前端行为不变，再内部复用 `manual_apply` 分支。
|
||
|
||
这样可以先交付全文改写，不会一次性破坏已有编辑器和深度研究流程。
|
||
|
||
### 4.6 模型、提示词与校验
|
||
|
||
管线只依赖一个流式模型端口：
|
||
|
||
~~~python
|
||
class StreamingRewriteModel(Protocol):
|
||
async def stream_text(
|
||
self,
|
||
*,
|
||
messages: list[BaseMessage],
|
||
model_name: str | None,
|
||
) -> AsyncIterator[TextChunk]: ...
|
||
~~~
|
||
|
||
第一版可以有两个 adapter：
|
||
|
||
- 普通文档复用 `writing.py` 的 chat model `astream`；
|
||
- 深度研究复用 `deep_research.py` 使用的 `DeerFlowCompletionBackend.stream_complete`。
|
||
|
||
先统一编排，不强制立即统一所有模型配置实现。
|
||
|
||
普通 Markdown 系统约束：
|
||
|
||
~~~text
|
||
仅根据原文与用户要求改写，不联网，不补充未给出的事实。
|
||
保留有效链接、代码块、表格、标题语义和用户明确要求保留的内容。
|
||
只输出完整 Markdown 正文；不得输出解释、前缀或“改写如下”。
|
||
~~~
|
||
|
||
深度研究额外约束：
|
||
|
||
~~~text
|
||
不得联网。事实、数字、结论和引用只能来自当前 session 已选资料。
|
||
只允许使用给出的 source_id；资料不足时保持谨慎表述，禁止自行补全。
|
||
~~~
|
||
|
||
校验规则：
|
||
|
||
| 类别 | 硬失败 | 告警但允许完成 |
|
||
| --- | --- | --- |
|
||
| 正文 | 空文档、仅空白、无可见内容 | 改写后与原文完全一致 |
|
||
| Markdown | 未闭合围栏、明确截断 | 标题层级跳级、章节数明显减少 |
|
||
| 深度研究来源 | 未选来源 ID、非法引用 | 引用数量下降、可能需核验的数字断言 |
|
||
|
||
## 5. 安全提交、对比与撤销
|
||
|
||
### 5.1 临时草稿不等于真实文件
|
||
|
||
用户视觉上看到“先清空再逐 token 写入”，但真实文件的处理必须是：
|
||
|
||
1. 读取原文并保存内容哈希、版本快照。
|
||
2. 右侧只展示内存/Job 中的 `draft_content`。
|
||
3. 生成完成后做校验和 diff。
|
||
4. 提交前再次读取真实来源，并比较 `SHA-256`。
|
||
5. 哈希一致才原子替换；否则进入冲突，不覆盖。
|
||
|
||
普通 Artifact 使用同目录临时文件、刷盘和 `os.replace`；深度研究通过数据库事务内的“旧哈希条件更新”提交。任何失败、取消或断流都保留真实原文。
|
||
|
||
### 5.2 撤销
|
||
|
||
撤销流程：
|
||
|
||
1. 读取该 Job 的 `before_full_rewrite` 快照。
|
||
2. 确认当前真实内容哈希仍等于该 Job 的 `committed_sha256`。
|
||
3. 若用户在改写后又手工编辑，返回冲突，不盲目覆盖。
|
||
4. 先保存当前内容为 `before_undo` 版本。
|
||
5. 原子恢复旧版本，Job 状态改为 `reverted`，消息列表卡片同步显示“已撤销”。
|
||
|
||
### 5.3 结构化 DiffSummary
|
||
|
||
后端产出结构化差异，前端仅渲染，避免生成空泛结论：
|
||
|
||
~~~ts
|
||
type DiffSummary = {
|
||
sourceDisplayName: string;
|
||
instruction: string;
|
||
modelName: string;
|
||
originalCharCount: number;
|
||
rewrittenCharCount: number;
|
||
charChangeRatio: number;
|
||
changedBlockCount: number;
|
||
headings: {
|
||
added: string[];
|
||
removed: string[];
|
||
reordered: string[];
|
||
levelWarnings: string[];
|
||
};
|
||
citations?: {
|
||
beforeCount: number;
|
||
afterCount: number;
|
||
retainedCount: number;
|
||
removedIds: string[];
|
||
invalidIds: string[];
|
||
};
|
||
requestedOptimizations: string[];
|
||
validationWarnings: string[];
|
||
};
|
||
~~~
|
||
|
||
推荐总结展示：
|
||
|
||
~~~text
|
||
已完成《新能源汽车市场分析报告》的整体改写。
|
||
|
||
- 改写范围：全文；要求为“统一正式分析语气、减少重复”；模型：默认模型。
|
||
- 数量变化：原文 8,260 字，改写后 8,110 字，减少 1.8%；调整 14 个内容块。
|
||
- 结构变化：标题层级保持不变；未新增或删除一级标题。
|
||
- 已执行的优化：按要求合并重复表述、统一语气、调整段落衔接。
|
||
- 保留情况：保留 35 条已选来源引用，未新增外部来源。
|
||
- 风险提示：无。
|
||
|
||
[查看前后对比] [撤销到改写前版本]
|
||
~~~
|
||
|
||
“已执行的优化”仅来自用户要求和可计算的结构差异；不能无依据宣称“文章更专业、更严谨”。
|
||
|
||
## 6. 前端实现设计
|
||
|
||
### 6.1 新增模块
|
||
|
||
~~~text
|
||
frontend-web/src/core/document-rewrite/
|
||
├─ types.ts
|
||
├─ api.ts
|
||
├─ sse.ts
|
||
├─ use-document-rewrite-job.ts
|
||
├─ document-rewrite-provider.tsx
|
||
└─ document-rewrite-presentation.ts
|
||
|
||
frontend-web/src/components/workspace/document-rewrite/
|
||
├─ DocumentRewriteDialog.tsx
|
||
├─ DocumentRewriteProgressStep.tsx
|
||
├─ DocumentRewriteSummaryCard.tsx
|
||
└─ DocumentDiffDialog.tsx
|
||
~~~
|
||
|
||
职责：
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `api.ts` | 创建、查询、取消、撤销 Job |
|
||
| `sse.ts` | SSE 解析、`after_seq` 重连 |
|
||
| `use-document-rewrite-job.ts` | Job 状态、草稿、rAF 合并 token |
|
||
| Provider | 同时向文件面板与消息列表提供同一任务状态 |
|
||
| `DocumentRewriteDialog` | 改写要求、模型、风格配置 |
|
||
| ProgressStep | 普通消息列表内的五步步骤条 |
|
||
| SummaryCard | 结构化总结、diff、撤销动作 |
|
||
| DiffDialog | 原文与改写后双栏/行级对比 |
|
||
|
||
模型选择使用项目已有的 `tdesign-react` 选择组件，放在全文改写配置弹窗中；局部编辑器保留当前模型传递方式，后续再统一选择器。
|
||
|
||
### 6.2 流式平滑：每帧合并 delta
|
||
|
||
不能因为 SSE 是 token 流就每 token 调一次 `setState`。应当网络层完整读取、渲染层按动画帧合并：
|
||
|
||
~~~ts
|
||
const pendingDeltaRef = useRef("");
|
||
const frameRef = useRef<number | null>(null);
|
||
|
||
function onRewriteDelta(delta: string) {
|
||
pendingDeltaRef.current += delta;
|
||
if (frameRef.current !== null) return;
|
||
|
||
frameRef.current = requestAnimationFrame(() => {
|
||
const pending = pendingDeltaRef.current;
|
||
pendingDeltaRef.current = "";
|
||
frameRef.current = null;
|
||
setDraftContent((previous) => previous + pending);
|
||
});
|
||
}
|
||
~~~
|
||
|
||
完成、失败、取消前必须 flush 最后一段缓存。右侧代码编辑器只消费 `draftContent`；真实 Artifact 查询缓存直到 `committed` 事件才更新。
|
||
|
||
### 6.3 ArtifactFileDetail 改造
|
||
|
||
在 `artifact-file-detail.tsx` 增加：
|
||
|
||
~~~ts
|
||
type DocumentRewriteTarget =
|
||
| {
|
||
kind: "artifact";
|
||
threadId: string;
|
||
path: string;
|
||
presentationThreadId: string;
|
||
}
|
||
| {
|
||
kind: "deep_research_report";
|
||
sessionId: string;
|
||
presentationThreadId: string;
|
||
};
|
||
~~~
|
||
|
||
改造步骤：
|
||
|
||
1. 加入右上角全文改写图标按钮和 `DocumentRewriteDialog`。
|
||
2. 有活跃任务时强制 `viewMode = "code"`。
|
||
3. 内容优先级为：`activeRewrite.draftContent ?? draftContent ?? artifactContent`。
|
||
4. 活跃任务中代码只读，禁用保存、局部编辑和重复全文改写。
|
||
5. 收到 `committed` 后用现有 `useUpdateArtifactContent` 或等价 Query cache 更新，使真实文件立即同步。
|
||
6. 收到 `conflict/error/cancelled` 时废弃临时草稿显示，回到真实文件内容。
|
||
|
||
### 6.4 ResearchSandboxPanel 接入
|
||
|
||
相关文件：
|
||
|
||
- `frontend-web/src/pages/deep-research/ResearchSandboxPanel.tsx`
|
||
- `frontend-web/src/pages/deep-research/useReportSandbox.ts`
|
||
- `frontend-web/src/pages/deep-research/DeepResearchWorkbench.tsx`
|
||
|
||
改造：
|
||
|
||
1. `ResearchSandboxPanel` 为虚拟 `report.md` 传入 `kind: "deep_research_report"` target。
|
||
2. `useReportSandbox` 接受 `externalDraftOverride`：
|
||
|
||
~~~ts
|
||
const visibleReport = activeDocumentRewrite?.isActive
|
||
? activeDocumentRewrite.draftContent
|
||
: reportMarkdown;
|
||
~~~
|
||
|
||
3. 流式期间只显示临时草稿，不提前写 session 报告。
|
||
4. `committed` 后刷新/替换 session 的 `report_markdown`；失败后恢复旧报告。
|
||
5. 当前“改写第一段 → 候选消息 → 确认应用”逻辑继续保留，不因全文改写而改变。
|
||
|
||
### 6.5 普通消息列表接入
|
||
|
||
复用：
|
||
|
||
- `frontend-web/src/components/workspace/messages/message-list.tsx`
|
||
- `frontend-web/src/components/workspace/messages/MessageGroup.tsx`
|
||
- `DeepResearchWorkbench.tsx` 中的虚拟消息注入模式。
|
||
|
||
`DocumentRewritePresentationProvider` 按 `presentation_thread_id` 读取 Job 历史并投影为：
|
||
|
||
1. 用户消息：“AI 全文改写《xxx.md》”；
|
||
2. AI 工具调用：`document_rewrite_progress`；
|
||
3. AI 富消息：`document_rewrite_summary`。
|
||
|
||
`MessageGroup.tsx` 增加 `document_rewrite_progress` 分支，渲染 `DocumentRewriteProgressStep`。最终摘要渲染 `DocumentRewriteSummaryCard`，其内含“查看前后对比”和“撤销”。
|
||
|
||
全文步骤固定为：
|
||
|
||
| 步骤 | 展示内容 |
|
||
| --- | --- |
|
||
| 固定原文版本 | 文件名、原文字数、快照已保存 |
|
||
| 理解改写要求 | 改写目标、模型、风格 |
|
||
| 流式重写 Markdown | 正在写入右侧 xxx.md、累计字数 |
|
||
| 校验文档 | 非空、标题、围栏、截断；报告还含来源检查 |
|
||
| 对比原文并生成说明 | 差异、风险、撤销入口 |
|
||
|
||
步骤条必须在完成后保留，不能因为流结束被隐藏。
|
||
|
||
## 7. 核心执行伪代码
|
||
|
||
~~~python
|
||
async def run_document_rewrite(job_id: str) -> None:
|
||
job = await jobs.acquire_lease(job_id)
|
||
source = source_factory.create(job) # 已完成鉴权的来源适配器
|
||
|
||
await emit("snapshotting")
|
||
snapshot = await source.read_snapshot()
|
||
base_hash = sha256(snapshot.content)
|
||
await jobs.freeze_snapshot(job_id, snapshot, base_hash)
|
||
await emit("snapshot_fixed", char_count=count_chars(snapshot.content))
|
||
|
||
messages = prompt_builder.build(
|
||
mode=job.mode,
|
||
source_kind=job.source_kind,
|
||
original=snapshot.content,
|
||
instruction=job.instruction,
|
||
style=job.style,
|
||
research_sources=snapshot.allowed_sources,
|
||
)
|
||
await emit("requirements_resolved", ...)
|
||
|
||
draft = ""
|
||
async for chunk in model.stream_text(messages=messages, model_name=job.model_name):
|
||
if await jobs.cancel_requested(job_id):
|
||
await jobs.mark_cancelled(job_id)
|
||
await emit("cancelled")
|
||
return
|
||
draft += chunk.text
|
||
await jobs.append_draft_periodically(job_id, draft)
|
||
await emit("rewrite_delta", delta=chunk.text)
|
||
|
||
await emit("validation_started")
|
||
validation = validate_markdown(
|
||
draft,
|
||
source_kind=job.source_kind,
|
||
allowed_citations=snapshot.allowed_citation_ids,
|
||
)
|
||
if validation.has_fatal_error:
|
||
await jobs.mark_failed(job_id, validation.message)
|
||
await emit("error", ...)
|
||
return
|
||
await emit("validation_completed", ...)
|
||
|
||
diff = build_diff_summary(snapshot.content, draft, validation)
|
||
await jobs.save_diff(job_id, diff)
|
||
await emit("comparison_ready", diff)
|
||
|
||
if job.commit_policy != AUTO_COMMIT_AFTER_VALIDATION:
|
||
await jobs.mark_candidate_ready(job_id)
|
||
return
|
||
|
||
await emit("commit_started")
|
||
await versions.save_before_rewrite(job, snapshot)
|
||
result = await source.commit_if_unchanged(
|
||
expected_hash=base_hash,
|
||
content=draft,
|
||
metadata=CommitMetadata(job_id=job_id),
|
||
)
|
||
if not result.ok:
|
||
await jobs.mark_conflict(job_id)
|
||
await emit("conflict", ...)
|
||
return
|
||
|
||
await jobs.mark_completed(job_id, result.sha256)
|
||
await emit("committed", ...)
|
||
await emit("completed", diff)
|
||
~~~
|
||
|
||
## 8. 实施顺序
|
||
|
||
### 阶段 A：后端内核与安全基础
|
||
|
||
1. 新增领域模型、来源端口、校验、确定性 diff。
|
||
2. 新增 Job、事件、版本数据表与 migration。
|
||
3. 参考深度研究 executor 完成后台任务、取消、SSE 重放。
|
||
4. 实现普通 Artifact 读取、哈希比较、原子提交和撤销 API。
|
||
5. 编写接口测试。
|
||
|
||
验收：可以通过 API 对普通 Markdown 创建全文任务；取消、失败、冲突均不改原文件；成功后可撤销。
|
||
|
||
### 阶段 B：普通沙箱全文 UI
|
||
|
||
1. 新增 `core/document-rewrite` 前端状态、SSE、rAF hook。
|
||
2. 改 `ArtifactFileDetail`：右上角按钮、配置弹窗、临时草稿、禁用态。
|
||
3. 接入普通 `MessageList` 的步骤条、总结卡、diff 和撤销。
|
||
4. 支持刷新后恢复 Job 状态与已完成历史。
|
||
|
||
验收：右侧可平滑逐 token 写入；完成后替换真实 Markdown；左侧步骤和总结保留；撤销成功恢复。
|
||
|
||
### 阶段 C：深度研究接入
|
||
|
||
1. 实现 `DeepResearchReportSource`。
|
||
2. 由 `ResearchSandboxPanel` 传入报告 target。
|
||
3. `useReportSandbox` 支持外部临时草稿。
|
||
4. 对深度研究添加引用白名单校验。
|
||
5. 保持现有报告局部候选确认卡不变，再逐步下沉公共 prompt/校验逻辑。
|
||
|
||
验收：报告全文改写不触发联网搜索，不允许新来源；局部报告改写依然先确认再应用。
|
||
|
||
### 阶段 D：局部改写内核迁移
|
||
|
||
1. 保持 `/api/writing/rewrite` 契约不变。
|
||
2. 将 `writing.py` 转为 `InlineDocumentSource + preview_only` 的兼容 facade。
|
||
3. 给 `useWritingRewrite` 增加原文快照失效检查。
|
||
4. 回归替换、插入、重试、继续追问。
|
||
|
||
## 9. 测试与验收
|
||
|
||
建议新增后端测试：
|
||
|
||
~~~text
|
||
offline-backend-20260512/backend/tests/
|
||
├─ test_document_rewrite_pipeline.py
|
||
├─ test_document_rewrite_api.py
|
||
├─ test_document_rewrite_versions.py
|
||
└─ test_document_rewrite_deep_research.py
|
||
~~~
|
||
|
||
必须覆盖：
|
||
|
||
- Job 状态、SSE 顺序和断线恢复；
|
||
- 空输出、围栏不闭合、截断、非法深度研究引用；
|
||
- 同一文件并发任务；
|
||
- 提交前手工修改导致的冲突；
|
||
- 取消/异常不改真实文件；
|
||
- 正常撤销、撤销前手工编辑导致的冲突；
|
||
- 旧 `/api/writing/rewrite`、深度研究 `/rewrite/stream` 兼容回归。
|
||
|
||
前端必须覆盖：
|
||
|
||
- 多个 delta 在一帧合并，最终内容不丢失；
|
||
- `committed` 前 Artifact 缓存不被临时草稿污染；
|
||
- 失败/取消/冲突后右侧恢复原文；
|
||
- 活跃任务禁用同文件编辑、保存、重复改写；
|
||
- 刷新后历史步骤条与总结仍存在；
|
||
- 深度研究虚拟 `report.md` 可用全文改写；
|
||
- 局部编辑器原文变化后不能应用过期候选。
|
||
|
||
执行基线：
|
||
|
||
~~~powershell
|
||
cd offline-backend-20260512/backend
|
||
$env:PYTHONPATH = "."
|
||
uv run --no-sync pytest tests/test_document_rewrite_pipeline.py -v
|
||
uv run --no-sync pytest tests/test_document_rewrite_api.py -v
|
||
uv run --no-sync ruff check app packages/harness
|
||
|
||
cd ../../frontend-web
|
||
pnpm typecheck
|
||
pnpm build
|
||
~~~
|
||
|
||
## 10. 风险控制
|
||
|
||
| 风险 | 控制措施 |
|
||
| --- | --- |
|
||
| 用户误以为真实文件已经清空 | 明确显示“临时草稿，原文件尚未修改” |
|
||
| 流式显示仍然卡顿 | 网络完整读取 + `requestAnimationFrame` 合并渲染 |
|
||
| 改写中用户手动编辑 | `SHA-256` compare-and-swap，冲突即拒绝覆盖 |
|
||
| 输出 Markdown 不完整 | 非空、围栏、截断和标题检查 |
|
||
| 深度研究幻觉 | 来源白名单、禁止联网、引用 ID 校验 |
|
||
| 文档过大 | 第一版拒绝并提示按章节改写，不隐式截断 |
|
||
| 局部编辑污染聊天历史 | 局部只在编辑器弹窗展示，不创建完整步骤条 |
|
||
| 历史记录只存在浏览器内存 | 全文 Job/Event/Diff 持久化，按展示线程恢复 |
|
||
|
||
## 11. 复用点清单
|
||
|
||
| 现有实现 | 在新方案中的用途 |
|
||
| --- | --- |
|
||
| `MarkdownAiEditor.tsx` | 保留局部编辑菜单、预览弹窗、确认动作 |
|
||
| `useWritingRewrite.ts` | 保留局部流控制，增加快照失效保护 |
|
||
| `open-canvas/api/rewrite.ts` | 保持兼容，逐步接入统一内核 |
|
||
| `routers/writing.py` | 复用当前模型流式读取，抽取 prompt/流逻辑 |
|
||
| `routers/deep_research.py` | 复用报告来源、哈希候选、来源约束 |
|
||
| `deep_research_job_executor.py` | 复用后台 Job、取消、事件重放模式 |
|
||
| `artifact-file-detail.tsx` | 复用沙箱文件操作、代码/预览、缓存同步 |
|
||
| `useUpdateArtifactContent` | 完成后更新普通 Artifact 缓存 |
|
||
| `ResearchSandboxPanel.tsx` | 复用研究报告的右侧沙箱宿主 |
|
||
| `useReportSandbox.ts` | 加入临时草稿覆盖显示 |
|
||
| `MessageList.tsx / MessageGroup.tsx` | 复用普通消息步骤条、总结消息、文件卡片能力 |
|
||
| `DeepResearchWorkbench.tsx` | 复用向普通消息列表投影过程事件的模式 |
|
||
|
||
## 12. 完成定义
|
||
|
||
完成后应满足：
|
||
|
||
1. 局部编辑依旧是编辑器弹窗中的人工确认操作。
|
||
2. 全文改写在普通消息列表展示完整且不隐藏的步骤条。
|
||
3. 右侧沙箱可平滑地逐 token 展示临时 Markdown 草稿。
|
||
4. 任何中断、取消、校验失败和冲突都不损坏真实文件。
|
||
5. 完成后用户可以看到量化差异、结构变化、来源保留和风险提示。
|
||
6. 普通 Markdown 与深度研究报告都可全文改写，但研究报告绝不绕过已选来源约束。
|
||
7. 每一次真实全文覆盖都有版本快照，并且能够安全撤销。
|
||
|