【实用程序】AI 文件整理助手（基于Next.js 16 + TypeScript + Prisma + SQLite + Tailwind CSS 4） — 详细设计与部署指南（附源代码）

海兰

403人浏览 · 2026-06-13 17:32:24

海兰 · 2026-06-13 17:32:24 发布

技术栈: Next.js 16 + TypeScript + Prisma + SQLite + Tailwind CSS 4

1. 概述

AI 文件整理助手是一个基于大语言模型（LLM）和多模态视觉模型（VLM）的智能文件管理系统。它可以自动分析文件的语义内容——无论是一份合同、一张照片还是一段代码——都能理解其核心信息，然后根据你设定的自然语言规则，自动完成文件重命名、分类归档等整理工作。

在这里插入图片描述

1.1 核心理念：感知 → 认知 → 决策 → 执行

整个系统被设计为一条清晰的四层流水线，每一层各司其职：

感知层：像一双“眼睛”，持续扫描你指定的文件夹，记录文件的大小、类型、内容摘要等基本信息。
认知层：调用 AI 模型真正“读懂”文件——合同里提到了什么条款？照片里是风景还是人物？代码文件实现什么功能？然后生成描述、分类和标签。
决策层：结合你自定义的整理规则（例如“所有合同文件放到 工作/合同 文件夹”），决定每个文件最终的去向和命名方式。如果发生同名冲突，自动协调。
执行层：按照计划实际移动、重命名文件，并完整记录每一步操作。如果将来发现整理不合理，可以一键回滚到整理前的状态。

通过这种分层设计，系统既保留了 AI 的灵活理解能力，又确保了你对文件整理的最终控制权。

2. 系统架构

2.1 整体架构图

生产环境采用 Caddy 作为统一反向代理入口，前端 Next.js 服务提供 Web 界面和 API，底层使用 SQLite 本地数据库，AI 能力可通过自带的 SDK 或你配置的自定义模型提供。

2.2 技术栈总览

层级	技术选型	说明
前端框架	Next.js 16 (App Router)	React 19 + Server Components
UI 组件库	shadcn/ui + Radix UI	50+ 可访问性组件
样式方案	Tailwind CSS 4 + tailwind-merge	原子化 CSS + 主题系统
动画与图表	Framer Motion + Recharts	流畅动效 + 仪表盘可视化
状态管理	Zustand + TanStack React Query	轻量级 UI 状态 + 服务端状态
表单校验	React Hook Form + Zod	类型安全的表单
ORM	Prisma 6	类型安全的数据库操作
数据库	SQLite (单文件)	零配置，嵌入式
运行时	Bun	高性能 JS 运行时
反向代理	Caddy	自动 HTTPS + 动态端口转发
AI SDK	z-ai-web-dev-sdk	内置 LLM/VLM 分析引擎

2.3 目录结构简析

.
├── prisma/               # 数据库模型定义
├── src/
│   ├── app/              # Next.js App Router
│   │   ├── api/          # 14 个 API 路由（分析、整理、执行、规则...）
│   │   └── page.tsx      # 主页面（5 个标签页）
│   ├── components/       # React 组件（仪表盘、文件管理、设置等）
│   ├── lib/              # 工具库（Prisma 客户端、API 封装、状态管理）
│   └── hooks/            # 自定义 hooks
├── .zscripts/            # 部署脚本（构建、启动）
├── Caddyfile             # Caddy 反向代理配置
└── db/custom.db          # SQLite 数据库文件

3. 数据库设计

数据库是系统的“记忆中枢”，记录了每个文件的元数据、AI 分析结果、用户规则、操作日志等。所有数据都保存在一个本地 SQLite 文件中，无需额外安装数据库服务。

3.1 ER 关系图

3.2 核心模型详解

📁 FileRecord — 文件记录

每个被监控的文件都会产生一条 FileRecord，记录它的“前世今生”。其中 status 字段体现了文件的整理生命周期：

