disk-space-analyzer 0.1.0

一个功能强大的磁盘空间分析和管理工具，提供直观的可视化界面、安全的删除机制和灵活的分析选项

磁盘空间分析工具

一个功能强大的磁盘空间分析和管理工具，提供直观的可视化界面、安全的删除机制和灵活的分析选项。

功能特性

核心功能

1. 磁盘信息可视化

• ✅ 物理分区自动去重识别
• ✅ 本地磁盘与远程挂载分类显示
• ✅ 点击分区卡片查看交互式目录树
• ✅ 实时容量和使用率监控

2. 目录分析

• ✅ 可配置分析深度（1-5层）
• ✅ 灰活的排除规则（路径、扩展名）
• ✅ 实新进度显示
• ✅ 表格视图和树形视图双模式
• ✅ 表格视图多级树形展开（最新）
• ✅ 中文路径支持（最新）

3. 安全删除

• ✅ 双重验证机制（最新功能）
  • 路径手动输入验证（禁止粘贴）
  • 随机验证码验证（加减法运算）
• ✅ 系统关键目录保护
• ✅ 删除前详细信息确认
• ✅ 操作不可逆警告

4. UI优化（进行中）

• 🔨 侧边栏布局（CSS已完成）
• ⏳ 磁盘卡片显示模式切换（Mini/横条/完整）
• ⏳ 分析结果视觉增强
• ⏳ 响应式设计

快速开始

方式1：通过 pip 安装（推荐）

从本地源码安装

# 克隆仓库（如果还没有）
git clone https://github.com/username/disk_analyzer.git
cd disk_analyzer

# 常规安装
pip install .

# 或者开发模式安装（代码修改实时生效）
pip install -e .

# 安装开发依赖
pip install -e .[dev]

从 PyPI 安装（未来可用）

pip install disk-analyzer

方式2：手动安装依赖

pip install -r requirements.txt

启动应用

使用命令行工具（pip 安装后）

# 标准启动
disk-analyzer

# 调试模式
disk-analyzer --debug

# 自定义端口
disk-analyzer --port 9090

# 不自动打开浏览器
disk-analyzer --no-browser

# 查看版本
disk-analyzer --version

使用 Python 模块运行

python -m disk_analyzer
python -m disk_analyzer --debug

使用传统脚本（向后兼容）

# 标准模式
python start_disk_tool.py

# 调试模式（支持热更新）
python start_disk_tool.py --debug

作为 Python 库使用

from disk_analyzer import DiskAnalyzer

# 创建分析器实例
analyzer = DiskAnalyzer(max_depth=3)

# 分析目录
results = analyzer.analyze_directory('/path/to/analyze')

# 处理结果
for item in results:
    print(f"{item.path}: {item.size_human}")

访问界面

打开浏览器访问：http://localhost:8080

技术栈

后端

• 框架：Flask 2.x
• 语言：Python 3.8+
• 架构：MVC模式

前端

• 框架：Bootstrap 5.1.3
• 图标：Bootstrap Icons 1.7.2
• 样式：原生CSS + 渐变设计

数据存储

• 配置存储：localStorage（浏览器本地）
• 无需数据库

项目结构

disk_analyzer/
├── disk_analyzer/              # 主包目录
│   ├── __init__.py            # 包初始化，导出公共API
│   ├── __main__.py            # 支持 python -m disk_analyzer 运行
│   ├── analyzer.py            # 磁盘分析核心逻辑
│   ├── web_app.py             # Web应用（Flask + HTML/JS）
│   └── cli.py                 # 命令行入口
├── docs/                        # 文档目录
│   ├── 1-设计/                  # 设计文档
│   │   ├── 磁盘信息可视化优化实现文档.md
│   │   ├── 功能扩展与UI优化实施进度.md
│   │   └── 表格视图多层级展开修复与路径显示优化.md
│   ├── 200-需求管理/            # 需求文档
│   │   └── 功能扩展与UI优化需求.md
│   └── changelog/               # 详细变更日志
│       ├── CHANGLOG-20251222-192109.md (✨最新)
│       ├── CHANGLOG-20251222-181038.md
│       ├── CHANGELOG-20251222-133710.md
│       ├── CHANGLOG-20251222-132701.md
│       └── CHANGLOG-20251222-132000.md
├── pyproject.toml               # 现代化项目配置
├── setup.py                     # 传统安装配置（向后兼容）
├── MANIFEST.in                  # 非代码文件清单
├── LICENSE                      # MIT 开源许可证
├── requirements.txt             # Python依赖
├── CHANGELOG.md                 # 全局变更日志
├── README.md                    # 项目说明
├── PUBLISHING_GUIDE.md          # PyPI发布指南
├── scripts/                     # 发布和版本管理脚本
│   ├── README.md                # 脚本使用说明
│   ├── publish.sh               # 交互式发布脚本
│   ├── bump_version.py          # 版本号更新脚本
│   └── check_release.py         # 发布前检查脚本
└── start_disk_tool.py           # 传统启动器（向后兼容）

使用指南

1. 分析磁盘目录

1. 在"分析设置"中输入要分析的路径（默认 /）
2. 设置分析深度（1-5层，默认3层）
3. 可选：添加排除路径或扩展名
4. 点击"开始分析"
5. 等待分析完成，查看表格视图或树形视图

