给单文件AI编辑套上安全锁：路径作用域账本实战

AI模型能在几秒内生成一个修复补丁，但"更快"从来不等于"更安全"。当你想让一个标题修复器只改动一个文件时，模型草稿却可能顺手在旁边多碰一个文件——在一个疲惫的工作日夜晚，你真的能当场发现这个"溜号"吗？

本文介绍一种轻量级的防护思路：在执行任何AI生成的单文件编辑之前，先建立一个"路径作用域账本"（path-scope ledger）。它只回答一个直白的问题——这次编辑究竟允许改动哪些确切路径？

这个账本到底在守护什么

账本不是人工代码审查的替代品。它在任何 apply 命令执行前，只做一次干脆利落的判断：这次任务允许哪些路径发生变化？

如果答案模糊，任务立即停止。即使是一个干净的 diff，只要路径范围过宽，也算失败；缺少证据同样算失败，而不是一句温和的警告。作者把"作用域蔓延"（scope creep）当作要让它变得醒目的头号Bug——所谓"凭感觉编码"（vibe-coded）的补丁，往往就是因为悄悄碰了一个没被点名的文件而翻车。

核心理念是fail-closed（默认拒绝）：除非证明补丁老老实实待在白名单内，否则一律拒绝执行。

第一步：冻结允许改动的路径

在模型开口之前，先选定一个文件并把它写下来。这个文件就是今晚编辑的全部契约。如果需要改第二个文件，那就另开一个任务。

mkdir -p evidence fixtures
printf '%s\n' 'src/titles.py' > evidence/allowlist.txt
wc -l evidence/allowlist.txt

为什么要冻结单个文件而不是整个目录？因为第二个文件会把作用域蔓延藏在一个"看起来友好"的 diff 里。一个检验标准是：你能用一句诚实的话同时解释两处改动吗？如果需要一整段才能说清，那这个任务其实已经是两个任务了，先拆开再去求助模型。宽泛的提示词，只会招来你并未请求的宽泛补丁。

第二步：捕获提案，而非直接应用

向模型索要一个统一 diff（unified diff）并把它保存成文件。先别 apply、别 commit、也别 stage。保存下来的 diff 只是一份"提案"，不是"通行证"。

test -s proposal.diff
git apply --check --verbose proposal.diff

需要注意的是，--check 只验证补丁能否被应用，它并不能证明路径是否落在白名单之内——那个证明属于下一步的账本。给模型的提示词要刻意保持"无聊"：在提示文本中点名允许的文件，并要求它在回复中拒绝其他一切路径。

统一 diff（unified diff）是 Unix/Linux 世界中最通用的补丁格式，由 diff -u 命令产生。每个文件块以 --- a/ 和 +++ b/ 标注原始路径和目标路径，后跟若干"hunk"——每个 hunk 以 @@ 行标记上下文位置，以 - 开头的行表示删除，以 + 开头的行表示新增，不带前缀的行为上下文行。git apply --check 命令会模拟应用这个格式的补丁，验证其能否无冲突地打入当前代码树，但它只做语法和上下文的合法性验证，并不解析路径语义。这正是文章所强调的：--check 是必要条件，却不是充分条件——路径是否落在白名单之内，需要账本脚本单独完成这一层判断。

第三步：运行作用域账本

账本的核心是一段几十行的 Python 脚本 scope_ledger.py，无需安装任何第三方库，标准库足矣（面向 Python 3.9+，因为用到了内建类型注解）。脚本做的事情很直接：

• 解析 diff 中所有 +++ b/ 开头的目标路径；
• 与白名单比对，列出越界路径；
• 检查文件数量是否超预算（默认 max_files=1）；
• 用一个粗糙的正则扫描是否出现密钥模式（如 AKIA...、api_key= 等）；
• 任何一条命中都写出失败卡片，并以退出码 2 返回。

def judge(allow, diff, max_files):
    paths = DIFF_PATH.findall(diff)
    unique = sorted(set(paths))
    extra = sorted(set(paths) - allow)
    reasons = []
    if not diff.strip():
        reasons.append("empty-diff")
    if not unique:
        reasons.append("no-target-path")
    if extra:
        reasons.append("path-outside-allowlist:" + ",".join(extra))
    if len(unique) > max_files:
        reasons.append("file-count-over-budget")
    if SECRET.search(diff):
        reasons.append("secret-pattern")
    return {"pass": not reasons, "allow": sorted(allow),
            "paths": unique, "reasons": reasons}

运行方式：

python3 scope_ledger.py \
  --allow evidence/allowlist.txt \
  --diff proposal.diff \
  --out evidence/scope-card.json
echo "exit=$?"

退出码 0 表示通过卡片已写入磁盘；退出码 2 表示停止，而且通过卡片绝不能残留。关键一点：不要让 apply 脚本忽略这个退出码，哪怕 diff 只有几行。要把后续命令串联成"卡片缺失即中止"的流程。

