文件名提取-吉米工具箱

一、这个插件能做什么

“文件名提取”用于扫描一个或多个文件、文件夹，把文件名称、路径、大小、修改时间等信息整理成列表，并导出为 TXT、CSV 或 XLSX 文件。

它适合以下场景：

整理一个资料文件夹中的全部文件名。
生成项目交付文件清单。
把多个文件夹中的文件路径汇总到 Excel。
统计文件大小和最后修改时间。
复制文件列表后粘贴到 Excel、表格或聊天窗口。
只导出自己需要的字段，并按文件名或相对路径排序。

插件只读取文件的名称、路径和基础属性，不读取或修改文件内容，也不会移动、重命名或删除原文件。

二、开始前请先准备

操作前建议先确认：

知道要扫描的是单个文件、多个文件，还是整个文件夹。
如果要扫描文件夹，决定是否需要包含所有子文件夹。
准备一个已有的文件夹作为导出目录。
想好导出文件名，例如“客户A文件清单”。
确认是否需要在对外发送的清单中包含“绝对路径”。绝对路径可能暴露电脑用户名、盘符和内部目录结构。
如果来源位于移动硬盘、共享盘或网盘，请先确认设备在线、路径可访问。

建议第一次使用时先选择少量文件，熟悉字段和格式后再扫描大量目录。

三、如何打开插件

打开吉米工具箱。
进入工具箱的“本地应用”列表。
找到名称为“文件名提取”的插件。
单击插件卡片或打开按钮。

插件窗口顶部有两个标签页：

“操作”：选择来源、加载文件、导出、复制和查看任务状态。
“配置”：选择导出字段、导出格式和排序方式。

窗口右上角还有：

“返回”：返回本地应用列表。
“置顶”：让窗口保持在其他窗口前面；再次单击可取消。

四、认识完整操作流程

推荐按以下顺序使用：

选择来源文件或来源目录。
确认是否开启“递归扫描”。
等待文件列表加载完成。
检查文件数量，移除不需要的项目。
选择导出目录并填写输出文件名。
到“配置”页选择导出字段、格式和排序。
回到“操作”页，把列表作为导出前预览进行检查。
单击“开始导出”。
等待状态显示“导出完成”。
到所选导出目录中打开结果文件。

本插件没有单独的“生成预览”按钮。加载完成后的文件表格就是待导出内容的预览。插件也没有“撤销”按钮，因为导出不会修改原文件；若不需要导出文件，可在 Windows 文件资源管理器中自行删除该结果文件。

五、添加文件和文件夹

“来源路径”支持直接选择文件、选择目录以及拖拽。

方法一：选择一个或多个文件

在“操作”页找到“来源路径”。
单击右侧“文件”按钮。
在 Windows 文件选择窗口中找到目标文件。
如需多选，可按住 Ctrl 再逐个单击文件，或用鼠标框选。
单击“打开”。
插件会立即开始扫描所选文件。
等待页面状态从“正在扫描”变为“扫描完成”。

通过“文件”按钮选择的文件不限扩展名，普通文档、图片、压缩包等都可以加入列表。

方法二：选择一个目录

单击“来源路径”右侧的“目录”按钮。
在 Windows 文件夹选择窗口中找到目标文件夹。
确认选择。
插件会立即扫描该文件夹。

“目录”按钮一次选择一个文件夹。如果要汇总多个文件夹，可以使用下方文件列表区域拖入多个项目，或者先扫描一个来源，再把其他来源拖入文件列表区域追加到来源路径后重新扫描。

方法三：拖到上方“来源路径”区域

打开 Windows 文件资源管理器。
选中一个或多个文件、文件夹。
按住鼠标左键，把它们拖到“来源路径”输入区域。
看到拖入高亮后松开鼠标。
插件会把本次拖入的路径作为新的来源并重新加载列表。

拖到上方来源区域会替换之前的来源路径。如果想保留已有来源并增加新内容，请使用下方“文件列表”区域。

方法四：拖到下方“文件列表”区域

先保留当前已经加载的来源。
从 Windows 文件资源管理器中选择要增加的文件或文件夹。
拖到下方“文件列表”区域。
松开鼠标后，插件会把新路径与已有来源路径合并，然后重新扫描全部来源。

同一路径被重复选择时，插件会在 Windows 大小写不敏感的规则下自动去重，不会重复导出同一个文件。

“来源路径”输入框为什么不能直接输入

该输入框为只读显示区。多个来源路径会用分号分隔。请使用“文件”“目录”按钮或拖拽来修改来源，避免手工输入路径错误。

六、理解“递归扫描”

“递归扫描”只影响所选文件夹，不影响直接选择的单个文件。

关闭：只读取来源文件夹最外层的文件，不进入下级文件夹。
开启：读取来源文件夹及其所有下级文件夹中的文件。

