萤核智能文件夹是一款基于本地 AI 模型的开源桌面文件管理工具，完全离线运行，保护隐私。本文从技术角度分享整个系统的设计与实现。
为什么要做这个工具？
电脑用了好几年，文件越来越多，项目文档、下载资料、工作文件散落各处，想找某个文件根本找不到。
传统工具只能按名称、日期、大小排序，但真正有用的分类是语义分类——比如"合同类"、"设计稿类"、"财务报表类"。这种分类只有 AI 才能做到。
而市面上的 AI 工具大多需要上传文件到云端，对于涉及隐私或商业机密的文件来说，这是不可接受的。
所以我做了这款完全本地运行的 AI 文件管理工具。
项目概览
| 项目 | 详情 |
|---|---|
| 名称 | 萤核智能文件夹 (Yonuc AI Folder) |
| 官网 | aifolder.iocn.cn |
| GitHub | github.com/Leonard-Li7… |
| 技术栈 | Electron Forge + electron-vite + React 19 + Zustand + Tailwind CSS |
| 数据库 | better-sqlite3 |
| AI 模型 | Qwen 通义千问本地模型 (1.5B ~ 7B) |
| 支持平台 | Windows / macOS / Linux |
核心架构设计
应用启动三阶段
为了平衡启动速度和服务可用性，系统采用三阶段启动策略：
配置阶段 (Configuration) → 初始化阶段 (Initialization) → 运行时阶段 (Runtime)
↓ ↓ ↓
日志 + 数据库 + 配置 AI服务 + 模型加载 服务就绪，响应请求
系统健康检查 能力检测 + 验证 支持懒加载切换
配置阶段只初始化最小依赖：日志系统、数据库连接、ConfigOrchestrator 配置管理、系统健康检查。AI 服务实例和模型加载全部延迟到第二阶段。
AI 分析三阶段管道
第一阶段（内容提取）→ 第二阶段（质量评分）→ 第三阶段（维度分析）
↓ ↓ ↓
FileAnalysisService QualityScoringService DimensionAnalyzer
- 内容提取：从各种文件格式中提取文本内容和元数据（支持文档、图片、音视频、代码等）
- 质量评分：评估提取内容的质量，过滤低质量或无效数据
- 维度分析：AI 根据文件内容生成语义维度标签，如"合同"、"设计稿"、"技术文档"等
整个过程完全在本地完成，不需要联网。
Monorepo 项目结构
yonuc-ai-folder/
├── apps/
│ ├── desktop/ # 桌面应用主程序
│ │ └── src/electron/
│ │ └── runtime-services/ # 运行时服务
│ │ ├── ai/ # AI 服务
│ │ ├── database/ # 数据库服务
│ │ ├── llama/ # Llama 模型服务
│ │ ├── system/ # 系统服务
│ │ └── filesystem/ # 文件系统服务
│ ├── server/ # 服务端
│ └── admin/ # 管理端
├── packages/
│ ├── core-engine/ # 核心 AI 引擎
│ ├── shared/ # 共享工具
│ └── types/ # 类型定义
└── tests/ # 测试
核心技术实现
1. 统一配置管理系统
采用 ConfigKey 字符串字面量类型 + ConfigOrchestrator 协调器模式：
// 88 个配置项定义为字符串字面量类型
type ConfigKey =
| 'APP_NAME' | 'APP_VERSION'
| 'AI_MODEL_NAME' | 'AI_MODEL_SIZE'
| 'ANALYSIS_BATCH_SIZE' | 'ANALYSIS_MAX_RETRIES'
// ... 更多配置项
// ConfigOrchestrator 提供类型安全的 API
const model = configOrchestrator.getValue<string>('AI_MODEL_NAME');
configOrchestrator.updateValue('ANALYSIS_BATCH_SIZE', 50);
// 通过 IPC 自动同步到渲染进程
configOrchestrator.onValueChange('AI_MODEL_NAME', (newVal) => {
// 配置变更时自动触发
});
2. 模型能力路由系统
不同模型有不同能力，系统通过 ModelCapabilityDetector 自动检测：
interface ModelCapability {
textAnalysis: boolean; // 文本分析
imageAnalysis: boolean; // 图片分析
codeAnalysis: boolean; // 代码分析
dimensionGeneration: boolean; // 维度生成
}
// 根据能力自动路由到合适的模型
const routingManager = new AIServiceRoutingManager();
const model = routingManager.selectModel(requiredCapabilities);
3. 虚拟目录系统
核心创新点之一——虚拟目录不移动原始文件，而是基于 AI 分类结果创建逻辑视图：
// 维度树节点
interface DimensionTreeNode {
id: string;
name: string; // 如 "合同", "设计稿"
fileCount: number;
children: DimensionTreeNode[];
files: AnalyzedFile[];
}
// 支持浏览模式（单选筛选）和整理模式（多选组合）
type ViewMode = 'browse' | 'organize';
4. 文件监听与自动分析
使用 chokidar 实现文件实时监控：
// 监听指定目录变更
const watcher = chokidar.watch(directoryPath, {
ignored: /(^|[/\]).|node_modules|.git/,
persistent: true,
ignoreInitial: true
});
watcher.on('add', (filePath) => {
// 新文件自动加入分析队列
analysisQueueService.addItems([{ path: filePath }]);
});
核心功能清单
| 功能 | 说明 |
|---|---|
| 本地 AI 分析 | 基于 Qwen 本地模型，完全离线运行 |
| 智能维度分类 | AI 自动按语义维度分类文件 |
| 虚拟目录 | 不移动原始文件，创建逻辑分类视图 |
| 一键整理 | 按分类结果自动移动文件到对应文件夹 |
| 文件监听 | 实时监控目录，新文件自动分析 |
| 多格式支持 | 文档、图片、音视频、代码等 |
| 跨平台 | Windows / macOS / Linux |
适用场景
- 设计师：大量设计稿、素材、参考文件的分类管理
- 律师/法务：合同、法律文书、案件资料的语义分类
- 研究人员：论文、参考文献、实验数据的智能归档
- 自由职业者：客户资料、项目文件、发票的统一管理
- NAS 用户：配合 NAS 对海量文件进行 AI 分类索引
如何使用
- 前往 GitHub Releases 下载最新版
- 安装后首次启动会进入欢迎向导，自动检测硬件并推荐 AI 模型
- 添加你想管理的工作目录
- 点击"开始分析"，AI 自动扫描并分类所有文件
- 在虚拟目录中浏览分类结果，支持一键整理
写在最后
萤核智能文件夹是一个核心业务逻辑开源的项目，理念是 "文件不出本机，隐私绝对安全"。
- GitHub: github.com/Leonard-Li7…
- 官网: aifolder.iocn.cn
如果觉得有帮助，欢迎 Star、Fork，也欢迎提 Issue 和 PR！
本文介绍了萤核智能文件夹的技术架构和核心实现，希望能为有类似需求的开发者提供参考。