pending：刚被系统发现，尚未分析。
analyzed：AI 已经理解了文件内容，生成了分类、标签和建议。
organized：文件已按照决策结果被移动或重命名。
rolled_back：曾经被整理过，但后来用户执行了回滚操作。

🏷️ SemanticTag — 语义标签

AI 可以为文件打上多个标签，例如一份发票可能同时拥有“财务”“发票”“2025年”等标签。source 字段标记了标签的来源（AI 生成、用户手动添加或规则匹配），方便后续优化模型。

📜 OrganizationRule — 整理规则

这是将自然语言转化为可执行逻辑的核心。你写下“所有合同文件都移到工作/合同目录”，系统会调用 LLM 将其解析为结构化的条件与动作，保存在 parsedLogic 字段中：

{
  "conditions": {
    "fileTypes": ["pdf", "docx"],
    "contentKeywords": ["合同", "协议"]
  },
  "actions": {
    "targetPath": "/工作/合同/",
    "namingPattern": "YYYY-MM-DD_主题"
  }
}

当新文件到来时，系统可以快速匹配这些结构化条件，而无需每次都调用 LLM，兼顾了灵活性与性能。
在这里插入图片描述

🔧 ModelConfig — AI 模型配置

你可以在设置中添加自己的 OpenAI 兼容模型（比如 DeepSeek、通义千问、智谱等）。系统会优先使用你配置的默认模型进行分析；如果连不通，会自动降级到内置的 z-ai-web-dev-sdk，确保核心功能始终可用。API Key 在数据库和前端界面中都会脱敏显示（如 sk-7a***3f）。
在这里插入图片描述

4. API 路由设计

系统一共提供了 14 个 API 路由，覆盖文件管理、AI 分析、整理执行、规则管理、回滚等全部功能。下面重点介绍几个核心流程的设计原理。

4.1 文件分析 — `POST /api/analyze`

分析一个文件时，系统需要决定应该调用 LLM（文本模型）还是 VLM（视觉模型），然后根据模型返回的 JSON 更新数据库。整个流程如下：

Prompt 设计要点：系统会构造一个包含文件名、扩展名、内容片段和 MIME 类型的提示词，明确要求模型只返回纯 JSON 格式。例如：

你是一个文件分析专家。请分析以下文件，返回 JSON，不要有其他文字。
文件名：2025_销售合同.pdf
类型：document
内容摘要：“本合同由甲方与乙方签订...”

模型返回的 JSON 包含 description、category、tags、suggestedName、suggestedPath 和 confidence 六个字段。系统内置了三级 JSON 容错机制：先尝试直接 JSON.parse，若失败则从 ```json ... ````代码块中提取，最后用正则提取任意{…}` 结构。

4.2 整理决策 — `POST /api/organize`

决策引擎使用优先级链来确保整理行为既符合用户规则，又具备 AI 的适应性：

规则匹配的两种方式：

结构化匹配（快速）：如果规则已经有了 parsedLogic，直接匹配 fileTypes、contentKeywords、pathPatterns、namePatterns 四个维度。
语义匹配（灵活）：如果规则是刚创建的，还未生成结构化条件，或者匹配失败，则回退到 LLM 语义判断。系统将规则文本和文件信息发给 LLM，询问“此文件是否符合该规则？”，模型返回 true/false。

命名模板：在规则中可以定义动态命名模式，例如 YYYY-MM-DD_主题。系统会将 YYYY 替换为当前年份，主题 替换为文件的第一个标签或分类名。

4.3 操作执行与回滚 — 保障安全

执行整理时，系统会逐条执行操作，并为每条操作创建一条 OperationLog 记录，包含完整的旧路径和新路径。即使在执行过程中某一条失败了，其他操作也不会受影响。

回滚同样简单：根据 OperationLog 中保存的 oldPath 和 oldName，将文件恢复原样，并将日志标记为 rolled_back。回滚是一次独立的文件系统操作，不会被记录为新的整理操作，但它本身也会产生一条新的 OperationLog 用于审计。
在这里插入图片描述

