為 AI 作品進行版本管理
人們與 AI 迭代時常常遺失好版本：重新產生會覆蓋、復原會跑過頭、或是對話偏離主題。此技能讓每一次變更都變成一個編號版本，並保留到使用者刪除它為止，讓使用者能查看、比較並回到任何先前的狀態。
三條規則
- 每一次變更都產生一個版本。 使用者請求一次且變更了檔案，就產生一個版本，並在該次對話結束時、在你回覆之前儲存。按請求而非按檔案編輯來儲存，能讓歷史記錄保持可讀性。
- 回溯絕不刪除版本。 只有腳本能寫入
.ai-versions/。絕對不要編輯、移動或刪除其中的任何內容，即使使用者要求清理也不行。請引導使用者使用backup。 - 回溯本身就是一個新版本。 使用腳本進行還原；絕不要靠記憶重建舊作品。還原會儲存為一個新版本，因此它也可以被復原。
腳本會自動選擇每個版本號碼。絕不要自行猜測；請回報它印出的號碼。
每個專案選擇一次模式
- 你可以執行命令並編輯檔案（Claude Code、Cursor、Codex、Windsurf、Copilot、Gemini CLI、Replit Agent、具備程式碼執行功能的 claude.ai）：使用下面的檔案模式。
- 專案有
.github/workflows/ai-versions.yml：它使用 GitHub 版本層。不要執行init。相反地，每次變更時，覆寫.ai-versions/pending.json；要回溯時，寫入.ai-versions/restore.json。兩者都在 assets/rules/github-layer-rules.md 中說明。 - 你無法執行命令（純文字聊天）：請遵循 references/chat-mode.md。
- 使用者在 Lovable、Bolt 或 v0（Bolt 和 v0 仍在測試中：尚未實際測試）、或 Figma Make 中建構，並詢問如何在那裡進行版本管理：請閱讀 references/app-builders.md。
檔案模式
腳本是此技能資料夾（即存放此 SKILL.md 的資料夾）內的 scripts/aiv.py。使用其完整路徑呼叫它，並透過 --root 指向專案：
python3 "<此技能的資料夾>/scripts/aiv.py" --root "<專案資料夾>" <命令>
# Windows：使用 py 而非 python3
經過 init 之後，每個專案也都有自己的副本，因此從專案資料夾執行 python3 .ai-versions/aiv.py <命令> 效果相同。以下，aiv 代表上述任一種形式。如果未安裝 Python，請告知使用者需要安裝它（python.org），並在安裝完成前使用聊天模式。
開始
在一個沒有 .ai-versions/ 的專案中進行第一次編輯之前，請先執行 init。它會將目前的檔案儲存為 v1.0.0，讓使用者永遠可以回到你碰觸它們之前的狀態。
如果資料夾包含的範圍比專案大（例如沙盒、家目錄、下載目錄），請設定範圍：init --only poster.html assets/。init 會拒絕超過 5,000 個檔案的資料夾，因為這通常表示指定了錯誤的資料夾。
每次變更之後
aiv save --bump minor --summary "新增了一個含三種方案的定價區塊" \
--reason "新區塊；佈局與樣式不變" --prompt "新增含三種方案的定價區塊"
--bump | 向使用者顯示為 | 使用時機 |
|---|---|---|
patch | 微調 | 功能相同，小幅調整：文字、顏色、間距、大小、小修正 |
minor | 新功能 | 新增功能，方向一致：區塊、頁面、元件、功能 |
major | 重大變更 | 方向改變：重新設計、新佈局、新樣式系統、移除功能 |
單次請求包含多項變更時，採用最高層級。若在兩個層級間不確定：採用較低者，並在 --reason 中說明。邊緣案例（文件、重構、內容更新）請參閱 references/bump-levels.md。
--summary 應為使用者而非開發者撰寫：「讓主視覺圖變大了」，而非「更新 Hero.tsx」。將使用者的請求簡短為一行，放在 --prompt 中。
然後在回覆結尾加上一行，例如：已儲存 v1.3.0（新功能）：新增了一個含三種方案的定價區塊。
如果 save 指出檔案與舊版本完全相符，它會將此次儲存記錄為回到該版本。請告知使用者發生了這種情況。
當使用者要求時
| 使用者說 | 執行 | 然後 |
|---|---|---|
| "顯示版本", "歷史記錄" | list | 顯示一個簡短表格。若要視覺化時間軸，請執行 view 並分享它產生的 HTML 檔案。 |
| "v1.3.0 改了什麼" | diff v1.3.0^ v1.3.0 | 用白話文解釋。vX^ 表示 vX 的前一個版本。 |
| "比較 v1.2 和 v2.0" | diff v1.2.0 v2.0.0 --stat，然後不帶 --stat 看細節 | 說明變更了什麼、哪裡變好了、哪裡變差了。如果你能呈現作品（HTML、圖片），請將兩者並排顯示。 |
| "回到 v1.2.0", "復原那個" | restore v1.2.0 或 restore prev（用於復原） | 然後執行下面的步驟。 |
| "只恢復舊的頁首", "保留新文字但用舊設計" | restore v1.2.0 --path <檔案> | 只有那些檔案會變更；它會儲存為一次微調。 |
| "從 v1.2.0 嘗試另一個方向" | restore v1.2.0 | 然後進行新的變更並照常儲存。 |
| "目前版本是什麼", "有沒有未儲存的變更" | status | |
| "把 v1.2.0 的檔案給我" | export v1.2.0 --out v1.2.0.zip | |
| "在其他聊天或工具中繼續這個" | backup --out history.zip | 在另一個地方：import history.zip。 |
當使用者含糊地提到某個版本時（「那個藍色的」、「改版之前的」），請執行 list 並比對摘要。如果兩個版本都符合，請詢問使用者是哪一個。
回溯之後
完整的還原會將所有專案檔案回復到先前的狀態，包括使用者可能不認為是作品一部分的檔案，例如筆記或資料。請告知使用者哪些檔案變更了（腳本會列出它們）。如果它先儲存了未儲存的作品，請說明哪個版本包含了它，並提議使用 restore <該版本> --path <檔案> 來恢復特定檔案。當請求明確只針對專案的一部分（「舊的顏色」）時，請直接從一開始就使用 --path。
在進行下一次變更之前，請執行 handoff <你還原的版本> 並將其輸出視為目前的事實依據。它只會列出導致該版本的決策，並標明被放棄的決策，這樣來自被拋棄方向的指令就不會悄悄回來。如果對話很長，請提議切換到一個新的聊天室，並將 handoff 的文字提供給使用者貼上。
忘記儲存的安全網
在 Claude Code 或 Cursor 中，每個專案提供此選項一次：install-hooks claude-code 或 install-hooks cursor。它會新增一個鉤子，在你完成時將你忘記儲存的任何變更儲存為一次微調。僅在使用者同意後才安裝它，因為它會寫入他們的工具設定。
談論版本
使用使用者的用語：微調、新功能、重大變更、已回溯。提及版本號碼，而不是提交紀錄、.ai-versions/ 中的檔案或雜湊值。特定工具的注意事項（claude.ai、Replit、Windows）在 references/tools.md 中。
當使用者回溯時，提醒他們一次：只有檔案會回來；資料庫行和其他即時資料會維持原樣。
所有命令
| 命令 | 功能 |
|---|---|
init [--only 路徑...] | 開始歷史記錄並儲存 v1.0.0 |
save --bump B --summary S [--reason R] [--prompt P] | 將目前檔案儲存為新版本 |
status | 顯示目前版本與未儲存變更 |
list [--all] [--json] | 顯示版本清單，最新的在前 |
show V | 顯示單一版本的詳細資訊與變更的檔案 |
diff [A] [B] [--stat] [--path P...] | 無參數：未儲存變更。一個參數：A 到最新。兩個參數：A 到 B |
restore V [--path P...] [--note N] | 回溯（所有檔案或僅部分）；先儲存未儲存的作品，再將還原儲存為新版本 |
handoff [V] | 清理從 V 繼續的上下文 |
view [--out FILE] | 所有版本的 HTML 時間軸 |
export V --out DIR_or_ZIP | 匯出單一版本的檔案 |
backup --out FILE.zip / import FILE.zip | 移動完整的歷史記錄 |
install-hooks claude-code|cursor | 自動儲存 AI 忘記的內容 |
setup-github [--with-pill] | 為應用建構器儲存庫新增 GitHub 層 |
doctor | 檢查歷史記錄是否有遺失的部分 |
版本可以寫成 v1.2.0、1.2.0、latest、prev 或 v1.2.0^。