【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载Gentle-AI 会在每次install、sync、upgrade操作前自动为你的 AI 编码 AgentClaude Code、Cursor、OpenCode、Codex、Pi 等配置文件创建快照备份并采用压缩、去重与自动修剪策略控制磁盘占用。本文围绕官方 备份与回滚指南 展开结合仓库内internal/backup/包的源码实现完整讲解备份触发流程、快照结构与清单字段、保留与去重算法、TUI 与 CLI 的恢复操作以及验证失败后的标准处置路径帮助你安全、可预期地管理配置文件回滚。备份系统如何工作备份系统在每次运行gentle-ai install、sync或upgrade时自动触发核心流程分为四步对应 snapshot.go 中Snapshotter.Create的实现计算校验和checksum对所有将要备份的文件计算复合 SHA-256 校验和去重跳过dedup如果结果与最近一次备份完全相同则跳过本次备份不产生新的快照创建压缩快照将所有配置文件打包为snapshot.tar.gz修剪旧备份仅保留最近 5 个未钉住unpinned的备份删除其余部分。触发点与元数据来源install/sync 路径在 run.go 的prepareBackupStep中执行先通过ComputeChecksum做去重判断再调用snapshotter.Create创建快照随后将source、description、created_by_version等元数据写入manifest.json最后执行保留期修剪backup.Prune。upgrade 路径在 executor.go 中通过snapshotCreator变量默认为backup.NewSnapshotter().Create在升级执行前创建快照ExecuteOptions.SkipBackup对应 CLI 的--no-backup可对单次运行显式跳过备份创建与修剪。每次 install/sync 还会在临时目录创建一份事务快照transaction snapshot供安装过程中失败时即时回滚使用成功后随清理步骤删除见 run.go 的cleanupRollbackSnapshot。校验和算法细节retention.go 中ComputeChecksum的算法是过滤出存在且为普通文件的路径 → 按字典序排序保证确定性 → 对每个文件内容计算 SHA-256 → 拼接所有path:hexhash\n对 → 对拼接结果再做一次 SHA-256 得到复合摘要。校验和包含绝对路径因此去重是每台机器级别的不同主机的相同文件会产生不同校验和——这是有意设计。当没有任何文件时使用空字符串的 SHA-256 作为稳定哨兵值emptyFilesChecksum使连续两次零文件备份也能被正确识别为重复snapshot.go。快照内容与目录结构每个备份快照存放在~/.gentle-ai/backups/id/下目录解析见 manifest.go包含两个关键文件manifest.json—— 元数据清单来源source、时间戳created_at、文件数file_count、校验和checksum、钉住状态pinned等snapshot.tar.gz—— 所有被备份文件的压缩归档。对于操作前不存在的路径清单记录existedfalse以便回滚时正确反向删除安装过程中创建的文件。manifest.json 字段说明manifest.go 定义的Manifest结构主要字段如下字段JSON 键含义IDid备份目录名基于时间戳生成CreatedAtcreated_atUTC 创建时间RootDirroot_dir备份目录绝对路径Sourcesource来源install/sync/upgrade/uninstall旧清单缺省显示unknown sourceDescriptiondescription人工可读的描述TUI 中r键可编辑FileCountfile_count实际存在并被快照的文件数existedfalse的条目不计入CreatedByVersioncreated_by_version创建该备份的 gentle-ai 版本Pinnedpinned是否被钉住受保护不被修剪Compressedcompressed是否使用 tar.gz 压缩归档Checksumchecksum复合 SHA-256用于去重Entriesentries每个备份目标的明细条目DisplayLabel方法manifest.go组合来源、本地时间戳与文件数生成人类可读标签钉住的备份会带[pinned]前缀——这正是 TUI 与gentle-ai restore --list列表里每行显示的内容。备份范围重要边界备份范围升级前与同步前的快照只覆盖state.InstalledAgents~/.gentle-ai/state.json中列出的 Agent。通过 gentle-ai 之外方式安装的 Agent 配置目录不会进入快照。此外upgrade 的备份遍历通过backupExcludeSubdirs白名单跳过运行态/缓存类目录executor.go例如backups绝不递归进备份自身、cache、debug、downloads、pluginsMCP 插件二进制可达 60 MB、sessions、tasks、telemetry、node_modules以及 Claude Code 的projects单目录可超 1 GB、Gemini/Antigravity 的browser_recordings可达 3 GB等。这些目录不是配置、且体积巨大跳过它们能避免升级过程被拖垮。保留策略与去重设置项默认值行为保留数量Keep count5保留最近 5 个未钉住的备份钉住备份Pinned永不删除无论数量多少都免于修剪重复备份Duplicates跳过配置未变化时不创建新备份压缩Compression始终启用新备份使用 tar.gz体积约缩小 75%默认保留数量5定义在 retention.go 的DefaultRetentionCount。修剪逻辑Pruneretention.go读取backupDir下所有含可读manifest.json的子目录按CreatedAt从新到旧排序划分出未钉住的部分若数量超过保留上限则删除最旧的超额备份单个目录删除失败仅记录日志、不中断其余备份的评估无manifest.json的目录被静默跳过不计入限额。去重由DuplicateManifestretention.go实现只有当最近一次备份的Checksum与本次相同且校验和不为空时才判定为重复。prepareBackupStep在判定重复时还会通过manifestTargetsMatch确认目标路径集合完全一致run.go双重保险后才真正跳过快照创建。钉住备份Pinning任何备份都可以在 TUI 中标记为钉住以保护其不被自动修剪运行gentle-ai进入Backups屏幕使用j/k选择备份按p切换钉住/取消钉住钉住的备份显示[pinned]标识。钉住的备份永远不会被自动删除即使超过保留数量上限也不例外。底层由TogglePin实现manifest.go翻转清单的Pinned字段并重写manifest.jsonTUI 的按键处理在 model.goPrune在分区时完全跳过Pinned true的备份retention.go。通过 TUI 管理备份进入Backups屏幕后可用快捷键如下TUI 按键分发见 model.go按键操作j/k上下移动选择Enter恢复选中的备份p钉住/取消钉住保护免于修剪r重命名添加描述d删除Esc返回r键调用RenameBackupmanifest.go只更新清单中的Description字段而不重命名目录d键先进入删除确认屏幕再调用DeleteBackupmanifest.go删除整个备份目录。通过 CLI 恢复备份gentle-ai restore是独立的命令行恢复入口完整实现见 restore.gogentle-ai restore [--list | latest | id] [--yes]参数作用--list列出所有可用备份而不执行恢复latest恢复最新备份列表中第一个id按 ID 精确恢复指定备份--yes/-y跳过确认提示适合脚本/非交互场景典型用法# 查看可用备份 gentle-ai restore --list # 恢复最近一次备份 gentle-ai restore latest # 按 ID 恢复并跳过确认 gentle-ai restore 20260928150405.000000000 --yes # 恢复过程中提示确认默认交互 gentle-ai restore latest # Restore backup id (install — 2026-09-28 15:04)? # This will overwrite your current configuration. Type yes to confirm:列表输出格式为[序号] ID 标签 [版本]例如[1] 20260928150405.000000000 install — 2026-09-28 15:04 (5 files) [v3.x]。确认逻辑只接受yes忽略大小写EOF 或非确认输入均视为拒绝并提示使用--yesrestore.go。恢复行为细节existedtrue从快照将文件恢复到原始路径existedfalse删除该文件回滚安装期间创建的文件按文件原子写入不存在部分恢复状态同时兼容压缩tar.gz与旧版plain file备份。原子写入与类型安全restoreEntryrestore.go通过filemerge.WriteFileAtomicMode写入文件并恢复原始权限位mode。恢复前会对清单中的每条OriginalPath做严格的路径围栏校验isPathUnderRoot路径必须是绝对路径、且位于允许的根目录默认$HOME之下对于压缩备份的SnapshotPath还要求是相对路径绝对路径会读取活文件系统而非解压目录直接拒绝。解压归档时compression.go 会拒绝任何含..的条目、解析到目标目录本身的.条目以及非普通文件类型防止路径穿越攻击。PathKind 分类语义清单条目的Kind字段manifest.go决定恢复策略regular普通文件进入归档并在恢复时写回existedfalse时显式删除directory空目录不归档恢复时确保目录存在、绝不删除预先存在的目录symlink_directory指向目录的相对符号链接不归档恢复时校验LinkTarget是安全相对路径非绝对路径、解析后仍在根目录内防..与..\穿越后再重建若磁盘上已存在同路径节点则必须仍是符号链接且指向相同目标否则 fail-closed 拒绝restore.gounknown旧版清单恢复时采用保守策略——existedfalse的 unknown 条目只保留不删除因为无法证明该路径是安装创建的删除可能误伤用户自有文件restore.go。旧版备份兼容v1.16 之前的旧版备份使用files/目录存放普通文件副本而非 tar.gz 归档Compressedfalse。RestoreService.Restore会根据manifest.Compressed自动分流到restoreCompressed或restorePlainrestore.go两种格式均可完整恢复。旧版清单没有Source、FileCount等字段时显示层优雅降级为unknown source、不显示文件数。验证失败后的标准处置如果安装后的验证失败按照文档给出的四步走审查验证报告中的失败检查项报告格式由 report.go 渲染逐项显示[ok]/[!!]/[??]/[--]状态与失败原因汇总行形如Verification checks: N passed, N failed, N warnings, N skipped通过 TUI 或gentle-ai restore latest从最新快照恢复使用--dry-run重新运行安装以验证计划install、sync、upgrade均支持 dry-run不产生任何文件变更修复外部依赖后重新安装。恢复操作全程有防误伤护栏清单中的root_dir必须位于~/.gentle-ai/backups/之下才会执行删除DeleteBackup的isRootDirUnderBackupRoot检查manifest.go回滚时rollbackRootsrun.go以本次 install/sync 实际写入过的 home 目录、工作区目录为边界校验每个条目防止被篡改的清单将文件写到任意位置。rollback 不覆盖的内容通过brew install、apt-get install或pacman -S安装的软件包不会在回滚时被卸载——快照系统只处理配置文件需要撤销包安装时请直接使用平台包管理器例如brew uninstall、sudo apt-get remove、sudo pacman -R。这也决定了备份系统的定位它是配置层的安全网负责把 Agent 配置文件恢复到操作前状态系统级依赖属于包管理器职责范围两者互补而不混淆。总结Gentle-AI 的备份与回滚机制在 internal/backup 包中形成了一条完整链路Snapshotter.Create负责快照与元数据记录 →ComputeChecksum/DuplicateManifest实现内容去重 →Prune按保留策略修剪 →RestoreService按 PathKind 语义安全恢复。日常使用中你只需记住三件事所有install/sync/upgrade都会自动留后路重要备份用 TUI 的p钉住出问题时用gentle-ai restore latest一键回退再用--dry-run验证计划后重装。赞分享【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载相关推荐Factorio Learning Environment备份策略快照与灾难恢复Factorio Learning Environment备份策略快照与灾难恢复 在Factorio Learning EnvironmentFLE中实人工智能大模型AI AgentAgent 评测模型评测Simplefolio备份策略数据恢复与版本回滚的完整指南Simplefolio备份策略数据恢复与版本回滚的完整指南 作为一款简洁美观的开发者作品集模板Simplefolio帮助开发者快速搭建个人在线作品展示平台。前端Monad数据库快照增量备份与恢复策略Monad数据库快照增量备份与恢复策略 引言数据安全的痛点与解决方案 你是否曾因数据库故障导致数据丢失是否在全量备份上耗费过多存储空间Monad数据库的上一篇紧急修复Librosa MFCC参数传递陷阱及0.11.0版本适配指南下一篇彻底解决Caddy证书冲突忽略已加载证书的终极配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gentle-AI 备份与回滚指南：快照、去重、保留策略与恢复实操
【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载Gentle-AI 会在每次install、sync、upgrade操作前自动为你的 AI 编码 AgentClaude Code、Cursor、OpenCode、Codex、Pi 等配置文件创建快照备份并采用压缩、去重与自动修剪策略控制磁盘占用。本文围绕官方 备份与回滚指南 展开结合仓库内internal/backup/包的源码实现完整讲解备份触发流程、快照结构与清单字段、保留与去重算法、TUI 与 CLI 的恢复操作以及验证失败后的标准处置路径帮助你安全、可预期地管理配置文件回滚。备份系统如何工作备份系统在每次运行gentle-ai install、sync或upgrade时自动触发核心流程分为四步对应 snapshot.go 中Snapshotter.Create的实现计算校验和checksum对所有将要备份的文件计算复合 SHA-256 校验和去重跳过dedup如果结果与最近一次备份完全相同则跳过本次备份不产生新的快照创建压缩快照将所有配置文件打包为snapshot.tar.gz修剪旧备份仅保留最近 5 个未钉住unpinned的备份删除其余部分。触发点与元数据来源install/sync 路径在 run.go 的prepareBackupStep中执行先通过ComputeChecksum做去重判断再调用snapshotter.Create创建快照随后将source、description、created_by_version等元数据写入manifest.json最后执行保留期修剪backup.Prune。upgrade 路径在 executor.go 中通过snapshotCreator变量默认为backup.NewSnapshotter().Create在升级执行前创建快照ExecuteOptions.SkipBackup对应 CLI 的--no-backup可对单次运行显式跳过备份创建与修剪。每次 install/sync 还会在临时目录创建一份事务快照transaction snapshot供安装过程中失败时即时回滚使用成功后随清理步骤删除见 run.go 的cleanupRollbackSnapshot。校验和算法细节retention.go 中ComputeChecksum的算法是过滤出存在且为普通文件的路径 → 按字典序排序保证确定性 → 对每个文件内容计算 SHA-256 → 拼接所有path:hexhash\n对 → 对拼接结果再做一次 SHA-256 得到复合摘要。校验和包含绝对路径因此去重是每台机器级别的不同主机的相同文件会产生不同校验和——这是有意设计。当没有任何文件时使用空字符串的 SHA-256 作为稳定哨兵值emptyFilesChecksum使连续两次零文件备份也能被正确识别为重复snapshot.go。快照内容与目录结构每个备份快照存放在~/.gentle-ai/backups/id/下目录解析见 manifest.go包含两个关键文件manifest.json—— 元数据清单来源source、时间戳created_at、文件数file_count、校验和checksum、钉住状态pinned等snapshot.tar.gz—— 所有被备份文件的压缩归档。对于操作前不存在的路径清单记录existedfalse以便回滚时正确反向删除安装过程中创建的文件。manifest.json 字段说明manifest.go 定义的Manifest结构主要字段如下字段JSON 键含义IDid备份目录名基于时间戳生成CreatedAtcreated_atUTC 创建时间RootDirroot_dir备份目录绝对路径Sourcesource来源install/sync/upgrade/uninstall旧清单缺省显示unknown sourceDescriptiondescription人工可读的描述TUI 中r键可编辑FileCountfile_count实际存在并被快照的文件数existedfalse的条目不计入CreatedByVersioncreated_by_version创建该备份的 gentle-ai 版本Pinnedpinned是否被钉住受保护不被修剪Compressedcompressed是否使用 tar.gz 压缩归档Checksumchecksum复合 SHA-256用于去重Entriesentries每个备份目标的明细条目DisplayLabel方法manifest.go组合来源、本地时间戳与文件数生成人类可读标签钉住的备份会带[pinned]前缀——这正是 TUI 与gentle-ai restore --list列表里每行显示的内容。备份范围重要边界备份范围升级前与同步前的快照只覆盖state.InstalledAgents~/.gentle-ai/state.json中列出的 Agent。通过 gentle-ai 之外方式安装的 Agent 配置目录不会进入快照。此外upgrade 的备份遍历通过backupExcludeSubdirs白名单跳过运行态/缓存类目录executor.go例如backups绝不递归进备份自身、cache、debug、downloads、pluginsMCP 插件二进制可达 60 MB、sessions、tasks、telemetry、node_modules以及 Claude Code 的projects单目录可超 1 GB、Gemini/Antigravity 的browser_recordings可达 3 GB等。这些目录不是配置、且体积巨大跳过它们能避免升级过程被拖垮。保留策略与去重设置项默认值行为保留数量Keep count5保留最近 5 个未钉住的备份钉住备份Pinned永不删除无论数量多少都免于修剪重复备份Duplicates跳过配置未变化时不创建新备份压缩Compression始终启用新备份使用 tar.gz体积约缩小 75%默认保留数量5定义在 retention.go 的DefaultRetentionCount。修剪逻辑Pruneretention.go读取backupDir下所有含可读manifest.json的子目录按CreatedAt从新到旧排序划分出未钉住的部分若数量超过保留上限则删除最旧的超额备份单个目录删除失败仅记录日志、不中断其余备份的评估无manifest.json的目录被静默跳过不计入限额。去重由DuplicateManifestretention.go实现只有当最近一次备份的Checksum与本次相同且校验和不为空时才判定为重复。prepareBackupStep在判定重复时还会通过manifestTargetsMatch确认目标路径集合完全一致run.go双重保险后才真正跳过快照创建。钉住备份Pinning任何备份都可以在 TUI 中标记为钉住以保护其不被自动修剪运行gentle-ai进入Backups屏幕使用j/k选择备份按p切换钉住/取消钉住钉住的备份显示[pinned]标识。钉住的备份永远不会被自动删除即使超过保留数量上限也不例外。底层由TogglePin实现manifest.go翻转清单的Pinned字段并重写manifest.jsonTUI 的按键处理在 model.goPrune在分区时完全跳过Pinned true的备份retention.go。通过 TUI 管理备份进入Backups屏幕后可用快捷键如下TUI 按键分发见 model.go按键操作j/k上下移动选择Enter恢复选中的备份p钉住/取消钉住保护免于修剪r重命名添加描述d删除Esc返回r键调用RenameBackupmanifest.go只更新清单中的Description字段而不重命名目录d键先进入删除确认屏幕再调用DeleteBackupmanifest.go删除整个备份目录。通过 CLI 恢复备份gentle-ai restore是独立的命令行恢复入口完整实现见 restore.gogentle-ai restore [--list | latest | id] [--yes]参数作用--list列出所有可用备份而不执行恢复latest恢复最新备份列表中第一个id按 ID 精确恢复指定备份--yes/-y跳过确认提示适合脚本/非交互场景典型用法# 查看可用备份 gentle-ai restore --list # 恢复最近一次备份 gentle-ai restore latest # 按 ID 恢复并跳过确认 gentle-ai restore 20260928150405.000000000 --yes # 恢复过程中提示确认默认交互 gentle-ai restore latest # Restore backup id (install — 2026-09-28 15:04)? # This will overwrite your current configuration. Type yes to confirm:列表输出格式为[序号] ID 标签 [版本]例如[1] 20260928150405.000000000 install — 2026-09-28 15:04 (5 files) [v3.x]。确认逻辑只接受yes忽略大小写EOF 或非确认输入均视为拒绝并提示使用--yesrestore.go。恢复行为细节existedtrue从快照将文件恢复到原始路径existedfalse删除该文件回滚安装期间创建的文件按文件原子写入不存在部分恢复状态同时兼容压缩tar.gz与旧版plain file备份。原子写入与类型安全restoreEntryrestore.go通过filemerge.WriteFileAtomicMode写入文件并恢复原始权限位mode。恢复前会对清单中的每条OriginalPath做严格的路径围栏校验isPathUnderRoot路径必须是绝对路径、且位于允许的根目录默认$HOME之下对于压缩备份的SnapshotPath还要求是相对路径绝对路径会读取活文件系统而非解压目录直接拒绝。解压归档时compression.go 会拒绝任何含..的条目、解析到目标目录本身的.条目以及非普通文件类型防止路径穿越攻击。PathKind 分类语义清单条目的Kind字段manifest.go决定恢复策略regular普通文件进入归档并在恢复时写回existedfalse时显式删除directory空目录不归档恢复时确保目录存在、绝不删除预先存在的目录symlink_directory指向目录的相对符号链接不归档恢复时校验LinkTarget是安全相对路径非绝对路径、解析后仍在根目录内防..与..\穿越后再重建若磁盘上已存在同路径节点则必须仍是符号链接且指向相同目标否则 fail-closed 拒绝restore.gounknown旧版清单恢复时采用保守策略——existedfalse的 unknown 条目只保留不删除因为无法证明该路径是安装创建的删除可能误伤用户自有文件restore.go。旧版备份兼容v1.16 之前的旧版备份使用files/目录存放普通文件副本而非 tar.gz 归档Compressedfalse。RestoreService.Restore会根据manifest.Compressed自动分流到restoreCompressed或restorePlainrestore.go两种格式均可完整恢复。旧版清单没有Source、FileCount等字段时显示层优雅降级为unknown source、不显示文件数。验证失败后的标准处置如果安装后的验证失败按照文档给出的四步走审查验证报告中的失败检查项报告格式由 report.go 渲染逐项显示[ok]/[!!]/[??]/[--]状态与失败原因汇总行形如Verification checks: N passed, N failed, N warnings, N skipped通过 TUI 或gentle-ai restore latest从最新快照恢复使用--dry-run重新运行安装以验证计划install、sync、upgrade均支持 dry-run不产生任何文件变更修复外部依赖后重新安装。恢复操作全程有防误伤护栏清单中的root_dir必须位于~/.gentle-ai/backups/之下才会执行删除DeleteBackup的isRootDirUnderBackupRoot检查manifest.go回滚时rollbackRootsrun.go以本次 install/sync 实际写入过的 home 目录、工作区目录为边界校验每个条目防止被篡改的清单将文件写到任意位置。rollback 不覆盖的内容通过brew install、apt-get install或pacman -S安装的软件包不会在回滚时被卸载——快照系统只处理配置文件需要撤销包安装时请直接使用平台包管理器例如brew uninstall、sudo apt-get remove、sudo pacman -R。这也决定了备份系统的定位它是配置层的安全网负责把 Agent 配置文件恢复到操作前状态系统级依赖属于包管理器职责范围两者互补而不混淆。总结Gentle-AI 的备份与回滚机制在 internal/backup 包中形成了一条完整链路Snapshotter.Create负责快照与元数据记录 →ComputeChecksum/DuplicateManifest实现内容去重 →Prune按保留策略修剪 →RestoreService按 PathKind 语义安全恢复。日常使用中你只需记住三件事所有install/sync/upgrade都会自动留后路重要备份用 TUI 的p钉住出问题时用gentle-ai restore latest一键回退再用--dry-run验证计划后重装。赞分享【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载相关推荐Factorio Learning Environment备份策略快照与灾难恢复Factorio Learning Environment备份策略快照与灾难恢复 在Factorio Learning EnvironmentFLE中实人工智能大模型AI AgentAgent 评测模型评测Simplefolio备份策略数据恢复与版本回滚的完整指南Simplefolio备份策略数据恢复与版本回滚的完整指南 作为一款简洁美观的开发者作品集模板Simplefolio帮助开发者快速搭建个人在线作品展示平台。前端Monad数据库快照增量备份与恢复策略Monad数据库快照增量备份与恢复策略 引言数据安全的痛点与解决方案 你是否曾因数据库故障导致数据丢失是否在全量备份上耗费过多存储空间Monad数据库的上一篇紧急修复Librosa MFCC参数传递陷阱及0.11.0版本适配指南下一篇彻底解决Caddy证书冲突忽略已加载证书的终极配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考