企业官网建设流程全解析

• AI 应用
• 大模型
• 本地部署
• 桌面应用

AI File Sorter 是一款支持本地与云端大模型的跨平台 AI 文件整理与重命名桌面应用。为了保障 AI 分类、文件改名、缓存学习等核心功能稳定可靠，项目构建了一套分层测试体系：基于 Catch2 的自动化单元测试、可随生产二进制运行的自测模式，以及面向真实本地大模型的 Live LLM 实战测试。本文将从新手视角带你快速了解这套测试体系如何运作。

1. 测试体系全景：三层防线如何分工

AI File Sorter 的测试分为三层，各负其责，共同覆盖从代码逻辑到真实运行时的全链路：

官方将测试地图浓缩在 docs/testing.md 中，而 TESTS.md 则是一份逐用例的详细目录：每个测试文件包含什么用例、目的、前置条件、操作步骤和预期结果，堪称"测试文档即代码说明书"的典范。

2. Catch2 单元测试：日常开发的主力

所有单元测试位于 tests/unit/，使用 Catch2 框架，通过 CTest 统一调度。配置时需要开启AI_FILE_SORTER_BUILD_TESTS=ON，之后只需两条命令：

cmake --build build-tests --config Release --target ai_file_sorter_tests --parallel ctest --test-dir build-tests -C Release --output-on-failure

只想跑单个用例？直接按名称（支持模式匹配）过滤即可：

./build-tests/ai_file_sorter_tests "用例名称或模式"

单元测试覆盖了哪些关键模块？

TESTS.md 按测试文件逐一登记了 50+ 个测试源文件，重点模块包括：

• 无头分析命令（tests/unit/test_headless_analysis_command.cpp）：验证 Explorer 集成的--headless契约，包括运行锁占用时报告blocked状态、空文件夹分类完成时写出completed状态 JSON、UTF-8 文件名在 Review 状态中不损坏等二十余个用例；
• 本地 LLM 后端（tests/unit/test_local_llm_backend.cpp）：覆盖 CUDA/Vulkan 后端探测、显存不足时安全回退 CPU、GPU 层数重试阶梯（如20, 15, 11, 8, 6, 4, 3, 2, 1）等 GPU 相关细节；
• 提示词构建器（tests/unit/test_local_llm_prompt_builder.cpp）：确保文档、图片、目录各自路由到专属系统提示词，且长分析段落重试裁剪后仍保留分类限制与回答格式；
• 复选框路由矩阵（tests/unit/test_checkbox_matrix.cpp）：穷举 128 种分析选项组合，验证每个文件都落入预期分桶——这是保证"用户勾什么、程序就做什么"的兜底防线；
• 用户学习库（tests/unit/test_user_learning_store.cpp）：验证用户确认的分类映射持久化、向量嵌入更新、清除学习行为时数据库依然可用；
• 缓存维护（tests/unit/test_cache_maintenance_service.cpp）：确认清理分类缓存时不会误删用户学习数据。

一个值得新手学习的细节：涉及 GUI 的测试使用 Qt 无头平台插件（Windows 用minimal、其他平台用offscreen），无需显示器也能跑完整的界面逻辑测试。

3. 生产自测模式：--self-test与--test

与许多项目不同，AI File Sorter 的生产二进制本身就内置了测试能力，实现见 app/include/AppTestRunner.hpp：

• --self-test：运行确定性的无头检查并以通过/失败退出码结束。当前套件whitelist会在临时配置目录中构建大型合成白名单，验证压缩提示词候选选择、已学分类偏好和 Unicode 白名单标签。可用--self-test=whitelist单独指定套件：

./build-tests/aifilesorter --self-test ./build-tests/aifilesorter --self-test=whitelist

• --test：启动正常 GUI 并附加 Tests 菜单，自动生成更大的示例白名单与示例文件，然后调用你选择的真实 LLM 走完整分析流程，方便在 Review 对话框中人工审查效果。测试模式产生的白名单、缓存、撤销数据都隔离在test_mode_profile目录中，不会污染真实配置。

这种"生产自测"的价值在于：它测试的是用户真正运行到的那个二进制，能暴露纯单元测试发现不了的环境问题（比如打包、路径、权限）。

4. Live LLM 实战测试：真实模型 + 真实文件

tests/live_llm/headless_live_llm_tests.py 是一套可选的黑盒集成测试，它对真实构建出的aifilesorter --headless命令发起攻击性检验：使用真实的本地文本模型（GGUF），对真实或生成的文件副本进行分类、重命名，然后校验输出的状态/Review JSON 以及文件系统上的实际变化。详见 tests/live_llm/README.md。

为什么它是"可选"的？

这套测试慢、依赖硬件、且模型措辞天然不确定，因此不纳入默认快速循环。它断言的是稳定的生产契约，而非模型的精确输出：

• 状态 JSON 合法、Review 计划成功生成
• 分类结果非空、且严格约束在白名单范围内
• 仅处理选中的文件（同目录多选边界）
• 文件扩展名保持不变
• 多语言重命名（英语/法语/简体中文/印地语）

如何开启并运行

在 CMake 配置时追加-DAI_FILE_SORTER_ENABLE_LIVE_LLM_TESTS=ON，Windows 用户推荐用辅助脚本：

.\app\build_windows.ps1 -Configuration Release -Variants Standard -BuildTests -EnableLiveLlmTests

然后指定模型并执行带live-llm标签的测试：

$env:AI_FILE_SORTER_LIVE_LLM_MODEL="C:\models\text-model.gguf" ctest --test-dir build-tests -L live-llm --output-on-failure

新手友好的容错设计：如果缺少可执行文件或可用模型，runner 会以退出码77结束，CTest 将其报告为跳过而非失败，不会污染你的日常测试基线。每轮运行还会在工作目录写progress.log，每个用例保留command.txt、stdout.txt、status.json等现场文件，失败时方便复现排查。

5. 什么改动该跑什么测试？

docs/testing.md 给出了实用的"变更 → 测试"映射，值得作为日常开发规范：

• 改了提示词或分类体系→ 先跑提示词构建器与分类相关测试；
• 改了无头模式或 Explorer 集成→ 跑聚焦的Headless*测试，并同步更新 TESTS.md；
• 改了更新器/更新源→ 跑更新器与更新源测试；
• 改了打包/构建脚本→ 除了单元测试，还要在相应平台验证构建路径。

辅助脚本也很齐全：tests/run_all_tests.sh 一键串行执行 tests/run_database_tests.sh（数据库场景）与 tests/run_translation_tests.sh（翻译管线），保证多语言与持久化两条长尾链路不被遗漏。

6. 总结

AI File Sorter 的测试体系体现了"AI 应用测试"的最佳实践：

1. 快而确定的 Catch2 单元测试覆盖 99% 的回归场景，且 UI 测试可在无头环境运行；
2. 生产自测（--self-test/--test）让开发者随时用真实二进制做确定性体检；
3. Live LLM 黑盒测试用稳定不变量（而非精确文案）来约束不确定的模型输出，慢则慢矣，却守住了最后的真实运行时防线。

对于想学习 AI 桌面应用工程实践的新手，这套"分层 + 文档即契约（TESTS.md）+ 稳定不变量断言"的组合，是一份可以直接借鉴的范本。

• AI 应用
• 大模型
• 本地部署
• 桌面应用