5. 前端设计

前端是一个单页应用（SPA），通过 5 个清晰的标签页提供所有功能。整个界面使用 Tailwind CSS 4 构建，支持暗色主题和流畅的动画过渡。

5.1 页面功能矩阵

标签页	组件	核心功能
仪表盘	`DashboardView`	统计卡片 + 柱状图（文件类型分布） + 环形饼图（置信度） + 折线图（近7天操作趋势） + 进度条（分类完成度） + 热门标签云
文件管理	`FilesView`	文件列表表格（支持搜索、筛选、按列排序） + 批量选择与操作 + 查看 AI 分析结果弹窗 + 执行整理确认对话框
智能规则	`RulesView`	自然语言规则编辑器（输入中文描述，一键 LLM 解析） + 预设规则库 + 优先级拖拽调整 + 启用/禁用开关
操作日志	`ActivityView`	操作历史列表（分页） + 按类型/状态筛选 + 每条日志旁的回滚按钮
系统设置	`SettingsView`	监控目录管理（添加/删除/开启递归） + 置信度阈值滑块（低于阈值不自动执行） + 自定义 AI 模型配置（含连通性测试） + 调度频率设置

5.2 状态管理 (Zustand)

全局状态只存放 UI 相关的共享信息，避免过度渲染：

interface AppState {
  activeTab: 'dashboard' | 'files' | 'rules' | 'activity' | 'settings'
  isAnalyzing: boolean      // 任何分析进行中时禁用某些按钮
  isOrganizing: boolean     // 整理进行中时显示进度提示
  selectedFileIds: string[] // 批量操作时记录选中的文件
}

业务数据（文件列表、规则列表等）由各个组件内部通过 React Query 管理，利用缓存和后台刷新提升体验。
在这里插入图片描述

5.3 数据可视化 — 一眼看懂你的文件世界

柱状图：展示文档、图片、视频、音频、代码、其他等类别的文件数量，每类用不同颜色区分。
环形饼图：展示 AI 分析的置信度分布（高 ≥80%、中 50–80%、低 <50%），让你快速判断 AI 建议的可靠程度。
折线图：展示过去 7 天每天的操作总数，同时用虚线拆分为“重命名”和“移动”两类，方便观察整理活动模式。
进度条：展示各类文件已完成分析的比例，例如“文档类已分析 82%”。

所有图表都基于 Recharts 实现，支持响应式布局和悬停详情提示。

6. AI 工作流原理

这一章深入解释系统如何“思考”一个文件的去处，以及如何让你参与进来形成良性循环。

6.1 分析阶段：从“文件名”到“理解内容”

传统文件整理只能看文件名和扩展名，而 AI 整理助手通过 LLM 和 VLM 真正理解文件内容。以一份 PDF 合同为例：

感知层提取文件的前 4000 个字符作为 contentSnippet，连同文件名、扩展名一起发送给 LLM。

LLM 阅读这段文本，识别出“甲方乙方”“签约金额”“有效期”等关键信息，然后输出 JSON：

{
  "description": "一份关于设备采购的销售合同，金额50万元，有效期至2026年12月。",
  "category": "合同",
  "tags": ["财务", "法务", "采购"],
  "suggestedName": "2025-03-15_设备采购合同",
  "suggestedPath": "/工作/合同/",
  "confidence": 0.94
}

系统将结果存入数据库，并将文件状态从 pending 更新为 analyzed。

对于图片文件，VLM 模型接收图片的 base64 或 URL，同样输出描述和标签。如果图片内容复杂（例如一张包含多个物体的照片），VLM 会尝试识别主要对象和场景。

为什么需要三级 JSON 解析？ 因为不同模型可能不遵守“只返回 JSON”的指令，有些模型会回复“好的，以下是您需要的 JSON：{...}”。系统必须先剔除这些额外文字，才能安全解析。

