1. 背景与痛点
在 IT 工程交付、政府项目或大型企业管理中，"资料归档" 往往是项目收尾阶段最令人头秃的环节。
C:\myApp\project-archive
场景通常是这样的：
- 原始文件一团糟 ：你手里有一个几百兆的文件夹，里面堆满了 PDF、扫描件、Word 文档，文件名五花八门（例如
2024-10-12 会议记录_最终版.pdf）。 - 归档要求极严格 ：客户给了你十几个 Word 文档（案卷目录），每个文档里有一个表格，规定了该案卷必须包含哪些文件，而且必须重命名为标准格式（例如
01-01 项目会议纪要.pdf）。 - 人工耗时极长：传统的做法是人工逐个打开文件看内容，然后去目录里找对应项，重命名，拖进去......几百个文件需要耗费数天，且极易出错。
解决思路：
能不能写个程序，让它像人一样"看懂"文件名，自动跟目录里的标题配对？
答案是肯定的。通过结合 Node.js 的文件处理能力与 DeepSeek LLM（大语言模型） 的语义理解能力，我们构建了一套自动化归档系统。
2. 系统架构设计
为了确保工具在实际工程中落地（可用、稳定、抗造），我们经历了从"全云端处理"到"本地+云端混合"的架构演进。
核心流程
- 输入：用户上传多个"案卷目录" Word 文件 (.docx)。
- 扫描：后端自动扫描本地磁盘的一个指定文件夹（存放所有杂乱的原始文件）。
- 解析：提取 Word 文档中表格的"序号"和"标准题名"。
- 思考（AI Agent） ：将"原始文件名列表"和"标准题名列表"发送给 DeepSeek API，让 AI 进行模糊语义匹配。
- 执行：根据 AI 的匹配结果，自动复制文件、重命名、分类存放到对应文件夹。
- 生成：自动生成符合档案局标准的"案卷封面"和"卷内目录" Word 文档。
- 输出：打包成 ZIP 供用户下载。
技术栈
- Runtime: Node.js (Express)
- AI Engine: DeepSeek V3 (via API)
- Word Process :
mammoth(读取内容),docxtemplater(生成模版) - File System :
fs-extra(增强的文件操作)
3. 核心代码深度解析
让我们通过分析 server.js 的关键逻辑，来看看这个系统是如何运转的。
3.1 启动自检与目录"防崩"设计
在早期的版本中，用户经常遇到 ENOENT 错误，原因是上传目录不存在。我们在系统启动时加入了强制自检：
javascript
// server.js 片段
const BASE_UPLOAD_DIR = path.join(__dirname, 'uploads');
const DOCX_UPLOAD_DIR = path.join(BASE_UPLOAD_DIR, 'docx_temp');
const RAW_FILE_DIR = path.join(BASE_UPLOAD_DIR, 'temp');
// 核心优化：启动即创建目录，防止找不到文件夹报错
fs.ensureDirSync(DOCX_UPLOAD_DIR);
fs.ensureDirSync(RAW_FILE_DIR);设计意图 ：利用 fs-extra 的 ensureDirSync，确保无论部署在什么环境，程序运行的第一秒，所有必要的基础设施都已就绪。
3.2 解析 Word 表格（提取归档需求）
Word 文档本质是 XML，直接解析很痛苦。我们使用 mammoth 将 Word 转为 HTML，再用 cheerio（类似 jQuery）提取表格数据。
javascript
// 解析目录 DOCX
const { value: html } = await mammoth.convertToHtml({ path: docFile.path });
const $ = cheerio.load(html);
$('table tr').each((i, elem) => {
// 提取表格列
const cols = $(elem).find('td').map((j, td) => $(td).text().trim()).get();
// 启发式校验：第一列是数字才认为是有效数据行
if (cols.length >= 3 && /^\d+$/.test(cols[0])) {
items.push({
seq: cols[0], // 序号
title: cols[3], // 题名 (这是我们要去匹配的目标)
// ...其他元数据
});
}
});设计意图：这种方式比直接解析 XML 更具容错性，即使 Word 表格格式稍微不规范，只要它是 HTML 表格结构，就能读取。
3.3 AI 大脑：DeepSeek 语义匹配
这是本系统的灵魂。传统的正则匹配（Regex）无法处理文件名差异（如"合同扫描件" vs "咨询服务合同"）。而 LLM 天生擅长这个。
javascript
async function callDeepSeekMatcher(rawFiles, targetItems) {
// Prompt 工程：明确任务、输入和输出格式
const prompt = `
任务：文件匹配。
【原始文件名】: ${JSON.stringify(rawFiles)}
【标准标题】: ${JSON.stringify(targetItems.map(t => ({ id: t.id, title: t.title })))}
请根据语义将标准标题与原始文件名配对。
要求：
1. 忽略日期格式差异、版本号差异。
2. 返回 JSON 格式: {"目标ID": "原始文件名"}。
`;
const response = await axios.post(DEEPSEEK_API_URL, {
model: "deepseek-chat",
messages: [{ role: "user", content: prompt }],
response_format: { type: "json_object" } // 强制 JSON 输出
}, ...);
return JSON.parse(response.data.choices[0].message.content);
}亮点 ：我们利用了 DeepSeek 的 json_object 模式，确保 AI 返回的不是闲聊，而是机器可读的结构化数据。
3.4 自动化执行与容错
拿到 AI 的匹配结果后，Node.js 开始搬运文件。这里处理了几个关键的工程问题：
- 文件缺失处理 ：如果 AI 没找到文件，生成一个
.txt占位符，提示人工后续补充。 - 非法字符清洗 ：Windows 文件名不支持
\ / : * ? " < > |，代码中自动替换为下划线。 - 格式强校验 ：严厉拒绝老旧的
.doc格式，避免解析器崩溃。
javascript
if (matchedName) {
// 构造标准化文件名：01-01 标准题名.pdf
const safeTitle = item.title.replace(/[\\/:*?"<>|]/g, '_');
const finalName = `${volNum}-${seqNum} ${safeTitle}${ext}`;
await fs.copy(srcFile.fullPath, path.join(targetFolder, finalName));
} else {
// 优雅降级：生成缺失提示文件
await fs.writeFile(path.join(targetFolder, `【缺失】${item.title}.txt`), "AI未找到匹配文件");
}4. 踩坑与填坑记录
在开发过程中，我们解决了几类典型问题，这些经验非常宝贵：
4.1 ZIP 乱码与上传超时
- 问题：最初允许用户上传几百兆的 ZIP 包。结果导致 Nginx 超时，且 Windows 上传的 ZIP 解压后中文全是乱码（GBK vs UTF-8 问题）。
- 解决：改为**"本地目录扫描模式"**。用户只需将原始文件解压到服务器指定目录，网页端只上传轻量的 Word 目录文件。既解决了乱码，又秒传秒开。
4.2 .doc vs .docx 的噩梦
- 问题 ：用户上传了老版本的
.doc文件，后端报错Can't find end of central directory。 - 原因 ：
.doc是二进制文件，.docx是 ZIP 包。Node.js 的现代库大多只支持 ZIP 结构的 Office 文档。 - 解决 ：在后端增加严格的文件扩展名校验，遇到
.doc直接抛出友好的错误提示，要求用户另存为.docx。
4.3 临时文件夹丢失 (ENOENT)
- 问题 ：
multer不会自动创建上传目录，导致首次运行直接崩溃。 - 解决 ：引入
fs.ensureDirSync，在应用启动层解决环境依赖。
5. 运行界面
