goodbuddy-shareserver/docs/features/share-server/prd.md

ShareServer PRD

文档信息

项目	内容
状态	设计中
版本	0.3
日期	2026-09-09
适用产品	独立部署的 ShareServer 与 Web 管理控制台
关联架构	共享网络总体设计
关联文档	功能逻辑、管理界面、技术设计

1. 背景

局域网配对适合附近设备，但不能统一解决跨网络访问、成员离职、组织策略、集中更新、审计和 跨组织协作。ShareServer 提供一个可自建的组织控制面，让设备通过主动出站连接注册能力并 接收任务，不要求为每台桌面设备开放公网端口。

2. 产品目标

1. 组织可在自有网络、私有云或公网独立部署 ShareServer。
2. 管理员可统一管理用户、组、设备、能力、权限、更新和审计。
3. 成员通过桌面端使用获准能力，无需日常进入管理控制台。
4. 设备离线、用户撤销或策略变化能准确影响新任务，不破坏历史证据。
5. 两个组织可经双边确认建立有限范围的联邦协作。
6. ShareServer 可以只运行控制面，也可按部署策略提供数据中继和包存储。
7. 成员可以显式开放自己的数字人，获准的组织成员可通过 @数字人 发起有界协作任务。
8. 部署方可以启用 ONLYOFFICE Docs，使 Desktop 在多个文档 Tab 中编辑 DOCX、XLSX 和 PPTX。

3. 产品范围

3.1 包含

• 本地账号及可配置 OIDC 身份源。
• 组织、成员、角色、用户组、设备组和服务账号。
• 设备注册、状态、撤销和合规元数据。
• 能力目录、Publication、Grant、强制策略和审批。
• 设备出站控制通道、任务路由、取消和可选中继。
• 签名能力包仓库、发布通道、更新策略和撤销。
• ShareServer 间双边联邦。
• 组织数字人目录、数字人 Publication、授权发现和 @数字人 调用。
• 可选 Office 编辑服务、工作副本、保存检查点、编辑器启动和 ONLYOFFICE callback。
• 审计、用量、保留和导出。
• Web 管理控制台和成员自助页面。

3.2 不包含

• 远程管理设备桌面、任意 Shell 或任意文件系统。
• 发现未注册的局域网设备。
• 保存或分发用户 API Key、Cookie 和桌面登录状态。
• 默认查看任务正文、附件和模型输出。
• 上传、同步或浏览数字人所有者的本地个人、项目、会话和原始 Agent 记忆。
• 因为成员加入组织而自动开放其数字人、记忆、Runtime、工作区或工具。
• 未经提供者发布自动盘点设备能力。
• 自动信任同域邮箱、同一网络或其他 ShareServer。
• 公共开放市场、计费结算或匿名能力调用。
• 替代 GoodBuddy 官方客户端、模型和 Agent 发布源。
• 自行实现 Office 渲染器，或把 ONLYOFFICE Document Server 打进 Desktop 安装包。
• 默认永久保存用户文档、选区、提示词或模型输出。

4. 功能需求

FR-1 实例初始化

• 首次启动通过一次性引导创建实例标识和首个系统管理员。
• 引导完成后永久关闭初始化入口，后续管理员通过正常身份流程创建。
• 实例公开描述包含名称、协议版本、登录方式和联邦端点，不包含内部拓扑。

FR-2 身份与组织

• 支持一个实例承载多个隔离组织，也支持部署为单组织模式。
• 支持本地账号和 OIDC；组织可限制允许的身份源。
• 成员可以属于多个组并拥有有界角色，角色不隐式跨组织。
• 停用用户立即停止签发新设备和任务凭据。

FR-3 设备管理

• 桌面端经用户登录、一次性挑战和设备签名完成注册。
• 设备条目显示所有者、平台、客户端版本、最近在线、连接和撤销状态。
• 设备主动建立出站控制连接；服务端不能借此调用未发布能力。
• 管理员可撤销设备并终止其新任务资格。

FR-4 能力目录

• 只接收已注册设备或服务节点提交的显式 Publication。
• 目录按调用者身份、设备状态、组织和策略过滤后返回。
• 支持同一能力多个版本和多个 provider，不掩盖来源。
• provider 离线时保留目录事实但显示不可用，不派发新任务。
• 数字人作为由具体设备或服务节点提供的复合 Agent 能力进入目录，持续显示所有者、提供者、 运行位置和可调用状态，不伪装成 ShareServer 自身能力。

FR-5 授权策略

• Grant 可绑定用户、组、设备、设备组和联邦组织。
• 可约束能力、版本、动作、输入类型、数据分类、提供者、时间、次数、并发和委托。
• 支持组织强制策略和用户可收紧偏好；拒绝优先。
• 每个决定返回稳定结果、命中策略和面向用户的原因。

FR-6 审批

