Agent-Checkpoint：Cursor AI 代理的預編輯快照與版本追蹤工具

大家好！和許多人一樣，我日常開發工作非常依賴 Cursor 的 Composer / Agent 模式。然而，在快速的多輪提示詞對話中，我經常遇到一個令人頭痛的問題：Cursor Agent 有時會產生幻覺、重寫半個正常運作的模組，或是在你檢查之前就覆蓋掉客製化的邏輯。

儘管 Cursor 內建了檢查點功能，但一旦你接受了某個編輯並執行了三到四個提示詞後，要單獨回溯某個特定檔案，同時又不影響 Git 樹中其他無關的良好進度，可能會非常棘手。此外，團隊成員在拉取程式碼時，也完全不知道 AI 修改了什麼以及原因。為了解決這個問題，我開發了 Agent-Checkpoint，這是一個開源、零依賴的溯源協定，它直接透過你的 .cursorrules 運行。

Agent-Checkpoint 在 Cursor 中的運作方式如下：每當 Cursor Agent 修改專案中的現有檔案時，它會自動遵循一個三步驟的工作流程。首先是「預編輯快照」，在觸碰任何檔案之前，它會在 .snapshots/<filename>_v<OLD_VERSION>.<ext> 建立一個原始副本。

接著是「語義影響分類」，Cursor 會將其自身的變更歸類為提示詞層級的語義化版本（SemVer）。其中，MAJOR 代表架構或破壞性介面變更；MINOR 代表新增功能或非破壞性模組；PATCH 則代表錯誤修復、重構或錯字修正。

最後是「雙帳本稽核追蹤」，它包含兩個部分：.snapshots/manifest.json 是一個緊湊的機器索引，用於快速的語義回溯和檢索；REVISION_LOG.md 則是一個人類可讀的變更日誌，記錄了確切的修改行數、語義分類和變更理由。

在 Cursor 中設定 Agent-Checkpoint 僅需 30 秒。你不需要任何 Node 套件、Python 腳本或背景常駐程式，只需將現成的轉接規則複製到你的 .cursorrules 中即可。你可以在這裡查看 Cursor 轉接器，然後像往常一樣向 Cursor 發出提示詞。

當你要求 Cursor 重構或更新檔案時，它會自動快照先前的狀態，分類語義化版本變更，並將一個條目附加到你的 REVISION_LOG.md 中。

在基準測試與安全性方面，Agent-Checkpoint 對儲存空間很友善，依政策排除二進位檔案和超過 1 MB 的檔案。活躍的日常使用每月只會產生約 15 到 50 MB 的純文字快照。它還能與 Cursor 內建的 Claude 3.5/3.7 Sonnet、GPT-4o 和 Gemini 模型無縫協作。

由於這是一個完全開源（MIT 授權）的專案，我非常樂意聽取其他 Cursor 進階使用者的意見。例如，當 Composer 觸及多個檔案時，你目前是如何處理快速回溯的？你希望協定涵蓋哪些邊緣案例？歡迎提供回饋和提交拉取請求（PRs）。