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 简称为“云端”。