# 电脑、设备、桌面与网络

> 使用 v42 computer、device、desktop 和 network 管理团队电脑与已配对设备、截取并控制远程桌面及其窗口与菜单，以及诊断 AP 和 P2P 网络路径。

`computer`、`device`、`desktop` 和 `network` 四个命令组用于查看和管理团队下的电脑、你已登录的 App 与 CLI 设备、远程桌面（截图、视频、鼠标、键盘与剪贴板）及其窗口与菜单，以及网络连接状态。

## 管理电脑（`v42 computer`）

```sh
v42 computer list
v42 computer show <computer>
v42 computer rename <computer> <name>
v42 computer pause <computer>
v42 computer resume <computer>
v42 computer relay <computer> <on|off>
v42 computer share <computer> <private|team>
v42 computer remove <computer> --yes
v42 computer cleanup [--dry-run] [--yes]
v42 computer herdr <computer> [--enable | --disable] [--sessions <sessions>]
```

- `computer list`：列出当前团队的所有电脑及其在线状态、暂停状态、中转模式、共享范围、Vibe42 版本、系统平台、featureset 以及活动终端数。
- `computer show <computer>`：按 ID 或名称查看单台电脑详情，包括其 Realm、宿主安装及访问限制。
- `computer rename <computer> <name>`：重命名电脑（去除首尾空白后 `1` 到 `64` 个字符；限团队 Owner、Admin 或该电脑的拥有者）。
- `computer pause <computer>` / `computer resume <computer>`：暂停电脑（恢复前无人可连接）或恢复已暂停的电脑（仅限团队 Owner 和 Admin；如果团队没有空闲的电脑名额，`resume` 会以 `resource_limit_exceeded` 失败）。
- `computer relay <computer> <on|off>`：开启（`on`）或关闭（`off`）该电脑的强制中转路由（限团队 Owner、Admin 或该电脑的拥有者）。
- `computer share <computer> <private|team>`：将电脑共享给整个团队（`team`），或设为仅对电脑拥有者及团队 Owner/Admin 可用（`private`）。仅该电脑的拥有者可修改此项。
- `computer remove <computer> --yes`：将电脑从团队中移除，撤销其凭据并删除云端保存的 Workspace 记录（仅限团队 Owner 和 Admin；必须传 `--yes`，否则返回 `confirmation_required`）。电脑磁盘上的本地文件不会受到任何影响。
- `computer cleanup [--dry-run] [--yes]`：移除离线超过 3 天的电脑（仅限团队 Owner 和 Admin）。不传 `--dry-run` 或 `--yes` 时以 `confirmation_required` 失败，并在 `error.details` 中列出候选电脑。
- `computer herdr <computer>`：查看电脑的 Herdr 桥接状态，或用 `--enable`、`--disable`、`--sessions <sessions>`（除默认实例外要连接的额外 Herdr 实例名，以逗号分隔；传空字符串 `""` 清空列表）修改配置。仅限该电脑拥有者在 macOS 或 Linux 上使用。

## 管理设备与配对请求（`v42 device`）

```sh
v42 device list [--all]
v42 device approve <code>
v42 device unpair <install_id>
v42 device cleanup [--dry-run] [--yes]
v42 device revoke <install_id>
```

- `device list`：列出你自己的设备（`installs`）以及有权访问当前团队的设备（`team_installs`；团队 Owner 和 Admin 可看到所有成员的设备）。`current: true` 标记当前 CLI 配置档案正在使用的设备。加上 `--all` 可一并包含已退出和已撤销的设备。
- `device approve <code>`：批准新电脑上显示的 8 位配对码，将其加入当前团队（需具备注册电脑的权限）。
- `device unpair <install_id>`：将你自己的某个 App 或浏览器退出登录（`<install_id>` 取自 `v42 device list` 的 `installs`）。不能用于退出当前正在运行命令的设备本身（请改用 `v42 logout`）。
- `device cleanup [--dry-run] [--yes]`：将你自己离线超过 3 天（且当前未在使用）的设备退出登录。不传 `--dry-run` 或 `--yes` 时以 `confirmation_required` 失败并列出候选设备。
- `device revoke <install_id>`：撤销某台设备对当前团队的访问权限并释放其占用的设备名额。注意：移除电脑（`v42 computer remove`）不会自动释放其宿主设备的名额；动态替换电脑时，请从 `v42 resources` 或 `v42 device list` 中找到对应的 `install_id` 并执行 `device revoke`。

## 控制桌面窗口、应用与菜单（`v42 desktop`）

需要目标电脑已开启远程桌面与远程控制（见[远程桌面：开始使用](/docs/remote-desktop/getting-started)）。下面的窗口、应用与菜单命令要求电脑 featureset 包含 `desktop.windows.v1`。

