device-center 0.2.0-beta.2 → 0.2.0-beta.4

package/CONTRIBUTING.md

@@ -7,3 +7,5 @@ Use Node.js 24, `npm ci --ignore-scripts`, `npm run dev`, `npm run check`, and `
 Preserve the compact sidebar, optional MCP setup, truthful device states, and separate memory/disk observations. The local process represents its machine; a container cannot claim its host. SSH configuration discovery must not execute commands or read keys, and association must not imply connectivity or task authority. Do not restore sample projects, hosted quota displays or simulated cloud synchronization.
 
 Never add real secrets to prompts, packages, fixture data or logs. SSH observation is an explicit owner action using a fixed script, isolated configuration, existing authentication and strict host trust; GET and MCP must never trigger connections. Tests inject subprocess results and do not contact real hosts. Resource enrollment, Agent installation, network discovery, tunnels, cloud deployment and remote tasks require separately scoped implementation and review. Do not run service installation or Docker deployment merely to validate a UI change. Keep user data and unrelated services intact.
+
+Pull requests run the existing checks and tests on GitHub-hosted macOS and Ubuntu. Main pushes additionally validate and build on the repository's dedicated MBM-24 and MBP-16 runners. These runners reject PR jobs and hold no production credentials. After the complete main CI succeeds, a separate GitHub-hosted production job builds the exact SHA, deploys through a restricted receiver, verifies public bytes and login protection, and confirms health or restores the previous code. See [delivery configuration](docs/development/delivery-profile.md) for the authorized channel, activation evidence, credentials boundary and recovery. npm publication remains a separate release.

package/Dockerfile

@@ -1,9 +1,10 @@
 # Optional local-only control plane, not a host/resource Agent.
 FROM node:24-bookworm-slim
 WORKDIR /app
-COPY --chown=node:node package.json npm-shrinkwrap.json index.html login.html ./
+COPY --chown=node:node package.json npm-shrinkwrap.json index.html login.html start.html favicon.svg ./
 COPY --chown=node:node server ./server
 COPY --chown=node:node src ./src
+COPY --chown=node:node docs/agent-install.md docs/friend-trial.md docs/remote-access.md docs/device-profiles.md docs/troubleshooting.md ./docs/
 RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund && mkdir -p /app/data && chown node:node /app/data
 USER node
 ENV PORT=5173 DEVICE_CENTER_RUNTIME=container DEVICE_CENTER_DB_PATH=/app/data/device-center.sqlite

package/README.md

@@ -1,13 +1,32 @@
 # Device Center
 
+界面与 Agent 安装说明支持简中、繁中、英、日、韩、西、法、德、巴西葡语。页面顶部可切换，也可分享 `/start?lang=en`、`/start?lang=ja`。详见[多语言说明](docs/i18n.md)。
+
 让主力电脑上的智能体，使用自己的闲置设备。MIT · Node.js 24 · macOS / Linux · beta。
 
 一个本机连接器，加一个可选的云端控制面。真实本机内存、磁盘分别展示；已有 SSH 配置可一键关联并执行固定只读检查；设备 Agent 可通过域名绑定账号，主动回报状态。指定日志经设备主人单独授权后，以双向 TLS 1.3 直连或密文中转读取。没有默认示例设备或虚构在线状态。
 
 ## 快速使用
 
+### 简化接入（beta.4 开发候选，尚未发布）
+
+一页指南明确提供 **交给 Agent／手动安装**，目标设备不需要先安装 AI Agent：
+
+```text
+复制安装说明给 Agent（或复制终端脚本）
+    → 自动安装并打开本次绑定页
+    → 本人登录、核对指纹、批准一次
+    → 自动确认资源回报，Agent 继续配置 MCP
+```
+
+有浏览器的设备无需搬运配对码，也不需要回 Agent 回复“已批准”。无浏览器服务器可选手动安装：目标终端运行脚本，在另一台电脑登录控制面，填入终端码、核对指纹并批准。全新安装脚本会配置用户级后台服务；已有安装时停止并保留设置。AI Agent／MCP 仅是管理电脑的可选能力。身份私钥留在设备；安装绑定只允许资源回报，远程日志仍需另外授权。[手动步骤与排查](docs/agent-install.md#手动安装目标设备没有-ai-agent)
+
+当前公开 npm 仍为 **0.2.0-beta.3**；下面的已发布命令保持可用。新流程需要新版控制面与 CLI 一起交付。
+
 希望交给本机 Agent 安装时，按[Agent 安装指南](docs/agent-install.md)选择本机、官方托管或已有自建服务。“交给 Agent 安装”可直接复制完整说明；登录和设备绑定仍由用户核对。朋友试用从[一页指南](https://devices.owenshen.top/start)开始，无需先登录。
 
+0.2.0-beta.3 增加九语言界面与安装说明，语言菜单支持键盘、窄屏与输入保留。长文档和 CLI 仍以中文为主。
+
 0.2.0-beta.2 增加设备命名、类型、用途、标签、手动服务清单及“采集一次”，见[设备说明与手动采集](docs/device-profiles.md)。旧 Driver 需升级后才能响应云端手动采集；服务与应用仍由用户手动登记。
 
 第一次使用可按 [新用户上手教程](docs/quick-start.md) 完成安装、设备配对和指定日志授权；[验收记录](docs/user-acceptance.md)列出已验证项目与限制。
@@ -15,7 +34,7 @@
 只用本机，不注册账号：
 
 ```sh
-npx --yes device-center@0.2.0-beta.2 start
+npx --yes device-center@0.2.0-beta.3 start
 ```
 
 打开 `http://127.0.0.1:5174`，将 `/mcp` 添加到本机智能体。侧栏“开始使用”按管理电脑 → 智能体 → 设备引导；导入 SSH 后检查一次连通性。没有可用 Agent/SSH 的设备保持未知；资源快照过期显示“待刷新”，不代表密钥过期。列表刷新不主动连接 SSH。
@@ -23,8 +42,8 @@ npx --yes device-center@0.2.0-beta.2 start
 需要在外查看设备、使用日志中转：
 
 ```sh
-npx --yes device-center@0.2.0-beta.2 plan
-npx --yes device-center@0.2.0-beta.2 connect --confirm
+npx --yes device-center@0.2.0-beta.3 plan
+npx --yes device-center@0.2.0-beta.3 connect --confirm
 # 自建控制面可指定 --cloud https://devices.example.com
 ```
 
