為甚麼 git checkout 無法還原 AI 編碼智能體操作前的專案狀態?
Perché git checkout non riesce ad annullare quello che ha cambiato un agente di coding AI?
作者提出按回合保存檔案前置內容的 checkpoint 方法,可還原 AI 編碼智能體操作前的專案狀態,這是 git checkout -- . 無法做到的。在 4,686 個檔案的 TypeScript 原始碼樹測試中,checkpoint 逐檔還原一致;四種 Git 復原方案都至少有檔案與回合前狀態不同。
文章以逐檔比較呈現 Git 復原方案的邊界,並示範按智能體回合保存檔案前置內容,保留用戶未提交修改並清除智能體新建檔案。
當 AI 代理程式修改專案檔案並弄壞某些東西時,第一反應是 git checkout -- . 或 git stash。兩者回答的都不是你真正想問的問題。Git 可以讓你回到最近一次提交。你想要的是代理程式執行前一刻的資料夾狀態,包括尚未提交的工作和 git 忽略的檔案,但不包括代理程式建立的檔案。
osFoundry 桌面應用程式以一個用 Rust 編寫、按內容定址的小型儲存區解決這個問題,checkpoint_store.rs。在代理程式寫入檔案之前,檔案目前的位元組會先儲存到 <project>/.osfoundry/checkpoints/blobs/<sha256>,而 /rewind 會將其寫回。以下是相同設計的 Python 版本,約 90 行,只用標準程式庫;並與四種 git 做法作比較,在一次貼近實際情況的代理程式回合中測試,並於一份包含 4,686 個檔案的 TypeScript 原始碼樹副本上計時。
一個回合,五種還原方法
測試專案是 Git 儲存庫內的一個極小網站:index.html、styles.css(212 行)、app.js,以及一個被 .gitignore 忽略的 .env。最近一次提交後,用戶把頁面標題改成 index.html,並開始處理一個未追蹤的 notes.md。這就是需要還原的狀態。
接着是代理程式回合:它把 styles.css 重寫成只有 41 行,修改 index.html 以載入新的 theme.css,重寫 app.js,讓 API_URL 中的 .env 指向 localhost,並建立 theme.css。每種還原方法都在乾淨的副本上執行,並由指令碼逐位元組比對每個檔案與回合開始前的狀態。
checkpoint restore matches the state before the turn: True differs: []
git checkout -- . matches the state before the turn: False differs: ['.env', 'index.html', 'theme.css']
git stash -u matches the state before the turn: False differs: ['.env', 'index.html', 'notes.md']
git checkout + git clean -fd matches the state before the turn: False differs: ['.env', 'index.html', 'notes.md']
git stash create before the turn matches the state before the turn: False differs: ['.env', 'theme.css']
| 方法 | 問題 |
|---|---|
git checkout -- . |
用戶對標題的修改會連同代理程式的修改一併遺失,theme.css 仍然存在,而 .env 保留代理程式設定的值 |
git stash -u |
代理程式的修改、用戶對標題的修改和 notes.md 全部放進同一個 stash,而 .env 保留代理程式設定的值 |
git checkout + git clean -fd
|
theme.css 會被移除,但 notes.md 也會被移除;標題修改會消失,而 .env 保留代理程式設定的值 |
回合開始前的 git stash create |
所有已追蹤的內容都會還原,但 theme.css 仍然存在,而 .env 從未納入快照 |
| 還原檢查點 | 與回合開始前的狀態一致 |
Git 的結果取決於 Git 本身的運作方式。還原至最近一次提交,或還原已追蹤及已暫存檔案的快照;只要你和代理程式的工作都尚未提交,這兩種方式都會把兩者混在一起。git 忽略的檔案不會被看見,除非你加入 -a;而 checkout 絕不會刪除快照中不存在的檔案。最後一行是最誠實的 git 設定:每個回合開始前都建立快照,但仍有五個檔案中的兩個還原錯誤。它還有一個副作用:git add -A 會在每個回合把你的所有工作暫存到真正的索引中。
儲存區
檢查點是一份按回合整理的清單:對於代理程式寫入的每個檔案,會記錄其先前內容的雜湊值,或註明該檔案原本不存在。每種不同內容的位元組只會儲存一次,放在 blobs/。
import hashlib, json, os, time
from pathlib import Path
MAX_BLOB = 8 * 1024 * 1024
class Checkpoints:
def __init__(self, root):
self.root = Path(root).resolve()
self.dir = self.root / ".osfoundry" / "checkpoints"
self.blobs = self.dir / "blobs"
self.index_file = self.dir / "index.json"
try:
self.index = json.loads(self.index_file.read_text())
except (OSError, ValueError):
self.index = []
def _save(self):
self.dir.mkdir(parents=True, exist_ok=True)
tmp = self.dir / "index.json.tmp"
tmp.write_text(json.dumps(self.index))
os.replace(tmp, self.index_file) # a half-written index loses everything
def capture(self, turn, label, path):
path = str(Path(path).resolve()) if Path(path).exists() else str(Path(path).absolute())
if not self._contained(path):
raise ValueError("outside the workspace: " + path)
cp = next((c for c in self.index if c["turn"] == turn), None)
if cp and any(f["path"] == path for f in cp["files"]):
return # first write in a turn wins
try:
size = os.path.getsize(path)
except FileNotFoundError:
pre = {"kind": "absent"}
else:
if size > MAX_BLOB:
pre = {"kind": "skipped", "reason": f"{size >> 20} MB over the limit"}
else:
data = Path(path).read_bytes()
sha = hashlib.sha256(data).hexdigest()
blob = self.blobs / sha
if not blob.exists(): # identical bytes are stored once
self.blobs.mkdir(parents=True, exist_ok=True)
blob.write_bytes(data)
pre = {"kind": "content", "sha256": sha, "bytes": size}
entry = {"path": path, "pre": pre}
if cp:
cp["files"].append(entry)
else:
self.index.append({"turn": turn, "label": label[:120],
"at": time.time_ns(), "files": [entry]})
self._save()
def write(self, turn, label, path, data):
"""What an agent's write tool would call."""
self.capture(turn, label, path)
Path(path).parent.mkdir(parents=True, exist_ok=True)
Path(path).write_bytes(data)
有三項細節決定還原是否正確,而 Rust 模組也遵循這三項規則。
以一個回合中首次擷取的路徑為準。代理程式往往會在同一回合多次寫入同一個檔案。還原的目標是回到回合開始時的檔案狀態,而不是代理程式兩次寫入之間的中間狀態,因此同一回合中同一路徑之後的擷取都會被忽略。
缺失的檔案會記錄為 absent。正是這一行讓還原程序可以刪除 theme.css。Git 沒有「此檔案不應存在」的對應機制;唯一例外是 git clean,但它也會刪除你想保留的檔案。
超過 8 MB 的檔案會記錄為 skipped,並附上原因,而不是悄悄略過。因此,還原時會指出未能還原這些檔案,而不是一聲不響地結束,留下新舊檔案混雜的狀態。
還原:由最舊到最新
def restore(self, turn):
target = next(c["at"] for c in self.index if c["turn"] == turn)
affected = sorted((c for c in self.index if c["at"] >= target),
key=lambda c: c["at"]) # oldest first
done, report = set(), {"restored": [], "deleted": [], "failed": []}
for cp in affected:
for f in cp["files"]:
path, pre = f["path"], f["pre"]
if path in done:
continue
done.add(path)
if not self._contained(path): # re-check, the index is just a file
report["failed"].append((path, "outside the workspace"))
elif pre["kind"] == "skipped":
report["failed"].append((path, pre["reason"]))
elif pre["kind"] == "absent":
Path(path).unlink(missing_ok=True)
report["deleted"].append(path)
else:
Path(path).parent.mkdir(parents=True, exist_ok=True)
Path(path).write_bytes((self.blobs / pre["sha256"]).read_bytes())
report["restored"].append(path)
self.index = [c for c in self.index if c["at"] < target]
self._save()
return report
def _contained(self, path):
p = Path(path)
if ".." in p.parts:
return False
p = p if p.is_absolute() else self.root / p
while not p.exists(): # deepest existing ancestor, symlinks resolved
p = p.parent
return p.resolve().is_relative_to(self.root)
如果第 1 回合之後又進行了第 2 和第 3 回合,回退至第 1 回合就必須撤銷這三個回合。只還原第 1 回合,會令第 2 回合的檔案與第 1 回合之前的檔案並存,形成從未存在過的組合。還原次序同樣重要。對於在多個回合中都被修改的檔案,正確的位元組應來自最早的修改前內容,也就是在第 1 回合開始時擷取的內容。如果由最新回到最舊,得到的會是第 2 回合的修改前內容,也就是第 1 回合完成後的狀態。Rust 原始碼中有一則註解説明瞭這點:最初的寫法是由最新回到最舊,測試 rewinding_a_turn_also_undoes_later_turns 發現了這個問題。
還原時會再次檢查路徑,因為 index.json 是描述的資料夾內一個普通檔案。如果信任這個檔案,任何能修改它的人或事物,都可能令還原程序向磁碟上的任何位置寫入資料。之後,已撤銷的回合會從索引中移除,這樣再次回退至同一位置時,就不會在已還原的檔案上再次「成功」。
在實際資料夾中的成本
這個目錄樹是某個真實 React 和 TypeScript 應用程式的 src 資料夾副本:共有 4,686 個檔案,大小為 121.4 MB,沒有檔案超過 8 MB。每個回合都會隨機選取一些檔案、擷取內容並在每個檔案末尾加上一行,然後執行還原,並將每個檔案與原始版本比較。所有還原結果都一致。測試環境:Apple M1、8 GB、macOS 15、APFS SSD、Python 3.9.6、git 2.39.5。
| 回合 | 擷取 + 寫入 | 儲存空間大小 | 還原 |
|---|---|---|---|
| 4 個檔案 + 新增 1 個 | 3.5 ms | 少於 0.1 MB | 1.2 ms |
| 50 個檔案 + 新增 1 個 | 62.4 ms | 0.9 MB | 8.2 ms |
| 500 個檔案 + 新增 1 個 | 1,035 ms | 11.7 MB | 227 ms |
| 全部 4,686 個檔案 | 30.5 s | 122.7 MB | 1.3 s |
作為比較,上一個情境(git add -A,然後 git stash create)中每回合建立 Git 快照,在這個目錄樹沒有任何修改時需時 61 至 68 ms;修改了四個檔案時則需時 50 至 67 ms。每次都必須檢查全部 4,686 個檔案。重寫所有檔案的操作完成後,緊接着一次操作需時 1,241 ms,因為 git 會重新計算所有時間戳記已變更檔案的雜湊值。檢查點每次只需檢查有寫入的檔案,因此無論專案大小如何,一般回合都只需幾毫秒。
最後一行突顯了目前程式碼的一個問題。該回合最初 100 個檔案的平均擷取時間為 1.29 ms,最後 100 個則為 9.54 ms。每次擷取都會重寫整個 index.json;它的大小已增至 1.3 MB,因此每次寫入的成本都會隨先前的寫入次數增加。把 _save 改為每次擷取時追加一行 JSON,在同一個包含 4,686 個檔案的目錄樹上解決了這個問題:總共需時 2.5 s,最初每次擷取需時 0.41 ms,最後則為 0.61 ms。如果 Agent 每回合只修改少量檔案,簡單版本已足夠。如果要透過 Agent 格式化整個程式碼庫,或重新命名其中的項目,就應使用只追加的日誌。
內容定址能節省甚麼,又不能節省甚麼
以各 blob 的 SHA-256 值命名,只會對完全相同的位元組去重,除此之外不會做其他處理。三項測量結果展示實際可達到的效果。
整個檔案樹中,4,686 個檔案有 4,677 種不同內容,因此在整個檔案樹上執行一輪,會儲存 4,677 個 blob。真正的原始碼樹中,重複檔案並不常見。
一個 2 MB 檔案在十輪中被重寫,Agent 每輪都新增一行:十份修改前內容全都不同,共 10 個 blob、20.0 MB。同一檔案若 Agent 每輪都寫入相同位元組(例如重試時產生相同輸出),則只有 2 個 blob、共 4.0 MB:原始版本,以及後續每一輪開始時的版本。兩種情況下,回到第一輪都能逐個位元組還原原始檔案。
blob 以原樣儲存,不作壓縮。整個檔案樹那一輪產生的 121.4 MB blob,若以 zlib level 6 壓縮,會縮至 33.7 MB;同一檔案樹提交一次後,Git 的物件儲存庫則為 41.0 MB。若長期保留儲存庫,加入壓縮是合理的,因為原始碼的壓縮率約為 3.6:1。版本之間儲存差異(如 Git pack 檔案所用的方式)在新增一行的情況下能節省更多空間,但所需程式碼遠多於修改前內容儲存庫所需。
這個版本的限制
只會偵測經由 write() 的寫入。如果 Agent 亦可執行 shell 命令,rm 或 sed -i 就不會被偵測到。osFoundry 應用程式會讓 Agent 的檔案寫入統一經過同一個函式,並在該處擷取內容。
還原時會把修改前內容寫入檔案,不論檔案目前內容為何。如果 Agent 執行後你曾手動修改檔案,回退該輪也會覆蓋你的修改。更嚴謹的版本會記錄 Agent 寫入內容的雜湊值,並在還原前檢查檔案是否仍有該雜湊值。如果沒有,便會先將目前位元組儲存為另一個 blob,這樣還原操作本身也可以撤銷。
此外,只要不回退任何一輪,儲存庫就會持續增長。只需加入一個 prune,刪除沒有檢查點引用的 blob,並限制保留的輪數即可。
上面的兩個 class 區塊就是整個 store,使用 Python 3.9 和標準程式庫,毋須安裝任何東西。osFoundry 桌面應用程式會在使用本機資料夾的聊天中,以 /rewind 形式提供 Rust 版本,可從 osFoundry 下載頁面免費下載。
來源:DEV Community · dev.to