change tk

AGENTS.md

@@ -1,275 +1,161 @@
-# Linux 存储管理器 (Linux Storage Manager) - AI Agent Guide
+# Linux 存储管理器 (Linux Storage Manager)
 
 ## 项目概述
 
-这是一个基于 PySide6 开发的 Linux 存储管理图形界面工具，提供磁盘管理、逻辑卷管理(LVM)和软阵列管理(RAID)三大核心功能。
+这是一个基于 PySide6 开发的 Linux 图形化存储管理工具，提供磁盘管理、逻辑卷管理(LVM)和软 RAID 管理功能。应用程序通过调用系统命令（如 `lsblk`, `parted`, `mdadm`, `lvm` 等）与 Linux 存储子系统交互。
 
-**主要功能模块：**
-1. **磁盘管理** - 分区创建/删除、格式化(ext4/xfs/ntfs/fat32)、挂载/卸载、分区表擦除
-2. **LVM 管理** - 物理卷(PV)、卷组(VG)、逻辑卷(LV)的创建和管理
-3. **RAID 管理** - 软阵列创建、管理、停止/启动阵列 (支持 RAID0/1/5/6/10)
+### 主要功能模块
+
+1. **块设备管理** - 查看磁盘信息、创建分区、格式化文件系统(ext4/xfs/ntfs/fat32)、挂载/卸载设备
+2. **LVM 管理** - 物理卷(PV)、卷组(VG)、逻辑卷(LV)的创建、删除和扩容
+3. **RAID 管理** - 软 RAID 阵列的创建、删除和监控（支持 RAID0/1/5/6/10）
 
 ## 技术栈
 
-| 组件 | 说明 |
-|------|------|
-| Python 3.14+ | 主要编程语言 |
-| PySide6 | Qt6 的 Python 绑定，用于 GUI |
-| Qt Designer (.ui 文件) | UI 设计文件 |
-| PyInstaller | 打包工具，生成独立可执行文件 |
-| 系统工具 | parted, mkfs.*, mount, umount, lvm2, mdadm, lsblk, findmnt |
+- **GUI 框架**: PySide6 (Qt for Python)
+- **UI 设计**: Qt Designer (form.ui)
+- **构建工具**: PyInstaller
+- **依赖库**: 
+  - PySide6 - GUI 框架
+  - pexpect - 交互式命令执行（用于 RAID 创建时的密码输入）
 
 ## 项目结构
 
 ```
 .
-├── mainwindow.py          # 主窗口，UI 与业务逻辑控制器
-├── ui_form.py             # 自动生成的 UI 代码 (从 form.ui 生成)
-├── form.ui                # Qt Designer UI 定义文件
-├── system_info.py         # 系统信息获取模块 (块设备、RAID、挂载点)
-├── disk_operations.py     # 磁盘操作 (分区、格式化、挂载)
-├── lvm_operations.py      # LVM 操作 (PV/VG/LV 管理)
-├── raid_operations.py     # RAID 操作 (mdadm 管理)
-├── dialogs.py             # 自定义对话框 (创建分区、RAID、PV/VG/LV 等)
-├── occupation_resolver.py # 设备占用解除模块 (处理挂载、进程占用)
-├── logger_config.py       # 日志配置 (输出到 QTextEdit 和控制台)
-├── pyproject.toml         # PySide6 项目配置
-├── disk-manager.spec      # PyInstaller 打包配置 (英文版)
-├── Linux存儲管理器.spec   # PyInstaller 打包配置 (中文版)
-└── build-app.sh           # 打包脚本
+├── mainwindow.py          # 应用程序入口，主窗口逻辑，连接各模块
+├── ui_form.py             # 由 form.ui 自动生成的 UI 类
+├── form.ui                # Qt Designer UI 定义文件（主界面布局）
+├── dialogs.py             # 自定义对话框（分区创建、挂载、RAID/LVM 创建等）
+├── system_info.py         # 系统信息获取模块（lsblk 解析等）
+├── disk_operations.py     # 磁盘操作（分区、格式化、挂载管理）
+├── lvm_operations.py      # LVM 操作（PV/VG/LV 管理）
+├── raid_operations.py     # RAID 操作（mdadm 命令封装）
+├── occupation_resolver.py # 设备占用检测与解除（嵌套挂载、进程占用）
+├── logger_config.py       # 日志配置（输出到 QTextEdit 控件）
+├── pyproject.toml         # PySide6 项目配置文件
+├── disk-manager.spec      # PyInstaller 打包配置
+└── build-app.sh           # 构建脚本
 ```
 
