aihezu 2.5.0 → 2.6.1

package/bin/aihezu.js

@@ -7,7 +7,10 @@ const readline = require('readline');
 const commands = {
   install: require('../commands/install'),
   clear: require('../commands/clear'),
-  usage: require('../commands/usage')
+  usage: require('../commands/usage'),
+  backup: require('../commands/backup'),
+  recover: require('../commands/recover'),
+  reset: require('../commands/reset')
 };
 
 const services = {
@@ -22,7 +25,10 @@ function showHelp() {
   console.log('用法: aihezu <command> [service]');
   console.log('\n命令:');
   console.log('  install <service>   配置服务 (API Key, URL, 网络设置)');
-  console.log('  clear <service>     清理缓存并刷新网络设置');
+  console.log('  clear <service>     清理缓存并刷新网络设置 (自动备份)');
+  console.log('  backup <service>    手动备份配置');
+  console.log('  recover <service>   从备份恢复配置');
+  console.log('  reset <service>     重置服务配置 (删除所有配置)');
   console.log('  usage [service]     查看用量统计');
   console.log('');
   console.log('usage 命令可选参数:');
@@ -47,10 +53,13 @@ function showHelp() {
   console.log('\n示例:');
   console.log('  aihezu install claude');
   console.log('  aihezu clear codex');
-  console.log('  aihezu usage           (查看所有服务用量)');
-  console.log('  aihezu usage cc        (只查看 Claude Code 用量)');
-  console.log('  aihezu install         (交互式安装)');
-  console.log('  aihezu help            (显示帮助信息)');
+  console.log('  aihezu backup claude      (备份 Claude Code 配置)');
+  console.log('  aihezu recover claude     (恢复 Claude Code 配置)');
+  console.log('  aihezu reset claude       (重置 Claude Code 配置)');
+  console.log('  aihezu usage              (查看所有服务用量)');
+  console.log('  aihezu usage cc           (只查看 Claude Code 用量)');
+  console.log('  aihezu install            (交互式安装)');
+  console.log('  aihezu help               (显示帮助信息)');
 }
 
 async function askQuestion(rl, question) {

package/commands/backup.js

@@ -0,0 +1,48 @@
+const { createBackup, cleanOldBackups } = require('../lib/backup');
+
+async function backupCommand(service) {
+  console.log('');
+  console.log('💾 正在备份 ' + service.displayName + ' 配置...');
+  console.log('');
+
+  if (!service.cacheConfig) {
+    console.log('❌ 此服务未定义配置信息，无法备份。');
+    return;
+  }
+
+  const { dir: targetDir, items: itemsToBackup } = service.cacheConfig;
+
+  // Add settings.json to backup list if it exists
+  const allItems = [...itemsToBackup];
+  if (service.name === 'claude') {
+    allItems.push('settings.json');
+  }
+
+  // Create backup
+  const result = createBackup({
+    targetDir: targetDir,
+    itemsToBackup: allItems,
+    description: service.displayName
+  });
+
+  if (!result.success) {
+    console.log(`❌ ${result.error}`);
+    return;
+  }
+
+  // Clean old backups (keep 3 most recent)
+  console.log('');
+  const deletedCount = cleanOldBackups({
+    targetDir: targetDir,
+    keepCount: 3
+  });
+
+  if (deletedCount > 0) {
+    console.log(`\n🧹 已清理 ${deletedCount} 个旧备份`);
+  }
+
+  console.log('');
+  console.log('✅ 备份完成！');
+}
+
+module.exports = backupCommand;

package/commands/clear.js

@@ -1,23 +1,52 @@
 const { modifyHostsFile } = require('../lib/hosts');
 const { cleanCache } = require('../lib/cache');
+const { createBackup, cleanOldBackups } = require('../lib/backup');
 
 async function clearCommand(service) {
   console.log('');
   console.log('🧹 正在清理 ' + service.displayName + ' 环境...');
   console.log('');
 
-  // 1. Clean Cache
+  // 1. Create backup before clearing
+  if (service.cacheConfig) {
+    const allItems = [...service.cacheConfig.items];
+    if (service.name === 'claude') {
+      allItems.push('settings.json');
+    }
+
+    const backupResult = createBackup({
+      targetDir: service.cacheConfig.dir,
+      itemsToBackup: allItems,
+      description: service.displayName
+    });
+
+    if (backupResult.success) {
+      console.log('');
+    } else {
+      console.log(`⚠️  备份失败: ${backupResult.error}`);
+      console.log('   继续清理缓存...');
+      console.log('');
+    }
+  }
+
+  // 2. Clean Cache
   if (service.cacheConfig) {
     cleanCache({
       targetDir: service.cacheConfig.dir,
       itemsToClean: service.cacheConfig.items,
       showHeader: true
     });
+
+    // Clean old backups (keep 3 most recent)
+    cleanOldBackups({
+      targetDir: service.cacheConfig.dir,
+      keepCount: 3
+    });
   } else {
     console.log('ℹ️  此服务未定义缓存配置。');
   }
 
-  // 2. Refresh Hosts (Ensure they are still set correctly)
+  // 3. Refresh Hosts (Ensure they are still set correctly)
   if (service.hostsConfig && service.hostsConfig.length > 0) {
     console.log('');
     console.log('=== 刷新网络配置 ===');

package/commands/recover.js

@@ -0,0 +1,107 @@
+const readline = require('readline');
+const { listBackups, restoreBackup, createBackup } = require('../lib/backup');
+
+async function askQuestion(rl, question) {
+  return new Promise(resolve => rl.question(question, answer => resolve(answer.trim())));
+}
+
+async function recoverCommand(service) {
+  console.log('');
+  console.log('🔄 ' + service.displayName + ' 配置恢复');
+  console.log('');
+
+  if (!service.cacheConfig) {
+    console.log('❌ 此服务未定义配置信息，无法恢复。');
+    return;
+  }
+
+  const { dir: targetDir, items: itemsToBackup } = service.cacheConfig;
+
+  // List available backups
+  const backups = listBackups(targetDir);
+
+  if (backups.length === 0) {
+    console.log('❌ 没有找到可用的备份文件。');
+    console.log('');
+    console.log('提示: 使用 `aihezu backup ' + service.name + '` 创建备份。');
+    return;
+  }
+
+  // Display available backups
+  console.log('可用的备份:');
+  console.log('');
+  backups.forEach((backup, index) => {
+    console.log(`  [${index + 1}] ${backup.formattedDate}  (${backup.formattedSize})`);
+  });
+  console.log('');
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    // Ask user to select a backup
+    let selectedIndex = -1;
+    let validChoice = false;
+
+    while (!validChoice) {
+      const answer = await askQuestion(rl, '请选择要恢复的备份 (输入编号, 或输入 q 退出): ');
+
+      if (answer.toLowerCase() === 'q') {
+        console.log('');
+        console.log('已取消恢复操作。');
+        return;
+      }
+
+      const index = parseInt(answer, 10) - 1;
+      if (index >= 0 && index < backups.length) {
+        selectedIndex = index;
+        validChoice = true;
+      } else {
+        console.log('无效的选择，请输入列表中的数字。');
+      }
+    }
+
+    const selectedBackup = backups[selectedIndex];
+
+    // Warn user about overwriting
+    console.log('');
+    console.log('⚠️  警告: 恢复备份将覆盖当前配置！');
+    console.log('');
+    console.log('   恢复的备份: ' + selectedBackup.formattedDate);
+    console.log('   目标目录: ' + targetDir);
+    console.log('');
+    console.log('💡 建议: 在继续之前，你可以先运行 `aihezu backup ' + service.name + '` 备份当前配置。');
+    console.log('');
+
+    const confirm = await askQuestion(rl, '确认恢复? (输入 yes 确认): ');
+
+    if (confirm.toLowerCase() !== 'yes') {
+      console.log('');
+      console.log('已取消恢复操作。');
+      return;
+    }
+
+    // Restore the backup
+    const result = restoreBackup({
+      backupFile: selectedBackup.filePath,
+      targetDir: targetDir
+    });
+
+    if (!result.success) {
+      console.log(`❌ ${result.error}`);
+      return;
+    }
+
+    console.log('');
+    console.log('✅ 恢复完成！');
+    console.log('');
+    console.log('提示: 如果你使用的是 Claude Code，可能需要重启才能使配置生效。');
+
+  } finally {
+    rl.close();
+  }
+}
+
+module.exports = recoverCommand;

package/commands/reset.js

@@ -0,0 +1,131 @@
+const readline = require('readline');
+const fs = require('fs');
+const path = require('path');
+const { createBackup } = require('../lib/backup');
+
+async function askQuestion(rl, question) {
+  return new Promise(resolve => rl.question(question, answer => resolve(answer.trim())));
+}
+
+async function resetCommand(service) {
+  console.log('');
+  console.log('🔄 重置 ' + service.displayName + ' 配置');
+  console.log('');
+
+  if (!service.cacheConfig) {
+    console.log('❌ 此服务未定义配置信息，无法重置。');
+    return;
+  }
+
+  const { dir: targetDir, items: itemsToClean } = service.cacheConfig;
+
+  if (!fs.existsSync(targetDir)) {
+    console.log('ℹ️  配置目录不存在，无需重置。');
+    return;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    // Collect items that exist
+    const existingItems = [];
+    for (const item of itemsToClean) {
+      const itemPath = path.join(targetDir, item);
+      if (fs.existsSync(itemPath)) {
+        existingItems.push(item);
+      }
+    }
+
+    // Also check for settings.json
+    if (service.name === 'claude') {
+      const settingsPath = path.join(targetDir, 'settings.json');
+      if (fs.existsSync(settingsPath)) {
+        existingItems.push('settings.json');
+      }
+    }
+
+    if (existingItems.length === 0) {
+      console.log('ℹ️  没有找到需要清理的配置文件。');
+      return;
+    }
+
+    // Show what will be deleted
+    console.log('⚠️  警告: 以下配置将被永久删除:');
+    console.log('');
+    existingItems.forEach(item => {
+      const itemPath = path.join(targetDir, item);
+      const stat = fs.statSync(itemPath);
+      const type = stat.isDirectory() ? '目录' : '文件';
+      console.log(`   - ${item} (${type})`);
+    });
+    console.log('');
+    console.log('💡 建议: 在继续之前，你可以先运行 `aihezu backup ' + service.name + '` 备份当前配置。');
+    console.log('');
+
+    const shouldBackup = await askQuestion(rl, '是否先创建备份? (yes/no, 默认 yes): ');
+
+    if (shouldBackup.toLowerCase() !== 'no') {
+      console.log('');
+      const backupResult = createBackup({
+        targetDir: targetDir,
+        itemsToBackup: existingItems,
+        description: service.displayName
+      });
+
+      if (backupResult.success) {
+        console.log('');
+      } else {
+        console.log(`⚠️  备份失败: ${backupResult.error}`);
+        console.log('');
+      }
+    }
+
+    console.log('⚠️  最后确认: 确定要删除所有配置吗？此操作不可恢复！');
+    console.log('');
+    const confirm = await askQuestion(rl, '请输入 "DELETE" (大写) 确认删除: ');
+
+    if (confirm !== 'DELETE') {
+      console.log('');
+      console.log('已取消重置操作。');
+      return;
+    }
+
+    // Delete all items
+    console.log('');
+    console.log('🗑️  正在删除配置...');
+    console.log('');
+
+    let deletedCount = 0;
+    for (const item of existingItems) {
+      const itemPath = path.join(targetDir, item);
+
+      try {
+        const stat = fs.statSync(itemPath);
+
+        if (stat.isDirectory()) {
+          fs.rmSync(itemPath, { recursive: true, force: true });
+          console.log(`   ✓ 已删除目录: ${item}`);
+        } else {
+          fs.unlinkSync(itemPath);
+          console.log(`   ✓ 已删除文件: ${item}`);
+        }
+        deletedCount++;
+      } catch (e) {
+        console.log(`   ✗ 删除失败: ${item} - ${e.message}`);
+      }
+    }
+
+    console.log('');
+    console.log(`✅ 重置完成！已删除 ${deletedCount} 个项目。`);
+    console.log('');
+    console.log('提示: 使用 `aihezu install ' + service.name + '` 重新配置服务。');
+
+  } finally {
+    rl.close();
+  }
+}
+
+module.exports = resetCommand;

package/commands/usage.js

@@ -263,6 +263,54 @@ function formatPercent(current, limit) {
   return `${((c / l) * 100).toFixed(1)}%`;
 }
 
+function normalizeEpochMs(value) {
+  const n = asNumber(value);
+  if (n === null) return null;
+  return n < 1e12 ? n * 1000 : n;
+}
+
+function formatDateTime(value) {
+  const ms = normalizeEpochMs(value);
+  if (ms === null) return '-';
+  const date = new Date(ms);
+  if (Number.isNaN(date.getTime())) return '-';
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hours = String(date.getHours()).padStart(2, '0');
+  const minutes = String(date.getMinutes()).padStart(2, '0');
+  const seconds = String(date.getSeconds()).padStart(2, '0');
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+function formatDurationSeconds(value) {
+  const total = asNumber(value);
+  if (total === null) return '-';
+  let remaining = Math.max(0, Math.floor(total));
+  const days = Math.floor(remaining / 86400);
+  remaining %= 86400;
+  const hours = Math.floor(remaining / 3600);
+  remaining %= 3600;
+  const minutes = Math.floor(remaining / 60);
+  const seconds = remaining % 60;
+
+  const parts = [];
+  if (days) parts.push(`${days} 天`);
+  if (hours) parts.push(`${hours} 小时`);
+  if (minutes) parts.push(`${minutes} 分`);
+  if (seconds || parts.length === 0) parts.push(`${seconds} 秒`);
+  return parts.join(' ');
+}
+
+function formatDurationMinutes(value) {
+  const minutes = asNumber(value);
+  if (minutes === null || minutes <= 0) return '-';
+  const human = formatDurationSeconds(minutes * 60);
+  if (human === '-') return '-';
+  const minuteText = Number.isInteger(minutes) ? String(minutes) : minutes.toFixed(2);
+  return `${human} (${minuteText} 分钟)`;
+}
+
 function renderBar(current, limit, width = 18) {
   const c = asNumber(current);
   const l = asNumber(limit);
@@ -326,6 +374,27 @@ function displayUsageStats(stats, origin, source) {
   const dailyCostLimit = (stats.dailyCostLimit !== undefined) ? stats.dailyCostLimit : limits.dailyCostLimit;
   const currentWindowCost = (stats.currentWindowCost !== undefined) ? stats.currentWindowCost : limits.currentWindowCost;
   const rateLimitCost = (stats.rateLimitCost !== undefined) ? stats.rateLimitCost : limits.rateLimitCost;
+  const windowStartTime = (stats.windowStartTime !== undefined) ? stats.windowStartTime : limits.windowStartTime;
+  const windowEndTime = (stats.windowEndTime !== undefined) ? stats.windowEndTime : limits.windowEndTime;
+  const windowRemainingSeconds = (() => {
+    const raw = (stats.windowRemainingSeconds !== undefined)
+      ? stats.windowRemainingSeconds
+      : limits.windowRemainingSeconds;
+    const provided = asNumber(raw);
+    if (provided !== null) return provided;
+    const endMs = normalizeEpochMs(windowEndTime);
+    if (endMs === null) return null;
+    return Math.max(0, Math.floor((endMs - Date.now()) / 1000));
+  })();
+  const windowDurationMinutes = (() => {
+    const raw = (stats.rateLimitWindow !== undefined) ? stats.rateLimitWindow : limits.rateLimitWindow;
+    const minutes = asNumber(raw);
+    if (minutes !== null) return minutes;
+    const startMs = normalizeEpochMs(windowStartTime);
+    const endMs = normalizeEpochMs(windowEndTime);
+    if (startMs === null || endMs === null || endMs <= startMs) return null;
+    return Math.round((endMs - startMs) / 60000);
+  })();
 
   const dailyRemaining = (() => {
     const c = asNumber(currentDailyCost);
@@ -360,6 +429,25 @@ function displayUsageStats(stats, origin, source) {
   if (windowRemaining !== null) {
     console.log(`窗口剩余: ${formatCost(windowRemaining)}`);
   }
+  const windowStartText = formatDateTime(windowStartTime);
+  const windowEndText = formatDateTime(windowEndTime);
+  if (windowStartText !== '-' || windowEndText !== '-') {
+    if (windowStartText !== '-' && windowEndText !== '-') {
+      console.log(`时间窗口: ${windowStartText} ~ ${windowEndText}`);
+    } else if (windowStartText !== '-') {
+      console.log(`时间窗口开始: ${windowStartText}`);
+    } else {
+      console.log(`时间窗口结束: ${windowEndText}`);
+    }
+  }
+  const windowDurationText = formatDurationMinutes(windowDurationMinutes);
+  if (windowDurationText !== '-') {
+    console.log(`周时间窗口: ${windowDurationText}`);
+  }
+  const resetCountdownText = formatDurationSeconds(windowRemainingSeconds);
+  if (resetCountdownText !== '-') {
+    console.log(`距离重置: ${resetCountdownText}`);
+  }
   console.log('');
 }
 

package/lib/backup.js

@@ -0,0 +1,237 @@
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { getLocalTimestamp } = require('./cache');
+
+/**
+ * Create a tar.gz backup of files/directories
+ * @param {Object} options - Backup options
+ * @param {string} options.targetDir - The directory containing items to backup
+ * @param {Array<string>} options.itemsToBackup - Items to backup (files or directories)
+ * @param {string} options.description - Description for logging
+ * @returns {Object} - { success: boolean, backupFile: string, error: string }
+ */
+function createBackup(options = {}) {
+  const { targetDir, itemsToBackup = [], description = '配置' } = options;
+
+  if (!targetDir || !fs.existsSync(targetDir)) {
+    return {
+      success: false,
+      error: `目录不存在: ${targetDir}`
+    };
+  }
+
+  if (itemsToBackup.length === 0) {
+    return {
+      success: false,
+      error: '没有指定要备份的项目'
+    };
+  }
+
+  const timestamp = getLocalTimestamp();
+  const backupFileName = `backup-${timestamp}.tar.gz`;
+  const backupFilePath = path.join(targetDir, backupFileName);
+
+  console.log(`\n📦 正在创建备份...`);
+  console.log(`   备份目录: ${targetDir}`);
+
+  try {
+    // Collect items that actually exist
+    const existingItems = [];
+    for (const item of itemsToBackup) {
+      const itemPath = path.join(targetDir, item);
+      if (fs.existsSync(itemPath)) {
+        existingItems.push(item);
+        const stat = fs.statSync(itemPath);
+        const type = stat.isDirectory() ? '目录' : '文件';
+        console.log(`   - ${item} (${type})`);
+      }
+    }
+
+    if (existingItems.length === 0) {
+      return {
+        success: false,
+        error: '没有找到可以备份的项目'
+      };
+    }
+
+    // Create tar.gz with all items
+    const itemsArg = existingItems.map(item => `'${item}'`).join(' ');
+    const tarCommand = process.platform === 'win32'
+      ? `tar -czf "${backupFilePath}" -C "${targetDir}" ${existingItems.map(i => `"${i}"`).join(' ')}`
+      : `tar -czf '${backupFilePath}' -C '${targetDir}' ${itemsArg}`;
+
+    execSync(tarCommand, { stdio: 'pipe' });
+
+    console.log(`\n✅ 备份创建成功: ${backupFileName}`);
+
+    return {
+      success: true,
+      backupFile: backupFilePath,
+      backupFileName: backupFileName
+    };
+
+  } catch (e) {
+    return {
+      success: false,
+      error: `备份失败: ${e.message}`
+    };
+  }
+}
+
+/**
+ * List all available backups in a directory
+ * @param {string} targetDir - Directory to search for backups
+ * @returns {Array} - Array of backup objects sorted by timestamp (newest first)
+ */
+function listBackups(targetDir) {
+  if (!targetDir || !fs.existsSync(targetDir)) {
+    return [];
+  }
+
+  try {
+    const items = fs.readdirSync(targetDir);
+    const backups = [];
+
+    for (const item of items) {
+      // Match pattern: backup-YYYYMMDDHHMMSS.tar.gz
+      const match = item.match(/^backup-(\d{14})\.tar\.gz$/);
+
+      if (match) {
+        const timestamp = match[1];
+        const itemPath = path.join(targetDir, item);
+        const stat = fs.statSync(itemPath);
+
+        // Format timestamp for display: YYYY-MM-DD HH:MM:SS
+        const year = timestamp.substring(0, 4);
+        const month = timestamp.substring(4, 6);
+        const day = timestamp.substring(6, 8);
+        const hour = timestamp.substring(8, 10);
+        const minute = timestamp.substring(10, 12);
+        const second = timestamp.substring(12, 14);
+        const formattedDate = `${year}-${month}-${day} ${hour}:${minute}:${second}`;
+
+        backups.push({
+          fileName: item,
+          filePath: itemPath,
+          timestamp: timestamp,
+          formattedDate: formattedDate,
+          size: stat.size,
+          formattedSize: formatBytes(stat.size)
+        });
+      }
+    }
+
+    // Sort by timestamp descending (newest first)
+    backups.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+    return backups;
+
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * Restore a backup file
+ * @param {Object} options - Restore options
+ * @param {string} options.backupFile - Path to the backup file
+ * @param {string} options.targetDir - Directory to restore to
+ * @returns {Object} - { success: boolean, error: string }
+ */
+function restoreBackup(options = {}) {
+  const { backupFile, targetDir } = options;
+
+  if (!backupFile || !fs.existsSync(backupFile)) {
+    return {
+      success: false,
+      error: `备份文件不存在: ${backupFile}`
+    };
+  }
+
+  if (!targetDir || !fs.existsSync(targetDir)) {
+    return {
+      success: false,
+      error: `目标目录不存在: ${targetDir}`
+    };
+  }
+
+  console.log(`\n🔄 正在恢复备份...`);
+  console.log(`   备份文件: ${path.basename(backupFile)}`);
+  console.log(`   恢复目录: ${targetDir}`);
+
+  try {
+    // Extract tar.gz to target directory
+    const tarCommand = process.platform === 'win32'
+      ? `tar -xzf "${backupFile}" -C "${targetDir}"`
+      : `tar -xzf '${backupFile}' -C '${targetDir}'`;
+
+    execSync(tarCommand, { stdio: 'pipe' });
+
+    console.log(`\n✅ 备份恢复成功`);
+
+    return {
+      success: true
+    };
+
+  } catch (e) {
+    return {
+      success: false,
+      error: `恢复失败: ${e.message}`
+    };
+  }
+}
+
+/**
+ * Clean old backups, keeping only the most recent N backups
+ * @param {Object} options - Clean options
+ * @param {string} options.targetDir - Directory containing backups
+ * @param {number} options.keepCount - Number of recent backups to keep (default: 3)
+ * @returns {number} - Number of backups deleted
+ */
+function cleanOldBackups(options = {}) {
+  const { targetDir, keepCount = 3 } = options;
+
+  if (!targetDir || !fs.existsSync(targetDir)) {
+    return 0;
+  }
+
+  const backups = listBackups(targetDir);
+
+  if (backups.length <= keepCount) {
+    return 0;
+  }
+
+  const backupsToDelete = backups.slice(keepCount);
+  let deletedCount = 0;
+
+  for (const backup of backupsToDelete) {
+    try {
+      console.log(`🗑️  删除旧备份: ${backup.fileName}`);
+      fs.unlinkSync(backup.filePath);
+      deletedCount++;
+    } catch (e) {
+      console.log(`⚠️  删除备份失败: ${e.message}`);
+    }
+  }
+
+  return deletedCount;
+}
+
+/**
+ * Format bytes to human readable format
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return Math.round(bytes / Math.pow(k, i) * 100) / 100 + ' ' + sizes[i];
+}
+
+module.exports = {
+  createBackup,
+  listBackups,
+  restoreBackup,
+  cleanOldBackups
+};

package/lib/cache.js

@@ -1,6 +1,7 @@
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
+const { execSync } = require('child_process');
 
 // Generate local timestamp: YYYYMMDDHHMMSS
 function getLocalTimestamp() {
@@ -14,6 +15,27 @@ function getLocalTimestamp() {
   return `${year}${month}${day}${hours}${minutes}${seconds}`;
 }
 
+// Create a tar.gz archive of a file or directory
+function createTarGzBackup(sourcePath, backupPath) {
+  const sourceDir = path.dirname(sourcePath);
+  const sourceName = path.basename(sourcePath);
+  const backupFile = `${backupPath}.tar.gz`;
+
+  try {
+    // Use tar command to create compressed archive
+    // -czf: create gzip compressed archive
+    // -C: change to directory before operation
+    const tarCommand = process.platform === 'win32'
+      ? `tar -czf "${backupFile}" -C "${sourceDir}" "${sourceName}"`
+      : `tar -czf '${backupFile}' -C '${sourceDir}' '${sourceName}'`;
+
+    execSync(tarCommand, { stdio: 'pipe' });
+    return backupFile;
+  } catch (e) {
+    throw new Error(`打包失败: ${e.message}`);
+  }
+}
+
 function cleanCache(options = {}) {
   const { 
     targetDir, 
@@ -43,7 +65,7 @@ function cleanCache(options = {}) {
     try {
       if (fs.existsSync(itemPath)) {
         const stat = fs.statSync(itemPath);
-        const backupPath = `${itemPath}-backup-${timestamp}`;
+        const backupBasePath = `${itemPath}-backup-${timestamp}`;
 
         if (stat.isDirectory()) {
           console.log(`📦 备份并清理目录: ${item}/`);
@@ -51,7 +73,17 @@ function cleanCache(options = {}) {
           console.log(`📦 备份并清理文件: ${item}`);
         }
 
-        fs.renameSync(itemPath, backupPath);
+        // Create tar.gz backup
+        const backupFile = createTarGzBackup(itemPath, backupBasePath);
+        console.log(`   ✓ 已打包为: ${path.basename(backupFile)}`);
+
+        // Remove original after successful backup
+        if (stat.isDirectory()) {
+          fs.rmSync(itemPath, { recursive: true, force: true });
+        } else {
+          fs.unlinkSync(itemPath);
+        }
+
         cleanedCount++;
       }
     } catch (e) {
@@ -59,24 +91,61 @@ function cleanCache(options = {}) {
     }
   }
 
-  // Clean old backups (generic logic: starting with 'backup-' or hidden backups)
+  // Clean old backups (keep only the 3 most recent backups)
   try {
     const items = fs.readdirSync(targetDir);
+    const backupItems = [];
+
+    // Collect all backup items with their timestamps
     for (const item of items) {
-      // Logic for backups: usually we renamed them to 'name-backup-timestamp'
-      // Or if the original logic was specific: '.claude-*' or 'backup-*'
-      // Let's stick to generic 'backup-*' or if the file ends with '-backup-\d+'
-      
-      const isBackup = item.startsWith('backup-') || /backup-\d{14}$/.test(item);
+      // Match pattern: *-backup-YYYYMMDDHHMMSS.tar.gz
+      const match = item.match(/^(.+)-backup-(\d{14})\.tar\.gz$/);
 
-      if (isBackup) {
+      if (match) {
+        const [, baseName, backupTimestamp] = match;
         const itemPath = path.join(targetDir, item);
-        const stat = fs.statSync(itemPath);
 
-        if (stat.isDirectory()) {
-          console.log(`🗑️  删除旧备份: ${item}/`);
-          fs.rmSync(itemPath, { recursive: true, force: true });
+        try {
+          const stat = fs.statSync(itemPath);
+          backupItems.push({
+            name: item,
+            baseName: baseName,
+            timestamp: backupTimestamp,
+            path: itemPath,
+            isFile: stat.isFile()
+          });
+        } catch (e) {
+          // Skip if stat fails
+        }
+      }
+    }
+
+    // Group backups by base name
+    const backupGroups = {};
+    for (const backup of backupItems) {
+      if (!backupGroups[backup.baseName]) {
+        backupGroups[backup.baseName] = [];
+      }
+      backupGroups[backup.baseName].push(backup);
+    }
+
+    // For each group, keep only the 3 most recent backups
+    for (const baseName in backupGroups) {
+      const group = backupGroups[baseName];
+
+      // Sort by timestamp descending (newest first)
+      group.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+      // Delete backups beyond the 3 most recent
+      const backupsToDelete = group.slice(3);
+
+      for (const backup of backupsToDelete) {
+        try {
+          console.log(`🗑️  删除旧备份: ${backup.name}`);
+          fs.unlinkSync(backup.path);
           cleanedCount++;
+        } catch (e) {
+          console.log(`⚠️  删除备份 ${backup.name} 时出错: ${e.message}`);
         }
       }
     }

package/lib/permissions.js

@@ -0,0 +1,105 @@
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+/**
+ * Fix file/directory permissions when running with sudo
+ * This ensures files are owned by the actual user, not root
+ *
+ * @param {string|string[]} paths - File or directory path(s) to fix
+ * @returns {boolean} - Whether permissions were fixed
+ */
+function fixPermissions(paths) {
+  // Check if running with sudo
+  const isSudo = process.getuid && process.getuid() === 0;
+
+  if (!isSudo) {
+    // Not running with sudo, no need to fix permissions
+    return false;
+  }
+
+  // Get the real user who invoked sudo
+  const realUser = process.env.SUDO_USER;
+
+  if (!realUser) {
+    console.log('⚠️  警告: 以 root 权限运行，但无法确定真实用户。');
+    console.log('   配置文件可能需要手动修改权限。');
+    return false;
+  }
+
+  // Get the real user's UID and GID
+  let uid, gid;
+  try {
+    const userInfo = execSync(`id -u ${realUser}`, { encoding: 'utf8' }).trim();
+    const groupInfo = execSync(`id -g ${realUser}`, { encoding: 'utf8' }).trim();
+    uid = parseInt(userInfo, 10);
+    gid = parseInt(groupInfo, 10);
+  } catch (e) {
+    console.log(`⚠️  警告: 无法获取用户 ${realUser} 的 UID/GID`);
+    return false;
+  }
+
+  // Convert single path to array for uniform processing
+  const pathArray = Array.isArray(paths) ? paths : [paths];
+
+  let fixedCount = 0;
+
+  for (const itemPath of pathArray) {
+    if (!fs.existsSync(itemPath)) {
+      continue;
+    }
+
+    try {
+      // Fix ownership recursively for directories
+      const stat = fs.statSync(itemPath);
+
+      if (stat.isDirectory()) {
+        // Recursively fix directory and all its contents
+        fixDirectoryOwnership(itemPath, uid, gid);
+        fixedCount++;
+      } else {
+        // Fix file ownership
+        fs.chownSync(itemPath, uid, gid);
+        fixedCount++;
+      }
+    } catch (e) {
+      console.log(`⚠️  无法修改 ${itemPath} 的权限: ${e.message}`);
+    }
+  }
+
+  if (fixedCount > 0) {
+    console.log(`\n🔧 已修复文件权限 (所有者: ${realUser})`);
+  }
+
+  return fixedCount > 0;
+}
+
+/**
+ * Recursively fix directory ownership
+ */
+function fixDirectoryOwnership(dirPath, uid, gid) {
+  // Fix the directory itself
+  fs.chownSync(dirPath, uid, gid);
+
+  // Fix all contents
+  const items = fs.readdirSync(dirPath);
+
+  for (const item of items) {
+    const itemPath = require('path').join(dirPath, item);
+
+    try {
+      const stat = fs.lstatSync(itemPath); // Use lstatSync to handle symlinks
+
+      if (stat.isDirectory()) {
+        fixDirectoryOwnership(itemPath, uid, gid);
+      } else {
+        fs.chownSync(itemPath, uid, gid);
+      }
+    } catch (e) {
+      // Skip items that can't be accessed
+    }
+  }
+}
+
+module.exports = {
+  fixPermissions
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aihezu",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "AI 开发环境配置工具 - 支持 Claude Code, Codex, Google Gemini 的本地化配置、代理设置与缓存清理",
   "main": "bin/aihezu.js",
   "bin": {

package/services/claude.js

@@ -1,6 +1,7 @@
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
+const { fixPermissions } = require('../lib/permissions');
 
 const homeDir = os.homedir();
 const configDir = path.join(homeDir, '.claude');
@@ -58,7 +59,10 @@ module.exports = {
 
     // Write file
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
-    
+
+    // Fix permissions if running with sudo
+    fixPermissions([configDir, settingsPath]);
+
     return [settingsPath];
   }
 };

package/services/codex.js

@@ -1,6 +1,7 @@
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
+const { fixPermissions } = require('../lib/permissions');
 
 const homeDir = os.homedir();
 const configDir = path.join(homeDir, '.codex');
@@ -114,6 +115,9 @@ module.exports = {
     authData.AIHEZU_OAI_KEY = apiKey;
     fs.writeFileSync(authPath, JSON.stringify(authData, null, 2), 'utf8');
 
+    // Fix permissions if running with sudo
+    fixPermissions([configDir, configPath, authPath]);
+
     return [configPath, authPath];
   }
 };

package/services/gemini.js

@@ -1,6 +1,7 @@
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
+const { fixPermissions } = require('../lib/permissions');
 
 const homeDir = os.homedir();
 const configDir = path.join(homeDir, '.gemini');
@@ -39,7 +40,7 @@ module.exports = {
     fs.writeFileSync(envFilePath, envContent, 'utf8');
 
         const configFiles = [envFilePath];
-    
+
         // 2. Conditionally write settings.json only if options are provided
         if (Object.keys(options).length > 0) {
           const settings = {
@@ -48,6 +49,9 @@ module.exports = {
           fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
           configFiles.push(settingsPath);
         }
-        
+
+        // Fix permissions if running with sudo
+        fixPermissions([configDir, ...configFiles]);
+
         return configFiles;  }
 };