PGU-NetFileSyncWin/AGENTS.md

PGU-NetFileSyncWin 项目维护说明

当前应用版本：v1.0.6（2026-09-27）

本版本变更：下载完成结果弹窗、失败项目明细、用时和平均速度统计、完成后速度条清零；并保留极速服务 V3、CPU 自适应并发、HTTP 长连接、服务版本显示与旧版升级、连接断开后的 user linger。

项目定位

PGU-NetFileSyncWin 是一个面向 Windows 的 PyQt5 远程文件管理与高速下载工具。它用于连接 PGU 设备、浏览远程文件，并将文件或文件夹下载到 Windows 本机。

项目重点优化：

• 大量小文件下载。
• 从 GUI 拖拽到 Windows 资源管理器下载。
• 远端极速服务的安装、升级、停止和开机自启。
• 便携式 ini 配置。

文件结构

• pgu4_sync.py：主程序，包含 GUI、连接、扫描、下载、极速服务管理逻辑。
• requirements.txt：运行依赖。
• run_pgu4_sync.bat：源码运行入口。
• assets/pgu_netfilesync_icon.ico：Windows exe 图标。
• assets/pgu_netfilesync_icon.png：Qt 窗口图标。
• docs/images/main-window.png：README 和 USER 使用的主界面截图。
• tests/test_delete_worker.py：永久删除的路径安全、分批和失败回退测试。
• tests/test_commercial_ui.py：商业化主界面、DPI、扫描默认值和状态栏集成测试。
• tests/test_fast_service_recovery.py：极速服务版本识别、重启恢复和修复状态测试。
• tests/test_password_storage.py：DPAPI 密码加密、迁移和清除测试。
• tests/test_root_access.py：/root 二次密码验证和符号链接绕过测试。
• tests/test_unicode_paths.py：中文远程路径、中文本地路径和极速 Range 协议测试。
• tests/test_update.py：版本比较、Release 解析、配置合并和更新脚本测试。
• README.md：项目概览。
• USER.md：用户说明书。
• AGENTS.md：维护说明。
• PGU-NetFileSyncWin.ini：本机便携配置文件，不提交仓库。

运行环境

本机默认 Python：

C:\Users\clear\.conda\envs\clear_conda_main\python.exe

安装依赖：

C:\Users\clear\.conda\envs\clear_conda_main\python.exe -m pip install -r requirements.txt

必须继续使用 PyQt5，不要改为 PyQt6。

配置文件

程序使用同目录 ini 保存配置：

PGU-NetFileSyncWin.ini

源码运行时，ini 位于项目目录。exe 运行时，ini 位于 exe 同目录。

默认内容：

[General]
host=192.168.1.248
port=22
username=clear
remote_path=/home/clear/Data

说明：

• 密码使用 Windows DPAPI 加密后保存为 password_protected。
• 旧版 password 明文键在启动时自动迁移并删除。
• DPAPI 密文绑定当前 Windows 用户，不能作为跨机器默认密码发布。
• PGU-NetFileSyncWin.ini 已在 .gitignore 中忽略，不要提交。
• 程序启动时如果 ini 不存在，会自动生成默认配置。

关键交互

远程文件列表需要保持接近资源管理器：

• 左侧空白列可作为框选起点。
• 右侧空白区和底部空白区可框选。
• 单击空白区域取消选择。
• 从文件行拖出 GUI 表示下载到 Windows 资源管理器。
• 进入 /root 或其子目录前必须再次输入当前 SSH 密码；离开 /root 后授权失效。
• ListWorker 使用 SFTP normalize 解析真实路径，指向 /root 的符号链接也必须触发验证。
• 右键可永久删除单个或多个远程文件、目录，使用远端 rm -rf -- 分批处理，不进入回收站。
• 删除命令按选中项分批并进行 shell 安全转义，禁止删除远程根目录 /；批量失败时逐项定位失败内容。
• rm -rf 返回失败时最多自动重试 5 次并指数退避，用于处理短暂的 Directory not empty 写入竞争。
• 每次删除后立即检查顶层选中路径是否仍存在，避免后台程序瞬间重建目录时误报成功。
• 确认后在弹窗中显示选中项删除进度，完成后自动刷新目录。
• 不显示左侧本地目录树。

底部条是速度条，不是总进度条：

• 100MB/s 映射到满格。
• 下载中蓝色。
• 下载完成弹窗关闭后速度条清零，恢复为等待状态。

局域网扫描端口：

• 5901
• 5923
• 8080

设备识别及端口映射规则：

• 发现 5923：显示为 PGU4，主界面端口填 5922。
• 发现 5901：显示为 PGU4，主界面端口填 22。
• 仅发现 8080：显示为 PGU5，主界面端口填 22。

扫描入口只保留在 设备与连接设置 弹窗中。选择设备后：

• PGU4 自动填写用户 clear、对应密码和 /home/clear/Data。
• PGU5 自动填写用户 root、对应密码和 /nvme-data/pgu_data。
• 密码始终使用 QLineEdit.Password 掩码显示。

极速通道

核心常量：

FAST_HTTP_PORT = 5924
FAST_HTTP_WORKERS = 8
FAST_HTTP_BIG_FILE_WORKERS = 3
FAST_HTTP_TIMEOUT = 45
FAST_SPLIT_THRESHOLD = 64 * 1024 * 1024
FAST_HTTP_TOKEN = "PGU4_SYNC_FAST_V2"
FAST_SERVICE_VERSION = "3"