6.2 决策阶段：多级智能协同

决策引擎的优先级链保证两个目标：用户规则优先，AI 补足空白。

第 1 级（用户规则）：如果你已经创建了规则“将任何包含‘合同’的文件移动到 工作/合同”，这条规则会直接生效。匹配过程首先使用结构化字段（快速），只有在规则太复杂或未解析时才调用 LLM 进行语义匹配。
第 2 级（AI 分析结果）：对于没有规则覆盖但已经被分析过的文件，系统直接使用 AI 给出的 category 和 suggestedPath。
第 3 级（实时 LLM 建议）：对于未分析且无规则的文件，系统临时向 LLM 发起一次请求，询问“这个文件应该放到哪里？”，并实时获得建议。
第 4 级（兜底）：如果以上都不可用（例如网络问题导致 LLM 无法调用），系统按扩展名简单分类：.pdf、.docx → /文档/，.jpg、.png → /图片/，等等。

这种多级设计确保了在任何情况下文件都不会被落下，同时优先尊重你设定的明确规则。

6.3 人机回环：让系统越用越聪明

设计一个“自我改进”的文件助手，离不开用户的反馈。系统通过以下机制形成闭环：

反馈收集：每次用户在界面上接受 AI 的建议、修改建议后再执行，或者直接回滚操作，系统都会记录下原始建议和用户的最终选择，存入 FeedbackExample 表。
阈值控制：你可以在设置中调高置信度阈值（比如 0.8），这样只有 AI 非常自信的建议才会自动执行，其余会要求你确认。
规则演化：未来版本可以基于积累的反馈数据，自动推荐新的整理规则或调整现有规则的优先级。

得益于完整的操作日志，你可以随时回滚任何一次整理操作，这给了你反复试验不同整理策略的自由。

7. 部署指南

7.1 环境要求

依赖	版本	用途
Bun	≥1.3	首选运行时（也可用 Node.js 20+ 备选）
Caddy	≥2.7	反向代理（提供简洁的 HTTPS 配置）
操作系统	Linux (Ubuntu 20.04+)	生产环境推荐
磁盘空间	≥2GB	包含依赖和数据库

7.2 开发环境快速启动

# 1. 安装依赖
bun install

# 2. 配置数据库路径
echo "DATABASE_URL=file:./db/custom.db" > .env

# 3. 初始化数据库 schema
bun run db:push
bun run db:generate

# 4. （可选）填充演示数据 — 启动后访问 GET /api/seed

# 5. 启动开发服务器
bun run dev   # 访问 http://localhost:3000

7.3 生产构建（使用提供的脚本）

项目提供了自动化构建脚本 .zscripts/build.sh，它会执行以下步骤：

安装依赖：bun install
构建 Next.js standalone：bun run build 生成 .next/standalone
准备数据库：将当前开发数据库复制到构建目录，并执行 prisma db push 同步 schema
打包：将 standalone 输出、数据库、Caddyfile、启动脚本打包成 tar.gz 文件

执行命令：

chmod +x .zscripts/build.sh
.zscripts/build.sh

生成的压缩包位于 ./build_fullstack_*.tar.gz。

7.4 生产部署（以 systemd 或 Docker 为例）

传统部署（systemd）

# 解压到应用目录
mkdir -p /app
tar -xzf build_fullstack_*.tar.gz -C /app

# 启动服务（脚本会自动启动 Next.js 和 Caddy）
chmod +x /app/start.sh
/app/start.sh

start.sh 的工作流程：

检查数据库文件完整性
设置 NODE_ENV=production、PORT=3000、HOSTNAME=0.0.0.0
用 bun server.js 后台启动 Next.js
用 exec caddy run 前台启动 Caddy（确保容器不退出）
捕获 SIGTERM 信号，优雅关闭所有子进程

Docker 部署（推荐）

创建 Dockerfile：

FROM oven/bun:1-alpine AS base
WORKDIR /app

