docs: design ShareServer Office editing

2026-09-09 12:43:00 +08:00
parent 5782667a40
commit b6d4633a33
12 changed files with 747 additions and 9 deletions
@@ -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

@@ -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 与模型连接

@@ -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)
@@ -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 自动裁剪的动态入口，
 或仅属于当前聊天的附属区域，以本文“能力目录稳定、面板实例由用户打开、当前上下文只提供
 默认值”的产品决策为准。
@@ -9,3 +9,7 @@
 | [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 |

 当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
+
+Office 文件的浏览器内人工编辑、AI 选区修改、保存和撤销不属于文档解析职责，由
+[Office 协同编辑](../office-document-editing/README.md)负责。文档处理仍负责内容提取、OCR、
+旧格式转换和供模型消费的统一结构。
@@ -251,6 +251,11 @@ ZIP 根目录包含模型文件和 `goodbuddy-model.json`。清单格式为 `goo

 ## 8. Office 与转换

+本节只定义 Office 文件的语义解析和格式转换，不提供可视化编辑器、编辑会话、选区、撤销或
+保存回写。通过 ShareServer 集成浏览器编辑器的设计见
+[Office 协同编辑](../office-document-editing/README.md)。编辑服务可以复用转换产物，但不能
+替代本地优先的聊天附件和知识库解析路径。
+
 ### 8.1 新格式

 - DOCX：正文、标题、表格、批注和图片关系；
@@ -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`，只记录实际完成范围和验证证据。
@@ -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 |
@@ -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 和回调令牌均不可重用。
@@ -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. 增加组织策略、配额、审计和生产部署验收。
+
+不得在服务端闭环、许可证和三平台真实编辑验收前把该能力标记为已提供。
@@ -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、标题栏和冲突对话框支持完整键盘操作及明确焦点恢复。
+- 第三方编辑器页面必须提供可识别标题；加载失败后焦点回到重试命令。
@@ -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 操作被拒绝，旧令牌不能重用，本地源文件不受服务端清理影响。