@hjj345345/all-files-backup-tool

v1.1.5

Published

3 months ago

通用文件/文件夹备份工具 —— 支持命令行交互、MCP 服务、Skill 三种使用形态

0High
0Medium
0Low

hjj345

backup cli mcp zip archive file-backup

All Files Backup Tool

通用文件/文件夹备份工具 —— 支持 CLI 命令行交互、MCP 服务、Skill 调用 三种形态

基于参考项目 auto-backup-openclaw-user-data 二次改造，采用三层分层架构，核心业务逻辑与使用形态彻底解耦。

简介

把任意文件/文件夹打包压缩备份，支持：

终端勾选式选择备份目标（含隐藏文件，@inquirer/prompts 原生分页，不闪跳）
合并压缩（全部打包成一个 zip）/ 分开压缩（每个目标各一个 zip）
可开关的排除策略（node_modules/.git/锁文件等，支持 glob 自定义）
智能处理锁文件（被占用/无权限的自动跳过并记录）
命令行实时进度条（6 阶段：校验→收集→压缩→清理→通知→完成）
ZIP 压缩（level 9）+ 可选 AES-256 加密
命名规则：自动模式（前缀默认使用目标原名）或模板占位符自定义
备份结束显示未备份/跳过的文件列表
保留策略（按份数/按天数自动清理旧备份）
Windows/Mac 桌面系统通知
斜杠命令体系：/backup_now /backup_list /backup_clean /backup_status /backup_config /backup_help

架构（三层）

┌─────────────────────────────────────────────┐
│  接入层 Adapters                             │
│  ├─ adapters/cli/   终端交互 (@inquirer/prompts) │
│  ├─ adapters/mcp/   MCP Server               │
│  └─ SKILL.md        Skill 描述               │
├─────────────────────────────────────────────┤
│  服务层 Core Service                         │
│  BackupService.run(options) → Result         │
├─────────────────────────────────────────────┤
│  领域模块 Modules                            │
│  config logger scanner collector archiver    │
│  namer cleaner notifier                      │
└─────────────────────────────────────────────┘

三形态共享同一套核心 BackupService.run(options)。

安装

方式一：npm 全局安装（推荐，CLI 用户）

npm install -g @hjj345345/all-files-backup-tool
afbackup                              # 任意目录下直接运行
afbackup update                       # 升级到最新版本

方式二：源码运行（开发者）

git clone <仓库地址>
cd all-files-backup-tool
npm install
node bin/afbackup.js

要求 Node.js ≥ 18。

快速开始

1. 交互式向导（推荐）

afbackup

按提示输入源目录 → 勾选条目 → 配置排除/加密/命名/输出 → 确认执行。

2. 非交互模式（脚本/Agent 调用）

afbackup --files D:/myproject,D:/notes.txt --out D:/bak --prefix proj --json

3. 带加密

afbackup --dir D:/myproject --encrypt --password "yourPassword" --label nightly

命令行选项

| 选项 | 说明 | |------|------| | --dir <path> | 指定要扫描的源目录 | | --files <list> | 非交互：逗号分隔的文件/文件夹路径 | | --out <path> | 输出目录（默认 ./backups） | | --merge / --split | 合并压缩（默认）/ 分开压缩（每个目标各一个 zip） | | --prefix <name> | 文件名前缀（不填默认用目标原名） | | --label <text> | 文件名标签 | | --template <tpl> | 自定义命名模板 | | --encrypt / --no-encrypt | 启用/关闭 AES-256 加密 | | --password <pw> | 加密密码（不填则自动生成 16 位随机密码） | | --no-exclude | 关闭排除策略 | | --no-notify | 关闭桌面通知 | | --no-retention | 关闭保留策略清理 | | --json | 以 JSON 输出结果 | | --help / --version | 帮助/版本 |

子命令

