vaishak-v-nair/Backspace

## 问题所在 问题不在于撤销代码。Git 已经能做到这一点。 真正的问题在于，当 AI agent 修改了 6 个文件中的 15 处代码，并且在 20 分钟后测试失败之前一切看起来都很正常时，**要知道是哪个 AI 操作引发了回归问题**。 ``` You: "Add JWT authentication" AI: modifies 12 files across auth/, middleware/, routes/, config/ 20 minutes later: tests fail You: "Which of those 12 changes broke it?" Git: "Here are 12 diffs. Good luck." Backspace: "Session 'Add JWT auth' modified 12 files. auth/middleware.ts has a suspicious sync→async change. Risk: HIGH — this pattern breaks callers 34% of the time." ``` ## Git 做不到的事 ### 1. 跨工具会话追踪 Cursor 有检查点。Claude Code 有检查点。Aider 使用 git commit。 它们互不相通。在项目中途切换工具，你的恢复历史就会变得支离破碎。 Backspace 提供了一个适用于所有 AI 工具（如 Cursor、Claude Code、Aider、Copilot 或任何兼容 MCP 的 agent）的统一恢复模型。 ### 2. 可疑变更检测 你要求 AI “添加暗黑模式”。它却同时修改了 `auth.ts` 和 `middleware.ts`。 Git 不会标记这些。Backspace 会。 ### 3. 结构化的 AI 会话 Git 只能看到 commit。Backspace 能看到 AI 操作——按意图分组，按 prompt 标记，并按风险评分。 commit 代表“改动了什么”。会话代表“AI 试图做什么，以及在这个过程中它接触过的所有内容”。 ## 快速开始 ``` npm install -g backspace-ai ``` ``` # 1. 初始化（每个项目一次） $ backspace-ai init ✓ Backspace initialized · .backspace/local.db created # 2. 开始监听（在 AI session 之前） $ backspace-ai watch ✓ Daemon started (PID: 42891) · Watching for changes... [snap] 4 files → "add auth module" [snap] 12 files → "refactor db layer" [snap] 23 files → "migrate API routes" ← breaks here # 3. 还原错误的 session $ backspace-ai revert ✓ 23 files reverted in 47ms ⚠ Most changes were in routes/ — AI modified API endpoint signatures This pattern causes breakages in 37% of sessions like this one ``` ## 工作原理 Backspace 运行一个轻量级的 daemon 来监视你的文件系统。当 AI 工具修改文件时，Backspace 会： 1. **将变更分组为会话** —— 不是松散的 diff，而是结构化的 AI 操作 2. **捕获每次文件变动前后的状态** 3. **通过 prompt 嗅探检测**正在使用的 AI 工具（如 Claude、Cursor、Aider） 4. **评估风险** —— 同步转异步的变更、身份验证修改、DB 查询、env vars 5. **实现即时恢复** —— 对任何会话进行原子级回滚 ``` AI Agent ──→ Filesystem │ Backspace Daemon │ ┌─────────┼─────────┐ │ │ │ Session Event Risk Tracker Logger Analyzer │ │ │ └─────────┼─────────┘ │ SQLite (WAL mode) AES-256-GCM encrypted ``` 所有数据都保留在你的机器上。零云端。零遥测。 ## CLI 参考 | 命令 | 描述 | |---------|-------------| | `backspace-ai init` | 初始化 `.backspace/` 目录和加密数据库 | | `backspace-ai watch` | 启动后台 daemon —— 捕获所有文件变更 | | `backspace-ai stop` | 停止 daemon，关闭当前活动会话 | | `backspace-ai status` | 显示 daemon 状态、DB 大小、活动会话 | | `backspace-ai log` | 列出所有已记录的会话及其文件计数 | | `backspace-ai show ` | 格式化输出某个会话的事件和 diff | | `backspace-ai revert` | 交互式会话选择器 → 原子级回滚 | | `backspace-ai revert --latest` | 回滚最近的一次会话 | | `backspace-ai revert --id ` | 通过 ID 回滚特定的会话 | | `backspace-ai timeline` | 所有 AI 活动的时间轴 | | `backspace-ai inspect ` | 单个事件的详细来源 | | `backspace-ai check ` | 在开始会话前进行 pre-flight 风险分析 | | `backspace-ai mcp` | 启动用于 AI agent 集成的 MCP server | | `backspace-ai integrate ` | 自动配置集成（例如 `claude`） | 查看完整的 [CLI 参考 →](docs/cli-reference.md) ## 跨工具支持 Backspace 适用于**所有** AI 编程工具： | 工具 | 集成方式 | |------|-------------| | **Claude Code** | `backspace-ai integrate claude` | | **Cursor** | 自动检测 | | **Aider** | 自动检测 | | **Copilot** | 自动检测 | | **任何 MCP Agent** | `backspace-ai mcp` | 一个恢复模型。任意工具。自由切换。 ## Pre-Flight 风险分析 甚至在启动 AI 会话之前，Backspace 就可以分析你的 prompt： ``` $ backspace-ai check "refactor the auth module to use JWT" ⚠ MEDIUM RISK prompt detected (auth-refactor) Common failure patterns for this type of change: - Existing session tokens invalidated - Middleware chain broken by new auth checks - Environment variables added without documentation Suggested constraints to add to your prompt: → "Do not modify existing middleware signatures" → "Keep backward compatibility with current session tokens" ``` ## 路线图 - [x] 核心 CLI (init, watch, stop, revert, log, show) - [x] AES-256-GCM 本地加密 - [x] AI prompt 嗅探 (Claude, Cursor, Aider) - [x] Pre-flight 风险分析 (`check` 命令) - [x] 回滚后模式分析 - [x] 用于 AI agent 集成的 MCP server - [x] 事件时间轴和检查 - [ ] 选择性回滚 (`--file`, `--hunk`) - [ ] `watch` 期间的可疑变更警告 - [ ] 会话比较 (`diff `) - [ ] VS Code 扩展 ## 许可证 MIT © [Vaishak V Nair](https://github.com/vaishak-v-nair)

**如果 Backspace 拯救了你的项目，请考虑给它一个 ⭐** *git 追踪 commit。backspace 追踪 AI 操作。*