-## 代码组织
-
-### 模块依赖关系
+## 模块依赖关系
 
 ```
-mainwindow.py (入口)
-    ├── ui_form.py (自动生成的 UI)
+mainwindow.py
+    ├── ui_form.py (UI 布局)
     ├── system_info.py (系统信息)
+    ├── logger_config.py (日志)
     ├── disk_operations.py (磁盘操作)
-    │   └── 依赖: system_info.py, lvm_operations.py
-    ├── lvm_operations.py (LVM 操作，提供 _execute_shell_command)
+    │       └── 依赖 system_info.py, lvm_operations.py
     ├── raid_operations.py (RAID 操作)
-    │   └── 依赖: system_info.py
-    ├── occupation_resolver.py (占用解除)
-    │   └── 依赖: lvm_operations.py, system_info.py
-    ├── dialogs.py (对话框)
-    └── logger_config.py (日志)
+    │       └── 依赖 system_info.py
+    ├── lvm_operations.py (LVM 操作)
+    ├── occupation_resolver.py (占用解决)
+    │       └── 依赖 lvm_operations.py, system_info.py
+    └── dialogs.py (对话框)
+            └── 依赖 logger_config.py
 ```
 
-### 核心类说明
+## 代码组织规范
 
-| 类名 | 文件 | 职责 |
-|------|------|------|
-| `MainWindow` | mainwindow.py | 主窗口，整合所有功能，处理用户交互 |
-| `SystemInfoManager` | system_info.py | 获取系统块设备信息、RAID 信息、挂载点 |
-| `DiskOperations` | disk_operations.py | 磁盘分区、格式化、挂载操作 |
-| `LvmOperations` | lvm_operations.py | LVM 相关操作，提供统一的 shell 命令执行接口 |
-| `RaidOperations` | raid_operations.py | RAID 阵列管理 |
-| `OccupationResolver` | occupation_resolver.py | 解除设备占用 (嵌套挂载、进程占用) |
-| `FormatWorker` | disk_operations.py | 后台格式化工作线程 |
-| `QTextEditLogger` | logger_config.py | 自定义日志处理器，输出到 UI |
+### 文件命名
+- 模块文件使用下划线命名法：`disk_operations.py`, `lvm_operations.py`
+- UI 相关文件：`form.ui`（设计源文件）, `ui_form.py`（自动生成）
 
-### 对话框类 (dialogs.py)
+### 类命名规范
+- 主窗口类：`MainWindow`
+- UI 类：`Ui_MainWindow`（Qt 自动生成）
+- 操作类：`DiskOperations`, `LvmOperations`, `RaidOperations`
+- 对话框类：`CreatePartitionDialog`, `MountDialog`, `CreateRaidDialog`
+- 工具类：`SystemInfoManager`, `OccupationResolver`
 
-- `CreatePartitionDialog` - 创建分区对话框
-- `MountDialog` - 挂载分区对话框
-- `CreateRaidDialog` - 创建 RAID 阵列对话框
-- `CreatePvDialog` - 创建物理卷对话框
-- `CreateVgDialog` - 创建卷组对话框
-- `CreateLvDialog` - 创建逻辑卷对话框
+### 命令执行模式
+所有系统命令执行都通过 `_execute_shell_command` 或 `_run_command` 方法封装，统一处理：
+- sudo 权限提升
+- 错误处理和日志记录
+- QMessageBox 错误提示（可抑制）
 
-## 构建和打包
+## 构建和运行
 
-### 依赖安装
+### 运行环境要求
+- Linux 操作系统（需要 root/sudo 权限执行存储管理命令）
+- Python 3.x
+- 系统依赖：`parted`, `mdadm`, `lvm2`, `dosfstools`, `e2fsprogs`, `xfsprogs`, `ntfs-3g`
 
+### 安装依赖
 ```bash
-pip install PySide6 pyinstaller pexpect
+pip install PySide6 pexpect
 ```
 
-### 开发运行
-
+### 运行应用
 ```bash
-# 直接运行
 python mainwindow.py
-
-# 注意: 部分功能需要 root 权限
-sudo python mainwindow.py
 ```
+注意：大部分功能需要 root 权限，建议以 sudo 运行或确保用户有 sudo 权限。
 
