# DirScanner

**Repository Path**: starstrust/dir-scanner

## Basic Information

- **Project Name**: DirScanner
- **Description**: Windows 目录索引生成器：双击扫描当前目录，生成可折叠 HTML，并可透视 Zip/7z/Rar（免解压） | Windows folder indexer: one-click scan to collapsible HTML with archive peeking (no extraction).
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📂 DirScanner（极速目录索引生成器）

一个轻量级、高性能的 Windows 目录扫描工具：**双击运行即可为“当前 exe 所在文件夹”生成可交互的目录索引（HTML）**。  
它支持**透视压缩包**（Zip / 7z / Rar / Tar / Gz / Bz2 等）内部的文件结构 —— **无需解压**即可预览，并支持无限层级的“套娃压缩包”。

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)

---

## 什么时候会用到它？

你会在下面这些场景里觉得它特别“省时间”：

- **硬盘/移动硬盘/NAS 的冷数据管理**：为了省空间把旧资料打包成 `.zip/.7z`，但偶尔要找里面某个文件时，不想每次都解压。
- **项目/素材库归档**：把历史版本、素材、旧工程压缩保存，但希望仍能“一眼看到结构”，决定要不要打开/解压。
- **备份盘快速盘点**：插上备份盘，双击生成一份可搜索/可折叠的索引文件，之后不用再反复点开文件夹。
- **交付给他人**：把目录结构导出成一个 HTML，别人用浏览器就能打开查看（无需额外软件）。

---

## ✨ 核心功能

- **⚡ 极速扫描**：多线程并行处理，充分利用多核 CPU。
- **📦 压缩包透视**：支持 Zip, 7z, Rar, Tar, Gz, Bz2…
  - **智能直读（Zip Stored）**：对于无压缩的 Zip（Stored 模式），直接映射物理偏移量读取，速度接近硬盘读取。
  - **流式扫描（大文件/奇异流）**：针对 `.gz/.bz2` 或“视频流中夹带 Zip 数据”等特殊情况，使用流式特征匹配算法，尽量做到**无需解压即可预览**，内存占用低。
  - **无限递归**：支持 Zip 套 7z 套 Zip 的无限层级结构（可配置策略与阈值，避免大文件导致卡顿）。
- **🚀 便携单文件**：基于 **.NET Framework 4.7.2**，可通过 Costura.Fody 合并依赖，最终生成单文件 `.exe`，无需安装。
- **📄 可交互报告**：生成折叠式 **HTML**，界面清爽，浏览器直接打开。

---

## 🔥 体验

> 日常双击就可以，只有需要改设置时才出现 GUI。

- **第一次运行**：弹出 GUI（设置输出文件名、是否透视压缩包、阈值、是否下次静默运行等）。
- **第二次及之后**：如果启用了静默模式，双击即后台扫描生成 HTML，自动退出。
- **恢复 GUI**：删除同目录下的配置文件（如 `config.json` 或 `[ExeName].cfg`），下次运行会重新弹出 GUI。

---

## 📦 输出是什么？为什么是 HTML？

默认输出为 `*.html`，用浏览器打开即可看到“可折叠目录树”。  
（部分 Markdown 阅读器也支持 `<details>` 折叠，但兼容性不如浏览器统一，所以这里优先用 HTML。）

---

## 🧩 工作方式（核心逻辑）

1. **扫描当前 exe 所在目录**（也就是你把 `DirScanner.exe` 放在哪，它就扫描哪里）。
2. **生成一份索引文件**（默认：`文件目录索引.html`）。
3. **再次双击时**：
   - 如果索引文件已存在：按配置执行“覆盖生成 / 更新生成”策略。
   - 可选择是否重新透视压缩包（因为压缩包通常是“稳定归档”，可不必每次都扫）。

---

## 📖 使用方法

### 方式 A：GUI 模式（第一次推荐）
1. 双击 `DirScanner.exe`
2. 设置：
   - 输出文件名（如 `文件目录索引.html`）
   - 是否透视压缩包
   - 内存阈值（小文件进内存更快，大文件走流式更省内存）
   - 是否“下次静默运行”
3. 点击“开始扫描”，生成 HTML

### 方式 B：静默模式（日常最爽）
1. 先运行一次，在 GUI 勾选“下次静默运行”（会生成配置文件）
2. 以后只要把 `DirScanner.exe` 放进任意文件夹，**双击即可自动生成索引**并退出
3. 删除配置文件即可恢复 GUI
4. 运行结束之后会有弹窗提示用于标记进程结束

---

## 🛠️ 技术栈

- **C# / WinForms** (.NET Framework 4.7.2)
- **System.IO.Compression**：原生 Zip（高速通道）
- **SharpCompress**：7z / Rar / Tar / Gz / Bz2 等复杂格式
- **Costura.Fody**：DLL 合并与压缩，生成单文件
- **Custom ZipStreamProcessor**：流式 Zip 解析器（用于受损或“特殊流”里的 Zip 结构识别）

---

## ⚙️ 配置项示例（示意）

> 实际配置文件名与字段以项目实现为准（例如 `config.json` 或 `[ExeName].cfg`）。

```json
{
  "OutputName": "文件目录索引.html",
  "ScanZip": true,
  "SilentMode": false,
  "MaxNestedZipSizeMB": 256
}
```

---

## 🧪 输出效果示例（节选）

HTML 中使用 `<details>` 折叠目录结构，默认收起，点击展开：

```html
<details>
  <summary>📁 Photos</summary>
  <div class="file">📄 2023.jpg</div>
  <div class="file">📄 logo.png</div>
</details>

<details>
  <summary>📦 Backup.zip（点击透视）</summary>
  <details>
    <summary>📂 src</summary>
    <div class="file">📄 main.cs</div>
  </details>
</details>
```

---

## 📥 下载

前往 Releases 页面下载最新版本的 `.exe` 文件。

---

## 🤝 贡献

欢迎提交 Issue 或 Pull Request！特别欢迎针对以下方向的优化：

- 压缩包透视性能与兼容性
- ZipStreamProcessor 的鲁棒性（受损 zip / 特殊流）
- 大文件与深层嵌套场景的内存与卡顿保护策略

---

## 📄 开源协议

本项目采用 [MIT License](LICENSE) 开源。