切换开关后，插件会按当前来源重新扫描。

示例：

D:\客户资料
├─ 封面.pdf
└─ 合同
   └─ 合同A.docx

关闭递归：只得到 封面.pdf。
开启递归：得到 封面.pdf 和 合同/合同A.docx。

扫描大量子文件夹可能需要较长时间。扫描时可以使用“暂停”“继续”或“取消”。

七、查看和整理文件列表

扫描完成后，页面会显示文件列表。列表中的业务字段会跟随“配置”页选择的导出字段变化，另外始终显示扫描状态、导出状态、错误原因和移除按钮。

列表顶部的标签含义如下：

“总文件数”：当前列表中的全部文件。
“已扫描”：已成功读取基础属性的文件。
“待导出”：尚未完成导出的文件。
“已导出”：最近一次导出中已成功写入结果的文件。
“失败”：扫描或导出失败的项目，以及无法访问的来源路径错误。

单击状态标签可以筛选列表，再单击“总文件数”恢复全部显示。

移除单个文件

每行最右侧有红色删除图标：

找到不想导出的文件。
单击该行最右侧的删除图标。
文件会从当前插件列表中移除。

这只移除列表记录，不会删除电脑上的原文件。任务运行期间不能移除。

清空列表

单击“清空”会清除当前扫描结果和状态，不会删除原文件。来源路径配置仍可能保留；再次单击“加载”会按原来源重新扫描。若要更换来源，请重新使用“文件”“目录”按钮或把新来源拖到上方来源区域。

部分路径处理失败

如果某些路径不存在、无权访问或读取失败，页面会显示“部分路径处理失败”提示，并展示其中一条错误。其他能够正常读取的文件仍会保留在列表中。

导出前请检查“失败”数量。若失败项属于必需资料，应先解决权限、设备连接或路径问题，然后重新加载。

八、详细理解每一个导出字段

打开“配置”标签页，在“导出字段”中可选择一个或多个字段。字段在选择列表中的顺序，就是导出文件中的列顺序。

1. 文件名

完整文件名，包含最后的扩展名。

示例：archive.tar.gz 的文件名是 archive.tar.gz。

适合：制作最简单的文件清单，或让客户看到实际文件名。

2. 基本名称

去掉最后一个扩展名后的名称。

示例：archive.tar.gz 的基本名称是 archive.tar，不是 archive。

没有扩展名的文件，其基本名称与文件名相同。

适合：后续在 Excel 中匹配名称、编号或业务标识。

3. 扩展名

文件最后一个扩展名，包含前面的点号。

示例：

报告.pdf 的扩展名是 .pdf。
archive.tar.gz 的扩展名是 .gz。
README 没有扩展名，导出值为空。

适合：按文件类型筛选、统计。

4. 相对路径

文件相对于本次来源公共目录的位置，使用 / 分隔目录层级。

示例：来源为 D:\客户资料，文件为 D:\客户资料\合同\合同A.docx，相对路径会是：

合同/合同A.docx

如果选择了不同磁盘、没有共同目录的多个来源，相对路径可能显示为带盘符的完整路径形式。对外发送清单前应抽查该字段。

适合：保留文件夹层级，同时避免重复显示同一段根目录。

5. 绝对路径

文件在当前电脑上的完整路径，例如：

D:\客户资料\合同\合同A.docx

绝对路径最适合内部查找文件，但可能暴露盘符、Windows 用户名、公司目录结构或共享服务器名称。对外发给客户时，除非确有需要，否则建议不要选择。

6. 文件大小

文件大小，单位为字节（Byte）。例如 1024 表示 1024 字节，约等于 1 KB。

XLSX 中会以数值保存，便于求和或排序；TXT、CSV 中显示为数字文本。

7. 修改时间

文件系统记录的最后修改时间。

列表中会按中文本地时间显示；导出文件中保存标准时间文本，便于不同软件读取。修改时间由文件系统提供，不一定等同于文件创建时间，也不一定代表最后一次人工编辑时间。

九、选择导出格式

“导出格式”支持 TXT、CSV 和 XLSX。

TXT

适合简单文本清单。

只选择一个字段时：每行一个值，不写表头。
选择两个或更多字段时：第一行是中文表头，各字段使用制表符分隔。
文件以 UTF-8 文本写出。

例如只选择“文件名”：

封面.pdf
合同A.docx
清单.xlsx

选择“文件名”和“相对路径”：

文件名    相对路径
封面.pdf    封面.pdf
合同A.docx    合同/合同A.docx

CSV

适合用 Excel、WPS 表格或数据软件打开。

始终包含中文表头。
使用英文逗号分隔字段。
会正确处理文件名中的逗号、双引号和换行。
使用带 BOM 的 UTF-8，方便 Windows 表格软件识别中文。
对以 =、+、-、@ 开头的文本会加保护，降低表格公式被意外执行的风险。

