ProcessDock/README.md

ProcessDock

ProcessDock 是一个使用 Python 和 PySide6 编写的 Windows 原生进程/端口管理工具。它读取本机的真实进程与监听端口，并提供搜索、自动刷新、进程详情和安全确认后的结束操作。

功能

• 查看正在运行的进程，以及 PID、CPU、内存、用户和状态
• 汇总 TCP 监听端口与 UDP 绑定端口，并支持根据端口反查进程
• 按进程名称、PID、端口、用户、路径或启动命令即时搜索
• 点击表格行，在右侧查看程序路径、启动参数、启动时间和父进程 PID
• 打开程序文件位置、复制启动命令、正常结束或强制结束进程
• 每 3 秒自动刷新，也可暂停自动刷新或手动刷新
• 后台线程采集数据，刷新时不阻塞窗口
• 结束前二次确认，并校验进程创建时间，避免 PID 复用导致误操作

环境要求

• Windows 10/11
• Python 3.10 或更高版本（已在 Python 3.11 上验证）

建议使用虚拟环境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

启动

python app.py

不需要控制台窗口时，也可以运行 pythonw ProcessDock.pyw；在 Python 文件关联正常的 Windows 环境中可直接双击 ProcessDock.pyw。

若不希望启动后开启自动刷新：

python app.py --no-auto-refresh

部分系统进程的路径、命令行、端口或结束权限受 Windows 限制。需要管理这些进程时，可右键 PowerShell 或终端并选择“以管理员身份运行”，再启动 ProcessDock。

测试

python -m unittest discover -s tests -v

打包为 EXE

在 PowerShell 中运行：

.\build_exe.ps1

脚本会生成图标、运行测试并构建单文件 GUI 程序，输出位置为 dist\ProcessDock.exe。目标电脑不需要安装 Python；首次启动单文件程序时需要解压 Qt 运行库，因此会比后续启动稍慢。

无窗口界面冒烟测试可以这样运行：

$env:QT_QPA_PLATFORM="offscreen"
python -m unittest tests.test_gui -v

行为说明

• 端口列表聚焦于服务端口：TCP 仅显示 LISTEN，UDP 显示已绑定的本地端口，不展示大量临时的出站连接端口。
• CPU 使用率按所有逻辑核心归一化。Windows 使用批量性能计数器；非 Windows 兼容模式的第一次刷新用于建立采样基线。
• “正常结束”在 Windows 上调用不带 /F 的 taskkill；“强制结束”直接终止进程。强制结束可能丢失未保存的数据。
• ProcessDock 会保护自己的进程，防止从界面中结束自身。
• 本工具只操作当前计算机，不连接远程服务、不上传进程数据，也不使用数据库。

项目结构

app.py                    程序入口
ProcessDock.pyw           无控制台窗口入口
processdock/services.py   进程采集、端口映射和系统操作
processdock/models.py     表格模型、筛选和操作按钮代理
processdock/ui.py         PySide6 主窗口与详情面板
processdock/styles.py     GUI 主题样式
tests/                    自动化测试
docs/blueprint.md         需求证据与验收范围