Auto Filename Helper 是一个原生 macOS 辅助应用，接收快捷指令提供的文件名建议，检查名称与路径，再执行改名。
下载目录里的 document (3).pdf 很难让人想起具体内容。描述清楚的名字方便查找，但自动生成的建议也可能含糊、与其他文件重名，或意外改变扩展名。
Auto Filename Helper 把工作分成两部分：快捷指令负责产生建议，原生应用负责校验和落地改名。它本身不是 AI 模型，也不会单独阅读文件并生成标题。
构建应用并接好快捷指令
仓库目前提供源码和 Auto Filename.shortcut，还没有 GitHub Release 安装包。构建需要 macOS 13 或更新版本，以及 Xcode Command Line Tools。
下载项目并查看安装脚本后，在项目目录执行：
|
|
脚本会安装到 ~/Applications/AutoFilenameHelper.app。再将 Auto Filename.shortcut 导入“快捷指令”，按 README 用 shortcut_shell_replacement.sh 替换执行步骤。
这个连接不能省略。只打开应用不会自动得到命名建议；快捷指令需要把文件路径和分析结果传给它。
可以把它想成一次有把关的交接：在 Finder 选中 document (3).pdf，快捷指令先给出类似“项目会议纪要.pdf”的建议，再把原路径、建议名称和理由交给应用。应用检查文件能否改名；遇到不确定的结果，就让你先看文件再确认。示例名称只是说明流程，实际建议取决于快捷指令对文件的分析。
先拿一个副本试运行
第一次可以选一份不重要的支持格式文件副本，从 Finder 运行快捷指令，检查建议名称和原因，再到 Finder 确认结果。
应用接收路径、建议名称、置信度和理由等字段。默认保留原扩展名，避免覆盖已有文件；对于不安全名称、隐藏名称、符号链接、不支持的类型或根本没有变化的名称，会拒绝处理。
这些检查保证的是改名操作更稳妥，不能证明建议内容一定准确。文件名最好描述事实，而不是生成一个看起来漂亮、以后却认不出的标题。
哪些情况需要人工确认
设置中可以调整改名阈值、扩展名处理和重名冲突行为，也能选择语言与外观。名称有歧义、置信度低、涉及可执行文件，或关闭自动改名时，都可能要求确认。
Quick Look、在 Finder 中显示和复制路径等入口，方便先查看原文件。内容还没搞清楚时，保留原名、稍后处理也是合理选择。
第一次试用时，最好拿文件副本核对三件事：建议是否真的描述内容、.pdf 这样的扩展名是否保留、原目录里是否已有同名文件。即使看到较高的置信度，也可以先用 Quick Look 打开文件，避免把不同内容改成很相似的名字。
这里的置信度来自上游工作流，不是应用独立验证的结论。调整阈值只是改变便利性与人工检查的分配，尤其当文件名还会影响后续归档规则时，更应先用少量文件确认效果。
下载源码后，先确认自己在哪个目录
在 GitHub 项目页通过 Code → Download ZIP 下载后，先解压，再打开包含 build_and_install.sh 的文件夹。终端里的“当前目录”应当是这个项目文件夹，而不是下载目录或解压包的上一级。可以先输入 cd ，把项目文件夹拖入终端，再按回车；拖入时系统会处理路径中的空格。
如果构建提示缺少 Xcode Command Line Tools，先运行 xcode-select --install，完成系统安装后再回来构建。安装脚本会重新生成并替换 ~/Applications/AutoFilenameHelper.app；若以前改过这个位置的应用，先留一份副本。源码目录可以留着供以后更新，但快捷指令最终调用的应该是已安装应用里的程序。
导入快捷指令后，打开编辑界面找到调用辅助程序的 Shell 步骤，保留前面负责生成建议的动作。仓库给出的替换脚本只有交接用途，它不会替你补上缺失的分析步骤。如果自己把应用装到了其他地方，要把调用路径一并改好，否则快捷指令可能已经生成结果，却找不到负责显示和改名的应用。
给文件名定一套容易延续的规则
先想好自己以后会用哪些词搜索。会议资料可以保留项目名、会议主题和文档中确有的日期；发票则优先保留商家、用途或票据编号。不要为了让名字完整，就把文件里没有的年份、人员或版本号补进去。自动建议再流畅，也需要符合这套规则。
比如把 document (3).pdf 改成“季度预算讨论.pdf”以后，真正有用的是以后输入“预算”就能找到它。如果同目录已经有另一份同名材料，应查看两份内容，而不是仅靠数字后缀区分。扩展名也有实际作用：把 .pdf 改成 .docx 不会把文件转换成 Word 文档，所以通常保持默认的扩展名保留设置更省心。
我建议先用几份不同内容的副本走完完整流程：一份名字清楚的文件、一份名称含糊的文件，以及一份会与现有文件重名的文件。看过应用如何接受、询问或拒绝以后，再决定自己的阈值。这样调整的是实际工作习惯，而不只是一个看不出含义的数字。
快捷指令运行了，却没有完成改名
排查时沿着“选中文件 → 生成建议 → 传给应用 → 应用处理”往下看。如果只打开了设置窗口，先检查快捷指令有没有把输入送到程序的标准输入；如果弹出确认窗口但文件名没变，看看是否还在等待你的选择。如果应用说明名称无变化或类型不支持，就先处理这条提示，不必重复运行同一个文件。
同样的名字未必表示同一个文件。确认窗口中先核对路径，尤其是桌面、下载和云盘里各有一份副本时；必要时用“在 Finder 中显示”定位原件。完成后回到那个目录检查，而不是只看最近使用列表。若文件还被其他脚本或项目配置按原名引用，改名前也要一起考虑这些引用。
本地改名与上游分析分开看
辅助应用本身不发送网络请求。但命名建议来自快捷指令，是否调用 AI 服务、传递哪些内容，要看快捷指令中的动作与配置。
因此，“改名在本地完成”不能直接推导为“整个分析过程都在本地”。使用个人文档前，先查看快捷指令实际做了什么。
如果想先解释陌生文件的用途，可以看 What File Is This；改名后需要快速查找，可以配合 MacHunt。完整接线方式见 项目 README。