# 三种安装方式：Agent、安装包、复制脚本

三种方式都安装相同的设备连接器；本机、官方托管、接入已有自建 HTTPS 服务是独立的使用模式。

| 系统 | 离线安装包 | 启动 |
| --- | --- | --- |
| Windows 11 x64 / ARM64 | ZIP，内置 Node 24 与依赖 | 完整解压后双击 `Install.bat` |
| macOS Intel / Apple Silicon | DMG，内置对应架构运行环境 | 发行包挂载后双击 `Install Device Center.app`，在终端确认；候选包用 `Install.command` |
| Linux x64 / ARM64（glibc） | 自解压 `.sh`，内置对应架构运行环境 | `sh device-center-版本-linux-架构-摘要.sh` |

安装包不依赖目标机的系统 Node.js、npm registry 或 npm 代理。官方/自建模式的登录、配对和回报仍需要可达的 HTTPS 网络。Linux 包使用官方 glibc Node 构建，不适用于 Alpine/musl。

## 统一接入向导

下载页对带有 `setupWizardVersion: 1` 的新包显示以下流程。旧包保留原说明，不把已发布的 npm beta.9 或旧离线包当作具有新版向导。

1. 选择这台电脑的角色：主控、被控，或两者；选择官方托管、仅本机或已有自建服务。默认端口 5174，当前用户登录后后台运行。
2. 向导先检查安装、已有身份、绑定和后台配置，展示本次计划后确认一次。相同服务的已有绑定直接复用；首次接入才由本人在已登录的官网确认设备，不自动批准请求。
3. 程序安装或升级后启动、恢复或复用匹配的用户后台，核验真实运行与云端回报。重新打开向导会按当前状态继续未完成步骤，不根据上次记录冒称成功。
4. 主控使用官方 Codex CLI 配置本机 MCP；同名同地址的有效配置复用，地址冲突或停用配置保留并解释。其它 MCP 客户端显示同一回环地址。配置写入和客户端连接分别显示，不能把“已配置”当作当前聊天已加载工具。

被控角色明确同意接收后才启用远程调试。已经启用时复用原 epoch，不反复启用而使官网授权失效。本人在官网选择允许访问的主控、操作与期限，可长期有效直到撤销；主控随后通过自己的签名身份自动发现已有授权，不再要求复制授权 ID，也不会自动新建权限。

升级保留原身份和设备条目。不同服务的身份、不匹配的后台、未识别的安装或 MCP 配置冲突会保留并提示。仅本机模式不登记云端设备；系统未登录、休眠、断网或前台程序关闭时，跨机能力不可用。

### 旧包兼容流程

1. 选择官方托管（默认）、仅本机或已有自建 HTTPS 地址。
2. 默认端口 5174、用户登录后后台运行、桌面在浏览器显示验证码；需要时展开推荐设置并修改。确认安装位置。
3. 安装或核验复用同一版本程序；后台需要再次确认才登记。不支持的用户服务管理器不自动提权、改策略或启用 linger，可重新运行向导选择前台。
4. 本机模式显示回环面板；托管模式在这台电脑显示验证码，由本人在自己已登录的电脑或手机打开 `/link` 输入、核对设备识别码并批准一次，这台电脑不需要登录。无浏览器或通过 SSH 时验证码显示在终端，只留在终端与本人设备之间，不发给 Agent。

仅本机模式不是独立局域网多机管理，仍只监听回环。自建选项连接已有服务，不会自动部署公网服务器。安装和配对不授予 SSH、日志或任意命令权限。

取消、失败后保留已完成的安装和身份。重开同一包可核验并继续。识别到旧版离线包时，须明确确认升级；仅停止并重启配置完全匹配的用户后台，完整旧程序另存备份，应用数据与绑定不迁移。无法识别的安装、无法确认的服务或不同控制面的身份会停止并解释，不自动覆盖或解绑。空的安装目标可安全恢复。

