简体中文 | English

PixelBridge 是一套 Windows 文件传输工具。它把文件编码成持续变化的画面，在另一台电脑上从远控窗口的实际屏幕像素中恢复文件。

不需要两端共享目录，不依赖剪贴板、磁盘映射或远控软件的文件传输功能。发送端只负责显示画面，接收端只负责看画面、恢复并验证文件。

PixelBridge v1.0 提供 Encoder 与 Decoder 两个独立程序，支持标准、灰阶高速、PAM4 与 PAM4 Wide 四种传输模式，以及断点恢复、完整性校验和双端诊断日志。

面向大文件的分段流式设计。 不需要将整个文件一次装入内存，可扩展到更大的文件规模；v1.0 当前单文件上限为 500 GiB，实际传输还需满足磁盘空间和接收资源预算要求。500 GiB 是产品准入上限，不代表已经完成这一大小的实测。

特定条件下，平均接收速度可达约 279 KB/s。 这是 PAM4 Wide 在真实非本机环境中完整接收大文件的留存实测成绩，包含最终文件校验，并非瞬时峰值。具体环境和计算口径见下方传输速度。

这是发送端实际显示的数据码面：Encoder 将文件编码为持续变化的灰阶图案并循环显示，Decoder 从捕获到的屏幕像素中恢复并校验文件。动图录制自真实发送画面。

本项目受 libcimbar 启发。libcimbar 展示了通过屏幕上的动态彩色图案、由手机摄像头读取来传输文件的思路。PixelBridge 将这一视觉传输思路聚焦到 Windows 非本机远控场景，针对这一用途的主要改进是：

• 更直接的远控接收： 直接捕获远控窗口实际显示的屏幕像素，不需要手机或摄像头，适合把远程电脑中的文件带回本地。
• 针对视频压缩的画面编码： 提供灰阶高速、PAM4 与 PAM4 Wide 等路线，减少对彩色数据通道的依赖，并以最终正确文件的接收速度为优化目标。
• 面向大文件的完整工作流： 将分段流式处理、有限内存预算、断点恢复、整文件校验、双端图形界面与诊断日志整合在一起，方便长时间接收和异常排查。

这些优势针对远控与大文件接收需求；两者的典型使用场景不同，不把不同环境的速度数字当作直接性能对比。

• 能使用远程桌面查看文件，但没有合适的文件传输入口。
• 远程桌面、虚拟桌面（VDI）等工作流中，希望通过已有可见画面将文件带回本地。
• 文件比较大，希望接收过程可恢复、可诊断，并能确认恢复结果是否正确。
• 接收端只有一块屏幕：先开始接收，再让远控码面覆盖所选屏幕即可；不需要给 Decoder 窗口预留一块区域。

PixelBridge 不是远控软件，不建立远程桌面连接，也不修改远控软件或网络设置。它不是摄像头扫码工具。如果可以直接复制文件，普通文件传输通常更快、更方便。

两端不交换接收进度和确认消息。请以 Decoder 的“已完成”为准，再停止 Encoder。 Encoder GUI 可选“超时关闭（秒）”：0 表示一直运行到人为停止，非零值从本次 Start 被接受时起算并在到时后安全停止；超时停止不代表文件已经收好。

1. 在两台电脑上分别启动对应程序，双端选择同一种传输模式。
2. 在 Decoder 选择保存目录、接收屏幕和“整屏”或区域。
3. 先点击 Decoder 的“开始接收”。
4. 在远程电脑的 Encoder 选择文件，再开始发送。保持完整数据码面可见，避免浮动面板、其它窗口和鼠标指针挡住码面。
5. 等 Decoder 显示“已完成”，再停止 Encoder。

Decoder 点击“开始接收”后，在 Encoder 首次显示并被接受的同 Profile SessionDescriptor 之前，GUI 活动“已花费时间”、平均速度和 ETA 不累计等待；活动窗口包含恢复、写盘、最终发布与重开复验。完成时 GUI 平均速度按原始文件总字节数除以冻结的活动耗时计算。正式 runStarted/runEnded 与 verified raw goodput 仍保留完整运行/性能证据语义。

接收大文件时，“已接收大小”可能暂时不上涨。 如果界面显示正在补齐分段、校验、写盘或等待轮播，这是接收流程中的正常等待，不要暂停。如果界面明确提示捕获中断、没有有效进展或错误，则按提示检查，而不是把所有停滞都当作正常。

完整操作、断点恢复及注意事项见 使用指南。

1080P 屏幕的非本机远控传输，建议优先选择 PAM4，双端选择一致；发送频率可先从 25 Hz 开始。 Encoder 和 Decoder 的新安装、缺失或非法 g22/carrier GUI 偏好默认选择 PAM4（索引 2）；已经保存的合法索引继续原样恢复。标准索引 0 仍作为兼容保留模式，CLI/core 默认与 GUI 默认分开。

这不是同一种模式的三个“画质档位”，而是三种不同的画面编码方式：

“灰阶高速”不代表在所有远控环境中都比 PAM4 更快。 单帧放入更多数据，如果经过视频压缩后丢失更多，总接收时间反而可能更长。以上是基于当前实现与已有实测的使用建议，不是三种模式在所有环境下的速度排名；如果 PAM4 接收效果不理想，可在相同环境下用同一个小文件手动对比灰阶高速，以完整文件的完成时间为准。三种模式都保留最终文件完整性校验，不以降低校验要求换速度。

