[Dogfooding] 重新设计设备接入：快速配对、按用途授权与免手工配置

[Disdjj]

要解决的问题

设备接入目前要求用户自己组合一套内部配置。用户反馈的实际路径是：

1. 在 Dashboard 生成 API Key。
2. 把 API Key 和 Base URL 带到目标设备，执行 daemon install。
3. 再决定并配置开放哪些常用命令。
4. 再添加文件夹，最后才能开始使用。

这不仅是步骤多，还要求用户理解凭证、网关地址、设备身份、后台进程、命令白名单和文件系统挂载，并在浏览器与终端之间传递配置、判断何时完成。系统把内部模块的衔接交给了人。

目标：用户表达“把这台设备连接到这里，允许做这些事”，系统负责配对、限权凭证、注册、配置落地和连接维护。常规交互接入不再要求用户手动创建、复制、拼装长期 API Key。

本 issue 是设备体验的产品设计与实现跟踪。用户流程来自上述反馈；实现约束来自代码审阅。本轮未进行实机可用性测试，以下流程是待验证设计，不是已实现能力或已测结论。

设计原则：按人的任务组织流程

用户真正需要决定的事	系统应承担的事
连接哪台设备、连接到哪个网关/空间	传递网关上下文、生成稳定设备身份、协调配对请求
是否认可这次接入，以及谁可以使用它	检查审批权限、签发设备专属限权凭证、应用调用访问策略
允许哪些用途、哪些目录、是否可写	将意图编译为命令 profile、目录边界和授权配置，校验并应用
是否退出终端后仍保持可用	检测系统支持、安装和维护后台服务、报告实际运行状态
修改授权、暂时停止、解除连接	更新配置、恢复连接、吊销凭证及清理关联状态

高级配置仍可访问，但默认流程不要求理解 SK、registerPaths、挂载路径或 systemd。必要的权限决定应清楚保留，重复填写和内部协调应由系统完成。

1. 快速配对：从用户所在的位置开始

至少提供一条覆盖无浏览器设备的 URL + 短码 快速配对路径，并评估浏览器自动打开和扫码作为同一流程的便捷入口。

场景	期望交互	必须解决的交接
已在 Dashboard，准备接入一台服务器	点击“连接设备”，在目标机器运行已带网关上下文的启动指引；回到当前页面确认出现的配对请求	不另外去密钥页；页面自动等待设备出现，不让用户复制回设备 ID
已在目标设备终端	启动连接，必要时只输入/选择网关一次；终端给出 URL 和短码，在可用的浏览器完成确认	无浏览器/无入站端口也能完成；终端显示当前进度并自动继续
目标设备本身有浏览器	自动打开确认页面，并保留可复制链接作为兜底	优先同机完成，不强迫拿出手机扫码
用手机审批另一台设备	扫描终端展示的二维码，在手机确认对应设备和网关	明确“手机在审批目标设备”，不能误把手机作为被接入设备；无相机时仍能用 URL + 短码

这些应是自然进入同一流程的方式，不需要用户先理解和挑选认证协议。自托管部署必须交代网关地址如何传入：短码本身不能凭空确定它属于哪个网关。Dashboard 已知的信息由系统带入，已有配置可以复用；陌生设备仍需要一次明确的目标选择。

配对成功后双方自动继续，用户不需要复制新 token、重跑安装命令或手动刷新才能看到结果。页面展示的是清晰可辨认的设备、当前网关及请求，而非只有“授权”按钮；设备名属于辅助识别，不能单凭可伪造名称建立信任。

二维码只承载配对入口，不装入长期 API Key，也不因扫码本身就完成授权。设备端持有的兑换凭据与展示给人的短码应有清楚的职责边界。

2. 能力配置：让人选择用途，不让人编写配置

配对解决“关联到哪里”；能力配置解决“允许做什么”。二者属于连续体验，但可以分步完成：