退出码（exit code）是 Unix 进程与调用方之间最可靠的通信契约。进程正常结束返回 0，任何非零值均表示某种错误或拒绝状态。脚本选择 2 而非 1 作为失败码，是一种刻意的语义区分：1 通常代表通用错误，2 在 shell 惯例中常用于"用法错误或条件不满足"，便于调用方在管道（pipeline）或 &&/|| 串联中精确区分"脚本崩溃"与"账本主动拒绝"这两种不同情形。文章特别强调"不要让 apply 脚本忽略退出码"，正是因为许多自动化脚本默认只检查命令是否能运行，而不检查它运行后是否同意放行——这是静默失败最常见的入口。

第四步：保留一个失败夹具

没有红色测试的闸门只是一厢情愿。作者建议存一个故意触碰第二个文件、并植入假密钥字符串的坏 diff，用来验证闸门确实会报警。

cat > fixtures/two-files.diff << 'EOF'
--- a/src/titles.py
+++ b/src/titles.py
@@ -1 +1 @@
-old title
+new title
--- a/src/notes.py
+++ b/src/notes.py
@@ -1 +1 @@
-note
+api_key=EXAMPLE_DO_NOT_USE
EOF

预期结果是退出码 2、生成 scope-card.fail.json、且不存在 scope-card.json。这个红色夹具是脚本的回归锁——绿色演示通过后也不要删除它，每次改动脚本后都应重跑。如果这个夹具竟然"通过"了，那说明账本在骗你。

回归测试（regression test）的核心价值在于：每次你修改一段代码，都能立刻知道原本应该失败的场景是否仍然失败。对于安全闸门而言，"红色夹具"的重要性甚至高于"绿色演示"——一个从不报警的闸门和一个不存在的闸门没有区别。软件工程中有一个反模式叫"假阳性绿灯"（false green），即测试套件全部通过，但其中某些测试的断言逻辑已经失效，它们永远不会变红。存储一个故意违规的 diff 文件并纳入每次 CI 或手动回归，就是对抗这一风险的最小化实践——它直接检验闸门的"牙齿"而非闸门的"外壳"。

第五步：只在通过卡片背后执行应用

真正 apply 之前，先读通过卡片，pass 字段缺失或为 false 就拒绝任务。应用后还要再做一道"暂存名核对"：

git apply --index proposal.diff
git diff --cached --name-only > evidence/staged.txt

import sys
allow = {ln.strip() for ln in open("evidence/allowlist.txt") if ln.strip()}
staged = {ln.strip() for ln in open("evidence/staged.txt") if ln.strip()}
sys.exit(0 if staged and staged <= allow else 4)

账本检查的是 diff 文本的路径作用域，而这第二次核对捕捉的是"应用过程本身发生漂移"的情况。双重保险，缺一不可。

可直接抄用的 fail-closed 规则

作者给出了一张清晰的闸门对照表，每一行都点名了证据文件与停止条件：

闸门	证据	何时默认拒绝
路径冻结	allowlist.txt	缺失、为空、或多于一条路径
提案保存	proposal.diff	缺失、为空、或 git apply --check 失败
作用域匹配	scope-card.json	任何路径越出白名单
文件预算	卡片 paths 字段	diff 中文件多于一个
密钥嗅探	卡片 reasons 字段	命中模式，哪怕是占位符
应用锁	退出码 0	卡片缺失、pass 为假、或暂存名漂移

除此之外还有三条"直接放弃"的规则：白名单扩张到超过单个目录就停；模型今晚吐不出统一 diff 就停；免费服务器跑不了脚本也停。等一晚，远比一次意外提交划算。尤其要警惕——程序崩溃本身也是一个"停止"信号，千万别捕获异常再打印一行"友好的成功"，那正是静默失败混进生产的方式。

适合与不适合的人群

这个方案并非万能。作者坦率列出了应当跳过的场景：今晚需要多服务发布、法务要求正式控制框架、或是跨多文件重命名符号——面对宽泛重命名，账本会"尖叫"，而且理应如此。如果你还读不懂统一 diff，那应该先学会 apply check，再去信任任何卡片输出。

最契合的使用者，是"单文件 + 临时分支"的独立开发者；已经逐块审查每个 hunk 的小团队也能用上这个红色夹具。其余所有人，都应保留人工 diff 审查。

作者毫不掩饰的局限

难得的是，文章对自身方法的边界非常诚实：

• 密钥检查只是一个粗糙的正则，会漏掉真实泄露，也会在文档上误报——每次命中都当停止信号并亲自读 hunk；
• 白名单不判断"允许文件内部"的行为，一个单文件 diff 照样可能删掉你需要的函数，卡片只证明路径作用域，不证明代码正确；
• 过时的失败卡片可能和新的通过卡片并存，退出码才是真正的锁，而非残留的文件名。

披露：原文作者说明本文为 MonkeyCode 产品外联的一部分，用它获取免费模型草稿和免费服务器运行闸门。但作者反复强调——账本本身比执行它的宿主更重要。任何本地模型加一个临时克隆仓库，都能喂给同一个闸门。

这篇实战教程的真正价值，不在于某个特定工具，而在于一种思维方式：**在 AI 的速度落地之前，先给它装一个小小的刹车。**模型变快了，但 apply 这一步并没有自动变安全——而安全，恰恰需要你自己亲手去冻结那一条路径。