AirScan-QR 是一款专为物理隔离环境 (Air-gapped) 及 跨端受限网络 设计的高效文件传输方案。它通过动态二维码序列流，利用“屏幕+摄像头”的视觉链路，彻底打破物理与协议的边界。
在无法连接互联网、禁用 U 盘、或无法建立局域网共享的场景下，AirScan-QR 是你的最佳选择：
- 封闭开发/实验室环境：从物理隔离的内网 PC 中取出日志、代码片段或小文件。
- 跨设备“无协议”互传：手机与手机之间、Android 与 iOS 之间，无需蓝牙或 WiFi，开码即传。
- 远程桌面/VPN 穿透：直接通过摄像头扫描远程桌面窗口中的二维码，将文件从远程服务器“拿”回本地 PC。
- 无痕传输：无需安装驱动，无需注册账号，所有逻辑在浏览器本地执行，不留物理痕迹。
- 两台设备均访问：https://topcss.github.io/AirScan-QR/
- 发送方：点击“选择文件” -> 设置帧率 -> 开始广播。
- 接收方：点击“开始扫描” -> 对准发送方屏幕 -> 完成后自动触发下载。
- 内网 PC 打开本项目（可通过 HTML 离线文件）。
- 发送方选择文件并广播。
- 手机扫码接收，实现文件“出网”。
- 在远程窗口中运行发送端并显示二维码。
- 本机 PC 接收中，选择屏幕录制，选择对应的应用窗口，即可接收文件。
| 发送端界面 (Sender) | 接收端界面 (Receiver) |
|---|---|
 |
 |