• 支持“仅连接，稍后设置”，清楚展示“已配对，尚未开放操作”，不要误报为失败，也不要声称已经可以使用文件或 shell。
• 首次选择只呈现少量可理解的用途，例如“查看基本状态”“访问指定文件夹”“使用常用运维操作”。每项列出真实范围、读写性质和前提条件；不支持的能力说明原因。
• 常用操作需要可维护的结构化预设，由系统生成并验证配置。普通用户无需先手写 command profile；不能把允许任意 shell 包装成“常用操作”。
• 非必要配置可以稍后完成。开放目录时再询问目录，启用写入时再说明写入影响，不强迫第一次选完未来所有用途。
• 完成后提供与当前授权相符的首个任务，直接展示结果，让用户理解连接的实际价值。
• 之后从设备详情修改能力，应用后明确反馈。新增目录或操作无需重新配对，也不要求再次生成 Key 或手工重装 daemon。

文件夹选择必须属于目标设备

不能把浏览器所在电脑的文件选择器当作远端目录选择器。设计阶段需比较目标设备终端交互选择、设备端本地 UI、受限远端选择等方案，交代目录列表在何种授权下可见。

用户应能确认目标机器、实际目录、只读/读写范围，并得到路径不存在或权限不足的就地反馈；不能为了方便选择而预先暴露整台设备的文件系统。本地资源访问仍由设备侧验证。

3. 配对之后：持续可用与可恢复

用户看到的进度应是“等待确认 → 正在完成连接 → 已连接”，并在需要时解释当前卡在哪一步。内部仍要区分配对、凭证交付、注册、配置应用及后台服务启动，避免任一步成功就提前宣告全部完成。

同时独立展示三个事实：是否已配对、当前是否在线、开放了哪些能力。已配对且离线的设备不应再次要求输入配对码。

• 后台运行： 用“退出终端后保持连接”表达目的，检测平台后自动完成支持的步骤。确需本机系统权限时解释具体用途；不要求用户研究 systemd。配对成功但后台安装失败，保留已完成进度并允许续做。
• 断网或重启： 已安装后台连接的设备恢复网络后沿用原身份重连，不重复创建设备或重复授权。
• 中途退出： 浏览器关闭、终端重启、请求过期等有明确恢复入口；显示已完成的部分，只重做失效步骤。
• 重复操作： 重复点击、扫码、安装或同名设备不生成额外有效凭证/重复设备，不误覆盖另一台机器。设备重装、主动替换设备需要单独的身份处理规则。
• 解除关系： 区分“暂停后台运行”“撤销访问”“解除配对”“卸载本机程序”，用后果解释差异；远端设备离线时也能撤销网关访问。已排队或可能已执行的任务按既有语义处理，不能承诺副作用被撤销。

4. 系统需要兜住的边界

以下是实现必须保证的内部行为，不是要增加到普通用户流程中的配置清单：

• 配对请求限时、一次性消费、可取消，短码错误/过期有可恢复提示；对猜码、重复兑换、并发审批和请求滥用有服务端约束。
• 配对绑定目标网关和发起设备持有的会话凭据，只有具备相应权限的审批者能批准；不得把浏览器里的 Admin SK 下发设备。
• 自动颁发的凭证只服务于相应设备和必要注册范围。凭证交付中断、配置保存失败及重新尝试不能遗留可用的孤立凭证；轮换、到期和吊销都要有恢复/失效语义。
• “设备获准接入”“调用者获准使用”“本机允许执行”是三个不同的授权边界。浏览器审批不能自动放开整机文件、全量 shell 或所有调用者权限。
• 用户能理解谁可以使用开放的能力；使用现有可解释的访问策略或选择明确的访问范围，不要求用户手写 scope，也不默认为所有连接者可用。
• 同一所有者可以在一次清楚的授权汇总中表达相关决定；多人代接入时，要明确管理员和设备持有者各自能批准什么。
• 本机目录边界、命令限制与敏感信息保护由代码保证。后续扩权须有明确授权，不能通过远端配置更新静默越过本地已允许范围。

现有基础与具体缺口

