DirScope · 目录内容提取器

浏览本地任意目录 → 一键导出结构化目录清单（TXT / Markdown / CSV / JSON / HTML）纯 Python 标准库实现，零第三方运行时依赖，可打包为单文件 DirScope.exe

不想装 Python？ 直接下载 DirScope.exe v1.2.4（13 MB 单文件，免安装，Windows 10 / 11 64 位）· 历史版本见发行版

主界面

一、这个工具解决什么问题

需要交付一份「某个文件夹里到底有什么」的清单时，靠资源管理器截图或手工列 Excel 都很费劲；用 dir /s 或 tree /f 又拿不到大小、时间、层级这些结构化字段，中文还容易乱码。

DirScope 就是干这一件事的桌面小工具：选一个目录 → 挑字段和格式 → 导出成可直接交付的清单，同时提供一个顺手好用的目录浏览器（前进/后退、面包屑、排序、筛选、右键菜单）。常见用途：

招投标 / 项目归档：交付「资料清单」TXT 或 Excel
软件著作权登记：整理源码目录结构，导出 Markdown 附在文档里
交付验收：给客户一份可折叠浏览的 HTML 目录报告
交接盘点：导出 CSV 做进一步统计

二、功能特性

需求	实现
目录浏览	左侧「快捷访问 + 此电脑（驱动器 / 懒加载目录树）」、可点击面包屑、可直接编辑的路径输入框；前进 / 后退 / 上级 / 刷新
内容展示	表格展示名称 · 类型 · 大小 · 修改时间，文件夹 / 文件用不同图标区分；点击表头排序（名称自然排序、大小、时间、类型，升降序），顶部按名称实时筛选（支持 `*` `?` 通配符与空格分词）
交互操作	双击进入文件夹 / 双击文件用系统默认程序打开（可选单击进入）；右键菜单：打开、在资源管理器中显示、设为根目录、复制完整路径、复制名称、刷新；`Ctrl+C` 复制选中路径
导出	可选是否递归、层级深度、导出字段（名称 / 类型 / 大小 / 修改时间 / 扩展名 / 相对路径 / 完整路径）；格式 TXT、Markdown 为主，另含 CSV、JSON、HTML；导出保留目录层级；自选保存路径，完成后弹窗提示并可直接打开文件或所在目录
界面风格	深色主题（`#0A0E14` 底 + 青色强调 `#2BD9C4`）、自绘圆角按钮 / 开关 / 标签、自绘矢量线性图标（居中、随状态换色、DPI 自适应）、自绘右键菜单、轻提示 Toast、状态栏实时统计
大目录不卡死	目录读取在后台线程，主线程按 600 行 / 批渲染；递归扫描独立线程 + 进度 + 可取消；30 000 项目录实测可正常加载
零依赖	运行时只用 Python 标准库 + tkinter，`pip install` 无需任何包，拷走即可运行

三、界面预览

主界面：左侧目录树 + 面包屑路径栏 + 文件表格 + 状态栏统计

主界面

导出对话框：格式卡片、字段胶囊、递归与深度、保存路径

导出对话框

HTML 导出报告样例：单文件深色报告，可折叠目录、内置名称筛选，直接用浏览器打开 docs/sample-report.html 即可查看。

四、快速开始

方式一：直接运行源码（推荐开发者）

git clone https://gitee.com/zzj0537/jack.git
cd jack
python run.py                :: 打开上次目录 / 用户主目录
python run.py "D:\项目资料"   :: 指定初始目录

要求：**Python 3.9+**，且安装包自带 tkinter（python.org 官方安装包默认包含；精简版 / 部分 conda 环境需另装）。

方式二：下载 exe 直接使用（推荐普通用户）

前往发行版（Releases）下载最新 DirScope.exe，双击运行，目标机器无需安装 Python。

方式三：自己打包

cd jack
packaging\build_exe.bat

脚本会自动：检查 Python 版本 → 生成应用图标 → 检查 / 安装 PyInstaller → 打包。产物：dist\DirScope.exe（单文件，约 12–16 MB，双击即用）。

手动等价命令：

python -m pip install -r requirements-dev.txt
python tools\make_icon.py
python -m PyInstaller packaging\DirScope.spec --noconfirm --clean

若需要「绿色目录版」（启动更快、可多文件共存），在 spec 里改用 COLLECT（onedir）即可；当前默认 onefile。

命令行用法（无界面批处理）

python -m app.cli list   "D:\项目资料" --limit 30
python -m app.cli export "D:\项目资料" -f md  -o 清单.md  --depth 2
python -m app.cli export "D:\项目资料" -f csv -o 清单.csv --fields name,type,size,modified

五、使用说明

