安全文件编辑 Sun-beining/ai-safe-edit

ai-safe-edit

让 AI 改文件变得安全的唯一入口。 改前备份 · 改后校验 · 失败自动回滚 —— 绝不留下半坏的文件。

English · MIT · Python 3.8+ · 零依赖

它解决什么问题

AI 改文件，本质是"写文本"。而当这些文本来自 shell heredoc、正则替换、或模型生成的代码时，下面三件事发生的频率高到真的会伤到你：

| 失败类型 | 会发生什么 |
| shell 转义吃字符 | heredoc 里的字面量 \n 变成真换行，把它所在的字符串悄悄截断 |
| 正则超范围匹配 | 本想只动一行的模式跨过了字符串边界，把旁边的代码也改坏 |
| 嵌套引号 | 生成代码时在 " 里写 " —— 语法错，而模型相当常犯 |

通常的反应是"把教训记下来"。但那不是约束。 下一个会话、下一个模型，照样会犯。

真实数字（来自这个工具诞生的项目）：一天之内犯了 10 次嵌套引号错误，而且全都落进了产物文件 ——因为改动绕过了那个本来就是为了防这事而做的工具。

再补一条小自白，因为它是最清楚的例证：在写【这个仓库自己】的提交信息时，同一类失败又发生了。
信息里有一处 --selftest ，套在 shell 的双引号字符串里。
shell 执行了反引号，把那个词删掉了。
提交就这么进去了，句子缺了主语 —— 而且会一直错着，因为没人检查提交信息。

"知道这个坑"不等于"不会踩"；只有闸门才算。

它做什么

把"教训"变成一个闸门：

1. 改前备份 → .safe_edit_backup/<时间戳>/
2. 改后立即校验： .py → compile() · .json → json.loads · .yaml → yaml.safe_load · .bat → ASCII-only 检查
3. ★ 校验失败 ⇒ 自动回滚，并明确报告
4. 退出码非 0 —— 模型或脚本不可能漏掉

半坏的文件永远不会留在磁盘上。

快速开始

带安全网地改
python safe_edit.py --file app.py --replace "旧文本" "新文本"

多文件同一替换
python safe_edit.py --files a.py b.py --replace "旧" "新"

★ 大段文本（含引号 / 中文）：两边从文件读—— 这是"shell 参数转义不可靠"时该用的模式
python safe_edit.py --file app.py --replace-with-file old.txt new.txt

只验不写
python safe_edit.py --check-only a.py b.py

回滚到最近一次备份
python safe_edit.py --rollback app.py

自检：阳例 + 阴例对照
python safe_edit.py --selftest

失败时你会拿到一份毫不含糊的报告，而且文件是干净的：

x app.py 改 1 处后校验失败 ⇒ 已自动回滚：语法错 line 207: invalid syntax （备份 .safe_edit_backup/20261015-213510/app.py）
==> 1 个失败（已回滚）—— 调用方必须知道这次没改成 (退出码 1)

从 AI Agent 里用（MCP）

mcp_server.py 把它通过 MCP 暴露出来 —— stdio + JSON-RPC 2.0， 不需要装任何依赖。工具：safe_edit / edit_check / edit_rollback。

{
"mcpServers": {
"ai-safe-edit": {
"command": "python",
"args": ["/绝对路径/ai-safe-edit/mcp_server.py"]
}
}
}

任何 MCP 客户端都能用 —— 包括 DeepSeek Harness、Claude Code、Cursor 等。

为什么要"强制"走它

一个能自由写文件的 agent，迟早会写出一个坏文件。
问题不在于"会不会"，在于：这个失败是当场暴露 + 回滚，还是很久以后以"某个没人记得改过的文件报了个怪错"的形式暴露。

这个项目用血换来的两条结论：

- "写下来的教训"不是约束，"变成闸门的教训"才是。
- 失败必须让调用方知道。 静默的成功比响亮的失败更糟 ——一个以为自己改成功的 agent，会在坏文件上继续盖楼。

诚实的局限

- 它不能判断改动对不对 —— 只能保证"改完还能解析"。
语义正确性仍然要靠测试、闸门、和人。
- 它拦不住绕过。想让绕过至少留下痕迹，见下面的配套工具。
- 目前校验 .py / .json / .yaml / .bat。其他后缀会备份 + 写入，但不校验。

配套：check_edit_discipline.py

"绕过零成本"是这套东西最大的漏洞。 配套的检查器补上它：

每次成功改动后记下文件的哈希；检查器比对"当前哈希 vs 最后记录"，报出 「这个文件改过，但没走 safe_edit」 —— 把静默的绕过变成可见的。

python check_edit_discipline.py # 检查
python check_edit_discipline.py --init # 建基线
python check_edit_discipline.py --selftest # 自检（含"绕过必被抓"的阴性对照）

相关工作

这个工具是在一个硬件设计 agent 项目里独立长出来的。做成之后，我们读了 DeepSeek Harness 的源码，发现它从另一端解决同一类问题： 让实验固化必须经过用户明确批准（install_bundle + pendingBuilds），所以模型写的东西不经人批准就进不了持久配置。

两者是互补的：

| | DeepSeek Harness | ai-safe-edit |
| 思路 | 阻止 —— 改动要先批准才能留存 | 兜住 —— 改动要校验，坏了就回滚 |
| 强项 | 未授权的东西写不进去 | 坏掉的东西活不下来（哪怕是绕过改的） |

许可

MIT