审阅基线：7201827。已有 Linux/systemd daemon 生命周期、设备实时会话、结构化命令 profile、文件访问和 durable mailbox；应复用底座，但前端体验无需照搬这些模块的组织方式。

• DevicesPage 只生成 tb connect <baseUrl>，并称 CLI 会提示输入 SK。
• connect 在缺 SK 时直接报错；默认 shell allow 为空，fs 要显式配置。因此当前入口既有说明偏差，也没有完成“直接连接并开始使用”的产品流程。
• daemon 已负责配置保存、安装更新、等待 ready 和失败回滚；当前长期运行支持有明确的 Linux/systemd 边界，不应伪装成所有平台均已支持。

设计交付与验收

先验证交互，再确定内部接口

• 提交 Dashboard 发起、无浏览器终端发起、同机浏览器与手机审批的流程稿；至少验证主路径和中途失败恢复，说明实际支持哪些平台。
• 对 URL + 短码、自动打开链接和扫码比较：跨屏幕次数、重复输入、目标辨认、失效恢复、无相机/无浏览器可达性；据此确定首期入口组合。协议、命令名、默认预设清单和远端目录选择方式在设计评审后确定。
• 找一位未参与实现的人按真实任务完成接入，记录完成时间、跨界面切换、手工复制项、求助点及能否正确说出授权范围。不能只用“少了几个点击”或实现者跑通脚本作为易用性证据。

端到端完成标准

• 新机器使用快速配对时，手动创建长期 API Key、复制长期 Key、手工拼装 Key + Base URL 的次数均为 0。安装客户端及必要的本机权限操作单独计量，不能藏在前置条件里。
• 没有浏览器、没有扫码条件的目标设备仍可通过 URL + 短码接入；手机可完成确认页面，设备端自动继续，双方显示同一结果。
• 既可仅配对并稍后配置，也可一次连续流程完成一个真实的受限任务。常用能力不需要手写 profile，文件访问明确指向目标设备且具备明确权限范围。
• 在已有设备上新增一个目录或常用操作，无需重新配对/生成 Key/手工重新安装；应用失败可恢复，已有授权不被静默扩大。
• 支持的平台上，启用后台运行后退出终端、重启或网络恢复能够沿用同一设备身份恢复；安装失败不能把“已配对”进度一并丢弃。
• 覆盖错误/过期码、拒绝审批、浏览器关闭、网络中断、重复兑换、并发确认、凭证保存失败和后台安装失败；不会生成重复设备或遗留有效孤立凭证。
• 用户能够辨认多台同名设备及多个网关；能够从控制台撤销指定设备访问，其他设备不受影响。设备端兑换凭据、长期 Key 和敏感参数不泄露到日志、分享链接或调用历史；展示给人的短码按配对流程限时使用。
• 新增的配对与管理能力提供 API/tb/Dashboard 一致的状态和权限语义；本机安装和资源授权仍由设备侧执行。实现通过 pnpm verify 和 pnpm turbo run build，并留下真实设备 dogfooding 证据。

分工与参考

#129 负责工作区、通用入口和视觉交互；本 issue 负责完整设备接入与授权体验。#108 的结构化设备操作、#112 的 agent-safe profile 和已完成 #117 的 mailbox 是可复用或相关工作，均不能替代快速配对与能力配置的交付。

可分阶段实现“快速配对与自动凭证”“按用途配置与首次任务”“长期使用和恢复”，但每阶段要检验整体路径是否仍把内部配置负担交给用户。

设计参考：

• RFC 8628：设备授权：为输入受限设备定义另一设备上确认授权的流程；短码与二维码可以呈现同一授权会话，扫码后仍需辨认并确认目标。它可供选型参考，不代表本仓库已有 OAuth 授权服务器或必须照搬完整身份体系。
• GitHub CLI 登录：浏览器登录流程是 CLI 的默认认证入口，可参考终端与浏览器的交接方式。
• Apple Onboarding 指南：将非必要设置后置、在需要时引导授权，可用于审查首轮配置的认知负担。