dsh-fs-inspector

DeepSeek Harness 文件系统巡检插件：目录体积统计（Top N 子目录 / 大文件）与最近修改文件查询。只读、零运行时依赖。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-fs-inspector
• npm：https://www.npmjs.com/package/dsh-fs-inspector

安装

npm install dsh-fs-inspector

使用说明

dir_size —— 目录体积统计

递归统计目录的总大小、文件数、子目录数，并按大小列出 Top N 子目录或大文件。

用户：看看 E:\projects 里哪些目录最占空间

目录：E:\projects
总大小：2.31 GB（2478567424 字节）
文件数：18234，子目录数：1204
忽略目录：.git

Top 10 子目录（按聚合大小）：
  1.   1.42 GB  目录  frontend\node_modules
  2.   512.10 MB  目录  backend\target
  ...

参数：

| 参数 | 说明 | |---|---| | path | 目录路径，默认当前目录 | | top | Top N，默认 10，上限 100 | | mode | dirs（子目录，默认）/ files（大文件）/ both | | ignore | 忽略的目录名，逗号分隔，默认 .git；传空字符串表示不忽略任何目录 |

recent_files —— 最近修改文件

按修改时间倒序列出文件，支持时间范围与扩展名过滤。

用户：这个目录里最近 3 天改过哪些 markdown 文件

目录：E:\projects\docs
匹配文件：7 个（since 3d）（扩展名 .md）

最近修改的 7 个文件：
  1. 2026-09-21T02:14:33.000Z    12.30 KB  guide/setup.md
  2. 2026-09-20T11:02:10.000Z     4.10 KB  README.md
  ...

参数：path、limit（默认 20，上限 200）、since（7d / 12h / 30m / 2w 或 ISO 时间 2026-09-01）、extensions（如 .md,.js）、ignore。

典型场景

1. 磁盘占用排查

用户：C 盘这个项目怎么这么大，帮我看看

用 dir_size 的默认 dirs 模式定位到 node_modules / target / 构建产物目录，再对可疑目录单独跑一次 dir_size 逐层下钻。

2. 清理前的影响面评估

用户：我想删掉 dist 目录，先看看它多大、里面有多少文件

dir_size 输出子目录聚合大小与总文件数，删除前先确认规模（本插件只统计不删除）。

3. 最近改动巡检 / 日报素材

用户：这周我改了哪些文件

recent_files 传 since=7d，按 mtime 倒序得到改动清单，可作为周报依据。

4. 构建产物新鲜度检查

用户：dist 是不是过期了，比源码旧？

对源码目录与 dist 目录分别跑 recent_files，对比最新 mtime 判断产物是否落后于源码。

5. 仓库体积体检

用户：仓库里有没有意外提交的大文件

dir_size 传 mode=files、ignore=（空，含 .git 目录）可看到最大文件排行，快速发现误提交的大文件。

安全边界

• 只读：两个工具仅执行 readdir / stat / lstat，不创建、不修改、不删除任何文件；测试中含"调用后目录内容与大小不变"的只读性断言。
• 不跟随符号链接：目录扫描跳过软链接，避免环路死循环与越出指定目录范围的遍历。
• 规模上限：单次扫描最多 20 万条目，超出即截断并在输出中标注 ⚠，防止超大目录导致长时间占用。
• 无权限静默降级：遇到 EACCES/EPERM 的子目录跳过并在条目中标注，不中断整体统计。
• 不读取文件内容：只读取元数据（大小、mtime），不打开文件，不涉及敏感内容泄露。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-table-render | 把 dir_size 的 Top N 输出整理为数据后渲染成对齐表格（含中文目录名） | | dsh-hash-checksum | 对 dir_size / recent_files 定位到的大文件进一步计算 sha256，用于校验或去重判断 | | dsh-file-search（二期 D10） | dir_size 先定位大目录，再用 file-search 在目标范围内做内容检索，缩小搜索面 | | dsh-folder-tree（二期 D9） | 体积统计与目录树结构展示互补：一个看"多大"，一个看"长什么样" | | dsh-file-manager-cli | 本插件负责"看"（只读统计），实际移动/删除/重命名交给 file-manager-cli | | dsh-workspace-journal | 把巡检结果（体积变化、最近改动）写入工作区日志，形成长期趋势记录 |

版本说明

• 0.1.0（2026-09-21）：初始版本。
  • dir_size：递归体积统计 + Top N 子目录/大文件、ignore 名单、20 万条目截断保护
  • recent_files：mtime 倒序 + since 相对时长（d/h/m/w）/ ISO 时间 + 扩展名过滤
  • 只读保证、软链接跳过、无权限降级

RoadMap

v0.2（计划）

• dir_size 增加 depth 参数，限制下钻层数
• 新增 du_compare：两次扫描结果对比，输出体积增减 Top N（定位"谁把仓库撑大了"）
• recent_files 支持按作者（需 git）或按文件类型分组统计
• 大目录扫描并发化，缩短超大目录耗时

v0.3（展望）

• 体积快照落盘 + 趋势报告（与 workspace-journal 联动）
• 重复文件检测（按 size + 前缀哈希预筛，再全量哈希确认）
• 排除规则支持 glob 模式（当前仅按目录名精确匹配）

FAQ

Q：为什么默认忽略 .git？ .git 内部对象文件多且体积大，通常不是排查目标。需要统计时传 ignore=（空字符串）即可包含。

Q：node_modules 为什么没被默认忽略？ 因为排查"目录为什么这么大"时，node_modules 往往正是答案。它体积大但可重建，本插件如实统计，是否清理由你决定。

Q：软链接目录里的文件为什么没统计到？ 为避免环路与越界遍历，扫描跳过所有符号链接。这是刻意的安全取舍。

Q：since 的 m 是月还是分钟？ 分钟（30m = 30 分钟）；周用 w（2w = 2 周）。月份请用 ISO 时间表达。

Q：扫描很慢/结果不完整？ 单次上限 20 万条目，超出会标注 ⚠ 并给出部分结果。建议缩小 path 范围或对子目录分别扫描。

Q：能帮我删除大文件吗？ 不能，本插件严格只读。删除请使用 dsh-file-manager-cli 并自行确认影响。

许可证

MIT