```sh
v42 desktop windows <computer>
v42 desktop apps <computer>
v42 desktop launch <computer> <app>
v42 desktop window <computer> <id> <close|minimize|full-screen>
v42 desktop menu <computer> <window>
v42 desktop menu-press --title <title> <computer> <window> <path>...
```

- `desktop windows <computer>`：列出 `<computer>` 桌面的显示器和已打开窗口。
- `desktop apps <computer>`：列出 `<computer>` 上可启动的应用程序（名称按 CLI 语言本地化）。
- `desktop launch <computer> <app>`：在 `<computer>` 上启动应用（已运行时则激活它）并返回其最前端窗口。`<app>` 可传应用路径，或 `v42 desktop apps` 中的 bundle ID、名称或本地化名称（不区分大小写）。
- `desktop window <computer> <id> <action>`：对窗口 `<id>`（来自 `v42 desktop windows`）执行 `close`（关闭）、`minimize`（最小化）或 `full-screen`（全屏）。
- `desktop menu <computer> <window>`：查看桌面窗口 `<window>` 所属应用的菜单栏结构。每个菜单项都带有 `path` 路径索引。
- `desktop menu-press --title <title> <computer> <window> <path>...`：点击 `<window>` 中的某个菜单项，`<path>...` 取自 `v42 desktop menu`（从顶层开始、包含分隔线的逗号分隔索引，如 `2,5`）。必须传入 `--title <title>` 作为安全校验：如果该菜单项当前的标题已不再匹配 `<title>`，点击会被拒绝。

### 截图、视频与输入

这些命令会打开一个远程桌面会话，要求电脑 featureset 包含 `desktop.v1`（否则返回 `desktop_unsupported`）。剪贴板命令还需要 `desktop.clipboard.v1`，`--window` 需要 `desktop.windows.v1`，`unlock` 需要 `desktop.unlock.v1`；缺少时返回 `desktop_feature_unsupported`。

```sh
v42 desktop screenshot <computer> -o <file.png|-> [--display <id> | --window <id>] [--quality <q>] [--max-width <n>] [--max-height <n>]
v42 desktop stream <computer> [-o <file|->] [--codec h264|hevc] [--duration <s>] [--frames <n>] [--display <id> | --window <id>] [--quality <q>]
v42 desktop move <computer> <x> <y> [--display <id> | --window <id>]
v42 desktop click <computer> <x> <y> [--button left|right|middle] [--count 1-3] [--display <id> | --window <id>]
v42 desktop drag <computer> <x1> <y1> <x2> <y2> [--button <b>] [--steps <n>] [--display <id> | --window <id>]
v42 desktop scroll <computer> [--at <x> <y>] [--dx <n>] [--dy <n>] [--display <id> | --window <id>]
v42 desktop key <computer> <combo>... [--window <id>]
v42 desktop type <computer> [<text> | --stdin] [--window <id>]
v42 desktop clipboard set <computer> [<text> | --stdin]
v42 desktop clipboard watch <computer> [--timeout <s>] [--count <n>]
v42 desktop clipboard copy <computer> [--timeout <s>] [--window <id>]
v42 desktop unlock <computer>
v42 desktop control <computer> [--display <id>] [--quality <q>]
```

