VibeRevert 是面向 AI 编程代理和 vibe coding 的项目完整性保护层，围绕一次 AI 编码会话提供记录、检查、修复和恢复能力。
用途 当你让 AI 代理在项目中工作时，它可能动到超出预期的内容，例如支付代码、数据库迁移或部署文件，而你自己尚未提交的工作可能正处在同一工作区中。VibeRevert 在会话开始前捕获项目的起始文件状态，使一次不理想的会话不至于让你损失大量工作。
主要能力
- 在会话开始前对项目做检查点，覆盖工作树、已暂存变更和未跟踪文件，包括尚未提交的工作。
- 记录会话以及会话运行期间发生变化的项目文件。
- 用确定性规则标记高风险编辑，涉及认证、支付、数据库、密钥、依赖或基础设施（见风险分类）。
- 根据这些发现生成可交给代理的修复提示，供下一次迭代使用。
- 在需要时将文件恢复到检查点。
- 它只警告，不会静默阻止你的工作。可选的 pre-commit 钩子可以在提交超过配置的风险阈值时拒绝提交，属于选择性启用、可调且像任何本地 Git 钩子一样可绕过。
规则决定，代理修复 VibeRevert 不会让另一个语言模型来判断代理的改动是否有风险。它的检查是确定性的：相同输入和配置产生相同发现，每个标记都有可检查的原因。当某处需要关注时，VibeRevert 可以把这些发现转成可交给代理的修复提示。规则决定要标记什么，你决定接下来做什么。
回滚全部或只回滚出错部分 viberevert rollback 会把本地项目文件（已跟踪、已暂存和未跟踪，包括未提交的工作）恢复到会话开始时的状态。默认先预览；--apply 才写入变更，且每次应用前会先保存一个可恢复的紧急检查点。自 0.8.0 起，也可以只恢复会话的一部分。例如代理对支付部分的改动是错的，但它新增的测试没问题，可以只放回支付相关改动，保留其余内容。
有四种选择方式，任一种都会把回滚切换为选择性模式。正向选择器按交集组合，因此 --only 'payments/**' --risk critical 表示 payments/ 内的关键变更，而不是 payments 加上所有不相关的关键文件。路径选择器会跟随被重命名的文件，所以移出 payments/ 的文件仍可匹配。只有当你选择的一切都能被恢复时才会执行：如果任何已选路径在会话结束后发生漂移，整个操作会拒绝，而不是只应用一半，--force 也不能覆盖这一点。如果选择性应用被中断，下一次会失败关闭，并指向紧急检查点，而不是在部分恢复之上再叠加第二次部分恢复。
两个需要留意的当前限制
- 0.8.0 之前结束的会话无法进行选择性回滚。它们没有记录自身贡献了什么，也无法重建。对这些会话整体回滚仍然照常可用。参见 MIGRATIONS.md。
- --finding 需要完整的 finding id，由 viberevert check --since <session> --json 打印。尚不接受短前缀。
它不能逆转项目文件之外的效果。部署、数据库写入、第三方 API 调用、支付和已发送邮件需要各自的恢复手段。回滚是基于状态的而非原子的，它是 AI 会话周围的安全网，不能替代测试或审查。在依赖之前，请阅读回滚能恢复和不能恢复的内容。
跨编码代理的一个恢复层 你可以继续使用偏好的编码工具。VibeRevert 可以包裹命令行代理会话（viberevert run <your-agent>），并通过安装器与 Claude Code、Cursor 等工具集成。内置检查点存在于代理工作流内部，而 VibeRevert 则留在项目侧：它捕获项目起始状态（包括未提交工作），记录会话，标记风险变更，预览回滚，并把恢复路径保留在代理之外。今天用 Claude Code，明天用 Cursor，或包裹其他终端代理，安全层始终与项目在一起。
接入你的工具 VibeRevert 以非破坏性方式安装，也可干净移除。它集成 Claude Code 和 Cursor（MCP 服务器和钩子）；每次安装都会预览其变更并保留恢复日志。参见入门指南。一个实验性的终端桥接（--pty）可以拦截交互式代理 shell 内的命令；它是尽力而为的，并在 PTY 契约中如此说明。
支持平台与要求 支持 Linux、macOS 和 Windows，需要 Node.js 22+。CI 在三个平台和 Node 22、24 上运行测试套件；各平台具体测试到的能力见兼容性说明。
许可与支持 VibeRevert 是 Apache-2.0 开源项目。赞助资金用于持续的跨平台测试、安全工作、回滚与恢复测试，以及帮助支付独立审查费用。赞助不影响风险发现或发布决策。参见 NOTICE 和许可证审计。
部分细节（如具体命令列表、配置项、风险分类完整内容、兼容性矩阵等）在所提供的资料中未完全展开，可查阅项目仓库相应文档。
