goodbuddy/docs/features/device-sharing/prd.md

设备发现与共享 PRD

文档信息

项目	内容
状态	本地元数据首期已接入；完整共享网络为后续设计
版本	0.1
日期	2026-09-03
适用产品	GoodBuddy Desktop
关联架构	共享网络总体设计
关联文档	功能逻辑、UI 设计、技术设计

当前首期：本地元数据

2026-10-01 首期范围由 FR-M1 至 FR-M5 定义。后文 FR-1 至 FR-14 保留为后续共享网络 设计，不能用来推断首期已有发现、认证、调用或内容传输能力。

• FR-M1 入口与设置：设备共享为可选应用，测试阶段默认关闭，应用中心提供启用开关； 启用后才出现在应用菜单，关闭时退出当前设备共享页面。旧设置缺少开关时按关闭处理，已保存的 明确启用值保留。关闭不清除目录、设备设置或撤销已发布记录。本机设备 ID 稳定保存，用户可 修改服务 URL 和设备名称。设置保存后重启仍保留；新设备默认连接 http://127.0.0.1:8787。
• FR-M2 注册与浏览：用户显式注册本机，随后查看服务实际返回的设备及发布列表。注册 包含 ID、名称、平台、应用版本；时间来自服务记录，不从更新时间推断在线状态。
• FR-M3 元数据发布：注册本机后可发布名称、描述、能力或知识类型、设备或服务器来源。 知识的搜索、读取、下载三个标志独立选择。服务器来源不会上传、同步或托管内容；权限 标志不提供内容访问实现。
• FR-M4 撤销与刷新：只给匹配本机 ID 的已发布条目提供撤销入口，确认后更新服务记录并 刷新目录，显示已撤销状态。该筛选不构成认证，服务本身没有所有权鉴权。
• FR-M5 失败恢复：请求有超时，错误可见；失败保留用户输入，列表失败不伪装为空目录。 修改服务 URL 后必须先保存，再向新服务注册或发布。既有应用设置、排序和常驻偏好保留。

验收顺序为启用应用、保存配置、注册本机、浏览返回列表、发布知识元数据、检查三个独立标志、撤销、 刷新并重启读取设备 ID。网络请求由 Main 发出，Renderer 只调用显式 preload 方法。

后续设计

以下章节为完整共享网络计划，尚未实施。

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 与现有能力的边界

• 远端调用不能扩大 Workspace、MCP、Skill 和知识库既有能力范围，沿用统一执行规则。
• 本机提供任务时使用能力声明对应的 Runtime 边界。
• SSH 远程项目、本机工具环境和模型配置默认不向 Peer 或网关传播。

5. 产品验收

• 两台新设备能完成发现、双端配对、授权、调用、取消和撤销。
• 三个概念“主动发现、允许被发现、开放能力”在状态和界面上互不混淆。
• 不配置网关时局域网工作完整；任一网关故障不阻塞其他来源。
• 未配对或未授权主体无法查看详细能力。
• 远端调用前能准确列出实际发送的数据，执行中和历史中可追溯提供者。
• 结果未知不会被显示为失败后自动重试或成功。
• 权限扩大的能力更新不会沿用旧授权静默安装。
• 中英文、键盘、焦点、窄窗口和深浅主题符合统一设计系统。