- `desktop screenshot`：把显示器（或用 `--window` 指定的单个窗口，会被提到最前）的画面存成 PNG。CLI 等画面静止 0.7 秒（最多 3 秒）后自行解码视频：macOS 用 VideoToolbox，Linux 与 Windows 调用系统的 `ffmpeg`（找不到时返回 `desktop_decoder_unavailable`）。结果包含图像的 `width`、`height`、`codec`、`display`（含显示器原生 `width`、`height`）、`window`，以及电脑是否可控制（`control`）。`-o -` 时 stdout 只输出 PNG。`--quality` 可选 `low`、`balanced`、`high`（默认）、`ultra`、`auto`，不支持 `ultra` 或 `auto` 的电脑分别按 `high`、`balanced` 处理。
- `desktop stream`：把原始 Annex B 格式的 H.264（`--codec hevc` 时为 HEVC）视频写到 stdout 或文件。画面变化以 JSON 写到 stderr；写文件时结束后输出摘要。到达 `--duration` 或 `--frames` 时以退出码 `0` 结束，SIGINT 为 `130`，SIGTERM 为 `143`。带 `--window` 时，如果窗口关闭、所属应用退出或长时间离屏，也会以退出码 `0` 结束（`reason` 为 `window_closed`），不会转而录下整个显示器；此时 `desktop screenshot --window` 返回 `window_not_found`。`--duration` 与 `--timeout` 最长 30 天。
- 坐标是**显示器的原生像素**（0 到 `display.width` − 1、0 到 `display.height` − 1），不是截图的像素，截图常被缩小：图像上的位置要乘以 `display.width / width`。传 `--window <id>`（取自 `v42 desktop windows` 或 `v42 desktop launch`；需要 `desktop.windows.v1`，不能与 `--display` 同时使用）时，命令先选中该窗口：电脑会恢复它、把它提到最前，并在注入输入时保持它在最前；坐标改为该窗口采集区域的原生像素（`window.width`、`window.height`）。`key`、`type` 和 `clipboard copy` 也接受 `--window`，按键和文字会落在该窗口，而不是当前有焦点的应用。窗口不存在时返回 `window_not_found`。
- `desktop move`、`click`、`drag`、`scroll`：指针输入。`--count 2` 为双击。`--dy` 为正时内容向下滚动，与网页滚轮事件一致。
- `desktop key`：依次按下按键或组合键，例如 `cmd+shift+4`、`ctrl+c`、`alt+tab`、`enter`。修饰键为 `cmd`（也可写 `command`、`meta`、`super`、`win`）、`ctrl`、`alt`（也可写 `option`）和 `shift`；按键是物理键，可写 DOM `KeyboardEvent.code`（`KeyA`、`Digit1`、`ArrowUp`、`F5`），或 `a`、`1`、`esc`、`tab`、`up`、`pagedown`、标点字符等名称。`cmd` 在 Mac 上是 Command 键，在其他电脑上是 Windows 键。
- `desktop type`：向当前聚焦的应用输入文字（最多 64 KiB）。与 App 一致，文字中的换行按 Shift+Enter 发送；要按回车请用 `desktop key <computer> enter`。
- 输入类命令（`move`、`click`、`drag`、`scroll`、`key`、`type`）发完后按估算时间等待电脑注入，再断开连接，电脑会丢弃尚未注入的输入。电脑很慢时（例如虚拟机或负载很高的主机），命令可能报告成功，但部分文字或按键并没有到达：请用 `desktop screenshot` 或 `desktop clipboard copy` 核对结果；长文本或连续操作请用 `desktop control`，它在会话结束前一直保持连接。
- `desktop clipboard set` 把纯文本（最多 60 KiB）写入电脑剪贴板。`clipboard watch` 对开始监听之后的每次变化输出一行 JSON（依次为 `ready`、`clipboard`、`stopped`）。`clipboard copy` 按下复制快捷键（Mac 为 `cmd+c`，其他电脑为 `ctrl+c`）并返回复制得到的 `text`，没有新内容时返回 `clipboard_unchanged`。
- `desktop unlock`：在电脑的锁屏上代为输入当前登录用户的密码。密码只从标准输入读取，在终端上不回显。`result` 为 `unlocked` 或 `not_locked`；密码错误时返回 `unlock_wrong_password`。
- `desktop control`：在一个会话里连续执行多步操作。stdin 每行是一个 JSON 请求，例如 `{"id":1,"op":"click","x":1520,"y":830}`，每个结果占一行 `{"id":1,"ok":true,"data":…}`。支持的 `op` 有 `screenshot`（传 `path` 写文件，否则以 `png_base64` 返回 PNG）、`move`、`click`、`drag`、`scroll`、`key`、`type`、`clipboard_set`、`clipboard_watch`、`select_display`、`select_window`、`unlock`、`status` 和 `close`；`status`、`clipboard`、`bye` 事件以 `{"event":…}` 行输出。stdin 结束时退出。

输入需要电脑允许远程控制（只能观看时返回 `desktop_view_only`，退出码 `4`）。电脑不会回执输入，因此每条输入命令都会等电脑有足够时间执行后才返回（按键和指针 200 毫秒，文字更久）。打开会话会唤醒电脑的显示器；电脑可控制且指针在其他显示器上时，指针会被移到所采集显示器的中央。经接入点中转的视频计入流量。

## 网络诊断与接入点选择（`v42 network`）

```sh
v42 network [<computer>]
v42 network aps
v42 network lock [<ap_id> | --clear]
v42 network probe
```

- `network [<computer>]`：诊断到中转接入点（AP）的网络路径（返回 `ap_path`、`ap_round_trip_ms`、按 `control`/`terminal`/`file` 顺序排列的 `ap_lanes` 以及 NAT 观测结果）；传入 `<computer>` 时还会最多等待 8 秒以测量到该电脑的连接状态（`p2p_allowed`、`p2p_connected` 以及各通道是 `quic`、`tcp` 还是 `relay`）。传入全局选项 `--force-relay` 可仅测量中转路径而不等待直连。
- `network aps`：列出所有中转接入点（AP）及其区域、支持的协议和实测往返耗时。
- `network lock [<ap_id> | --clear]`：从下一条命令起让当前配置档案优先使用指定的 `<ap_id>`（来自 `v42 network aps`），或传 `--clear` 恢复自动选择。如果锁定的 AP 不健康或不可达，CLI 会自动回退到可用节点。
- `network probe`：重新测量所有接入点的延迟并输出最新结果。