后台安装失败时，向导列出原因与日志位置，可明确选择核验已有 Driver 或前台继续；关闭前台终端会停止回报。暂时断网会重试当前配对申请；重开同一连接命令可续接。申请五分钟内须完成批准，过期后登录/邮箱验证已完成的用户可明确确认新申请，无需重装。已批准但回执丢失时，原设备签名可在 24 小时内核对结果；这不延长批准有效期，也不重复添加设备。页面批准结果不确定时先检查结果，再决定是否继续。

程序与应用数据分离，安装包不包含数据库、身份、认证配置或用户 SSH 文件。日志授权与 CLI 授权的后续命令会优先寻找离线包，再寻找已有 npm 安装，不要求安装包修改 PATH。

## 安装路径与诊断

Windows 程序：`%USERPROFILE%\AppData\Local\Programs\Device Center\offline`。
macOS/Linux 程序：`~/.local/share/device-center/offline`。
数据继续使用原有平台应用数据目录；没有复制或重置身份。已有 npm 安装不自动卸载，服务/绑定冲突会保留并停止。

在解压后的安装入口加 `--verify` 仅验证清单与全部文件；`--plan` 同时显示目标位置，两者不安装或联网。显式的 `--install-only --confirm` 只安装程序，不登记服务、配对或生成身份。

macOS 安装器在终端运行，无需安装第三方终端应用。普通用户级安装不使用 sudo。发行 DMG 要完成个人 Developer ID 签名、公证、staple 与 Gatekeeper 核验；未签名的 CI 候选明确标记。Windows/Linux 预览包目前没有平台代码签名，下载页提供完整 SHA-256；不要关闭系统安全策略。

## 构建与提供下载

在对应构建环境从锁文件准备依赖，运行：

```sh
npm ci --ignore-scripts
npm run installer:build -- --output /新的输出目录 --platform darwin --arch arm64
npm run installer:build -- --output /新的输出目录 --platform win32 --arch x64
npm run installer:build -- --output /新的输出目录 --platform linux --arch x64
```

`--arch` 支持 x64、arm64；DMG 仅在 macOS 构建。构建阶段从 Node 官方源下载固定 `24.16.0` 运行时，并与官方 SHA-256 清单核对；依赖由 npm-shrinkwrap 固定且禁用安装钩子。目标机安装阶段不下载任何依赖。

产物名含产品版本、系统、架构与内容摘要。旁边的 `.installer.json` 和 `.sha256` 记录源码 SHA、dirty、Node 版本、大小及签名/公证状态。输出不覆盖已存在同名包；本地 dirty 构建不能冒充已发布版本。

下载服务设置 `DEVICE_CENTER_INSTALLERS_DIR` 指向只由部署者维护的产物目录，存放包及对应 `.installer.json`。`GET /install/packages` 仅公开可用包信息，`GET /install/packages/<id>` 下载前验证完整归档摘要。目录、未完成包、非法文件名与缺失包不会作为可下载选项显示；没有部署包时指南明确提示改用 Agent/脚本，不生成虚假下载链接。

三平台构建 workflow 在 PR、主线与手动触发时产生自有 CI 存储的候选包。公开 beta 包由维护者从通过 CI 的精确主线构建、验证后上传官方同域目录，不依赖私有 GitHub 仓库的匿名访问。新向导包元数据包含 `setupWizardVersion: 1`，源码 SHA 与完整归档摘要按实际记录，不覆盖旧包。macOS 构建可显式设置 `DEVICE_CENTER_SIGN_MACOS=1`，从本机受控配置传入 `APPLE_SIGNING_IDENTITY`、`APPLE_TEAM_ID` 与公证 API 参数；公证和 Gatekeeper 任一步失败不生成可发布元数据。私钥不得上传仓库或进入产物。

目录以版本和源码 SHA 分开，先核验全部归档摘要再切换 `DEVICE_CENTER_INSTALLERS_DIR`。回退时恢复上一目录并重启既有服务，保留用户数据。公开前必须核对官网目录、全部下载 SHA 和 npm 固定版本；用户服务重启与真实云端配对仍需目标设备本人验收。