添加注释

src/utils/fileStore.ts

@@ -36,12 +36,14 @@ export const atomicWriteFileWithHistory = async (
 
   let backupPath: string | null = null;
   if (previous !== null) {
+    // 仅在覆盖已有文件时保留历史版本，避免为首次创建产生空备份。
     backupPath = buildHistoryBackupPath(path, options);
     await atomicWriteFile(backupPath, previous);
   }
 
   try {
     await atomicWriteFile(path, content);
+    // 给调用方预留一个写后钩子；若后续步骤失败，这里仍会回滚到旧内容。
     await options.afterWrite?.();
   } catch (error) {
     try {
@@ -158,6 +160,7 @@ const buildHistoryBackupPath = (path: string, options: HistoricalWriteOptions) =
   const relativePath = relative(options.rootDir, path);
   const scopedPath =
     relativePath && !relativePath.startsWith("..") ? relativePath : basename(path);
+  // 备份目录尽量复用原始相对路径，便于按业务目录回看历史。
   const backupName = `${basename(path)}.${Date.now().toString(36)}.bak`;
   return join(options.historyDir, dirname(scopedPath), backupName);
 };