goodbuddy/docs/features/device-sharing/ui-design.md

设备发现与共享 UI 设计

文档信息

项目	内容
状态	本地元数据首期已接入；完整共享网络为后续设计
版本	0.1
日期	2026-09-03
关联 PRD	设备发现与共享 PRD
功能逻辑	功能逻辑设计
全局规范	GoodBuddy 统一界面设计系统

本文只定义桌面端界面。所有颜色、间距、字体、通知、Switch、PageTabs、焦点和响应式行为以 全局设计系统为准。

当前首期页面

本节对应 FR-M1 至 FR-M5，后文四页签、配对及调用界面为后续设计。

应用中心显示“可选”及启用状态，测试阶段默认关闭，此时“打开”禁用。应用设置复用共享 Switch，常显测试状态和关闭后果，不提供常驻开关。启用后应用菜单显示入口，关闭时退出 设备共享页面并返回对话。主内容区使用 standard PageShell、PageHeader 与全局范围徽标。 标题下常显未认证、ID 识别用途和无执行／内容访问的边界。内容依次为本机设置、已注册设备、 发布表单和发布目录。服务 URL 与设备名称可编辑，设备 ID 只读；注册、保存与刷新为次操作， “发布元数据”为唯一主按钮。

类型与来源使用短标签原生选择框；知识的搜索、读取、下载使用三个独立 Checkbox。服务器来源 不上传或同步内容的说明常显。发布按钮附近显示已保存的目标服务及设备名称，尚未注册或 配置未保存时给出操作提示。列表展示服务返回的名称、标识、平台／类型、更新时间和发布状态， 不展示在线灯或执行按钮。

撤销使用共享危险入口和就地确认，说明保留记录且不删除本机内容。成功与操作失败通过应用 通知反馈；目录加载失败在页面显示并由刷新按钮恢复。宽度收窄时按钮换行，长 URL 和 ID 换行； 表单复用 .field，颜色与间距使用共享令牌。页面文案提供中英文。

1. 信息架构

设置中心新增一级分类“设备发现与共享”，使用 standard PageShell：

设备发现与共享
发现附近的 GoodBuddy，或连接组织网关使用和开放能力

[ 局域网 ] [ 网关 ] [ 本机共享 ] [ 活动记录 ]

四项使用共享 PageTabs 的 segmented 视觉变体。普通入口默认“局域网”；来自能力来源、 连接错误或审计入口的定向导航打开对应页签。页签选择不持久化为产品设置。

2. 局域网页签

页面顺序固定为本机发现状态、已配对设备、附近设备。

局域网

发现附近设备                                      [Switch 开]
查看同一网络中主动开放的 GoodBuddy 设备

允许其他设备发现本机                              [Switch 关]
设备名称：Jiang-PC                                 [编辑]

已配对设备                                      [刷新]
名称             状态        能力       最近连接       操作
GPU-Workstation  在线        4 项       刚刚           ...

附近设备
Design-Mac       等待配对                               [配对]

• 两个 Switch 必须独立成行，不能使用一个总开关。
• “允许被发现”开启后只显示广播状态和设备名，不暗示已经共享能力。
• 设备行采用紧凑列表，不使用大卡片墙。
• 已配对设备行可展开简要能力；完整信息进入设备详情抽屉。
• 离线设备保留在“已配对设备”，附近广播消失不删除配对。

2.1 配对对话框

与 Design-Mac 配对

验证码        824 193
设备          Design-Mac · macOS
设备指纹      7A:31:...:D9
有效时间      01:42

请确认另一台设备显示相同信息。
[取消] [信息一致，确认配对]

双方尚未确认时显示独立进度。拒绝、超时和连接失败保留设备行并给出重新配对，不显示成功 通知。成功使用应用通知，焦点回到对应设备行。

2.2 设备详情

详情使用右侧抽屉，包含“概览”“能力”“授权”“活动”四个内部页签。未配对设备不能打开 能力和授权。撤销配对放在抽屉底部 danger zone，并说明活动任务和历史记录影响。

3. 网关页签

网关                                                   [添加网关]

研发组织网关
研发中心 · 成员
已连接 · 策略同步于 14:32
可用能力 18 项 · 本机发布 2 项                         [...]

空状态说明网关是附加连接，局域网无需网关即可使用。主操作为“添加网关”。

3.1 添加网关

对话框只要求 HTTPS 地址，也可由邀请链接预填：