策略：

• 连接时同时检测 Windows 本机与远端设备在线 CPU 线程数，总并发自动取两者较小值且不保存。
• 小文件按文件并发，最多 8 路，并复用每个下载线程的 HTTP 连接，优先保证吞吐稳定。
• 大文件超过 64MB 后使用 Range 分片。
• 单个大文件最多 3 路分片，避免远端磁盘和HTTP线程争用。
• 分片失败在块内断点续传并自动重试，避免从块头重复下载。
• 极速HTTP使用45秒读取超时，避免短暂磁盘/网络抖动被过早判定失败。
• 失败汇总只在任务结束后提示。
• V3 按远端逻辑 CPU 数量建立并发槽位，上限为 min(16, CPU线程数) 且至少 2 路；同时扩大连接等待队列并启用 HTTP/1.1 长连接。路径仍使用 UTF-8 URL-safe Base64，支持中文目录、中文文件名和空格。

远端极速服务

安装位置：

~/.local/share/pgu4_sync/pgu4_fast_http.py

日志位置：

~/.local/state/pgu4_sync/pgu4_fast_http.log

自启配置：

~/.config/systemd/user/pgu4-sync-fast.service
crontab @reboot

极速服务脚本带持久版本标记，并在权限允许时启用 systemd user linger，避免 SSH 会话结束后服务退出。连接设备时：

• 当前 V3 服务正常：直接启用极速通道并刷新自启配置，GUI 显示 极速 v3。
• 检测到旧版本时显示实际版本，例如 极速 v2 · 可升级，按钮提供 升级极速。
• 当前 V3 已安装但未运行：自动清理残留进程并重启，不显示升级。
• 自动恢复失败：显示 修复极速。
• 仅脚本确实为旧版本时显示 升级极速。
• crontab 清理必须匹配 pgu4_fast_http.py.*--port 5924，避免带引号的旧命令累积。

关闭 Windows GUI 不会停止 PGU 设备上的极速服务。

自动更新

当前应用版本由 APP_VERSION 定义。打包后的 EXE 启动后会静默访问 Gitea releases/latest：

• 没有新版本、请求超时或接口异常时不提示。
• 左侧底部提供 检查更新 按钮；手动检查会明确提示最新版或连接失败。
• 仅接受 107.173.157.41:3000 上名为 PGU-NetFileSyncWin.exe 的附件。
• 发现更高版本后询问用户，确认后显示下载进度。
• 新版 INI 只补充当前 INI 缺失的键，绝不覆盖已有连接配置。
• EXE 下载后校验发布尺寸、MZ 文件头和最终下载主机。
• 退出当前程序后由隐藏 PowerShell 脚本替换 EXE 并重启；新版启动失败时恢复旧 EXE。

发布新版本时必须同步修改 APP_VERSION，否则新版仍会被判断为旧版本。

打包

验证：

C:\Users\clear\.conda\envs\clear_conda_main\python.exe -m py_compile pgu4_sync.py
C:\Users\clear\.conda\envs\clear_conda_main\python.exe -m unittest discover -s tests -v

打包：

C:\Users\clear\.conda\envs\clear_conda_main\python.exe -m PyInstaller --clean --noconfirm --onefile --windowed --name PGU-NetFileSyncWin --icon assets\pgu_netfilesync_icon.ico --add-data "assets\pgu_netfilesync_icon.ico;assets" --add-data "assets\pgu_netfilesync_icon.png;assets" --add-binary "C:\Users\clear\.conda\envs\clear_conda_main\Library\bin\libssl-3-x64.dll;." --add-binary "C:\Users\clear\.conda\envs\clear_conda_main\Library\bin\libbz2.dll;." --add-binary "C:\Users\clear\.conda\envs\clear_conda_main\Library\bin\ffi-8.dll;." --exclude-module PyQt5.QtWebEngine --exclude-module PyQt5.QtWebEngineWidgets --exclude-module PyQt5.QtWebKit --exclude-module PyQt5.QtWebKitWidgets --exclude-module matplotlib --exclude-module numpy --exclude-module pandas --exclude-module scipy --exclude-module IPython --exclude-module jupyter --exclude-module notebook --exclude-module pytest --exclude-module tkinter pgu4_sync.py

发布时创建不含任何密码字段的配置文件：

@"
[General]
host=192.168.1.248
port=22
username=clear
remote_path=/home/clear/Data
"@ | Set-Content dist\PGU-NetFileSyncWin.ini -Encoding UTF8

发布

Gitea 仓库：

http://107.173.157.41:3000/clear/PGU-NetFileSyncWin

Release 附件建议只上传：

• PGU-NetFileSyncWin.exe
• PGU-NetFileSyncWin.ini

不要额外上传源码 zip，因为 Gitea 会自动提供源码 ZIP 和 TAR.GZ。

注意事项

• 不要提交 PGU-NetFileSyncWin.ini。
• 不要提交 build/、dist/、release/。
• 发布前确认 exe 为 WINDOWS_GUI 子系统，不显示命令行窗口。
• Windows 可能缓存旧图标，验证图标时需要关闭旧进程，必要时取消任务栏固定。