| 命令 | 功能 | |------|------| | afbackup | 交互式备份向导（默认） | | afbackup backup | 开始备份 | | afbackup list | 列出备份文件 | | afbackup clean | 清理旧备份 | | afbackup status | 查看备份状态与配置 | | afbackup config | 查看/重置配置 | | afbackup update | 升级到最新版本（交互确认） | | afbackup help | 帮助信息 |

斜杠命令（Skill 模式）

| 命令 | 映射 | |------|------| | /backup_now | node bin/afbackup.js | | /backup_now --files <路径> | node bin/afbackup.js --files <路径> | | /backup_list | node bin/afbackup.js list | | /backup_clean | node bin/afbackup.js clean | | /backup_status | node bin/afbackup.js status | | /backup_config | node bin/afbackup.js config | | /backup_help | node bin/afbackup.js help |

命名模板占位符

| 占位符 | 含义 | 示例 | |--------|------|------| | {prefix} | 前缀 | backup | | {date} | 日期 | 20260620 | | {time} | 时间 | 1504 | | {datetime} | 日期_时间 | 20260620_1504 | | {seq} | 当日序号 | 01 | | {label} | 自定义标签 | nightly | | {host} | 主机名 | DESKTOP-XXX |

自动模式：{prefix}_{date}_{time}_{seq}.zip 示例：sm-to-do-list_20260620_1504_01.zip（前缀自动取目标原名）

MCP 服务

在 Agent 的 MCP 配置中加入，三种方式任选其一：

方式一：npx 即用即走（推荐，无需安装）

{
  "mcpServers": {
    "all-files-backup": {
      "command": "npx",
      "args": ["-y", "-p", "@hjj345345/all-files-backup-tool", "afbackup-mcp"]
    }
  }
}

方式二：全局安装后直接使用

npm install -g @hjj345345/all-files-backup-tool

{
  "mcpServers": {
    "all-files-backup": {
      "command": "afbackup-mcp"
    }
  }
}

方式三：源码运行

{
  "mcpServers": {
    "all-files-backup": {
      "command": "node",
      "args": ["<项目路径>/bin/afbackup-mcp.js"]
    }
  }
}

暴露工具：

scan_dir — 扫描目录列出条目（预览）
run_backup — 执行备份（入参即 options）

Skill 调用

Agent 读取 SKILL.md 后，可直接使用斜杠命令（映射到 CLI）：

/backup_now → node bin/afbackup.js（交互式）或 node bin/afbackup.js --files <path> --json
/backup_list → node bin/afbackup.js list
/backup_clean → node bin/afbackup.js clean
/backup_status → node bin/afbackup.js status
/backup_config → node bin/afbackup.js config
/backup_help → node bin/afbackup.js help

详见 SKILL.md。

配置文件

位置：~/.all-files-backup-tool/config.json（首次运行自动创建）。模板见 templates/config.template.json。

项目结构

all-files-backup-tool/
├── package.json
├── README.md
├── SKILL.md
├── .gitignore
├── bin/
│   ├── afbackup.js          # CLI 入口
│   └── afbackup-mcp.js      # MCP 入口
├── src/
│   ├── index.js             # 统一导出
│   ├── core/                # 服务层 + 领域模块
│   │   ├── backup-service.js
│   │   ├── config.js
│   │   ├── logger.js
│   │   ├── scanner.js
│   │   ├── collector.js
│   │   ├── archiver.js
│   │   ├── namer.js
│   │   ├── cleaner.js
│   │   └── notifier.js
│   └── adapters/            # 接入层
│       ├── cli/
│       │   ├── wizard.js
│       │   ├── commands.js
│       │   └── args.js
│       └── mcp/
│           └── server.js
└── templates/
    └── config.template.json

解密说明

加密文件（AES-256）需用 7-Zip / WinRAR / PeaZip 解压并输入密码；系统原生解压不支持。 密码务必妥善保存，丢失无法恢复。

许可证

MIT