# ProcessDock

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

## 功能

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

## 环境要求

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

建议使用虚拟环境：

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

## 启动

```powershell
python app.py
```

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

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

```powershell
python app.py --no-auto-refresh
```

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

## 测试

```powershell
python -m unittest discover -s tests -v
```

## 打包为 EXE

在 PowerShell 中运行：

```powershell
.\build_exe.ps1
```

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

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

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

## 行为说明

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

## 项目结构

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