顶部按钮：后退、前进、上级、刷新。
路径区默认为面包屑，点击任意层级跳转；点右侧铅笔图标（或 Ctrl+L）切换为文本输入，回车确认。
左侧「快捷访问」读取系统真实路径（兼容 OneDrive 重定向的桌面 / 文档）；驱动器节点展开时按需加载子目录。

排序与筛选

点击表头 名称 / 类型 / 大小 / 修改时间 排序，再次点击切换升降序（表头显示 ▲ / ▼）。
右上搜索框实时筛选，支持 报告、2026 报告（空格分词 = 同时满足）、*.md（通配符）。
状态栏实时显示：项目数、文件夹数、文件数、合计大小、选中项数量与大小、读取耗时。

导出

点右上「导出目录」。
导出范围：是否包含子目录（递归）、层级深度（0 = 不限）、是否包含隐藏文件。
导出格式：TXT / Markdown / CSV / JSON / HTML 卡片式选择。
导出字段：多选胶囊标签（名称始终包含）。
保存位置：默认 桌面\目录名_目录清单_时间戳.<ext>，可浏览修改。
点击「开始导出」→ 进度窗口（扫描进度 / 可取消）→ 完成弹窗（打开文件 / 打开所在文件夹）。

六、导出格式与层级表达

格式	层级表达方式	适用场景
TXT	ASCII 树形连接线（`├──` `└──`），元信息按列对齐（中文按双宽计算）	打印、粘贴到工单 / 文档
Markdown	嵌套无序列表，目录加粗、元信息用 `<sub>`；名称用行内代码避免下划线转义	知识库、Git 仓库文档
CSV	`层级` 列 + 名称缩进；可选字节数与可读大小双列；UTF-8 BOM 便于 Excel 直接打开	Excel / 数据加工
JSON	嵌套 `children` 树 + 统计与选项元数据	程序二次处理
HTML	单文件深色报告，可折叠目录、内置名称筛选、统计徽章	交付给他人浏览

字段选择对每种格式均生效（TXT / MD 中附加为元信息行，CSV / JSON 中为列 / 键）。

七、快捷键

快捷键	功能
`Alt+←` / `Alt+→`	后退 / 前进
`Backspace`	返回上级目录
`F5`	刷新
`Ctrl+F`	聚焦筛选框
`Ctrl+L`	编辑路径
`Ctrl+O`	选择根目录
`Ctrl+E`	导出当前目录
`Ctrl+C`	复制选中项完整路径
`Enter` / 双击	打开选中项
`Esc`	清除筛选

八、项目结构

jack/
├── run.py                      # 源码运行入口
├── requirements.txt            # 运行时无第三方依赖
├── requirements-dev.txt        # 打包依赖（pyinstaller）
├── app/
│   ├── main.py                 # 应用入口（DPI 感知、异常兜底）
│   ├── cli.py                  # 命令行：list / export（可无界面批处理）
│   ├── core/                   # 业务层（不依赖任何 UI）
│   │   ├── models.py           # Entry / Node / ScanResult
│   │   ├── formatting.py       # 大小、时间、类型标签、自然排序、通配符匹配
│   │   ├── listing.py          # 目录枚举、排序、筛选、统计
│   │   ├── scanner.py          # 递归扫描（迭代栈、取消、深度限制、聚合大小）
│   │   ├── exporters.py        # TXT/MD/CSV/JSON/HTML 渲染 + 原子写盘
│   │   ├── settings.py         # %APPDATA%\DirScope\settings.json
│   │   └── shell.py            # 已知文件夹、驱动器、默认程序打开、定位
│   ├── ui/
│   │   ├── theme.py            # 配色、字体、ttk 样式、深色标题栏、DPI
│   │   ├── raster.py           # 纯标准库光栅化 + PNG/ICO 编码
│   │   ├── icons.py            # 抗锯齿图标：文件夹/文件/驱动器 + 工具栏矢量线性图标
│   │   ├── widgets.py          # 圆角按钮、搜索框、开关、Toast、自绘右键菜单、模态基类
│   │   ├── main_window.py      # 主窗口：导航、表格、异步加载、导出流程
│   │   └── export_dialog.py    # 导出设置 / 进度 / 完成对话框
│   └── resources/app.ico       # 应用图标（由 tools/make_icon.py 生成）
├── packaging/
│   ├── DirScope.spec           # PyInstaller 配置（onefile + 图标 + 版本信息）
│   ├── version_info.txt        # exe 属性中的版本资源
│   └── build_exe.bat           # 一键打包
├── tests/test_core.py          # 86 项核心自测（无需第三方框架）
├── tools/make_icon.py          # 生成多尺寸 ico
├── docs/                       # 截图、示例报告
├── .gitee/                     # Issue / Pull Request 模板
├── CHANGELOG.md                # 版本更新日志
├── CONTRIBUTING.md             # 贡献指南
├── LICENSE                     # 木兰宽松许可证 v2
└── README.md / README.en.md    # 中文 / 英文说明

