data-backup

集成技能的智能备份系统

此目录中的支持文件：

• MANIFEST_BACKUPS.md —— 支持 MANIFEST 的智能备份
• FULL_PROJECT_BACKUPS.md —— 完整项目备份、选择性纳入或排除、路径验证
• ADVANCED_USAGE.md —— 自定义脚本、多个文件备份、实际示例

何时使用此技能

在以下情况下使用此技能：

• 处理文件会随时间变化的任何项目
• 处理 Jupyter 笔记本、数据文件（CSV/TSV）、HackMD 演示文稿或混合项目
• 需要在备份前进行智能清理（清除输出、移除调试代码）
• 想要追踪何时发生了哪些更改（数据溯源）
• 需要用于协作或发布的专业备份工作流
• 希望通过智能调用其他技能，实现上下文感知的备份

问题

长期运行的数据丰富化项目面临以下风险：

• 意外覆盖导致数天的工作丢失
• 无法还原到先前的数据状态
• 没有记录何时发生了哪些更改
• 手动备份占满磁盘空间
• 无法确定哪个版本是当前版本

解决方案：集成技能的智能双层备份系统

核心功能

1. 智能检测 —— 自动检测项目类型和需要备份的文件
2. 技能集成 —— 使用 jupyter-notebook、hackmd 和其他技能进行备份前清理
3. 每日备份 —— 滚动保留 7 天（自动清理）
4. 里程碑备份 —— 永久保存并压缩（gzip 压缩率约为 80%）
5. CHANGELOG —— 自动记录所有更改
6. 会话集成 —— 退出 Claude Code 会话时提示进行备份

智能检测与集成

备份系统会自动检测项目类型，并执行相应的清理：

Jupyter 笔记本（使用 jupyter-notebook 技能）：

• 检测：*.ipynb 文件
• 备份前清理：清除所有单元格输出，移除标记为 'debug' 或 'remove' 的单元格，验证笔记本

HackMD/演示文稿（使用 hackmd 技能）：

• 检测：包含 slideOptions: 前置元数据的 *.md 文件
• 备份前清理：验证 SVG 元素、检查幻灯片分隔符、验证 YAML 前置元数据

数据文件（原生处理）：

• 检测：*.csv、*.tsv、*.xlsx 文件
• 备份前清理：验证文件完整性，检查是否损坏

Python 项目（使用 managing-environments 技能）：

• 检测：requirements.txt、environment.yml、venv/、.venv/
• 备份前清理：移除 .pyc、__pycache__、.pytest_cache，清理构建产物

混合项目：检测以上所有类型，并对每种文件类型执行相应的清理。

目录结构

仅包含数据的项目：

project/
├── your_data_file.csv          # Main working file
├── backup_project.sh           # Smart backup script
└── backups/
    ├── daily/                  # Rolling 7-day backups
    ├── milestones/             # Permanent compressed backups
    ├── CHANGELOG.md            # Auto-generated change log
    └── README.md               # User documentation

混合项目（笔记本 + 数据）：

project/
├── analysis.ipynb              # Jupyter notebooks
├── data.csv                    # Data files
├── backup_project.sh           # Smart backup script
└── backups/
    ├── daily/                  # Rolling 7-day backups
    │   └── backup_2026-01-17/
    │       ├── notebooks/      # Cleaned (no outputs)
    │       └── data/
    ├── milestones/             # Permanent compressed backups
    ├── CHANGELOG.md
    └── README.md

存储效率

• 每日备份：约 5.4 MB（7 天 × 770 KB）
• 里程碑备份：每个压缩后约 200 KB（gzip 压缩后体积减少 80%）
• 总计：完整项目历史记录小于 10 MB
• 自动清理：旧的每日备份会在 7 天后删除

实现

使用 /backup 命令快速开始

首次使用——设置备份系统：

/backup

这将会：

• 检测项目类型（笔记本、数据文件、演示文稿等）
• 设置带有智能清理功能的相应备份脚本
• 创建备份目录结构
• 可选择配置自动备份

日常使用——创建备份：

/backup                    # Daily backup with smart cleanup
/backup milestone "desc"   # Milestone backup
/backup list              # View all backups
/backup restore DATE      # Restore from backup

备份期间会发生什么

备份前智能清理：

1. 检测项目中的文件类型
2. 应用特定技能的清理操作：
   • 笔记本：清除输出，移除调试单元格
   • HackMD：验证 SVG，检查格式
   • Python：移除 .pyc、__pycache__
   • 数据：验证完整性
3. 创建包含清理后文件的有序备份
4. 更新 CHANGELOG，记录备份内容

手动使用脚本（替代方案）

./backup_project.sh                           # Daily backup
./backup_project.sh milestone "description"   # Milestone
./backup_project.sh list                      # List backups
./backup_project.sh restore 2026-01-23        # Restore

何时创建里程碑

• 添加新的数据源后（GenomeScope、核型、外部 API）
• 进行重大数据转换或筛选前
• 完成分析章节时
• 提交／发布前
• 与协作者分享前
• 恢复缺失数据后

