From b6d4633a33a59aacc9c67e2503aa062c11f6d776 Mon Sep 17 00:00:00 2001 From: mesalogo Date: Wed, 9 Sep 2026 12:43:00 +0800 Subject: [PATCH] docs: design ShareServer Office editing --- FEATURES.md | 8 + FEATURES.zh-CN.md | 1 + .../share-network-architecture.md | 46 +++- docs/features/assistant-workbar/prd.md | 34 ++- docs/features/document-processing/README.md | 4 + docs/features/document-processing/prd.md | 5 + .../office-document-editing/README.md | 29 +++ .../office-document-editing/logic-design.md | 117 ++++++++++ docs/features/office-document-editing/prd.md | 127 ++++++++++ .../technical-design.md | 217 ++++++++++++++++++ .../office-document-editing/ui-design.md | 83 +++++++ .../office-document-editing/user-stories.md | 85 +++++++ 12 files changed, 747 insertions(+), 9 deletions(-) create mode 100644 docs/features/office-document-editing/README.md create mode 100644 docs/features/office-document-editing/logic-design.md create mode 100644 docs/features/office-document-editing/prd.md create mode 100644 docs/features/office-document-editing/technical-design.md create mode 100644 docs/features/office-document-editing/ui-design.md create mode 100644 docs/features/office-document-editing/user-stories.md diff --git a/FEATURES.md b/FEATURES.md index 9ffa6e0b..4038da6e 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -77,6 +77,14 @@ otherwise. attachments and knowledge remain in the conversation composer, while memory, when implemented, and historical execution context belong to the associated Task. See the [Feature PRD](./docs/features/assistant-workbar/prd.md). +- [ ] **ShareServer Office co-editing** (design): Uses an optional ShareServer + integration with ONLYOFFICE Docs to open multiple filename-labelled document + tabs in the assistant workbar. The planned scope covers DOCX, XLSX, and PPTX + manual editing, save and undo, source-file conflict protection, and later AI + selection edits. The selected ShareServer and editor process document content; + Desktop neither bundles nor starts Document Server and does not claim offline + editing when no service is configured. See the + [design](./docs/features/office-document-editing/README.md). ### Agent Runtimes and model connections diff --git a/FEATURES.zh-CN.md b/FEATURES.zh-CN.md index cc6dd792..1032c031 100644 --- a/FEATURES.zh-CN.md +++ b/FEATURES.zh-CN.md @@ -25,6 +25,7 @@ - [ ] **项目 Agent Space**（规划中）：在 Project 中统一角色、知识、Skills/MCP、模型、审批策略、预算和超时，并支持模板复用。 - [ ] **应用导航与系统工具快捷入口**（仅设计）：规划固定系统入口、内置应用显隐和打开现有工作栏的底部工具按钮；尚未实现新界面。详见[设计文档](./docs/features/application-tool-navigation/README.md)。 - [ ] **通用助手工作栏与执行空间后续能力**（规划中）：在现有工作栏和多终端基础上继续加入监督、统一 Runtime、受管进程、静态安全 HTML 预览、可固定目标的工作区/浏览器/成果实例、底部停靠与独立窗口。Task Center 保持 Task 的单例索引，附件与知识库继续由会话输入区管理，未来的记忆与历史执行上下文归入关联 Task。详见 [Feature PRD](./docs/features/assistant-workbar/prd.md)。 +- [ ] **ShareServer Office 协同编辑**（设计中）：通过可选 ShareServer 集成 ONLYOFFICE Docs，在助手工作栏中以文件名打开多个文档 Tab，支持 DOCX、XLSX、PPTX 的人工编辑、保存、撤销、源文件冲突保护和后续 AI 选区修改。Office 正文会由所选 ShareServer 和编辑引擎处理；Desktop 不内置或启动 Document Server，未配置服务时不宣称离线编辑。详见[设计文档](./docs/features/office-document-editing/README.md)。 ### Agent Runtime 与模型连接 diff --git a/docs/architecture/share-network-architecture.md b/docs/architecture/share-network-architecture.md index 5217361e..e9d629d2 100644 --- a/docs/architecture/share-network-architecture.md +++ b/docs/architecture/share-network-architecture.md @@ -5,8 +5,8 @@ | 项目 | 内容 | | --- | --- | | 状态 | 设计中 | -| 版本 | 0.1 | -| 日期 | 2026-09-03 | +| 版本 | 0.2 | +| 日期 | 2026-09-09 | | 适用范围 | GoodBuddy 桌面端、ShareServer、网关间联邦协议 | | 桌面端设计 | [设备发现与共享](../features/device-sharing/README.md) | | 服务端设计 | [ShareServer](../../../goodbuddy-shareserver/docs/features/share-server/README.md) | @@ -26,7 +26,7 @@ 1. **GoodBuddy Desktop** 在设置中提供“设备发现与共享”，默认使用局域网发现与直连，也可 由用户额外连接一个或多个 ShareServer。 2. **ShareServer** 是独立部署、独立升级的 Web 服务，提供组织、设备、能力、权限、更新、 - 联邦、中继和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。 + 联邦、中继、Office 编辑和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。 ### 2.2 能力优先，来源可见 @@ -55,6 +55,17 @@ ShareServer 负责身份、目录、策略、任务路由、更新和审计。 直接建立；网络条件不允许时，可按组织策略使用 ShareServer 中继。是否允许中继、正文是否 端到端加密、是否允许跨组织，由本次任务冻结的策略共同决定。 +### 2.6 Office 编辑是 ShareServer 托管服务 + +ShareServer 可以把 ONLYOFFICE Docs、工作副本存储、保存回调和编辑会话作为一个可选部署 +能力提供给 Desktop。Desktop 只连接用户已明确配置的 ShareServer，不直接配置 Document +Server，也不在本机启动服务。Office 文档内容会由 ShareServer 和编辑引擎处理，因此不能沿用 +“控制面默认不读取正文”的数据面假设；创建编辑会话前必须明确显示服务端、数据去向和保留期。 + +编辑后的本地或 SSH 源文件仍由 Desktop 或远程 GoodBuddy Agent 持有和原子回写。ShareServer +是工作副本及服务端保存检查点的权威，不是源文件最终写入成功的权威。完整设计见 +[Office 协同编辑](../features/office-document-editing/README.md)。 + ## 3. 术语 | 术语 | 定义 | @@ -71,6 +82,7 @@ ShareServer 负责身份、目录、策略、任务路由、更新和审计。 | `Task` | 一次远程能力调用及其输入、执行、输出和终态 | | `Package` | 可下载到本机安装的签名能力工件 | | `FederationTrust` | 两个组织网关之间经管理员确认的双边信任关系 | +| `DocumentEditSession` | ShareServer 托管的单文档短期编辑会话、工作副本和保存检查点 | “网关”是 ShareServer 的网络角色；产品名称为 `ShareServer`，独立仓库为 `goodbuddy-shareserver`。 @@ -84,6 +96,10 @@ GoodBuddy Desktop A <-- mDNS 发现 + 配对后 TLS 直连 --> GoodBuddy Desktop 单组织： GoodBuddy Desktop A -- 出站连接 --> ShareServer <-- 出站连接 -- Provider Device B +Office 编辑： +GoodBuddy Desktop --> ShareServer --> ONLYOFFICE Docs + └-------> 临时工作副本与保存检查点 + 跨组织： Desktop A --> ShareServer A <== 联邦信任 ==> ShareServer B <-- Provider Device B ``` @@ -121,6 +137,7 @@ Desktop A --> ShareServer A <== 联邦信任 ==> ShareServer B <-- Provider Devi - 计算组织强制策略，签发短期任务授权。 - 路由任务、维护在线状态，并在允许时中继数据。 - 管理签名包、发布通道、更新策略和撤销。 +- 可选管理 Office 编辑会话、ONLYOFFICE 接入、工作副本、保存回调、保留和清理。 - 建立双边联邦关系并限制跨组织可见性与调用。 - 保存有界审计元数据、用量和管理操作。 @@ -339,6 +356,16 @@ created/awaiting_approval/queued/connecting -> rejected | expired | cancelled - 未识别字段在声明允许扩展的位置忽略，安全与授权枚举中的未知值一律拒绝。 - 联邦只交换双方共同支持的能力和策略表达式，不降低任一方策略。 +### 11.5 Office 编辑协议 + +Office 编辑使用独立的 HTTPS 会话、文件和事件 API，不复用普通远程能力 Task 表达长生命周期 +编辑器。Desktop 通过设备凭据创建会话和传输源文件；编辑器使用一次性启动授权；ONLYOFFICE +使用独立短期 JWT 获取工作副本并提交保存回调。三类凭据使用不同 audience，不能互换。 + +文档页签可以长期存在，但启动 URL、文件 URL、callback token 和编辑 Cookie 必须短期、单用途 +并可撤销。跨端会话、保存和冲突规则见 +[Office 协同编辑技术设计](../features/office-document-editing/technical-design.md)。 + ## 12. 数据与审计 ### 12.1 最小审计事件 @@ -358,6 +385,8 @@ created/awaiting_approval/queued/connecting -> rejected | expired | cancelled - 桌面端是本地配对、本机共享偏好和本地活动记录的权威。 - ShareServer 是组织成员、设备注册、组织策略、发布目录和组织审计的权威。 +- ShareServer 是 Office 工作副本、服务端保存检查点、编辑会话和保留清理的权威；Desktop 或 + 远程 GoodBuddy Agent 是源文件是否成功回写的权威。 - 能力提供者是运行中任务及结果是否产生的权威。 - 联邦两端各自保存本组织审计，不复制对方完整成员目录或内部策略。 @@ -376,6 +405,10 @@ ShareServer 可以部署到公网，因此公网连接、外部组织和服务 8. 密钥只进入对应安全存储，诊断和审计使用固定字段与脱敏错误码。 9. 限制握手、清单、帧、文件、并发、速率、任务时长和审计查询大小。 10. 撤销设备、用户、Grant、Publication、Package 或 FederationTrust 后停止签发新令牌。 +11. Office 编辑器使用固定 origin 和隔离会话，不获得 Electron、文件系统、Shell、Runtime 或 + 普通 ShareServer 管理 API；Document Server 默认禁止任意出站网络和未批准插件。 +12. Office 文件正文由服务端实际处理，组织策略必须定义允许格式、大小、保留和内容访问角色， + Desktop 在上传前显示这些事实。 ## 14. 建议领域实体 @@ -401,6 +434,8 @@ PackageRelease FederationTrust AuditEvent Revocation +DocumentEditSession +DocumentCheckpoint ``` 共享协议只定义跨端 DTO 和状态，不规定桌面 SQLite 与 ShareServer 数据库使用相同表结构。 @@ -442,6 +477,10 @@ ShareServer 不反向依赖桌面端 `src/shared`，构建和运行不要求桌 - [ ] 跨组织调用同时满足两端策略；联邦撤销后不能创建新任务。 - [ ] 审计默认只保存必要元数据，不保存正文、文件、密钥或认证信息。 - [ ] ShareServer 可独立部署和升级，不由 Electron 启动，也不影响桌面端离线使用。 +- [ ] 启用 Office 服务后，Desktop 可在多实例文档页签中编辑 DOCX、XLSX 和 PPTX；保存回调、 + 源文件冲突或网络故障均不会破坏原文件。 +- [ ] Office 会话的启动、文件和 callback 凭据不可互换，过期或撤销后不能重用；临时工作副本 + 按策略清理，默认审计不保存文档正文或 AI 选区内容。 ## 17. 相关设计 @@ -453,5 +492,6 @@ ShareServer 不反向依赖桌面端 `src/shared`，构建和运行不要求桌 - [ShareServer 功能逻辑](../../../goodbuddy-shareserver/docs/features/share-server/logic-design.md) - [ShareServer 管理界面](../../../goodbuddy-shareserver/docs/features/share-server/ui-design.md) - [ShareServer 技术设计](../../../goodbuddy-shareserver/docs/features/share-server/technical-design.md) +- [Office 协同编辑](../features/office-document-editing/README.md) - [SSH 远程主机与 Agent](../features/remote-host/README.md) - [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md) diff --git a/docs/features/assistant-workbar/prd.md b/docs/features/assistant-workbar/prd.md index 92d1f301..0466e922 100644 --- a/docs/features/assistant-workbar/prd.md +++ b/docs/features/assistant-workbar/prd.md @@ -36,8 +36,8 @@ Runtime 统一抽象为“执行空间”。 ### 2.1 助手工作栏 助手工作栏是 GoodBuddy 中始终可访问的应用级工具容器。它提供稳定能力目录，用户从中 -查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器、资源监控 -和成果面板实例。稳定的是能力的可发现性，不是九个同时占据界面的固定面板。 +查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器、资源监控、 +成果和文档面板实例。稳定的是能力的可发现性，不是十个同时占据界面的固定面板。 工作栏不是： @@ -85,6 +85,7 @@ Runtime 浏览器 资源监控 成果 +文档 ``` - 应用不得根据当前项目、会话、Runtime、主机或探测结果无提示地增删能力目录项。 @@ -109,6 +110,7 @@ Runtime 使用本机 Home。 - 工作区默认显示当前项目目录，用户可以打开其他本机目录或远程目录。 - 成果默认使用当前范围，用户可以切换到项目、全局或其他允许范围。 +- 文档创建时固定到用户明确打开的文件和 ShareServer 编辑会话，不提供跟随模式。 - 下一次请求的附件和知识库由当前 Composer 展示与管理，不作为工作栏能力。历史执行上下文 随关联 Task 查看；记忆功能实现后也归入任务中心，而不是新增独立上下文面板。 @@ -203,7 +205,7 @@ Runtime ### 6.2 能力目录与面板实例 -能力目录不等于同时打开九个面板。当前产品采用“已打开实例 Tab + 持久新增按钮”的工作栏 +能力目录不等于同时打开十个面板。当前产品采用“已打开实例 Tab + 持久新增按钮”的工作栏 模型：Tab 行只显示已打开实例，行末“+”始终可见；点击后在工作栏内容区打开稳定能力目录， 用户再创建或激活应用实例。详细交互以 [助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。 @@ -473,7 +475,20 @@ Task 呈现来源，不把 Run 作为导航对象。 - 不使用 `dangerouslySetInnerHTML`，不启用 Electron `webviewTag`。 - 外部打开是明确的用户操作，并说明外部浏览器可能执行脚本或联网。 -### 7.10 Composer 与任务上下文 +### 7.10 文档 + +文档是可创建多个实例的工作栏应用。用户从工作区、成果或会话文件引用打开受支持的 Office +文件时新增文档 Tab；每个实例固定到一个 ShareServer 编辑会话，不随当前 Conversation 或 +Project 切换。Tab 使用文档文件名，同名实例增加序号，完整来源通过 Tooltip 和页签内信息 +显示。编辑器、保存、冲突、AI 选区修改和关闭行为以 +[Office 协同编辑](../office-document-editing/README.md)为准。 + +完整编辑器需要至少 `720px` 可用宽度；低于 `480px` 时不把第三方工具栏压缩到重叠，而显示 +摘要和“展开编辑”命令。展开到主内容区、底部或独立窗口继续使用同一页签实例和编辑会话。 +文档编辑依赖用户明确配置且声明健康能力的 ShareServer；不可用时保留入口和原因，不回退为 +未经说明的远程服务。本地默认应用打开仍是独立用户操作。 + +### 7.11 Composer 与任务上下文 工作栏不提供独立“上下文”能力。用户准备下一次模型请求时： @@ -499,6 +514,7 @@ type WorkbarCapabilityId = | 'browser' | 'resources' | 'results' + | 'document' type WorkbarTargetRef = | { type: 'conversation'; id: string } @@ -511,6 +527,7 @@ type WorkbarTargetRef = | { type: 'managed-process'; id: string } | { type: 'browser-session'; id: string } | { type: 'artifact'; id: string } + | { type: 'document-session'; id: string } ``` Renderer 选择目标后，Main 必须重新验证对象存在、归属范围和当前用户可见性。不能把目标 ID @@ -941,7 +958,7 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。 ### 17.1 稳定能力目录与用户控制 -- [ ] 九个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。 +- [ ] 十个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。 - [ ] Task Center 继续作为 Task 的单例索引，不删除入口、不复制会话，也不混入 Job、Run 或心跳事项。 - [ ] 项目、会话、Runtime 或主机变化不会无提示地增删能力目录项。 - [ ] 用户可以按需打开、关闭、排序和停靠面板实例。 @@ -956,6 +973,8 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。 - [ ] 监督可以作用于普通 Conversation、Task 和后续实验对象，不假设编程语境。 - [ ] 工作区不是 Git 仓库时仍可浏览文件。 - [ ] Runtime 不支持某项原生能力时仍可从目录打开面板并获得准确说明。 +- [ ] 文档能力可以打开多个以文件名命名的固定实例；未配置健康 ShareServer 时显示原因， + 不把系统默认应用或静态预览冒充内置编辑。 ### 17.3 安全与控制 @@ -999,6 +1018,7 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。 - [ ] 创建中、Agent 操作中和完整交互期间禁用浏览器其余工具栏控件；活动加载仍可单独停止， 且停止加载不会关闭会话或释放 Runtime 上下文。 - [ ] 活动 Conversation 没有浏览器会话时，可从同一地址栏按 Agent 相同 URL 策略启动会话。 +- [ ] 文档编辑器在右侧宽度不足时不发生工具栏或正文重叠，并可使用同一会话展开到可编辑布局。 ## 18. 相关文档的职责 @@ -1015,8 +1035,10 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。 - [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md) 定义该 Runtime 的具体适配边界。 - [SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md) 定义 Host 级组件获取、首次准备、更新、回退和项目只验证边界。 +- [Office 协同编辑](../office-document-editing/README.md) 定义文档多实例、ShareServer 编辑会话、 + 保存、冲突和 AI 选区修改。 - [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。 -若其他文档把工作栏描述为九个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口， +若其他文档把工作栏描述为十个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口， 或仅属于当前聊天的附属区域，以本文“能力目录稳定、面板实例由用户打开、当前上下文只提供 默认值”的产品决策为准。 diff --git a/docs/features/document-processing/README.md b/docs/features/document-processing/README.md index 47f10d8e..1cdfa29a 100644 --- a/docs/features/document-processing/README.md +++ b/docs/features/document-processing/README.md @@ -9,3 +9,7 @@ | [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 | 当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 + +Office 文件的浏览器内人工编辑、AI 选区修改、保存和撤销不属于文档解析职责，由 +[Office 协同编辑](../office-document-editing/README.md)负责。文档处理仍负责内容提取、OCR、 +旧格式转换和供模型消费的统一结构。 diff --git a/docs/features/document-processing/prd.md b/docs/features/document-processing/prd.md index 73beaab0..d4206bbf 100644 --- a/docs/features/document-processing/prd.md +++ b/docs/features/document-processing/prd.md @@ -251,6 +251,11 @@ ZIP 根目录包含模型文件和 `goodbuddy-model.json`。清单格式为 `goo ## 8. Office 与转换 +本节只定义 Office 文件的语义解析和格式转换，不提供可视化编辑器、编辑会话、选区、撤销或 +保存回写。通过 ShareServer 集成浏览器编辑器的设计见 +[Office 协同编辑](../office-document-editing/README.md)。编辑服务可以复用转换产物，但不能 +替代本地优先的聊天附件和知识库解析路径。 + ### 8.1 新格式 - DOCX：正文、标题、表格、批注和图片关系； diff --git a/docs/features/office-document-editing/README.md b/docs/features/office-document-editing/README.md new file mode 100644 index 00000000..de4f129d --- /dev/null +++ b/docs/features/office-document-editing/README.md @@ -0,0 +1,29 @@ +# Office 协同编辑 + +Office 协同编辑通过 ShareServer 集成 ONLYOFFICE Docs，使 GoodBuddy Desktop 可以在助手 +工作栏中打开多个文档页签，并在同一编辑器中完成人工编辑、AI 选区修改、保存、撤销和冲突处理。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [Office 协同编辑 PRD](./prd.md) | 用户问题、产品范围、功能要求和验收标准 | +| [用户故事](./user-stories.md) | 打开、多页签、保存、AI 编辑、冲突和恢复场景 | +| [功能逻辑设计](./logic-design.md) | 文档会话、保存、冲突、断线和关闭规则 | +| [界面设计](./ui-design.md) | 工作栏多实例文档页签、编辑状态和响应式行为 | +| [技术设计](./technical-design.md) | Desktop、ShareServer、ONLYOFFICE 的边界、协议、安全与实施顺序 | + +## 术语 + +- **文档页签**：助手工作栏中的多实例应用页签，标题来自文档文件名。 +- **编辑会话**：一个文档页签对应的服务端短期会话和 Desktop 本地状态。 +- **源文件**：用户明确打开的本机或托管 SSH 工作区文件。 +- **工作副本**：编辑期间由 ShareServer 管理并提供给 ONLYOFFICE 的临时版本。 +- **保存检查点**：ONLYOFFICE 已提交给 ShareServer、但不一定已经回写源文件的稳定版本。 + +文档解析、OCR 和旧格式转换继续由[文档处理](../document-processing/README.md)负责。ShareServer +的组织、服务部署和运维由独立仓库的 ShareServer 文档负责；跨端身份、传输和审计共同规则见 +[共享网络总体设计](../../architecture/share-network-architecture.md)。 + +当前功能仍处于设计阶段，尚无可验证实现，因此不建立进度文档。开始实施后再新增 +`progress.md`，只记录实际完成范围和验证证据。 diff --git a/docs/features/office-document-editing/logic-design.md b/docs/features/office-document-editing/logic-design.md new file mode 100644 index 00000000..1209f25e --- /dev/null +++ b/docs/features/office-document-editing/logic-design.md @@ -0,0 +1,117 @@ +# Office 协同编辑功能逻辑设计 + +## 1. 核心不变量 + +1. 一个文档页签只绑定一个 `DocumentEditSession`，不会随当前项目或会话切换目标。 +2. 源文件路径和替换权限只由 Desktop Main 持有。 +3. ShareServer 是服务端工作副本和保存检查点的权威，Desktop 是源文件回写结果的权威。 +4. ONLYOFFICE 报告已保存不等于源文件已经回写成功。 +5. 没有稳定保存检查点时，任何界面都不能显示“修改可恢复”。 +6. 源文件基准版本不匹配时禁止静默覆盖。 +7. 一次 AI 请求要么作为一个编辑事务完整应用，要么不产生修改。 + +## 2. 状态维度 + +编辑会话不是一个布尔状态，至少包含以下独立维度： + +```ts +type DocumentEditState = { + connection: 'connecting' | 'online' | 'offline' | 'expired' + editor: 'loading' | 'ready' | 'failed' + checkpoint: 'clean' | 'dirty' | 'saving' | 'available' | 'failed' | 'unknown' + source: 'unchanged' | 'writing' | 'saved' | 'conflict' | 'unavailable' + access: 'edit' | 'read-only' | 'revoked' +} +``` + +`checkpoint=available` 只表示 ShareServer 有可下载版本；只有 `source=saved` 才表示本机或远程 +源文件已经更新。 + +## 3. 打开流程 + +```text +用户选择文件 +-> Desktop 验证来源、格式、大小和 ShareServer 连接 +-> Desktop 冻结源文件 identity、大小和 SHA-256 +-> ShareServer 创建空编辑会话并返回一次性上传授权 +-> Desktop 流式上传工作副本并校验 SHA-256 +-> ShareServer 创建 ONLYOFFICE 配置和一次性启动授权 +-> Desktop 创建文档页签并加载编辑器 +-> ONLYOFFICE 读取 ShareServer 工作副本 +-> ready +``` + +任一步失败都进入确定失败状态。ShareServer 对未完成上传和未启动会话按短期限清理。 + +## 4. 保存流程 + +```text +编辑器提交保存 +-> ShareServer 接收 ONLYOFFICE 回调 +-> 校验会话、状态、大小、格式和内容摘要 +-> 原子发布新保存检查点 +-> Desktop 得到 checkpoint available 事件 +-> Desktop 重新读取源文件 identity 和 SHA-256 +-> 未变化：下载、复核、写临时文件、原子替换 +-> 已变化：进入 conflict，不覆盖 +-> Desktop 回报 source saved 或 conflict +``` + +相同检查点回写使用幂等键。网络超时但替换结果不确定时，Desktop 重新读取源文件摘要确认， +不能直接重复写入或声称失败。 + +## 5. 冲突决策 + +| 条件 | 结果 | +| --- | --- | +| 源文件与基准一致 | 允许原子回写 | +| 源文件不存在 | 显示来源不可用，允许另存为 | +| 源文件摘要变化 | 冲突，禁止自动覆盖 | +| 源文件只读或授权失效 | 保留检查点，允许重新授权或另存为 | +| ShareServer 检查点过期 | 不能回写，说明修改不可恢复 | + +首期冲突操作只有“打开外部版本”“另存当前编辑版本”“放弃编辑版本”和经二次确认的“替换 +外部版本”。不提供自动 OOXML 合并。 + +## 6. AI 编辑流程 + +1. 用户在编辑器内发起 AI 编辑，插件冻结当前文档 revision 和选区锚点。 +2. 选区为空、过大、包含不支持对象或会话非编辑态时拒绝发送。 +3. Desktop 将有界选区作为用户明确提供的上下文交给当前 Conversation。 +4. Agent 返回受限结构化编辑操作，不返回可执行脚本。 +5. 应用前再次比较文档 revision；已变化时要求用户重新选择或重新生成。 +6. ONLYOFFICE 插件在一个撤销上下文中执行全部操作。 +7. 任一操作失败则回滚整个事务；成功后高亮修改并使检查点变为 `dirty`。 + +AI 编辑继承发起请求的 Ask/Execute 模式。Ask 只生成建议，不调用编辑器写入；Execute 才能 +应用结构化修改。用户在编辑器中发起操作只授权当前文档和冻结选区，不授予 Agent 其他文件或 +系统能力。 + +## 7. 页签与关闭 + +- 每次打开创建新实例；相同源文件可以存在多个编辑会话，但第二个及后续实例默认只读，避免 + 两个独立保存链路互相覆盖。用户关闭原编辑会话后可以将只读实例提升为编辑。 +- 同名文件使用显示序号区分，序号只属于当前工作栏布局，不写入文件或服务端标题。 +- 关闭 clean 页签直接结束会话。 +- 关闭 dirty、saving、available、failed 或 unknown 页签必须根据可恢复事实给出对应选择。 +- 应用退出复用同一判断；不能等待无限期保存。超时后保留 ShareServer 已确认检查点，并在下次 + 启动显示恢复入口。 + +## 8. 断线与撤销 + +- Desktop 断线不主动销毁服务端会话；在保留期内可以使用同一会话 ID 重新认证恢复。 +- ShareServer 与 ONLYOFFICE 断线时禁止新编辑，保留最后稳定检查点和明确错误阶段。 +- 权限被撤销后立即停止新读取、保存和 AI 操作；已经下载到 Desktop 的本地源文件不由服务端 + 删除。 +- 撤销只作用于编辑器当前撤销栈。已经回写源文件后执行撤销会产生新的 dirty revision，仍需 + 再次保存才能更新源文件。 + +## 9. 需求映射 + +| 逻辑 | PRD | 用户故事 | +| --- | --- | --- | +| 打开和会话创建 | FR-1、FR-2、FR-7、FR-12 | US-A1、US-A2、US-D2 | +| 检查点和源文件回写 | FR-4、FR-5 | US-B1 | +| 冲突和关闭 | FR-8、FR-10 | US-B2、US-B3 | +| AI 编辑事务与模式 | FR-6 | US-C1、US-C2 | +| 断线、撤销和保留 | FR-9、FR-11 | US-D1、US-E1 | diff --git a/docs/features/office-document-editing/prd.md b/docs/features/office-document-editing/prd.md new file mode 100644 index 00000000..7bc94b5a --- /dev/null +++ b/docs/features/office-document-editing/prd.md @@ -0,0 +1,127 @@ +# Office 协同编辑 PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.1 | +| 日期 | 2026-09-09 | +| 适用产品 | 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 可以读取用户明确选择的内容，并将一次 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 模式 +可以生成建议，但不得调用编辑器写入。 + +### 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 或普通设置导出。 + +## 5. 文件范围 + +首期可编辑格式： + +| 类型 | 格式 | 编辑器类型 | +| --- | --- | --- | +| 文档 | `.docx` | `word` | +| 表格 | `.xlsx` | `cell` | +| 演示文稿 | `.pptx` | `slide` | + +PDF 保持预览或文档处理用途，不进入首期 Office 编辑。宏格式、模板格式、受密码保护文件和包含 +活动内容的文件默认拒绝，后续必须单独完成格式、安全和保存兼容性设计。 + +## 6. 验收标准 + +- 三个 Desktop 操作系统均能从同一 ShareServer 打开、编辑和保存三种首期格式。 +- 同一工作栏至少可以同时保留两个独立文档页签，切换不会串文件、选区或保存状态。 +- 同名文件的页签可辨认，页签标题和完整来源一致。 +- 保存失败、回调失败和源文件冲突均不会破坏原文件。 +- 每次 AI 修改可以单次撤销，拒绝或取消不会产生部分修改。 +- ShareServer 不可用时已有本地文件仍可由默认应用打开，但不能伪装成内置编辑可用。 +- Renderer、编辑器页面和日志中均不存在本机绝对路径、ShareServer 管理密钥或长期文件令牌。 +- 文档会话过期后，旧启动 URL、文件 URL 和回调令牌均不可重用。 diff --git a/docs/features/office-document-editing/technical-design.md b/docs/features/office-document-editing/technical-design.md new file mode 100644 index 00000000..d424757e --- /dev/null +++ b/docs/features/office-document-editing/technical-design.md @@ -0,0 +1,217 @@ +# Office 协同编辑技术设计 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.1 | +| 日期 | 2026-09-09 | +| 关联 PRD | [Office 协同编辑 PRD](./prd.md) | +| 跨端架构 | [ShareServer 联邦网络总体设计](../../architecture/share-network-architecture.md) | + +## 1. 技术选型 + +首个 Provider 使用 ONLYOFFICE Docs Developer Edition。采用前必须确认当前许可证、桌面应用 +分发权、并发连接口径、白标、Automation API、离线私有部署和安全支持；技术设计不构成授权 +结论。 + +不采用： + +- ONLYOFFICE Desktop Editors：它是独立桌面产品，不是 GoodBuddy 工作栏嵌入 SDK。 +- Node/Python OOXML 库：只提供生成或结构化处理，不提供高保真画布、选区和撤销栈。 +- Microsoft WOPI：第三方接入资格和云授权不适合作为 GoodBuddy 默认能力。 +- 自研 OOXML 渲染器：格式兼容和编辑成本超出当前产品边界。 + +后续 Provider 可以增加 Univer Sheets，但只能按通过验收的格式和能力声明，不能由“纯前端”推导 +为完整 Office 兼容。 + +## 2. 组件边界 + +```text +GoodBuddy Renderer + └─ 文档 Tab 外壳、公开状态、用户命令 + +GoodBuddy Main + ├─ DocumentEditSessionService + ├─ 本地/SSH 源文件 Grant 与校验 + ├─ 上传、下载、原子回写和冲突检测 + ├─ OfficeEditorView 生命周期 + └─ 本地活动记录 + +ShareServer + ├─ 用户、设备、组织和策略认证 + ├─ Office 会话 API 与短期启动授权 + ├─ 工作副本、保存检查点和保留清理 + ├─ ONLYOFFICE JWT、文件 URL 和 callback handler + ├─ 编辑器版本、健康、配额和审计 + └─ 可选 AI 编辑消息中继 + +ONLYOFFICE Document Server + └─ Word、Spreadsheet、Presentation Web Editors +``` + +ShareServer 可以把 ONLYOFFICE 和对象存储作为同一部署套件的依赖管理，但两者仍是独立服务。 +Desktop 不读取 Document Server 地址或密钥，只消费 ShareServer 返回的一次性编辑启动 URL。 + +## 3. 工作栏实例 + +在工作栏应用注册表新增多实例 `document`： + +```ts +type DocumentPanelInstance = { + id: string + capability: 'document' + documentSessionId: string + displayName: string + duplicateIndex?: number + binding: { mode: 'pinned'; target: { type: 'document-session'; id: string } } + dock: 'right' | 'bottom' | 'window' +} +``` + +持久布局只保存公开会话 ID、显示名、来源对象 ID 和停靠方式，不保存启动 URL、Cookie、文件 +令牌、绝对路径或 ONLYOFFICE 配置。应用恢复时由 Main 重新认证并判断会话能否恢复。 + +编辑器内容不使用现有静态 HTML `iframe sandbox=""`。Main 为每个已加载会话创建独立 +`WebContentsView`，固定允许的 ShareServer origin、隔离 session partition、关闭 Node +integration、开启 context isolation 和 sandbox，并禁用新窗口、任意下载、权限请求和非允许 +导航。远端页面不获得通用 Electron preload API。 + +多页签允许多个会话描述同时存在；只有经过资源验收的有限数量编辑器保持加载。非活动实例的 +具体挂起和恢复阈值在跨平台内存测试后冻结，不能未经保存检查点直接销毁 dirty 编辑器。 + +## 4. ShareServer API 边界 + +建议的服务端资源： + +```text +POST /api/v1/office/sessions +PUT /api/v1/office/sessions/{id}/source +POST /api/v1/office/sessions/{id}/launch +GET /api/v1/office/sessions/{id} +GET /api/v1/office/sessions/{id}/events +GET /api/v1/office/sessions/{id}/checkpoints/{revision} +POST /api/v1/office/sessions/{id}/source-commit +DELETE /api/v1/office/sessions/{id} + +GET /internal/office/files/{objectToken} +POST /internal/office/callback/{callbackToken} +``` + +Desktop API 使用设备凭据和组织 audience。启动 URL 使用一次性 code，交换为 HttpOnly、Secure、 +SameSite Cookie 后立即失效。ONLYOFFICE 文件 URL、callback URL 和 JWT 使用独立 audience、短 +有效期及单会话绑定，不能用于普通 ShareServer API。 + +ShareServer 不把对象存储公开 URL 直接返回 Renderer。文件下载必须重新验证用户、设备、会话、 +revision 和策略，并返回声明大小和 SHA-256。 + +## 5. 会话契约 + +```ts +type CreateDocumentEditSession = { + source: { + kind: 'workspace-file' | 'artifact' + publicSourceId: string + displayName: string + mediaType: string + size: number + sha256: string + } + requestedAccess: 'edit' | 'read-only' +} + +type DocumentEditSessionSummary = { + id: string + state: 'uploading' | 'ready' | 'editing' | 'offline' | 'expired' | 'closed' + access: 'edit' | 'read-only' + documentType: 'word' | 'cell' | 'slide' + displayName: string + sourceRevision: string + checkpoint?: { + revision: string + size: number + sha256: string + createdAt: string + } + retentionExpiresAt: string +} +``` + +远端值全部经过有界 schema 校验。`publicSourceId` 是 Desktop 管理的对象 ID，不是文件路径。 + +## 6. 文件与保存 + +- Desktop 从已授权本地或 SSH 源读取并流式计算大小和 SHA-256。 +- 上传目标由 Main 从固定 ShareServer API 获得，不接受 Renderer 提供 URL。 +- ShareServer 写入随机对象键，拒绝用户文件名决定存储路径。 +- ONLYOFFICE callback 先写临时对象，校验后原子发布为新 checkpoint。 +- Desktop 下载 checkpoint 到 GoodBuddy-owned 暂存，复核大小、SHA-256、普通文件属性和文件 + magic，再在源文件同目录创建临时文件并原子替换。 +- SSH 源文件由远程 GoodBuddy Agent 执行相同摘要、冲突和原子替换，不把远程凭据交给 + ShareServer。 +- 每次成功回写后 Desktop 将新摘要作为下一次冲突检测基准。 + +## 7. 编辑器桥与 AI 编辑 + +ShareServer 托管固定版本的 GoodBuddy ONLYOFFICE 插件。插件只能： + +- 获取当前会话和有界选区描述； +- 发起 AI 编辑请求并显示状态； +- 接收受限结构化编辑操作； +- 在一个编辑器撤销上下文中应用、回滚和高亮修改； +- 发布不含正文的 dirty、save 和 revision 事件。 + +首期优先让插件通过 ShareServer 会话通道与 Desktop 交换事件，不给远端编辑页面添加通用 +Electron preload。ShareServer 只中继有界事件；Agent 请求仍由 Desktop 创建并经过现有 +Conversation、模型、Ask/Execute、取消和活动记录边界。 + +Ask 请求可以返回可复制的修改建议，但 Main 拒绝向插件下发写操作。只有 Execute 请求能够 +取得绑定当前文档会话、revision 和选区的短期编辑 Grant；该 Grant 不包含源文件路径，也不能 +用于其他文档、文件工具或系统能力。 + +结构化操作按文档类型单独列白名单，例如文本替换、单元格值或公式更新、幻灯片对象文字 +替换。禁止传入 JavaScript、宏、任意 ONLYOFFICE 方法名或表达式求值。 + +## 8. 部署与配置 + +ShareServer 部署清单新增可选 Office 组件： + +```text +ShareServer API +PostgreSQL +兼容 S3 的对象存储 +ONLYOFFICE Document Server +Office callback worker +``` + +服务端管理配置包含 Document Server 内部地址、公开编辑 origin、JWT 密钥引用、对象存储、 +允许格式、文件大小、并发、会话期限和 checkpoint 保留。管理界面提供真实健康检查：创建最小 +文档、打开编辑器、执行保存回调并核对输出，而不是只检查 HTTP 端口。 + +Desktop 仅显示某个 ShareServer 是否声明并实际通过 `office.edit` 能力检查。未配置或不健康时 +保留文档入口并说明不可用原因。 + +## 9. 安全边界 + +1. ShareServer 和 ONLYOFFICE 之间使用独立网络和凭据，不公开管理接口。 +2. 文档内容是不可信输入；禁用宏、外部插件、任意外链加载和 Document Server 出站网络。 +3. 每个文件 URL、callback 和启动授权绑定单会话、单用途和短期限。 +4. Renderer 不接触设备凭据、ONLYOFFICE JWT、对象存储凭据或本机绝对路径。 +5. 编辑器 origin 不能调用任意 IPC、Shell、文件系统、浏览器或 Runtime 工具。 +6. 上传、下载、callback、事件和 AI 操作限制字节数、频率、并发和总时长。 +7. 服务端保留策略到期后清理工作副本、checkpoint、编辑 Cookie 和对象令牌；审计元数据按组织 + 策略独立保留。 +8. 组织管理员能够撤销 Office 能力和活动会话；撤销后 Desktop 仍保留本地源文件，不把服务端 + 删除描述为本地删除。 + +## 10. 实施顺序 + +1. 在 ShareServer 独立仓库补充 Office 服务 PRD、部署配置、对象存储和 ONLYOFFICE 许可证决策。 +2. 实现服务端最小会话、上传、启动、callback、checkpoint、下载和清理闭环。 +3. Desktop 增加多实例文档页签和只读打开，完成三平台真实视觉及资源验证。 +4. 接入源文件冲突检测、原子保存、另存为、关闭和恢复。 +5. 实现固定 ONLYOFFICE 插件及单次可撤销 AI 选区修改。 +6. 增加组织策略、配额、审计和生产部署验收。 + +不得在服务端闭环、许可证和三平台真实编辑验收前把该能力标记为已提供。 diff --git a/docs/features/office-document-editing/ui-design.md b/docs/features/office-document-editing/ui-design.md new file mode 100644 index 00000000..cc0da5e6 --- /dev/null +++ b/docs/features/office-document-editing/ui-design.md @@ -0,0 +1,83 @@ +# Office 协同编辑界面设计 + +## 1. 信息架构 + +Office 文档不是一级页面，也不是成果面板中的内嵌卡片。它是助手工作栏中可创建多个实例的 +“文档”应用。打开文件后新增文档页签，页签关闭只结束对应编辑会话。 + +```text +助手工作栏 Tab 行 +[任务] [工作区] [预算.xlsx] [方案.docx] [+] + └─ 当前文档编辑器 +``` + +“+”能力目录持续提供“文档”入口。用户从目录打开时选择已授权文件；从工作区、成果或会话文件 +引用打开时直接创建实例。 + +## 2. 页签 + +- 图标按文档、表格和演示文稿类型显示，使用现有图标库。 +- 可见标题使用文件名，不显示完整路径。 +- 同名实例依次显示 `预算.xlsx`、`预算.xlsx · 2`。 +- Tooltip 显示完整文件名、项目或成果来源、ShareServer 名称和只读状态，不显示本机绝对路径。 +- `aria-label` 包含文件名、序号和状态。 +- 加载、未保存、保存中、冲突和断线使用状态图标及可访问名称，不只依赖颜色。 +- 文档应用为 `multiple`，不因已有文档页签而聚焦或替换其他实例。 + +## 3. 文档标题栏 + +编辑器上方保留 GoodBuddy 控制的紧凑标题栏： + +- 左侧：文件名、来源范围、只读或冲突状态。 +- 中部：最近一次源文件保存结果。 +- 右侧：保存、另存为、刷新状态、在独立窗口打开和更多菜单。 + +撤销、重做、格式、查找和文档内部编辑命令使用 ONLYOFFICE 工具栏，不在 GoodBuddy 标题栏 +重复。保存按钮必须区分“正在保存到 ShareServer”和“已写回源文件”。 + +## 4. 尺寸与停靠 + +文档页签沿用工作栏右侧、底部和独立窗口三种停靠方式，但编辑器有额外宽度要求： + +| 可用宽度 | 行为 | +| --- | --- | +| `>= 720px` | 完整编辑器与完整工具栏 | +| `480px - 719px` | 编辑器精简工具栏，保留核心编辑命令 | +| `< 480px` | 不加载可编辑画布，显示文件摘要、状态和“展开编辑”命令 | + +右侧工作栏达到普通 `300px` 最小宽度时不能把完整 Office 工具栏压缩到重叠。用户选择“展开 +编辑”时切换到主内容区或独立窗口，仍复用原文档页签和编辑会话，不创建第二份文档。 + +文档画布、公式栏、幻灯片缩略图和滚动区域使用稳定尺寸；编辑器加载、状态文字或长文件名不得 +推动 Tab 行和标题栏重新布局。 + +## 5. 状态与反馈 + +| 状态 | 可见反馈 | 允许操作 | +| --- | --- | --- | +| 上传中 | 上传进度、目标 ShareServer、取消 | 取消 | +| 编辑中 | 编辑器、来源和最近保存时间 | 编辑、AI 编辑、保存 | +| 只读 | 持续只读标识和原因 | 查看、另存为 | +| 保存中 | “正在创建检查点”或“正在写回源文件” | 不重复保存，可继续查看 | +| 冲突 | 持续警告和两个版本的时间、大小 | 打开外部版本、另存、替换 | +| 断线 | 明确失败阶段和重试 | 查看最后已加载内容、重连 | +| 会话过期 | 修改是否存在稳定检查点 | 恢复检查点或关闭 | + +通知不能代替页签内持续状态。后台文档保存完成只更新页签状态和应用通知，不抢占当前页签。 + +## 6. AI 编辑 + +- AI 编辑入口出现在 ONLYOFFICE 选区工具栏或 GoodBuddy 编辑器插件中。 +- 点击后使用紧凑指令输入框；当前选区类型和范围持续可见。 +- 发送前显示将使用的 Conversation、模型和 ShareServer，不展示内部选区 ID。 +- 处理中锁定本次选区事务，不锁定整个文档的阅读和滚动。 +- 成功后高亮所有修改位置，并显示可用的撤销命令。 +- 文档 revision 已变化时不静默套用旧结果，要求重新选择或重新生成。 + +## 7. 可访问性与主题 + +- GoodBuddy 外壳遵循根级 `UI-DESIGN.md` 的主题和焦点规则。 +- 编辑器主题跟随应用主题，但第三方编辑器无法完整匹配时优先保证可读性，不注入脆弱的 DOM + 样式覆盖。 +- Tab、标题栏和冲突对话框支持完整键盘操作及明确焦点恢复。 +- 第三方编辑器页面必须提供可识别标题；加载失败后焦点回到重试命令。 diff --git a/docs/features/office-document-editing/user-stories.md b/docs/features/office-document-editing/user-stories.md new file mode 100644 index 00000000..6ad36da4 --- /dev/null +++ b/docs/features/office-document-editing/user-stories.md @@ -0,0 +1,85 @@ +# Office 协同编辑用户故事 + +## US-A1 打开本地文档 + +**Given** 用户已连接支持 Office 编辑的 ShareServer，并在工作区选择一个受支持文件 + +**When** 用户选择“在文档页签中打开” + +**Then** GoodBuddy 显示目标服务和数据去向，验证并上传工作副本，然后以文件名创建新文档 +页签；失败不会修改源文件或留下可重用文件授权。 + +## US-A2 同时打开多个文档 + +**Given** 工作栏已经存在一个文档页签 + +**When** 用户打开另一个文档或再次打开同一文档 + +**Then** 工作栏创建独立页签，不替换现有实例；同名页签可辨认，文件、选区和保存状态不串联。 + +## US-B1 人工编辑并保存 + +**Given** 文档编辑器已进入可编辑状态 + +**When** 用户修改内容并保存 + +**Then** ShareServer 先形成稳定检查点，Desktop 确认源文件未被外部修改后原子回写，并明确 +显示“已写回源文件”。 + +## US-B2 源文件发生冲突 + +**Given** 用户编辑期间源文件被其他程序修改 + +**When** 新检查点准备回写 + +**Then** GoodBuddy 禁止静默覆盖，并允许用户查看外部版本、另存编辑版本、放弃编辑版本或经 +二次确认替换。 + +## US-B3 关闭未保存文档 + +**Given** 页签存在未形成检查点或尚未回写源文件的修改 + +**When** 用户关闭页签或退出应用 + +**Then** GoodBuddy 根据真实可恢复状态提供保存、放弃或取消，不把未知结果显示为已保存。 + +## US-C1 使用 AI 修改选区 + +**Given** 当前 Conversation 使用 Execute，用户在编辑器中选择受支持内容 + +**When** 用户提交 AI 修改要求 + +**Then** Agent 只接收有界选区和必要上下文，编辑器将完整结果作为一个事务应用并允许单次撤销。 + +## US-C2 Ask 模式请求修改 + +**Given** 当前 Conversation 使用 Ask + +**When** 用户请求 AI 修改当前选区 + +**Then** GoodBuddy 可以生成修改建议，但不会调用编辑器写入；界面提供切换 Execute 后重新应用 +的明确入口。 + +## US-D1 网络中断后恢复 + +**Given** 编辑会话已经建立 + +**When** Desktop、ShareServer 或 ONLYOFFICE 之间的连接中断后恢复 + +**Then** 页签保留并显示失败阶段；只有 ShareServer 确认存在稳定检查点时才提供恢复和回写。 + +## US-D2 服务未配置或不健康 + +**Given** 用户没有连接支持 Office 编辑的 ShareServer，或服务健康检查失败 + +**When** 用户打开文档能力 + +**Then** 入口仍可发现并解释不可用原因，同时保留使用系统默认应用打开本地文件的独立操作。 + +## US-E1 权限撤销和保留到期 + +**Given** 管理员撤销编辑权限，或编辑会话达到保留期限 + +**When** 用户继续访问旧页签 + +**Then** 新读取、保存和 AI 操作被拒绝，旧令牌不能重用，本地源文件不受服务端清理影响。