goodbuddy/docs/features/office-document-editing/prd.md

# Office 协同编辑 PRD

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.2 |
| 日期 | 2026-09-28 |
| 适用产品 | GoodBuddy Desktop、ShareServer |
| 推荐编辑引擎 | 首选 ONLYOFFICE Docs Developer Edition；正式采用前验证实时编辑接口并确认授权与报价 |

## 1. 背景

GoodBuddy 已能解析、生成和预览部分 Office 文件，但用户无法在客户端内直接修改 DOCX、
XLSX 和 PPTX，也无法把当前选区交给 Agent 后在原位置应用修改。自行实现高保真 OOXML
编辑器不符合产品投入边界，因此通过 ShareServer 集成成熟的浏览器编辑引擎。

## 2. 目标

- Windows、macOS 和 Linux Desktop 使用同一套浏览器编辑能力。
- DOCX、XLSX、PPTX 在助手工作栏中以多个独立文档页签打开。
- 用户可以手动编辑、保存、撤销和重做。
- 用户在左侧与 Agent 对话，在右侧助手工作栏看到当前文档的修改状态和结果，无需重新打开文件。
- Agent 可以读取用户明确选择的最新内容，并将一次 AI 修改作为一个可撤销编辑事务应用。
- 本地源文件只在用户明确打开后上传工作副本，保存时通过 Desktop 原子回写。
- ShareServer 统一承载编辑器接入、短期会话、工作副本、回调、保留和服务端审计。

## 3. 非目标

- 不自行实现 Word、Excel 或 PowerPoint 的排版与渲染引擎。
- 不把 ONLYOFFICE Document Server 打入 Desktop 安装包或由 Electron 启动。
- 不把编辑能力描述为离线功能；未连接已配置的 ShareServer 时不可创建新编辑会话。
- 不允许编辑器浏览任意本机目录，也不把本机绝对路径发送给 ShareServer。
- 不把 Node/Python OOXML SDK 当作可视化编辑器；它们后续只用于受控批处理 Provider。
- 首期不提供多人实时协作、文档分享链接、移动端编辑或跨组织编辑。
- 首期不支持 DOC、XLS、PPT 直接编辑；旧格式转换仍属于文档处理能力。

## 4. 功能要求

### FR-1 打开文档

用户可以从工作区文件、成果或会话文件引用中选择“在文档页签中打开”。Desktop 必须先验证
文件范围、扩展名、真实格式、大小和当前 ShareServer 能力，再创建编辑会话。失败时不得上传
部分文件或留下可继续访问的会话。

### FR-2 多实例文档页签

“文档”是助手工作栏的多实例能力。每次打开创建一个新页签，不把所有文件复用为单例。
页签主标题为文件名；同名页签增加序号，完整来源通过 Tooltip 和页签内来源信息显示。

### FR-3 基础编辑

编辑器至少支持 DOCX、XLSX 和 PPTX 的打开、人工编辑、保存、撤销、重做、复制粘贴、查找和
格式工具。具体格式兼容程度以真实样本验收为准，不因文件能打开就宣称完整兼容。

### FR-4 保存与回写

ONLYOFFICE 保存先形成 ShareServer 保存检查点。Desktop 下载并验证检查点后，只有在源文件
仍与打开时或上次成功保存后的版本一致时才原子替换源文件。成功后更新本地基准校验和和页签
状态。任何中间失败都保留原文件。

### FR-5 另存为

用户可以把当前保存检查点另存到当前已授权执行空间内的新路径。目标选择和冲突确认由 Desktop
完成；ShareServer 和编辑器不能决定本机路径。

### FR-6 AI 选区编辑

用户在编辑器中明确选择文字、单元格、对象、页面或幻灯片后，可以发起 AI 编辑。编辑器提供
当前会话内本次选区的最新内容、有界结构和必要上下文，包括尚未保存到源文件的人工修改。
Agent 通过当前编辑会话应用受支持的结构化操作；一次请求形成一个撤销事务。只有 Execute
模式可以应用修改；Ask 模式可以生成建议，但不得调用编辑器写入。

首期有界操作至少覆盖选区读取、指定文本替换、单元格区域公式与数字格式设置，以及指定幻灯片
文本和对象属性修改。操作前明确目标文件与范围，完成后返回实际修改结果；不支持的操作说明
限制，不以模型生成了建议或工具请求已发出作为成功依据。

Agent 思考期间用户可以继续编辑。应用前检查当前文档版本与目标是否仍符合本次请求；内容变化
或目标失效时停止应用旧结果，保留人工修改并提示基于最新内容重试。切换页签或选区不得将已
提交请求改发到其他目标。已打开文档的交互修改不得通过直接重写源文件并重载编辑器实现。

### FR-7 权限与数据去向

创建会话前持续显示目标 ShareServer、将上传的文件、服务端可读取文档内容以及默认保留期限。
组织策略可以禁止格式、限制文件大小、强制只读或禁止 AI 编辑。Desktop 偏好只能收紧策略。

### FR-8 版本冲突

源文件在编辑期间被其他程序修改时，Desktop 不得覆盖。用户可以重新加载外部版本、将编辑
检查点另存为新文件，或显式比较后选择替换；首期不自动合并二进制 Office 文件。

### FR-9 断线与恢复

短暂断线不关闭页签。界面区分 Desktop 到 ShareServer、ShareServer 到 ONLYOFFICE 和保存回调
故障。只有 ShareServer 确认存在稳定检查点时才显示“可恢复”；未知结果不得显示为已保存。

### FR-10 关闭