主要功能

安全功能

1. 未经询问绝不覆盖 - 覆盖现有备份前会先提示
2. 恢复前进行安全备份 - 恢复前会先备份当前状态
3. 自动清理 - 自动删除旧的每日备份（可配置）
4. 完整的审计跟踪 - CHANGELOG 会记录所有内容
5. 里程碑保护 - 永久保留重要版本（压缩存储）

CHANGELOG 跟踪

CHANGELOG.md 会自动记录：

• 每次备份的日期
• 类型（每日备份或里程碑）
• 变更说明（适用于里程碑）
• 对数据所做的重大修改

CHANGELOG 示例：

## 2026-01-23
- **MILESTONE**: Recovered VGP accessions (backup created)
  - Added columns: `accession_recovered`, `accession_recovered_all`
  - Recovered 5 VGP accessions from NCBI
- Daily backup created at 2026-01-23 15:00:00

## 2026-01-22
- Enriched GenomeScope data for 21 species from AWS repository
- Added column: `genomescope_path` with direct links to summary files

使用 /backup 命令

设置模式（首次运行）： /backup -- 检测项目类型、设置脚本并创建目录结构。

每日备份模式： /backup -- 快速进行每日备份。

里程碑模式： /backup milestone "description of changes" -- 例如：/backup milestone "added heterozygosity data"

列出和恢复：

/backup list              # Show all available backups
/backup restore 2026-01-23 # Restore from specific date

配置： 编辑 backup_project.sh，以更改保留天数（默认：7）、备份目录位置或自定义清理规则。

对数据分析的益处

• 数据溯源：CHANGELOG 会记录每次修改；为论文方法部分提供清晰的审计跟踪
• 放心尝试：轻松回滚，让你可以安全地尝试不同方法
• 专业工作流：符合出版标准；审稿人可以核验数据处理步骤
• 便于协作：团队成员可以了解数据历史和扩充过程

与 /safe-exit 集成会话

使用 /safe-exit 结束 Claude Code 会话时，系统会自动：

1. 检测当前项目中是否存在备份系统
2. 若已配置备份系统，则提示进行备份（每日备份、里程碑、跳过或取消）
3. 按需执行清理和备份
4. 提示创建 Obsidian 会话摘要（如果有 Obsidian 技能）
5. 正常退出会话

这样可以确保你在会话结束时不会忘记备份，也不会忘记记录工作！

工作流示例

星期一早上

/backup                          # Daily backup with smart cleanup
# Work on notebooks and data enrichment all day
/backup milestone "added karyotype data for 50 new species"

会话结束时

/safe-exit
# Prompted: daily backup -> backup complete -> session summary -> exit

星期五（糟糕，犯了个错误！）

/backup list                     # Check available backups
/backup restore 2026-01-23       # Restore from Wednesday

支持 MANIFEST 的备份

对于包含 MANIFEST 文件的项目，请使用仅包含必要文件的智能备份。完整模式、脚本模板、包含／排除规则以及与 /backup 命令的集成方式，请参阅 MANIFEST_BACKUPS.md。

完整项目备份

对于代码和数据都会发生变化的项目，可选择性地备份整个项目，在避免冗余的同时捕获完整状态。实现模式、备份策略对比、大小基准和路径验证指南，请参阅 FULL_PROJECT_BACKUPS.md。

高级用法

自定义备份脚本模板、多文件处理、查看压缩后的里程碑和实际示例，请参阅 ADVANCED_USAGE.md。

最佳实践

1. 在会话开始时创建每日备份 - 养成习惯
2. 每次重大变更后创建里程碑 - 不要依赖记忆
3. 使用描述清晰的里程碑名称 - 使用 "added genomescope"，不要使用 "updates"
4. 分享前检查 CHANGELOG - 确认数据溯源记录清晰
5. 定期列出备份 - 确认自动清理正常运行
6. 测试一次恢复操作 - 确认自己知道如何恢复

故障排除

找不到备份脚本

ls -l backup_project.sh   # Check if backup system is set up
/backup                    # Set up if needed

磁盘空间不足

du -sh backups/            # Check backup sizes
# Reduce retention: edit DAYS_TO_KEEP=3 in backup_table.sh
# Manually clean old milestones if needed

CHANGELOG 变得太大

tail -100 backups/CHANGELOG.md > backups/CHANGELOG_recent.md
mv backups/CHANGELOG.md backups/CHANGELOG_archive.md
mv backups/CHANGELOG_recent.md backups/CHANGELOG.md

概述

• 双层系统：每日滚动记录 + 永久里程碑
• 存储高效：Gzip 压缩（减少约 80%）
• 自动清理：每日记录保留 7 天滚动窗口
• 完整审计记录：CHANGELOG 跟踪所有变更
• 安全优先：未经确认绝不覆盖
• 全局安装程序：可在所有项目中使用
• 专业工作流：达到可供发表的数据来源记录标准