设计要点：core/ 与 ui/ 严格分离 —— 所有目录读取、扫描、渲染逻辑均可在无界面环境下测试与复用（app/cli.py 即为其命令行封装）。

九、开发与测试

:: 核心逻辑自测（86 项断言，纯标准库 unittest 风格，无需 pip install）
python tests\test_core.py

:: 命令行快速验证
python -m app.cli list "D:\项目资料" --limit 30
python -m app.cli export "D:\项目资料" -f md -o 清单.md --depth 2

测试覆盖：大小 / 时间格式化、类型枚举、隐藏文件判定、自然排序（第2章 在 第10章 前）、通配符与分词筛选、扫描深度与取消、五种导出器及字段裁剪、设置持久化、矢量图标墨迹居中校验、1500 项性能基线。

性能参考（本机 SSD，1080p / 150% DPI）：

场景	结果
4 935 项目录（`System32`）	枚举 19 ms，界面渲染约 1.5 s（分批，期间可交互）
30 245 项目录（`WinSxS`）	枚举 3.2 s（后台线程，界面不冻结）
递归扫描 34 138 项 / 15 GB	1.8 s，可随时取消

十、实现要点

不卡界面：目录读取跑在 threading.Thread，通过 queue + after(40ms) 回传；表格按 600 行 / 批插入，状态栏显示渲染进度；过期的加载结果按 token 丢弃。
扫描安全：显式栈迭代（无递归深度限制）；默认不跟随符号链接 / 联接点（避免死循环）；单目录权限错误标记为「无访问权限」而不断链；节点数上限 40 万，超出显式标注「已截断」。
写盘安全：先写同目录临时文件，再 os.replace 原子替换；CSV 使用 utf-8-sig（Excel 中文不乱码），其余 UTF-8。
零依赖图标：raster.py 自带超采样光栅化（含解析式抗锯齿圆弧）+ PNG/ICO 编码器，图标全部代码生成，避免引入 Pillow；工具栏用矢量线性图标而非字体符号，既能按状态换色，也不会出现字体子像素彩边，并用「墨迹包围盒」自动校验居中。
细节：DPI 感知（150% 缩放不错位）、深色标题栏（DWM 属性）、窗口尺寸按屏幕工作区收敛（不会被任务栏遮挡）、偏好存入 %APPDATA%\DirScope\settings.json。

十一、已知限制

拖拽文件夹到窗口：tkinter 原生不支持跨进程拖放，需要 tkdnd 等原生扩展，故未实现（可用「打开文件夹」或路径输入替代）。
不递归展开符号链接 / 联接点（结果中会标注「符号链接（未展开）」）。
仅读操作：不提供重命名 / 删除 / 移动等文件管理功能，避免误操作风险。
单文件 exe 首次启动需解压运行时，约 0.5–1.5 s；若追求极速启动可改用 onedir 打包。
打包后的 exe 未做数字签名，个别安全软件可能对 PyInstaller 产物给出启发式提示。
仅支持 Windows（依赖 ctypes 调用 Win32 API 读取驱动器、深色标题栏、文件定位）。

十二、更新日志

完整记录见 CHANGELOG.md，近期版本：

v1.2.3：工具栏图标全部改为自绘矢量线性图标并修正居中；新增图标墨迹居中自动校验测试（86 项）。
v1.2.2：修复路径栏高度塌陷、状态栏被裁、图标 DPI 缩放模糊等问题。
v1.1.0：新增图形界面（目录树 / 表格 / 导出对话框 / 深色主题）。
v1.0.0：命令行版本（list / export）与五种导出器。

十三、参与贡献

欢迎提 Issue 或 Pull Request。提交前请先读 CONTRIBUTING.md，核心要求：改动后 python tests\test_core.py 必须全绿，core/ 不得反向依赖 ui/。

如果这个工具帮到了你，点个 Star 是最好的鼓励。

十四、许可协议

本项目采用 木兰宽松许可证，第 2 版（Mulan PSL v2） 开源，全文见 LICENSE。

Copyright (c) 2026 Jack
DirScope is licensed under Mulan PSL v2.
You can use this software according to the terms and conditions of the Mulan PSL v2.
You may obtain a copy of Mulan PSL v2 at:
    http://license.coscl.org.cn/MulanPSL2
THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
See the Mulan PSL v2 for more details.