7.8 KiB
设备发现与共享功能逻辑设计
文档信息
| 项目 | 内容 |
|---|---|
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | 设备发现与共享 PRD |
| 共享规则 | 共享网络总体设计 |
本文负责桌面端状态、不变量和决策规则，不重复跨端协议定义。
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 局域网服务
discover: off | starting | active | unavailable | error
advertise: off | starting | active | unavailable | error
操作系统或网络不支持时使用 unavailable；运行失败使用 error。两者分别重试。
2.2 附近设备
visible_unpaired -> pairing -> paired_online
pairing -> rejected | expired | failed
paired_online <-> paired_offline
paired_* -> identity_changed | revoked
identity_changed 不自动接受新证书。用户必须撤销旧配对后重新配对。
2.3 网关连接
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 本机发布
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. 提供者选择
自动选择按以下顺序比较满足当前输入和授权的在线候选：
- 本机提供者。
- 已配对局域网提供者。
- 当前用户所属组织提供者。
- 联邦外部组织提供者。
- 同级中按服务端预计排队时间和稳定能力版本排序。
自动选择不跨越 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 子集、端到端中继加密套件和桌面端可 注册为共享能力的首批实际类型；这些是技术选择，不改变本文状态和产品规则。