PAM4 Wide 是 PAM4 的大码面版本，不是更适合 1080P 的“高档位”。 它沿用四级灰阶思路，利用更大的显示面积携带更多数据：

这里说的是文件所在电脑的实际物理桌面，不是 Decoder 窗口的大小。1080P 发送端选择 PAM4，不选择 Wide；不能把 Wide 强行缩小到 1080P。 标准与灰阶高速也使用 1920×1080 基础码面。接收端可以整屏或区域接收，但远控内部缩放、画质和实际传来的像素会影响结果，不能仅凭显示器分辨率保证速度。25 Hz 是起步建议，不是所有环境的最优值；提高发送频率不一定更快。

当前 PAM4 家族 GUI 的发送屏幕还要求未旋转，且不超过 3840×2160；可用尺寸有明确上下限，不表示任意分辨率均已适配。

界面支持单屏接收；目前缺少只有一块物理显示器的独立电脑验收，不能把“双屏电脑上选一块屏”的测试等同于这一认证。详见 支持与验证范围。

Decoder 的高级选项可对灰阶高速、PAM4 和 PAM4 Wide 开启按内存预算接收，设置活动解码器总预算和单实例上限，也可使用本机建议值。

这能减少“活动名额已满，先等其它分段完成”的情况，但不是内存越满越快。需要给操作系统、远控程序、捕获和断点数据留下空间；发生换页反而可能变慢。具体说明见 内存预算。

速度取决于整条远控画面链路，没有一个适用于所有电脑、网络和远控软件的固定数值。

已有非本机实测的平均完整文件接收速度如下：

两项记录均来自 ToDesk 专业版、高清画质、25 Hz 发送，本地接收屏幕为 2560×1440。历史记录的 KB/s 仍按 1 KB = 1024 字节计算。 平均值按原始文件大小除以接收端完整运行时间计算，包含启动等待、修复、写盘、整文件校验和最终复验；它们不是瞬时峰值或理论带宽，也不与新 GUI 的活动接收平均速度共享同一个时间窗口。

这些是特定环境下的留存测试记录，不是本次发布构建的重新测速，也不是两种模式在相同分辨率、相同文件下的横向对比。不能把 Wide 的约 279 KB/s 当成 1080P PAM4 的速度承诺，也不保证任意远控链路都能达到表中数值或全程进度连续增长。版本、原始数值与验证信息见 证据与限制。

两端正常 GUI / 传输 CLI 会自动保存低频诊断日志。界面“高级选项”中可打开日志目录，也可手动导出最终报告。

• 默认位置：%LOCALAPPDATA%\PixelBridge\Logs\Encoder 或 Decoder。
• 日志记录发送、捕获、解码、资源等待和最终校验状态；不保存屏幕截图或文件内容。
• 最终报告可能含文件名、本地路径、会话标识和环境信息。分享前请检查需要隐去的个人信息。

详见 日志与故障定位。

远程文件 → 分段与压缩 → 纠删/纠错编码 → 可见数据画面
                                          ↓ 既有远控画面链路
本地文件 ← 完整性校验 ← 分段恢复 ← 捕获到的屏幕像素

• 纯视觉、单向。 Decoder 的文件内容只来自它实际捕获的像素，没有后台文件传送通道，也没有反向 ACK。
• 为不稳定画面设计。 循环发送与纠删码允许丢失部分画面后继续收集修复数据，不要求每帧都到达。
• 分段、有限资源、可恢复。 不需要一次把整文件放进内存；已验证分段写盘，保留可复核的断点状态。
• 正确性优先。 传输 CRC、分段摘要和整文件 BLAKE3 分层检查；未通过整文件验证和安全发布、最终重开复验，不算完成。

1. 远控传的是视频，不是原始像素。 色度抽样、有损压缩、缩放、重复帧和局部更新会改变数据码面；新路线采用独立身份的四级灰阶 PAM4，并保留可见定位、时序与校准区域。
2. 发送得快不代表收得快。 更高发送频率、更大的码面可能增加视频编码压力，导致有效新数据反而减少。
3. 没有反馈，就无法只补最后缺的那一段。 接收尾部可能等待下一轮合适的修复块，这是总完成时间的重要组成。
4. 更多活动解码器有代价。 并行保留更多分段有助于接纳数据，同时增加内存、持久化和整理成本；必须保持资源有界与崩溃恢复正确。

完整参数、协议不变量、捕获生命周期、持久化和实测边界见 技术路线与总体设计。

Windows x64、C++20、MSVC、Qt Widgets、CMake 和 vcpkg。构建方法、定向测试以及贡献规范见 开发指南，文档总入口见 docs。

仓库中的诊断工具和 PBBridge 只用于开发编排与取证，不是产品的额外文件通道。离线 MP4、摄像头接收、任意缩放/HDR 以及跨平台接收不属于本次已交付能力声明。

v1.0 的交付内容、验证范围及已知历史性能限制见 发布说明。

本项目采用 MIT License，允许在保留版权和许可声明的前提下使用、修改及再分发，包括商业用途。软件按许可证原文“按原样”提供。

Qt 等第三方组件仍遵守各自许可证；正式包附带许可原文、依赖清单和 Qt 对应源码。详见 第三方组件与许可。

特别感谢 GPT-5.6 Sol、GPT-6 Astra、GLM-5.3、Qwen 3.8 Flash Next 及其背后的研发团队，为本项目探索与开发提供的帮助和启发！同时感谢 libcimbar、各开源依赖的贡献者，以及参与实测与反馈的使用者。完整说明见 致谢。