hyperfield/ai-file-sorter
GitHub: hyperfield/ai-file-sorter
一款隐私优先的跨平台桌面应用，利用本地或远程大语言模型对图片、文档和音视频文件进行智能分类与重命名，帮助用户高效整理杂乱文件夹。
Stars: 847 | Forks: 96
# AI File Sorter
[](#)
[](#)
[](https://sourceforge.net/projects/ai-file-sorter/files/latest/download)
[](https://app.codacy.com/gh/hyperfield/ai-file-sorter/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://filesorter.app/donate/)
` 下，并将运行时 DLL/SO 副本放置在 `app/lib/ggml/w` 下。该脚本拒绝同时启用 CUDA 和 Vulkan，因此请针对每个后端分别运行它。同时提供这两个目录可以让启动器在可用时优先选择 Vulkan，然后选择 CUDA，或者保留在 CPU 上——不会保留仅限 CUDA 的依赖项。
5. **编译应用程序**
cd app
make -j4
二进制文件生成在 `app/bin/aifilesorter`。
Makefile 需要 `pkg-config` + 由包管理的 `libmediainfo`；它有意拒绝 vendored 的 MediaInfo 副本。
6. **全局安装 (可选)**
sudo make install
7. **构建 Debian 软件包 (可选)**
./app/scripts/package_deb.sh
打包脚本始终捆绑 CPU 运行时，并自动包含 `app/lib/precompiled` 中已经暂存的任何 GPU
变体（例如在
`app/scripts/build_llama_linux.sh cuda=off vulkan=on` 之后的 `vulkan`）。如果需要
较小的仅限 CPU 的软件包，请使用
`./app/scripts/package_deb.sh --cpu-only`，或者如果希望在缺少特定暂存变体时
脚本执行失败，请使用 `--include-vulkan` / `--include-cuda`。
### macOS
1. **安装 Xcode 命令行工具**（`xcode-select --install`）。
2. **安装 Homebrew**（如果需要）。
3. **安装依赖项**
brew install qt curl jsoncpp sqlite openssl fmt spdlog mediainfo cmake git pkgconfig libffi
如果 Qt 尚未存在于您的环境中，请将其添加：
export PATH="$(brew --prefix)/opt/qt/bin:$PATH"
export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$(brew --prefix)/share/pkgconfig:$PKG_CONFIG_PATH"
4. **克隆存储库和子模块**（与 Linux 命令相同）。
5. **构建 vendored libzip**（生成 `zipconf.h` 和 `libzip.a`）
cmake -S external/libzip -B external/libzip/build \
-DBUILD_SHARED_LIBS=OFF \
-DBUILD_DOC=OFF \
-DENABLE_BZIP2=OFF \
-DENABLE_LZMA=OFF \
-DENABLE_ZSTD=OFF \
-DENABLE_OPENSSL=OFF \
-DENABLE_GNUTLS=OFF \
-DENABLE_MBEDTLS=OFF \
-DENABLE_COMMONCRYPTO=OFF \
-DENABLE_WINDOWS_CRYPTO=OFF
cmake --build external/libzip/build
6. **构建 llama 运行时（在 Apple Silicon 上启用 Metal）**
./app/scripts/build_llama_macos.sh
macOS 应用程序和 `.app` 包使用暂存在 `app/lib/precompiled*` 下的运行时；它们不需要 Homebrew 的 `ggml` 或 `llama.cpp` 库。
如果您在通用库位置安装了较旧的 `ggml` / `llama.cpp` 副本，请优先取消链接或删除它们，而不是隐式依赖它们。
7. **编译应用程序**
cd app
make -j8 # 使用 -jN 控制并行度
sudo make install # 可选
默认构建将二进制文件放置在 `app/bin/aifilesorter`。
**变体目标：**
make -j8 MACOS_LLAMA_M1 # 输出 app/bin/m1/aifilesorter
make -j8 MACOS_LLAMA_M2 # 输出 app/bin/m2/aifilesorter
make -j8 MACOS_LLAMA_INTEL # 输出 app/bin/intel/aifilesorter
这些目标在编译应用程序之前会重新构建 llama.cpp 运行时。
在 Apple Silicon 上交叉编译 Intel 时，请使用 x86_64 Homebrew（位于 `/usr/local` 下）或设置 `BREW_PREFIX=/usr/local`，以便 Qt/pkg-config 能正确解析。
`sudo make install` 将 macOS 运行时库放置在 `/usr/local/lib/aifilesorter` 下，以避免与无关的系统或 Homebrew ggml 库发生冲突。
每个变体使用不同的构建目录以避免跨架构冲突：
- llama.cpp 库：`app/lib/precompiled-m1`、`app/lib/precompiled-m2`、`app/lib/precompiled-intel`
- 对象文件：`app/obj/arm64` 或 `app/obj/x86_64`
### Windows
现在的构建目标是原生 MSVC + Qt6，无需 MSYS2。支持两个选项；推荐 vcpkg 路线。
选项 A - CMake + vcpkg (推荐)
1. 安装先决条件：
- 带有 Desktop C++ 工作负载的 Visual Studio 2022
- CMake 3.21+（Visual Studio 附带最新版本）
- vcpkg：（克隆并引导）
- 由 vcpkg 清单管理的 `libmediainfo` 包（不使用 vendored 的 MediaInfo 子模块/二进制文件）
- **MSYS2 MinGW64 + OpenBLAS**：从 安装 MSYS2，打开一个 *MSYS2 MINGW64* shell，然后运行 `pacman -S --needed mingw-w64-x86_64-openblas`。`build_llama_windows.ps1` 脚本将此 OpenBLAS 副本用于纯 CPU 构建（vcpkg 变体不合适），默认为 `C:\msys64\mingw64`，除非您传递 `openblasroot=` 或设置 `OPENBLAS_ROOT`。
2. 克隆存储库和子模块：
git clone https://github.com/hyperfield/ai-file-sorter.git
cd ai-file-sorter
git submodule update --init --recursive
3. **构建 vendored libzip**（生成 `zipconf.h` 和 `libzip.lib`）
在您将用于构建应用程序的同一个 x64 Native Tools / VS Developer PowerShell 中运行：
cmake -S external\libzip -B external\libzip\build -A x64 `
-DBUILD_SHARED_LIBS=OFF `
-DBUILD_DOC=OFF `
-DENABLE_BZIP2=OFF `
-DENABLE_LZMA=OFF `
-DENABLE_ZSTD=OFF `
-DENABLE_OPENSSL=OFF `
-DENABLE_GNUTLS=OFF `
-DENABLE_MBEDTLS=OFF `
-DENABLE_COMMONCRYPTO=OFF `
-DENABLE_WINDOWS_CRYPTO=OFF
cmake --build external\libzip\build --config Release
4. 确定 vcpkg 根目录。它是包含 `vcpkg.exe` 的文件夹（例如 `C:\dev\vcpkg`）。
- 如果 `vcpkg` 在您的 `PATH` 中，请运行此命令以打印该位置：
Split-Path -Parent (Get-Command vcpkg).Source
- 否则，请使用您克隆 vcpkg 的目录。
MediaInfo 注意：您**不要**在 Windows 上手动添加 `MediaInfoLib` 的 include/lib 路径。项目已经在 `app/vcpkg.json` 中声明了 `libmediainfo`，并且 `app\build_windows.ps1` 使用 vcpkg 工具链 + 清单配置 CMake，以便 `find_package(MediaInfoLib ...)` 自动解析它。如果您想显式预安装或验证它，请运行 `vcpkg install libmediainfo:x64-windows`。
5. 构建捆绑的 `llama.cpp` 运行时变体（在同一个 **x64 Native Tools** / **VS 2022 Developer PowerShell** shell 中运行）。针对您需要的每个后端调用一次该脚本。在运行纯 CPU 变体之前，请确保步骤 1 中的 MSYS2 OpenBLAS 安装已存在（或显式传递 `openblasroot=`）：
# 纯 CPU / OpenBLAS
app\scripts\build_llama_windows.ps1 cuda=off vulkan=off vcpkgroot=C:\dev\vcpkg
# CUDA (需要匹配的 NVIDIA 工具包/驱动)
app\scripts\build_llama_windows.ps1 cuda=on vulkan=off vcpkgroot=C:\dev\vcpkg
# Vulkan (需要 LunarG Vulkan SDK 或供应商的 Vulkan 1.2+ 运行时)
app\scripts\build_llama_windows.ps1 cuda=off vulkan=on vcpkgroot=C:\dev\vcpkg
每次运行都会在 `app\lib\precompiled\` 下生成适当的 `llama.dll` / `ggml*.dll` 对，并将运行时 DLL 复制到 `app\lib\ggml\w` 中。对于 Vulkan 构建，请安装最新的 LunarG Vulkan SDK（或供应商的运行时），确保在同一 shell 中成功运行 `vulkaninfo`，然后运行该脚本。同时提供 Vulkan 和（可选）CUDA artifacts 可以让 `StartAiFileSorter.exe` 在启动时检测最佳后端——首选 Vulkan，在缺少 Vulkan 时使用 CUDA，而 CPU 作为后备，因此并不强求 CUDA。
6. 使用辅助脚本构建 Qt6 应用程序（仍在 VS shell 中）。辅助脚本通过 `windeployqt` 暂存运行时 DLL，跨变体共享一个依赖项安装树，并且默认在一次运行中生成三个 Windows 构建：
# 如果脚本执行被阻止，每个 shell 需执行一次：
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
app\build_windows.ps1 -Configuration Release -VcpkgRoot C:\dev\vcpkg
- 将 `C:\dev\vcpkg` 替换为您克隆 vcpkg 的路径；它必须包含 `scripts\buildsystems\vcpkg.cmake`。
- 默认情况下，辅助脚本会生成以下输出目录：
- 启用 Windows 自动更新的标准安装程序构建：`app\build-windows\Release`
- 禁用更新检查的 Microsoft Store 构建：`app\build-windows-store\Release`
- 仅通知/手动更新的独立 Windows 构建：`app\build-windows-standalone\Release`
- 使用 `-Variants Standard`、`-Variants MsStore` 或 `-Variants Standalone` 仅构建一个子集。
- `aifilesorter.exe` 是主要的 Windows GUI 入口点。`StartAiFileSorter.exe` 仍作为旧版引导程序在其旁边构建，并带有相同的更新器模式。
- 如果 `VCPKG_ROOT`/`VPKG_ROOT` 已设置或 `vcpkg`/`vpkg` 在 `PATH` 中，则 `-VcpkgRoot` 是可选的。
- 每个变体目录都会收到其自己的可执行文件和暂存的 Qt/第三方 DLL。如果您只想要二进制文件而不捆绑运行时 DLL，请传递 `-SkipDeploy`。
- 传递 `-Parallel ` 以覆盖默认的“所有核心”并行构建行为（例如 `-Parallel 8`）。默认情况下，脚本会调用 `cmake --build ... --parallel ` 和 `ctest -j ` 以使 MSBuild 和 Ninja 保持充分利用。
选项 B - CMake + Qt 在线安装程序
1. 安装先决条件：
- 带有 Desktop C++ 工作负载的 Visual Studio 2022
- 通过 Qt Online Installer 安装的 Qt 6.x MSVC kit（例如，Qt 6.6+ 与 MSVC 2019/2022）
- CMake 3.21+
- vcpkg（用于非 Qt 库）：curl, jsoncpp, sqlite3, openssl, fmt, spdlog, gettext, libmediainfo
2. **构建 vendored libzip**（生成 `zipconf.h` 和 `libzip.lib`）
在您将用于构建应用程序的同一个 x64 Native Tools / VS Developer PowerShell 中运行：
cmake -S external\libzip -B external\libzip\build -A x64 `
-DBUILD_SHARED_LIBS=OFF `
-DBUILD_DOC=OFF `
-DENABLE_BZIP2=OFF `
-DENABLE_LZMA=OFF `
-DENABLE_ZSTD=OFF `
-DENABLE_OPENSSL=OFF `
-DENABLE_GNUTLS=OFF `
-DENABLE_MBEDTLS=OFF `
-DENABLE_COMMONCRYPTO=OFF `
-DENABLE_WINDOWS_CRYPTO=OFF
cmake --build external\libzip\build --config Release
3. 构建捆绑的 `llama.cpp` 运行时（在同一个 VS shell 中）。任何缺失的 OpenBLAS/cURL 包将通过 vcpkg 自动安装：
pwsh .\app\scripts\build_llama_windows.ps1 [cuda=on|off] [vulkan=on|off] [vcpkgroot=C:\dev\vcpkg]
在配置 GUI 之前，这是必需的，因为构建会链接到生成的 `llama` 静态库/DLL。
4. 从存储库根目录配置 CMake，以便 CMake 可以同时看到 Qt 安装和应用程序的 vcpkg 清单（根据您的 Qt 安装修改 `CMAKE_PREFIX_PATH`）：
$env:VCPKG_ROOT = "C:\path\to\vcpkg" # 例如 C:\dev\vcpkg
$qt = "C:\Qt\6.6.3\msvc2019_64" # 示例
cmake -S app -B build -G "Ninja" `
-DCMAKE_PREFIX_PATH=$qt `
-DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake `
-DVCPKG_MANIFEST_DIR=app `
-DAI_FILE_SORTER_REQUIRE_MEDIAINFOLIB=ON `
-DVCPKG_TARGET_TRIPLET=x64-windows
cmake --build build --config Release
此配置步骤启用了 vcpkg 清单模式，因此 `libmediainfo` 会从 `app\vcpkg.json` 自动安装/解析。在 Windows 上无需为 MediaInfo 手动编辑链接器或 include 路径。
说明
- 要从头开始重建，请运行 `.\app\_windows.ps1 -Clean`。该脚本会在配置之前删除选定的变体构建目录和共享的 `app\build-windows-vcpkg_installed` 依赖树。
- 每次成功构建后，运行时 DLL 会通过 `windeployqt` 自动复制；如果您自己管理部署，请使用 `-SkipDeploy` 跳过此步骤。
- 如果 Visual Studio 将 `VCPKG_ROOT` 设置为其在 `Program Files` 下的捆绑副本，请将 vcpkg 克隆到一个可写目录（例如 `C:\dev\vcpkg`），并在运行 `build_llama_windows.ps1` 时传递 `vcpkgroot=`。
- 如果您计划提供 CUDA 或 Vulkan 加速，请在配置 CMake 之前为您打算包含的每个后端运行 `build_llama_*` 辅助脚本，以便库存在。运行时可以同时包含两者并在启动时自动选择，因此 CUDA 仍然是可选的。
- 目前，`-BuildTests` 和 `-RunTests` 仅在 `Standard` 变体中构建并执行测试，这是 Windows 主要的开发/CI 配置。
### 运行测试
基于 Catch2 的单元测试是可选的。通过 CMake 启用它们：
```
cmake -S app -B build-tests -DAI_FILE_SORTER_BUILD_TESTS=ON -DAI_FILE_SORTER_REQUIRE_MEDIAINFOLIB=ON
cmake --build build-tests --target ai_file_sorter_tests --parallel $(nproc)
ctest --test-dir build-tests --output-on-failure -j $(nproc)
```
在 macOS 上，将 `$(nproc)` 替换为 `$(sysctl -n hw.ncpu)`。
在 Windows (PowerShell) 上，请使用：
```
cmake -S app -B build-tests -DAI_FILE_SORTER_BUILD_TESTS=ON -DAI_FILE_SORTER_REQUIRE_MEDIAINFOLIB=ON
cmake --build build-tests --target ai_file_sorter_tests --parallel $env:NUMBER_OF_PROCESSORS
ctest --test-dir build-tests --output-on-failure -j $env:NUMBER_OF_PROCESSORS
```
说明
- 列出单个 Catch2 用例：`./build-tests/ai_file_sorter_tests --list-tests`
- 打印每个用例名称（包括成功）：`./build-tests/ai_file_sorter_tests --verbosity high --success`
在 Windows 上，您可以将 `-BuildTests`（以及用于执行 `ctest` 的 `-RunTests`）传递给 `app\build_windows.ps1`：
```
app\build_windows.ps1 -Configuration Release -Variants Standard -BuildTests -RunTests
```
当前的测试套件（位于 `tests/unit` 下）侧重于核心实用程序；随着新功能获得测试覆盖，可对其进行扩展。
### 在运行时选择后端
Linux 启动器（`app/bin/run_aifilesorter.sh` / `aifilesorter-bin`）和 Windows 启动器均接受以下可选标志：
- `--cuda={on|off}` – 强制启用或禁用 CUDA 后端。
- `--vulkan={on|off}` – 强制启用或禁用 Vulkan 后端。
当未提供任何标志时，应用程序会按优先级顺序（Vulkan → CUDA → CPU）自动检测可用的运行时。使用这些标志可跳过某个后端（`--cuda=off` 会强制使用 Vulkan/CPU，即使已安装 CUDA；`--vulkan=off` 会显式测试 CUDA）或验证新安装的堆栈（`--vulkan=on`）。不允许同时为两个标志传递 `on`，如果未检测到任何 GPU 后端，应用程序将自动保留在 CPU 上。
#### Vulkan 和 VRAM 说明
- 在可用时首选 Vulkan；仅在缺少 Vulkan 或显式请求时才使用 CUDA。
- 应用程序会根据可用的 VRAM 自动估算 `n_gpu_layers`。出于安全考虑，集成 GPU 的上限被设定为 4 GiB，这可能会限制卸载量。
- 如果 VRAM 紧张，应用程序可能会回退到 CPU 或减少卸载。根据经验法则，8 GB+ 的 VRAM 可为 Vulkan 卸载和图像分析提供更流畅的体验；4 GB 通常会导致部分卸载或 CPU 回退。
- 使用 `AI_FILE_SORTER_N_GPU_LAYERS`（`-1` 为自动，`0` 为强制 CPU）或 `AI_FILE_SORTER_GPU_BACKEND=cpu` 覆盖自动估算。
- 对于图像分析，`AI_FILE_SORTER_VISUAL_USE_GPU=0` 会强制视觉编码器在 CPU 上运行，以避免 VRAM 分配错误。
### 环境变量
运行时和 GPU：
- `AI_FILE_SORTER_GPU_BACKEND` - 选择 GPU 后端：`auto`（默认）、`vulkan`、`cuda` 或 `cpu`。
- `AI_FILE_SORTER_N_GPU_LAYERS` - 覆盖 llama.cpp 的 `n_gpu_layers`；`-1` = 自动，`0` = 强制 CPU。
- `AI_FILE_SORTER_CTX_TOKENS` - 覆盖本地 LLM 上下文长度（默认 2048；限制范围 512-8192）。
- `AI_FILE_SORTER_GGML_DIR` - 从中加载 ggml 后端共享库的目录。在 macOS 上，这只能从捆绑或同级应用程序运行时目录中自动发现；如果您需要自定义的 ggml 运行时，请显式使用此变量。
Visual LLM：
- `LLAVA_MODEL_URL` - 视觉 LLM GGUF 模型的下载 URL（启用图像分析所必需）。
- `LLAVA_MMPROJ_URL` - 视觉 LLM mmproj GGUF 文件的下载 URL（启用图像分析所必需）。
- `AI_FILE_SORTER_VISUAL_USE_GPU` - 强制视觉编码器使用 GPU (`1`) 或 CPU (`0`)。默认为自动；如果 VRAM 较低，Vulkan 可能会回退到 CPU。
超时和日志记录：
- `AI_FILE_SORTER_LOCAL_LLM_TIMEOUT` - 等待本地 LLM 响应的秒数（默认 60）。
- `AI_FILE_SORTER_REMOTE_LLM_TIMEOUT` - 等待 OpenAI/Gemini 响应的秒数（默认 10）。
- `AI_FILE_SORTER_CUSTOM_LLM_TIMEOUT` - 等待自定义兼容 OpenAI API 响应的秒数（默认 60）。
- `AI_FILE_SORTER_LLAMA_LOGS` - 启用详细的 llama.cpp 日志（`1`/`true`）；同时遵循 `LLAMA_CPP_DEBUG_LOGS`。
存储和更新：
- `AI_FILE_SORTER_CONFIG_DIR` - 覆盖基本配置目录（`config.ini` 所在的位置）。
- `CATEGORIZATION_CACHE_FILE` - 覆盖配置目录中的 SQLite 缓存文件名。
- `UPDATE_SPEC_FILE_URL` - 覆盖更新源规范 URL（开发/测试）。更新器现在从 `update.windows`、`update.macos` 和 `update.linux` 读取各平台的更新流，但仍接受旧版的单流数据源。
- `AI_FILE_SORTER_UPDATER_TEST_MODE` - 启用 Windows 更新器实时测试模式（`1`/`true`）。启用后，应用程序会跳过更新源获取，并根据以下值合成一个更新版本。
- `AI_FILE_SORTER_UPDATER_TEST_URL` - Windows 更新器实时测试包的直接 URL。它可以指向一个 `.exe`、`.msi`，或者一个仅包含一个 `.exe` 或 `.msi` 的 `.zip`。
- `AI_FILE_SORTER_UPDATER_TEST_SHA256` - 下载的实时测试包的 SHA-256 校验和。如果 URL 指向 ZIP，则此校验和必须是 ZIP 存档本身的。
- `AI_FILE_SORTER_UPDATER_TEST_VERSION` - 实时测试模式显示的可选合成版本。默认为附加了额外尾部的当前应用程序版本，例如 `1.7.2.1`。
- `AI_FILE_SORTER_UPDATER_TEST_MIN_VERSION` - 实时测试模式的可选合成最低版本。默认为 `0.0.0`，因此测试的行为类似于可选更新。
更新源示例：
```
{
"update": {
"current_version": "1.7.1",
"min_version": "1.6.0",
"download_url": "https://filesorter.app/download",
"windows": {
"current_version": "1.7.1",
"min_version": "1.6.0",
"download_url": "https://filesorter.app/download",
"installer_url": "https://filesorter.app/downloads/AIFileSorterSetup-1.7.1.exe",
"installer_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
"macos": {
"current_version": "1.7.1",
"min_version": "1.6.0",
"download_url": "https://filesorter.app/download"
},
"linux": {
"current_version": "1.7.1",
"min_version": "1.6.0",
"download_url": "https://filesorter.app/download"
}
}
}
```
兼容性说明：
- 较旧的应用程序版本仅读取 `update` 下的扁平顶级字段，因此如果您仍需支持它们，请将 `current_version`、`min_version` 和 `download_url` 保留在那里作为旧版兼容流。
- 较新的应用程序版本更倾向于特定平台的更新流，并在存在时使用 `update.windows`、`update.macos` 或 `update.linux`。
- 旧版兼容流只能代表一个通用流，不能代表单独的各平台版本或安装程序。
仅限 Windows 的直接安装程序更新：
- `installer_url` - Windows 安装程序包的直接 URL。
- `installer_sha256` - 用于在启动前验证下载的安装程序的 SHA-256 校验和。
- `installer_url` 现在也可以指向 ZIP 存档，只要该存档仅包含一个安装程序负载（`.exe` 或 `.msi`）。
- 当这两个字段在 Windows 上同时存在时，应用程序可以下载安装程序、验证它，然后提示：`退出应用程序并启动安装程序以进行更新`。
Windows 更新器实时测试模式：
- `aifilesorter.exe` 直接在 Windows 上接受以下标志：
`--updater-live-test`
`--updater-live-test-url=`
`--updater-live-test-sha256=`
`--updater-live-test-version=`
`--updater-live-test-min-version=`
- 如果您仍然使用引导程序路径，`StartAiFileSorter.exe` 也会接受并转发相同的标志系列。
- 实时测试模式仅限 Windows 使用，并有意绕过正常的更新 JSON 源。
- 如果 ZIP 包含多个 `.exe` 或 `.msi`，更新器将停止，而不是去猜测要启动哪个安装程序。
- 如果存在 `--updater-live-test` 但省略了 URL / SHA 标志，`aifilesorter.exe` 还会在可执行文件旁边查找 `live-test.ini` 文件，并从那里填充缺失的值。
- 命令行标志的优先级仍然高于 `live-test.ini`，因此您可以保留一个默认文件，并在需要时仅覆盖一个字段。
`live-test.ini` 示例：
```
[LiveTest]
download_url = https://files.example.com/AIFileSorterSetup-1.7.3.zip
sha256 = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
current_version = 1.7.3
min_version = 0.0.0
```
PowerShell 启动示例：
```
.\aifilesorter.exe `
--development `
--updater-live-test
```
## 分类缓存数据库
AI File Sorter 将分类结果存储在 `config.ini` 旁边的本地 SQLite 数据库中（基本目录可以通过 `AI_FILE_SORTER_CONFIG_DIR` 覆盖）。此缓存允许应用程序跳过已处理的文件并在两次运行之间保留重命名建议。
存储的内容：
- 目录路径、文件名和文件类型（用作唯一键）。
- 类别/子类别、分类法 ID、分类样式和时间戳。
- 建议的文件名（用于图片和文档的重命名建议）。
- 纯重命名标志（在启用图片/文档纯重命名模式时使用）。
- 已应用重命名标志（标记执行重命名的时间，使其不会再次被建议）。
如果您从“审查”对话框中重命名或移动文件，缓存条目将更新为新名称。已重命名的图片文件在后续运行中将被跳过，不进行视觉分析和重命名建议。在“审查”对话框中，当启用纯重命名模式时，这些已重命名的行会被隐藏，但当启用分类时，它们会保持可见，以便您仍然可以将它们移动到类别文件夹中。要重置文件夹的缓存，请接受重新分类提示或删除缓存文件（或将 `CATEGORIZATION_CACHE_FILE` 指向一个新文件名）。
## 卸载说明
- **Debian/Ubuntu 软件包安装**：`sudo apt remove aifilesorter`
- **Linux 源码安装**：`cd app && sudo make uninstall`
- **macOS 源码安装**：`cd app && sudo make uninstall`
对于源代码安装，`make uninstall` 会移除可执行文件和暂存的预编译库。如果您不再需要它们，还可以删除 `~/.local/share/aifilesorter/llms` (Linux) 或 `~/Library/Application Support/aifilesorter/llms` (macOS) 中缓存的本地 LLM 模型。
## 使用您的 OpenAI API 密钥
想要使用 ChatGPT 而不是捆绑的本地模型吗？请使用您自己的 OpenAI API 密钥：
1. 在应用程序中打开 **设置 -> 选择 LLM**。
2. 选择 **ChatGPT (OpenAI API key)**，粘贴您的密钥，并输入您想要使用的 ChatGPT 模型（例如 `gpt-4o-mini`、`gpt-4.1` 或 `o3-mini`）。
3. 点击 **OK**。该密钥将本地存储在您的 AI File Sorter 配置中（位于应用程序数据文件夹中的 `config.ini` 中），并用于未来的运行。清空该字段即可将其移除。
4. 仅在选择此选项时才需要网络连接。
## 使用您的 Gemini API 密钥
更倾向于使用 Google 的模型？请使用您自己的 Gemini API 密钥：
1. 访问 **https://aistudio.google.com** 并使用您的 Google 帐号登录。
2. 在左侧导航栏中，打开 **API keys**（或 **Get API key**），然后点击 **Create API key**。选择 *Create API key in new project*（或选择一个现有项目）并复制生成的密钥。
3. 在应用程序中，打开 **设置 -> 选择 LLM**，选择 **Gemini (Google AI Studio API key)**，粘贴您的密钥，并输入您想要的 Gemini 模型（例如 `gemini-2.5-flash-lite`、`gemini-2.5-flash` 或 `gemini-2.5-pro`）。
4. 点击 **OK**。该密钥本地存储在您的 AI File Sorter 配置中，并用于未来的运行。清空该字段即可将其移除。
## 测试
- 从存储库根目录，清除任何旧缓存并运行 CTest 包装脚本：
cd app
rm -rf ../build-tests # 清除来自其他检出的缓存
./scripts/rebuild_and_test.sh
- 该脚本会配置到 `../build-tests`，进行构建，然后运行 `ctest`。
- 如果您有多个存储库副本（例如 `ai-file-sorter` 和 `ai-file-sorter-mac-dist`），则每个副本都需要自己的 `build-tests` 文件夹；重用来自不同路径的文件夹会导致 CMake 抱怨源/构建目录不匹配。
## 诊断
如果您需要报告错误或收集故障排除数据，请使用捆绑的诊断脚本：
- **macOS:** `./app/scripts/collect_macos_diagnostics.sh`
- **Linux:** `./app/scripts/collect_linux_diagnostics.sh`
- **Windows (PowerShell):** `.\app\scripts\collect_windows_diagnostics.ps1`
每个脚本都会收集相关日志，对常见的敏感路径进行脱敏处理，并将结果打包成 zip 存档以便共享。请参阅 [app/scripts/README.md](app/scripts/README.md) 了解诸如时间过滤和自动打开输出文件夹等选项。
## 使用指南
1. 启动应用程序（请根据您的操作系统参阅[安装说明](#installation)中的最后一步）。
2. 选择要分析的目录。
### 使用空运行和撤销
- 在结果对话框中，您可以启用 **“空运行 (仅预览，不移动文件)”** 以预览计划的移动。预览对话框会显示“从/到”信息，而不会移动任何文件。
- 在执行真正的排序后，应用程序会保存一个持久的撤销计划。您可以稍后通过 **编辑 → “撤销上次运行”** 进行还原（尽力而为；跳过冲突/更改）。
3. 根据您的偏好勾选主窗口上的复选框。
4. 点击 **“分析”** 按钮。应用程序将根据您选择的选项扫描每个文件和/或目录。
5. 将出现一个审查对话框。验证已分配的类别（以及子类别，如果在步骤 3 中启用）。
6. 点击 **“确认并排序!”** 移动文件，或点击 **“稍后继续”** 推迟。由于分类结果已保存，您可以随时从上次停下的地方继续。
## 对远程目录进行排序 (例如 NAS)
请遵循[使用指南](#how-to-use)中的步骤，但对 **步骤 2** 进行如下修改：
- **Windows：** 为您的网络共享分配一个驱动器号（例如 `Z:` 或 `X:`）（[操作说明](https://support.microsoft.com/en-us/windows/map-a-network-drive-in-windows-29ce55d1-34e3-a7e2-4801-131475f9557d))。
- **Linux & macOS：** 使用类似以下的命令将网络共享挂载到本地文件夹：
sudo mount -t cifs //192.168.1.100/shared_folder /mnt/nas -o username=myuser,password=mypass,uid=$(id -u),gid=$(id -g)
(请将 192.168.1.100/shared_folder 替换为您实际的网络位置路径，并根据需要调整选项。)
## 贡献
- Fork 本存储库并提交 Pull Request。
- 在 GitHub Issue Tracker 上报告问题或建议功能。
- 遵循现有的代码风格和文档格式。
## 致谢
- Curl:
- Dotenv:
- git-scm:
- Hugging Face:
- JSONCPP:
- Llama:
- libzip:
- Local File Organizer
- llama.cpp
- MediaInfoLib:
- Mistral AI:
- OpenAI:
- OpenSSL:
- PDFium:
- Qt:
- unzip (Info-ZIP):
标签：AI, Apple Metal, Bash脚本, CUDA, DLL 劫持, LLM集成, Vectored Exception Handling, Vulkan, 人工智能, 内容感知, 图像处理, 大语言模型, 效率工具, 数字资产管理, 数据整理, 数据治理, 文件分类, 文件去重, 文件归档, 文件搜索, 文件整理, 文件检索, 文件管理, 文件重命名, 文档管理, 服务枚举, 本地LLM, 本地模型, 本地部署, 桌面应用程序, 用户模式Hook绕过, 自动化代码审查, 视频处理, 远程LLM, 音频处理, 预览工作流