From be23c1346b07555acb2021811e7acb83831786a3 Mon Sep 17 00:00:00 2001 From: mesalogo Date: Mon, 28 Sep 2026 16:59:51 +0800 Subject: [PATCH] docs: define live Office editing requirements and acceptance Specify same-session Agent edits, visible changes, and Word, Excel, and PowerPoint acceptance scenarios. Record centralized deployment and ONLYOFFICE API licensing prerequisites as design requirements, not implemented capabilities. --- docs/features/office-document-editing/prd.md | 70 ++++++++++++-- .../office-document-editing/user-stories.md | 92 ++++++++++++++++++- 2 files changed, 152 insertions(+), 10 deletions(-) diff --git a/docs/features/office-document-editing/prd.md b/docs/features/office-document-editing/prd.md index 7bc94b5a..26fdb9a0 100644 --- a/docs/features/office-document-editing/prd.md +++ b/docs/features/office-document-editing/prd.md @@ -5,10 +5,10 @@ | 项目 | 内容 | | --- | --- | | 状态 | 设计中 | -| 版本 | 0.1 | -| 日期 | 2026-09-09 | +| 版本 | 0.2 | +| 日期 | 2026-09-28 | | 适用产品 | GoodBuddy Desktop、ShareServer | -| 推荐编辑引擎 | ONLYOFFICE Docs Developer Edition，最终采用前完成许可证与分发审核 | +| 推荐编辑引擎 | 首选 ONLYOFFICE Docs Developer Edition；正式采用前验证实时编辑接口并确认授权与报价 | ## 1. 背景 @@ -21,7 +21,8 @@ XLSX 和 PPTX，也无法把当前选区交给 Agent 后在原位置应用修改 - Windows、macOS 和 Linux Desktop 使用同一套浏览器编辑能力。 - DOCX、XLSX、PPTX 在助手工作栏中以多个独立文档页签打开。 - 用户可以手动编辑、保存、撤销和重做。 -- Agent 可以读取用户明确选择的内容，并将一次 AI 修改作为一个可撤销编辑事务应用。 +- 用户在左侧与 Agent 对话，在右侧助手工作栏看到当前文档的修改状态和结果，无需重新打开文件。 +- Agent 可以读取用户明确选择的最新内容，并将一次 AI 修改作为一个可撤销编辑事务应用。 - 本地源文件只在用户明确打开后上传工作副本，保存时通过 Desktop 原子回写。 - ShareServer 统一承载编辑器接入、短期会话、工作副本、回调、保留和服务端审计。 @@ -66,10 +67,18 @@ ONLYOFFICE 保存先形成 ShareServer 保存检查点。Desktop 下载并验证 ### FR-6 AI 选区编辑 -用户在编辑器中明确选择文字、单元格、对象、页面或幻灯片后，可以发起 AI 编辑。编辑器只提供 -本次选区的有界结构和必要上下文。Agent 返回编辑器支持的结构化操作，由编辑器插件应用；一次 -请求形成一个撤销事务，并在完成后标出修改位置。只有 Execute 模式可以应用修改；Ask 模式 -可以生成建议，但不得调用编辑器写入。 +用户在编辑器中明确选择文字、单元格、对象、页面或幻灯片后，可以发起 AI 编辑。编辑器提供 +当前会话内本次选区的最新内容、有界结构和必要上下文，包括尚未保存到源文件的人工修改。 +Agent 通过当前编辑会话应用受支持的结构化操作；一次请求形成一个撤销事务。只有 Execute +模式可以应用修改；Ask 模式可以生成建议，但不得调用编辑器写入。 + +首期有界操作至少覆盖选区读取、指定文本替换、单元格区域公式与数字格式设置，以及指定幻灯片 +文本和对象属性修改。操作前明确目标文件与范围，完成后返回实际修改结果；不支持的操作说明 +限制，不以模型生成了建议或工具请求已发出作为成功依据。 + +Agent 思考期间用户可以继续编辑。应用前检查当前文档版本与目标是否仍符合本次请求；内容变化 +或目标失效时停止应用旧结果，保留人工修改并提示基于最新内容重试。切换页签或选区不得将已 +提交请求改发到其他目标。已打开文档的交互修改不得通过直接重写源文件并重载编辑器实现。 ### FR-7 权限与数据去向 @@ -102,6 +111,34 @@ Desktop 记录本地打开、保存、另存为、冲突、AI 编辑请求和终 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. 文件范围 首期可编辑格式： @@ -121,7 +158,22 @@ PDF 保持预览或文档处理用途，不进入首期 Office 编辑。宏格 - 同一工作栏至少可以同时保留两个独立文档页签，切换不会串文件、选区或保存状态。 - 同名文件的页签可辨认，页签标题和完整来源一致。 - 保存失败、回调失败和源文件冲突均不会破坏原文件。 -- 每次 AI 修改可以单次撤销，拒绝或取消不会产生部分修改。 +- 每次已完成 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 思考期间用户修改文档 | 旧结果不覆盖新修改，支持基于最新内容重试 | +| 共同编辑流程 | 应用、定位、高亮、撤销、重做、保存并重新打开 | 当前页签无需重载即可显示结果；保存后的文件内容与预期一致 | + +文件兼容性使用包含中文字体、分页、表格、图表和公式的实际样本检查。目标平台的嵌入加载、 +焦点、快捷键与复制粘贴一并验收；接口验证和授权确认完成后再进入完整工作栏与生产部署实施。 diff --git a/docs/features/office-document-editing/user-stories.md b/docs/features/office-document-editing/user-stories.md index 6ad36da4..a3c29342 100644 --- a/docs/features/office-document-editing/user-stories.md +++ b/docs/features/office-document-editing/user-stories.md @@ -1,5 +1,9 @@ # Office 协同编辑用户故事 +日期：2026-09-28。状态：需求设计，尚未完成实现与真实编辑器验证。 + +需求范围见 [PRD](./prd.md)。本轮补充 ONLYOFFICE 同会话编辑、右侧修改展示和选型验证用例。 + ## US-A1 打开本地文档 **Given** 用户已连接支持 Office 编辑的 ShareServer，并在工作区选择一个受支持文件 @@ -45,11 +49,15 @@ ## US-C1 使用 AI 修改选区 +关联：`FR-6`、`FR-13`。 + **Given** 当前 Conversation 使用 Execute，用户在编辑器中选择受支持内容 **When** 用户提交 AI 修改要求 -**Then** Agent 只接收有界选区和必要上下文，编辑器将完整结果作为一个事务应用并允许单次撤销。 +**Then** Agent 只接收当前会话的最新有界选区和必要上下文，右侧显示目标与处理状态；编辑器 +确认后原位更新、临时高亮并支持定位修改范围，无需重载。完整结果作为一个事务应用，可以 +单次撤销和重做；高亮不进入正文，完成状态不表示已写回源文件。 ## US-C2 Ask 模式请求修改 @@ -60,6 +68,65 @@ **Then** GoodBuddy 可以生成修改建议，但不会调用编辑器写入；界面提供切换 Execute 后重新应用 的明确入口。 +## US-C3 读取尚未保存的人工修改 + +关联：`FR-6`。 + +**Given** 用户已在右侧修改文档，但尚未保存到源文件 + +**When** 用户选择刚修改的内容并要求 Agent 继续编辑 + +**Then** Agent 基于当前编辑会话中的最新内容执行；磁盘旧文件和旧检查点不能替代本次上下文。 + +## US-C4 Agent 思考期间继续编辑 + +关联：`FR-6`、`FR-8`。 + +**Given** Agent 已读取选区，正在生成修改 + +**When** 用户继续修改文档，或切换到另一个文档页签与选区 + +**Then** 切换页签不改变原请求目标；原文档版本变化或目标失效时不应用旧结果，保留人工修改并 +提示基于最新内容重试。同一文档的其他页签也不能接收本次操作。源文件冲突仍按 `US-B2` 处理。 + +## US-C5 编辑 Word、Excel 和 PPT + +关联：`FR-3`、`FR-6`、`FR-13`。 + +**Given** 已分别准备 DOCX、XLSX 和 PPTX 样本，当前 Conversation 使用 Execute + +**When** 用户分别请求改写选中段落、修改选区公式及两位小数格式、修改指定幻灯片文本和对象属性 + +**Then** 按下表验证实际结果；每个样本均完成定位、高亮、单次撤销、重做、保存及重新打开检查。 + +| 样本 | 验收结果 | +| --- | --- | +| DOCX | 目标段落内容符合要求，约定文字与段落格式保留，范围外内容不变 | +| XLSX | 目标区域公式及重算值符合预期，数字显示为两位小数，区域外内容不变 | +| PPTX | 指定页面和对象定位正确，文本与属性变更符合要求，非目标对象及布局不变 | + +## US-C6 不支持、取消和执行失败 + +关联：`FR-6`、`FR-13`。 + +**Given** 用户发起一次 AI 编辑请求 + +**When** 操作不受支持、用户取消或编辑器未能确认结果 + +**Then** 不支持时返回具体限制；提交前取消不修改文档，已应用事务提供撤销。未知结果明确显示 +待核实，不自动重复写入，不以建议生成成功代替编辑成功；执行失败保留原因和实际已应用状态。 + +## US-C7 编辑状态与源文件保存 + +关联：`FR-4`、`FR-13`。 + +**Given** 右侧已显示 Agent 修改完成，用户又进行了一次人工编辑 + +**When** 用户保存文档并重新打开源文件 + +**Then** 保存包含已确认的 AI 修改与后续人工修改；只有源文件回写成功才显示“已写回源文件”。 +回调或回写失败时保留失败状态及可用检查点，不因右侧已经更新而宣称保存完成。 + ## US-D1 网络中断后恢复 **Given** 编辑会话已经建立 @@ -83,3 +150,26 @@ **When** 用户继续访问旧页签 **Then** 新读取、保存和 AI 操作被拒绝，旧令牌不能重用，本地源文件不受服务端清理影响。 + +## US-F1 启用集中部署的 Office 服务 + +关联：`FR-7`、`FR-12`、`FR-14`。 + +**Given** 部署方已准备独立的 ONLYOFFICE 服务及所需授权，用户已连接 ShareServer + +**When** 用户首次在 Desktop 打开 Office 文档 + +**Then** 无需在用户电脑安装 Docker；打开前能看到工作副本进入哪个服务及保留期限。实际验证 +文件下载、保存回调和中文字体；在 Windows、macOS 和 Linux 检查加载、焦点、快捷键与复制粘贴。 + +## US-F2 决定正式采用 ONLYOFFICE + +关联：`FR-14`。 + +**Given** 产品团队以 ONLYOFFICE Docs Developer 为首选，正在进行接口与授权验证 + +**When** 评审是否进入完整功能实施 + +**Then** 提供 `US-C1` 至 `US-C7` 的真实会话验证结果、三类文件样本兼容性记录，以及覆盖实际 +部署与嵌入方式的授权条件和报价。Automation API 单独确认额外费用；插件替代方案单独验证。 +未通过项明确列出限制与范围决定，仅安装容器、打开文档或完成转换不能视为实时编辑验证通过。