| 功能：文件切片、动态帧率调节、实时广播 | 功能：扫码识别、分片重组、自动下载 |
- ⚡ 高速流传输：基于
qrious优化算法，支持 1-30 FPS 动态帧率调节。 - 🧩 动态分片技术：单帧容量支持 200-800 Byte 自由调节，适配不同性能的扫描端。
- 🔄 智能补帧机制：可视化缺失帧矩阵，点击特定帧即可单点重传，攻克环境光干扰导致的跳帧难题。
- 📄 元数据保留：支持超长文件名及后缀名的无损还原，确保文件开箱即用。
- 🎨 极简交互：基于 Tailwind CSS 构建，适配手机与 PC 端，支持深色模式。
项目采用二维码流水线协议 (QR-Pipeline Protocol)：
TaskID | FileName | TotalFrames | CurrentIndex | DataPayload
- 数据编码：将文件转化为 Base64 后进行切片分段。
- 文件名编码：文件名经
encodeURIComponent编码为纯 ASCII 后传输，接收端解码还原，确保中文等多字节字符文件名无损（QR 编码库对非 ASCII 字符存在单字节截断问题）。 - 索引校验：通过数组索引重组分片，确保文件合并顺序 100% 准确。
- 零服务器依赖：纯客户端逻辑，数据不经过中转，隐私安全无忧。
由于采用单 HTML 架构，你可以根据需求选择：
- 在线访问：通过 GitHub Pages 直接使用。
- 本地携带：右键“另存为”
index-embedded.html，嵌入式单文件版本，放入 U 盘随身携带。 - 内网分发：直接将 HTML 文件部署在内网静态服务器或共享文件夹中。
- 独立 EXE（推荐离线场景）：双击
dist/AirScan-QR.exe即可使用，详见下节。
项目支持打包为单文件独立 EXE，在无 Python、无网络（页面资源已内嵌）的 Windows 环境下双击即可运行：
- HTTPS 自动服务：双击后在后台启动本地 HTTPS 服务（默认
https://localhost:4443），自动生成自签名 SSL 证书（有效期约 10 年，SAN 覆盖localhost、127.0.0.1、本机主机名与全部本机 IP；IP 变化时自动重新生成）； - 实时控制台日志：双击运行自动弹出终端命令行窗口，实时滚动输出运行状态——监听地址与端口、证书状态、访问日志（每个请求的客户端与状态码）、错误日志（TLS 握手失败、连接异常等）、状态变更日志（服务启动/就绪/停止），便于监控运行状态与排查问题；
- 自动打开：服务完成 TLS 就绪检测后，自动调用系统默认浏览器打开主页；
- 摄像头可用：HTTPS + 接受证书后即为浏览器安全上下文（Secure Context），本机与局域网设备均可正常调用摄像头（getUserMedia）扫码；
- 局域网访问：服务监听
0.0.0.0，手机/其他设备访问https://<本机IP>:4443/index-embedded.html即可使用（本机 IP 可用ipconfig查询，也可直接查看控制台日志中输出的访问地址）； - 端口自适应：默认端口被占用时自动尝试后续端口（4443 → 4452）；
- 友好提示：资源缺失、证书生成失败、端口全部被占、服务启动异常等情况会弹出 Windows 原生提示框说明原因。
控制台日志输出示例：
[2026-10-13 10:19:05] [信息] AirScan-QR 启动中...
[2026-10-13 10:19:05] [信息] [证书] 复用已有自签名证书: C:\Users\xxx\AppData\Roaming\AirScan-QR\cert.pem
[2026-10-13 10:19:05] [信息] [服务] HTTPS 服务已绑定 0.0.0.0:4443（TLS 就绪）
[2026-10-13 10:19:06] [信息] [地址] 本机访问: https://localhost:4443/index-embedded.html
[2026-10-13 10:19:06] [信息] [地址] 局域网访问: https://192.168.1.100:4443/index-embedded.html
[2026-10-13 10:19:08] [信息] [访问] 127.0.0.1 "GET /index-embedded.html HTTP/1.1" 200 -
[2026-10-13 10:19:09] [错误] [连接] TLS 接入握手失败: [SSL: HTTP_REQUEST] http request
首次访问的证书提示（自签名证书的正常现象）：
浏览器首次访问会出现"你的连接不是专用连接"警告，点击 "高级" → "继续前往 xxx（不安全）" 接受一次即可，之后同一浏览器会记住该证书，摄像头等功能一切正常。
防火墙提示：由于监听 0.0.0.0，双击运行时 Windows 会弹出防火墙授权窗口，请勾选"专用网络"（及需要的"公用网络"）并允许，局域网设备才能访问；仅本机使用则无影响。
消除浏览器警告（可选）：将生成的证书导入当前用户受信任根存储后，本机浏览器不再提示：
# 证书位置：打包版 %APPDATA%\AirScan-QR\cert.pem，开发版 certs\cert.pem
certutil -user -addstore Root "$env:APPDATA\AirScan-QR\cert.pem"一键构建（推荐）（项目统一使用 uv 管理依赖）：
uv run python build.py一键完成全流程构建，无需人工干预：依赖同步（uv sync，自动处理 dev 依赖）→ 资源检查（校验页面文件完整）→ 产物打包（PyInstaller 控制台模式）→ 产物校验与中间文件清理；构建前会自动结束残留的 AirScan-QR.exe 进程，避免文件锁定导致打包失败。
手动打包（与一键构建等价）：
uv add --dev pyinstaller # 首次打包前安装（已配置）
uv run pyinstaller --onefile --name AirScan-QR --paths src ^
--add-data "index.html;web" --add-data "index-embedded.html;web" ^
--add-data "airscan-fountain.html;web" --noconfirm --clean src/airscan_qr/__main__.py注意：不使用 --windowed（保留控制台子系统），exe 启动后自动弹出终端窗口实时输出运行日志。
打包产物位于 dist/AirScan-QR.exe。开发调试可直接运行 uv run airscan-qr（或 uv run python -m airscan_qr）。
功能验证：uv run python test/test_airscan_qr.py 验证模块逻辑（证书 SAN 覆盖、HTTPS 各源访问、TLS 信任链与主机名校验、端口回退等 15 项）；加 --exe 参数验证打包后的 EXE（7 项，会真实打开浏览器）。
EXE 日志验证：uv run python test/exe_log_verify.py 验证打包 EXE 的控制台实时日志（状态日志、访问日志、错误日志通路、日志格式，共 7 项）。
摄像头链路验证（可选）：uv run python test/cdp_verify.py [目标URL] 通过 Edge headless + CDP 在真实浏览器中验证 HTTPS 页面的 isSecureContext 与 getUserMedia 实际调用（本机默认地址，也可传入局域网 IP 地址验证跨设备访问路径）。
中文文件名验证（可选）：uv run python test/cn_filename_verify.py 通过 Edge headless + CDP 在真实浏览器中验证中文文件名的端到端传输（QR 编码 → 解码 → 重组 → 下载内容逐字节比对，覆盖在线版/离线版/喷泉码版三个页面，并复现修复前的损坏场景），脚本会自动检测并启动本地 HTTPS 服务。
- index.html: 正式版，技术路线为单码循环播放传文件，支持摄像头扫码和pc跨应用扫码。
- airscan-fountain.html 喷泉版，技术路线为四码同传，解决了丢帧需要重传的问题，极高的提升了传输效率。
MIT License © [Jack/topcss]
- 召集令：挑战视觉传输效率极限 (Screen-to-Camera) 邀请各位散修，我们创造最高效的视觉传输方案。
- airscan-fountain.html 实现了喷泉码，四码同传，效率极高，但是简单的文本会导致卡死，哪位朋友有空可以看看。 感谢 @YILS-LIN 解决