• 调用、能力发布、数字人上线或范围扩大、权限扩大更新和联邦关系可以要求审批。
• 审批项显示申请人、对象、影响范围、数据类别、期限和策略依据。
• 批准结果有明确范围和有效期，不提供无边界“永久允许”。
• 申请内容变化后旧审批失效。

FR-7 任务路由

• 根据冻结 provider、在线连接和路由策略把任务声明发送给目标设备。
• 支持直连协商、网关中继和取消传播。
• 任务正文与控制元数据分离；默认审计不保存正文。
• 已接受任务断线后允许查询同一 task，不自动创建重复执行。

FR-8 能力包与更新

• 保存不可变签名 Package 和发布目录。
• 支持组织、组、平台、架构和维护窗口的更新策略。
• 支持固定版本、允许版本范围、暂停发布和紧急撤销。
• 权限扩大必须触发新批准，不能被普通自动更新策略覆盖。
• 包来源、大小、摘要、签名和下载结果可审计。

FR-9 联邦

• 两个 ShareServer 通过指纹交换和双方管理员确认建立关系。
• 双方分别配置公开能力、允许主体、数据范围、用量和期限。
• 最终权限取双方策略交集；任一端撤销后停止新任务。
• 不默认链式转发到第三个组织。

FR-10 审计与用量

• 记录身份、设备、发布、授权、审批、任务、包和联邦管理事件。
• 默认仅记录共享架构定义的有界元数据。
• 支持按组织隔离查询、条件筛选、分页和流式导出。
• 审计员只读，不能因查看日志取得任务正文或管理权限。

FR-11 管理控制台

• 提供概览、组织与成员、设备、能力目录、数字人、权限策略、审批、发布与更新、网关联邦、 任务与中继、审计、系统设置。
• 普通成员只看到自己的设备、授权和待办；管理员栏目按权限隐藏并在 API 再次校验。
• 普通成员可以管理自己发布的数字人，并发现和 @ 当前组织内获准调用的数字人。
• 所有高影响操作说明对象、范围和后果。

FR-12 可部署性

• 支持容器部署，配置与持久数据分离。
• 支持外部 PostgreSQL；对象存储和中继按功能启用。
• 提供健康、就绪、指标、结构化日志、备份和恢复说明。
• 服务升级不能要求同时升级所有在线桌面端；按协议版本协商兼容集合。

FR-13 数字人发布与组织内 @ 调用

• “数字人”是运行在成员设备或组织服务节点上的可调用 Agent Publication。一个成员可以按 不同用途发布零个或多个数字人，每个数字人独立配置 handle、能力、提供者和记忆来源； 加入组织、注册设备或创建本地 Agent 都不会自动发布。
• 发布时必须明确数字人的组织内唯一 @handle、显示名、说明、版本、提供者、支持的输入/ 输出类型、可用时间、并发、有效期、目标用户或用户组，以及 discover/inspect/invoke 动作。@数字人 是 invoke 的界面入口，不绕过 Grant 或审批。
• 数字人目录持续显示所有者、来源组织、执行设备或服务节点、Runtime 类型、版本、在线状态、 数据策略和最近可用性；重名显示名不能掩盖唯一 handle 和实际提供者。
• 获准成员在组织会话或任务输入中通过显式选择器插入 @数字人。发送前必须显示实际接收者、 执行位置、将发送的数据类别、附件、路由、中继可读性、有效授权和可能的下游委托。
• 一次 @数字人 创建绑定所选数字人 Publication、版本和 provider 的远程 Task。数字人离线 或拒绝时不得改发给同名数字人或其他 provider；网络中断后的终态遵守 FR-7。
• 数字人默认无权读取所有者的其他本地记忆。发布时，所有者可以勾选该数字人的 Agent 分区、 Global 分区、指定 Project 分区和指定 Automation 分区；首期不能开放短期的 Conversation 和 Run 分区。一次调用只在 Publication 冻结的允许分区中读取当前有效、已确认且敏感度 允许的记忆。
• 记忆检索和上下文组装始终在 Provider 本地完成。ShareServer 只保存 Publication 的分区 种类、经过验证的本地关联 ID 摘要和是否使用专属记忆等策略元数据；原始记忆、分区内容、 来源正文和检索结果不上传 ShareServer，也不向调用者展示。
• 数字人输出可能受到其 Agent 记忆影响，因此发布页和调用确认必须显示“使用数字人专属记忆” 这一事实及允许的数据敏感度。Restricted 记忆不得用于远端调用；暂停或撤销数字人后停止 新调用，但保留历史任务和有界审计。
• Provider 在执行边界重新验证 Publication、Grant、输入 schema、数据类别、大小、期限和 本地 Agent 记忆权限。ShareServer 的允许决定不能扩大数字人所在设备的本地权限。
• 所有者可以暂停、恢复、更新或撤销自己的数字人。handle 或能力、数据、工具、委托发生 变化，或新增可读记忆分区时，旧批准失效并重新进入审批；移除可读分区可以立即收紧而不 等待新批准，普通文案修改不得改变既有权限。
• 审计默认只记录调用方、数字人、Publication、provider、数据类别、路由、授权、状态、耗时 和大小，不保存消息正文、附件内容、模型输出或记忆内容。

