root/goodbuddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: design ShareServer Office editing

Browse Source
This commit is contained in:
mesalogo
2026-09-09 12:43:00 +08:00
parent 5782667a40
commit b6d4633a33
12 changed files with 747 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
FEATURES.md
+8
View File
@@ -77,6 +77,14 @@ otherwise.
attachments and knowledge remain in the conversation composer, while memory, attachments and knowledge remain in the conversation composer, while memory,
when implemented, and historical execution context belong to the associated Task. See when implemented, and historical execution context belong to the associated Task. See
the [Feature PRD](./docs/features/assistant-workbar/prd.md). 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 ### Agent Runtimes and model connections
FEATURES.zh-CN.md
+1
View File
@@ -25,6 +25,7 @@
- [ ] **项目 Agent Space**（规划中）：在 Project 中统一角色、知识、Skills/MCP、模型、审批策略、预算和超时，并支持模板复用。 - [ ] **项目 Agent Space**（规划中）：在 Project 中统一角色、知识、Skills/MCP、模型、审批策略、预算和超时，并支持模板复用。
- [ ] **应用导航与系统工具快捷入口**（仅设计）：规划固定系统入口、内置应用显隐和打开现有工作栏的底部工具按钮；尚未实现新界面。详见[设计文档](./docs/features/application-tool-navigation/README.md)。 - [ ] **应用导航与系统工具快捷入口**（仅设计）：规划固定系统入口、内置应用显隐和打开现有工作栏的底部工具按钮；尚未实现新界面。详见[设计文档](./docs/features/application-tool-navigation/README.md)。
- [ ] **通用助手工作栏与执行空间后续能力**（规划中）：在现有工作栏和多终端基础上继续加入监督、统一 Runtime、受管进程、静态安全 HTML 预览、可固定目标的工作区/浏览器/成果实例、底部停靠与独立窗口。Task Center 保持 Task 的单例索引，附件与知识库继续由会话输入区管理，未来的记忆与历史执行上下文归入关联 Task。详见 [Feature PRD](./docs/features/assistant-workbar/prd.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 与模型连接 ### Agent Runtime 与模型连接
docs/architecture/share-network-architecture.md
+43 -3
View File
@@ -5,8 +5,8 @@
| 项目 | 内容 | | 项目 | 内容 |
| --- | --- | | --- | --- |
| 状态 | 设计中 | | 状态 | 设计中 |
| 版本 | 0.1 | | 版本 | 0.2 |
| 日期 | 2026-09-03 | | 日期 | 2026-09-09 |
| 适用范围 | GoodBuddy 桌面端、ShareServer、网关间联邦协议 | | 适用范围 | GoodBuddy 桌面端、ShareServer、网关间联邦协议 |
| 桌面端设计 | [设备发现与共享](../features/device-sharing/README.md) | | 桌面端设计 | [设备发现与共享](../features/device-sharing/README.md) |
| 服务端设计 | [ShareServer](../../../goodbuddy-shareserver/docs/features/share-server/README.md) | | 服务端设计 | [ShareServer](../../../goodbuddy-shareserver/docs/features/share-server/README.md) |
@@ -26,7 +26,7 @@
1. **GoodBuddy Desktop** 在设置中提供“设备发现与共享”，默认使用局域网发现与直连，也可 1. **GoodBuddy Desktop** 在设置中提供“设备发现与共享”，默认使用局域网发现与直连，也可
由用户额外连接一个或多个 ShareServer。 由用户额外连接一个或多个 ShareServer。
2. **ShareServer** 是独立部署、独立升级的 Web 服务，提供组织、设备、能力、权限、更新、 2. **ShareServer** 是独立部署、独立升级的 Web 服务，提供组织、设备、能力、权限、更新、
联邦、中继和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。 联邦、中继、Office 编辑和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。
### 2.2 能力优先，来源可见 ### 2.2 能力优先，来源可见
@@ -55,6 +55,17 @@ ShareServer 负责身份、目录、策略、任务路由、更新和审计。
直接建立；网络条件不允许时，可按组织策略使用 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. 术语 ## 3. 术语
| 术语 | 定义 | | 术语 | 定义 |
@@ -71,6 +82,7 @@ ShareServer 负责身份、目录、策略、任务路由、更新和审计。
| `Task` | 一次远程能力调用及其输入、执行、输出和终态 | | `Task` | 一次远程能力调用及其输入、执行、输出和终态 |
| `Package` | 可下载到本机安装的签名能力工件 | | `Package` | 可下载到本机安装的签名能力工件 |
| `FederationTrust` | 两个组织网关之间经管理员确认的双边信任关系 | | `FederationTrust` | 两个组织网关之间经管理员确认的双边信任关系 |
| `DocumentEditSession` | ShareServer 托管的单文档短期编辑会话、工作副本和保存检查点 |
“网关”是 ShareServer 的网络角色；产品名称为 `ShareServer`，独立仓库为 “网关”是 ShareServer 的网络角色；产品名称为 `ShareServer`，独立仓库为
`goodbuddy-shareserver`。 `goodbuddy-shareserver`。
@@ -84,6 +96,10 @@ GoodBuddy Desktop A <-- mDNS 发现 + 配对后 TLS 直连 --> GoodBuddy Desktop
单组织： 单组织：
GoodBuddy Desktop A -- 出站连接 --> ShareServer <-- 出站连接 -- Provider Device B GoodBuddy Desktop A -- 出站连接 --> ShareServer <-- 出站连接 -- Provider Device B
Office 编辑：
GoodBuddy Desktop --> ShareServer --> ONLYOFFICE Docs
└-------> 临时工作副本与保存检查点
跨组织： 跨组织：
Desktop A --> ShareServer A <== 联邦信任 ==> ShareServer B <-- Provider Device B 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. 数据与审计
### 12.1 最小审计事件 ### 12.1 最小审计事件
@@ -358,6 +385,8 @@ created/awaiting_approval/queued/connecting -> rejected | expired | cancelled
- 桌面端是本地配对、本机共享偏好和本地活动记录的权威。 - 桌面端是本地配对、本机共享偏好和本地活动记录的权威。
- ShareServer 是组织成员、设备注册、组织策略、发布目录和组织审计的权威。 - ShareServer 是组织成员、设备注册、组织策略、发布目录和组织审计的权威。
- ShareServer 是 Office 工作副本、服务端保存检查点、编辑会话和保留清理的权威；Desktop 或
远程 GoodBuddy Agent 是源文件是否成功回写的权威。
- 能力提供者是运行中任务及结果是否产生的权威。 - 能力提供者是运行中任务及结果是否产生的权威。
- 联邦两端各自保存本组织审计，不复制对方完整成员目录或内部策略。 - 联邦两端各自保存本组织审计，不复制对方完整成员目录或内部策略。
@@ -376,6 +405,10 @@ ShareServer 可以部署到公网，因此公网连接、外部组织和服务
8. 密钥只进入对应安全存储，诊断和审计使用固定字段与脱敏错误码。 8. 密钥只进入对应安全存储，诊断和审计使用固定字段与脱敏错误码。
9. 限制握手、清单、帧、文件、并发、速率、任务时长和审计查询大小。 9. 限制握手、清单、帧、文件、并发、速率、任务时长和审计查询大小。
10. 撤销设备、用户、Grant、Publication、Package 或 FederationTrust 后停止签发新令牌。 10. 撤销设备、用户、Grant、Publication、Package 或 FederationTrust 后停止签发新令牌。
11. Office 编辑器使用固定 origin 和隔离会话，不获得 Electron、文件系统、Shell、Runtime 或
普通 ShareServer 管理 API；Document Server 默认禁止任意出站网络和未批准插件。
12. Office 文件正文由服务端实际处理，组织策略必须定义允许格式、大小、保留和内容访问角色，
Desktop 在上传前显示这些事实。
## 14. 建议领域实体 ## 14. 建议领域实体
@@ -401,6 +434,8 @@ PackageRelease
FederationTrust FederationTrust
AuditEvent AuditEvent
Revocation Revocation
DocumentEditSession
DocumentCheckpoint
``` ```
共享协议只定义跨端 DTO 和状态，不规定桌面 SQLite 与 ShareServer 数据库使用相同表结构。 共享协议只定义跨端 DTO 和状态，不规定桌面 SQLite 与 ShareServer 数据库使用相同表结构。
@@ -442,6 +477,10 @@ ShareServer 不反向依赖桌面端 `src/shared`，构建和运行不要求桌
- [ ] 跨组织调用同时满足两端策略；联邦撤销后不能创建新任务。 - [ ] 跨组织调用同时满足两端策略；联邦撤销后不能创建新任务。
- [ ] 审计默认只保存必要元数据，不保存正文、文件、密钥或认证信息。 - [ ] 审计默认只保存必要元数据，不保存正文、文件、密钥或认证信息。
- [ ] ShareServer 可独立部署和升级，不由 Electron 启动，也不影响桌面端离线使用。 - [ ] ShareServer 可独立部署和升级，不由 Electron 启动，也不影响桌面端离线使用。
- [ ] 启用 Office 服务后，Desktop 可在多实例文档页签中编辑 DOCX、XLSX 和 PPTX；保存回调、
源文件冲突或网络故障均不会破坏原文件。
- [ ] Office 会话的启动、文件和 callback 凭据不可互换，过期或撤销后不能重用；临时工作副本
按策略清理，默认审计不保存文档正文或 AI 选区内容。
## 17. 相关设计 ## 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/logic-design.md)
- [ShareServer 管理界面](../../../goodbuddy-shareserver/docs/features/share-server/ui-design.md) - [ShareServer 管理界面](../../../goodbuddy-shareserver/docs/features/share-server/ui-design.md)
- [ShareServer 技术设计](../../../goodbuddy-shareserver/docs/features/share-server/technical-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) - [SSH 远程主机与 Agent](../features/remote-host/README.md)
- [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md) - [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md)
docs/features/assistant-workbar/prd.md
+28 -6
View File
@@ -36,8 +36,8 @@ Runtime 统一抽象为“执行空间”。
### 2.1 助手工作栏 ### 2.1 助手工作栏
助手工作栏是 GoodBuddy 中始终可访问的应用级工具容器。它提供稳定能力目录，用户从中 助手工作栏是 GoodBuddy 中始终可访问的应用级工具容器。它提供稳定能力目录，用户从中
查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器、资源监控 查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器、资源监控、
和成果面板实例。稳定的是能力的可发现性，不是九个同时占据界面的固定面板。 成果和文档面板实例。稳定的是能力的可发现性，不是十个同时占据界面的固定面板。
工作栏不是： 工作栏不是：
@@ -85,6 +85,7 @@ Runtime
浏览器 浏览器
资源监控 资源监控
成果 成果
文档
``` ```
- 应用不得根据当前项目、会话、Runtime、主机或探测结果无提示地增删能力目录项。 - 应用不得根据当前项目、会话、Runtime、主机或探测结果无提示地增删能力目录项。
@@ -109,6 +110,7 @@ Runtime
使用本机 Home。 使用本机 Home。
- 工作区默认显示当前项目目录，用户可以打开其他本机目录或远程目录。 - 工作区默认显示当前项目目录，用户可以打开其他本机目录或远程目录。
- 成果默认使用当前范围，用户可以切换到项目、全局或其他允许范围。 - 成果默认使用当前范围，用户可以切换到项目、全局或其他允许范围。
- 文档创建时固定到用户明确打开的文件和 ShareServer 编辑会话，不提供跟随模式。
- 下一次请求的附件和知识库由当前 Composer 展示与管理，不作为工作栏能力。历史执行上下文 - 下一次请求的附件和知识库由当前 Composer 展示与管理，不作为工作栏能力。历史执行上下文
随关联 Task 查看；记忆功能实现后也归入任务中心，而不是新增独立上下文面板。 随关联 Task 查看；记忆功能实现后也归入任务中心，而不是新增独立上下文面板。
@@ -203,7 +205,7 @@ Runtime
### 6.2 能力目录与面板实例 ### 6.2 能力目录与面板实例
能力目录不等于同时打开九个面板。当前产品采用“已打开实例 Tab + 持久新增按钮”的工作栏 能力目录不等于同时打开十个面板。当前产品采用“已打开实例 Tab + 持久新增按钮”的工作栏
模型：Tab 行只显示已打开实例，行末“+”始终可见；点击后在工作栏内容区打开稳定能力目录， 模型：Tab 行只显示已打开实例，行末“+”始终可见；点击后在工作栏内容区打开稳定能力目录，
用户再创建或激活应用实例。详细交互以 用户再创建或激活应用实例。详细交互以
[助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。 [助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。
@@ -473,7 +475,20 @@ Task 呈现来源，不把 Run 作为导航对象。
- 不使用 `dangerouslySetInnerHTML`，不启用 Electron `webviewTag`。 - 不使用 `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' | 'browser'
| 'resources' | 'resources'
| 'results' | 'results'
| 'document'
type WorkbarTargetRef = type WorkbarTargetRef =
| { type: 'conversation'; id: string } | { type: 'conversation'; id: string }
@@ -511,6 +527,7 @@ type WorkbarTargetRef =
| { type: 'managed-process'; id: string } | { type: 'managed-process'; id: string }
| { type: 'browser-session'; id: string } | { type: 'browser-session'; id: string }
| { type: 'artifact'; id: string } | { type: 'artifact'; id: string }
| { type: 'document-session'; id: string }
``` ```
Renderer 选择目标后，Main 必须重新验证对象存在、归属范围和当前用户可见性。不能把目标 ID Renderer 选择目标后，Main 必须重新验证对象存在、归属范围和当前用户可见性。不能把目标 ID
@@ -941,7 +958,7 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
### 17.1 稳定能力目录与用户控制 ### 17.1 稳定能力目录与用户控制
- [ ] 九个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。 - [ ] 十个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。
- [ ] Task Center 继续作为 Task 的单例索引，不删除入口、不复制会话，也不混入 Job、Run 或心跳事项。 - [ ] Task Center 继续作为 Task 的单例索引，不删除入口、不复制会话，也不混入 Job、Run 或心跳事项。
- [ ] 项目、会话、Runtime 或主机变化不会无提示地增删能力目录项。 - [ ] 项目、会话、Runtime 或主机变化不会无提示地增删能力目录项。
- [ ] 用户可以按需打开、关闭、排序和停靠面板实例。 - [ ] 用户可以按需打开、关闭、排序和停靠面板实例。
@@ -956,6 +973,8 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
- [ ] 监督可以作用于普通 Conversation、Task 和后续实验对象，不假设编程语境。 - [ ] 监督可以作用于普通 Conversation、Task 和后续实验对象，不假设编程语境。
- [ ] 工作区不是 Git 仓库时仍可浏览文件。 - [ ] 工作区不是 Git 仓库时仍可浏览文件。
- [ ] Runtime 不支持某项原生能力时仍可从目录打开面板并获得准确说明。 - [ ] Runtime 不支持某项原生能力时仍可从目录打开面板并获得准确说明。
- [ ] 文档能力可以打开多个以文件名命名的固定实例；未配置健康 ShareServer 时显示原因，
不把系统默认应用或静态预览冒充内置编辑。
### 17.3 安全与控制 ### 17.3 安全与控制
@@ -999,6 +1018,7 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
- [ ] 创建中、Agent 操作中和完整交互期间禁用浏览器其余工具栏控件；活动加载仍可单独停止， - [ ] 创建中、Agent 操作中和完整交互期间禁用浏览器其余工具栏控件；活动加载仍可单独停止，
且停止加载不会关闭会话或释放 Runtime 上下文。 且停止加载不会关闭会话或释放 Runtime 上下文。
- [ ] 活动 Conversation 没有浏览器会话时，可从同一地址栏按 Agent 相同 URL 策略启动会话。 - [ ] 活动 Conversation 没有浏览器会话时，可从同一地址栏按 Agent 相同 URL 策略启动会话。
- [ ] 文档编辑器在右侧宽度不足时不发生工具栏或正文重叠，并可使用同一会话展开到可编辑布局。
## 18. 相关文档的职责 ## 18. 相关文档的职责
@@ -1015,8 +1035,10 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
- [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md) 定义该 Runtime 的具体适配边界。 - [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md) 定义该 Runtime 的具体适配边界。
- [SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md) - [SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md)
定义 Host 级组件获取、首次准备、更新、回退和项目只验证边界。 定义 Host 级组件获取、首次准备、更新、回退和项目只验证边界。
- [Office 协同编辑](../office-document-editing/README.md) 定义文档多实例、ShareServer 编辑会话、
保存、冲突和 AI 选区修改。
- [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。 - [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。
若其他文档把工作栏描述为九个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口， 若其他文档把工作栏描述为十个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口，
或仅属于当前聊天的附属区域，以本文“能力目录稳定、面板实例由用户打开、当前上下文只提供 或仅属于当前聊天的附属区域，以本文“能力目录稳定、面板实例由用户打开、当前上下文只提供
默认值”的产品决策为准。 默认值”的产品决策为准。
docs/features/document-processing/README.md
+4
View File
@@ -9,3 +9,7 @@
| [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 | | [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 |
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
Office 文件的浏览器内人工编辑、AI 选区修改、保存和撤销不属于文档解析职责，由
[Office 协同编辑](../office-document-editing/README.md)负责。文档处理仍负责内容提取、OCR、
旧格式转换和供模型消费的统一结构。
docs/features/document-processing/prd.md
+5
View File
@@ -251,6 +251,11 @@ ZIP 根目录包含模型文件和 `goodbuddy-model.json`。清单格式为 `goo
## 8. Office 与转换 ## 8. Office 与转换
本节只定义 Office 文件的语义解析和格式转换，不提供可视化编辑器、编辑会话、选区、撤销或
保存回写。通过 ShareServer 集成浏览器编辑器的设计见
[Office 协同编辑](../office-document-editing/README.md)。编辑服务可以复用转换产物，但不能
替代本地优先的聊天附件和知识库解析路径。
### 8.1 新格式 ### 8.1 新格式
- DOCX：正文、标题、表格、批注和图片关系； - DOCX：正文、标题、表格、批注和图片关系；
docs/features/office-document-editing/README.md
+29
View File
@@ -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`，只记录实际完成范围和验证证据。
docs/features/office-document-editing/logic-design.md
+117
View File
@@ -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 |
docs/features/office-document-editing/prd.md
+127
View File
@@ -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 和回调令牌均不可重用。
docs/features/office-document-editing/technical-design.md
+217
View File
@@ -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. 增加组织策略、配额、审计和生产部署验收。
不得在服务端闭环、许可证和三平台真实编辑验收前把该能力标记为已提供。
docs/features/office-document-editing/ui-design.md
+83
View File
@@ -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、标题栏和冲突对话框支持完整键盘操作及明确焦点恢复。
- 第三方编辑器页面必须提供可识别标题；加载失败后焦点回到重试命令。
docs/features/office-document-editing/user-stories.md
+85
View File
@@ -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 操作被拒绝，旧令牌不能重用，本地源文件不受服务端清理影响。