跳到正文
DEV Community· Hanako H.·· 12 天前精選AI 評分76

為甚麼 git checkout 無法還原 AI 編碼智能體操作前的專案狀態?

Perché git checkout non riesce ad annullare quello che ha cambiato un agente di coding AI?

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