FR-14 Office 编辑服务

• Office 编辑是可选服务能力。未配置或健康检查失败时，ShareServer 仍可运行其他控制面功能， 并向 Desktop 返回明确不可用原因。
• 首选 ONLYOFFICE Docs Developer Edition，目标支持 DOCX、XLSX 和 PPTX。正式采用前必须完成 实时编辑接口验证，并确认许可证、桌面集成、并发连接、白标、私有部署和安全支持范围与报价。 Automation API 为 Developer 版额外收费能力，不能从社区版容器部署成功推定已获授权； 插件替代路径需单独验证功能与授权条件。
• 推荐部署方在服务器 Docker 中独立运行 Document Server，普通 Desktop 用户无需安装 Docker。 启用前验证文件下载、保存回调及中文字体；工作副本进入所选服务处理范围，集中部署不提供完全离线编辑。
• Desktop 的右侧文档页签与 Agent 操作同一编辑会话，支持读取未保存的人工修改、原位应用、 修改定位与高亮、撤销重做；源文件回写仍以检查点为依据。客户端需求与选型验证以 Office PRD 的 FR-6、 FR-13、FR-14 为准。
• Desktop 使用设备身份创建 DocumentEditSession，上传经过大小、格式和 SHA-256 声明的工作 副本。ShareServer 不接收本机或 SSH 绝对路径，也不允许文件名决定对象存储路径。
• ShareServer 为编辑器签发一次性启动授权，为 ONLYOFFICE 签发独立的短期文件和 callback 凭据；设备、编辑器和 callback audience 不能互换。
• ONLYOFFICE 保存先形成不可变 DocumentCheckpoint。ShareServer 只宣称检查点可用，不宣称 Desktop 本地或 SSH 源文件已经回写成功。
• 服务端保存组织、主体、会话、文档类型、大小、策略、编辑器版本、checkpoint 和清理审计； 默认不保存文档正文、选区正文、提示词或模型输出到普通日志和审计表。
• 管理员可以配置允许格式、文件大小、并发、会话期限、checkpoint 保留、只读策略和 AI 编辑 开关。策略变化可以阻止新操作，不改写已经下载到 Desktop 的源文件。
• ShareServer 托管固定版本的 GoodBuddy ONLYOFFICE 插件，用于有界选区、revision、编辑事务和 非正文状态事件。插件不能调用任意 ShareServer 管理 API、Electron IPC、宏或脚本执行入口。
• Ask 只能取得 AI 修改建议；只有 Desktop 确认的 Execute 请求可以取得绑定单会话、revision 和选区的短期编辑授权。
• 会话关闭、撤销或到期后停止新读取、保存和 AI 操作，并按组织保留策略清理工作副本、 checkpoint、Cookie 和对象令牌。

5. 产品验收

• 新实例可完成初始化、登录、创建组织、邀请成员和注册真实桌面设备。
• 两个不同组织不能通过 API、搜索、计数、错误或审计结果读取对方数据。
• 设备只有发布能力后才进入获准目录，撤销后不能接收新任务。
• 调用授权能同时处理用户、设备、组织、提供者、数据和联邦限制。
• 任务中继关闭时控制面仍可运行；中继开启时可取消并形成准确终态。
• 权限扩大的包更新不能自动部署。
• 两个独立 ShareServer 能建立、使用、暂停和撤销双边联邦。
• 成员可以显式发布一个数字人，获准的同组织成员能从选择器插入 @handle 并完成一次有界 调用；未获准成员不能通过目录、搜索、补全或直接 API 枚举和调用该数字人。
• 暂停或撤销数字人后不能创建新调用，已完成任务与有界审计仍可追溯到原 Publication 和 provider。
• 数字人调用可以使用所有者在发布时勾选的 Agent、Global、指定 Project 或指定 Automation 分区，但不能开放 Conversation 和 Run；ShareServer 和调用者不能读取原始记忆、未选择的 本地分区或记忆来源正文。
• 启用 Office 服务后，Windows、macOS 和 Linux Desktop 可从同一 ShareServer 分别打开、编辑 和保存 DOCX、XLSX、PPTX；多个会话不会串文件、选区、checkpoint 或权限。
• 文件 URL、callback token 和编辑器启动授权过期或撤销后不可重用；保存失败、源文件冲突或 网络结果未知不会被 ShareServer 记录为源文件已保存。
• Office 服务停用或故障不影响身份、设备、能力目录和其他任务控制面。
• Agent 实时编辑按 Office 用户故事 的 US-C1 至 US-C7 验证；集中部署和选型按 US-F1、US-F2 验证，不以部署成功代替产品验收。
• 备份恢复后组织、策略、发布和审计身份保持一致，短期连接和令牌不恢复。