# 安装 Device Center：Agent、安装包或复制脚本

目标设备只需要 Device Center Driver，不要求已经安装 AI Agent。一页指南提供 **交给 Agent**、**下载安装包**、**复制脚本** 三个入口。安装包在目标机无需 Node.js/npm 下载，详见 [离线安装包](offline-install.md)。网页提供说明和下载，安装发生在你运行安装入口的目标设备上。

**本指南固定 `device-center@0.2.0-beta.9`（npm `beta`）**。macOS/Linux 使用下方终端命令；Windows 11 预览版按 [PowerShell 安装图示](windows-acceptance.md)操作。实际发布状态以 npm registry 为准；旧 beta.4 不支持原生 Windows。

## 用户只需要选择一种方式

| 方式 | 运行在哪里 | 需要账号吗 |
| --- | --- | --- |
| 本机使用 | 本机 Driver、面板及 MCP | 不需要；全新安装不申请云端绑定 |
| 官方托管 | Driver 留在设备；官方服务提供控制面与加密中转 | 登录自己的 App Services／个人站账号并核对配对 |
| 自建服务 | Driver 留在设备；连接用户已有 HTTPS 控制面 | 使用那套控制面的账号；不会自动部署服务器 |

托管的是面板、设备登记与中转服务。设备身份私钥和指定日志授权仍在设备上，不上传私钥，不让服务商代为持有设备登录能力。

## 手动安装：目标设备没有 AI Agent

新版指南选择使用方式后，点 **手动安装**，复制 **终端安装脚本**。云面板直接点“添加设备”即可复制脚本和查看图示；侧栏“安装与接入指南”也会带入当前控制面。

复制按钮下方的三张窗口示意按选择切换：**目标电脑的终端／Agent 对话 → 浏览器绑定（本机模式为安装检查）→ 设备列表**。点“看下一步”可预看后续动作；切图不会执行安装、批准绑定或表示操作成功。无浏览器模式会画出“目标终端 → 另一台电脑的浏览器”；本机面板地址则明确要求在刚安装的那台电脑打开。