# 安装 Caddy
RUN apk add --no-cache caddy

# 复制构建产物
COPY build_output/next-service-dist ./next-service-dist
COPY build_output/db ./db
COPY build_output/Caddyfile ./
COPY build_output/start.sh ./

RUN chmod +x start.sh

EXPOSE 81 3000
CMD ["./start.sh"]

构建并运行：

docker build -t ai-file-organizer .
docker run -d -p 81:81 -p 3000:3000 \
  -v /host/data:/app/db \   # 持久化数据库
  --name file-organizer \
  ai-file-organizer

7.5 Caddy 反向代理配置解析

Caddyfile 中配置了两个主要规则：

:81 {
    # 动态端口转发：支持 ?XTransformPort=3001 等
    @transform_port_query {
        query XTransformPort=*
    }
    handle @transform_port_query {
        reverse_proxy localhost:{query.XTransformPort}
    }

    # 默认转发到 Next.js 3000 端口
    handle {
        reverse_proxy localhost:3000
    }
}

默认监听 81 端口，将请求转发给 Next.js 3000 端口。
支持查询参数 XTransformPort，可以临时将请求转发到其他端口（用于开发调试）。

7.6 环境变量参考

变量名	默认值	说明
`DATABASE_URL`	`file:/app/db/custom.db`	SQLite 数据库文件路径
`PORT`	`3000`	Next.js 服务端口
`HOSTNAME`	`0.0.0.0`	服务绑定地址
`NODE_ENV`	`production`	运行模式

8. 配置自定义 AI 模型

系统默认内置了一套 AI 模型（z-ai-web-dev-sdk），可以开箱即用。但如果你有自己的 API Key（比如 OpenAI、DeepSeek、通义千问等），可以添加自定义模型以获得更好的分析质量或更低的成本。

8.1 支持的提供商

在“系统设置 → 模型配置”中，选择预设提供商后会自动填充 API URL：

提供商	API URL 模板	常用模型 ID
OpenAI	`https://api.openai.com/v1`	`gpt-4o`, `gpt-4o-mini`
Azure	`https://{resource}.openai.azure.com`	`gpt-4`, `gpt-35-turbo`
DeepSeek	`https://api.deepseek.com/v1`	`deepseek-chat`
通义千问	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-plus`, `qwen-max`
智谱 AI	`https://open.bigmodel.cn/api/paas/v4`	`glm-4-flash`
Moonshot	`https://api.moonshot.cn/v1`	`moonshot-v1-8k`

8.2 配置步骤

进入 系统设置 → 模型配置 → 点击 添加模型。
选择提供商（或选择“自定义”手动填写 URL）。
填入 API Key（输入框支持显示/隐藏切换）。
选择或输入 Model ID。
选择模型类型：
- LLM：仅用于分析文本文件（文档、代码、日志等）
- VLM：仅用于分析图片文件
- Both：同时用于两者（如 GPT-4o）
（可选）设置为默认模型：新文件分析将优先使用此模型。
（可选）调整高级参数：Max Tokens（256–32768）、Temperature（0–2）。
点击 测试连接 — 系统会发送一个测试请求到 /chat/completions 端点，验证 API Key 和网络是否正常。
测试通过后点击保存。

8.3 模型切换与降级

当分析请求到达时，系统会按照以下顺序选择模型：

如果文件指定了某模型（例如通过 API 参数），使用该模型。
否则，查找用户设置的 默认模型（类型匹配：文本文件找 LLM，图片找 VLM）。
如果默认模型不可用（如配置错误、网络不通），自动降级到内置的 z-ai-web-dev-sdk。
如果内置 SDK 也失败，返回分析失败，但系统会在日志中记录详细错误信息供排查。

这种设计保证了在任何情况下你都能获得分析结果，不会因为 API Key 过期或网络问题导致功能完全不可用。

9. 关键设计决策

为什么选择 SQLite 而不是 PostgreSQL？