-### 生成可执行文件
-
+### 打包可执行文件
 ```bash
-# 使用 PyInstaller (需要配置虚拟环境路径)
-sudo /path/to/venv/bin/pyinstaller -F --name "disk-manager" mainwindow.py
+# 使用 PyInstaller
+sudo pyinstaller -F --name "disk-manager" mainwindow.py
 
-# 或使用提供的打包脚本 (需修改路径)
-bash build-app.sh
+# 或使用提供的脚本
+sudo ./build-app.sh
 ```
 
-打包配置文件:
-- `disk-manager.spec` - 英文名称配置
-- `Linux存儲管理器.spec` - 中文名称配置
+打包后的可执行文件位于 `dist/disk-manager`。
 
-## UI 设计规范
-
-### 界面布局 (form.ui)
-
-主窗口包含:
-1. **刷新按钮** - 刷新所有设备信息
-2. **标签页控件** - 三个标签页:
-   - 块设备概览 (treeWidget_block_devices)
-   - RAID 管理 (treeWidget_raid)
-   - LVM 管理 (treeWidget_lvm)
-3. **日志输出区** (logOutputTextEdit) - 显示操作日志
-
-### 修改 UI 的流程
+## 开发注意事项
 
+### UI 修改流程
 1. 使用 Qt Designer 编辑 `form.ui`
-2. 使用 `pyside6-uic` 重新生成 `ui_form.py`:
-   ```bash
-   pyside6-uic form.ui -o ui_form.py
-   ```
-3. 注意：`ui_form.py` 是自动生成的，不要手动修改
+2. 使用 `pyside6-uic form.ui -o ui_form.py` 重新生成 Python UI 文件
+3. 或在 Qt Creator 中配置 PySide6 项目自动处理
 
-## 编码规范
+### 日志系统
+- 使用 `logger_config.py` 中配置的全局 logger
+- 日志同时输出到控制台和 GUI 的 QTextEdit 控件
+- 日志级别：`logging.DEBUG`（开发时可调整）
 
-### 代码风格
-
-- 使用 4 空格缩进
-- 函数和变量使用小写加下划线命名 (snake_case)
-- 类名使用大驼峰命名 (PascalCase)
-- 注释和日志使用中文
+### 线程安全
+- 格式化操作使用 `FormatWorker` 在后台线程执行，避免阻塞 UI
+- 通过 Qt Signal/Slot 机制与主线程通信
 
 ### 错误处理
+- 所有 shell 命令执行都有统一的错误处理
+- 关键错误会弹出 QMessageBox 提示用户
+- 详细错误信息写入日志
 
-所有 shell 命令执行通过 `_execute_shell_command` 方法统一处理:
-- 自动处理 sudo 权限
-- 统一的错误对话框显示
-- 详细的日志记录
+## 系统命令依赖
 
-示例:
-```python
-success, stdout, stderr = self.lvm_ops._execute_shell_command(
-    ["parted", "-s", device_path, "mklabel", "gpt"],
-    f"擦除 {device_path} 上的分区表失败"
-)
-```
+应用依赖以下 Linux 命令行工具：
 
-### 日志记录
-
-使用标准 logging 模块，配置在 `logger_config.py`:
-- DEBUG: 详细的调试信息
-- INFO: 常规操作信息
-- WARNING: 警告信息
-- ERROR: 错误信息
-
-日志同时输出到:
-1. 控制台 (标准输出)
-2. UI 的 QTextEdit 控件 (通过 QTextEditLogger)
-
-## 关键实现细节
-
-### 1. 权限处理
-
-所有需要 root 权限的操作都通过 `sudo` 执行。项目中没有直接处理密码输入，依赖系统的 sudo 配置。
-
-### 2. 异步操作
-
-格式化操作使用 `QThread` + `FormatWorker` 在后台执行，避免阻塞 UI:
-```python
-# 信号定义
-formatting_finished = Signal(bool, str, str, str)  # success, device, stdout, stderr
-formatting_started = Signal(str)
-```
-
-### 3. 设备识别
-
-- 使用 `lsblk -J` 获取块设备信息 (JSON 格式)
-- 支持通过设备路径或 maj:min 号识别设备
-- 正确处理符号链接 (如 LVM 设备、RAID 别名)
-
-### 4. 占用解除
-
-`OccupationResolver` 类处理复杂的设备占用情况:
-- 嵌套挂载点卸载
-- 用户进程占用检测和终止
-- 交换分区关闭
-
-## 测试策略
-
-当前项目没有自动化测试套件。测试主要依赖:
-
-1. **手动测试** - 在真实 Linux 环境中测试各项功能
-2. **日志验证** - 通过日志输出验证操作执行
-
-**测试环境要求:**
-- Linux 系统 (建议 Ubuntu/Debian 或 Arch Linux)
-- 安装必要工具: `parted`, `lvm2`, `mdadm`, `dosfstools`, `ntfs-3g`
-- 测试磁盘建议使用虚拟机或空闲磁盘，避免数据丢失
-
-## 安全注意事项
-
-⚠️ **危险操作警告:**
-
-1. **格式化操作** - 会永久删除数据
-2. **分区删除** - 会丢失分区数据
-3. **分区表擦除** - 会清除整个磁盘分区信息
-4. **RAID 操作** - 错误的操作可能导致阵列损坏
-
-**安全准则:**
-- 所有危险操作都有确认对话框
-- 操作前会记录警告日志
-- 建议只在测试环境或已备份的系统上使用
-- 部分操作不可逆，请谨慎操作
-
-## 外部依赖工具
-
-应用程序依赖以下系统工具:
-
-| 工具 | 用途 |
+| 功能 | 命令 |
 |------|------|
