From 1320bb81a6bc837d18eeba6b6b78a79a88ce072b Mon Sep 17 00:00:00 2001 From: yuanyuanxiang <962914132@qq.com> Date: Thu, 19 Nov 2026 20:43:30 +0100 Subject: [PATCH] Docs: add client capability matrix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 docs/Client_Capability_Matrix.md,以 Windows 客户端为基线,按连接与传输、 远程桌面、文件管理、系统管理、监控审计、升级运维六类对比 Linux、macOS、 Android 的实现情况;另附平台前提与登录能力位对照。 - 主表所有行 Windows 均为 ✓,其他平台按客户端源码逐项核对(命令处理、能力位、 管理器实现),不依赖 README 描述。 - 明确 WS/WSS 是出包能力(四端网络层都支持),运行时协议切换仅 Windows;Android 剪贴板只写不读、进程管理需 root、缺关键帧请求与通用键盘注入;Linux 窗口列表 实际回空、多显示器只能整 X root;macOS 无分享/转移/自升级。 - 补充连接管理、切换显示器、视图偏好、调优/硬编码、文件复制粘贴、C2C 文本、 机器管理子项、RDP 维护、远程封禁等易漏能力,标注 Windows 独有或部分实现。 验证:独立审查代理对照 client/linux/macos/android 源码复核,修正 11 处错误或 遗漏;主表 74 行 Windows 列全为 ✓。 Model: deepseek-flash Co-Authored-By: Claude Code --- docs/Client_Capability_Matrix.md | 179 +++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 docs/Client_Capability_Matrix.md diff --git a/docs/Client_Capability_Matrix.md b/docs/Client_Capability_Matrix.md new file mode 100644 index 0000000..27e35f9 --- /dev/null +++ b/docs/Client_Capability_Matrix.md @@ -0,0 +1,179 @@ +# 客户端能力矩阵 + +以 Windows 客户端为基线,对比 Linux、macOS、Android 客户端的实现情况。表中所有主表行在 Windows 列均为 ✓;其他平台按实际代码判断,不做推测。 + +- 依据:各平台客户端源码(`client/`、`linux/`、`macos/`、`android/app/src/main/`)与登录能力位(`common/commands.h` 的 `DefaultCaps()`),代码基线 `main@d9fe93f`(2026-11-19)。 +- `linux/README.md` 里的「未实现」清单部分已过时(例如开机自启已由 `install.sh` 实现),以本表为准。 +- 图例:✓ 已实现;△ 部分实现或依赖运行环境;— 未实现。 +- 服务端侧功能(主机列表、备注/分组、上线提醒、授权管理界面、MCP、Web 控制台等)不在本表范围。 + +## 一、连接与传输 + +| 功能 | Windows | Linux | macOS | Android | +|---|:---:|:---:|:---:|:---:| +| TCP 直连 | ✓ | ✓ | ✓ | ✓ | +| WebSocket / WSS 传输(出包时选择) | ✓ | ✓ | ✓ | ✓ | +| TLS 加密传输 | ✓ | ✓ | ✓ | ✓ | +| 子连接 ConnAuth 身份校验 | ✓ | ✓ | ✓ | ✓ | +| 断线自动重连 | ✓ | ✓ | ✓ | ✓ | +| 心跳与活动窗口上报 | ✓ | ✓ | ✓ | ✓ | +| 服务端修改分组 | ✓ | ✓ | ✓ | ✓ | +| UDP / KCP / HTTP 伪装传输 | ✓ | — | — | — | +| 并发上线(多实例并行) | ✓ | — | — | — | +| 远程切换传输协议(TCP/WS/WSS) | ✓ | — | — | — | +| 客户端 ID 重建(克隆机撞 ID) | ✓ | — | — | — | +| 分享主机 / 取消分享 | ✓ | ✓ | — | — | +| 转移主机(到期自动复原) | ✓ | ✓ | — | ✓ | + +说明: +- 分享/转移:Android 实现转移、不实现分享(收到分享命令会回“不支持”);macOS 两者均未实现。 +- **WebSocket/WSS 是“出包能力”,不是“运行时切换能力”**:四个平台的网络层(`IOCPClient` + `WsChannel.h`)都实现了 WS/WSS,生成客户端时把「协议」选为 WebSocket 或 WS+TLS 即可,客户端启动后按烘焙的 `protoType` 连接(需经反向代理入口;WSS 还需内嵌或在线下发的信任锚)。但运行时的「协议切换」菜单走 `COMMAND_SET_PROTO`,只有 Windows 客户端处理该命令并声明 `CLIENT_CAP_PROTO_SWITCH`;其他平台该菜单整组置灰,菜单里勾选 TCP 只是当前实际连接的传输,不代表客户端只能走 TCP。 +- UDP/KCP/HTTP 伪装传输:只有 Windows 客户端有对应实现;Linux/macOS/Android 的网络层只处理 TCP/WS/WSS,出包时选其他协议不会生效。 +- 并发上线(`RUNNING_PARALLEL`)只有 Windows 客户端实现;其他平台按单实例运行。 +- 客户端 ID 重建同样仅 Windows 处理。 +- TLS:macOS 复用 `client/TlsChannelLinux.cpp`,实机验证仍待补;Android/Linux 已随 TLS 开关使用。 + +## 二、远程桌面 + +| 功能 | Windows | Linux | macOS | Android | +|---|:---:|:---:|:---:|:---:| +| 实时屏幕查看 | ✓ | ✓ | ✓ | ✓ | +| H.264 编码与关键帧请求 | ✓ | ✓ | ✓ | △ | +| 画质档位下发(自适应/固定档) | ✓ | ✓ | ✓ | ✓ | +| 帧率设置(`CMD_FPS`) | ✓ | — | — | ✓ | +| 远程桌面调优 / 硬编码 / SSE2 | ✓ | — | — | — | +| 鼠标/键盘注入 | ✓ | ✓ | ✓ | △ | +| 剪贴板同步 | ✓ | ✓ | ✓ | △ | +| 剪贴板文件同步(复制文件/路径) | ✓ | ✓ | ✓ | — | +| 锁定目标键鼠 | ✓ | — | — | ✓ | +| 隐私屏幕(独立桌面) | ✓ | — | — | — | +| 多显示器整桌面捕获 | ✓ | △ | — | — | +| 切换显示器 | ✓ | — | — | — | +| 黑白屏幕(灰度传输) | ✓ | ✓ | ✓ | — | +| 区域/窗口级截图 | ✓ | — | — | — | +| 全屏 / 远程光标视图偏好 | ✓ | ✓ | — | — | +| 滚动优化 / 多线程压缩 | ✓ | — | — | — | +| RDP 会话归位 / 虚拟桌面重置 / 窗口切换 | ✓ | — | — | — | +| 自定义光标 | ✓ | — | — | — | +| 屏幕缩略图预览 | ✓ | ✓ | ✓ | ✓ | +| 远程音频监听 | ✓ | — | — | ✓ | +| 远程摄像头 | ✓ | — | — | ✓ | +| 键盘记录 | ✓ | — | — | — | +| 即时消息/远程交谈 | ✓ | — | — | ✓ | +| 远程画板 | ✓ | — | — | — | + +说明: +- 剪贴板:Windows/Linux/macOS 支持读取与写入;Android 只处理服务端下发的“写入并粘贴”,不支持读取设备剪贴板。 +- 剪贴板文件同步:Windows/Linux/macOS 在剪贴板里是文件时返回文件清单/内容(`COMMAND_GET_FOLDER` / `COMMAND_GET_FILE`),Android 没有文件剪贴板协议。 +- 缩略图预览:Linux 需有可截图的 X11 会话,macOS 需已授予录屏权限,Android 需无障碍服务与 API 30+;条件不满足时客户端不声明对应能力位,服务端会提前拒绝。 +- 画质配置表(`CMD_QUALITY_PROFILES`)仅 Windows/Android 处理;Linux/macOS 只处理单档 `CMD_QUALITY_LEVEL`。 +- 关键帧请求(`COMMAND_SCREEN_KEYFRAME_REQ`):Windows/Linux/macOS 处理(Web 屏幕墙恢复用);Android 未处理该命令,只在注入手势后主动请求 IDR。 +- 鼠标/键盘注入:Windows/Linux/macOS 是完整键鼠注入;Android 把鼠标映射为触摸手势,只支持 Back/Home/Apps/截图/粘贴等少量按键,没有通用键盘注入。 +- 帧率设置:Android 处理 `CMD_FPS`;`CMD_SCREEN_TUNING` 在 Android 上是显式 no-op,`COMMAND_ENCODE_LEVEL`(硬编码选择)只有 Windows 处理。 +- 多显示器:Windows 支持整桌面捕获和按显示器切换;Linux 总是抓 X root(含所有显示器),不能按显示器选择;macOS 只抓主显示器。 +- 全屏/远程光标:Windows 与 Linux 会把主控端的视图偏好落盘并在下次打开时上报;macOS/Android 没有这两个偏好命令。 +- 黑白屏幕(灰度传输):Windows/Linux/macOS 处理 `ALGORITHM_GRAY`;Android 没有该算法,收到后会忽略灰度标志。 +- RDP 会话归位/虚拟桌面重置/窗口切换:均为 Windows 屏幕子连接命令,其他平台没有对应实现。 +- 键盘记录仅在 Windows 客户端实现(支持实时与离线落盘、清除);其他平台没有输入钩子。 +- 远程音频为单向麦克风监听(Windows/Android);双向语音对讲/麦克风回传未实现(评估后放弃)。Windows 的音频开关支持持久化(`CMD_AUDIO_CTRL`),Android 不支持。 +- 远程摄像头:Windows 支持压缩开关与分辨率调整;Android 固定 1280×720@8fps JPEG。 +- Android 的锁定键鼠、黑屏遮罩、锁屏(映射 `GLOBAL_ACTION_LOCK_SCREEN`)都依赖无障碍服务,客户端按运行时状态追加 `PRIVACY_OVERLAY` / `LOCK_SCREEN` 能力位;Windows 无锁屏/黑屏对应行,故未列入主表。 + +## 三、文件管理 + +| 功能 | Windows | Linux | macOS | Android | +|---|:---:|:---:|:---:|:---:| +| 磁盘/目录浏览 | ✓ | ✓ | ✓ | ✓ | +| 上传/下载 | ✓ | ✓ | ✓ | ✓ | +| V2 文件传输通道 | ✓ | ✓ | ✓ | ✓ | +| 断点续传 | ✓ | — | — | — | +| 删除/重命名/新建目录 | ✓ | ✓ | ✓ | ✓ | +| 文件搜索 | ✓ | — | — | ✓ | +| 压缩/解压 | ✓ | — | — | — | +| 客户端间 C2C 文件直传 | ✓ | △ | △ | — | +| 客户端间 C2C 剪贴板文本 | ✓ | △ | △ | — | +| 文件复制/粘贴 / 属性 / 最近文件 / 网上邻居 / 远程打开 / 强制删除 | ✓ | — | — | — | +| 文件加密/解密(经典文件管理器) | ✓ | — | — | — | +| 插件文件管理(SimplePlugins) | ✓ | — | — | — | + +说明: +- 断点续传:仅 Windows 客户端处理 `COMMAND_FILE_QUERY_RESUME` / `COMMAND_FILE_RESUME`;其他平台走 V2 普通传输,不响应续传查询。 +- C2C 文件:Windows 支持发送(`CLIENT_CAP_C2C_PATHS`)与接收(`COMMAND_C2C_PREPARE/_RESP`);Linux/macOS 只做接收端并在落盘后回执(`CLIENT_CAP_C2C_RECV_ACK`);Android 未实现。C2C 需要收发两端能力配合,单端具备能力不等于任意两平台之间都能直传。 +- C2C 剪贴板文本(`COMMAND_C2C_TEXT`):Windows 能发送也能接收;Linux/macOS 只处理接收端(服务端下发文本后写入本机剪贴板,Linux 需要 `xclip`/`xsel`);Android 未实现。 +- 文件复制/粘贴、属性、最近文件、网上邻居、远程打开、强制删除:Windows 经典文件管理器的扩展命令;Linux/macOS/Android 的 V2 文件管理只提供目录浏览与增删改,没有这些入口。 +- 文件加密/解密:Windows 客户端处理 `COMMAND_FILE_Encryption` / `COMMAND_FILE_Decrypt`;其他平台没有对应实现。 +- 插件文件管理(SimplePlugins):Windows 的「实验功能 → 文件管理」走 `COMMAND_FILE_MANAGER_PLUGIN`;其他平台没有该插件入口。 + +## 四、系统管理 + +| 功能 | Windows | Linux | macOS | Android | +|---|:---:|:---:|:---:|:---:| +| 进程列表 | ✓ | ✓ | ✓ | △ | +| 结束进程 | ✓ | ✓ | ✓ | △ | +| 进程冻结/解冻/删除 | ✓ | — | — | — | +| 窗口列表 | ✓ | — | △ | — | +| 窗口操作(激活/移动/置顶/关闭) | ✓ | — | — | — | +| 远程终端(PTY) | ✓ | ✓ | ✓ | ✓ | +| 服务管理(启动/停止/暂停/删除) | ✓ | — | — | — | +| 计划任务管理 | ✓ | — | — | — | +| 注册表管理 | ✓ | — | — | — | +| 系统信息/机器管理 | ✓ | — | — | — | +| 已安装软件清单/卸载 | ✓ | — | — | — | +| 电源操作(关机/重启/注销) | ✓ | — | — | — | +| 下载执行 / 上传执行 / DLL 执行 | ✓ | — | — | — | +| 代理映射/端口转发 | ✓ | — | — | — | +| 提权运行(UAC) | ✓ | — | — | — | +| 进程注入(记事本 / Shellcode) | ✓ | — | — | — | +| 连接管理(连接列表/强制断开) | ✓ | — | — | — | +| 远程封禁(强制终止客户端) | ✓ | — | — | — | + +说明: +- Android 进程列表/结束进程依赖 root;非 root 设备登录时不声明 `CLIENT_CAP_PROCESS`,服务端直接返回“不支持”。 +- 窗口列表:macOS 只提供应用列表(PID 当伪句柄),不是窗口级枚举;Linux 的 `COMMAND_WSLIST` 只回一个空 `TOKEN_WSLIST`(无 GUI 窗口管理),Android 仅上报当前活动窗口标题。窗口移动/置顶/关闭只有 Windows 实现。 +- 机器管理(Windows)在同一面板下还提供网络连接、浏览器历史、收藏夹、HOSTS 文件、驱动服务等清单/编辑能力;其他平台没有对应面板。 +- 电源操作仅 Windows 实现(MCP `power_action` 也只放行 Windows 主机)。 +- 连接管理:Windows 客户端枚举本机 TCP 连接并通过 `SetTcpEntry` 强制断开;其他平台没有 `COMMAND_CONNECTION` / `COMMAND_KILL_CONNECTION` 处理。 +- 远程封禁(`COMMAND_FORBIDDEN`)只有 Windows 客户端处理(直接 `TerminateProcess` 退出);其他平台收到命令会走 default 丢弃。 + +## 五、监控与审计 + +| 功能 | Windows | Linux | macOS | Android | +|---|:---:|:---:|:---:|:---:| +| 拉取客户端运行日志 | ✓ | ✓ | ✓ | ✓ | +| 历史活动上报 | ✓ | ✓ | ✓ | ✓ | + +## 六、升级与运维 + +| 功能 | Windows | Linux | macOS | Android | +|---|:---:|:---:|:---:|:---:| +| 远程升级 | ✓ | ✓ | — | ✓ | +| TLS 开关下发 | ✓ | ✓ | ✓ | ✓ | +| 自启动/服务化 | ✓ | ✓ | ✓ | △ | +| 远程卸载 | ✓ | — | — | ✓ | +| 授权/许可校验(V2) | ✓ | — | — | — | + +说明: +- 远程升级:Windows 替换 PE、Linux 替换 ELF、Android 下发 APK 并拉起系统安装器(尚未真机验收);macOS 客户端没有 `COMMAND_UPDATE` 分支,暂不支持自升级。 +- 自启动:Windows 安装为系统服务;Linux 注册 XDG autostart(`install.sh`,另有 `-d` 守护进程模式);macOS 添加登录项;Android 为前台服务,但清单里没有 BOOT_COMPLETED 接收器,重启设备后需手动启动一次。 +- 远程卸载:Linux/macOS 仅提供本地 `uninstall.sh`,服务端命令不会被处理。 +- 授权/许可:V2 授权校验、服务端「延长授权/撤销授权」只对 Windows 客户端生效;其他平台不参与授权校验。 + +## 七、平台前提与已知边界 + +- **Windows**:功能最全;能力位未声明的终端、进程、聊天等功能实际已实现(服务端历史上按平台名放行)。 +- **Linux**:抓屏与注入依赖 X11/XTest;Wayland 会话下抓屏不可用。安装脚本要求以普通桌面用户运行,以注册 autostart。 +- **macOS**:屏幕录制与辅助功能需要用户在“隐私与安全性”里授权;更新二进制会导致授权失效,需要重新授权。自升级未实现。 +- **Android**:屏幕预览/注入依赖无障碍服务;进程管理依赖 root;文件管理依赖全盘访问权限(MANAGE_EXTERNAL_STORAGE);远程摄像头、音频、锁屏、黑屏遮罩需相应系统权限或 API 级别;APK 在线升级已编码但尚未真机验收。 + +## 八、能力位对照(登录上报) + +服务端从 `moduleVersion` 的 `-XXXX` 后缀解析能力位(`DefaultCaps()`): + +| 平台 | 默认能力位 | 运行时追加 | +|---|---|---| +| Windows | V2、UTF8、SCREEN_PREVIEW、C2C_PATHS、PROTO_SWITCH、VIRTUAL_DESKTOP、WINDOW_INFO、SCREEN_REGION | 仅当本次连接走 TLS 且使用内嵌锚时追加 EMBEDDED_ANCHOR | +| Linux | V2、UTF8、C2C_RECV_ACK、PROCESS | SCREEN_PREVIEW(有可抓 X11 桌面时) | +| macOS | V2、UTF8、TERMINAL、SCREEN_CLIPBOARD、PROCESS、C2C_RECV_ACK | SCREEN_PREVIEW(已授录屏权限时) | +| Android | V2、UTF8、APK_UPDATE、SCREEN_CLIPBOARD、UNINSTALL、REMOTE_CHAT、TERMINAL | SCREEN_PREVIEW、LOCK_SCREEN、PRIVACY_OVERLAY、PROCESS(按无障碍/API/root 状态) | + +注意:Windows 的终端、进程、聊天、剪贴板、卸载等能力虽未在能力位中声明,但客户端实际实现并被服务端按平台放行;其他平台的能力位缺失会被服务端提前拒绝。