@@ -66,4 +85,4 @@ npm run verify:package
 
 需要已有受信任 App Services 共享账号服务与同父域会话；不是通用第三方 OAuth。个人部署可选 personal + ownerEmail。旧个人数据切多用户前按[迁移与回退说明](docs/hosted-access.md)核验原所有者映射；不能只切回旧代码而保留多用户数据库。
 
-当前没有密钥托管、安装时自动联网或远程 shell。安全边界与披露方式见 [SECURITY](SECURITY.md)。npm 包公开不自动改变 GitHub 仓库可见性；本次发布是可追溯工作区快照，不是 main CI 构建。
+当前没有密钥托管、安装时自动联网或远程 shell。安全边界与披露方式见 [SECURITY](SECURITY.md)。npm 包公开不自动改变 GitHub 仓库可见性；npm 发布独立于 Web 部署。主线验证、自动部署和失败恢复的机制及启用证据见[持续交付](docs/development/delivery-profile.md)。

package/bin/device-center.mjs

@@ -34,8 +34,9 @@ export function helpText() {
 
 device-center start [--port 5174]             启动本机面板与只读 MCP
 device-center plan --cloud https://你的域名    预览回报范围，不生成身份或联网
-device-center connect --cloud https://你的域名 --confirm
-                                            在本机生成身份，申请配对后等待你核对批准
+device-center connect --cloud https://你的域名 --browser --confirm
+                                            打开浏览器核对批准一次，自动等待与核验首次回报
+                                            无浏览器服务器：去掉 --browser，在本机终端手动配对
 device-center status                         查看已有绑定，不显示私钥
 device-center run [--port 5174]               前台恢复已绑定 Driver
 device-center disconnect --confirm           通知云端撤销，保留本机身份

package/docs/agent-install.md

@@ -1,8 +1,8 @@
-# 让 Agent 安装 Device Center
+# 安装 Device Center：Agent 或手动
 
-用户选择模式后，把完整安装说明交给**正在目标电脑上运行、具备本机安装能力的 Agent**。网页只复制说明，不会远程替浏览器所在电脑安装软件。
+目标设备只需要 Device Center Driver，不要求已经安装 AI Agent。一页指南提供 **交给 Agent** 和 **手动安装** 两个入口。网页只复制内容，安装发生在你执行脚本的目标设备上。
 
-`device-center@0.2.0-beta.2` 提供“交给 Agent 安装”、设备说明与手动采集。新用户可在[一页试用指南](https://devices.owenshen.top/start)免登录选择方式并复制完整说明。
+**beta.4 是本地开发候选，尚未发布到 npm。** 当前公开版为 `device-center@0.2.0-beta.3`。新流程需要控制面与 CLI 一起升级；下列 `--browser` 指新版源码能力，不应交给旧客户端执行。
 
 ## 用户只需要选择一种方式
 
@@ -14,6 +14,34 @@
 
 托管的是面板、设备登记与中转服务。设备身份私钥和指定日志授权仍在设备上，不上传私钥，不让服务商代为持有设备登录能力。
 
+## 手动安装：目标设备没有 AI Agent
+
+新版指南选择使用方式后，点 **手动安装**，复制 **终端安装脚本**。主面板的“安装 Device Center”中也有手动指南入口，会带入当前选择的控制面。
+
+复制按钮下方的三张窗口示意按选择切换：**目标电脑的终端／Agent 对话 → 浏览器绑定（本机模式为安装检查）→ 设备列表**。点“看下一步”可预看后续动作；切图不会执行安装、批准绑定或表示操作成功。无浏览器模式会画出“目标终端 → 另一台电脑的浏览器”；本机面板地址则明确要求在刚安装的那台电脑打开。
+
+1. **准备环境**：macOS / Linux、Node.js 24+ 和 npm。缺少 Node.js 时先从官方来源安装；Windows 原生 Driver 暂未支持。脚本只支持全新安装，发现已有 CLI 会停止，不覆盖身份或配置。
+2. **在目标设备执行**：Mac 打开“终端”；Linux 使用终端，或你已经建立的 SSH 会话。粘贴整块脚本并执行。不需要把它发给 AI Agent，也不会替你建立 SSH 连接。
+3. **本机使用**：不登录、不申请云端绑定。安装结束后在这台设备打开 `http://127.0.0.1:5174` 查看资源。
+4. **托管／自建接入**：复制前选择目标设备有没有浏览器：
+
+   | 目标设备 | 接下来的操作 |
+   | --- | --- |
+   | 有浏览器 | 脚本执行 `connect --browser --confirm`，自动打开本次申请。登录自己的账号，对照终端完整公钥指纹并批准一次。程序自动等待结果并核验首次回报。 |
+   | 无浏览器／服务器 | 脚本执行不带 `--browser` 的 `connect --confirm`。保持终端打开，在另一台有浏览器的电脑登录同一控制面，点“连接我的电脑”，输入终端的五分钟配对码，对照完整公钥指纹并批准。设备自动继续；云端列表首次收到数据后显示在线。 |
+
+5. **查看结果**：后台用户服务应为运行状态，云端要有新的实际回报时间；“已绑定”与“已收到资源回报”是两件事。无需回到 Agent 回复“已批准”。不要重复绑定来解决未回报。
+
+AI Agent 和 MCP 是管理端的可选能力：只有以后想让某台电脑上的 AI Agent 使用 Device Center 时，才在**那台管理电脑**配置本机 MCP。目标设备没有 AI Agent，照样可以常驻回报并作为另行授权的日志读取目标。服务器的 `127.0.0.1` 指服务器自己，不能作为另一台电脑的远程 MCP 地址。
+
+### 手动模式遇到问题
+
+- **已有安装**：脚本停止是保留现有设置，不是安装成功。使用已有 CLI 的 `status`、`service status --port 5174` 核对版本、绑定与服务，再明确选择复用或升级。不要直接重装或解绑。
+- **没有浏览器／打开失败**：预先选择“无浏览器／服务器”。若已经运行过浏览器模式且打开失败，可以在目标终端重新运行同一条 `connect` 命令并去掉 `--browser`，以新申请为准。不要把配对码贴进 AI Agent 对话或共享截图。
+- **端口冲突**：保留其他程序，选明确可用的本机端口，并同步脚本里的服务、配对和面板地址。
+- **后台服务失败**：macOS 需要登录用户的 launchd；Linux 需要 `systemd --user`。脚本不会自动改系统权限或启用 linger。无人登录也要常驻的服务器，需管理员单独配置合适的服务生命周期；不满足时可按下面的前台方式使用。
+- **绑定后未回报**：检查 Driver 是否运行、设备是否休眠、到控制面域名的 HTTPS 出站连通性与系统时间。首次回报可能需约 30 秒；在面板核对真实时间，不把仅有本地绑定当作在线。不需要对公网开放设备端口。
+
 ## Agent 执行顺序
 
 只有用户明确要求在当前电脑安装并选择模式后，才能执行以下步骤。阅读本文本身不授予安装、配对或访问其他设备的权限。
@@ -29,7 +57,7 @@
 全新安装可以使用：
 
 ```sh
-npm install --global --prefix "$HOME/.local" --ignore-scripts device-center@0.2.0-beta.2
+npm install --global --prefix "$HOME/.local" --ignore-scripts device-center@0.2.0-beta.4
 "$HOME/.local/bin/device-center" --version
 ```
 
@@ -61,12 +89,18 @@ macOS 使用当前登录用户的 launchd；Linux 需要可用的 `systemd --use
 
 ```sh
 "$HOME/.local/bin/device-center" plan --cloud 'https://devices.owenshen.top' --port 5174
-"$HOME/.local/bin/device-center" connect --cloud 'https://devices.owenshen.top' --port 5174 --confirm
+"$HOME/.local/bin/device-center" connect --cloud 'https://devices.owenshen.top' --port 5174 --browser --confirm
 ```
 
 自建模式替换为用户明确提供的 HTTPS 控制面域名，不携带路径、账号或参数。不能自动覆盖其他控制面的绑定。
 
-用户在该控制面登录自己的账号，核对本机终端的完整公钥指纹，再手动批准新增设备。Agent 不代为批准，不读取密码、cookie 或私钥；配对码留在本机终端，不贴进智能体对话、脚本或链接。若 Agent 的执行工具会把终端配对码自动记录进对话，只把这一步交给用户在本机终端执行，Agent 继续其他检查。
+Agent 直接执行带 `--browser` 的命令并保持进程。命令自动打开本机默认浏览器，申请自动带入；未登录时先登录，之后自动回到同一申请。用户只需核对命令输出的完整公钥指纹，并在浏览器批准一次。Agent 不代为批准，不读取密码、cookie、私钥或带凭据的浏览器链接。
+
+浏览器模式不向 stdout/stderr 输出配对码或临时登记票据。票据仅通过系统浏览器打开，放在 URL fragment 中，页面立即移除，暂存在同标签页的 sessionStorage 供登录跳转使用；五分钟有效、一次批准，服务端仅存摘要。不要复制、分享或记录该链接。票据不进入提示词、安装脚本或压缩包。
+
+用户批准后，命令自动继续并等待首次资源回报，返回 `firstReport.verified`。**不要让用户去终端重新执行，也不要要求用户回复“已批准”。** Agent 持续观察自己启动的进程，`firstReport.verified=true` 后继续 MCP 配置；前台模式进程会继续运行，不必等它退出。`false` 表示绑定成功但回报未证实，检查服务、网络与时钟，不要重新绑定。
+
+仅当目标机没有浏览器、打开失败或系统阻止打开时，再让用户在目标机终端运行去掉 `--browser` 的同一条 connect 命令。配对码只留在本机终端与登录后的面板，不进入 Agent 对话。旧控制面需要先升级；命令不会自动降级并打印凭据。
 
 前台 `connect` 在批准后启动 Driver；已经运行的用户服务会读取绑定并开始回报。不能仅凭 `configured=true` 宣称云端已收到数据，要核对真实回报和时间。
 
@@ -98,7 +132,7 @@ http://127.0.0.1:5174/mcp
 
 默认不导入或连接 SSH 主机、不分享 SSH、不扫描局域网、不开放设备入站端口、不配置隧道、不授予日志或命令权限。安装与绑定不等于远程操作授权。
 
-## 给 Agent 的公开文档入口
+## 公开文档入口
 
 当前源码服务提供固定路径 `GET /install/agent.md`，仅返回本文，不需要登录，不含账号、身份或设备清单。官方入口为 https://devices.owenshen.top/install/agent.md；自建服务使用自己的域名与相同路径。
 

package/docs/driver-binding.md

@@ -5,6 +5,16 @@
 
 ## 三步接入
 
+### beta.4 简化接入候选（尚未发布）
+
+新版一页指南并列提供 Agent 说明和手动安装脚本。目标设备有浏览器时共用 `connect --browser --confirm`：自动打开 `/pair`，本人登录并核对完整公钥指纹、批准一次；CLI 自动检测结果并核验首次回报。无需手动搬运配对码，也不用回 Agent 回复“已批准”。手动模式还可选“无浏览器／服务器”，脚本生成不带 `--browser` 的命令，通过另一台电脑完成下面的填码流程。目标设备不需要 AI Agent 或 MCP。已有安装脚本停止保留设置；Agent 可核对后复用已有绑定，不重复登记。
+
+浏览器模式使用独立的 256 位随机登记票据，五分钟有效，服务端只存 SHA256 摘要。CLI 不输出它，仅通过默认浏览器打开 `/pair#ticket=…&expires=…`。fragment 不发送到 HTTP 服务器或 Referer；页面立即移除，仅在同标签页 sessionStorage 暂存以跨过登录，批准、取消、过期时移除。不把它放进提示词、安装脚本或归档；它不是账号登录或远程任务权限。拥有票据仍需登录并本人核对批准，设备领取结果仍必须证明持有私钥。不要分享绑定链接或批准陌生请求。
+
+自动打开失败时明确转手动，不自动输出凭据。自建控制面必须升级后才支持浏览器交接。`firstReport.verified=false` 会明确区分“已绑定”和“首次回报未确认”，不应重新绑定。
+
+### 手动兼容流程
+
 1. 登录自己的 HTTPS 控制面，点 **连接我的电脑**。下载 Driver 源码包，在管理电脑解压到长期保留的目录；需要 Node.js 24，无第三方运行依赖。已有最新版源码仓库可直接使用。
 2. 在该目录的终端运行面板复制的命令。下面是占位域名，请替换为自己的 HTTPS 域名。npm 分发候选见 [npm 使用与发布说明](npm.md)：
 
@@ -66,4 +76,4 @@ npm run service -- install --confirm --port 5174
 
 ## 账号归属与候选版本
 
-当前源码 beta.2 增加显式多用户账号隔离，未发布或部署；npm beta.1 客户端的机器配对/签名协议保持兼容。个人模式仍为默认；多用户的面板批准需同时提交码与完整指纹，归属只取服务核验的账号，不接受客户端 tenantId。历史个人记录不自动转移；多账号数据不能交给旧的无隔离服务器读取。详见[托管接入、迁移与回退](hosted-access.md)。
+显式多用户隔离已在 beta.3 上线；beta.4 浏览器交接仍是本地开发候选，旧客户端的手动配对与签名协议保持兼容。个人模式仍为默认；多用户批准需同时提交配对码或短时浏览器票据，以及完整指纹，归属只取服务核验的账号，不接受客户端 tenantId。历史个人记录不自动转移；多账号数据不能交给旧的无隔离服务器读取。详见[托管接入、迁移与回退](hosted-access.md)。

package/docs/friend-trial.md

@@ -1,6 +1,6 @@
 # Device Center · 朋友试用指南
 
-让本机 Agent 看见自己的电脑与闲置设备：真实内存、磁盘、设备用途，以及单独授权的指定日志。当前为 `0.2.0-beta.2` 公开试用版。
+让本机 Agent 看见自己的电脑与闲置设备：真实内存、磁盘、设备用途，以及单独授权的指定日志。当前为 `0.2.0-beta.3` 公开试用版。
 
 **入口：https://devices.owenshen.top/start**。支持 macOS / Linux，需要 Node.js 24+；Windows 原生版尚未支持。
 
@@ -14,7 +14,7 @@
 
 Agent 按说明检查已有配置、固定版本安装、设置用户级后台服务、配置 MCP 并核验结果。已有配置冲突时解释并让你选择，不自动覆盖。系统授权或当前 Agent 无法配置 MCP 时，会请你完成对应一步。
 
-不使用 Agent 时，可在全新环境运行 `npx --yes device-center@0.2.0-beta.2 start` 体验本机面板；这是前台方式，终端关闭后停止。长期使用按[完整安装指南](https://devices.owenshen.top/install/agent.md)固定安装。
+不使用 Agent 时，可在全新环境运行 `npx --yes device-center@0.2.0-beta.3 start` 体验本机面板；这是前台方式，终端关闭后停止。长期使用按[完整安装指南](https://devices.owenshen.top/install/agent.md)固定安装。
 
 ## 2. 托管模式才需要登录绑定
 

package/docs/hosted-access.md

@@ -1,6 +1,6 @@
 # 本机、官方与自建接入
 
-本版本 0.2.0-beta.2 使用同一 CLI 支持官方与自建 HTTPS 控制面；每个账号独立管理自己的设备。安装不自动接入，connect --confirm 默认申请官方服务，用户登录并核对批准后才绑定。
+本版本 0.2.0-beta.3 使用同一 CLI 支持官方与自建 HTTPS 控制面；每个账号独立管理自己的设备。安装不自动接入，connect --confirm 默认申请官方服务，用户登录并核对批准后才绑定。
 
 ## 用户流程
 

package/docs/i18n.md

@@ -0,0 +1,32 @@
+# 多语言界面
+
+支持简体中文（`zh-CN`）、繁體中文（`zh-TW`）、English（`en`）、日本語（`ja`）、한국어（`ko`）、Español（`es`）、Français（`fr`）、Deutsch（`de`）、Português do Brasil（`pt-BR`）。繁中采用台湾常用术语，葡语采用巴西用法。
+
+## 使用
+
+页面顶部点击地球图标与当前语言，展开双列菜单；各语言使用自己的原名，当前语言显示勾选。登录页和弹窗复用同一组件。选择后自动收起，点击外部或按 Esc 可关闭；支持方向键、Home / End、回车和 Tab。窄屏下菜单位置保持在视口内。
+
+切换不刷新页面，保留设备说明、搜索与安装地址等当前输入，不触发配对、采集或授权。
+
+首次按浏览器语言选择；之后记住当前浏览器、当前站点的选择。优先级是 URL 的 `lang` → 本机保存的偏好 → 浏览器语言 → 英文。支持地区变体，如 `en-US`、`ja-JP`、`zh-Hant-HK`。本机存储不可用时仍可切换，并通过 URL 保持当前语言。
+
+可以分享指定语言的页面，例如 `/start?lang=en` 或 `/start?lang=ja`。内部导航、登录重定向与退出登录会带上所选语言。
+
+## 覆盖与边界
+
+- 公开试用指南、登录页、设备面板、设备说明、状态与采集提示、SSH 导入与连接计划、配对和日志授权说明。
+- 复制给 Agent 的完整安装说明按所选语言生成；具体命令、版本、域名与参数保持原样。复制不会安装软件。
+- 设备名称、用途、标签、服务、SSH 别名、路径、指纹等用户数据不翻译。状态代码、API、认证、有效期与权限契约不变。
+- 浏览器内使用静态词典，不发送设备数据到外部翻译服务。已有服务端固定诊断仅通过明确的文案映射翻译；未知诊断原样显示。
+- Markdown 长文档与 CLI 输出目前以简体中文为主。外语页面的长文档链接注明中文，不能将界面翻译等同于所有文档与 CLI 已本地化。
+- 九种语言已做目录完整性与交互检查；公开推广前仍欢迎母语使用者改进术语和语气。
+
+## 维护
+
+`src/messages.js` 是词典真源；各语言必须拥有同一组键、相同的 `{placeholder}` 参数，不能把旧键重新分配给不同语义。`panel.N` 是现有面板的稳定文案键；新增文案优先用语义键，如 `count.bound`。
+
+`src/i18n.js` 负责语言归一化、选择与安全插值。文本使用 `t`，HTML 模板使用会转义参数的 `h`。静态页面只翻译显式 `data-i18n` 标记；禁止遍历用户文本或对整个 DOM 做替换。布局选择器使用稳定 class，不能依赖翻译后的 aria-label。
+
+`src/install-prompt.js` 负责说明组装，`src/onboarding.js` 保持命令和验证规则。翻译安全说明时保留本人核对完整指纹、配对码不进入 prompt、私钥留在设备、操作单独授权等约束。
+
+运行 `npm run check`、`npm test`。`tests/i18n.test.mjs` 覆盖词典、占位符、引用、地区语言归一化、安装模式与命令不变性。新增公共脚本时须核对云端静态白名单、未登录 API 隔离和安装包清单。

package/docs/npm.md

@@ -1,16 +1,18 @@
 # npm / npx 分发
 
-MIT，Node.js 24，macOS/Linux。当前版本 `0.2.0-beta.2`，使用 npm `beta` 渠道；是否上架以公开 registry 为准。
+MIT，Node.js 24，macOS/Linux。当前版本 `0.2.0-beta.3`，使用 npm `beta` 渠道；是否上架以公开 registry 为准。
+
+本地 `0.2.0-beta.4` 候选新增 `connect --browser --confirm` 与普通终端安装脚本，尚未发布。必须先发布新 CLI，再将指南切到对应版本并部署新版控制面；只更新网页不能让已安装的旧 CLI 获得新参数。新控制面继续支持旧版手动填码。回退网页与旧 CLI 不会删除既有身份，新增加的登记摘要列可保留。以下仍为当前已发布版命令。
 
 ```sh
-npx --yes device-center@0.2.0-beta.2 --help
-npx --yes device-center@0.2.0-beta.2 plan
+npx --yes device-center@0.2.0-beta.3 --help
+npx --yes device-center@0.2.0-beta.3 plan
 # 主动接入默认官方服务，执行后在终端与面板之间核对配对
-npx --yes device-center@0.2.0-beta.2 connect --confirm
+npx --yes device-center@0.2.0-beta.3 connect --confirm
 # 自建服务
-npx --yes device-center@0.2.0-beta.2 connect --cloud https://你的控制面域名 --confirm
+npx --yes device-center@0.2.0-beta.3 connect --cloud https://你的控制面域名 --confirm
 # 仅本机，无账号要求
-npx --yes device-center@0.2.0-beta.2 start
+npx --yes device-center@0.2.0-beta.3 start
 ```
 
 安装与无参/help/version/plan 不生成身份，不配对，不自动启动后台进程。复制命令不含凭据。只有 connect --confirm 才生成本机身份并申请绑定；默认官方地址不会自动批准，用户需登录自己的账号。SSH 缓存分享须 --share-ssh 与面板再次批准。
@@ -18,7 +20,7 @@ npx --yes device-center@0.2.0-beta.2 start
 面板和本机 MCP：`http://127.0.0.1:5174/`、`/mcp`。常驻先固定安装：
 
 ```sh
-npm install -g device-center@0.2.0-beta.2
+npm install -g device-center@0.2.0-beta.3
 device-center service plan --port 5174
 # 自行停止同端口前台进程，再主动安装
 device-center service install --port 5174 --confirm

package/docs/onboarding.md

@@ -13,6 +13,8 @@
 
 ## 服务器 / Docker 部署后的接入
 
+beta.4 本地候选提供并列的 Agent／手动安装入口，目标设备不要求 AI Agent 或 MCP。手动安装可选有浏览器自动交接，或无浏览器终端填码。有浏览器时申请自动带入，本人登录、核对指纹并批准一次；CLI 自动等待与验证首次回报，不要求用户回 Agent 回复“已批准”。无浏览器服务器在另一台电脑完成下列手动流程。此候选尚未发布，当前公开 beta.3 的行为仍如下。
+
 控制面与管理电脑可能是两台机器。当前服务只读取自己所在机器的配置；服务器配置不能代替用户电脑的配置，Docker 也不会取得宿主 SSH 权限。
 
 当前支持 macOS/Linux 管理 Driver，需要 Node.js 24，操作收敛为：
@@ -32,7 +34,7 @@ Driver 主动建立获准的安全出站连接。短时一次性登记凭据应
 | 目标设备条件 | 用户最少操作 | 结果条件 |
 | --- | --- | --- |
 | 管理电脑已有可用 SSH 配置 | 一键导入引用 | 导入后自动检查一次，取得真实资源后才显示近期在线与资源 |
-| 目标设备已有智能体 | 复制安装指导，交给目标机智能体；确认安装与绑定 | 0.2.0-beta.2 可复制完整安装说明，本机生成身份并核对配对与真实回报；签名安装器待实现 |
+| 目标设备已有智能体 | 复制安装指导，交给目标机智能体；确认安装与绑定 | 0.2.0-beta.3 可复制完整安装说明，本机生成身份并核对配对与真实回报；签名安装器待实现 |
 | 目标设备没有智能体 | 下载对应平台的验签安装包，在目标机运行并批准绑定 | 与智能体辅助方式使用同一接入协议；待实现 |
 | 不能安装 Agent，也没有可用 SSH | 明示缺少接入条件 | 保持未知，不伪装接通 |
 

package/docs/remote-access.md

@@ -1,13 +1,13 @@
 # 远程日志：明确授权后使用
 
-本版本 0.2.0-beta.2 支持 macOS / Linux、Node.js 24。两台设备主动连接同一 HTTPS 控制面，默认使用 `https://devices.owenshen.top`；可用 `--cloud https://你的域名` 替换。安装或查看帮助不会产生身份、配对或运行远程操作。
+本版本 0.2.0-beta.3 支持 macOS / Linux、Node.js 24。两台设备主动连接同一 HTTPS 控制面，默认使用 `https://devices.owenshen.top`；可用 `--cloud https://你的域名` 替换。安装或查看帮助不会产生身份、配对或运行远程操作。
 
 ## 最短流程
 
 在管理电脑和目标设备分别运行：
 
 ```sh
-npm install -g device-center@0.2.0-beta.2
+npm install -g device-center@0.2.0-beta.3
 device-center connect --confirm
 ```
 

package/docs/roadmap.md

@@ -14,6 +14,12 @@
 - “交给 Agent 安装”：本机、官方托管、已有自建服务；固定版本、用户级后台与 MCP 步骤。
 - 免登录的一页试用指南。登录、完整指纹核对和设备批准仍由用户完成。
 
+## 0.2.0-beta.3
+
+- 简中、繁中、英、日、韩、西、法、德、巴葡九种语言，覆盖指南、登录、面板与 Agent 安装说明。
+- 统一语言菜单、浏览器偏好和分享链接，切换保留未保存输入；命令与设备数据保持原样。
+- 长文档和 CLI 仍以中文为主，翻译尚待母语者校对。
+
 ## 后续候选
 
 1. 验证各平台真实常驻、升级和恢复；减少 Node 与终端依赖。

package/docs/security-and-sync.md

@@ -6,6 +6,8 @@
 
 App Services 账号由固定 HTTPS `/v1/me` 核验，不解码自报 JWT 作为信任。稳定 issuer/subject 摘要派生租户，所有查询和撤销按服务端已核验租户限定。上游不可用时拒绝；密码认证只支持个人模式。旧个人归属与回退见[托管接入](hosted-access.md)。
 
+云端允许从个人站或其它网站打开 `/`、`/index.html`、`/login`、`/start` 和 `/start.html`，仅限浏览器顶层 GET 页面导航（`Sec-Fetch-Mode: navigate`、`Sec-Fetch-Dest: document`）。面板仍需登录，匿名根页面跳转登录；API、脚本、iframe 和写请求不适用此例外。同父域 `same-site` 也不等于 `same-origin`，不能用于跨来源操作设备。Host、HTTPS 代理标记与显式 Origin 校验始终保留，本机模式不变。
+
 远程日志使用 Node/OpenSSL TLS 1.3 双向认证，两端固定经核对的证书/指纹。目标本机 grant 只允许指定管理身份、标签、规范化文件路径和截止时间；每次最多64KiB。禁止任意命令、任意路径、符号链接/多硬链接/非普通文件。直连和云中转都核验当前云端成员，撤销后拒绝新操作。
 
 云端中转只见密文与账号/设备/流量元数据。配额每日持久计数，队列、帧、会话、速率和并发均有界。两端本机审计不保存日志内容；超容量拒绝，不自动清理。详见[授权与额度](remote-access.md)。

package/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#0c0c0e"/>
+  <path d="M12 42V12h30v30H12Zm10 10h30V22H22v30Z" fill="none" stroke="#ff8254" stroke-width="4" stroke-linejoin="round"/>
+</svg>

package/index.html

@@ -6,6 +6,8 @@
     <meta name="theme-color" content="#f4f5f1" />
     <meta name="description" content="Device Center · 云端控制面与设备 Agent 接入原型" />
     <link rel="stylesheet" href="/src/styles.css" />
+    <link rel="stylesheet" href="/src/i18n.css" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <title>Device Center · 设备控制面</title>
   </head>
   <body>

package/login.html

@@ -1,5 +1,5 @@
 <!doctype html>
 <html lang="zh-CN">
-<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>登录 · Device Center</title><link rel="stylesheet" href="/src/login.css"></head>
-<body><main><div class="mark">DC</div><h1>Device Center</h1><p>登录你的设备控制面</p><p id="loading" role="status">正在读取登录方式…</p><form id="login" hidden><label>用户名<input name="username" autocomplete="username" required maxlength="64"></label><label>密码<input name="password" type="password" autocomplete="current-password" required maxlength="256"></label><button type="submit">登录</button><p id="message" role="alert"></p></form><section id="unified" hidden><p>使用 App Services／个人站的统一账号。</p><a id="unified-login" class="login-link" target="_blank" rel="noopener noreferrer">使用统一账号登录 ↗</a><p class="help">在新页面用邮箱或 Google 完成登录，回到这里会自动进入设备面板。</p><button id="continue-login" type="button">我已登录，继续</button><p id="unified-message" role="status"></p></section><p class="install-help">还未安装？<a href="/start" target="_blank" rel="noopener noreferrer">查看一页试用指南 ↗</a><br><span>本机使用无需账号；官方托管需登录并核对绑定。</span></p><small id="access-notes">账号登录 · HTTPS 保护</small></main><script type="module" src="/src/login.js"></script></body>
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="icon" href="/favicon.svg" type="image/svg+xml"><title data-i18n="login.title">登录 · Device Center</title><link rel="stylesheet" href="/src/login.css"><link rel="stylesheet" href="/src/i18n.css"></head>
+<body class="login-page"><main><div class="language-picker" data-language-picker></div><div class="mark">DC</div><h1>Device Center</h1><p data-i18n="login.subtitle">登录你的设备控制面</p><p id="loading" role="status" data-i18n="login.loading">正在读取登录方式…</p><form id="login" hidden><label><span data-i18n="login.username">用户名</span><input name="username" autocomplete="username" required maxlength="64"></label><label><span data-i18n="login.password">密码</span><input name="password" type="password" autocomplete="current-password" required maxlength="256"></label><button type="submit" data-i18n="login.submit">登录</button><p id="message" role="alert"></p></form><section id="unified" hidden><p data-i18n="login.unified">使用 App Services／个人站的统一账号。</p><a id="unified-login" class="login-link" target="_blank" rel="noopener noreferrer" data-i18n="login.link">使用统一账号登录 ↗</a><p class="help" data-i18n="login.help">在新页面用邮箱或 Google 完成登录，回到这里会自动进入设备面板。</p><button id="continue-login" type="button" data-i18n="login.continue">我已登录，继续</button><p id="unified-message" role="status"></p></section><p class="install-help"><span data-i18n="login.notInstalled">还未安装？</span><a href="/start" target="_blank" rel="noopener noreferrer" data-language-link data-i18n="login.guide">查看一页试用指南 ↗</a><br><span data-i18n="login.installHint">本机使用无需账号；官方托管需登录并核对绑定。</span></p><small id="access-notes" data-i18n="login.multi">账号设备隔离 · HTTPS 保护</small></main><script type="module" src="/src/login.js"></script></body>
 </html>

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "device-center",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "device-center",
-      "version": "0.2.0-beta.2",
+      "version": "0.2.0-beta.4",
       "license": "MIT",
       "dependencies": {
         "@peculiar/x509": "2.1.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "device-center",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.4",
   "license": "MIT",
   "type": "module",
   "description": "Local device connector with account-bound pairing, TLS encrypted relay and explicitly authorized log access",
@@ -37,7 +37,9 @@
     "docs/remote-access.md",
     "npm-shrinkwrap.json",
     "start.html",
-    "docs/friend-trial.md"
+    "favicon.svg",
+    "docs/friend-trial.md",
+    "docs/i18n.md"
   ],
   "publishConfig": {
     "access": "public",

package/scripts/driver.mjs

@@ -8,21 +8,23 @@ import { servicePlan } from './service.mjs';
 import { cloudOrigin, publicIdentity, signedRequest } from '../server/drivers/driverProtocol.mjs';
 import { cloudPost, defaultLinkFile, readLink, writeLink, linkSummary, ensurePrivateDirectory } from '../server/drivers/cloudLink.mjs';
 import { issueCertificate } from '../server/drivers/certificates.mjs';
+import { pairingBrowserUrl, openPairingBrowser, waitForFirstReport } from '../server/drivers/browserPairing.mjs';
 
-const usage = 'npm run driver -- plan|connect|run|status|disconnect --cloud https://你的域名 [--share-ssh] [--port 5174] [--confirm]';
+const usage = 'npm run driver -- plan|connect|run|status|disconnect --cloud https://你的域名 [--browser] [--share-ssh] [--port 5174] [--confirm]';
 export function driverPlan(argv = []) {
   const command = argv[0] ?? 'plan';
-  let origin = 'https://devices.owenshen.top', port = 5174, confirm = false, shareSsh = false;
+  let origin = 'https://devices.owenshen.top', port = 5174, confirm = false, shareSsh = false, browser = false;
   for (let i = 1; i < argv.length; i++) {
     if (argv[i] === '--cloud' && argv[i+1]) origin = argv[++i];
     else if (argv[i] === '--port' && argv[i+1]) port = Number(argv[++i]);
     else if (argv[i] === '--confirm') confirm = true;
     else if (argv[i] === '--share-ssh') shareSsh = true;
+    else if (argv[i] === '--browser') browser = true;
     else throw new Error(usage);
   }
   if (!['plan', 'connect', 'run', 'status', 'disconnect'].includes(command) || !Number.isInteger(port) || port < 1024 || port > 65535) throw new Error(usage);
   cloudOrigin(origin);
-  return { command, origin, port, confirm, shareSsh, fields: ['管理电脑名称', '系统类型', '内存', '用户目录卷磁盘', ...(shareSsh ? ['至多15个已关联SSH主机的名称和缓存资源状态（不含地址、用户、路径或配置）'] : [])], keyStorage: '仅本机私有目录/0600文件；当前不是Keychain/TPM封装', tasksAuthorized: false, backgroundInstalled: false };
+  return { command, origin, port, confirm, shareSsh, browser, fields: ['管理电脑名称', '系统类型', '内存', '用户目录卷磁盘', ...(shareSsh ? ['至多15个已关联SSH主机的名称和缓存资源状态（不含地址、用户、路径或配置）'] : [])], keyStorage: '仅本机私有目录/0600文件；当前不是Keychain/TPM封装', tasksAuthorized: false, backgroundInstalled: false };
 }
 export async function runLocal(plan) {
   // Reuse only a running native Driver that implements this protocol; never stop another listener.
@@ -43,8 +45,8 @@ export async function runLocal(plan) {
   const shutdown = () => instance.server.close(() => { instance.db.close(); process.exit(0); });
   process.once('SIGINT', shutdown); process.once('SIGTERM', shutdown);
 }
-export async function main(argv = process.argv.slice(2)) {
-  const plan = driverPlan(argv), file = defaultLinkFile();
+export async function main(argv = process.argv.slice(2), { file = defaultLinkFile(), post = cloudPost, openBrowser = openPairingBrowser, runDriver = runLocal, waitReport = waitForFirstReport } = {}) {
+  const plan = driverPlan(argv);
   if (Number(process.versions.node.split('.')[0]) < 24) throw new Error('需要 Node.js 24 或更高版本。');
   if (plan.command === 'plan') return plan; // No files, key generation, network or installation.
   if (process.platform === 'win32') throw new Error('Windows 身份文件的安全存储尚未实现，当前管理 Driver 只支持 macOS/Linux。');
@@ -66,16 +68,31 @@ export async function main(argv = process.argv.slice(2)) {
     writeLink(file, state, { create: true });
   }
   if (!state.certificate) { state.certificate = await issueCertificate(state); writeLink(file, state); }
-  const pending = await cloudPost(plan.origin, '/api/driver/pair/start', { publicKey: state.publicKey, certificate: state.certificate, name: hostname().slice(0,80), platform: ({ darwin: 'macOS', linux: 'Linux' })[platform()], shareSsh: plan.shareSsh });
-  if (!/^[a-f0-9-]{36}$/.test(pending.id) || !/^[A-F0-9]{4}-[A-F0-9]{4}$/.test(pending.code) || pending.fingerprint !== state.fingerprint || !Number.isSafeInteger(pending.expiresAt)) throw new Error('云端配对响应无效。');
-  console.log(`请打开 ${plan.origin}，点“连接我的电脑”，在面板单独输入以下配对码（5分钟内有效）：\n${pending.code}\n核对本机公钥指纹：${state.fingerprint}\n仅批准你刚在这台电脑发起的请求；配对码不放入智能体prompt或安装脚本。`);
+  let pending;
+  try { pending = await post(plan.origin, '/api/driver/pair/start', { publicKey: state.publicKey, certificate: state.certificate, name: hostname().slice(0,80), platform: ({ darwin: 'macOS', linux: 'Linux' })[platform()], shareSsh: plan.shareSsh, ...(plan.browser ? { browser: true } : {}) }); }
+  catch (error) {
+    if (plan.browser && error.statusCode === 400 && error.message === 'invalid_driver_input') throw new Error('控制面尚不支持浏览器接入，请升级控制面；或在本机终端使用不带 --browser 的 connect。未自动输出配对凭据。');
+    throw error;
+  }
+  if (!/^[a-f0-9-]{36}$/.test(pending.id) || (!plan.browser && !/^[A-F0-9]{4}-[A-F0-9]{4}$/.test(pending.code)) || pending.fingerprint !== state.fingerprint || !Number.isSafeInteger(pending.expiresAt)) throw new Error('云端配对响应无效。');
+  if (plan.browser) {
+    const url = pairingBrowserUrl(plan.origin, pending);
+    console.log(`正在打开本机浏览器。请本人登录账号，核对设备后批准一次。\n本机公钥指纹：${state.fingerprint}\n无需填写配对码，也无需回复 Agent；程序会自动等待并核验。`);
+    await openBrowser(url);
+  } else console.log(`请打开 ${plan.origin}，点“连接我的电脑”，在面板单独输入以下配对码（5分钟内有效）：\n${pending.code}\n核对本机公钥指纹：${state.fingerprint}\n仅批准你刚在这台电脑发起的请求；配对码不放入智能体prompt或安装脚本。`);
   const deadline = Math.min(pending.expiresAt, Date.now() + 300_000);
   while (Date.now() < deadline) {
-    const result = await cloudPost(plan.origin, '/api/driver/pair/poll', signedRequest(state.privateKey, plan.origin, '/api/driver/pair/poll', pending.id, {}));
+    const result = await post(plan.origin, '/api/driver/pair/poll', signedRequest(state.privateKey, plan.origin, '/api/driver/pair/poll', pending.id, {}));
     if (result.state === 'approved') {
       if (!/^[a-f0-9-]{36}$/.test(result.driverId) || typeof result.shareSsh !== 'boolean' || result.shareSsh && !plan.shareSsh) throw new Error('云端批准范围无效。');
       state = { ...state, driverId: result.driverId, shareSsh: result.shareSsh, disabled: false }; writeLink(file, state);
-      console.log('已绑定。私钥留在本机，只回报获准字段；远程任务未授权。'); await runLocal(plan); return linkSummary(state);
+      console.log('已绑定。私钥留在本机，只回报获准字段；远程任务未授权。');
+      const since = Date.now();
+      await runDriver(plan);
+      if (!plan.browser) return linkSummary(state);
+      const report = await waitReport({ port: plan.port, driverId: state.driverId, origin: state.origin, since });
+      console.log(report.verified ? '云端已接收首次资源回报，接入完成。' : '账号绑定已完成，但尚未确认首次资源回报。请检查本机服务与网络，不要重复绑定。');
+      return { ...linkSummary(state), firstReport: report };
     }
     if (result.state !== 'pending') throw new Error('配对响应无效。');
     await new Promise(done => setTimeout(done, 5000));

package/server/cloudAccess.mjs

@@ -4,6 +4,7 @@ import { createUnifiedAccess } from './unifiedAccess.mjs';
 
 const SESSION_AGE = 8 * 60 * 60 * 1000;
 const COOKIE = '__Host-device-center';
+const ENTRY_PAGES = new Set(['/', '/index.html', '/login', '/start', '/start.html', '/pair']);
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const reject = (message) => { throw new Error(message); };
 
@@ -42,9 +43,14 @@ export function createCloudAccess({ publicOrigin, authFile, now = Date.now, fetc
     origin: publicOrigin,
     validate(request) {
       // The process stays on loopback. The proxy preserves Host and overwrites X-Forwarded-Proto.
+      const site = request.headers['sec-fetch-site'];
+      // External links may open HTML pages; API requests, frames and writes remain isolated.
+      const entryNavigation = request.method === 'GET' && ['same-site', 'cross-site'].includes(site) &&
+        request.headers['sec-fetch-mode'] === 'navigate' && request.headers['sec-fetch-dest'] === 'document' &&
+        ENTRY_PAGES.has(new URL(request.url ?? '/', publicOrigin).pathname);
       if (request.headers.host !== url.host || request.headers['x-forwarded-proto'] !== 'https' ||
           (request.headers.origin && request.headers.origin !== publicOrigin) ||
-          (request.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(request.headers['sec-fetch-site']))) {
+          (site && !['same-origin', 'none'].includes(site) && !entryNavigation)) {
         throw Object.assign(new Error('cloud_origin_required'), { statusCode: 403 });
       }
       return publicOrigin;

package/server/drivers/browserPairing.mjs

@@ -0,0 +1,41 @@
+import { spawn } from 'node:child_process';
+import { cloudOrigin } from './driverProtocol.mjs';
+
+export function pairingBrowserUrl(origin, pending) {
+  cloudOrigin(origin);
+  if (!/^[a-f0-9]{64}$/.test(pending.browserTicket ?? '') || !Number.isSafeInteger(pending.expiresAt)) throw new Error('控制面尚不支持浏览器接入，请升级控制面；或在本机终端使用不带 --browser 的 connect。');
+  const url = new URL('/pair', origin);
+  // Fragments are excluded from HTTP requests and Referer; the page removes this immediately.
+  url.hash = new URLSearchParams({ ticket: pending.browserTicket, expires: String(pending.expiresAt) }).toString();
+  return url.href;
+}
+
+export async function openPairingBrowser(url, { platform = process.platform, spawnImpl = spawn } = {}) {
+  const target = new URL(url);
+  cloudOrigin(target.origin);
+  if (target.pathname !== '/pair' || target.search || !/^#ticket=[a-f0-9]{64}&expires=\d+$/.test(target.hash)) throw new Error('无效的浏览器交接。');
+  const command = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null;
+  if (!command) throw new Error('此系统尚不支持浏览器接入。');
+  // No shell, URL echo or opener output in the Agent transcript.
+  await new Promise((resolve, reject) => {
+    const child = spawnImpl(command, [target.href], { stdio: 'ignore', shell: false });
+    const timer = setTimeout(() => { child.kill(); reject(new Error('无法打开本机浏览器。请在本机终端执行不带 --browser 的 connect 手动配对；不会自动输出凭据。')); }, 10_000);
+    child.once('error', () => { clearTimeout(timer); reject(new Error('无法打开本机浏览器，请在本机终端使用不带 --browser 的 connect 手动配对。')); });
+    child.once('close', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error('浏览器打开失败，请在本机终端使用不带 --browser 的 connect 手动配对。')); });
+  });
+}
+
+export async function waitForFirstReport({ port, driverId, origin, since, fetchImpl = fetch, now = Date.now, sleep = ms => new Promise(done => setTimeout(done, ms)), timeoutMs = 75_000 }) {
+  const deadline = now() + timeoutMs;
+  while (now() < deadline) {
+    try {
+      const reply = await fetchImpl(`http://127.0.0.1:${port}/api/driver/link`, { signal: AbortSignal.timeout(1500), redirect: 'error' });
+      if (reply.ok) {
+        const link = await reply.json();
+        if (link.protocol === 'device-center-driver-v1' && link.driverId === driverId && link.origin === origin && !link.disabled && link.publisher?.state === 'connected' && link.publisher.lastSuccess >= since) return { verified: true, receivedAt: link.publisher.lastSuccess };
+      }
+    } catch { /* Registration and cloud delivery are separate results. */ }
+    await sleep(1500);
+  }
+  return { verified: false, reason: 'first_report_timeout' };
+}