disk-health-monitor

Disk Health Check

Help users analyze disk space, find large files, clean up caches, and generate system health reports.

Use Cases

• The user says "My computer is running out of space" or "Help me see what's taking up so much space"
• The user says "Clean up the system cache" or "Find the largest files"
• The user says "My computer has gotten slow, help me check it"

Execution Method

Analyze system status through shell commands.Choose the corresponding command set based on the operating system: use bash for macOS/Linux, and PowerShell for Windows.

---

macOS / Linux Command Set

Disk Space Overview

# 各分区使用情况
df -h

# 用户主目录下各子目录占用（按大小降序）
du -sh ~/* 2>/dev/null | sort -rh | head -20

Large File Discovery

# 找出 > 100MB 的文件（排除隐藏目录）
find ~ -type f -size +100M -not -path '*/.*' -exec ls -lhS {} + 2>/dev/null | head -20

# 找出 > 1GB 的文件
find ~ -type f -size +1G -not -path '*/.*' -exec ls -lh {} + 2>/dev/null

Cache Analysis

# macOS 应用缓存
du -sh ~/Library/Caches/* 2>/dev/null | sort -rh | head -10

# Linux 用户缓存
du -sh ~/.cache/* 2>/dev/null | sort -rh | head -10

# 系统临时文件
du -sh /tmp/* 2>/dev/null | sort -rh | head -10

# 开发工具缓存
du -sh ~/.npm/_cacache 2>/dev/null
du -sh ~/Library/Caches/pip 2>/dev/null   # macOS
du -sh ~/.cache/pip 2>/dev/null           # Linux

Duplicate File Detection

# macOS：使用 md5 -r（输出格式与 md5sum 兼容）
find <target_dir> -type f -not -empty -not -path '*/.*' -exec md5 -r {} + 2>/dev/null | sort | uniq -w32 -dD

# Linux：使用 md5sum
find <target_dir> -type f -not -empty -not -path '*/.*' -exec md5sum {} + 2>/dev/null | sort | uniq -w32 -dD

<target_dir> Replace with the directory specified by the user; if not specified, default to ~/Documents。

Old File Discovery

# 180 天未修改的大文件（> 50MB）
# 注意：用 -mtime（修改时间），不要用 -atime（macOS 默认 noatime，访问时间不更新）
find ~ -type f -size +50M -mtime +180 -not -path '*/.*' 2>/dev/null | head -20

---

Windows Command Set (PowerShell)

Disk Space Overview

# 各分区使用情况
Get-PSDrive -PSProvider FileSystem | Select-Object Name,
  @{N='Used(GB)';E={[math]::Round($_.Used/1GB,2)}},
  @{N='Free(GB)';E={[math]::Round($_.Free/1GB,2)}},
  @{N='Total(GB)';E={[math]::Round(($_.Used+$_.Free)/1GB,2)}}

# 用户主目录下各子目录占用（按大小降序）
Get-ChildItem $HOME -Directory | ForEach-Object {
  [PSCustomObject]@{
    Name = $_.Name
    SizeMB = [math]::Round((Get-ChildItem $_.FullName -Recurse -File -ErrorAction SilentlyContinue |
      Measure-Object Length -Sum).Sum / 1MB, 2)
  }
} | Sort-Object SizeMB -Descending | Select-Object -First 20

Large File Discovery

# 找出 > 100MB 的文件
Get-ChildItem $HOME -Recurse -File -ErrorAction SilentlyContinue |
  Where-Object { $_.Length -gt 100MB -and $_.Attributes -notmatch 'Hidden' } |
  Sort-Object Length -Descending |
  Select-Object FullName, @{N='SizeMB';E={[math]::Round($_.Length/1MB,2)}}, LastWriteTime -First 20

# 找出 > 1GB 的文件
Get-ChildItem $HOME -Recurse -File -ErrorAction SilentlyContinue |
  Where-Object { $_.Length -gt 1GB } |
  Select-Object FullName, @{N='SizeGB';E={[math]::Round($_.Length/1GB,2)}}, LastWriteTime

Cache Analysis

# Windows 临时文件
$tempPaths = @($env:TEMP, "$env:LOCALAPPDATA\Temp")
foreach ($p in $tempPaths) {
  if (Test-Path $p) {
    $size = (Get-ChildItem $p -Recurse -File -ErrorAction SilentlyContinue |
      Measure-Object Length -Sum).Sum
    "$p : $([math]::Round($size/1MB, 2)) MB"
  }
}

# npm 缓存
$npmCache = "$env:APPDATA\npm-cache"
if (Test-Path $npmCache) {
  $size = (Get-ChildItem $npmCache -Recurse -File -ErrorAction SilentlyContinue |
    Measure-Object Length -Sum).Sum
  "npm cache: $([math]::Round($size/1MB, 2)) MB"
}

# pip 缓存
$pipCache = "$env:LOCALAPPDATA\pip\Cache"
if (Test-Path $pipCache) {
  $size = (Get-ChildItem $pipCache -Recurse -File -ErrorAction SilentlyContinue |
    Measure-Object Length -Sum).Sum
  "pip cache: $([math]::Round($size/1MB, 2)) MB"
}

Duplicate File Detection

# 按 MD5 哈希查找重复文件
Get-ChildItem <target_dir> -Recurse -File -ErrorAction SilentlyContinue |
  Where-Object { $_.Length -gt 0 -and $_.Attributes -notmatch 'Hidden' } |
  ForEach-Object {
    [PSCustomObject]@{
      Hash = (Get-FileHash $_.FullName -Algorithm MD5).Hash
      Path = $_.FullName
      SizeMB = [math]::Round($_.Length/1MB, 2)
    }
  } | Group-Object Hash | Where-Object { $_.Count -gt 1 } |
  ForEach-Object { $_.Group }

<target_dir> Replace with the directory specified by the user; if not specified, default to $HOME\Documents。

Old File Discovery

# 180 天未修改的大文件（> 50MB）
Get-ChildItem $HOME -Recurse -File -ErrorAction SilentlyContinue |
  Where-Object { $_.Length -gt 50MB -and $_.LastWriteTime -lt (Get-Date).AddDays(-180) } |
  Sort-Object Length -Descending |
  Select-Object FullName, @{N='SizeMB';E={[math]::Round($_.Length/1MB,2)}}, LastWriteTime -First 20

---

Safety Rules

• Do not automatically delete any files: After listing suggestions, use the HITL tool to request user confirmation
• Confirm before cache cleanup: Some caches need to be re-downloaded after cleanup, so the impact must be communicated to the user
• Do not touch core system directories：
  • macOS: skip /System、/Library(note that ~/Library can be scanned)
  • Windows: skip C:\Windows、C:\Program Files、C:\Program Files (x86)
  • Linux: skip /usr、/lib、/boot、/proc、/sys
• Do not scan sensitive directories: skip .ssh、.gnupg、.aws、.kube and other security-related directories
• Hidden files are skipped by default: in bash, find add -not -path '*/.*', and in PowerShell exclude the Hidden attribute

Output Specifications

Generate a structured health report:

## 磁盘健康报告

### 空间概览
- 总空间: XXX GB
- 已用: XXX GB (XX%)
- 可用: XXX GB

### Top 10 大文件
| 文件 | 大小 | 最后修改 |
|---|---|---|

### 缓存占用
| 目录 | 大小 | 建议 |
|---|---|---|

### 清理建议
- 可回收空间: 约 XX GB
- 建议操作: ...（列出具体操作，等用户确认后执行）