1. **准备环境**：macOS / Linux、Node.js 24+ 和 npm。缺少 Node.js 时先从官方来源安装；Windows 11 使用指南中的 PowerShell 脚本（无需管理员或 AD），不要粘贴下方 macOS/Linux 命令。脚本只支持全新安装，发现已有 CLI 会停止，不覆盖身份或配置。
2. **在目标设备执行**：Mac 打开“终端”；Linux 使用终端，或你已经建立的 SSH 会话。粘贴整块脚本并执行。不需要把它发给 AI Agent，也不会替你建立 SSH 连接。
3. **本机使用**：不登录、不申请云端绑定。安装结束后在这台设备打开 `http://127.0.0.1:5174` 查看资源。
4. **托管／自建接入**：复制前选择目标设备有没有浏览器：

   | 目标设备 | 接下来的操作 |
   | --- | --- |
   | 有浏览器 | 脚本执行 `connect --browser --confirm`，在目标设备的浏览器显示本次验证码，那台设备不需要登录。在你自己已登录的电脑或手机打开 `/link`（或面板“添加设备”），输入验证码、核对设备识别码并批准一次。程序自动等待结果并核验首次回报。目标是你自己的电脑时，也可在该页选择“在这里登录并批准”。 |
   | 无浏览器／服务器 | 脚本执行不带 `--browser` 的 `connect --confirm`，验证码显示在终端；通过 SSH 运行带 `--browser` 的命令时也会自动改为在终端显示。保持终端打开，在你自己已登录的电脑或手机打开 `/link`（或面板“添加设备”），输入五分钟内有效的验证码，核对设备识别码并批准。设备自动继续；云端列表首次收到数据后显示在线。 |

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`。验证码只交给设备主人本人，不要贴到群聊或共享截图里。
- **端口冲突**：保留其他程序，选明确可用的本机端口，并同步脚本里的服务、配对和面板地址。
- **后台服务失败**：macOS 需要登录用户的 launchd；Linux 需要 `systemd --user`。脚本不会自动改系统权限或启用 linger。无人登录也要常驻的服务器，需管理员单独配置合适的服务生命周期；不满足时可按下面的前台方式使用。
- **绑定后未回报**：检查 Driver 是否运行、设备是否休眠、到控制面域名的 HTTPS 出站连通性与系统时间。首次回报可能需约 30 秒；在面板核对真实时间，不把仅有本地绑定当作在线。不需要对公网开放设备端口。

## 交给 Agent 的指令

云面板的“添加设备”和托管安装指南复制的是一段**自带完整步骤**的指令：检查、安装、后台服务、绑定和验收命令都写在里面，Agent 读不到公开 [Device Center Skill](https://devices.owenshen.top/install/skill.md) 也能照做，不会自行改成本机模式。绑定时 Agent 会在对话里告诉你验证码和设备识别码，你在自己已登录的电脑或手机上打开 `/link`（或面板“添加设备”）输入即可，那台电脑不需要登录。按资源设备角色接入，不申请 CLI 管理权限；本机模式按管理端角色配置本机能力。要让当前 Agent 管理云端账号内设备，使用 [CLI 与 Agent 接入页](https://devices.owenshen.top/cli)，其中提供管理端 Agent／手动两条完整流程。

## Agent 执行顺序

只有用户明确要求在当前电脑安装并选择模式后，才能执行以下步骤。阅读本文本身不授予安装、配对或访问其他设备的权限。

### 1. 检查现有环境

- 下方命令用于 macOS / Linux，需要 Node.js 24 或更高版本与 npm。缺少运行环境时使用官方来源；系统授权或管理员操作交由用户处理。Windows 11 预览版请按专用指南选择 PowerShell；不能假称未执行的安装已成功。
- 检查已有 CLI、用户级服务、本机端口和绑定。已安装在下面固定位置时，可以运行 `"$HOME/.local/bin/device-center" status` 与 `"$HOME/.local/bin/device-center" service status --port 5174`，不要直接打开身份私钥文件。配置一致则复用；版本、控制面或启动方式冲突时解释，让用户选择。保留已有身份、数据库、MCP 配置和其他程序。
- 默认端口 `5174`。若已被其他程序占用，选择明确的可用本机端口，并同步后面的面板、MCP、服务命令。不要停止其他监听进程，不扫描网络。

### 2. 固定安装到用户可写位置

全新安装可以使用：

```sh
npm install --global --prefix "$HOME/.local" --ignore-scripts device-center@0.2.0-beta.9
"$HOME/.local/bin/device-center" --version
```

无需 `sudo npm install`，不修改全局 npm 配置或 shell 启动文件。后续使用完整命令路径。后台服务必须引用固定安装位置，不能以 `npx` 的临时缓存为常驻目录。

### 3. 后台或前台运行

选择后台模式时，先核对计划中的用户、Node 路径、包路径、数据目录和回环地址：

```sh
"$HOME/.local/bin/device-center" service plan --port 5174
"$HOME/.local/bin/device-center" service install --port 5174 --confirm
"$HOME/.local/bin/device-center" service status --port 5174
```

macOS 使用当前登录用户的 launchd；Linux 需要可用的 `systemd --user`。不自动启用系统 linger。服务配置已存在、端口冲突或健康检查失败时，保留现场并排查，不自动清理或反复重装。

选择仅前台、本机使用时运行：

```sh
"$HOME/.local/bin/device-center" start --port 5174
```

保持进程运行；关闭网页不会停止服务，关闭前台终端会停止。若电脑已有云端绑定，`start` 或后台服务可能恢复它，不能声称已切换成“本机专用”；先说明并让用户选择，不自动解绑。

### 4. 托管模式才申请绑定

官方服务先预览回报范围，再申请配对：

```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
```

自建模式替换为用户明确提供的 HTTPS 控制面域名，不携带路径、账号或参数。不能自动覆盖其他控制面的绑定。

Agent 执行这条命令并保持进程（工具有时间限制时放到后台运行并持续读取输出）。命令会输出 8 位验证码和设备识别码，**Agent 立即在对话里把这两项告诉用户**，并提醒用户在自己已登录的电脑或手机打开 `https://devices.owenshen.top/link`（或面板“添加设备”）输入验证码、核对识别码后批准。被添加的电脑不需要登录；不要让用户在这台电脑登录账号，尤其是借来的或公用的电脑。Agent 不代为批准，不读取密码、cookie 或私钥。