XLSX

适合直接交付给客户或继续在 Excel/WPS 中整理。

工作表名称为“文件列表”。
第一行是加粗表头。
首行冻结，向下滚动时表头仍可见。
自动添加筛选功能。
路径列会设置较宽的列宽。
文件大小以数字形式保存。
文件名和路径按文本写入，不会当作 Excel 公式执行。

对于电脑操作经验较少的客户，通常优先推荐 XLSX；只需要一列纯文件名时，可选择 TXT。

十、设置排序

排序字段

“文件名”：按完整文件名排序，不考虑所在目录作为首要条件。
“相对路径”：先按目录层级和相对路径排序，适合保留文件夹结构的清单。

排序方向

“升序”：从小到大、从前到后。
“降序”：从大到小、从后到前。

排序使用自然排序，因此 file2 通常排在 file10 前面，而不是简单地按单个字符比较。文件名或相对路径相同时，会使用绝对路径保持稳定顺序。

十一、设置导出位置和文件名

选择导出目录

回到“操作”标签页。
找到“导出目录”。
单击右侧“选择”。
选择一个已经存在且可以写入的文件夹。

也可以把一个文件夹拖到“导出目录”输入区域。请拖入文件夹，不要拖入普通文件。

填写输出文件名

在“输出文件名”中填写名称，默认是“文件名列表”。建议只填写名称主体，不手工填写扩展名，例如：

客户A文件清单

选择 XLSX 后，最终文件名会是：

客户A文件清单.xlsx

如果输入的名称已经带有与所选格式相同的扩展名，插件不会重复添加。若带的是另一种扩展名，则会继续添加当前格式扩展名。例如名称填 清单.csv、格式选 TXT，结果会是 清单.csv.txt。因此最简单的做法是只填写名称主体。

输出文件名不能：

为空或超过 120 个字符。
包含 < > : " / \ | ? * 等 Windows 非法字符。
以空格或点结尾。
使用 CON、PRN、AUX、NUL、COM1、LPT1 等 Windows 保留名称。

已有同名文件时

插件不会覆盖已有结果。若导出目录中已经存在 文件名列表.xlsx，新的结果会自动命名为：

文件名列表 (1).xlsx

如果该名称也存在，会继续使用 (2)、(3)。

十二、开始导出并判断结果

确认文件列表不为空。
确认导出目录、输出文件名正确。
确认至少选择了一个导出字段。
回到“操作”页，单击“开始导出”。
等待状态从“正在导出”变为“导出完成”。
查看“已导出”和“失败”数量。
打开之前选择的导出目录。
找到“输出文件名 + 所选格式扩展名”的文件；若有同名文件，留意 (1)、(2) 后缀。
打开结果文件，检查表头、行数和几条样例。

导出采用临时文件完成。只有完整结果准备好后，插件才会提交最终文件；失败或取消时会清理未完成的临时文件，不会留下一个看似正常但内容不完整的最终结果。

十三、复制结果到剪贴板

如果不想生成文件，可以单击“复制”。

复制功能会：

使用当前选择的导出字段。
使用当前排序字段和排序方向。
始终包含中文表头。
使用制表符分隔列，适合直接粘贴到 Excel 或 WPS 表格。

操作步骤：

加载并检查文件列表。
在“配置”页选择字段和排序。
回到“操作”页，单击“复制”。
打开 Excel、WPS、记事本或目标聊天窗口。
按 Ctrl + V 粘贴。

注意：复制内容是普通制表符文本。若来源文件名由不可信人员提供，并且以 =、+、- 或 @ 开头，粘贴到部分表格软件时可能被识别为公式。此类清单建议使用 CSV 或 XLSX 导出，它们带有相应的文本保护。

十四、暂停、继续和取消

扫描或导出运行时可以使用任务控制按钮。

暂停

单击“暂停”后，插件会在安全检查点停止继续扫描或生成后续内容。当前正在进行的一个小步骤可能先完成，因此状态不一定立刻停止变化。

继续

暂停后按钮变为“继续”。单击后任务从暂停位置继续。

取消扫描

取消扫描会停止继续读取来源。当前扫描不会生成导出文件。取消后可重新选择来源并加载。

取消导出

导出是一个完整结果文件。取消时，尚未提交的临时文件会清理，通常不会产生半成品结果文件。已经在取消前完整提交成功的结果不再属于运行中的任务。

离开插件或退出工具箱时，如果任务仍在运行，工具箱会提示存在未完成任务；确认离开会中止未完成进度。

本插件没有撤销功能，因为扫描和导出都不修改原文件。要删除已成功导出的清单，请到导出目录中手工删除对应结果文件。

十五、完整操作示例

目标：把 D:\客户资料 及其子文件夹中的所有文件导出成 Excel 清单，包含文件名、扩展名、相对路径、大小和修改时间。

