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

docs: design device sharing network

Browse Source
This commit is contained in:
mesalogo
2026-09-03 16:34:28 +08:00
parent 468cf0483f
commit fba5e1ad30
17 changed files with 2124 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/device-sharing/README.md
+28
View File
@@ -0,0 +1,28 @@
# 设备发现与共享
本功能是 GoodBuddy 桌面端管理附近设备、本机共享和 ShareServer 连接的唯一入口。默认连接
方式是局域网；网关由用户额外添加。功能不包含 ShareServer 的组织管理 Web 界面。
## 文档导航
| 文档 | 权威职责 |
| --- | --- |
| [PRD](./prd.md) | 用户问题、范围、功能需求和产品验收 |
| [功能逻辑](./logic-design.md) | 不变量、状态、授权优先级和失败结果 |
| [UI 设计](./ui-design.md) | 设置入口、四个页签、配对与调用交互 |
| [技术设计](./technical-design.md) | Desktop 进程边界、持久化、IPC、网络和验证 |
| [共享网络总体设计](../../architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威 |
当前没有单独的 User Stories：正常、失败、撤销、权限和兼容场景已直接进入 PRD 验收与逻辑
决策表。功能尚未实施，因此不创建 `progress.md`。
## 术语
- **附近设备**：同一局域网内主动广播 GoodBuddy 共享服务的设备。
- **已配对设备**：双方确认设备指纹后建立点对点信任的设备。
- **网关连接**：本机与某个 ShareServer 中特定组织身份的连接。
- **本机共享**：由本机作为提供者发布给 Peer 或组织的能力。
- **远端能力**：由其他设备或组织提供、本机可以查看或调用的能力。
SSH 远程项目是用户明确配置 Host 后操作远端工作区的独立功能，不自动进入设备发现与共享，
详见[远程主机与远程执行](../remote-host/README.md)。
docs/features/device-sharing/logic-design.md
+202
View File
@@ -0,0 +1,202 @@
# 设备发现与共享功能逻辑设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
| 共享规则 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
本文负责桌面端状态、不变量和决策规则，不重复跨端协议定义。
## 1. 核心不变量
### INV-1 连接方式独立
局域网、每个 GatewayConnection 和本机能力互不拥有生命周期。启停、失败或删除其中一项不
改写其他项。
### INV-2 三项操作独立
`discovering`、`advertising` 和 `publishing` 是三个独立状态。任何组合均合法，界面不得用
一个“设备共享”总开关代替。
### INV-3 默认不共享
新安装没有 Publication。允许被发现只公开配对入口，不公开能力清单。
### INV-4 身份先于能力
未配对局域网设备不能取得详细能力；未注册网关设备不能取得组织目录。缓存不能绕过当前
身份和撤销状态继续调用。
### INV-5 提供者在调用前冻结
自动选择只生成候选决定。用户确认或无需确认的请求创建后，provider、route 和授权快照不可
改变。失败后切换提供者属于新的请求。
### INV-6 最小发送上下文
只发送能力 schema 要求且用户当前选择的输入。当前 Conversation、Project 和 Workspace 不
因能力被调用而整体成为输入。
### INV-7 结果未知不重放
已经被提供者接受但终态无法确认的副作用任务进入 `outcome_unknown`。重新执行必须由用户
发起，并显示可能重复产生副作用。
### INV-8 撤销只影响未来授权
撤销配对、网关连接、Grant 或 Publication 后不再创建新任务。历史记录保留；活动任务按
冻结策略取消或完成，不能追改为从未发生。
### INV-9 设置导航无业务副作用
四个 PageTabs 只切换视图，不自动开始广播、连接网关、发布能力或保存草稿。
## 2. 状态维度
### 2.1 局域网服务
```text
discover: off | starting | active | unavailable | error
advertise: off | starting | active | unavailable | error
```
操作系统或网络不支持时使用 `unavailable`；运行失败使用 `error`。两者分别重试。
### 2.2 附近设备
```text
visible_unpaired -> pairing -> paired_online
pairing -> rejected | expired | failed
paired_online <-> paired_offline
paired_* -> identity_changed | revoked
```
`identity_changed` 不自动接受新证书。用户必须撤销旧配对后重新配对。
### 2.3 网关连接
```text
draft -> authenticating -> connecting -> connected
authenticating -> cancelled | auth_failed
connecting/connected -> offline | auth_expired | policy_blocked
offline -> connecting
任意已保存状态 -> removed
```
`offline` 保留连接和缓存目录供只读说明，但不能创建新任务；`auth_expired` 要求重新登录；
`policy_blocked` 显示服务端给出的稳定原因和管理员联系路径。
### 2.4 本机发布
```text
not_published -> draft -> validating -> published
validating -> invalid
published -> paused -> published
published/paused -> removed
```
草稿和无效发布不对外可见。能力实现消失时发布进入 `paused`，不删除用户配置。
### 2.5 远端任务
采用共享架构定义的状态。本机 UI 归并为：
| 协议状态 | 用户状态 |
| --- | --- |
| `created/awaiting_approval` | 等待确认 |
| `queued/connecting` | 正在连接 |
| `running` | 正在执行 |
| `completed` | 已完成 |
| `failed/rejected/expired` | 未完成，并显示具体原因 |
| `cancelled` | 已取消 |
| `outcome_unknown` | 结果未知 |
## 3. 默认状态
| 设置 | 全新安装默认值 |
| --- | --- |
| 发现附近设备 | 开启 |
| 允许其他设备发现本机 | 关闭 |
| 自动接受配对 | 不支持 |
| 本机共享能力 | 无 |
| 网关连接 | 无 |
| 永久调用 Grant | 无 |
主动发现默认开启只浏览 GoodBuddy 主动广播，不执行端口扫描。操作系统权限尚未授予时，首次
进入页面再触发对应系统说明和授权，不在应用启动时抢占焦点。
## 4. 提供者选择
自动选择按以下顺序比较满足当前输入和授权的在线候选：
1. 本机提供者。
2. 已配对局域网提供者。
3. 当前用户所属组织提供者。
4. 联邦外部组织提供者。
5. 同级中按服务端预计排队时间和稳定能力版本排序。
自动选择不跨越 `require_approval` 与 `allow`：若排名第一的候选需要批准，界面显示该候选及
批准要求，不静默换成权限更宽但来源更远的候选。用户可以明确选择其他候选。
## 5. 调用决策表
| 身份与能力状态 | 授权结果 | 行为 |
| --- | --- | --- |
| 身份有效、输入匹配 | allow | 创建任务并展示执行位置 |
| 身份有效、输入匹配 | require_approval | 显示完整确认后创建 |
| 身份有效 | deny | 不创建任务，显示策略原因 |
| 提供者离线 | 任意 | 不创建任务，允许重新选提供者 |
| 清单过期或版本变化 | 任意 | 刷新后重新计算，不沿用确认 |
| 文件超过能力或策略上限 | 任意 | 就地拒绝并显示上限 |
| 委托链与确认不一致 | 任意 | 拒绝并要求以新执行链重新确认 |
## 6. 撤销与删除
| 操作 | 删除内容 | 保留内容 |
| --- | --- | --- |
| 撤销 Peer | 配对凭据、该 Peer 的本地 Grant 和目录缓存 | 活动记录、已安装包 |
| 移除网关 | 本机设备凭据、连接配置、目录缓存 | 服务端账号、活动记录、已安装包 |
| 停止发布 | 对外 Publication | 能力实现、发布草稿、历史任务 |
| 删除发布 | Publication 和本地发布设置 | 能力实现、历史任务 |
| 删除已安装包 | GoodBuddy-owned 安装内容和分配 | 来源审计与任务历史 |
存在活动任务时，撤销操作明确询问是否同时发送取消；无论取消是否确认，立即禁止新任务。
## 7. 失败与恢复
- mDNS 不可用：显示手动地址配对，不关闭已配对直连。
- 广播失败：保留用户开关意图，状态为错误并允许重试。
- 网关离线：指数退避重连，用户手动“重新连接”可立即尝试一次。
- 登录取消：不保存连接。
- 目录刷新失败：保留最后缓存并标记时间，不允许基于过期授权启动新任务。
- 调用前连接失败：任务失败，可安全重新执行。
- 提供者接受后断线：恢复查询同一任务；仍无法确认时进入结果未知。
- 下载或签名失败：删除候选暂存，保留现有安装，不切换来源。
## 8. 需求追踪
| 需求 | 主要逻辑 |
| --- | --- |
| `FR-1`、`FR-2` | `INV-1`、`INV-2`、`INV-9` 和默认状态 |
| `FR-3`、`FR-4` | 身份不变量和附近设备状态机 |
| `FR-5` | 连接独立不变量、网关连接状态和删除规则 |
| `FR-6` | provider 冻结不变量和提供者选择顺序 |
| `FR-7` | 默认不共享不变量、本机发布状态和撤销规则 |
| `FR-8` | 最小发送上下文和调用决策表 |
| `FR-9` | 远端任务状态、结果未知不重放和失败恢复 |
| `FR-10` | 撤销与删除、下载或签名失败规则；包协议由共享架构定义 |
| `FR-11` | 撤销后历史保留和任务状态；展示行为由 UI 设计定义 |
| `FR-12`、`FR-13` | 独立状态维度和失败恢复 |
| `FR-14` | 身份先于能力、最小发送上下文和调用决策表 |
## 9. 逻辑完整性
本设计已覆盖发现、配对、连接、发布、调用、取消、撤销、离线、身份变化、权限变化和能力
更新。实现前仍需在共享协议中固定受限 JSON Schema 子集、端到端中继加密套件和桌面端可
注册为共享能力的首批实际类型；这些是技术选择，不改变本文状态和产品规则。
docs/features/device-sharing/prd.md
+160
View File
@@ -0,0 +1,160 @@
# 设备发现与共享 PRD
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 适用产品 | GoodBuddy Desktop |
| 关联架构 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
| 关联文档 | [功能逻辑](./logic-design.md)、[UI 设计](./ui-design.md)、[技术设计](./technical-design.md) |
## 1. 背景
GoodBuddy 的能力当前主要在本机执行，SSH 远程项目则要求用户预先配置具体 Host。个人和组织
需要在不复制完整环境的情况下使用附近工作站、其他成员设备或组织节点上的模型、知识、硬件
和工具，也需要在经过确认后把可分发能力安装到本机。
该能力不能以“扫描局域网机器”的方式实现。产品只发现主动开放 GoodBuddy 服务的设备，
配对后才查看详细能力，授权后才发送数据或执行任务。
## 2. 产品目标
1. 用户无需配置服务器即可发现并配对同一局域网中的 GoodBuddy 设备。
2. 用户可以额外连接一个或多个 ShareServer，使用组织或合作组织提供的能力。
3. 用户能够逐项决定本机向哪些 Peer、用户组或组织开放什么能力。
4. 远程调用前、中、后都能确认提供者、执行位置、数据去向和授权依据。
5. 局域网、各网关连接和本机能力彼此独立，单点故障不阻塞其他来源。
6. 可分发能力必须在明确校验和批准后安装，不迁移对方凭据或机器配置。
## 3. 功能范围
### 3.1 包含
- 设置中的“设备发现与共享”一级分类。
- 局域网主动发现、选择、双端配对、重命名和撤销。
- 本机被发现开关和配对请求处理。
- ShareServer 添加、登录、连接状态、组织身份和移除。
- 远端能力目录、提供者选择、调用确认、进度、取消和结果。
- 本机能力逐项发布、范围、允许动作和确认策略。
- 签名能力包查看、下载、校验、安装和权限变化确认。
- 局域网与网关活动记录。
### 3.2 不包含
- 扫描未主动广播 GoodBuddy 服务的机器或端口。
- 在桌面端管理 ShareServer 成员、组织策略、联邦或服务器运维。
- 自动公开本机 Skill、MCP、知识库、模型、文件或 SSH Host。
- 同步 API Key、Cookie、系统环境变量、绝对路径或登录状态。
- 把现有 SSH Host 自动转换为共享设备。
- 无界远程 Shell、桌面控制或任意文件浏览接口。
- 在网关断开时把组织授权自动降级为局域网授权。
## 4. 功能需求
### FR-1 设置入口
- 设置中心增加“设备发现与共享”一级分类。
- 页面提供“局域网”“网关”“本机共享”“活动记录”四个同级页签。
- 普通入口默认打开“局域网”；定向入口可打开指定页签。
### FR-2 独立开关
- “发现附近设备”和“允许其他设备发现本机”使用两个独立 Switch。
- 任一开关变化不撤销既有配对、不改变网关连接、不开放能力。
- 新安装默认允许主动发现；默认不允许本机被发现，默认无共享能力。
### FR-3 附近设备
- 只展示当前收到有效主动广播的 GoodBuddy 设备。
- 未配对设备只展示配对所需的有限信息，不展示能力和资产详情。
- 列表区分附近未配对、已配对在线、已配对离线和身份变化。
- 用户可手动刷新，但持续发现不得因刷新造成列表闪烁或重复项。
### FR-4 双端配对
- 双方显示相同验证码、设备名称、系统类型和证书指纹。
- 只有双方在时限内确认才建立配对。
- 任一端拒绝、超时、身份变化或连接中断均不保存半配对关系。
- 任一端可以撤销；撤销不删除历史活动记录。
### FR-5 网关连接
- 用户可输入 HTTPS ShareServer 地址或打开受支持的邀请链接。
- 登录在系统浏览器中完成，设备凭据回到 Main 的安全存储。
- 连接条目显示服务名、组织、当前成员身份、状态和最近策略同步时间。
- 同一设备可连接多个网关；移除连接只删除本机凭据和缓存，不删除服务端账号。
### FR-6 能力目录
- 已配对 Peer 和已连接网关分别返回当前身份获准查看的能力。
- 同一能力有多个提供者时合并展示，并允许“自动选择”或明确选择提供者。
- 自动选择仅比较满足授权和输入要求的在线候选，依次选择本机、已配对局域网 Peer、
当前用户所属组织和联邦外部组织；同级候选再按预计等待时间和稳定能力版本排序。
- 选择结果必须在执行前冻结并展示，不能执行中静默更换提供者。
### FR-7 本机共享
- 只有显式注册为可共享的能力才能出现在本机共享列表。
- 每项能力分别设置目标范围、`discover/inspect/invoke/download` 动作、输入类型、大小、
并发、有效期和是否逐次确认。
- 关闭能力或目标范围后停止接受新任务，不伪装为删除能力本身。
- 知识库原文、工作区写入、进程执行和硬件控制需要独立的明确能力声明。
### FR-8 调用确认
- 首次或策略要求时，确认界面显示提供者、执行位置、接收方、输入内容类别、文件名和大小、
路由、中继可读性及下游委托。
- 用户可取消、仅本次允许，或在组织策略允许时按当前范围保存授权。
- 调用上下文不隐式包含其他会话消息、整个工作区或未选择的知识库内容。
### FR-9 执行状态
- 会话或任务活动持续显示远端能力名称、来源、状态、发送字节和停止入口。
- 支持排队、连接、执行、完成、失败、取消、过期和结果未知。
- 网络中断且副作用结果无法确认时显示“结果未知”，不自动重试。
### FR-10 能力包
- 展示来源、版本、发布者、平台、大小、签名、权限和依赖。
- 下载和安装经过共享架构规定的校验流程。
- 新版本扩大权限时必须重新批准。
- 安装到本机后按现有 Skill/MCP/Runtime 分配规则启用，不因来自可信组织自动取得全部 Runtime。
### FR-11 活动记录
- 统一记录本机发出、远端发入、局域网、网关和跨组织活动。
- 支持按方向、来源、能力、结果和时间筛选。
- 详情显示授权依据、执行链、数据类别、大小、版本和终态，不默认保存正文。
### FR-12 错误隔离
- 局域网发现失败不影响网关和本机能力。
- 一个网关认证或连接失败不影响其他网关。
- 一个提供者离线时不自动改发给另一个提供者；用户重新执行时再选择。
- 页面保留可修复配置和准确错误，不以空状态代替失败状态。
### FR-13 平台与网络
- 支持 Windows、macOS、Linux 的当前桌面目标架构。
- mDNS 被网络阻断时允许通过已知局域网地址发起配对，但仍执行相同身份确认。
- 所有公网 ShareServer 使用 HTTPS；不提供“忽略证书错误”。
### FR-14 与现有能力的边界
- 远端调用不能扩大 Ask/Execute、Workspace、MCP、Skill 和知识库现有权限。
- 本机提供任务时使用能力声明对应的 Runtime 边界。
- SSH 远程项目、本机工具环境和模型配置默认不向 Peer 或网关传播。
## 5. 产品验收
- 两台新设备能完成发现、双端配对、授权、调用、取消和撤销。
- 三个概念“主动发现、允许被发现、开放能力”在状态和界面上互不混淆。
- 不配置网关时局域网工作完整；任一网关故障不阻塞其他来源。
- 未配对或未授权主体无法查看详细能力。
- 远端调用前能准确列出实际发送的数据，执行中和历史中可追溯提供者。
- 结果未知不会被显示为失败后自动重试或成功。
- 权限扩大的能力更新不会沿用旧授权静默安装。
- 中英文、键盘、焦点、窄窗口和深浅主题符合统一设计系统。
docs/features/device-sharing/technical-design.md
+213
View File
@@ -0,0 +1,213 @@
# 设备发现与共享技术设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
| 共享协议 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
## 1. 进程边界
```text
Renderer
-> 窄 Preload API
Main
-> DeviceSharingService
-> LanDiscoveryService
-> PeerPairingService
-> GatewayConnectionService
-> CapabilityCatalogService
-> CapabilityPublicationService
-> RemoteTaskService
-> PackageAcquisitionService
-> SharingAuditStore
-> 既有 Capability / Runtime / Skill / MCP 服务
```
Renderer 只取得脱敏快照和调用显式动作。设备私钥、Peer 证书、网关凭据、网络 socket、原始
任务令牌、任意文件读取和包缓存路径只存在于 Main。
## 2. 模块职责
| 模块 | 职责 |
| --- | --- |
| `LanDiscoveryService` | mDNS browse/advertise、手动地址握手、接口变化 |
| `PeerPairingService` | 临时握手、验证码、双端确认、配对凭据与撤销 |
| `GatewayConnectionService` | 浏览器登录、设备注册、WebSocket、重连和策略同步 |
| `CapabilityCatalogService` | 合并本机、Peer 和网关目录，保留来源身份 |
| `CapabilityPublicationService` | 校验本机可共享能力并向目标范围发布 |
| `RemoteTaskService` | 授权、确认、provider 冻结、传输、取消和终态 |
| `PackageAcquisitionService` | 固定来源下载、校验、安装协调和权限差异 |
| `SharingAuditStore` | 本机有界审计查询、筛选和清理 |
目录合并只生成 UI 视图，不能把不同 provider 的授权、版本和执行位置压成一个身份。
## 3. 共享契约
实现前建立独立 `packages/share-protocol`。Desktop 只从该包导入 Zod schema 和 TypeScript
类型。协议输入在网络边界和 IPC 边界分别验证，不能因已经过网络校验而跳过 Renderer 输入
校验。
建议导出：
```text
DeviceSummary
PairingChallenge
GatewayDescriptor
CapabilityManifest
Publication
GrantConstraint
AuthorizationDecision
RemoteTaskSnapshot
RemoteTaskEvent
PackageDescriptor
AuditEventSummary
ProtocolError
```
错误只向 Renderer 返回稳定 code、可本地化参数和可恢复动作，不转发远端堆栈、响应正文或
内部地址。
## 4. 持久化
建议在现有 Desktop SQLite 中增加：
```text
device_identity_metadata
peer_pairings
gateway_connections
capability_publications
local_grants
remote_tasks
sharing_audit_events
installed_shared_packages
```
- 私钥和 refresh credential 存系统安全存储；SQLite 只存引用和脱敏元数据。
- 附近广播、在线状态、配对验证码、短期任务令牌和目录候选只存在于内存。
- 网关能力目录可有界缓存，用于离线说明，不作为离线调用授权。
- 审计正文不落库，字段和保留上限在实现前固定。
- 数据库迁移只覆盖已发布 schema；未发布设计不预建兼容读取器。
## 5. 局域网网络实现
- 使用系统支持的 mDNS/DNS-SD 库 browse `_goodbuddy-share._tcp.local`。
- 广播绑定用户允许的网络接口；接口切换时重建监听，不保留旧地址为身份。
- 服务端口由 Main 持有，使用设备证书建立 TLS。
- 未配对握手仅暴露配对所需字段，并限制并发、频率、消息大小和有效时间。
- 手动地址只替代发现，不替代证书指纹与双端确认。
- 停止广播时关闭未完成配对监听；已配对活动连接按任务生命周期处理。
## 6. 网关连接
1. Main 校验 HTTPS URL，并取得服务公开描述。
2. 生成带 PKCE、随机 state 和设备挑战的系统浏览器登录请求。
3. 本机 loopback 或已注册应用链接只接收一次性回调 code。
4. Main 交换设备凭据，展示组织身份，用户确认后持久化。
5. Main 建立带设备身份的 WebSocket 出站连接。
6. 心跳更新在线状态；断线按有界指数退避重连。
服务器返回的跳转 URL 必须符合已取得服务描述和 HTTPS 限制。Renderer 不能提交认证头、设备
证书、WebSocket URL 或任意回调地址。
## 7. 本机能力适配
不是所有现有 Capability 都自动可共享。每种可共享类型需要显式 adapter：
```ts
interface ShareableCapabilityAdapter {
describe(): CapabilityManifest
validatePublication(input: PublicationDraft): ValidationResult
invoke(input: unknown, context: ProviderTaskContext): AsyncIterable<TaskEvent>
cancel(taskId: string): Promise<CancelResult>
}
```
adapter 负责把共享输入映射到既有生产服务，并保留原权限边界。首批类型在实现前根据真实
产品需求确定；未有 adapter 的 Skill、MCP、知识库和 Runtime 不出现在共享列表。
## 8. 远端调用生命周期
```text
Renderer 选择能力和输入
-> Main 解析候选并取得当前授权
-> 必要时返回确认描述
-> 用户批准
-> Main 冻结 task/provider/route/policy
-> 建立数据通道并流式发送
-> Provider 再校验并接受
-> Main 转发有界进度和结果
-> 终态与审计事务保存
```
每次任务使用稳定 `taskId` 和 attempt ID。Provider 未接受前的连接失败可以明确失败；已接受
后的断线先查询同一任务，不新建 attempt。无法恢复权威终态时保存 `outcome_unknown`。
附件从 Main 已授权的用户选择结果读取，按声明大小流式发送，不把任意本机路径交给远端。
接收成果先写 GoodBuddy-owned 暂存并校验，再通过现有 Artifact 边界进入产品。
## 9. IPC
Preload 只暴露按产品动作命名的方法，例如：
```text
sharing.getSnapshot
sharing.updateLanSettings
sharing.startPairing / confirmPairing / cancelPairing
sharing.revokePeer
sharing.addGateway / completeGatewayLogin / removeGateway
sharing.listCapabilities
sharing.savePublication / pausePublication / deletePublication
sharing.prepareInvocation / confirmInvocation / cancelTask
sharing.listAuditEvents / getAuditEvent
```
所有变更方法校验 trusted sender、严格 schema、对象当前 revision 和归属关系。不得暴露通用
HTTP、WebSocket、mDNS、证书、文件传输或数据库查询 IPC。
## 10. 生命周期与资源边界
- 应用启动按保存设置启动主动发现；不因保存了网关而阻塞窗口创建。
- 广播只有在用户开启后启动。
- 网关连接在后台恢复，认证过期只影响对应连接。
- 应用退出停止接收新任务，取消未接受任务，并有界通知活动 Provider 后关闭连接。
- 单个 Peer/网关/任务设置连接数、帧、字节、并发和重连上限。
- 大文件全程流式处理，不进入单个 Main `Buffer` 或 Renderer state。
## 11. 与现有模块集成
- `capability-service` 提供本机能力事实；共享 adapter 明确选择可公开子集。
- 已安装共享 Skill/MCP 继续使用现有配置、启停和 Runtime 分配，不建立第二套执行器。
- SSH Host 保持独立；除非未来提供专门 adapter 和用户发布，否则不进入目录。
- 远端 Task 的公开活动复用现有工具/任务展示语义，但保留 provider 和 route 字段。
- 应用更新源、模型下载源、Agent 下载源和工具下载源不因添加 ShareServer 自动改变。
## 12. 验证策略
### 12.1 自动化
- schema 边界、未知枚举和协议版本协商。
- 三个独立开关及默认值。
- mDNS 去重、接口变化、广播停止和手动地址。
- 配对双方确认、拒绝、超时、身份变化和撤销。
- 多网关隔离、认证过期、重连和移除。
- provider 排序、冻结、授权变化和失败不切换。
- 调用确认最小输入、附件上限、取消和结果未知。
- Publication 校验、暂停、撤销和 adapter 消失。
- 包签名、权限差异、来源冻结和失败保留旧安装。
- IPC sender、revision、归属和无通用网络/文件接口。
### 12.2 真实环境
- Windows、macOS、Linux 至少两种组合完成同网段发现和配对。
- mDNS 可用、被防火墙阻断、网络接口切换和设备离线场景。
- 真实 ShareServer 登录、设备出站连接、目录、调用和认证过期。
- 小型 JSON、文件流、取消、Provider 进程失败和网络中断。
- 确认日志、Renderer、诊断和审计中没有凭据或文件正文。
设计文档完成不代表功能实施或上述验证通过。
docs/features/device-sharing/ui-design.md
+211
View File
@@ -0,0 +1,211 @@
# 设备发现与共享 UI 设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
本文只定义桌面端界面。所有颜色、间距、字体、通知、Switch、PageTabs、焦点和响应式行为以
全局设计系统为准。
## 1. 信息架构
设置中心新增一级分类“设备发现与共享”，使用 `standard` PageShell：
```text
设备发现与共享
发现附近的 GoodBuddy，或连接组织网关使用和开放能力
[ 局域网 ] [ 网关 ] [ 本机共享 ] [ 活动记录 ]
```
四项使用共享 `PageTabs` 的 `segmented` 视觉变体。普通入口默认“局域网”；来自能力来源、
连接错误或审计入口的定向导航打开对应页签。页签选择不持久化为产品设置。
## 2. 局域网页签
页面顺序固定为本机发现状态、已配对设备、附近设备。
```text
局域网
发现附近设备 [Switch 开]
查看同一网络中主动开放的 GoodBuddy 设备
允许其他设备发现本机 [Switch 关]
设备名称：Jiang-PC [编辑]
已配对设备 [刷新]
名称 状态 能力 最近连接 操作
GPU-Workstation 在线 4 项 刚刚 ...
附近设备
Design-Mac 等待配对 [配对]
```
- 两个 Switch 必须独立成行，不能使用一个总开关。
- “允许被发现”开启后只显示广播状态和设备名，不暗示已经共享能力。
- 设备行采用紧凑列表，不使用大卡片墙。
- 已配对设备行可展开简要能力；完整信息进入设备详情抽屉。
- 离线设备保留在“已配对设备”，附近广播消失不删除配对。
### 2.1 配对对话框
```text
与 Design-Mac 配对
验证码 824 193
设备 Design-Mac · macOS
设备指纹 7A:31:...:D9
有效时间 01:42
请确认另一台设备显示相同信息。
[取消] [信息一致，确认配对]
```
双方尚未确认时显示独立进度。拒绝、超时和连接失败保留设备行并给出重新配对，不显示成功
通知。成功使用应用通知，焦点回到对应设备行。
### 2.2 设备详情
详情使用右侧抽屉，包含“概览”“能力”“授权”“活动”四个内部页签。未配对设备不能打开
能力和授权。撤销配对放在抽屉底部 danger zone，并说明活动任务和历史记录影响。
## 3. 网关页签
```text
网关 [添加网关]
研发组织网关
研发中心 · 成员
已连接 · 策略同步于 14:32
可用能力 18 项 · 本机发布 2 项 [...]
```
空状态说明网关是附加连接，局域网无需网关即可使用。主操作为“添加网关”。
### 3.1 添加网关
对话框只要求 HTTPS 地址，也可由邀请链接预填：
```text
网关地址
[https://share.example.com]
[取消] [继续登录]
```
地址通过 Main 验证后打开系统浏览器。应用内显示“等待浏览器登录”和取消入口，不嵌入第三方
登录页。回调成功后显示服务名、组织和账号，用户确认才保存连接。
网关详情抽屉包含连接、组织身份、可用能力、本机发布和诊断。移除连接明确说明只移除本机
连接，不删除组织账号或服务端设备记录。
## 4. 本机共享页签
页首状态摘要不能替代逐项开关：
```text
本机共享
已开放 2 项能力 · 局域网 1 项 · 网关 2 项
搜索能力 [范围筛选] [状态筛选]
文档转 Word [Switch 开]
范围：研发组织、GPU-Workstation
允许：查看、远程调用
确认：每次调用 [编辑]
```
能力关闭时保留配置摘要并标为“已暂停”。点击“编辑”打开共享设置对话框：
- 目标范围使用分组多选，不混合 Peer、网关组织和用户组。
- 允许动作使用 Checkbox。
- “每次确认”使用 Switch。
- 输入类型、大小、并发、时间段和有效期使用对应表单控件。
- 权限较高的能力在提交区显示具体影响，不用泛化风险等级。
- 提交按钮附近再次列出目标范围和允许动作。
能力尚未注册为可共享时不展示虚假的禁用行。列表为空时说明当前没有可共享能力，并提供前往
“能力与工具”的次操作。
## 5. 活动记录页签
使用 `dashboard` 所需的表格能力，但保持在设置 PageShell 内横向滚动：
```text
方向 能力 对端/来源 状态 时间
发出 图像生成 研发组织网关 已完成 14:36
收到 文档转 Word GPU-Workstation 正在执行 14:31
```
工具栏提供方向、来源、状态、时间和搜索。详情抽屉显示任务 ID、能力版本、授权依据、路由、
数据类型和大小、执行链、耗时、结果及取消/撤销入口。正文和文件内容默认不展示。
## 6. 能力选择与调用确认
远端能力进入现有能力目录时，在名称旁持续显示来源标签。多个提供者使用菜单选择：
```text
图像生成
提供者 [自动选择：GPU-Workstation v]
```
调用需要确认时使用对话框：
```text
调用“合同风险检查”
提供者 法务服务商
执行位置 外部组织
将发送 当前输入；contract.docx（1.8 MB）
连接方式 ShareServer 中继
网关可见正文 否
下游调用 无
[取消] [仅本次允许] [按此范围始终允许]
```
组织策略不允许保存 Grant 时不显示“始终允许”。按钮文字必须表达作用域，不能使用“确定”。
## 7. 执行活动
会话和任务中的远端工具活动至少显示：
```text
合同风险检查 · 法务服务商
正在执行 · 已发送 1 个文件（1.8 MB） [停止]
```
展开后显示路由、能力版本和执行链。跨组织来源使用文字“外部组织”，不能只靠颜色。进入结果
未知时显示持久警告和“查看活动详情”，不提供普通的自动重试按钮。
## 8. 状态与错误
- 首次为空、筛选无结果、加载失败、无权限和离线分别使用不同状态。
- 缓存目录必须显示“上次更新于”，且离线时不能显示为当前可用。
- 身份变化使用阻塞状态，唯一修复路径是撤销后重新配对。
- 网关认证过期在对应网关行提供“重新登录”。
- 发布字段错误就地显示；异步连接错误显示在对象行或详情中。
- 配对成功、网关保存和共享发布成功使用应用通知，不重复显示页内成功横幅。
## 9. 无障碍与响应式
- 四个页签使用 `tablist/tab/tabpanel`、方向键、Home、End 和可见焦点。
- 持久二元状态使用 `role="switch"`；范围和动作多选使用 Checkbox。
- 表格在窄窗口切换为保留同样字段的列表，不隐藏提供者、状态或执行位置。
- 指纹和长网关地址允许换行并提供复制按钮，不依靠水平裁切。
- 对话框关闭后焦点回到触发控件；浏览器登录返回后恢复到等待登录区域。
- 状态包含文字和图标，不以颜色作为唯一信号。
## 10. 固定词汇
使用“设备发现与共享”“局域网”“网关”“本机共享”“附近设备”“已配对设备”“允许其他
设备发现本机”“结果未知”“外部组织”。不使用“扫描机器”“公网共享”“永久信任整台设备”
或把 ShareServer 简称为“云端”。
docs/features/share-server/README.md
+29
View File
@@ -0,0 +1,29 @@
# ShareServer
ShareServer 是 GoodBuddy 设备共享网络的独立 Web 服务。它为一个或多个组织提供身份与设备
目录、能力发布、授权策略、任务路由、可选数据中继、能力包更新、网关联邦和审计管理。
ShareServer 不属于 Electron Main，不负责桌面端局域网发现，也不自动取得设备上的能力、
文件、凭据或 SSH Host。
## 文档导航
| 文档 | 权威职责 |
| --- | --- |
| [PRD](./prd.md) | 管理角色、产品范围、功能需求和验收 |
| [功能逻辑](./logic-design.md) | 组织隔离、设备、发布、策略、任务和联邦状态规则 |
| [管理界面设计](./ui-design.md) | ShareServer Web 控制台的信息架构与交互 |
| [技术设计](./technical-design.md) | 服务模块、API、数据、部署、运维和验证 |
| [共享网络总体设计](../../architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威 |
当前没有单独的 User Stories：管理员、能力发布者、审计员和普通成员场景已进入 PRD 与逻辑
设计。服务尚未实施，因此不创建 `progress.md`。
## 角色
- **系统管理员**：维护实例、身份源、域名、证书、存储和全局限制。
- **组织管理员**：管理本组织成员、设备、组、策略、能力和联邦关系。
- **能力发布者**：在获准范围内发布设备能力或签名能力包。
- **审批人**：处理调用、发布、更新和联邦申请。
- **审计员**：只读查看和导出获准范围内的审计事件。
- **成员**：主要通过 GoodBuddy Desktop 使用能力，只在 Web 端处理个人设备和审批。
docs/features/share-server/logic-design.md
+209
View File
@@ -0,0 +1,209 @@
# ShareServer 功能逻辑设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [ShareServer PRD](./prd.md) |
| 共享规则 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
## 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 初始化入口一次性关闭
初始化只在实例尚无系统管理员时可用。首个系统管理员创建成功后，后续请求即使持有旧的
一次性引导材料也不能再次进入初始化流程。
## 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。
## 3. 授权计算顺序
1. 验证请求身份、会话 audience 和 organization。
2. 验证用户、设备、provider、Publication 和 FederationTrust 当前状态。
3. 校验能力版本、动作、输入 schema、数据类别、大小和委托链。
4. 收集调用方组织、提供方组织、Publication 和 Grant 规则。
5. 按拒绝优先合并，计算 `deny/require_approval/allow`。
6. 校验次数、并发、预算和有效期。
7. 返回决定、稳定原因和策略引用；需要批准时建立内容绑定申请。
8. 创建任务时再次计算，并把决定快照写入任务。
目录查询可以预计算“可能可用”，但不能替代第 1 至 8 步。
## 4. 组织角色边界
| 动作 | 系统管理员 | 组织管理员 | 发布者 | 审批人 | 审计员 | 成员 |
| --- | --- | --- | --- | --- | --- | --- |
| 实例设置 | 是 | 否 | 否 | 否 | 只读有限项 | 否 |
| 成员与组 | 紧急管理 | 是 | 否 | 否 | 只读 | 自己 |
| 注册设备 | 只读/撤销 | 是 | 自己 | 否 | 只读 | 自己 |
| 发布能力/包 | 否 | 是 | 授权范围 | 否 | 只读 | 否 |
| 编辑策略 | 否 | 是 | 否 | 否 | 只读 | 否 |
| 处理审批 | 否 | 可配置 | 否 | 授权范围 | 只读 | 自己的申请 |
| 联邦关系 | 实例级许可 | 是 | 否 | 可共同审批 | 只读 | 否 |
| 审计导出 | 实例级 | 组织级 | 自己相关 | 自己相关 | 授权范围 | 自己相关 |
实际权限仍由策略计算，表格定义产品默认职责而非硬编码角色名称。
## 5. 任务路由决策
| 条件 | 结果 |
| --- | --- |
| provider 在线且双方可直连 | 签发短期直连协商信息 |
| 无法直连且双方策略允许中继 | 建立有界中继通道 |
| 中继关闭或任一方禁止 | 创建失败，说明无可用路由 |
| provider 离线 | 不排队到无限期，按能力配置有界等待或拒绝 |
| provider 接受后连接中断 | 保留 task，等待同一 provider 恢复/查询 |
| provider 终态未知且恢复期结束 | `outcome_unknown` |
| 调用方取消 | 转发取消；provider 确认后终态 cancelled |
中继容量不足只产生排队或资源错误，不切换 provider，不改变是否允许中继。
## 6. 更新策略优先级
```text
紧急撤销
> 组织强制固定版本/禁止版本
> 设备组发布通道
> 用户允许的版本范围
> 当前已安装版本
```
任何权限扩大都从自动路径转为 `require_approval`。降级只有在目标版本仍被签名目录允许且
策略明确指定时才提供，不自动视为故障回滚。
## 7. 联邦可见性
联邦目录只导出对方明确允许的能力投影：组织显示名、能力、版本范围、数据政策和可用性摘要。
不导出内部设备名、成员清单、组结构、节点地址、内部策略全文或审计记录。跨组织请求使用
双方关联 ID，双方各自解析本地主体。
## 8. 删除、撤销与保留
- 删除组织前必须停止新任务、撤销联邦和设备，并按保留策略归档审计；不提供无提示级联。
- 删除用户不删除其历史动作，审计显示不可变主体摘要。
- 撤销设备、Publication、Grant、Package 或联邦后立即阻止新令牌。
- 对象存储中的未完成任务正文按任务期限清理；审计元数据按组织保留策略清理。
- 法定保留只锁定匹配审计事件，不使被撤销身份重新可用。
## 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` | 短期权威恢复规则和逻辑完整性；部署结构由技术设计定义 |
## 10. 逻辑完整性
本设计覆盖实例、组织、成员、设备、发布、授权、审批、任务、更新、联邦、撤销和恢复。实现
前仍需确定首个 OIDC 提供者矩阵、默认审计保留期、部署规模目标和中继带宽上限；这些部署
参数应可配置，不改变拒绝优先、双边联邦和 provider 冻结规则。
docs/features/share-server/prd.md
+149
View File
@@ -0,0 +1,149 @@
# ShareServer PRD
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 适用产品 | 独立部署的 ShareServer 与 Web 管理控制台 |
| 关联架构 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
| 关联文档 | [功能逻辑](./logic-design.md)、[管理界面](./ui-design.md)、[技术设计](./technical-design.md) |
## 1. 背景
局域网配对适合附近设备，但不能统一解决跨网络访问、成员离职、组织策略、集中更新、审计和
跨组织协作。ShareServer 提供一个可自建的组织控制面，让设备通过主动出站连接注册能力并
接收任务，不要求为每台桌面设备开放公网端口。
## 2. 产品目标
1. 组织可在自有网络、私有云或公网独立部署 ShareServer。
2. 管理员可统一管理用户、组、设备、能力、权限、更新和审计。
3. 成员通过桌面端使用获准能力，无需日常进入管理控制台。
4. 设备离线、用户撤销或策略变化能准确影响新任务，不破坏历史证据。
5. 两个组织可经双边确认建立有限范围的联邦协作。
6. ShareServer 可以只运行控制面，也可按部署策略提供数据中继和包存储。
## 3. 产品范围
### 3.1 包含
- 本地账号及可配置 OIDC 身份源。
- 组织、成员、角色、用户组、设备组和服务账号。
- 设备注册、状态、撤销和合规元数据。
- 能力目录、Publication、Grant、强制策略和审批。
- 设备出站控制通道、任务路由、取消和可选中继。
- 签名能力包仓库、发布通道、更新策略和撤销。
- ShareServer 间双边联邦。
- 审计、用量、保留和导出。
- Web 管理控制台和成员自助页面。
### 3.2 不包含
- 远程管理设备桌面、任意 Shell 或任意文件系统。
- 发现未注册的局域网设备。
- 保存或分发用户 API Key、Cookie 和桌面登录状态。
- 默认查看任务正文、附件和模型输出。
- 未经提供者发布自动盘点设备能力。
- 自动信任同域邮箱、同一网络或其他 ShareServer。
- 公共开放市场、计费结算或匿名能力调用。
- 替代 GoodBuddy 官方客户端、模型和 Agent 发布源。
## 4. 功能需求
### FR-1 实例初始化
- 首次启动通过一次性引导创建实例标识和首个系统管理员。
- 引导完成后永久关闭初始化入口，后续管理员通过正常身份流程创建。
- 实例公开描述包含名称、协议版本、登录方式和联邦端点，不包含内部拓扑。
### FR-2 身份与组织
- 支持一个实例承载多个隔离组织，也支持部署为单组织模式。
- 支持本地账号和 OIDC；组织可限制允许的身份源。
- 成员可以属于多个组并拥有有界角色，角色不隐式跨组织。
- 停用用户立即停止签发新设备和任务凭据。
### FR-3 设备管理
- 桌面端经用户登录、一次性挑战和设备签名完成注册。
- 设备条目显示所有者、平台、客户端版本、最近在线、连接和撤销状态。
- 设备主动建立出站控制连接；服务端不能借此调用未发布能力。
- 管理员可撤销设备并终止其新任务资格。
### FR-4 能力目录
- 只接收已注册设备或服务节点提交的显式 Publication。
- 目录按调用者身份、设备状态、组织和策略过滤后返回。
- 支持同一能力多个版本和多个 provider，不掩盖来源。
- provider 离线时保留目录事实但显示不可用，不派发新任务。
### FR-5 授权策略
- Grant 可绑定用户、组、设备、设备组和联邦组织。
- 可约束能力、版本、动作、输入类型、数据分类、提供者、时间、次数、并发和委托。
- 支持组织强制策略和用户可收紧偏好；拒绝优先。
- 每个决定返回稳定结果、命中策略和面向用户的原因。
### FR-6 审批
- 调用、能力发布、权限扩大更新和联邦关系可以要求审批。
- 审批项显示申请人、对象、影响范围、数据类别、期限和策略依据。
- 批准结果有明确范围和有效期，不提供无边界“永久允许”。
- 申请内容变化后旧审批失效。
### FR-7 任务路由
- 根据冻结 provider、在线连接和路由策略把任务声明发送给目标设备。
- 支持直连协商、网关中继和取消传播。
- 任务正文与控制元数据分离；默认审计不保存正文。
- 已接受任务断线后允许查询同一 task，不自动创建重复执行。
### FR-8 能力包与更新
- 保存不可变签名 Package 和发布目录。
- 支持组织、组、平台、架构和维护窗口的更新策略。
- 支持固定版本、允许版本范围、暂停发布和紧急撤销。
- 权限扩大必须触发新批准，不能被普通自动更新策略覆盖。
- 包来源、大小、摘要、签名和下载结果可审计。
### FR-9 联邦
- 两个 ShareServer 通过指纹交换和双方管理员确认建立关系。
- 双方分别配置公开能力、允许主体、数据范围、用量和期限。
- 最终权限取双方策略交集；任一端撤销后停止新任务。
- 不默认链式转发到第三个组织。
### FR-10 审计与用量
- 记录身份、设备、发布、授权、审批、任务、包和联邦管理事件。
- 默认仅记录共享架构定义的有界元数据。
- 支持按组织隔离查询、条件筛选、分页和流式导出。
- 审计员只读，不能因查看日志取得任务正文或管理权限。
### FR-11 管理控制台
- 提供概览、组织与成员、设备、能力目录、权限策略、审批、发布与更新、网关联邦、任务与
中继、审计、系统设置。
- 普通成员只看到自己的设备、授权和待办；管理员栏目按权限隐藏并在 API 再次校验。
- 所有高影响操作说明对象、范围和后果。
### FR-12 可部署性
- 支持容器部署，配置与持久数据分离。
- 支持外部 PostgreSQL；对象存储和中继按功能启用。
- 提供健康、就绪、指标、结构化日志、备份和恢复说明。
- 服务升级不能要求同时升级所有在线桌面端；按协议版本协商兼容集合。
## 5. 产品验收
- 新实例可完成初始化、登录、创建组织、邀请成员和注册真实桌面设备。
- 两个不同组织不能通过 API、搜索、计数、错误或审计结果读取对方数据。
- 设备只有发布能力后才进入获准目录，撤销后不能接收新任务。
- 调用授权能同时处理用户、设备、组织、提供者、数据和联邦限制。
- 任务中继关闭时控制面仍可运行；中继开启时可取消并形成准确终态。
- 权限扩大的包更新不能自动部署。
- 两个独立 ShareServer 能建立、使用、暂停和撤销双边联邦。
- 备份恢复后组织、策略、发布和审计身份保持一致，短期连接和令牌不恢复。
docs/features/share-server/technical-design.md
+242
View File
@@ -0,0 +1,242 @@
# ShareServer 技术设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [ShareServer PRD](./prd.md) |
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
| 共享协议 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
## 1. 仓库与运行边界
实现时在仓库顶层创建独立项目：
```text
shareserver/
README.md
package.json
src/
api/
auth/
organizations/
devices/
capabilities/
policies/
approvals/
tasks/
relay/
packages/
federation/
audit/
web/
migrations/
deploy/
tests/
```
当前只提交设计文档，不创建无法运行的目录占位。服务端和 Desktop 共同依赖未来的
`packages/share-protocol`，ShareServer 不导入 Electron 的 `src/shared`。
## 2. 技术选型约束
- 使用与仓库一致的 TypeScript/Node.js 工具链，具体 HTTP 框架在实现前根据维护性选择。
- PostgreSQL 是组织、策略、任务元数据和审计的权威数据库。
- Package 与可选中继暂存使用 S3 兼容对象存储；不开启对应功能时不要求对象存储。
- Web 控制台与 API 同源部署，采用严格 CSP，不在浏览器保存设备凭据。
- 单实例部署可完整工作；水平扩展时再引入共享事件/连接路由组件，不为未验证规模预设复杂
分布式协议。
## 3. 服务模块
| 模块 | 职责 |
| --- | --- |
| `auth` | 本地身份、OIDC、Web session、服务和设备凭据 |
| `organizations` | 组织、成员、组、角色和范围解析 |
| `devices` | 注册挑战、设备记录、出站连接和在线状态 |
| `capabilities` | manifest、provider、Publication 和目录投影 |
| `policies` | Grant、强制策略和确定性授权计算 |
| `approvals` | 内容绑定申请、决定、过期和通知 |
| `tasks` | task/attempt、provider 路由、状态和取消 |
| `relay` | 可选有界数据中继，不解释能力正文 |
| `packages` | 不可变对象、签名目录、通道和撤销 |
| `federation` | 网关身份、offer、双边策略和跨组织映射 |
| `audit` | 事务内审计写入、查询、保留和导出 |
模块通过服务接口调用，API handler 不直接拼接跨组织 SQL 或自行计算权限。
## 4. API 边界
建议分为四类 audience：
```text
/api/v1/web/* 管理控制台与成员自助 API
/api/v1/device/* 设备注册、目录和任务控制 API
/api/v1/federation/* ShareServer 间 API
/api/v1/public/* 服务描述、健康与登录入口
```
设备使用 WebSocket `/api/v1/device/connect` 建立出站控制通道。包下载使用短期、绑定主体和对象
摘要的 URL。联邦 API 使用网关身份，不接受普通用户 session。每类 token 使用不同 issuer/
audience/scope，不能互换。
所有请求经 schema、认证、organization scope、授权、速率和大小边界。列表使用游标分页和固定
最大页；错误返回 request ID、稳定 code 和有界参数。
## 5. 数据模型
核心表建议为：
```text
instances
identity_providers
users
organizations
memberships
groups
group_members
role_bindings
registered_devices
device_credentials
device_connections
capabilities
capability_versions
providers
publications
grants
policies
approval_requests
approval_decisions
tasks
task_attempts
task_events
package_objects
package_releases
release_channels
update_policies
federation_trusts
federation_capability_exports
audit_events
revocations
```
要求：
- 所有组织数据表包含不可为空的 `organization_id`，并由 repository 层强制作用域。
- 唯一约束同时包含 organization，避免跨组织名称冲突泄漏。
- 密钥保存为单向摘要或经外部主密钥加密的密文；数据库不保存明文 token。
- 在线连接和短期 nonce 主要在内存；表中只保存恢复所需元数据，不把 socket 当持久对象。
- task event 只存控制状态和有界统计；正文流不进入普通关系表。
## 6. 事务与一致性
- 业务变更与对应审计事件在同一 PostgreSQL 事务提交。
- Publication/Grant/Policy 使用 revision 做乐观并发，Web 草稿不能覆盖他人更新。
- 授权决定创建 task 时再次读取当前 revision，并将命中策略摘要冻结到 task。
- 设备在线状态允许短暂最终一致；身份、撤销、授权和任务接受必须走权威存储。
- 重复注册挑战、联邦 offer 和 task create 使用唯一幂等键。
- 无法确认 provider 副作用时只更新 `outcome_unknown`，不靠消息队列自动重放。
## 7. 设备连接与任务
连接建立后完成设备 credential、organization、客户端协议和当前 registration 校验。服务端为
每个连接设置心跳、空闲、帧、发送队列和并发上限。
任务流程：
```text
authorize -> create task -> resolve exact provider connection
-> send declaration -> provider accepts/rejects
-> establish direct or relay route -> stream progress
-> provider terminal result -> caller delivery -> audit terminal state
```
同一设备重复连接时使用 connection generation；新连接接管未来任务，旧连接仍只允许完成或
查询已归属 task，随后有界关闭。不能把新任务随机发到身份相同但 generation 过期的 socket。
## 8. 中继
中继是可选模块：
- 控制面与中继可部署在不同进程，但共享 task 授权验证。
- 每个 relay ticket 绑定 task、调用方、provider、方向、期限和最大字节。
- 实现背压和全局/组织/设备并发及带宽上限。
- 不解析能力正文，不写普通日志；需要临时落盘时使用加密 GoodBuddy-owned 暂存并按 task 清理。
- 中继关闭、过载或策略禁止时返回准确路由错误，不静默转到其他节点。
## 9. Package 存储
上传先进入不可公开暂存：流式计算大小和 SHA-256，验证签名、manifest、版本、平台和权限后，
以 digest 发布为不可变对象。相同 digest 可去重，但组织授权和 Release 分别保存。
Release catalog 使用独立签名域。服务器不能重打包已签名 payload；镜像目标必须保持相同字节、
大小和 SHA-256。撤销更新目录和授权，不覆盖或原地删除仍受审计保留的对象。
## 10. 联邦协议
- 每个实例生成网关身份和可轮换证书，私钥不进入数据库备份明文。
- offer 包含双方可人工核对的组织名、端点、指纹、协议和 nonce。
- 双方确认后交换有界 capability projection 和本地映射 ID。
- 跨组织 task 带双方关联 ID 和短期签名声明；每端独立授权并各写审计。
- 不接受调用方提供的任意回调 URL、第三方 hop 或内部主体 ID。
- 证书轮换需要旧身份签名或双方重新确认；身份突变直接暂停关系。
## 11. Web 安全
- 使用 HttpOnly、Secure、SameSite cookie 和 CSRF 防护管理 Web session。
- OIDC 使用 state、nonce、PKCE 和固定回调地址。
- 富文本字段按纯文本显示；manifest/schema 使用安全代码查看器，不执行 HTML。
- 权限隐藏仅改善界面，所有 API 在服务端重新校验。
- 登录、设备注册、目录、审批、导出和联邦接口分别限速。
- 密钥字段只能替换、轮换和测试，永不回显。
## 12. 部署与配置
最小生产部署：
```text
TLS reverse proxy/load balancer
ShareServer API + Web
PostgreSQL
可选：S3 compatible object storage
可选：Relay worker
```
部署配置通过环境变量或挂载文件提供数据库、主密钥、公开 URL、OIDC、邮件、对象存储和限制。
普通 Web 管理员不能修改基础设施秘密。提供数据库迁移命令、不可变镜像、非 root 容器、健康
与就绪端点、优雅停止和部署示例。
## 13. 可观测性与备份
- 结构化日志只包含 request/task/organization 关联 ID、稳定事件和错误码。
- 指标覆盖请求、WebSocket、授权结果、任务状态、中继、Package 和联邦，不包含能力正文。
- tracing 跨内部服务传播关联 ID，跨联邦只传播双方同意的关联标识。
- 备份 PostgreSQL、Package 对象和网关身份；不备份缓存、Web session、nonce 或中继暂存。
- 恢复后撤销列表、组织 ID、签名目录和审计序列保持有效，所有设备重新连接。
## 14. 测试策略
### 14.1 自动化
- schema、认证 audience、CSRF、OIDC 和设备挑战。
- 每个 repository/API 的跨组织隔离与枚举防护。
- 拒绝优先授权、审批内容绑定、预算和并发。
- device generation、离线、撤销、重连和 provider 冻结。
- task 幂等、取消、结果未知和不自动重放。
- Package 流式校验、不可变性、权限 diff 和撤销。
- 联邦双方确认、策略交集、暂停、证书变化和禁止第三 hop。
- 审计事务、过滤、分页、导出和正文缺失。
### 14.2 集成与部署
- Desktop 与真实 ShareServer 完成注册、目录、调用、文件和取消。
- 两个隔离组织验证搜索、计数、错误、对象和审计不泄漏。
- 两个 ShareServer 完成联邦建立、跨组织调用和单方撤销。
- 中继关闭与开启、容量耗尽、连接中断和大文件背压。
- 数据库备份恢复、版本升级、滚动停止和设备重连。
- 生产 TLS、OIDC 和对象存储组合的端到端验证。
设计完成不代表服务已实现；只有独立部署和真实 Desktop 端到端路径通过后才能更新实施状态。
docs/features/share-server/ui-design.md
+159
View File
@@ -0,0 +1,159 @@
# ShareServer Web 管理界面设计
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [ShareServer PRD](./prd.md) |
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
ShareServer 是独立 Web 产品，不直接复用 Electron 页面壳层实现，但沿用 GoodBuddy 的语义
词汇、状态含义和克制的运营工具风格。界面以列表、表格和主从详情为主，不使用营销首页或
装饰性卡片墙。
## 1. 使用对象
- 普通成员主要在 GoodBuddy Desktop 使用能力；Web 端只处理自己的设备、申请和授权。
- 组织管理员使用完整组织控制台。
- 系统管理员使用与组织控制台分开的实例管理范围。
- 审计员进入只读视图，不显示可变更控件。
登录后直接进入当前身份可用的实际控制台，不显示产品宣传页。
## 2. 全局框架
```text
顶部栏：ShareServer 实例名 | 当前组织 | 全局搜索 | 审批 | 账号
侧栏：
概览
组织与成员
设备
能力目录
权限策略
审批
发布与更新
网关联邦
任务与中继
审计
系统设置（仅系统管理员）
```
当前组织始终显示。切换组织会重新加载整个数据范围，不保留上一组织的选择、筛选或详情。
系统管理使用“实例范围”标识，不能伪装成某个组织。
## 3. 概览
概览只显示需要行动和运行事实：
- 待审批数量及最旧等待时间。
- 在线/离线/已撤销设备。
- 可用/离线/暂停能力。
- 当前任务、失败和结果未知。
- 包更新异常和紧急撤销。
- 联邦连接异常。
- 中继流量和容量，仅在中继启用时显示。
指标可点击进入已带筛选的对应页面。没有事件时不显示虚构趋势。
## 4. 组织与成员
使用“成员”“用户组”“角色”三个同级页签。成员表包含姓名、身份源、组、状态、设备数和
最近活动。邀请是唯一主操作；暂停和移除进入行末菜单。
成员详情采用抽屉，显示身份、组、角色、设备、有效 Grant、申请和审计。管理员不能查看成员
任务正文或桌面文件。
## 5. 设备
```text
设备 所有者 平台 状态 能力 最近在线
Jiang-PC Jiang Windows 在线 2 刚刚
GPU-Worker-02 AI Team Linux 离线 8 2 小时前
```
设备详情包含概览、连接、已发布能力、Grant 和活动。设备状态与 Publication 状态分别显示。
撤销设备使用危险确认，说明新任务、活动任务和重新注册影响。
## 6. 能力目录
目录以能力为第一列，提供者为可展开信息：
```text
能力 版本 提供者 可见范围 可用性
图像生成 2.1.0 3 个节点 设计组 2/3 在线
```
详情包含 manifest、provider、Publication、允许输入、数据政策、调用趋势和最近错误。管理员
看到的是组织元数据，不通过目录读取能力内部数据。
## 7. 权限策略
策略页分“强制策略”和“Grant”。创建和编辑使用结构化表单：主体、能力、动作、输入、提供者、
时间、预算、批准和委托。保存前提供自然语言摘要：
> 允许“设计组”从合规设备调用组织内“图像生成”2.x；只发送文本和图片；每人每日 20 次；
> 不允许下游委托。
策略冲突预览显示最终结果和命中规则，但不提供允许规则覆盖拒绝规则的顺序拖拽。
## 8. 审批
审批收件箱按调用、发布、更新和联邦分类。详情必须显示申请人、能力或对象、目标范围、数据
类别、权限变化、期限和策略依据。批准按钮使用具体文案，例如“允许本次调用”“批准此版本
发布”，不能只有“同意”。
批量批准仅用于同类型、同策略且不包含权限扩大的低影响申请；联邦和权限扩大更新不支持
批量批准。
## 9. 发布与更新
页面分“能力包”“发布通道”“更新策略”“撤销记录”。Package 表显示版本、发布者、签名、
大小、目标平台、权限变化和状态。上传后先进入验证，不直接发布。
版本详情提供 manifest、摘要、签名、兼容范围、权限 diff、依赖和下载事实。紧急撤销位于
独立 danger zone，需要输入版本标识确认，并说明受影响设备和新任务。
## 10. 网关联邦
```text
合作组织 对端地址 状态 开放能力 有效期
法务服务商 share.legal.example 已连接 2 项 12-31
```
建立关系采用向导：填写端点、核对组织和指纹、选择公开范围、设置调用与数据限制、生成 offer、
等待对方确认、复核双方交集。只有双方完成后显示“已连接”。
详情明确展示“我方开放”“对方开放”“最终可用”三个集合。暂停和撤销说明对活动任务的处理。
## 11. 任务与中继
任务表显示调用方、能力、provider、路由、数据类别、状态、耗时和时间。默认不显示正文。
活动任务提供取消；结果未知使用独立状态并显示 provider 最后确认点。
中继未启用时页面显示控制面正常和启用位置，不展示零值图表。启用后显示活动连接、吞吐、
排队、容量和拒绝原因，不提供查看正文的调试入口。
## 12. 审计
提供操作者、动作、对象、组织、结果、时间和关联 ID 的可筛选表格。导出前显示条件、估算行数、
时区和字段范围；大导出作为后台任务生成有时效下载。审计详情保持只读，不把原始内部错误、
认证信息或任务正文显示给管理员。
## 13. 系统设置
只包含实例名称、公开地址、身份源、邮件、数据库/对象存储状态、中继开关与上限、保留策略、
联邦总开关、证书和版本。秘密字段只支持替换或测试，不回显原值。
运行时基础设施配置优先来自部署环境；Web 界面不能修改数据库连接串、主密钥或容器挂载路径。
## 14. 状态、响应式与无障碍
- 加载、无数据、无匹配、无权限、服务错误和部分不可用分别展示。
- 管理表格支持键盘访问、可见焦点、表头关联和分页；行菜单有可访问名称。
- 窄屏将表格转为字段列表，保持组织、来源、状态和风险信息，不把管理动作挤成不可辨图标。
- 所有时间显示实例时区并可查看 ISO 时间；联邦事件同时显示对端时间时标明时区。
- 状态不只依赖颜色。危险操作在确认后保持原页面上下文和可恢复错误。