2. 查看分区详情

1. 在"系统磁盘信息"区域查看所有分区
2. 点击任意分区卡片
3. 弹窗显示该分区的目录树结构

3. 安全删除目录

1. 在分析结果中找到要删除的目录
2. 点击"删除"按钮
3. 安全验证步骤：
   • 步骤1：手动输入完整路径（禁止粘贴）
   • 步骤2：计算并输入验证码答案
4. 两项验证通过后点击"确认删除"

4. 排除规则配置

排除路径示例：

/tmp,/var/log,/home/user/.cache

排除扩展名示例：

.log,.tmp,.cache,.bak

API参考

获取分区列表

GET /api/partitions

获取分区目录树

POST /api/partition-tree
Body: {
  "mount_point": "/",
  "max_depth": 2,
  "limit": 20
}

开始目录分析

POST /api/analyze
Body: {
  "path": "/",
  "depth": 3,
  "limit": 50,
  "exclude_paths": ["/tmp"],
  "exclude_extensions": [".log"]
}

查询分析进度

GET /api/analysis-progress/{analysis_id}

安全删除文件/目录

POST /api/delete
Body: {
  "path": "/path/to/delete"
}

安全性

删除操作安全机制

前端验证：

• ✅ 路径完全匹配（区分大小写）
• ✅ 禁止复制粘贴（强制手动输入）
• ✅ 随机验证码验证
• ✅ 实时状态反馈

后端保护：

• ✅ 系统关键目录拦截（/、/proc、/sys等）
• ✅ 路径规范化（防止相对路径逃逸）
• ✅ 权限检查
• ✅ 错误分类处理

建议增强（后续版本）：

• 后端路径二次验证
• 删除操作日志记录
• 回收站机制（可撤销删除）

性能优化

• ✅ 分区识别使用设备号，性能开销可忽略
• ✅ 树形分析限制深度和数量，单次分析耗时1-3秒
• ✅ CSS transition代替JavaScript动画，提升帧率
• ✅ 前端渲染初始仅渲染前两层，深层节点懒加载

浏览器兼容性

• Chrome/Edge ≥ 90
• Firefox ≥ 88
• Safari ≥ 14

版本历史

alpha-1.0 (2025-12-22)

• ✅ 删除安全机制强化（双重验证）
• 🔨 侧边栏布局优化（CSS框架）
• 📝 文档体系建立

详见：CHANGELOG.md

开发计划

短期（本周）

• 完成侧边栏HTML结构重构
• 实现侧边栏折叠/展开功能
• 实现磁盘卡片显示模式切换
• 分析结果视觉增强

中期（下周）

• 树形结构多级展开
• 系统磁盘信息折叠功能
• 全面测试和优化
• 浏览器兼容性测试

长期（未来迭代）

• 后端路径验证增强
• 删除操作日志记录
• 撤销删除功能
• 键盘快捷键支持
• 暗色模式
• 导出PDF报告

贡献指南

开发规范

请参考项目规范文档：

• .cursor/rules/ep.mdc - 主导航索引
• .cursor/rules/需求分析流程.mdc - 需求分析规范
• .cursor/rules/任务管理与功能点完成流程.mdc - 任务管理规范

提交规范

遵循约定式提交（Conventional Commits）：

feat: 添加新功能
fix: 修复Bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关

许可证

[待定]

联系方式

[待补充]

致谢

• Bootstrap - 前端UI框架
• Flask - Python Web框架
• Bootstrap Icons - 图标库
• Firefox ≥ 88
• Safari ≥ 14

版本历史

alpha-1.0 (2025-12-22)

• ✅ 删除安全机制强化（双重验证）
• 🔨 侧边栏布局优化（CSS框架）
• 📝 文档体系建立

详见：CHANGELOG.md

开发计划

短期（本周）

• 完成侧边栏HTML结构重构
• 实现侧边栏折叠/展开功能
• 实现磁盘卡片显示模式切换
• 分析结果视觉增强

中期（下周）

• 树形结构多级展开
• 系统磁盘信息折叠功能
• 全面测试和优化
• 浏览器兼容性测试

长期（未来迭代）

• 后端路径验证增强
• 删除操作日志记录
• 撤销删除功能
• 键盘快捷键支持
• 暗色模式
• 导出PDF报告

贡献指南

开发规范

请参考项目规范文档：

• .cursor/rules/ep.mdc - 主导航索引
• .cursor/rules/需求分析流程.mdc - 需求分析规范
• .cursor/rules/任务管理与功能点完成流程.mdc - 任务管理规范

提交规范

遵循约定式提交（Conventional Commits）：

feat: 添加新功能
fix: 修复Bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关

发布和版本管理

项目提供了完整的发布和版本管理工具：

1. 版本号管理：使用 scripts/bump_version.py 脚本统一更新所有文件中的版本号
2. 发布前检查：运行 scripts/check_release.py 确保发布准备工作完成
3. 交互式发布：使用 scripts/publish.sh 脚本进行交互式发布
4. 详细指南：查看 PUBLISHING_GUIDE.md 获取完整的PyPI发布指南

详细信息请参考 scripts/README.md。

许可证

[待定]

联系方式

[待补充]

致谢

• Bootstrap - 前端UI框架
• Flask - Python Web框架
• Bootstrap Icons - 图标库