# ShareServer 功能逻辑设计 ## 文档信息 | 项目 | 内容 | | --- | --- | | 状态 | 设计中 | | 版本 | 0.6 | | 日期 | 2026-10-01 | | 关联 PRD | [ShareServer PRD](./prd.md) | | 共享规则 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) | ## 本地目录首期状态规则 本地目录实现设备与发布元数据,使用[技术设计第 4.1 节](./technical-design.md#41-本地共享目录契约已实现) 的独立接口;本地模型网关规则见第 6.1 节。下文组织身份、Grant、任务和文档归属规则属于目标设计。 Office 私有部署第一阶段的限定状态规则见第 8.2 节,不声称具备 INV-1 的组织隔离或 INV-12 的多类凭据体系。 - 注册相同设备 ID 更新名称、平台及版本,保留首次注册时间;相同内容重试不改变时间。 - 注册不自动发布内容,也不表示设备在线。设备列表目前没有心跳或离线判断。 - 发布必须关联已有设备。新 ID 创建 `published` 条目;相同 ID、相同内容返回已有记录, 相同 ID、不同内容报冲突,不覆盖原记录。 - 撤销将状态变为 `revoked` 并保留目录记录。重复撤销不改变结果;重试旧发布请求不恢复已撤销记录。 - 能力与知识按 `kind` 区分。知识的搜索、原文、下载标志分别存储,不相互推导; `server` 来源也只是发布者声明,不表示文件已经上传或同步。 - 当前没有用户主体或组织所有权,因此真实目录按设备查看。组织示例已移除, 不把设备名称推定为用户身份。 ## 1. 核心不变量 ### INV-1 组织隔离先于角色 任何查询和变更先绑定 organization,再计算角色。系统管理员的跨组织操作使用独立系统管理 入口并形成审计,不能依靠省略 organization 条件获得全局数据。 ### INV-2 注册不等于发布 设备注册只建立身份和连接资格。没有有效 Publication 时,目录中没有该设备能力。 ### INV-3 目录不等于授权 看到能力不能推导可调用或可下载。创建任务和下载包时重新计算当前授权。 ### INV-4 服务端授权不能扩大端点授权 ShareServer 的 `allow` 只是签发任务资格。Provider 和调用方仍执行各自本地策略;任一端拒绝 即终止动作。 ### INV-5 策略拒绝优先 同一动作命中多个规则时使用 `deny > require_approval > allow`。没有匹配 allow 时默认 deny。 ### INV-6 联邦为双边交集 单方创建或接受的关系不生效。双方 active 且两端发布、Grant 和数据策略均允许时才能跨组织 创建任务。 ### INV-7 任务提供者不可改写 ShareServer 只路由调用方冻结的 provider,不在离线、繁忙或失败时替换节点。 ### INV-8 不恢复短期权威 备份恢复不恢复 Web 会话、设备 socket、一次性挑战、审批 nonce 或任务数据通道。终端必须 重新连接并证明身份。 ### INV-9 初始化入口一次性关闭 初始化只在实例尚无系统管理员时可用。首个系统管理员创建成功后,后续请求即使持有旧的 一次性引导材料也不能再次进入初始化流程。 ### INV-10 数字人发布不等于记忆公开 发布数字人只建立一个有界 Agent Publication。它默认不取得所有者任何本地记忆;所有者可以 在发布时勾选 Agent、Global、指定 Project 和指定 Automation 分区,不能开放 Conversation 和 Run 分区。ShareServer 和调用者只能看到允许分区种类与“本次调用会使用本地记忆”的政策 事实,不能读取原始条目、分区内容、来源正文或检索结果。新增可读分区按权限扩大重新审批, 移除分区可以立即收紧。 以上限制针对本地记忆授权。用户另行选定并发布的知识、监督回顾副本按 FR-18 计算内容授权, 不使底层记忆分区可浏览;回答使用与原文读取是不同动作。 ### INV-11 服务端检查点不等于源文件已保存 在显式的本地来源导入/回写模式中,ONLYOFFICE 保存只产生 ShareServer 权威的 `DocumentCheckpoint`。只有 Desktop 或远程 GoodBuddy Agent 校验源文件基准并完成原子替换后,源文件才是已保存状态。ShareServer 不根据 callback 成功推断本机或 SSH 文件已经更新。 文档默认以 ShareServer 为主存储,日常操作在 GoodBuddy 中完成。服务端主存模式不要求本地 回写确认;主文档生命周期独立于编辑会话,不能因会话关闭或检查点清理而删除主文档。 个人创建者可删除自己的文档或确认转移所有权给组织。转移后原个人删除权立即失效,删除和 恢复按当前组织权限判断;恢复不改变归属。管理身份和归属元数据可见性不授予个人正文访问权。 ### INV-12 Office 凭据单用途 设备 API 凭据、编辑器一次性启动授权、ONLYOFFICE 文件令牌和 callback token 分别绑定不同 audience、单个文档会话和短期限。任何一种凭据都不能换取其他 API 权限。 ## 2. 主要状态 ### 2.1 成员 ```text invited -> active -> suspended -> active invited -> expired | revoked active/suspended -> removed ``` `suspended` 不能登录或创建新任务;历史归属保留。`removed` 不级联删除审计和已完成任务。 ### 2.2 注册设备 ```text pending -> active <-> offline pending -> expired | rejected active/offline -> revoked ``` 客户端心跳只决定 `active/offline`,不能清除 `revoked`。重新注册生成新设备 registration。 ### 2.3 Publication ```text draft -> pending_approval -> active draft/pending_approval -> rejected active <-> paused active/paused -> revoked ``` provider 离线不会把 Publication 变为 paused;目录同时展示“已发布”和“当前离线”两个事实。 ### 2.4 审批 ```text pending -> approved | rejected | cancelled | expired ``` 审批对象内容摘要、申请主体或策略版本变化后,原审批不能复用。approved 只产生其声明范围内 的 Grant 或一次性决定。 ### 2.5 Package Release ```text draft -> verifying -> available -> paused -> available verifying -> invalid available/paused -> revoked ``` 发布后的版本和字节不可变。修复内容必须使用新版本;revoked 不删除审计证据和对象摘要。 ### 2.6 FederationTrust ```text draft -> offered -> mutually_confirmed -> active offered -> rejected | expired active <-> paused 任意非终态 -> revoked ``` `mutually_confirmed` 只表示身份确认完成;双方策略同步成功后才进入 active。 ### 2.7 DocumentEditSession 以下包含上传阶段的流程描述本地来源模式;不将其作为服务端主文档的生命周期。 ```text creating -> uploading -> ready -> editing creating/uploading -> failed | cancelled | expired ready/editing <-> offline ready/editing/offline -> closing -> closed 任意非终态 -> revoked | expired ``` 编辑内容使用独立状态维度: ```text clean -> dirty -> saving -> checkpoint_available saving -> failed | outcome_unknown checkpoint_available -> dirty ``` `offline` 不删除已确认 checkpoint。`outcome_unknown` 必须通过对象摘要和 callback 幂等键查询 同一次保存,不能自动创建另一份 checkpoint。 ### 2.8 工作空间共享与资料同步 本地 Workspace 始终具有本地身份,共享关联记录目标组织和服务端身份。每个关联单独记录: | 维度 | 状态与含义 | | --- | --- | | 共享生命周期 | `local_only -> enable_pending -> shared -> revoke_pending -> revoked`;开启失败回到 local_only 并保留原因 | | 资料同步策略 | `on_demand` 或 `periodic`;暂停只暂停资料自动交换,不影响实时消息或撤销共享 | | 消息连接 | 实时订阅及断线补收独立运行,消息与处理状态不等待资料周期 | | 连接 | online / offline,与共享授权独立 | | 同步结果 | idle / syncing / partial / failed / conflict,附最近成功时间及未确认变更 | `revoked` 表示该共享关联终止,本地 Workspace 仍可使用。重新开启使用新关联。撤销请求结果 未知时保持 `revoke_pending` 并查询同一请求;权限被拒不能伪装为已撤销。已有共享关联被 服务端移除或组织停用时,由服务端状态收紧访问,本地的 shared 缓存不产生权威。 开启共享仅发布确认清单中的内容。新增成员可以访问当前被授予的空间历史,管理者添加前 必须确认该范围;不能通过添加成员突破来源授权。首期同一关联不可跨组织移动。 同步以逐项确认推进进度;冲突保留本地和远端版本,权限与撤销始终采用服务端当前权威。 发起关闭后本端停止普通上传,联网先提交关闭;服务端已确认的关闭阻止旧队列重放。 已经发送的历史不能通过暂停、删除本地队列或关闭共享改写为从未发送。 ### 2.9 消息交付与处理 消息交付:`local_pending -> submitting -> accepted | rejected`。local_pending 显示“待发送”。确认丢失时保留未确认状态, 按稳定消息身份重试或查询;不能先生成第二个身份。accepted 仅表示服务端接收,不表示成员 设备收到、已读或已执行。公开回复同样先经历交付确认。未确认 AI 草稿存入本人私有范围, 其正文不进入空间实时流、公开历史和普通成员的离线补收;只可向本人发送私有草稿就绪通知。 普通消息和提及只有交付状态;只有 accepted 且明确携带“请求处理”及处理人身份的消息进入处理流程: ```text 本人模式 / 要求本人确认 -> awaiting_human -> human_handling -> replied_by_human 分身先回复 -> ai_running -> replied_by_ai 分身起草 -> ai_running -> draft_ready -> replied_by_human_confirmed ai_running / draft_ready / replied_by_ai -> human_handling AI 不可用 / 失败 -> awaiting_human(保留原因) ``` 状态描述一次定向请求的当前处理事实。接手保留此前回复,不覆盖作者;本次回复完成后继续 讨论可创建关联回复或新请求。空间撤销、成员移除或资料授权失效可将未完成处理阻止在当前 状态并显示原因,不能标记为已完成。已发布事实保留,新的读取仍需有效授权。 开启尚未确认时也可 `enable_pending -> revoke_pending`。关闭请求绑定原开启操作身份,服务端 必须串行确定开启是否已生效:已生效则撤销同一关联,未生效则阻止该开启操作随后生效。 仅在确认不存在仍有效的关联后显示关闭完成。重连时此检查优先于普通上传。 成员范围扩大时检查既有共享正文、附件及上下文快照的来源授权。若新增受众不被允许,拒绝 该成员变更,保留原成员集合;管理者先补齐授权或移除不兼容共享内容,再提交变更。 资料定期模式在客户端运行且联网时按周期交换资料增量。显式提交的资料按需同步在重连后继续重试, 暂停资料自动同步不取消此类显式请求;未提交本地草稿不得随重连上传。 实时消息由服务端接受后通知在线成员;客户端按服务端进度补收消息、回复与状态事件,按稳定 身份及状态版本去重合并,旧事件不能回退处理状态。断线恢复可以重复传输事件,不得重新创建 处理任务。消息附带内容准备失败时保持待发送并显示原因,不先创建缺少上下文的处理请求。 ## 3. 授权计算顺序 1. 验证请求身份、会话 audience 和 organization。 2. 验证用户、设备、provider、Publication 和 FederationTrust 当前状态。 3. 校验能力或数字人版本、动作、输入 schema、数据类别、大小和委托链。 4. 收集调用方组织、提供方组织、Publication 和 Grant 规则。 5. 按拒绝优先合并,计算 `deny/require_approval/allow`。 6. 校验次数、并发、预算和有效期。 7. 返回决定、稳定原因和策略引用;需要批准时建立内容绑定申请。 8. 创建任务时再次计算,并把决定快照写入任务。 目录查询可以预计算“可能可用”,但不能替代第 1 至 8 步。 此顺序用于能力调用。空间消息先检查组织、空间、发送者、提及身份、处理人(如有)和附带内容的共享范围, 普通发言及提及无需 Publication;只有显式处理请求选择分身执行时再走上述能力授权。空间访问授权不能代替 Publication/Grant,本人草稿确认也不能绕过当前访问权限。 ## 4. 组织角色边界 | 动作 | 系统管理员 | 组织管理员 | 发布者 | 审批人 | 审计员 | 成员 | | --- | --- | --- | --- | --- | --- | --- | | 实例设置 | 是 | 否 | 否 | 否 | 只读有限项 | 否 | | 成员与组 | 紧急管理 | 是 | 否 | 否 | 只读 | 自己 | | 注册设备 | 只读/撤销 | 是 | 自己 | 否 | 只读 | 自己 | | 发布能力/包 | 否 | 是 | 授权范围 | 否 | 只读 | 否 | | 发布自己的数字人 | 否 | 是 | 授权范围 | 否 | 只读 | 自己 | | 编辑策略 | 否 | 是 | 否 | 否 | 只读 | 否 | | 处理审批 | 否 | 可配置 | 否 | 授权范围 | 只读 | 自己的申请 | | 联邦关系 | 实例级许可 | 是 | 否 | 可共同审批 | 只读 | 否 | | Office 服务配置 | 是 | 策略与会话管理 | 否 | 可配置 | 只读 | 使用获准服务 | | 审计导出 | 实例级 | 组织级 | 自己相关 | 自己相关 | 授权范围 | 自己相关 | 实际权限仍由策略计算,表格定义产品默认职责而非硬编码角色名称。 ## 5. 任务路由决策 | 条件 | 结果 | | --- | --- | | provider 在线且双方可直连 | 签发短期直连协商信息 | | 无法直连且双方策略允许中继 | 建立有界中继通道 | | 中继关闭或任一方禁止 | 创建失败,说明无可用路由 | | provider 离线 | 不排队到无限期,按能力配置有界等待或拒绝 | | provider 接受后连接中断 | 保留 task,等待同一 provider 恢复/查询 | | provider 终态未知且恢复期结束 | `outcome_unknown` | | 调用方取消 | 转发取消;provider 确认后终态 cancelled | 中继容量不足只产生排队或资源错误,不切换 provider,不改变是否允许中继。 ### 5.1 成员消息的处理决定 普通消息与提及不创建处理任务。按以下顺序决定一次已接收的显式处理请求的处理方式: 1. 校验当前空间、成员和附带内容权限。无权时阻止处理,不改投其他人。 2. “需要本人确认”直接进入 awaiting_human。 3. 使用服务端接受处理请求时的成员空间偏好版本;未配置时为本人处理。 4. 分身方式解析接收者明确绑定的 Publication/version/provider,并记录任务关联;不可用时转本人待处理。 5. 执行前和发布前重验权限及处理版本。普通偏好更新不改写在途任务,撤销或本人接手可以阻止后续发布。 消息身份、AI 执行身份和公开回复身份分别幂等。多个设备不能对同一待处理版本创建重复任务。 本人接手以服务端原子变更处理版本为生效点;其后旧版本 AI 结果只可作为不公开的结果保留, 不得自动发送。若 AI 回复先发布,则保留该回复,本人可在其后补充。 确认草稿绑定草稿版本、确认者和最终正文摘要。其他成员和普通审计不能读取未发送草稿, 政策审批产生的 Grant 不构成本人对该正文的确认。 确认操作原子消费待确认的处理版本。相同操作重试返回既有结果;不同设备对同一草稿提交不同 正文时仅首个成功确认生效,后续返回版本冲突并保留客户端编辑。本人接手也推进处理版本, 其后迟到的旧草稿确认不能另建回复绕过冲突。 ### 5.2 来源、受众与动作 共享知识区分服务器同步副本和远程设备取用。已就绪的服务器副本不因来源设备离线而失效, 但更新需等待设备连接;远程取用在设备离线时不可用。发布暂停或设备撤销仍阻止使用,不能 以已有副本绕过撤销。搜索、读取原文、下载分别判断权限;可用状态、共享对象和管理员元数据 可见性均不替代动作授权。当前共享中心仅展示真实目录声明,无真实内容请求。 可用内容为来源授权、当前入口受众、动作、空间权限、组织策略及 Provider 本地权限的交集。 个人外部入口与组织空间独立授权;同一分身身份复用不复制其所有来源权限。 | 回顾用于回答 | 回顾原文可读 | 行为 | | --- | --- | --- | | 否 | 否 | 不向该入口提供回顾 | | 是 | 否 | 分身可参考,访客不能取得原文 | | 否 | 是 | 访客可阅读,分身不得将其作为回答来源 | | 是 | 是 | 两种动作均需按各自授权检查 | 撤销影响新读取、检索和发布,不追溯删除已经发送的文字或已下载副本。同步内容快照不冻结 授权;发送后、执行前授权失效时,应阻止使用相应来源并说明原因,不能因为曾经发送就继续访问。 ## 6. 更新策略优先级 ```text 紧急撤销 > 组织强制固定版本/禁止版本 > 设备组发布通道 > 用户允许的版本范围 > 当前已安装版本 ``` 任何权限扩大都从自动路径转为 `require_approval`。降级只有在目标版本仍被签名目录允许且 策略明确指定时才提供,不自动视为故障回滚。 ### 6.1 本地模型网关 本节描述已实现的 [B1 网关](./backend-foundation-design.md#4-b1正常模型网关接入);完整验收尚未完成。 模型网关向其他服务真实转发,不托管模型。新存储无上游、映射和审计。别名全局唯一并绑定 一个上游与远端模型。客户端必须提供有效 Bearer 访问 Key;列表只返回 Key 授权、上游及映射 均启用、凭据可用的模型,无需认证的上游不要求凭据。“凭据已配置”仅表示保存了密文或有效 环境引用,不表示解密或连接已验证。 上游凭据按 `keep|replace|clear` 显式保留、替换或清除;空值不代表清除,无需认证不会自动删除 已有凭据。新秘密加密保存;主密钥缺失或错误时报告不可用,不覆盖旧密文。旧环境变量引用可 继续调用,显式替换后改为托管凭据;前缀导入界面及接口已移除。 Key 仅创建时返回原文,存储摘要;授权绑定模型记录 UUID,修改别名不改变范围。未知或撤销 Key 返回 401,未授权模型返回 403。重复撤销保持原撤销时间,撤销阻止新请求,不主动取消已开始 的流。管理与旧目录接口限制实际 socket 为直连回环,不能靠 Origin 或转发头建立管理身份。 发现模型真实访问上游列表,但不自动保存发现结果;失败仍可手工映射。用户选择或手动填写映射, 再通过本机管理测试入口显式测试。调用按配置将别名 换为远端模型,响应恢复别名,不允许请求覆盖上游地址或凭据,也不自动重试或切换上游。 调用终态为成功、失败或取消。JSON 响应通过格式检查后记录成功;SSE 必须收到 `[DONE]`,提前 结束记为失败。取消或超时中止上游请求,流已开始时的 HTTP 200 不等于最终成功。审计只记录 调用元数据,缺失用量保留未知;存储保留最新 200 条,不保存提示词、工具参数或响应正文。 配置和审计写盘成功后才更新内存,坏文件或写入失败报错,不清空已有记录。 本地预览已有 Key 级模型授权,尚无组织认证、组织隔离、用户组策略或配额。配置下发为占位, 没有发布、回退或设备确认;保存网关模型不会自动下发。接口和资源限制见技术设计第 4.2 节。 历史网关/配置演示记录保持原有证据范围,不能据此认定真实转发或交付已验证。 文档页显示待接入说明,已移除会话内存演示及模拟组织角色;文档归属与回收规则仍待服务端实现。 ## 7. 联邦可见性 联邦目录只导出对方明确允许的能力投影:组织显示名、能力、版本范围、数据政策和可用性摘要。 不导出内部设备名、成员清单、组结构、节点地址、内部策略全文或审计记录。跨组织请求使用 双方关联 ID,双方各自解析本地主体。 ## 8. 删除、撤销与保留 - 删除组织前必须停止新任务、撤销联邦和设备,并按保留策略归档审计;不提供无提示级联。 - 删除用户不删除其历史动作,审计显示不可变主体摘要。 - 撤销设备、Publication、Grant、Package 或联邦后立即阻止新令牌。 - 对象存储中的未完成任务正文按任务期限清理;审计元数据按组织保留策略清理。 - Office 会话关闭、撤销或到期后停止签发新启动、文件和 callback 令牌。工作副本与 checkpoint 按 Office 保留策略清理,不连带删除服务端主文档;法定保留只能保留匹配对象和审计,不能恢复会话权限。 - 法定保留只锁定匹配审计事件,不使被撤销身份重新可用。 ### 8.1 Office 保存与回写结果 下表的源文件确认与冲突项仅适用于本地来源导入/回写模式。 | 条件 | ShareServer 结果 | | --- | --- | | callback 通过验证且对象完整 | 原子发布新 checkpoint,通知 Desktop | | callback 重复且幂等键相同 | 返回已有 checkpoint,不创建新版本 | | callback 超时且对象结果未知 | `outcome_unknown`,查询确认后再转终态 | | Desktop 确认源文件已写回 | 记录 `source_commit_confirmed` 元数据 | | Desktop 报告源文件冲突 | 保留 checkpoint 至到期,记录 `source_conflict` | | 设备或组织权限撤销 | 拒绝新操作并关闭会话,不删除 Desktop 源文件 | ### 8.2 Office 私有部署第一阶段(待实现) 服务端主文档有稳定 ID 和单调递增的持久化 revision;编辑会话关联文档 ID、基准 revision、 编辑轮次及 ONLYOFFICE `document.key`。同一文档同一轮共同编辑复用 key,不按浏览器或每次打开 生成不同 key。活动轮次不接受另一份上传覆盖主文档;另传文件创建新文档。 - status `6` 表示编辑期间的 forcesave:持久化快照后更新已保存 revision,继续当前编辑轮次, 不更换 key,也不据此宣布后续人工修改已保存。 - status `2` 表示本轮编辑结束后的保存:持久化最终内容后结束该轮;等待最终保存时,新打开请求 等待或返回可重试状态,不能先开启一个会被旧回调覆盖的新轮次。下轮从最新 revision 生成新 key。 - 关闭浏览器不等于服务端保存完成;无修改结束按 status `4` 收束,status `3`/`7` 保存错误保留 最近成功版本并报告失败。status `4` 不增版,无内容变化时允许恢复原 key 的连接;需验证断网后 重连场景,不因一次断连即换 key。连接和其他通知不触发文件保存。 - 同文档保存串行处理,重复回调返回原结果;已结束轮次的迟到回调不得覆盖新轮次,迟到的 forcesave 不得覆盖最终保存。无法确定先后或版本冲突时保留原版本并报告待确认,不按到达时间盲目覆盖。 - 已持久化才显示“已保存到服务器”;写盘失败不确认成功,确认丢失后查询或重试同一次保存。 主文档不因会话结束而删除,首期不提供归属转移或组织权限承诺。 协议、幂等依据与文件提交方式由[技术设计第 10.1 节](./technical-design.md#101-私有部署第一阶段待实现) 定义。首期保存结果不涉及 Desktop/SSH 源文件回写。 ## 9. 需求追踪 | 需求 | 主要逻辑 | | --- | --- | | `FR-1` | `INV-1`、`INV-9` 和系统管理员角色边界 | | `FR-2` | 组织隔离不变量、成员状态和角色边界 | | `FR-3` | 注册不等于发布、设备状态和短期权威恢复规则 | | `FR-4` | 注册、Publication、目录与授权不变量 | | `FR-5` | 拒绝优先不变量和授权计算顺序 | | `FR-6` | 审批状态、内容绑定和授权重算 | | `FR-7` | provider 冻结不变量和任务路由决策 | | `FR-8` | Package Release 状态和更新策略优先级 | | `FR-9` | 联邦双边交集、FederationTrust 状态和联邦可见性 | | `FR-10` | 组织隔离、删除撤销与保留规则 | | `FR-11` | 组织角色边界及各对象状态;展示行为由 UI 设计定义 | | `FR-12` | 短期权威恢复规则和逻辑完整性;部署结构由技术设计定义 | | `FR-13` | 注册、Publication、目录与授权不变量,provider 冻结及 `INV-10` | | `FR-14` | `INV-11`、`INV-12`、DocumentEditSession、Office 保存与保留规则;私有部署第一阶段见 8.2 | | `FR-15` | 2.8 工作空间共享状态、组织与空间成员边界 | | `FR-16` | 2.8 资料同步与消息连接分离;2.9 交付确认、实时更新与补收 | | `FR-17` | 2.9 普通消息与处理请求分离;5.1 处理优先级与接手竞争 | | `FR-18` | INV-10、5.2 来源、受众与动作交集 | ## 10. 逻辑完整性 本设计覆盖实例、组织、成员、设备、能力与数字人发布、授权、审批、任务、更新、联邦、Office 编辑、撤销和恢复。实现前仍需确定首个 OIDC 提供者矩阵、默认审计保留期、部署规模目标、中继 带宽上限、Office 文件上限和 checkpoint 保留期;这些部署参数应可配置,不改变拒绝优先、双边 联邦、provider 冻结、Office 凭据单用途和源文件权威规则。