# jack

**Repository Path**: zzj0537/jack

## Basic Information

- **Project Name**: jack
- **Description**: Dirscope目录内容提取器：需要交付一份「某个文件夹里到底有什么」的清单时，靠资源管理器截图或手工列 Excel 都很费劲；用 dir /s 或 tree /f 又拿不到大小、时间、层级这些结构化字段，中文还容易乱码。DirScope 就是干这一件事的桌面小工具：选一个目录 → 挑字段和格式 → 导出成可直接交付的清单，支持多种导出格式。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DirScope · 目录内容提取器

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

[![star](https://gitee.com/zzj0537/jack/badge/star.svg?theme=dark)](https://gitee.com/zzj0537/jack/stargazers)
[![fork](https://gitee.com/zzj0537/jack/badge/fork.svg?theme=dark)](https://gitee.com/zzj0537/jack/members)
![version](https://img.shields.io/badge/version-1.2.4-2BD9C4)
![python](https://img.shields.io/badge/python-3.9%2B-3776AB)
![platform](https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-0078D4)
![license](https://img.shields.io/badge/license-Mulan%20PSL%20v2-green)
[![download](https://img.shields.io/badge/download-DirScope.exe%20v1.2.4-2BD9C4)](https://gitee.com/zzj0537/jack/releases/download/V1.2.4/DirScope.exe)

> **不想装 Python？** 直接下载 [`DirScope.exe` v1.2.4](https://gitee.com/zzj0537/jack/releases/download/V1.2.4/DirScope.exe)（13 MB 单文件，免安装，Windows 10 / 11 64 位）· 历史版本见 [发行版](https://gitee.com/zzj0537/jack/releases)

![主界面](docs/screenshot-main.png)

---

## 目录

- [一、这个工具解决什么问题](#一这个工具解决什么问题)
- [二、功能特性](#二功能特性)
- [三、界面预览](#三界面预览)
- [四、快速开始](#四快速开始)
- [五、使用说明](#五使用说明)
- [六、导出格式与层级表达](#六导出格式与层级表达)
- [七、快捷键](#七快捷键)
- [八、项目结构](#八项目结构)
- [九、开发与测试](#九开发与测试)
- [十、实现要点](#十实现要点)
- [十一、已知限制](#十一已知限制)
- [十二、更新日志](#十二更新日志)
- [十三、参与贡献](#十三参与贡献)
- [十四、许可协议](#十四许可协议)

---

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

需要交付一份「某个文件夹里到底有什么」的清单时，靠资源管理器截图或手工列 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` 无需任何包，拷走即可运行 |

---

## 三、界面预览

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

![主界面](docs/screenshot-main.png)

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

![导出对话框](docs/screenshot-export.png)

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

---

## 四、快速开始

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

```bat
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）](https://gitee.com/zzj0537/jack/releases) 下载最新 `DirScope.exe`，双击运行，目标机器无需安装 Python。

### 方式三：自己打包

```bat
cd jack
packaging\build_exe.bat
```

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

手动等价命令：

```bat
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`。

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

```bat
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`（通配符）。
- 状态栏实时显示：项目数、文件夹数、文件数、合计大小、选中项数量与大小、读取耗时。

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

---

## 六、导出格式与层级表达

| 格式 | 层级表达方式 | 适用场景 |
| --- | --- | --- |
| **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` 即为其命令行封装）。

---

## 九、开发与测试

```bat
:: 核心逻辑自测（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`。

---

## 十一、已知限制

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

---

## 十二、更新日志

完整记录见 [CHANGELOG.md](CHANGELOG.md)，近期版本：

- **v1.2.4**：标题栏品牌区新增 `© Jack` 版权标识，偏好设置与 exe 属性同步；文档截图重拍。
- **v1.2.3**：工具栏图标全部改为自绘矢量线性图标并修正居中；新增图标墨迹居中自动校验测试（86 项）。
- **v1.2.2**：修复路径栏高度塌陷、状态栏被裁、图标 DPI 缩放模糊等问题。
- **v1.1.0**：新增图形界面（目录树 / 表格 / 导出对话框 / 深色主题）。
- **v1.0.0**：命令行版本（list / export）与五种导出器。

---

## 十三、参与贡献

欢迎提 [Issue](https://gitee.com/zzj0537/jack/issues) 或 Pull Request。提交前请先读 [CONTRIBUTING.md](CONTRIBUTING.md)，核心要求：改动后 `python tests\test_core.py` 必须全绿，`core/` 不得反向依赖 `ui/`。

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

---

## 十四、许可协议

Copyright © 2026 **Jack**（[gitee.com/zzj0537](https://gitee.com/zzj0537)）。

本项目采用 **木兰宽松许可证，第 2 版（Mulan PSL v2）** 开源，全文见 [LICENSE](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.
```