零运维：文件整理助手定位为本地或边缘部署的个人工具，用户不希望管理一个独立的数据库服务。SQLite 就是一个文件，备份即复制。
性能足够：对于个人文件量（几千到几万条记录），SQLite 的查询性能完全够用，配合 Prisma 的索引优化可以轻松应对。
迁移灵活：Prisma ORM 支持从 SQLite 无缝切换到 PostgreSQL，只要修改 schema.prisma 中的 datasource 即可。

为什么使用 Bun 而非 Node.js？

启动速度：Bun 的启动时间比 Node.js 快 4 倍以上，对于需要频繁重启的开发环境和冷启动的容器部署，体验提升明显。
原生 TypeScript：无需配置 ts-node 或预编译，直接运行 .ts 文件，简化脚本逻辑。
内置包管理器：bun install 的速度比 npm 或 yarn 快一个数量级。

为什么自然语言规则而不是编程式规则？

目标用户并非专业开发者。用自然语言描述整理逻辑（如“将下载文件夹中所有图片按日期归档到图片库”）比编写 JavaScript 条件语句要直观得多。同时，LLM 将自然语言解析为结构化条件后，匹配过程是确定性的、可解释的，避免了每次决策都调用 LLM 带来的不确定性和额外成本。

为什么操作必须可回滚？

文件整理涉及实际的文件系统变更，一次误操作可能导致重要文件被覆盖或丢失。通过完整的操作日志和回滚机制，用户获得了一个“安全网”：可以放心地尝试 AI 建议，如果效果不满意，一键恢复原状。这大大降低了用户对自动化整理的心理门槛。

10. 日常运维

10.1 数据库备份

SQLite 数据库是一个单文件，备份非常简单：

cp /app/db/custom.db /backup/custom_$(date +%Y%m%d_%H%M%S).db

建议通过 cron 设置每日自动备份：

0 2 * * * cp /app/db/custom.db /backup/custom_$(date +\%Y\%m\%d).db

10.2 查看服务日志

systemd：如果配置为服务，使用 journalctl -u file-organizer -f
Docker：使用 docker logs -f file-organizer
直接运行：日志会输出到终端，也可以重定向到文件

10.3 服务重启

# systemd
systemctl restart file-organizer

# Docker
docker restart file-organizer

# 直接运行（需先杀掉旧进程）
pkill -f "bun server.js" && /app/start.sh

10.4 常用诊断命令

# 1. 检查 Next.js 服务是否正常
curl -s http://localhost:3000/api/dashboard | head -c 200

# 2. 检查数据库完整性
sqlite3 /app/db/custom.db "PRAGMA integrity_check;"

# 3. 统计各状态文件数量（快速了解整理进度）
sqlite3 /app/db/custom.db "SELECT status, COUNT(*) FROM FileRecord GROUP BY status;"

# 4. 查看最近的 API 错误（如果日志中记录）
grep "ERROR" /var/log/file-organizer.log | tail -20

10.5 升级指南

当有新版本发布时，升级步骤如下：

备份数据库：cp /app/db/custom.db /backup/
停止服务：systemctl stop file-organizer
解压新版本：覆盖 /app 目录（注意不要覆盖 db/custom.db 和配置文件）
运行数据库迁移：cd /app && bun run db:push
启动服务：systemctl start file-organizer

如果使用 Docker，只需拉取新镜像并重新创建容器，挂载的数据库卷会保持不变。

结语

AI 文件整理助手不是为了取代你对文件的管理，而是成为一位不知疲倦的智能助手。它通过感知、认知、决策、执行四层流水线，将 AI 的理解能力与你定义的规则无缝结合，同时通过操作回滚和反馈机制让你始终掌握最终控制权。无论是日常下载文件夹的自动归档，还是大型项目的资料整理，你都可以从重复的手动劳动中解放出来，专注于更有创造性的工作。

现在，按照部署指南启动你的 AI 文件整理助手，让文件世界变得井然有序吧。