mirror of
https://github.com/kunkundi/crossdesk.git
synced 2026-11-02 03:52:43 +08:00
[docs] expand CLI guide with npm setup and previews
This commit is contained in:
dijunkun
@@ -7,6 +7,8 @@
|
||||
<div align="center">
|
||||
|
||||
[](#download)
|
||||
[](#cli)
|
||||
[](https://www.npmjs.com/package/@chunkdash/crossdesk-cli)
|
||||
|
||||
[](https://github.com/kunkundi/crossdesk/releases)
|
||||
[](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml)
|
||||
@@ -51,7 +53,7 @@ CrossDesk 让你从电脑、浏览器、手机或终端连接远端电脑，也
|
||||
| 鸿蒙 PC（开发版） | **控制 / 被控**；API 26，arm64；使用 DevEco 构建并签名 HAP，仍在进行真机验收 |
|
||||
| 鸿蒙手机 / 平板（开发版） | **仅控制**；API 20+，arm64；使用 DevEco 构建并签名 HAP，仍在进行真机验收 |
|
||||
| Web | **仅控制**；支持 WebRTC 的浏览器；无需在控制端安装客户端 |
|
||||
| 终端 CLI（开发版） | **仅控制**；构建目标为 macOS / Linux（x64、arm64）和 Windows（x64）；从源码构建，平台验收范围见 [CLI 说明](apps/cli/README.md) |
|
||||
| 终端 CLI（开发版） | **仅控制**；分发目标为 macOS / Linux（x64、arm64）和 Windows（x64）；通过 [npm 安装](#cli-npm) 或从源码构建，平台验收范围见 [CLI 说明](apps/cli/README.md) |
|
||||
|
||||
系统要求按当前源码与构建配置整理，具体安装包以对应 Release 说明为准。各客户端的功能范围见 [终端 CLI](#cli) 与 [移动端与鸿蒙](#mobile)。
|
||||
|
||||
@@ -130,6 +132,38 @@ CrossDesk 让你从电脑、浏览器、手机或终端连接远端电脑，也
|
||||
|
||||
`crossdesk-cli` 在终端中通过 9 位设备 ID 连接被控电脑，默认只读、静音。普通终端使用 ANSI 字符画面，支持 Kitty 图形协议的终端可显示像素画面；可切换显示器、调整画质、放大细节和平移，也可明确开启键鼠控制。CLI 可以独立于桌面 GUI 构建，被控电脑仍需运行 CrossDesk 并提供可捕获的图形会话，信令服务需支持 `cli` 临时身份注册。
|
||||
|
||||
### 画面预览
|
||||
|
||||
| ANSI 字符画面 | Kitty 协议像素画面 |
|
||||
| --- | --- |
|
||||
| <img src="docs/images/cli-ansi-overview.png" width="480" alt="CrossDesk CLI 的 ANSI 四象限全景：顶部显示只读模式和连接状态，底部显示操作快捷键" /> | <img src="docs/images/cli-kitty-overview.png" width="480" alt="CrossDesk CLI 的 Kitty 协议全景：同一远程桌面以像素画面显示，保留状态栏和操作快捷键" /> |
|
||||
| 用彩色字符显示桌面轮廓，适合普通终端；查看局部可按 `d` 放大。 | 直接显示像素画面，适合支持 Kitty 图形协议的终端，如 Ghostty。 |
|
||||
|
||||
两图采集于 **2026-10-31**，来自同一授权设备的实际只读连接，以 160 × 48 字符视口还原 CLI 的 ANSI / Kitty 协议输出。图示为输出渲染，终端实窗效果受字体、窗口大小及协议支持影响；采集方法见 [图示来源](docs/images/README.md#cli-captures)。
|
||||
|
||||
<a id="cli-npm"></a>
|
||||
|
||||
### 通过 npm 安装并连接
|
||||
|
||||
准备 **Node.js 22 或以上**及 npm，从 [@chunkdash/crossdesk-cli](https://www.npmjs.com/package/@chunkdash/crossdesk-cli) 安装。npm 会按操作系统与 CPU 架构选择原生程序，无需安装 Xmake 或 C++ 编译工具链。
|
||||
|
||||
```sh
|
||||
npm install -g @chunkdash/crossdesk-cli@latest
|
||||
crossdesk-cli doctor --json
|
||||
crossdesk-cli 123456789
|
||||
```
|
||||
|
||||
将 `123456789` 换成被控电脑的 9 位设备 ID，连接时按提示隐藏输入密码。默认只读、静音；`doctor` 仅检查本机环境，不发起连接。更新到最新版时，重新执行上面的 `npm install -g @chunkdash/crossdesk-cli@latest`。
|
||||
|
||||
无需全局安装时，也可使用 `npx`，首次运行会下载对应平台包：
|
||||
|
||||
```sh
|
||||
npx @chunkdash/crossdesk-cli@latest doctor --json
|
||||
npx @chunkdash/crossdesk-cli@latest 123456789
|
||||
```
|
||||
|
||||
请安装统一入口 `@chunkdash/crossdesk-cli`，并保留 npm 的可选依赖，不要添加 `--omit=optional`；仅安装平台包不会注册 `crossdesk-cli` 命令。平台运行要求、旧包迁移及故障排查见 [npm 分发说明](apps/cli/docs/npm-distribution.md)。
|
||||
|
||||
### 从源码构建并连接
|
||||
|
||||
准备 Git、Xmake 3.1.1 或以上、C++17 编译工具链及对应平台依赖。以下以 macOS / Linux shell 为例；Windows 的 Git Bash / 开发者 PowerShell 步骤见 [CLI 构建说明](apps/cli/docs/terminal-client.md#构建与安装)。
|
||||
@@ -146,7 +180,34 @@ xmake run crossdesk-cli 123456789
|
||||
|
||||
已有仓库时从仓库根目录执行依赖准备及后续命令。将 `123456789` 换成被控电脑的 ID，密码在连接时隐藏输入。`doctor` 只检查本机环境，不发起连接。仓库默认构建桌面端；以上配置只构建 CLI，需要同时构建桌面端时将 `CROSSDESK_BUILD_DESKTOP` 设为 `y`。产物位于 `build/<platform>/<arch>/release/`。
|
||||
|
||||
ANSI 全景受终端字符网格限制。阅读小字可添加 `--quality high --zoom native`，或进入画面后按 `d` 查看细节；`--renderer kitty` 需要终端支持对应协议。显示、鼠标报告、SSH 和终端兼容性见 [使用说明](apps/cli/docs/terminal-client.md)。
|
||||
### 选择画面与连接参数
|
||||
|
||||
默认 `--renderer auto` 自动探测 Kitty 图形协议，未获支持时回退为 ANSI。macOS「终端」等普通终端可显式选择 `ansi`；Ghostty 等支持该协议的终端可选择 `kitty`。显式指定 `kitty` 但探测失败时会报错，此时改用 `ansi`。
|
||||
|
||||
以下示例使用 npm 全局安装后的命令；从源码构建时，可在仓库根目录将 `crossdesk-cli` 替换为 `xmake run crossdesk-cli`。
|
||||
|
||||
```sh
|
||||
# 普通终端：以细节模式查看局部
|
||||
crossdesk-cli 123456789 --renderer ansi --zoom native
|
||||
|
||||
# 支持 Kitty 图形协议的终端：显示像素画面
|
||||
crossdesk-cli 123456789 --renderer kitty
|
||||
|
||||
# 降低远端画质与刷新请求
|
||||
crossdesk-cli 123456789 --quality balanced --fps 8
|
||||
```
|
||||
|
||||
| 参数 | 用途 |
|
||||
| --- | --- |
|
||||
| `--renderer auto\|ansi\|kitty` | 自动选择、字符画面或像素画面；默认 `auto` |
|
||||
| `--zoom native` | 从原始细节模式开始；`--zoom 2` 表示相对全景放大 2 倍 |
|
||||
| `--quality low\|balanced\|high\|ultra` | 请求最高 360p / 720p / 1080p / 2160p；默认 `high`，实际画质由被控端决定 |
|
||||
| `--fps 8` | 固定本地输出目标和相应远端预览请求；允许 1–30，默认本地目标为 30，未指定时远端供帧会自适应 |
|
||||
| `--display 1` | 选择第二个显示器，索引从 `0` 开始 |
|
||||
| `--control` | 连接后直接启用键鼠控制；省略时默认只读 |
|
||||
| `--server your-server.example --port 9099` | 使用自建信令服务，两端需接入同一服务 |
|
||||
|
||||
ANSI 全景受字符网格限制，提高画质不能让整屏小字变得清晰；可扩大终端、缩小字体，再按 `d` 查看局部，按 `f` 回到全景。顶部状态栏显示模式、连接进度、渲染器、缩放、实时输出 FPS 和网络信息，窄窗口会省略部分字段。通过 SSH 使用时分配 PTY（`ssh -t`）；tmux / screen 使用 ANSI。更多显示、鼠标报告和兼容性说明见 [终端使用指南](apps/cli/docs/terminal-client.md)。
|
||||
|
||||
### 控制、查看与退出
|
||||
|
||||
@@ -160,7 +221,9 @@ ANSI 全景受终端字符网格限制。阅读小字可添加 `--quality high -
|
||||
| `d` / `f` | 在只读或本地命令模式中切换原始细节 / 完整桌面；只读时也可点击目标进入细节 |
|
||||
| 方向键 / `i j k l` | 在只读或本地命令模式中平移；`i` 上、`j` 左、`k` 下、`l` 右 |
|
||||
|
||||
`Ctrl+]` 模式不会因为缩放、平移或按 `c` 自动结束。状态栏中的 `CONTROL PAUSED` / `READ ONLY` 表示返回后是否启用控制。控制模式中的普通 `c`、`q` 和 `Ctrl+C` 会发送到远端，需要先按 `Ctrl+]` 执行本地操作；再次按 `Ctrl+]` 也可返回，若返回控制模式则向远端发送一次该组合键。
|
||||
**控制模式下退出：先按 `Ctrl+]`，再按 `q`。** 普通 `c`、`q` 和 `Ctrl+C` 在控制模式中会发送到远端。
|
||||
|
||||
`Ctrl+]` 模式不会因为缩放、平移或按 `c` 自动结束。状态栏中的 `CONTROL PAUSED` / `READ ONLY` 表示返回后是否启用控制；按 `Esc` / `Ctrl+C` 手动返回。再次按 `Ctrl+]` 也可返回，若返回控制模式则向远端发送一次该组合键。
|
||||
|
||||
### Pi 扩展与功能范围
|
||||
|
||||
@@ -173,7 +236,7 @@ pi -e ./apps/cli/plugins/pi/index.ts
|
||||
|
||||
其他平台将 `CROSSDESK_CLI` 改为原生可执行文件的绝对路径。在 Pi 中输入 `/crossdesk` 或 `/crossdesk 123456789`，按提示输入密码。安装要求与验证范围见 [Pi 扩展说明](apps/cli/docs/terminal-client.md#pi-扩展)。
|
||||
|
||||
CLI 当前仅提供 ID 连接与远程观看 / 输入，不提供 IP 直连、音频播放、文件传输或剪贴板同步。macOS arm64 已完成本地构建和连接验证；Linux / Windows 完整运行、SSH / Kitty 实机显示及真实 Pi TUI 的验收范围见 [验证记录](apps/cli/docs/validation.md)。平台构建配置与 npm 打包流程不代表全部平台已验收或包已发布。
|
||||
CLI 当前仅提供 ID 连接与远程观看 / 输入，不提供 IP 直连、音频播放、文件传输或剪贴板同步。macOS arm64 已完成本地构建和连接验证；Linux / Windows 完整运行、SSH / Kitty 实机显示及真实 Pi TUI 的验收范围见 [验证记录](apps/cli/docs/validation.md)。平台构建与 npm 发布不代表全部平台已完成实机验收。
|
||||
|
||||
[CLI 文档入口](apps/cli/README.md) · [终端使用与故障排查](apps/cli/docs/terminal-client.md) · [桥接协议](apps/cli/docs/bridge-protocol.md) · [npm 打包与分发](apps/cli/docs/npm-distribution.md)
|
||||
|
||||
|
||||
+67
-4
@@ -7,6 +7,8 @@
|
||||
<div align="center">
|
||||
|
||||
[](#download)
|
||||
[](#cli)
|
||||
[](https://www.npmjs.com/package/@chunkdash/crossdesk-cli)
|
||||
|
||||
[](https://github.com/kunkundi/crossdesk/releases)
|
||||
[](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml)
|
||||
@@ -51,7 +53,7 @@ Get a package matching your OS and CPU architecture from the [website](https://w
|
||||
| HarmonyOS PC (development) | **Control + host**. API 26, arm64; build and sign a HAP with DevEco; physical-device validation is ongoing |
|
||||
| HarmonyOS phones / tablets (development) | **Control only**. API 20+, arm64; build and sign a HAP with DevEco; physical-device validation is ongoing |
|
||||
| Web | **Control only**. A WebRTC-capable browser; no client installation on the controlling device |
|
||||
| Terminal CLI (development) | **Control only**. Build targets: macOS / Linux (x64, arm64) and Windows (x64). Build from source; see the [CLI guide](apps/cli/README.md) (Chinese) for platform validation status |
|
||||
| Terminal CLI (development) | **Control only**. Distribution targets: macOS / Linux (x64, arm64) and Windows (x64). [Install from npm](#cli-npm) or build from source; see the [CLI guide](apps/cli/README.md) (Chinese) for platform validation status |
|
||||
|
||||
Requirements follow the current source and build configuration. Check the release notes for the downloaded package. Client capabilities are summarized under [Terminal CLI](#cli) and [Mobile and HarmonyOS](#mobile).
|
||||
|
||||
@@ -130,6 +132,38 @@ Remote sessions support monitor switching, video quality and frame-rate controls
|
||||
|
||||
`crossdesk-cli` connects to a host by its 9-digit device ID and starts in read-only, silent mode. Standard terminals use ANSI character rendering; terminals supporting the Kitty graphics protocol can display pixel graphics. The CLI supports monitor selection, quality settings, detail zoom, panning, and optional keyboard/mouse control. It builds independently of the desktop GUI. The host still needs CrossDesk and a capturable graphical session, and the signaling service must support temporary `cli` identities.
|
||||
|
||||
### Display preview
|
||||
|
||||
| ANSI character rendering | Kitty pixel graphics |
|
||||
| --- | --- |
|
||||
| <img src="docs/images/cli-ansi-overview.png" width="480" alt="CrossDesk CLI ANSI quadrant overview, with read-only mode and connection status at the top and shortcuts at the bottom" /> | <img src="docs/images/cli-kitty-overview.png" width="480" alt="CrossDesk CLI Kitty protocol overview of the same remote desktop, rendered as pixels with the status bar and shortcuts" /> |
|
||||
| Colored characters show the desktop in standard terminals; press `d` to inspect a smaller region. | Pixel graphics display the desktop in terminals supporting the Kitty graphics protocol, such as Ghostty. |
|
||||
|
||||
Both images were captured on **2026-10-31** from real read-only connections to the same authorized host. They render the CLI's ANSI / Kitty protocol output in a 160 × 48 character viewport. Actual terminal appearance depends on the font, window size, and protocol support. See [capture notes](docs/images/README.md#cli-captures) for the method.
|
||||
|
||||
<a id="cli-npm"></a>
|
||||
|
||||
### Install from npm and connect
|
||||
|
||||
Install **Node.js 22 or later** and npm, then get [@chunkdash/crossdesk-cli](https://www.npmjs.com/package/@chunkdash/crossdesk-cli). npm selects the native executable for your OS and CPU architecture; Xmake and a C++ toolchain are not required.
|
||||
|
||||
```sh
|
||||
npm install -g @chunkdash/crossdesk-cli@latest
|
||||
crossdesk-cli doctor --json
|
||||
crossdesk-cli 123456789
|
||||
```
|
||||
|
||||
Replace `123456789` with the host's 9-digit device ID and enter its password at the hidden prompt. Connections start in read-only, silent mode; `doctor` checks the local environment without connecting. To update, run `npm install -g @chunkdash/crossdesk-cli@latest` again.
|
||||
|
||||
You can also use `npx` without a global installation. The first run downloads the matching platform package:
|
||||
|
||||
```sh
|
||||
npx @chunkdash/crossdesk-cli@latest doctor --json
|
||||
npx @chunkdash/crossdesk-cli@latest 123456789
|
||||
```
|
||||
|
||||
Install the main `@chunkdash/crossdesk-cli` package with npm optional dependencies enabled; do not add `--omit=optional`. Installing a platform package alone does not register the `crossdesk-cli` command. See the [npm distribution guide](apps/cli/docs/npm-distribution.md) (Chinese) for platform requirements, migration from older packages, and troubleshooting.
|
||||
|
||||
### Build and connect
|
||||
|
||||
Install Git, Xmake 3.1.1 or later, a C++17 toolchain, and the platform dependencies. The following example uses a macOS / Linux shell; Windows Git Bash / Developer PowerShell steps are in the [CLI build guide](apps/cli/docs/terminal-client.md#构建与安装) (Chinese).
|
||||
@@ -146,7 +180,34 @@ xmake run crossdesk-cli 123456789
|
||||
|
||||
For an existing checkout, run the dependency preparation and subsequent commands from the repository root. Replace `123456789` with the host's ID; the password prompt hides your input. `doctor` reports the local environment without connecting. The repository builds the desktop client by default; this configuration builds only the CLI. Set `CROSSDESK_BUILD_DESKTOP=y` to also build the desktop client. Binaries are placed in `build/<platform>/<arch>/release/`.
|
||||
|
||||
An ANSI overview is limited by the terminal's character grid. Add `--quality high --zoom native`, or press `d` in the viewer, to inspect small text. `--renderer kitty` requires a terminal supporting that protocol. See the [terminal guide](apps/cli/docs/terminal-client.md) (Chinese) for rendering, mouse reporting, SSH, and terminal compatibility.
|
||||
### Rendering and connection options
|
||||
|
||||
The default `--renderer auto` probes for Kitty graphics support and falls back to ANSI. Use `ansi` explicitly in standard terminals such as macOS Terminal, or `kitty` in compatible terminals such as Ghostty. Explicit `kitty` mode reports an error if the probe fails; use `ansi` in that case.
|
||||
|
||||
These examples use the command installed globally by npm. For a source build, replace `crossdesk-cli` with `xmake run crossdesk-cli` and run it from the repository root.
|
||||
|
||||
```sh
|
||||
# Standard terminal: start with a detail view
|
||||
crossdesk-cli 123456789 --renderer ansi --zoom native
|
||||
|
||||
# Terminal supporting the Kitty graphics protocol: display pixel graphics
|
||||
crossdesk-cli 123456789 --renderer kitty
|
||||
|
||||
# Request lower video quality and refresh rate
|
||||
crossdesk-cli 123456789 --quality balanced --fps 8
|
||||
```
|
||||
|
||||
| Option | Purpose |
|
||||
| --- | --- |
|
||||
| `--renderer auto\|ansi\|kitty` | Automatic selection, character rendering, or pixel graphics; default: `auto` |
|
||||
| `--zoom native` | Start in native detail mode; `--zoom 2` zooms to twice the full-desktop scale |
|
||||
| `--quality low\|balanced\|high\|ultra` | Request up to 360p / 720p / 1080p / 2160p; default: `high`. The host determines actual quality |
|
||||
| `--fps 8` | Fix the local output target and corresponding remote preview request; accepts 1–30. The default local target is 30, with adaptive remote requests when omitted |
|
||||
| `--display 1` | Select the second monitor; indexes start at `0` |
|
||||
| `--control` | Enable keyboard/mouse control immediately after connecting; omitted by default for read-only viewing |
|
||||
| `--server your-server.example --port 9099` | Use a self-hosted signaling service; both ends must use the same service |
|
||||
|
||||
ANSI overviews are limited by the character grid: higher video quality alone cannot make full-desktop text legible. Enlarge the terminal or reduce its font size, press `d` for detail, and `f` to return to the full desktop. The top bar shows input mode, connection progress, renderer, zoom, live output FPS, and network information; narrow windows omit some fields. Allocate a PTY over SSH (`ssh -t`), and use ANSI inside tmux / screen. See the [terminal guide](apps/cli/docs/terminal-client.md) (Chinese) for rendering, mouse reporting, and compatibility details.
|
||||
|
||||
### Control, navigation, and exit
|
||||
|
||||
@@ -160,7 +221,9 @@ An ANSI overview is limited by the terminal's character grid. Add `--quality hig
|
||||
| `d` / `f` | Switch to native detail / full-desktop view in read-only or local command mode; clicking in read-only mode also opens detail at that point |
|
||||
| Arrow keys / `i j k l` | Pan in read-only or local command mode: `i` up, `j` left, `k` down, `l` right |
|
||||
|
||||
Zooming, panning, or pressing `c` does not end `Ctrl+]` mode. The status bar shows `CONTROL PAUSED` / `READ ONLY` to indicate whether control will resume. In control mode, ordinary `c`, `q`, and `Ctrl+C` go to the host, so enter local command mode first for local actions. Pressing `Ctrl+]` again also leaves local mode and forwards that shortcut if control resumes.
|
||||
**To quit while controlling the host, press `Ctrl+]`, then `q`.** Ordinary `c`, `q`, and `Ctrl+C` go to the host in control mode.
|
||||
|
||||
Zooming, panning, or pressing `c` does not end `Ctrl+]` mode. The status bar shows `CONTROL PAUSED` / `READ ONLY` to indicate whether control will resume; press `Esc` / `Ctrl+C` to return manually. Pressing `Ctrl+]` again also leaves local mode and forwards that shortcut if control resumes.
|
||||
|
||||
### Pi extension and feature scope
|
||||
|
||||
@@ -173,7 +236,7 @@ pi -e ./apps/cli/plugins/pi/index.ts
|
||||
|
||||
On other platforms, set `CROSSDESK_CLI` to the absolute path of the native executable. Enter `/crossdesk` or `/crossdesk 123456789` in Pi and follow the password prompt. See the [Pi extension guide](apps/cli/docs/terminal-client.md#pi-扩展) (Chinese) for requirements and validation scope.
|
||||
|
||||
The CLI currently provides ID-based viewing and input, without direct IP connections, audio playback, file transfer, or clipboard synchronization. Local builds and remote connections have been validated on macOS arm64. See the [validation record](apps/cli/docs/validation.md) (Chinese) for the remaining Linux / Windows, SSH / Kitty terminal, and actual Pi TUI checks. Platform build configurations and npm packaging do not establish that every platform is validated or that packages have been published.
|
||||
The CLI currently provides ID-based viewing and input, without direct IP connections, audio playback, file transfer, or clipboard synchronization. Local builds and remote connections have been validated on macOS arm64. See the [validation record](apps/cli/docs/validation.md) (Chinese) for the remaining Linux / Windows, SSH / Kitty terminal, and actual Pi TUI checks. Platform builds and npm publication do not establish that every platform has been validated on real devices.
|
||||
|
||||
[CLI documentation](apps/cli/README.md) · [Terminal usage and troubleshooting](apps/cli/docs/terminal-client.md) · [Bridge protocol](apps/cli/docs/bridge-protocol.md) · [npm packaging and distribution](apps/cli/docs/npm-distribution.md) (detailed guides in Chinese)
|
||||
|
||||
|
||||
+55
-3
@@ -2,14 +2,38 @@
|
||||
|
||||
CrossDesk 的终端主控客户端，源码位于本仓库的 `apps/cli`。通过真实 MiniRTC ID 会话观看远程桌面；默认只读、静音。包含 ANSI 象限字符画面、局部放大和平移、Kitty 图形后端，以及 Pi 自定义 TUI 扩展。
|
||||
|
||||
分发目标为 macOS / Linux（x64、arm64）和 Windows（x64）的原生终端客户端。npm 包发布后可统一使用：
|
||||
## 画面预览
|
||||
|
||||
| ANSI 字符画面 | Kitty 协议像素画面 |
|
||||
| --- | --- |
|
||||
| <img src="../../docs/images/cli-ansi-overview.png" width="480" alt="CrossDesk CLI 的 ANSI 全景输出，包含只读状态栏与快捷键提示" /> | <img src="../../docs/images/cli-kitty-overview.png" width="480" alt="CrossDesk CLI 的 Kitty 像素全景输出，显示同一远程桌面" /> |
|
||||
|
||||
图示来自 **2026-10-31** 的实际只读连接，通过伪终端采集并渲染协议输出；来源与边界见 [图示说明](../../docs/images/README.md#cli-captures)。默认 `auto` 探测 Kitty 支持，失败时使用 ANSI；普通终端可指定 `--renderer ansi`，Ghostty 等支持 Kitty 图形协议的终端可指定 `--renderer kitty`。ANSI 全景适合查看桌面轮廓，阅读小字需进入细节模式。
|
||||
|
||||
## 安装与连接
|
||||
|
||||
### 通过 npm 安装
|
||||
|
||||
需要 **Node.js 22 或以上**和 npm。统一入口为 [@chunkdash/crossdesk-cli](https://www.npmjs.com/package/@chunkdash/crossdesk-cli)，分发目标为 macOS / Linux（x64、arm64）和 Windows（x64）。安装时自动选择对应的原生程序，无需 Xmake 或 C++ 编译工具链：
|
||||
|
||||
```sh
|
||||
npm install -g @chunkdash/crossdesk-cli@latest
|
||||
crossdesk-cli doctor --json
|
||||
crossdesk-cli 123456789
|
||||
```
|
||||
|
||||
将示例 ID 替换为被控电脑的 9 位 ID，按提示隐藏输入密码。`doctor` 仅检查本机环境，不发起连接。更新到最新版时重新执行上述安装命令。
|
||||
|
||||
无需全局安装时，使用 `npx`，首次运行会下载对应平台包：
|
||||
|
||||
```sh
|
||||
npx @chunkdash/crossdesk-cli@latest doctor --json
|
||||
npx @chunkdash/crossdesk-cli@latest 123456789
|
||||
```
|
||||
|
||||
统一入口包为 `@chunkdash/crossdesk-cli`，安装后命令仍为 `crossdesk-cli`。五个平台依赖使用 `@chunkdash/crossdesk-cli-*`，由启动器自动选择。旧的无 scope 平台包不属于这套依赖；仅安装平台包不会注册命令。是否可安装以 npm 上完整版本的发布结果为准，三端实机验收尚未全部完成。运行要求、打包、本地安装与发布步骤见 [npm 分发](docs/npm-distribution.md)。
|
||||
安装后命令为 `crossdesk-cli`。五个平台依赖使用 `@chunkdash/crossdesk-cli-*`，由启动器自动选择；请保留 npm 的可选依赖，不要使用 `--omit=optional`。旧的无 scope 平台包不属于这套依赖，仅安装平台包不会注册命令。三端实机验收尚未全部完成；运行要求、旧包迁移、打包与发布步骤见 [npm 分发](docs/npm-distribution.md)。
|
||||
|
||||
### 从源码构建
|
||||
|
||||
在 CrossDesk 仓库根目录执行以下命令构建 CLI：
|
||||
|
||||
@@ -21,7 +45,35 @@ xmake run crossdesk-cli doctor --json
|
||||
xmake run crossdesk-cli 123456789 --quality high --zoom native
|
||||
```
|
||||
|
||||
`crossdesk-cli <设备ID> [选项]` 为默认连接方式，`view <设备ID>` 保留为兼容别名。最后一个设备 ID 是格式示例，使用时替换为你有权访问的设备。密码通过隐藏提示输入。只读时 `c` 开启控制、`q` 或 `Ctrl+C` 退出；点击目标或按 `d` 进入原始细节模式，`+/-` 或滚轮缩放，方向键或 `i` 上、`j` 左、`k` 下、`l` 右平移，`f` 回到完整桌面。任何模式下先按 `Ctrl+]` 进入持续本地命令模式，再按 `c` 选择返回后的控制状态、`q` 退出或视图按键连续调整画面，`Esc` / `Ctrl+C` 手动返回。控制模式中的 `Ctrl+T`、`Ctrl+C` 和普通按键均传给远端。ANSI 全屏缩略图仍受字符网格限制，默认请求 high 画质，阅读小字建议使用细节模式；支持 Kitty 协议的终端可使用 `--renderer kitty` 获得像素画面。
|
||||
构建后可直接运行 `build/<platform>/<arch>/release/crossdesk-cli`，也可将对应目录加入 PATH；Windows 的文件名为 `crossdesk-cli.exe`。
|
||||
|
||||
### 常用连接命令
|
||||
|
||||
以下示例适用于 npm 全局安装，或已将原生程序加入 PATH 的环境。`crossdesk-cli <设备ID> [选项]` 为默认连接方式，`view <设备ID>` 保留为兼容别名。设备 ID 是格式示例，使用时替换为你有权访问的设备，密码通过隐藏提示输入：
|
||||
|
||||
```sh
|
||||
crossdesk-cli 123456789 --renderer kitty
|
||||
crossdesk-cli 123456789 --renderer ansi --zoom native
|
||||
crossdesk-cli 123456789 --quality balanced --fps 8
|
||||
crossdesk-cli 123456789 --display 1
|
||||
```
|
||||
|
||||
默认请求 `high` 画质（最高 1920 × 1080），`--display` 的索引从 `0` 开始。交互 CLI 默认本地输出目标为 30 FPS，远端供帧会随输出耗时自适应；显式 `--fps` 固定目标和相应预览请求，实际帧率仍取决于设备、终端与链路。更多参数见 [主 README](../../README.md#cli) 和 [终端使用指南](docs/terminal-client.md)。
|
||||
|
||||
## 查看、控制与退出
|
||||
|
||||
| 操作 | 按键 |
|
||||
| --- | --- |
|
||||
| 开启远端控制 | 只读模式下按 `c` |
|
||||
| 放大局部 / 回到全景 | 只读或本地命令模式下按 `d` / `f`；只读时也可点击目标进入细节 |
|
||||
| 缩放 / 平移 | 只读或本地命令模式下用 `+/-` 或滚轮缩放；方向键或 `i` 上、`j` 左、`k` 下、`l` 右平移 |
|
||||
| 暂停远端输入并进入本地命令模式 | `Ctrl+]` |
|
||||
| 选择返回后的控制状态 | 本地命令模式下按 `c`，再按 `Esc` / `Ctrl+C` 返回 |
|
||||
| 退出连接 | 只读模式下按 `q` / `Ctrl+C`；控制模式下先按 `Ctrl+]`，再按 `q` |
|
||||
|
||||
本地命令模式在缩放、平移和按 `c` 后持续保持，直到手动返回。控制模式中的 `Ctrl+T`、`Ctrl+C` 和普通按键均传给远端。再次按 `Ctrl+]` 也可离开本地命令模式，若返回控制模式则同时向远端发送该组合键。
|
||||
|
||||
## 更多文档与功能范围
|
||||
|
||||
- [构建、使用、Pi 安装和故障排查](docs/terminal-client.md)
|
||||
- [私有桥接协议](docs/bridge-protocol.md)
|
||||
|
||||
@@ -2,16 +2,24 @@
|
||||
|
||||
## 使用方式
|
||||
|
||||
完整版本发布后的统一入口如下。构建产物或部分平台包上传成功，不代表入口包和全部平台依赖已经可用；发布者须完成本文的注册表检查。
|
||||
从 [@chunkdash/crossdesk-cli](https://www.npmjs.com/package/@chunkdash/crossdesk-cli) 安装统一入口，npm 会选择对应系统和架构的原生平台包。需要 Node.js 22 或以上和 npm，无需本机编译工具链。
|
||||
|
||||
```sh
|
||||
npm install -g @chunkdash/crossdesk-cli@latest
|
||||
crossdesk-cli doctor --json
|
||||
crossdesk-cli 123456789
|
||||
```
|
||||
|
||||
更新时重新执行同一条 `npm install -g @chunkdash/crossdesk-cli@latest`。将示例 ID 替换为被控电脑的 9 位 ID，密码在连接时隐藏输入；`doctor` 只检查本机环境，不建立远程连接。
|
||||
|
||||
无需全局安装时使用 `npx`，首次运行会下载对应平台包：
|
||||
|
||||
```sh
|
||||
npx @chunkdash/crossdesk-cli@latest doctor --json
|
||||
npx @chunkdash/crossdesk-cli@latest 123456789
|
||||
npm install -g @chunkdash/crossdesk-cli
|
||||
crossdesk-cli 123456789
|
||||
```
|
||||
|
||||
需要 Node.js 22 或以上和 npm。启动器根据 Node 的 `process.platform` / `process.arch` 选择同版本的 `@chunkdash` 平台包，直接启动原生 C++ 程序，继承终端、工作目录、环境变量和命令参数。安装过程不下载外部可执行文件、不执行 postinstall、不在用户机器编译。不要使用 `--omit=optional`，否则对应平台包不会安装。
|
||||
启动器根据 Node 的 `process.platform` / `process.arch` 选择同版本的 `@chunkdash` 平台包，直接启动原生 C++ 程序，继承终端、工作目录、环境变量和命令参数。原生可执行文件随 npm 平台包下载，安装过程不执行 postinstall，也不在本机编译。不要使用 `--omit=optional`，否则对应平台包不会安装。
|
||||
|
||||
入口包名为 `@chunkdash/crossdesk-cli`，`bin` 声明的终端命令仍为 `crossdesk-cli`。如已全局安装旧的无 scope 入口，先执行 `npm uninstall -g crossdesk-cli`，再安装 scoped 入口，避免两个包争用同一个命令。原来的 `crossdesk-cli@0.1.0` 是独立的旧包，改名不会更新它或自动迁移已有安装。
|
||||
|
||||
|
||||
@@ -35,9 +35,25 @@ On **2026-10-25**, 16 images were rendered from the actual Slint components at `
|
||||
| `desktop-stream-video-settings-*.png` | 会话工具栏与画面设置 / Session video settings | 1920 × 1200 |
|
||||
| `desktop-about-*.png` | 关于与检查更新 / About and update check | 1280 × 944 |
|
||||
| `web-client.png`（中文） | Web 连接首页 / Web connection page | 1280 × 720 |
|
||||
| `cli-ansi-overview.png` | CLI ANSI 四象限全景 / ANSI quadrant overview | 1600 × 960 |
|
||||
| `cli-kitty-overview.png` | CLI Kitty 协议像素全景 / Kitty protocol pixel overview | 1600 × 960 |
|
||||
|
||||
桌面图片使用 2× 原生渲染缩放，捕获窗口内容区，不包含 macOS 原生标题栏。未放大旧 UI 截图，也未重绘控件；演示远端画面由实际组件按比例显示。Markdown 只设置展示宽度。常规设置可滚动，`desktop-settings` 展示首屏，`desktop-settings-network` 展示网络连接分组；Windows 专属采集方式与便携版服务入口不会出现在这些 macOS 图片中。
|
||||
|
||||
<a id="cli-captures"></a>
|
||||
|
||||
## CLI 图示 / CLI captures
|
||||
|
||||
- **2026-10-31 04:39（UTC+8）重新采集**，使用在 macOS arm64 上从 `22796368` 构建的 release CLI，连接同一用户授权的被控设备，分别采集 ANSI 与 Kitty 输出。两次连接均保持只读；图示展示远端当前的动画窗口，替换此前的桌面壁纸画面。
|
||||
- 使用工程外的 POSIX 伪终端采集器，视口为 **160 列 × 48 行**，每格 **10 × 20 像素**，输出 PNG 为 **1600 × 960**。顶栏与底部快捷键直接来自 CLI 输出；图示不包含连接密码或真实设备 ID。
|
||||
- ANSI 图由实际转义序列恢复字符网格及前景／背景色，四象限字符按对应的色块渲染。Kitty 图由 CLI 内联发送的 zlib / Base64 RGB 帧解码，按协议 placement 的行列尺寸显示；采集器只提供内联图像能力，不支持共享内存。
|
||||
- 这些图片是**实际 CLI 输出的渲染图**。Ghostty 和 macOS「终端」窗口的自动化访问被工具拒绝，未取得原生窗口截图，也未据此完成这两款应用的实窗验收。字体栅格、图像缩放和显示时序由采集器处理，不能用图中 FPS 推断 Ghostty 或其他终端的实际显示性能。
|
||||
- 构建配置、采集脚本、原始输出与中间产物均存放在工程外临时目录；工程内只保存最终图示及文档。示例命令使用占位 ID，凭据通过隐藏提示输入。
|
||||
|
||||
Refreshed at **04:39 (UTC+8) on 2026-10-31** with a macOS arm64 release CLI built from `22796368`, using real read-only connections to the same authorized host. Both images now show the animation window on the remote desktop, replacing the previous wallpaper views. An external POSIX PTY collector reports 160 × 48 cells at 10 × 20 pixels and renders the actual CLI output to PNG. The ANSI image reconstructs character cells and colors; the Kitty image decodes inline RGB frames and applies their placement dimensions. The collector does not support shared-memory images. These are output renderings; native Ghostty and macOS Terminal window access was denied by the automation tool. They do not validate either application's window rendering or display performance. Passwords and real device IDs are omitted. Capture scripts, raw output, build configuration, and intermediate files stay outside the repository.
|
||||
|
||||
重新采集时，使用 release CLI，在支持相应协议的终端或 PTY 采集器中分别运行 `crossdesk-cli <设备ID> --renderer ansi --quality high` 和 `crossdesk-cli <设备ID> --renderer kitty --quality high`，通过隐藏提示输入密码，等待顶栏显示 `Displaying` 后捕获完整视口，再按 `q` 退出。若使用 PTY 采集器，须正确处理终端尺寸回复、ANSI 光标与颜色、Kitty 探测、分块上传和 placement 缩放，并在图注中明确采集方式。更新图片前检查敏感信息、画面比例和状态栏完整性，并同步更新本节的日期、版本与验证范围。
|
||||
|
||||
## 重新生成 / Regenerate
|
||||
|
||||
以下命令在已配置依赖的 macOS 工程根目录执行。生成程序只渲染演示状态；所有临时源码、可执行文件和 PPM 均存放在工程外，确认图片后才将 PNG 复制进 `docs/images`。`sips` 仅做无损格式转换，图片没有重绘或后期修改。
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 908 KiB |
Reference in New Issue
Block a user