内容
="center">
<img src="assets/safefs-logo.svg" alt="SafeFS logo" width="112" height="112">
</p>
# SafeFS MCP
version](https.shields.io/npm/v/@tekergul/safefs.svg)](https://www/@tekergul-mcp)
](https://github.com/TEKERGUL/safefs-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/TEKERGUL/safefs-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
AI 代码工具出错了？回滚最近 10 分钟的更改。
SafeFS 是一个适用于 AI 编码代理的轻量级会话保护工具。它在本地记录文件更改快照，而无需 Git 提交、Docker 守护进程、数据库或网络服务。
SafeFS 仍然是一个 MCP 服务器，但推荐的工作流程是优先使用保护层：守护进程在后台记录本地文件更改，而 MCP 工具处理差异、时间线、存储状态和回滚。
## 为什么选择 SafeFS
AI 编码工具速度快，但一次糟糕的重构可能会影响多个文件，而你可能直到事后才注意到。Git 在你记得提交更改帮助，而 SafeFS 则从“我让代理尝试某事”到“我保留此更改”之间的差距。
- 启动 AI 会话时提供轻量级保护
- 让代理使用其正常的编辑工具
- 预览过去 `10m`、`1h` 或 `1d` 的更改
- 回滚仅限于高风险会话窗口，而无需重置整个仓库
- 默认情况下，将机密、`.git`、`.safefs`、供应商文件夹、构建输出、二进制文件和大文件排除在快照之外
## 快速入门
全局安装一次：
```bash
npm install -g @tekergul/safefs-mcp
```
后续升级```bash
npm install -g @tekergulefs-mcp@latest
```
初始化项目：
```safefs init --clients claude-guard
Invoke-Expression (safefs auto-guard env powershell)
claude
```
Bash/z
```bash
safefs init --yes --aude --auto-guard
eval "$(safefs env bash)"
cl```
激活后，您的代理。项目本地包装器在后台启动 SafeFS 守护进程。
预览恢复：
```bashafefs diff
safefs rollbackm
safefs rollback 10m --yes回滚默认为 dry-run。仅在查看计划或差异后才使用 `--yes`。
## 30 秒演示流程bash
npmg @tekergul/safefs-mcp
efs init --yes --clients claude --auto-geval "$(saf-guard env bashaude
```
要求代理改进一个小应用程序。然后要求风险的重构。当结果：
```bashafefs diff 10mafefs rollbackm --yes
```
SafeFS 恢复受影响文件的更改前状态，同时保持无关的项目文件不变。
## 功能
- 适用于通过守护进程/监视或项目本地自动守护进程使用原生编辑工具的代理
- 从 `10m`、`15m`、`1h`、`3h`、`1d`、`7d` 或戳回滚 AI
- 在应用，以可读的统一差异预览回滚
- 在不重置整个项目的情况下，恢复单个文件
- 跳过已记录的编辑后更改的文件的冲突
- 默认忽略受保护的路径、机密、供应商文件夹、构建输出、二进制文件和大文件
- 在大型项目中，将监视状态缓存在本地清单中
- 检测稳定写入、常见临时大小写冲突、和相同哈希移动
- 推迟大批量更新弃监视器事件
- 使用 `safefs checkup` 报告项目存储健康状况
- 支持 Claude Code、Codex、Cursor、Antigravity、Gemini CLI、Rooline 等 MCP ## 安装模式
| | 命令 | 最| --- | --- | --- |
| 自动守护safefs init --clients claude --uard` | 需要最少输入的日常 AI 会话 |
| 手动守护 | `safefs guard -- claude` | 一次保护的会话 |
监视 | `safefs watch` | 单独的终端监视所有本地编辑 |
| 仅 MCP | `safefs serve --root .` |需要恢复/状态工具的客户端 |
自动守护是项目本地的。它在 `.efs/bin` 下器，在 `.s 下创建激活脚本，但不编辑全局 shell 配置文件或劫持全局二进制## CLI
```bash
safefs init
safefs doctor
safefs guard -- claude
safefs auto-guard install --clients claudex
saf-guard status
safefs auto-guard env
safefs auto-guard uninstall
s mcp-config antigravity
safefs watch
safefs watch --dry-run
safefs timeline 3h
safefs diff 10safefs diff 10m
s rollback 10m
safefs rollback --yes
s storage
safefs
safefs checkup --strict
safefs prune --days 30
safefs prune --days 30 --yes --gc
safefs gc
safefs gc --yes
```
维护命令也默认为 dry-run。`checkup` 在不删除任何文件的情况下报告存储和监视器健康状况。`prune` 删除旧的时间线事件，`gc` 在提供 `--yes` 时删除无引用对象。
## 自动守护、守护和监视模式
`auto-guard` 是最简单的日常设置。它在 `.efs/bin` 下安装项目本地包装器，不修改全局 shell 配置全局二进制文件：
```bash
saf --yes --clients claude,codex --uard
safefs auto-guard status
```
激活，然后正常代理：
```powershell-Expression (safefs auto-guard env powershell)
claude
```
如果 `safefs PATH 未激活，请终端中再次命令，您将在其中。
手动 `guard`可用于显：
```bash
efs guard -- claude
safefs guardx
```
`guard` 启动 SafeFS 监视器，运行命令原生文件写入/移动，并在命令退出时刷新最终更改。
在的终端时使用 `watch`：
```bash
safefs watch监视模式尊重ignore`、受保护的模式、文件大小限制写入去抖、二进制检测、大小写冲突链接策略、、每个周期速率safefs/watch/manifest.json` 重## 支持的客户端客户端 | MCP 自动守护包装 || --- | --- | --- |
Code | 是 | 推荐的演示| Codex | 是 | 是 | 使用 Safe 工具进行检查/恢复 |
| Cursor | 是 | 是 | MCP 配置片段由 init 生成 |
| Antigravity | 片段 | 先监视 | 使用 `safefs mcp-config antigravity`，然后运行 `safefs watch` |
| Gemini CLI | 是 | 是 | 工具名称可能有别名前缀 |
| Roo Code / Cline | 手动示例 | 监视/守护兼容 | 使用标准 MCP 服务器配置 |
| 其他编辑器/终端 | 无生成配置 | 监视/守护兼容 | 使用 `safefs watch` 或 `safefs guard -- <command>` |
## MCP 工具
SafeFS 仍然是一个 MCP 服务器。监视器/自动守护层捕获原生编辑；MCP 工具提供恢复和检查：
- `safe_read_file`
- `safe_diff`
- `safe_timeline`
- `safe_restore_file`
- `safe_rollback_time`
- `safe_storage_status`
旧版写入工具因兼容性而保留，但不再是推荐的路径：
- `safe_write`
- `safe_patch`
- `safe_delete`
Gemini CLI 使用服务器别名限定 MCP 工具名称，因此 SafeFS 工具可能显示为 `mcp_safefs_safe_diff` 等名称。
## 回滚工作原理
1. 守护进程/监视器构建或重用本地基线清单。
2. 原生文件更改在去抖窗口后变得稳定。
3. SafeFS 在 `.safefs/objects/` 中存储更改前/后的内容，并追加已提交的时间线事件。
4. 回滚按文件分组提交事件，验证当前哈希，检查冲突，并恢复最早的更改前状态。
5. 回滚写入一个短抑制标记，以防止监视器将回滚本身记录为新的代理编辑。
如果文件在记录的编辑后更改，回滚会跳过它并报告预期的/当前哈希。
## 恢复会话示例
```bash
# 查看 SafeFS 可以从过去 10 分钟恢复的内容。
safefs diff 10m
# 在不触及文件的情况下预览回滚。
safefs rollback 10m
# 在查看后应用回滚。
safefs rollback 10m --yes
```
典型的 dry-run 输出将已恢复的文件、将被删除的已创建文件、冲突和跳过的文件分开。冲突报告包括预期和当前哈希，以便您可以决定是保留手动编辑、检查差异还是重试较窄的路径。
对于单个损坏的文件，MCP 客户端可以使用 `safe_restore_file` 代替回滚整个时间窗口：
```json
{
"path": "src/utils.ts",
"dryRun": true
}
```
`checkpointId` 是可选的。如果省略，SafeFS 将恢复该文件最新的已提交检查点。应用仍需要 `dryRun: false` 和 `confirm: true`。
## 安全模型
- 路径必须位于工作区根目录内
- 默认保护 `.git/`、`.safefs/`、`.env*`、密钥、令牌、云凭证、机密和常见的构建/供应商文件夹
- 用户配置可以添加受保护的模式和监视排除
- 默认跳过符号链接；启用跟随时阻止符号链接逃逸
- 监视模式跳过二进制文件和大文件
- 时间线事件仅追加
- 时间线清理和对象垃圾收集是显式且默认为 dry-run 的维护命令
参见 [SECURITY.md](SECURITY.md)。
## 存储和隐私
SafeFS 在项目本地的 `.safefs/` 目录中存储快照。它不上传源代码、不将文件内容发送到服务器，也不要求后台云服务。
默认监视规则避免：
- `.git/`、`.safefs/`、`.env*`、凭证、密钥和类似令牌的文件
- `node_modules/`、`dist/`、`build/`、缓存和包管理器存储
- 二进制文件、非常大的文件和临时编辑器文件
- 符号链接逃逸到工作区根目录之外
您可以使用以下命令检查本地存储：
```bash
safefs checkup
safefs storage
safefs prune --days 30
safefs prune --days 30 --yes --gc
safefs gc --yes
safefs timeline --since 1h
```
`safefs storage` 和 `safefs checkup` 使用相同的警告引擎。当时间线文件、对象存储或最旧事件超过已配置的阈值时，它们会发出警告，但不会自动清理或删除文件。
对象压缩是可选的：
```yaml
storage:
objectCompression: true
```
启用时，SafeFS 使用 gzip 压缩新写入的对象，同时保持基于原始未压缩字节的哈希。现有的原始对象保持可读，不会迁移或重写。
## 二进制文件策略
SafeFS 关注面向文本的 AI 编码会话。
- 监视模式默认跳过二进制文件，并将跳过原因报告为 `binary_file_skipped`
- `safefs watch --dry-run` 将二进制文件跳过计数与跳过文件分开显示
- 统一差异输出不尝试对二进制内容进行文本差异；二进制差异标记为二进制
- 旧版写入工具是面向文本的兼容性工具
- 对象存储可以循环原始字节，但监视模式保持更安全的默认跳过二进制文件
## 客户端配置
推荐的设置命令为选定的客户端编写项目本地配置片段：
```bash
safefs init --yes --clients codex,cursor,claude,gemini,antigravity --auto-guard
```
手动示例位于 [examples/](examples/) 中。
### Antigravity
Antigravity 使用全局/共享的 MCP 配置文件。SafeFS 不会自动修改它。
从项目根目录生成 SafeFS 片段：
```bash
safefs init --yes --clients antigravity
safefs mcp-config antigravity
```
将输出粘贴到 Antigravity 的原始 MCP 配置文件 `~/.gemini/config/mcp_config.json` 中，然后在打开或使用 Antigravity 之前启动监视模式：
```bash
safefs doctor --antigravity
safefs watch
```
生成的片段使用绝对 `--root` 路径，因为 Antigravity 的全局配置不是项目本地的。
### Gemini CLI
项目配置路径：`.gemini/settings.json`
```json
{
"mcpServers": {
"safefs": {
"command": "npx",
"args": ["-y", "@tekergul/safefs-mcp", "serve", "--root", "."],
"timeout": 600000,
"trust": false
}
}
}
```
验证 Gemini 是否可以查看项目配置：
```bash
safefs doctor --gemini-smoke
```
### Claude Code / Cursor
cpServers`
```json "m {
"safefs": {
type": "stdio "command":px",
" ["-y", "@tekergul/safefs-mcp", "serve", "--root", "."],
"env": {}
}
}
}
```
### Codex
```toml
[m.safefs]
true
commandnpx"
args-y", "@tekergul/safcp", "serveroot", "."_timeout_sec = 10
tool_timeout_sec60
default_tools_mode = "enabled_tools = [
"safe_read_file",
"safe_diff",
"safe_timeline",
_restore_file",
safe_rollback_time "safe_storage]
```
## 限制
- 故意阻止目录删除
- 函数级和精确行范围回滚计划在后续版本中实现
- 对象压缩是可选的，仅适用于新对象；现有原始对象不会迁移
- 自动守护进程是按项目选择的；SafeFS 不会修改全局 shell 启动文件
- SafeFS 补充 Git；它不会取代提交、分支或备份
## 架构
SafeFS 构建为三个协作MCP 控制层、原生编辑监视器和回滚引擎。
```mermaid
flowchart TD
A["AI 编码客户端<br/>Claude, Codex, Cursor, Antigravity, Gemini"] --> B["原生编辑路径<br/>工具，终端，代理写入"]
A --> C["MCP 控制层<br/>safe_diff, safe_timeline, safe_restore_file, safe_rollback_time"]
B --> D["守护进程/监视器层<br/>稳定写入，排除，移动检测"]
D --> E["路径安全性和策略<br/>受保护的模式，符号链接，大小限制，速率限制"]
E --> F["对象存储<br/>.safefs/objects, 可选 gzip"]
E --> G["时间线<br/>.safefs/timeline/events.jsonl"]
C --> H["回滚引擎<br/>dry-run, 冲突检查，恢复"]
F --> H
G --> H
H --> I["工作区文件"]
H --> J["抑制标记<br回滚和旧被重新记录 --> D
数据流
`auto-guardguard` 或 为工作轻量级监。
2.编辑文件。SafeFS 不要求代理写入工具. 监视写入变得稳定安全的路径，并寻址对象. 大批量周期限制记录；剩余的稳定更改起，等待下一个5. 时间已提交的文件更改，包括写入、删除和移动操作。
6. `safe_diff` 和 `safefs diff` 计算回滚将7. `safe_restore_file` 在不触及无关文件的情况下，从检查点恢复选。
8._rollback_time` 和 `safefs rollback` 在更改文件当前哈希。
9. 回滚抑制防止 将其自身的恢复操作记录为新的代理编辑。
### 设计原则
- 保护原生编辑每个代理选择
- dry-run-first 恢复而不是破坏性自动化
- 保持项目数据本地且可检查
- 即使用户配置宽松，也保护机工作区内部信息
- 保持，适用于真正的仓库，而不仅仅是演示 开发
```pnpm install
pnpm lint
pnpm test
pnpm build
npm pack --dry-run
```
## 发布检查清单
1. 在本地确认 `pnpm audit`、`pnpm lint`、`pnpm test`、`pnpm build`、`npm pack -- 和 `/cli.js --help均通过。
2. 运行一个干净项目的烟雾测试：全局安装、`safefs init --yes --clients claude --auto-guard`、shell 激活、包装器启动、`safefs diff 10m` 和回滚 dry-run。
3. 推送并等待 GitHub Actions 变绿。
4. 使用 `npm publish --access public` 发布。
5. 使用 `npm view @tekergul/safefs-mcp version` 和 `safefs doctor --online` 验证 npm。
6. 使用 1.2 说明创建 GitHub 发布；演示 GIF/徽标润色可以在发布后跟进。
## 许可证
MIT