-| lsblk | 获取块设备信息 |
-| parted | 分区管理 |
-| mkfs.ext4/mkfs.xfs/mkfs.vfat/mkfs.ntfs | 文件系统格式化 |
-| mount/umount | 挂载/卸载 |
-| lvm (pvcreate/vgcreate/lvcreate 等) | LVM 管理 |
-| mdadm | RAID 管理 |
-| findmnt | 挂载点查询 |
-| fuser | 进程占用查询 |
-| stat | 设备信息获取 |
-| pexpect | 交互式命令执行 (RAID 创建) |
+| 块设备信息 | `lsblk` |
+| 分区操作 | `parted`, `partprobe` |
+| 文件系统 | `mkfs.ext4`, `mkfs.xfs`, `mkfs.ntfs`, `mkfs.vfat` |
+| 挂载管理 | `mount`, `umount`, `findmnt` |
+| RAID 管理 | `mdadm` |
+| LVM 管理 | `pvcreate`, `vgcreate`, `lvcreate`, `pvs`, `vgs`, `lvs` 等 |
+| 进程查询 | `lsof`, `fuser` |
 
-## 配置说明
+## 安全考虑
 
-### pyproject.toml
+1. **权限要求**: 应用需要 root/sudo 权限执行存储管理操作
+2. **危险操作确认**: 格式化、删除分区/卷等操作都有确认对话框
+3. **设备占用检测**: `OccupationResolver` 模块检测并解除设备占用（卸载挂载点、停止进程）后才执行操作
+4. **fstab 备份**: 修改 `/etc/fstab` 前建议用户手动备份
 
-PySide6 项目配置文件，定义项目文件列表:
-```toml
-[tool.pyside6-project]
-files = ["dialogs.py", "disk_operations.py", ...]
-```
+## 已知限制
 
-### .gitignore
+- 仅支持 Linux 系统
+- 需要图形桌面环境
+- 部分操作（如 RAID 创建）可能需要密码输入
+- 不支持 LVM/RAID 的降级恢复等高级场景
 
-排除目录:
-- /dist/ - PyInstaller 输出
-- /build/ - 构建缓存
-- /.qtcreator/ - Qt Creator 配置
-- /__pycache__/ - Python 缓存
+## 调试建议
 
-## 开发工作流
-
-1. **修改 UI**: 编辑 `form.ui` → 运行 `pyside6-uic` 生成 `ui_form.py`
-2. **添加功能**: 在相应模块添加逻辑，在 `MainWindow` 添加槽函数
-3. **测试**: 在 Linux 环境中运行 `python mainwindow.py`
-4. **打包**: 运行 `build-app.sh` 或直接使用 PyInstaller
-5. **提交**: 使用 `up+.sh` 脚本辅助 git 提交 (需配置)
-
-## 常见问题
-
-1. **UI 更新不生效** - 检查是否重新生成了 `ui_form.py`
-2. **权限错误** - 确保以 sudo 运行或配置 sudo 免密
-3. **命令未找到** - 安装对应的系统工具包
-4. **RAID 创建卡住** - pexpect 交互处理可能需要调整
+1. 查看日志输出（GUI 底部 QTextEdit 或控制台）
+2. 检查系统命令是否安装：`which parted mdadm lvm`
+3. 手动测试命令：`sudo lsblk -J`
+4. 检查权限：确保用户有 sudo 权限或已切换到 root