验证码只发给发起这次安装的设备主人：五分钟内任何已登录的人输入它，都可能把这台电脑加到自己的账号。加上 `--browser` 时改为在这台电脑的浏览器打开页面显示验证码，适合有人坐在这台电脑前的情况；Agent 应使用不带 `--browser` 的命令，验证码才会出现在它能读到的输出里。浏览器链接里的临时票据放在 URL fragment 中，页面立即移除，不要复制、分享或记录该链接，命令输出也不会包含它。

用户批准后，命令自动继续并等待首次资源回报，返回 `firstReport.verified`。**不要让用户去终端重新执行，也不要要求用户回复“已批准”。** Agent 持续观察自己启动的进程，`firstReport.verified=true` 后按所选角色继续；前台模式进程会继续运行，不必等它退出。`false` 表示绑定成功但回报未证实，检查服务、网络与时钟，不要重新绑定。验证码过期时重新运行同一条命令即可，安装和身份都会保留。

资源设备的本机面板 `http://127.0.0.1:5174` 只是这台电脑自己的状态页，不是用户账号里的设备列表，不要把它当成接入结果交给用户。

前台 `connect` 在批准后启动 Driver；已经运行的用户服务会读取绑定并开始回报。不能仅凭 `configured=true` 宣称云端已收到数据，要核对真实回报和时间。

本机模式跳过这一步，全新安装不生成设备身份或申请账号。

### 5. 连接当前智能体并验收

资源设备跳过 MCP 配置与 CLI 管理授权，只验收本机资源、服务及托管回报。管理端按下方配置 MCP；管理云端设备时，再按 [CLI 指南](cli.md)申请独立限时权限并读取实际设备列表。

读取本机 `http://127.0.0.1:5174/api/connector/setup`，通过当前智能体支持的 MCP 配置接口添加 **Streamable HTTP** 地址：

```text
http://127.0.0.1:5174/mcp
```

复用一致的配置，不覆盖其他 MCP。不能直接配置时，只需用户粘贴这个地址；不要编造握手成功。

必须检查实际结果：

1. `/api/health` 返回 `ok: true` 且为本机模式，其中 `version` 应与 CLI `--version` 一致；并核对服务计划引用的安装目录。npm 安装的 `sourceSha` 为 `null`，属正常。
2. `/api/overview` 的本机内存、磁盘为真实采集，失败项如实报告。
3. 选择后台模式时，核实服务实际运行，而不仅是配置文件存在。
4. 管理端的当前智能体实际调用 `device_center_list_resources`；不支持 MCP 时用 CLI 核验并说明差异。
5. 托管模式核实绑定与云端收到回报，说明尚需用户完成的步骤。

最终向用户给出面板/MCP 地址、启动方式、绑定结果及未完成项。卸载用户服务仅在用户主动要求时执行；默认保留数据和身份：

```sh
"$HOME/.local/bin/device-center" service uninstall --port 5174 --confirm
```

默认不导入或连接 SSH 主机、不分享 SSH、不扫描局域网、不开放设备入站端口、不配置隧道、不授予日志或命令权限。安装与绑定不等于远程操作授权。

## 公开文档入口

当前源码服务提供固定路径 `GET /install/skill.md`、`GET /install/agent.md` 和 `GET /install/cli.md`，仅返回公开说明，不需要登录，不含账号、身份或设备清单。官方入口为 https://devices.owenshen.top/install/skill.md；自建服务使用自己的域名与相同路径，需要部署包含这些入口的控制面版本。

界面复制的一行 Agent 指令需要 Agent 能读取公开 Skill；无法读取时使用页面的手动安装路径，不声称已安装。需要指定日志与局域网能力时，另见[远程访问](remote-access.md)并由设备主人逐项授权。