网关地址
[https://share.example.com]

[取消] [继续登录]

地址通过 Main 验证后打开系统浏览器。应用内显示“等待浏览器登录”和取消入口，不嵌入第三方 登录页。回调成功后显示服务名、组织和账号，用户确认才保存连接。

网关详情抽屉包含连接、组织身份、可用能力、本机发布和诊断。移除连接明确说明只移除本机 连接，不删除组织账号或服务端设备记录。

4. 本机共享页签

页首状态摘要不能替代逐项开关：

本机共享
已开放 2 项能力 · 局域网 1 项 · 网关 2 项

搜索能力                     [范围筛选] [状态筛选]

文档转 Word                                      [Switch 开]
范围：研发组织、GPU-Workstation
允许：查看、远程调用
确认：每次调用                                    [编辑]

能力关闭时保留配置摘要并标为“已暂停”。点击“编辑”打开共享设置对话框：

• 目标范围使用分组多选，不混合 Peer、网关组织和用户组。
• 允许动作使用 Checkbox。
• “每次确认”使用 Switch。
• 输入类型、大小、并发、时间段和有效期使用对应表单控件。
• 权限较高的能力在提交区显示具体影响，不用泛化风险等级。
• 提交按钮附近再次列出目标范围和允许动作。

能力尚未注册为可共享时不展示虚假的禁用行。列表为空时说明当前没有可共享能力，并提供前往 “能力与工具”的次操作。

5. 活动记录页签

使用 dashboard 所需的表格能力，但保持在设置 PageShell 内横向滚动：

方向       能力             对端/来源          状态       时间
发出       图像生成         研发组织网关       已完成     14:36
收到       文档转 Word      GPU-Workstation    正在执行   14:31

工具栏提供方向、来源、状态、时间和搜索。详情抽屉显示任务 ID、能力版本、授权依据、路由、 数据类型和大小、执行链、耗时、结果及取消/撤销入口。正文和文件内容默认不展示。

6. 能力选择与调用确认

远端能力进入现有能力目录时，在名称旁持续显示来源标签。多个提供者使用菜单选择：

图像生成
提供者 [自动选择：GPU-Workstation v]

调用需要确认时使用对话框：

调用“合同风险检查”

提供者       法务服务商
执行位置     外部组织
将发送       当前输入；contract.docx（1.8 MB）
连接方式     ShareServer 中继
网关可见正文 否
下游调用     无

[取消] [仅本次允许] [按此范围始终允许]

组织策略不允许保存 Grant 时不显示“始终允许”。按钮文字必须表达作用域，不能使用“确定”。

7. 执行活动

会话和任务中的远端工具活动至少显示：

合同风险检查 · 法务服务商
正在执行 · 已发送 1 个文件（1.8 MB）                 [停止]

展开后显示路由、能力版本和执行链。跨组织来源使用文字“外部组织”，不能只靠颜色。进入结果 未知时显示持久警告和“查看活动详情”，不提供普通的自动重试按钮。

8. 状态与错误

• 首次为空、筛选无结果、加载失败、无权限和离线分别使用不同状态。
• 缓存目录必须显示“上次更新于”，且离线时不能显示为当前可用。
• 身份变化使用阻塞状态，唯一修复路径是撤销后重新配对。
• 网关认证过期在对应网关行提供“重新登录”。
• 发布字段错误就地显示；异步连接错误显示在对象行或详情中。
• 配对成功、网关保存和共享发布成功使用应用通知，不重复显示页内成功横幅。

9. 无障碍与响应式

• 四个页签使用 tablist/tab/tabpanel、方向键、Home、End 和可见焦点。
• 持久二元状态使用 role="switch"；范围和动作多选使用 Checkbox。
• 表格在窄窗口切换为保留同样字段的列表，不隐藏提供者、状态或执行位置。
• 指纹和长网关地址允许换行并提供复制按钮，不依靠水平裁切。
• 对话框关闭后焦点回到触发控件；浏览器登录返回后恢复到等待登录区域。
• 状态包含文字和图标，不以颜色作为唯一信号。

10. 固定词汇

使用“设备发现与共享”“局域网”“网关”“本机共享”“附近设备”“已配对设备”“允许其他 设备发现本机”“结果未知”“外部组织”。不使用“扫描机器”“公网共享”“永久信任整台设备” 或把 ShareServer 简称为“云端”。