没有未回写修改时直接关闭。存在 ShareServer 检查点但尚未回写源文件时，用户选择“保存并
关闭”“放弃修改”或“取消”。放弃只结束编辑会话和删除临时工作副本，不删除源文件。

### FR-11 审计

Desktop 记录本地打开、保存、另存为、冲突、AI 编辑请求和终态。ShareServer 记录组织、主体、
会话、文档类型、字节数、策略、编辑器版本、保存版本和保留清理，不默认记录选区正文、完整
文档内容、提示词或模型输出。

### FR-12 服务配置

Desktop 只连接用户已明确添加并认证的 ShareServer。ONLYOFFICE 地址、JWT 密钥、对象存储和
回调配置由 ShareServer 管理，不进入 Desktop Renderer 或普通设置导出。

推荐由部署方在服务器 Docker 中独立运行 ONLYOFFICE Document Server，客户端加载编辑器；
普通用户无需安装 Docker。启用前验证文件下载、保存回调和中文字体，并说明工作副本会进入
所选服务的处理范围。完全离线编辑不属于此部署方案。

### FR-13 Agent 修改可见性

右侧文档页签与 Agent 使用同一个编辑会话。请求处理中显示当前目标与执行状态；编辑器确认
应用后，内容在当前页签直接更新，用户可定位并看到修改范围的临时高亮。状态提示和高亮不写入
文档正文，执行完成不等于源文件已保存。用户可以继续手动编辑，并对该次 AI 修改撤销或重做。

实时可见以一次已确认的编辑事务为单位，不要求模拟逐字输入。失败、取消或结果未知应明确
显示实际状态；提交前取消不修改文档，已应用的事务通过撤销恢复，结果未知时先核实再重试。

### FR-14 选型验证与授权

ONLYOFFICE 是统一承载 Word、Excel、PPT 的首选方案。正式采用前，必须在同一嵌入编辑会话中
验证选区读取、人工修改反馈、Agent 写入、修改定位与高亮、撤销重做，以及保存后重新打开。
验证目标见第 6 节，不能以编辑器可打开或转换成功代替 Agent 编辑验证。

优先验证 Automation API 与 GoodBuddy 编辑器插件的配合方式。根据
[官方 Automation API 文档](https://api.onlyoffice.com/docs/docs-api/usage-api/automation-api/)
（2026-09-28 核对），该接口仅适用于 Docs Developer，且需额外付费。选型需取得覆盖桌面嵌入、
私有部署、并发连接、分发和所需接口的授权条件及报价；社区版容器部署成功不代表取得这些权益。
插件独立接入可作为备选验证，不预先认定与 Automation API 等价或免除商业授权要求。

三类文件的实际接口覆盖、单次撤销、高亮方式、中文字体与复杂格式兼容性，以及授权成本均为
待验证项。未通过的操作记录具体限制，再决定补充实现或调整范围；本 PRD 不表示已有可用实现。

## 5. 文件范围

首期可编辑格式：

| 类型 | 格式 | 编辑器类型 |
| --- | --- | --- |
| 文档 | `.docx` | `word` |
| 表格 | `.xlsx` | `cell` |
| 演示文稿 | `.pptx` | `slide` |

PDF 保持预览或文档处理用途，不进入首期 Office 编辑。宏格式、模板格式、受密码保护文件和包含
活动内容的文件默认拒绝，后续必须单独完成格式、安全和保存兼容性设计。

## 6. 验收标准

- 三个 Desktop 操作系统均能从同一 ShareServer 打开、编辑和保存三种首期格式。
- 同一工作栏至少可以同时保留两个独立文档页签，切换不会串文件、选区或保存状态。
- 同名文件的页签可辨认，页签标题和完整来源一致。
- 保存失败、回调失败和源文件冲突均不会破坏原文件。
- 每次已完成 AI 修改可以单次撤销和重做；拒绝或提交前取消不修改文档，应用后取消按 FR-13 处理。
- ShareServer 不可用时已有本地文件仍可由默认应用打开，但不能伪装成内置编辑可用。
- Renderer、编辑器页面和日志中均不存在本机绝对路径、ShareServer 管理密钥或长期文件令牌。
- 文档会话过期后，旧启动 URL、文件 URL 和回调令牌均不可重用。

以下场景按 [用户故事](./user-stories.md) 的 `US-C1` 至 `US-C7`、`US-F1` 和 `US-F2` 验证；
记录编辑器版本、授权版本、样本和实际结果，不把待测能力标记为已通过。

| 样本／场景 | 操作 | 通过标准 |
| --- | --- | --- |
| Word | 改写选中段落 | 右侧原位更新，保留约定段落与文字格式，范围外内容不变 |
| Excel | 修改指定区域公式并设为两位小数 | 公式重算与预期一致，显示格式正确，区域外内容不变 |
| PPT | 修改指定页文本及一个对象属性 | 对象定位准确，非目标对象与布局不变 |
| 人工修改反馈 | 人工修改后不保存，立即发起 AI 请求 | Agent 读取到会话内最新内容 |
| 并行编辑 | Agent 思考期间用户修改文档 | 旧结果不覆盖新修改，支持基于最新内容重试 |
| 共同编辑流程 | 应用、定位、高亮、撤销、重做、保存并重新打开 | 当前页签无需重载即可显示结果；保存后的文件内容与预期一致 |

文件兼容性使用包含中文字体、分页、表格、图表和公式的实际样本检查。目标平台的嵌入加载、
焦点、快捷键与复制粘贴一并验收；接口验证和授权确认完成后再进入完整工作栏与生产部署实施。