mirror of
https://github.com/kunkundi/crossdesk.git
synced 2026-11-02 20:12:44 +08:00
[feat] integrate CrossDesk CLI with terminal rendering and npm packaging
This commit is contained in:
dijunkun
@@ -0,0 +1,35 @@
|
||||
# Bridge v1（CrossDesk 私有协议，不是 MCP）
|
||||
|
||||
启动：`crossdesk-cli bridge --stdio [--password-fd 3] [--server host] [--port 9099] [--quality low|balanced|high|ultra]`。
|
||||
通过参数数组启动，不经 shell。stdin/stdout 为 UTF-8 NDJSON，每行一个完整 JSON。stdout 使用保留的描述符，底层 stdout 重定向到 stderr。宿主应消费/隔离 stderr，不能展示为视频行或模型消息。bridge 不要求 TTY。
|
||||
|
||||
每条请求含整数 `id` 和字符串 `method`。响应含同一 `id`、布尔 `ok`，成功时还含 `version:1`、完整 `status`；失败含固定 `error`（无效请求、版本或操作不可用等），不回显原输入/凭据。无有效 id 的错误为 null。事件没有 id。先 hello，再发送其他操作。
|
||||
|
||||
| method | 字段 | 行为 |
|
||||
|---|---|---|
|
||||
| hello | version:1 | 协议版本握手 |
|
||||
| viewport | columns:1..240, rows:1..100, colors:8/24/256, utf8:boolean, fps:1..30；可选 detail:quadrant/half, quality:low/balanced/high/ultra, zoom:1..32, native:boolean | 设置画面行数（不含状态栏）、本地目标与预览档位；默认 quadrant/high/1、native=false，保留未显式指定的 detail/quality/zoom/native；不探测宿主 TTY |
|
||||
| connect | device:9位数字字符串, display:0..63（默认0） | 从专用 password fd 读取至换行/EOF（最多256字节、等待5秒），开始异步注册/连接；ok不是远端已连接 |
|
||||
| status | 无 | 返回当前状态 |
|
||||
| control | enabled:boolean | 显式启停控制；关闭时释放输入 |
|
||||
| input | data:string，最多16KiB | 终端原始按键/UTF-8/bracketed paste/SGR鼠标；只读时不发送到远端，1/鼠标点击进入细节，+/-/滚轮缩放，方向键/hjkl 平移，0 全景；本地 Ctrl+] 退出，Ctrl+T 切换控制 |
|
||||
| display | index:0..63 | 选择已广告的零起始显示器，提升 generation |
|
||||
| ack | frame_id、generation：非负整数 | 确认宿主消费帧；匹配当前等待帧才开放下一帧 |
|
||||
| disconnect | 无 | 释放输入、结束当前媒体会话 |
|
||||
| exit | 无 | 断开并结束进程 |
|
||||
|
||||
凭据不能放在 connect JSON 中。专用描述符可以由 Node `spawn` 的第四条 pipe 提供。成功读取后会话不会保留用户密码供上层访问；MiniRTC 内部为现有 Join/重连流程持有必要凭据直到销毁 Peer。下一次 connect 必须有可读的凭据来源；Pi 关闭视图后直接结束进程。
|
||||
|
||||
帧事件：
|
||||
|
||||
```json
|
||||
{"event":"frame","frame_id":42,"decoded_frame_id":38,"generation":4,"source_width":1280,"source_height":720,"zoom":2,"native":false,"source_rect":[320,180,640,360],"detail":"quadrant","columns":80,"rows":23,"lines":["..."],"queue_ms":3.2}
|
||||
```
|
||||
|
||||
实际 lines 数为 rows，仅包含本地生成的 SGR 颜色序列、空格和 U+2580～U+259F 块字符，不含远端名称或任意终端指令。`frame_id` 是进程递增的输出序号，静止画面重绘仍产生新序号；`decoded_frame_id` 标识源解码帧，同源重绘可以相同。`source_width/height` 为实际解码尺寸，source_rect 为实际源裁剪矩形 [x,y,width,height]。native=true 表示原始细节模式，zoom 为当前模式下的倍率；generation 在关闭、重新连接和显示器切换时变化。viewport 变化可能与已写出的旧尺寸帧交错，宿主应丢弃不匹配尺寸/旧 generation 的帧并释放对应 ACK。宿主返回的 ACK 表示消费/布局，不表示屏幕物理显示完成。
|
||||
|
||||
状态事件每秒最多一次：`{"event":"state","status":{...},"output_bytes":123,"submitted_frames":3,"elapsed_seconds":1.5}`。status 含 registering/connecting/connected/failed/closed/idle、client_id（当前或刚结束会话的 `cli-xxxxxxxxx`，注册前为空）、error、control、generation、显示器、文本/预览能力、预览确认状态、请求的 preview_width/height/quality/bitrate_bps、帧计数与网络统计。接收/提交 FPS 由相应计数的增量除以时间增量计算。
|
||||
|
||||
边界：输入每条及当前解析缓冲上限64KiB、嵌套32层；响应队列64条；输出一条在途消息上限2MiB；1MiB/s；最多一条待 ACK 帧；一个最新待渲染 NV12 加一个最近画面的重绘缓存。协议错误明确响应；超限缓冲后结束。EOF 清理会话，完整的已收请求按序处理，不完整末尾报错；最多两秒排空输出后退出。宿主应持续消费响应，不能无限发送而不读取。失去连接后的释放只能尽力发送。
|
||||
|
||||
没有 `screenshot`、`audio`、文件、剪贴板、任意远端动作或 shell 命令方法；未知方法报错。模型接入者必须另行取得截图/自动操作授权，不能把持续帧事件附加到聊天记录。
|
||||
@@ -0,0 +1,82 @@
|
||||
# npm 分发与平台兼容性
|
||||
|
||||
## 使用方式
|
||||
|
||||
发布后的统一入口如下；本仓库当前尚未向 npm 发布，不能把这些命令当成已经上线的服务。
|
||||
|
||||
```sh
|
||||
npx crossdesk-cli@latest doctor --json
|
||||
npx crossdesk-cli@latest view 123456789
|
||||
npm install -g crossdesk-cli
|
||||
crossdesk-cli view 123456789
|
||||
```
|
||||
|
||||
需要 Node.js 22 或以上和 npm。启动器根据 Node 的 `process.platform` / `process.arch` 选择同版本的平台包，直接启动原生 C++ 程序，继承终端、工作目录、环境变量和命令参数。安装过程不下载外部可执行文件、不执行 postinstall、不在用户机器编译。不要使用 `--omit=optional`，否则对应平台包不会安装。
|
||||
|
||||
## 平台与终端
|
||||
|
||||
| 平台 | 原生包 | 终端适配与运行边界 |
|
||||
| --- | --- | --- |
|
||||
| macOS Apple Silicon | `crossdesk-cli-darwin-arm64` | POSIX TTY；具体最低系统版本写入包内 `build-info.json` |
|
||||
| macOS Intel | `crossdesk-cli-darwin-x64` | POSIX TTY；最低系统版本同上 |
|
||||
| Linux x64 | `crossdesk-cli-linux-x64` | glibc、libstdc++、zlib；所需 GLIBC / GLIBCXX 版本写入 `build-info.json` |
|
||||
| Linux arm64 | `crossdesk-cli-linux-arm64` | 同上 |
|
||||
| Windows x64 | `crossdesk-cli-win32-x64` | Windows 10 或以上，原生 Console / ConPTY 与 VT 输出 |
|
||||
| Windows arm64 | `crossdesk-cli-win32-arm64` | Windows 11 ARM，原生 Console / ConPTY |
|
||||
|
||||
这些是构建与分发目标，不代表均已实机通过。当前完整构建与 npm 运行验证只覆盖 macOS arm64；CLI 主程序与平台 I/O 已通过 Windows / Linux x64、arm64 的交叉编译检查。其他平台的完整 MiniRTC 链接、实际视频连接、键鼠、终端恢复仍需对应机器验收。
|
||||
|
||||
普通终端使用 ANSI 渲染，按能力选择 TrueColor / 256 色 / 基础色；Kitty 图形协议是可选增强。macOS Terminal、iTerm2、Linux 常用终端、Windows Terminal 和 VS Code 集成终端属于目标场景。SSH 应分配 PTY（`ssh -t`）；tmux / screen 使用 ANSI。不支持 `TERM=dumb` 或把交互观看输出重定向到文件；非交互宿主使用 `bridge --stdio`。Alpine / musl 当前没有预编译包。Windows 独立 mintty 窗口可能不提供 Console / ConPTY，应使用 Windows Terminal 承载 Git Bash。
|
||||
|
||||
CI 的 macOS 构建配置指定 `--target_minver=13.0`，但最终必须检查实际产物及依赖。当前开发机的本地二进制最低要求为 **macOS 27.0**，不应将这个本地产物宣称为旧 macOS 通用版。
|
||||
|
||||
## 生成包
|
||||
|
||||
先按 [构建说明](terminal-client.md) 构建 release，再执行：
|
||||
|
||||
```sh
|
||||
npm --prefix apps/cli run pack:npm
|
||||
```
|
||||
|
||||
脚本读取 `apps/cli/package.json` 与 `apps/cli/xmake.lua` 的版本，检查二者一致；确认源码中的 MiniRTC 日志脱敏补丁已应用，再检查当前平台二进制格式、CPU、动态链接依赖，并运行离线 `doctor --json`。macOS 只接受系统动态库，Linux 只接受列明的基础系统运行库，Windows 拒绝未随产品处理的 DLL 和动态 MSVC 运行库。Windows 在含 `dumpbin.exe` 的 Visual Studio 开发者环境中运行打包。脚本预先检查两个输出文件是否存在，并在临时目录中完成两个包后再写入输出目录；写入失败时清理本次已写入的包，已有同名产物不会被覆盖。
|
||||
|
||||
默认从 `build/<platform>/<arch>/release/` 读取原生程序，将两个 `.tgz` 写入 `build/npm/`。可指定路径：
|
||||
|
||||
```sh
|
||||
npm --prefix apps/cli run pack:npm -- --binary /absolute/path/crossdesk-cli --out-dir /absolute/path/output
|
||||
```
|
||||
|
||||
每台构建机生成当前平台的原生包与相同版本的通用启动包。`apps/cli/npm/platforms.json` 集中定义六个平台；启动包通过精确版本的 `optionalDependencies` 让 npm 仅安装匹配系统和 CPU 的原生包。原生包包含二进制、运行要求、SHA-256，以及当前控制端和已应用修补的 MiniRTC 源码快照。外部 Xmake 依赖的许可证、对应源码和重链接材料需要随正式版本一并提供，参见 [源码来源](source-provenance.md)。源码快照已含 MiniRTC，解包后无需运行 `prepare-deps.sh`；在 `source/` 目录按上述构建说明显式关闭桌面、开启 CLI，再构建 `crossdesk-cli`。源码包仅包含 CLI 及其依赖，不包含桌面或移动应用。
|
||||
|
||||
`apps/cli/package.json` 的 `private: true` 表示源码目录不是发布产物。只发布打包脚本生成的 tarball；生成的包不带 private 标记。
|
||||
|
||||
## 本地安装验证
|
||||
|
||||
以 macOS arm64 为例，用生成包的绝对路径，在工程外的临时目录执行：
|
||||
|
||||
```sh
|
||||
npx --yes --offline \
|
||||
--package /absolute/path/crossdesk-cli-darwin-arm64-0.1.0.tgz \
|
||||
--package /absolute/path/crossdesk-cli-0.1.0.tgz \
|
||||
-- crossdesk-cli doctor --json
|
||||
```
|
||||
|
||||
也可先 `npm install --ignore-scripts` 安装这两个本地 tarball，再使用安装目录中的 `crossdesk-cli`。验证交互观看需要真实 TTY 与授权的被控端，doctor 不会建立远程连接。
|
||||
|
||||
Pi 等宿主应直接启动原生程序以可靠控制进程和专用密码描述符。全局安装后，用 `crossdesk-cli --print-binary-path` 获取路径，再将该路径设为 `CROSSDESK_CLI`；不要把整条 npx 命令放进此变量。
|
||||
|
||||
## CI 与发布
|
||||
|
||||
`.github/workflows/build-cli.yml` 配置六个平台的原生 release 构建、doctor 和打包，并上传 tarball；该工作流不执行 npm publish。工作流随 CLI 整合到 CrossDesk；本次本地整合未触发远程 CI。
|
||||
|
||||
正式发布时，先发布全部对应版本的原生包，再发布通用 `crossdesk-cli` 包。例如：
|
||||
|
||||
```sh
|
||||
npm publish crossdesk-cli-darwin-arm64-0.1.0.tgz --access public
|
||||
# 同样发布其余五个平台的原生包后，再发布入口包。
|
||||
npm publish crossdesk-cli-0.1.0.tgz --access public
|
||||
```
|
||||
|
||||
发布需要目标 npm 包的权限；当前名称只是配置值，查询时注册表返回未找到，不等于已经获得名称所有权。每次版本发布同步更新 `apps/cli/package.json` 和 `apps/cli/xmake.lua`。缺失平台包时启动器明确报错，不下载别的平台程序或回退为源码编译。
|
||||
|
||||
依据：[npm bin / optionalDependencies / os / cpu](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/)、[npx](https://docs.npmjs.com/cli/v11/commands/npx/)、[GitHub runner 平台](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)、[Windows Console 模式](https://learn.microsoft.com/en-us/windows/console/getconsolemode)。
|
||||
@@ -0,0 +1,15 @@
|
||||
# 源码来源
|
||||
|
||||
CLI 从独立开发目录整合到 CrossDesk，入口、打包脚本、npm 启动器和 Pi 扩展位于 `apps/cli`，会话和终端渲染实现分别位于 `libs/controller`、`libs/terminal`。
|
||||
|
||||
- CrossDesk 仓库：`https://github.com/kunkundi/crossdesk.git`。独立 CLI 的协议代码原取自 `becd1c0437f6c4fad757052c70db1eba71cf312f`；整合时目标仓库基于 `2f57d0ab`，两边 wire 源文件一致，直接复用现有 `libs/wire`。
|
||||
- MiniRTC：`https://github.com/kunkundi/minirtc.git`，固定提交 `b9ee1fa7fe038fdf771f5dec1b1d561d78273f15`。该提交基于整合前的 `cdcd0d8fb0e9b688f3bf6416fe52b634cf20d9ca`，仅增加下述四处凭据日志脱敏修改。
|
||||
- `ControllerSession` 的流名称、HostInformation 和输入参考 Android `rtc_bridge.cpp`；身份使用单 Peer 的 `cli` 临时注册协议；终端适配不依赖 JNI、Surface 或 GuiRuntime。
|
||||
- 帧缓存遵守 `MiniRtcVideoFrame` 回调借用契约，直接复制到有界 CPU 存储，不跨回调保留 native 指针。
|
||||
- PreviewSubscription 复用 wire 实现与对端 capability 字段，不新增被控端协议。
|
||||
|
||||
`deps/patches/minirtc-credential-logs.patch` 是 CLI 所需的 MiniRTC 修补：Join、排队 Join、取消 Join、Leave 四个日志点只记录 `@` 前的 ID，不记录密码。`apps/cli/scripts/prepare-deps.sh` 验证固定版本并幂等应用补丁，CLI 构建检查补丁已存在。共享子模块中的脱敏同样适用于桌面程序；补丁没有改变鉴权、TLS、TURN 或媒体协议。
|
||||
|
||||
npm 原生包携带 CLI、共享库、构建配置和已修补 MiniRTC 的源码快照，不复制桌面、移动端、测试或本机构建缓存。源码包保留仓库目录结构，在 `source/` 中配置 `--CROSSDESK_BUILD_DESKTOP=n --CROSSDESK_BUILD_CLI=y` 后构建。
|
||||
|
||||
LICENSE 沿用 CrossDesk GPL-3.0；MiniRTC 子模块保留其 LGPL-3.0 和第三方声明。外部 Xmake 依赖的许可证、对应源码及重链接材料仍需随正式版本提供。
|
||||
@@ -0,0 +1,127 @@
|
||||
# 终端客户端
|
||||
|
||||
## 构建与安装
|
||||
|
||||
要求 Git、Xmake >= 3.1.1、C++17 编译器、系统 zlib 头文件/链接库，以及 MiniRTC 包构建使用的系统工具。macOS SDK 已提供 zlib；Linux 需相应开发包（如 zlib1g-dev）；Windows 使用 Visual Studio C++ 构建工具，zlib 由 Xmake 获取并静态链接，运行库使用 MT。依赖需要可访问 Xmake 包仓库。Linux 使用 GCC/Clang；macOS 使用 Xcode 命令行工具。无需安装 Slint、SDL、X11、PulseAudio 或桌面采集 SDK。
|
||||
|
||||
```sh
|
||||
./apps/cli/scripts/prepare-deps.sh
|
||||
xmake f -y --CROSSDESK_BUILD_DESKTOP=n --CROSSDESK_BUILD_CLI=y --USE_CUDA=n -m release
|
||||
xmake build crossdesk-cli
|
||||
xmake run crossdesk-cli doctor --json
|
||||
```
|
||||
|
||||
`prepare-deps.sh` 固定 MiniRTC commit 并应用凭据日志脱敏补丁，可重复执行。构建会检查补丁，缺失时失败。不要直接升级子模块。仓库默认开启桌面构建、关闭 CLI。上述参数只构建 CLI；需要同时构建桌面和 CLI 时，将 `CROSSDESK_BUILD_DESKTOP` 设为 `y`。恢复默认桌面配置使用 `xmake f -y --CROSSDESK_BUILD_DESKTOP=y --CROSSDESK_BUILD_CLI=n`。所有命令均从仓库根目录执行。
|
||||
|
||||
构建产物在 `build/<platform>/<arch>/<mode>/crossdesk-cli`。可把对应目录加入 PATH 或复制可执行文件到自己的 bin 目录。Pi 需要直接启动该可执行文件，不能使用会输出构建日志的 `xmake run` 作为桥接程序。
|
||||
|
||||
macOS 的 MiniRTC 依赖仍链接 VideoToolbox/CoreMedia 和 GLib 声明的 AppKit 等系统框架；CLI 不创建 GUI、采集器或音频设备。硬件解码参数显式关闭。Linux 无需 DISPLAY/WAYLAND_DISPLAY；本轮尚未在 Linux 主机实际构建验证。
|
||||
|
||||
Windows 产物为 `build/windows/<arch>/release/crossdesk-cli.exe`；先在 Git Bash 中执行 `sh apps/cli/scripts/prepare-deps.sh`，然后可在开发者 PowerShell 中执行上述 Xmake 命令。Windows 使用 Console / ConPTY 的原生键盘、鼠标事件和 VT 输出，保存并恢复控制台模式与代码页；无需 WSL。Windows Terminal、现代 PowerShell / CMD 和 VS Code 的 ConPTY 终端属于目标运行环境，仍需实机验收。Git Bash 的独立 mintty 窗口没有原生控制台时，应从 Windows Terminal 的 Git Bash 配置启动。
|
||||
|
||||
预编译 npm 包的用户无需构建工具，见 [npm 分发](npm-distribution.md)。
|
||||
|
||||
## 连接与身份
|
||||
|
||||
```sh
|
||||
crossdesk-cli view 123456789
|
||||
crossdesk-cli view 123456789 --renderer ansi --fps 8 --quality high --zoom native
|
||||
crossdesk-cli view 123456789 --renderer kitty --quality ultra --zoom native --display 0
|
||||
crossdesk-cli view 123456789 --control
|
||||
crossdesk-cli view 123456789 --server your-server.example --port 9099
|
||||
```
|
||||
|
||||
设备 ID 必须是 9 位数字，以上数字仅示例。默认信令地址沿用当前 CrossDesk：`api.crossdesk.cn:9099`。密码从本地终端隐藏输入（POSIX `/dev/tty`、Windows `CONIN$` / `CONOUT$`），不提供密码命令行参数。CLI 不读取、不修改桌面配置。每次连接直接用 `cli` 请求服务端分配临时 `cli-xxxxxxxxx` ID（后缀为 9 位数字），注册、Join 和媒体使用同一个 Peer。CLI 仅作为控制端，不申请普通数字身份或 `C-` 身份，也不保存本机密码或重连凭据。每次启动或重新连接都会申请新的 ID；断开后服务端按 Web 临时身份的规则清理注册记录。
|
||||
|
||||
需先部署支持 `cli` 注册的新版 crossdesk-server；旧服务端会登录失败，本客户端不会回退为普通设备身份。桥接 `status.client_id` 返回服务端分配的 ID。
|
||||
|
||||
流程为创建主控 Peer、注册流 → 以 `cli` 注册 → SignalConnected 返回 `cli-xxxxxxxxx` → Join → Connected → 现有 HostInformation 握手 → 显示器选择、能力协商 → 视频。Init 返回 0 不是远端连接成功。连接总超时默认 30 秒；信令断开后结束本次会话，用户重新连接，不自动循环重试密码。
|
||||
|
||||
保留 MiniRTC WSS 证书链与主机名验证、TURN 临时凭据下发及 SRTP 协商。未提供跳过证书检查的参数。SRTP 是否实际协商成功通过状态统计呈现；沿用现有 MiniRTC 对旧端的兼容性，不宣称所有旧端必然启用 SRTP。自建证书问题应修复证书/系统信任链。
|
||||
|
||||
## ANSI、Kitty 与 SSH
|
||||
|
||||
ANSI 默认使用四象限字符：每个字符从 2×2 样本选择误差最小的两个颜色和象限形状，比原先上下半方块多一倍水平采样点；每个字符仍只有前景/背景两色。使用 `--ansi-detail half` 可回到上下半方块以兼容字体。缩小时采用面积加权滤波，避免最近邻采样漏掉细线。支持 TrueColor、256 色和基础 8 色，256 色选择实际颜色立方体或灰阶条中更接近的颜色。环境的 COLORTERM/TERM 决定颜色模式；非 UTF-8 locale 使用背景色空格。TERM=dumb、非 TTY 输出明确拒绝 view，不输出全屏转义序列。
|
||||
|
||||
画面按字符单元比例等比缩放，留黑边及状态栏，默认假定字符宽高比 0.5；TTY 提供像素尺寸时使用其比例。每次只输出变化行，合并连续颜色设置；缩放在完整输出边界清理旧画面。上限 240 列、100 画面行；默认预留两行及一列，避免自动换行。
|
||||
|
||||
ANSI 在完整桌面缩略图中仍无法保留普通字号的文字。先增加终端列数（缩小终端字体或扩大窗口），阅读局部时用 `--zoom native`。只读全景中点击目标位置可直接进入该区域的细节模式；按 `1` 则以当前中心进入。细节模式依据视口和字符宽高比选择源区域，避免为了完整装入桌面而把文字缩小；ANSI 视野较小，借助方向键平移阅读。`--zoom 1..32` 是相对整桌面的倍率；在细节模式中 `+/-` 是相对原始细节尺寸的倍率。画面缩放完全在本地进行，控制鼠标坐标映射回原始桌面的正确区域。
|
||||
|
||||
auto 模式发送 Kitty 查询与设备属性查询，等待最多 250ms；没有有效 Kitty 回应就用 ANSI。显式 kitty 模式探测失败时报错。tmux/screen 中 auto 使用 ANSI，显式 kitty 报不支持；不修改用户终端配置。
|
||||
|
||||
Kitty 通过终端字节流发送 zlib 压缩的内联 RGB/Base64（每块至多 4096 字符），不使用远端临时图片文件。图像固定 ID=31、placement=1，更新同一图像，退出删除。依据终端报告的像素尺寸生成画面（未知时按 10×20 像素字符估算），上限 1920×1080。保留黑边和宽高比；原始细节模式按像素视口裁取源区域，避免整桌面缩小。没有可靠终端像素尺寸时使用估算值，因此不承诺显示设备的物理像素一一对应。压缩后超出单次输出预算时逐级降低尺寸。高熵视频压缩率较低，同一输出预算下实际帧率可能低于目标。RGB 压缩无损，不代表上游视频编码无损。
|
||||
|
||||
```sh
|
||||
ssh -t your-server
|
||||
crossdesk-cli view 123456789 --renderer ansi --fps 8
|
||||
```
|
||||
|
||||
用户本地终端负责显示 SSH 字节流。ANSI、Kitty over SSH 和 SSH+tmux 的实机互通尚未验证。无 GUI 指主控客户端；被控端仍需要可捕获的图形会话。
|
||||
|
||||
## 预览与背压
|
||||
|
||||
`--fps 1..30` 是本地输出目标。对端声明 PreviewSubscription 时，映射到合法 1/8/15 FPS（15 需要对应能力）；普通编码设置仍使用合法 30 FPS。分辨率上限使用协商到的 v2，视频预算只在 bandwidth 能力存在时发送。`--quality low|balanced|high|ultra` 对应如下请求：
|
||||
|
||||
| 档位 | 分辨率上限 | 质量枚举 | 视频预算 |
|
||||
|---|---|---|---|
|
||||
| low | 640×360 | 0 | 1Mbps |
|
||||
| balanced | 1280×720 | 1 | 2.5Mbps |
|
||||
| high（默认） | 1920×1080 | 2 | 6Mbps |
|
||||
| ultra | 3840×2160 | 2 | 12Mbps |
|
||||
|
||||
这些是请求上限，实际视频尺寸与码率由被控端决定，ultra 不会把低分辨率源变成真实 4K。低带宽链路可显式选择 balanced/low。窗口缩小不会再把远端预览降到字符网格尺寸；选定清晰度用于后续局部放大。旧端继续基础观看并本地限帧缩放，不发送未声明的扩展。预览 request_id/ack/accepted 可从桥接状态检查；未确认或被拒绝不冒充成功，也不阻止基础视频。
|
||||
|
||||
媒体回调仅同步复制借用的 NV12 数据，校验尺寸、容量、native 描述符与 stride；不保留借用指针。上限单帧 16,777,216 像素、每边 8192、偶数尺寸。最多一个待转换帧，替换前先完成校验与复制，无效帧不会挤掉已有画面；播放器另保留最近转换的一帧用于静止桌面的本地放大/重绘，并在接收新帧时回收上一帧缓冲区供后续复制使用。只丢弃解码后图像。显示器切换/关闭提升 generation，旧帧失效。
|
||||
|
||||
转换与输出在拥有会话的事件循环，媒体回调独立。输出至多一个完整消息（2MiB），以 1MiB/s 令牌预算分块非阻塞写入；不能开始新画面时保留最新解码帧。ANSI 差分基准只在整帧输出完成后提交。Pi 桥接另要求消费帧 ACK，最多一帧等待 ACK，输入映射只在对应 ACK 后切换到新网格。状态栏优先在完整画面输出之间更新，避免大图持续刷新时状态饥饿；可写事件唤醒短写重试，仍遵守字节预算。控制事件至多 64 条，协议输入 64KiB/嵌套 32 层，输入粘贴缓冲 32KiB，文本单次最多 16KiB。
|
||||
|
||||
统计包括收到帧数、被替换帧数、非法帧、等待帧数、实际完整提交次数、输出字节数、运行秒数、最近本地排队时间、网络码率/RTT/SRTP。通过计数差/时间差可得到区间 FPS；view 结束日志另给平均提交 FPS。写入 TTY 完成不等于屏幕显示完成，本地排队时间不是端到端延迟。
|
||||
|
||||
## 输入与退出
|
||||
|
||||
默认只读、静音。`--control` 或 Ctrl+T 明确启用输入；Ctrl+T 再次关闭并释放已记录按键/鼠标。Ctrl+] 始终退出；控制模式下 q 是远端文本。Ctrl+T 和 Ctrl+] 是保留本地组合，目前不可重绑定。
|
||||
|
||||
只读时，`1` 或在画面中单击进入该位置的原始细节模式；`+` / `=` 放大、`-` 缩小（1～32倍），滚轮以鼠标指向为中心调整倍率。方向键或 `h/j/k/l` 向左/下/上/右平移，`0` 恢复完整画面。黑边点击被忽略。这些按键和鼠标在控制模式下仍传给远端；调整视图时先 Ctrl+T 切回只读。放大、平移和只读鼠标定位不会向远端发送操作，也适用于静止画面。
|
||||
|
||||
支持 SGR 鼠标移动、左右中键、拖动和滚轮；黑边不发送新点击，黑边处松开仍释放旧按钮。输入坐标映射到所选显示器，`--display` 是 HostInformation 列表的零起始索引，视频流为 Display1、Display2……
|
||||
|
||||
支持 UTF-8 文本与 bracketed paste（远端须声明 text_input），Enter、Tab、Backspace、Esc、方向、Home/End、Delete、PageUp/Down、F1–F4、Ctrl/Alt+英文字母。不支持的远端文本能力会提示，不把粘贴执行为本地 shell 命令。普通终端采用立即按下/释放的 tap 策略；不承诺持续按键、所有组合键、IME 或完整键盘布局。Pi 使用宿主 SDK 解码增强按键后转为这组基础输入。
|
||||
|
||||
失焦报告、关闭控制、切换显示器、退出和断开都尝试释放已记录输入；网络已中断时不能保证远端收到释放。正常退出在普通执行路径恢复终端模式、鼠标报告、光标、自动换行和备用屏幕。POSIX 同样处理 SIGINT/SIGTERM/SIGHUP；Windows 处理控制台 Ctrl+C / Ctrl+Break，恢复控制台模式与代码页。中止时最多等待两秒排空当前画面，随后发送取消/终止转义序列并恢复；输出连接彻底损坏或 SIGKILL 时无法保证恢复，可在 shell 执行 `reset`。
|
||||
|
||||
只读是本客户端行为限制，不是服务端强制的独立只读授权。没有文件/剪贴板/远端命令接收处理器。
|
||||
|
||||
## Pi 扩展
|
||||
|
||||
依据已下载的 `@earendil-works/pi-coding-agent` 与 `pi-tui` **1.4.0** SDK 实现和类型检查。旧的 `@mariozechner` 包未验证，缺少 ctx.mode 的宿主会降级。
|
||||
|
||||
```sh
|
||||
export CROSSDESK_CLI="$PWD/build/macosx/arm64/release/crossdesk-cli"
|
||||
pi -e ./apps/cli/plugins/pi/index.ts
|
||||
```
|
||||
|
||||
在 Pi 输入 `/crossdesk` 或 `/crossdesk 123456789`。先输入 ID，再在自定义遮蔽组件输入密码。扩展使用独立 fd 3 写密码，随后关闭；不写配置、聊天、工具结果或模型上下文。键盘 Ctrl+] 关闭，Ctrl+T 开关控制。插件默认请求 high 预览并显示 ANSI 象限字符行，支持同样的只读细节/放大/平移键，颜色深度依据终端环境回退，由 Pi 自身布局和刷新；不直接占用 TTY，不发送 Kitty 图形或自行打开鼠标报告。
|
||||
|
||||
需要全局发现时，把整个 `apps/cli/plugins/pi` 目录复制到 `~/.pi/agent/extensions/crossdesk/` 后重启 Pi 或执行 `/reload`。卸载时先关闭视图，删除该目录并 `/reload`；使用 `-e` 时从启动参数移除即可。无需修改包中的密码或设备配置。默认连接官方信令；自建信令当前通过独立 view 命令使用，插件尚无服务器设置界面。
|
||||
|
||||
仅在 `ctx.mode === "tui"`、hasUI 且进程双向 TTY 时打开组件。RPC/print/json 返回独立播放器提示，不声称内嵌视频。UI 关闭/会话退出先关闭 bridge stdin，超时 SIGTERM，再超时 SIGKILL。桥接异常会显示在仍可 Ctrl+] 退出的组件内。SDK 类型和模拟 UI 生命周期已验证，真实 Pi TUI 视觉刷新、增强按键与鼠标传递未实机验收。真实设备的 bridge 与独立 view 验证见 [验证记录](validation.md)。
|
||||
|
||||
官方依据：[扩展文档](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md)、[TUI 文档](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/tui.md)、[Kitty 图形协议](https://sw.kovidgoyal.net/kitty/graphics-protocol/)。
|
||||
|
||||
## 故障排查与边界
|
||||
|
||||
- `incorrect_password`：重新启动并输入正确密码，不自动重复尝试。
|
||||
- `device_not_found` / `device_offline_or_unavailable`：核对 ID、服务端和被控端在线状态。
|
||||
- `signaling_login_failed` / `signaling_disconnected`：检查服务器、网络、代理、防火墙；确认服务端已支持 `cli` 注册。
|
||||
- `cli_identity_not_supported`：服务端未返回有效的 `cli-` 加 9 位数字的身份，需升级或检查服务端。
|
||||
- `tls_certificate_error`：检查证书链、主机名、机器时钟和系统 CA，不关闭验证。
|
||||
- `connection_timeout` / `connection_failed`：检查 NAT/TURN 与被控端。TURN 凭据只取服务端下发值。
|
||||
- `display_not_available`：换成远端声明的索引；单会话一次只显示一个屏幕。
|
||||
- `media_initialization_failed`：检查编译依赖和本地媒体运行环境。
|
||||
- 只读下按键无动作是预期；远端未声明文本协议时文本输入不可用。
|
||||
- 日志在进程创建的私有临时目录（POSIX `/tmp/crossdesk-cli-*`、Windows `%TEMP%\crossdesk-cli-*`）。view 的摘要在 client.log；底层诊断默认关闭且敏感 Join 日志已修补。目录不保存密码；使用完可删除。错误退出信息在恢复终端后显示。
|
||||
- `doctor --json` 是环境报告，不会联网登录、主动探测 Kitty 或证明远端可连接。
|
||||
|
||||
第一轮无音频播放或音频订阅 API，SSH 服务器上的声音不会传回本地。无后台守护进程、共享媒体 Broker、IP 直连、MCP 或自动截图。其他宿主可以使用 [私有桥接](bridge-protocol.md)，没有可靠自定义 UI 时打开独立终端或给出播放器命令。
|
||||
|
||||
每个播放器/桥接进程只拥有自己的一个媒体会话，不向模型消息发送视频。
|
||||
@@ -0,0 +1,40 @@
|
||||
# CLI 验证记录
|
||||
|
||||
## 本地仓库整合（2026-10-30）
|
||||
|
||||
环境为 macOS arm64、Xcode SDK 27.0、Xmake 3.1.1、C++17，关闭 CUDA。CLI 源码整合到 CrossDesk 的 `apps/cli`，共享现有 wire 与 MiniRTC；未新增或修改工程内测试。
|
||||
|
||||
- CLI 单独配置和 release 构建通过，目标为 `crossdesk-cli`；`doctor --json` 返回有效 JSON，动态链接依赖仅为系统库及框架，无 Slint / SDL。
|
||||
- 同时启用桌面与 CLI 时，debug 配置下 `crossdesk`、`crossdesk-cli` 均编译通过。
|
||||
- 原有仓库结构、wire 和键盘状态测试通过，未修改测试源码。
|
||||
- 工程外桥接检查通过：JSON 协议、版本校验、分片、EOF、消息上限、慢消费者、本地信令失败、凭据描述符和非 TTY 拒绝。
|
||||
- 工程外 POSIX PTY 检查通过：隐藏密码、无 DISPLAY/WAYLAND_DISPLAY、原始模式恢复、Kitty 探测超时和 tmux 下明确拒绝 Kitty。
|
||||
- macOS arm64 原生 npm 包和通用启动包生成成功；离线安装、启动器 `doctor` 和原生程序路径解析通过。该本地产物最低要求为 macOS 27.0。
|
||||
- 从原生包解出源码后，在没有 Git 元数据、没有桌面应用源码的目录中重新配置、构建 CLI 并运行 `doctor` 成功。
|
||||
- 验证后恢复整合前的桌面 debug 构建配置，CLI 默认关闭；新命令行二进制保留在 `build/macosx/arm64/release/crossdesk-cli`。
|
||||
|
||||
## 优化回归（2026-10-30）
|
||||
|
||||
- Release 构建、实际二进制 bridge/PTY 回归通过。ASan/UBSan 检查覆盖原有会话和渲染行为，以及无效帧保留、NV12 缓冲复用、预览参数去重、ACK 状态、重复断开和重连网络统计复位。
|
||||
- 生产 bridge 配合工程外假传输验证静止画面重绘、细节模式、质量切换、窗口变化、无效配置原子性和帧 ACK 背压，通过。
|
||||
- ANSI 渲染前后对比覆盖 8/24/256 色、UTF-8/ASCII、half/quadrant、全景/细节模式，输出校验值一致。在本机 240×100 网格连续执行 200 次差分生成，静止网格约 447.4 ms → 3.6 ms，单行变化约 422.8 ms → 9.5 ms。该结果只衡量差分文本生成，不包含视频解码、图像缩放和终端显示时间。
|
||||
- npm 真实打包、离线安装及源码包重建通过；工程外故障注入确认已有产物保留、第二个包生成失败时无半套输出、缺失脱敏补丁时拒绝打包。
|
||||
|
||||
新增回归代码、基准、假传输和验证产物均位于工程外临时目录，未向工程或子模块添加测试。此次完整构建与运行验证覆盖 macOS arm64，未重新进行 Linux/Windows 实机验证。
|
||||
|
||||
## 独立开发阶段的验证范围
|
||||
|
||||
以下为迁入前的验证记录摘要，不表示本次重新连接了远程设备：
|
||||
|
||||
- macOS arm64 的 debug/release 构建、CLI bridge 的 NDJSON、POSIX PTY 隐藏密码与终端恢复均已验证。
|
||||
- 工程外的 ASan/UBSan 检查覆盖会话状态、只读限制、输入释放、帧内存所有权、渲染、缩放和平移、输出背压和帧 ACK。
|
||||
- Pi 1.4.0 SDK 类型检查与模拟组件生命周期已验证；真实 Pi TUI 视觉效果未验收。
|
||||
- 早期身份协议版本曾连接真实设备进行只读 ANSI 观看和 Kitty 协议数据验证；Kitty 数据解压检查不等于 Kitty 应用或 SSH 实机显示验收。
|
||||
- 改为 `cli-` 临时身份后，正式 CLI 与本地 WSS 服务端验证了临时注册、Join、身份不可复用及退出清理；线上服务尚未在该轮部署，早期画面验证不能代替新身份协议的线上联调。
|
||||
- npm 的 macOS arm64 本地生成及安装已验证；Linux / Windows 当时仅完成 CLI 主程序和平台 I/O 的交叉编译检查，没有完整 MiniRTC 链接和实机连接结果。
|
||||
|
||||
## 实测边界
|
||||
|
||||
本地检查不涵盖 Linux / Windows 完整构建、跨平台远程控制、Kitty/SSH 实际终端显示、真实 Pi TUI 或长时间资源占用。六个平台 CI 配置与 npm 包名均不代表已发布或已验收。
|
||||
|
||||
CLI 需要支持 `cli` 临时注册的服务端。`doctor --json` 仅报告本机环境，不会联网登录或证明远端可连接。
|
||||
Reference in New Issue
Block a user