打开“文件名提取”。
单击“来源路径”右侧“目录”。
选择 D:\客户资料。
开启“递归扫描”。
等待状态显示“扫描完成”。
检查总文件数是否合理。
打开“配置”标签页。
在“导出字段”中依次选择：文件名、扩展名、相对路径、文件大小、修改时间。
“导出格式”选择“XLSX”。
“排序字段”选择“相对路径”。
“排序方向”选择“升序”。
回到“操作”标签页。
在“导出目录”中选择 D:\导出清单。
“输出文件名”填写 客户资料文件清单。
单击“开始导出”。
等待状态显示“导出完成”。
打开 D:\导出清单\客户资料文件清单.xlsx。
检查首行表头、文件总行数，以及几个子文件夹的相对路径。

十六、常见问题与解决办法

1. 提示“请选择来源目录或文件”

请使用“文件”“目录”按钮或拖拽添加来源。来源输入框不能手工编辑。

2. 选择目录后没有子文件夹中的文件

检查“递归扫描”是否开启。开启后插件会重新扫描当前来源。

3. 同一个文件为什么没有出现两次

插件会对同一路径自动去重。在 Windows 中，路径字母大小写不同也会视为同一个文件。

4. 显示“部分路径处理失败”

可能原因包括：文件被删除、移动硬盘断开、共享盘离线、目录无权限或文件属性读取失败。查看提示中的路径，恢复访问后重新加载。

5. “开始导出”按钮不能单击

请确认：

文件列表不为空。
当前没有扫描或导出任务运行。
已选择导出目录。
至少选择了一个导出字段。

6. 提示“导出目录不存在”或“导出目录无效”

使用“选择”按钮重新选择一个真实文件夹。不要把普通文件拖到导出目录区域，也不要使用已经断开的移动盘或网络路径。

7. 提示“输出文件名无效”

删除文件名中的非法字符，确保名称不以点或空格结尾，并建议只填写名称主体，不手工添加扩展名。

8. 找不到导出文件

返回查看当时选择的“导出目录”，并搜索输出文件名。若目录中已有同名文件，请查找带 (1)、(2) 的新文件。

9. TXT 第一行为什么没有表头

当 TXT 只选择一个字段时，插件有意省略表头，让每一行直接成为一个值。选择两个或更多字段时才会写入表头。

10. “文件大小”为什么是一串数字

导出的单位是字节，便于精确统计。例如 1024 字节约为 1 KB，1048576 字节约为 1 MB。

11. 相对路径为什么有时像完整路径

当多个来源位于不同磁盘或没有共同目录时，无法计算统一的相对根目录，因此该字段可能显示带盘符的路径。若要得到简洁相对路径，建议每次处理同一根目录下的文件。

12. 清空后再次加载，文件又出现了

“清空”只清除扫描结果，不一定清除已保存的来源路径。若要换一批来源，请重新选择或拖入新的来源。

13. 暂停后状态仍变化了一次

暂停在安全检查点生效，当前正在执行的小步骤可能先完成。这不是重复扫描或重复导出。

十七、风险和数据安全说明

插件只读取文件名、路径、大小和修改时间等文件系统信息，不读取文件正文。
扫描、清空和移除列表都不会删除或修改原文件。
导出只在指定目录新建清单文件，不覆盖已有同名结果。
绝对路径、相对路径和文件名本身可能包含客户名称、人员姓名、项目编号、服务器名称等敏感信息。
对外发送前应打开结果文件检查字段，尤其确认是否真的需要“绝对路径”。
CSV 和 XLSX 对可能被表格软件当作公式的文件名做了文本保护；直接复制到剪贴板的 TSV 内容不具备同等级保护。
导出失败或取消时会清理临时文件，但磁盘故障、权限变化等外部问题仍可能导致操作失败。
插件不会上传清单；是否通过聊天、邮箱或网盘发送结果由用户自行决定。

十八、完成前检查清单

导出前请确认：

来源文件和文件夹选择正确。
“递归扫描”状态符合需要。
总文件数与预期大致一致。
“失败”数量为 0，或已核对所有失败来源。
已移除不应出现在清单中的文件。
导出字段完整且顺序正确。
对外发送时已谨慎决定是否包含绝对路径。
导出格式适合接收方；电脑经验较少的客户优先考虑 XLSX。
排序字段和方向正确。
导出目录真实存在且可写入。
输出文件名不含非法字符。

导出完成后请确认：

页面状态显示“导出完成”。
“失败”数量为 0。
已在正确导出目录找到结果文件。
已留意文件名是否带 (1)、(2) 后缀。
打开结果后，表头、字段顺序和文件行数正确。
抽查了几个根目录文件和子目录文件。
对外发送前再次检查了路径和文件名中的敏感信息。