dsh-folder-tree

DeepSeek Harness 目录树插件：以树形文本渲染目录结构（深度可控、可忽略 node_modules/.git、防符号链接环路），并统计目录/文件数与扩展名分布。只读、零运行时依赖。

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

安装

npm install dsh-folder-tree

使用说明

render_tree —— 渲染目录树

以树形文本展示目录结构，支持深度控制、忽略目录、仅显示目录、附带文件大小。

用户：看下这个项目长什么样

E:\dsh-plugins\dsh-folder-tree/
├── README.md
├── cordis.patch.yml
├── index.js
├── package.json
└── test-plugin.js

0 个目录，5 个文件（深度 ≤ 3）
忽略：node_modules, .git

带下钻与目录优先排序：

E:\projects\demo/
├── docs/
│   └── guide.md
├── src/
│   ├── sub/
│   ├── a.js
│   └── b.js
└── README.md

3 个目录，4 个文件（深度 ≤ 3）
忽略：node_modules, .git

参数：

| 参数 | 说明 | |---|---| | path | 目录路径，默认当前目录 | | depth | 最大下钻层数，默认 3，上限 10（根的直接子项为第 1 层） | | ignore | 忽略的目录名，逗号分隔，默认 node_modules,.git；传空字符串表示不忽略 | | dirs_only | 仅显示目录，默认 false | | show_size | 在文件名后附带大小，默认 false | | limit | 最多渲染的条目数，默认 200，上限 2000 |

tree_stats —— 目录结构统计

统计目录数、文件数、实际最大深度，并按扩展名给出文件数量与体积分布。

用户：这个目录里文件类型都是什么

目录：E:\projects\demo
目录数：3，文件数：5
最大深度：3（统计上限 3）

按扩展名分布（Top 10）：
  .md              3 个       360 B
  .js              2 个       300 B

参数：path、depth（默认 3，上限 10）、ignore（默认 node_modules,.git）、top（扩展名展示条数，默认 10，上限 50）。

典型场景

1. 快速了解项目结构

用户：这个仓库的目录结构是怎样的

render_tree 用默认 depth=3 一次看清主干；node_modules/.git 默认被忽略，输出干净。

2. 定位某个目录的位置

用户：组件都放在哪一层

render_tree 传 dirs_only=true，只看目录骨架，快速把握层级。

3. 排查体积异常的目录

用户：哪个子目录文件特别多

tree_stats 看目录/文件数，再配合 render_tree 的 show_size=true 定位大文件。

4. 交付前的目录体检

用户：打包前确认没把 node_modules 带进去

render_tree 传 ignore=（空）即可把被忽略的目录也显示出来，确认实际包含内容。

5. 技术栈分布速览

用户：这个项目主要是什么语言

tree_stats 的扩展名分布 Top N 直接给出文件类型构成。

安全边界

• 只读：两个工具仅执行 readdir / stat / lstat，不创建、不修改、不删除任何文件；测试中含"调用后文件数不变"的只读性断言。
• 符号链接一律跳过：目录扫描不跟随任何软链接/junction，从根源上杜绝环路死循环与越出指定目录范围的遍历（测试中以 junction 指回祖先目录验证）。
• 深度与条目双重上限：depth 上限 10、limit 上限 2000、扫描条目上限 20 万，超出即截断并标注 ⚠，防止超大目录导致长时间占用。
• 无权限静默降级：遇到无权限的子目录跳过，不中断整体渲染与统计。
• 不读取文件内容：只读取目录项与文件元数据（名称、大小），不打开文件，不涉及敏感内容泄露。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-fs-inspector | 一个看"长什么样"（folder-tree），一个看"多大"（fs-inspector），配合定位体积异常目录 | | dsh-file-search（二期 D10） | 先用 render_tree 摸清结构，再用 file-search 在目标目录做内容检索 | | dsh-table-render | 把 tree_stats 的扩展名分布整理为数据后渲染成对齐表格 | | dsh-file-manager-cli | 本插件负责"看"（只读渲染），实际移动/删除/重命名交给 file-manager-cli | | dsh-workspace-journal | 把目录结构快照写入工作区日志，形成长期变化记录 |

版本说明

• 0.1.0（2026-09-22）：初始版本。
  • render_tree：树形渲染 + 深度控制 + 忽略名单 + 仅目录 + 大小标注 + 条目上限
  • tree_stats：目录/文件计数 + 最大深度 + 扩展名分布 Top N
  • 符号链接跳过（防环路）、无权限降级、只读保证

RoadMap

v0.2（计划）

• render_tree 支持 pattern 过滤，只渲染匹配名称的条目
• 新增 tree_compare：对比两次目录树快照，输出新增/删除的目录与文件
• 忽略规则支持 glob 模式（当前仅按目录名精确匹配）
• 大目录渲染并发化，缩短超大目录耗时

v0.3（展望）

• 目录树快照落盘 + 变化趋势报告（与 workspace-journal 联动）
• 输出格式可选（ascii / unicode / markdown 列表）
• 结合 .gitignore 自动推导忽略名单

FAQ

Q：为什么默认忽略 node_modules 和 .git？ 它们条目极多且通常不是结构查看的目标。需要时传 ignore=（空字符串）即可完整显示。

Q：depth 的计数从哪一层开始？ 根的直接子项为第 1 层。depth=1 只显示根的一级内容，depth=3 显示到第三层。

Q：软链接指向的目录为什么没显示？ 为避免环路死循环与越界遍历，扫描一律跳过符号链接/junction。这是刻意的安全取舍。

Q：渲染结果被截断（出现 ⚠）怎么办？ 说明条目达到 limit 上限。可提高 limit、降低 depth，或缩小 path 范围分段查看。

Q：tree_stats 的"最大深度"和传入的 depth 有何区别？ depth 是统计的深度上限；"最大深度"是实际统计到的最深层级，可能小于上限。

Q：能帮我删除或移动目录吗？ 不能，本插件严格只读。文件操作请使用 dsh-file-manager-cli。

源码与发布地址

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

许可证

MIT