【2026 最新】Atlas Agent Source Control 教學：Claude Code／Codex Session 收據驗收

如果你正讓 Claude Code 與 Codex 輪流改同一個專案，這篇 Atlas Agent Source Control 教學要處理的不是「怎麼多開兩個聊天視窗」，而是一個更難回答的問題：某個 commit 到底來自哪次 session、當時下了什麼指令、工具做過什麼，以及改寫 Git 歷史後，這條關聯還找不找得回來？

Atlas 把 agent 對話、tool call、檔案變更與 Git commit 放進同一條 Timeline，形成 checkpoint。最容易記的心法是：Session 收據 ＝ Commit（結果）＋ Session（過程）＋ Linkage（兩者的可追查關聯）。它補的是 Git 看不見的「過程證據」，但不等於逐行作者鑑定，也不會替你隔離兩個 agent 的 working tree。

本文以 2026 年 9 月 5 日仍是最新公開版本的 Atlas alpha-0.3.0 為基準，帶你從安裝前檢查、關閉非必要 analytics、Claude Code／Codex 雙 worktree 實作，一路驗收到 amend、rebase、squash、失敗 session、secret redaction 與共享記憶污染。Atlas 的簽章與原始碼可以先查；功能結果仍應在合成測試 repo 裡自行重跑。

先講結論：Atlas 值得裝嗎？

值得小規模試用，但現在更像 provenance／observability 工具，而不是 Git 的替代品。如果你常在 code review 時追問「這段是誰叫 agent 改的、為什麼這樣改」，Atlas 的 checkpoint 很有價值；如果你真正的痛點是兩個 agent 同時覆寫檔案，優先解法仍是 Git worktree。

• Atlas 擅長：把候選 session 關聯到 commit，保留 prompt、tool call、diff 與時間線脈絡。
• Atlas 不保證：逐行 authorship、每個 commit 都有 checkpoint、任何 history rewrite 都能自動修復。
• 目前適合：macOS、願意在測試 repo 驗收 alpha 工具、需要跨 agent 稽核線索的個人或小團隊。
• 目前不適合：把它當秘密管理邊界、合規稽核唯一證據，或期待 Windows／Linux 已受官方 QA。

Git commit 已經有作者，為什麼還要 Session 收據？

Git commit 能回答「哪個帳號提交、哪些行改了、父 commit 是誰」，卻不會保存 agent 收到的 prompt、嘗試過的工具、失敗路徑或決策理由。就像餐廳帳單只列最後點了什麼，Session 收據則把點餐過程、退菜原因和廚房操作連回這張帳單。

依 Atlas 的 Timeline 文件與 alpha-0.3.0 原始碼，系統會觀察 Git 歷史，再以 session 曾觸碰的檔案、內容特徵與 patch-id 建立關聯；它不安裝 Git hooks、不改 Git config，也不寫 Git refs。這是一種啟發式 session-to-commit association：既有檔案主要看 touched path，新檔案還會核對內容，因此同一檔案被 agent、人類或多個 agent 交錯重寫時，不能把 checkpoint 說成「確切作者」。

真正好用的判準不是畫面上有沒有綠色勾勾，而是你能否從一個 commit 反查：

1. 哪一次 Claude Code 或 Codex session 被列為候選來源；
2. 當時的 prompt 與 tool call 是否足以解釋 diff；
3. commit amend／rebase 後，連結是否仍指向同一個語意變更；
4. 無法確定時，Atlas 是否誠實標成 orphan，而不是亂猜。

Atlas Agent Source Control 教學步驟 1：先鎖定版本與安裝邊界

先到 Atlas 官方網站或 GitHub Releases 下載。alpha-0.3.0 提供 Apple Silicon 與 Intel 的 DMG，官方支援範圍是 macOS 13 以上；README 對 Linux／Windows 的措辭仍是可從相同原始碼建置、尚未測試。不要把「能編譯」寫成「正式支援」。

安裝前，先把環境版本記進驗收紀錄：

sw_vers
uname -m
git --version
claude --version
codex --version

本文下載的 Apple Silicon DMG 以 macOS Gatekeeper 檢查為「accepted」，簽章顯示 notarized Developer ID，App 版本為 0.3.0；但這台撰稿環境沒有啟動 Atlas，也缺少它從原始碼跑完整測試所需的 Bun／Rust 工具鏈。因此後面的按鈕位置依官方文件整理，rewrite 與 redaction 的預期則來自 release tag 的程式與測試；你仍要在自己的隔離 repo 完成 UI 驗收。

Atlas Agent Source Control 教學步驟 2：先關 analytics，再開 Local capture

Atlas 主打 local-first，但「Atlas 的本機記錄層」不等於整套工作完全離線：Claude Code、Codex 仍會和各自服務通訊，而官方 DMG 的匿名 usage analytics 預設開啟。第一次開啟後，先做這四件事：

1. 進入 Settings → General，關閉 usage analytics。官方 Telemetry 說明稱事件不含 prompt、response、檔案路徑、tool 參數／輸出或 diff，但會含 agent／model、工具種類與次數、檔案副檔名與行數、token／cost／duration、OS／架構等操作中繼資料。
2. 若你曾登入 Atlas，再檢查「把匿名歷史連到帳號」的選項；不需要就不要開。這和單純關閉後續 analytics 是兩件事。
3. 從專案標題旁的 pill 選 Create → Local → Enable，啟用本機 session capture；確認專案出現健康狀態，而不是只看到 repo 已匯入。
4. 檢查 repo 的 ignore 狀態。Atlas 的專案資料可能出現在 .atlas/，不要在未審查內容前把它提交進產品 repo。

git status --short
git check-ignore -v .atlas/ 2>/dev/null || true

還有兩個網路例外容易漏掉：自動更新檢查有自己的 Updates 開關，不隨 analytics consent 一起關；你主動送出的 feedback 也走獨立路徑。若專案有嚴格網路政策，應以防火牆或封包記錄驗證，而不是只看一個 toggle。

步驟 3：Claude Code 與 Codex 必須分到兩個 worktree

同一個 issue 可以，同一個 physical checkout 不行。Atlas 能觀察 provenance；截至本文核對日，官方公開文件未承諾會替每個平行 agent 自動建立 worktree。最安全的教學拓撲是從同一個固定 base 建兩個 branch／worktree，讓 Claude Code 與 Codex 各自在自己的 working tree 寫入：

git worktree add -b agent/receipt-claude ../receipt-claude main
git worktree add -b agent/receipt-codex ../receipt-codex main
git worktree list

分別把兩個目錄加入 Atlas，再在各自 session 選對 agent。Claude Code 與 Codex 在 Atlas 裡是外部 ACP subprocess；一個 session 只屬於一個 agent，切換 agent 是建立／重設另一個 session，再靠 shared memory 或 handoff 串脈絡，不是把同一條對話原封不動換模型。

兩邊使用同一份、刻意受限的任務說明，例如：

只修改 docs/receipt-test.md。
寫入你的 agent 名稱、目前 branch，以及你選擇這個格式的理由。
不要修改其他檔案；完成後停下，等待我審查與 commit。

先看 git diff --stat 與內容，再由你自己 commit。等 Atlas Timeline 出現 checkpoint 後，逐一對照 prompt、tool call、changed files、diff 與 commit SHA。若畫面只證明「這個 session 碰過同一路徑」，就不要自行升級為逐行歸屬。

如果你還不熟悉這種隔離方式，可先讀 Nodeterm 多 Agent 空間教學與 Proliferate worktree 教學；兩者更偏向隔離與工作流，Atlas 則更偏向 session 與 commit 的追查關聯。

步驟 4：用 amend、rebase、squash 驗收 checkpoint

正常 commit 連得上只是起點。Atlas 原始碼以 stable patch-id 尋找改寫後的相同 diff；如果 diff 不變、patch-id 唯一，而且仍落在最近 200 個可達 commits 的修復掃描範圍內，amend／rebase 比較有機會重新連結。這不是「任何改寫都保證恢復」。

A. 正常 commit

完成一個單檔變更並 commit。預期 Timeline 有一個 checkpoint，session、檔案與 diff 都對得上。

B. Amend 但不改 diff

git commit --amend --no-edit

SHA 會改，diff 語意不變。預期 checkpoint 重新指到新 SHA；如果舊、新 SHA 同時顯示為有效，就記錄為異常。

C. Rebase 到更新的 base

先在測試用 base 加一個不衝突 commit，再 rebase agent branch。預期相同 patch 能重連；若 conflict resolution 改變了 diff，patch-id 也會改，orphan 反而可能是正確的保守行為。

D. Squash 兩個 commits

Atlas 的 rewrite tests 顯示，多 commit squash 後原 checkpoints 會 orphan、session 保留；它不應猜哪一段過程屬於新合成 commit。這不是單純的「功能壞掉」，而是證據已不足。你要驗的是 orphan 是否清楚可見、原 session 是否仍可匯出。

E. 失敗與中斷 session

讓 agent 執行一個必然失敗、但不具破壞性的命令，或在未完成 turn 時正常退出 App。Atlas 關閉時會停止受管的 ACP subprocess，重新開啟 store 時，未完成 turn 應被 reconcile 為 aborted；不要假設關掉 Atlas 後 agent 仍會在背景完成。

步驟 5：用假秘密驗證 redaction，不要拿真密鑰下注

Atlas alpha-0.3.0 的 checkpoint capture 會先經過多層 best-effort redactor，包含常見 provider prefix、credential URI／DSN、key-value 模式與高 entropy 字串。這能降低風險，卻不等於「秘密永不落盤」，更不會阻止 prompt 先被送到 Claude 或 OpenAI 的服務。

安全驗法是使用只為測試生成、永遠不能登入任何服務的 canary：

printf '%s\n' 'DEMO_ONLY_TOKEN=sk-test-NOT-A-REAL-SECRET-1234567890' > redaction-canary.txt
git status --short

1. 叫 agent 讀取並說明這個檔案，再觀察 prompt、tool output、diff 與 checkpoint 顯示。
2. 匯出 Session 的 Markdown 與 JSON，搜尋完整 canary。
3. 在你建立的測試帳號中，盤點專案 checkpoint store、agent transcript、shared-memory artifacts 與 feedback 畫面；不要只查 Timeline。
4. 確認 UI 顯示遮罩後，也測常見正常字串是否被誤遮，否則 redaction 可能讓收據失去可讀性。
5. 完成後刪除測試檔：rm redaction-canary.txt。

為什麼要查多個資料面？因為 release 原始碼的 checkpoint capture 明確呼叫 redactor，但另一條 agent transcript 儲存函式會直接序列化 message content，程式中看不到同樣的 redactor 呼叫。這只是從原始碼得到的風險推論，不是已證實 packaged App 洩漏；正因如此，驗收不能把一個畫面的遮罩擴張成全系統保證。

步驟 6：用 A/B 測試抓共享記憶污染

Atlas 的 shared memory 會把 project plan、decisions、changes、failures、architecture、facts 與相關 session 脈絡帶到後續 turn。它可能省下重講背景的時間，也可能把舊任務、錯誤決策或另一個 agent 的假設一起帶進來。

建立兩份全新的相同 repo：

1. A 組：關閉 shared memory，直接問「這個專案的 receipt policy 是什麼？只根據 repo 內證據回答」。
2. B 組：先在另一個 session 放入合成假規則 RECEIPT_TEST_POLICY=blue-otter，再開新 session 問同一題。
3. 兩組使用同一 agent、同一 model、同一 prompt，記錄答案是否引用不存在於 repo 的 blue-otter。
4. 再新增一份 repo 內的真規則，觀察 Atlas 是否優先採用新證據、能否指出來源，以及清除 UI 記憶後是否還會殘留。

若 B 組把假規則當事實，代表 handoff 有污染風險；若完全找不到已確認的真決策，則 retrieval 可能漏召回。截至本文核對日，官方公開資料未提供可比較的 precision／recall 或品質提升 benchmark，所以不要把「共享記憶」直接翻譯成「答案必然更好」。需要更完整的跨 session 思路，可延伸閱讀 Claude Code 跨 Session 協作與 Context Repo 教學。

Atlas、Git worktree、Nodeterm、Proliferate 怎麼選？

裸 Git worktree：先解決互相覆寫

Git 原生 worktree 讓同一 repository 有多個 checkout，各自擁有 HEAD、index 與 branch，並共享 object store。它不保存 prompt 或 agent session，但隔離是平行寫入的地基；即使裝 Atlas，高風險專案通常仍要 worktree。

Nodeterm：先看清楚誰在哪裡跑

Nodeterm 把真正 terminal、worktree group 與 agent session 畫成空間化 canvas，Context Link 偏向明確拉取另一節點的 transcript／summary。它適合「我要一眼看懂多個 agent 卡在哪裡」，Atlas 則偏「我要從 commit 追回 session」。

Proliferate：把隔離、review、publish 串成流程

Proliferate 的 workspace、worktree、diff scope、逐檔／hunk stage、review 與 publish 路徑較完整。要注意：同一 workspace 內的不同 agent 仍可能共享 checkout，worktree 也不會隔離 credentials、ports、processes 或 caches。

Atlas：當你最在意「為什麼會有這個 commit」

Atlas 的差異化是統一 Timeline、checkpoint 與本機 shared memory。它也不是 Claude→Codex 交接的唯一方案：OpenAI 已有官方 Codex plugin for Claude Code，Codex 本身也有 /import、resume、hooks 與本機 transcripts。Atlas 的賣點應放在持續觀察與關聯，不是宣稱別人無法交接。

若你想先理解更大的 agent 執行框架，再讀 AI Agent Harness 是什麼與 如何打造 Agent Harness。

alpha-0.3.0 的已知邊界

• 平台：官方支援與可下載 binary 目前只有 macOS；Linux／Windows 尚未完成官方 QA。
• Cloud capture：alpha-0.3.0 原始碼中仍是關閉狀態，本教學只談 Local capture。
• 既有 Claude Code session：Atlas 會掃描 ~/.claude/projects/ 匯入；它會讀取 JSONL 中可得的 messages、tool calls 與 usage，但刻意不建立 retroactive checkpoint，不可假裝它能回溯找到舊 commit。
• 既有 Codex session：Atlas alpha-0.3.0 的 Codex adapter 沒提供 Atlas 可解析、用來重建舊對話的 on-disk transcript；這不代表 Codex 自己沒有 transcripts、hooks 或 resume。
• 長尾 agents：官方 README 明說 registry 中其他 ACP agents 的 QA 還在進行；登入、權限、model picker、resume、cancel 與 crash recovery 都要逐一測。
• 退出與移除：Atlas 的 repo 資料、app config、agent transcripts、memory、cache 與 telemetry identity 不是同一個位置；截至本文核對日，alpha-0.3.0 README 與官方文件未提供完整 uninstall data map，先匯出、備份與盤點，不要照猜測的刪除腳本清理。

Atlas Agent Source Control 常見問題

Atlas 可以取代 Git 嗎？

不可以。Git 仍負責 commit、branch、merge 與歷史；Atlas 是把 agent session 關聯到這些歷史的觀察層。

有 Linked checkpoint 就代表這幾行一定是該 agent 寫的嗎？

不代表。它是以 touched paths、內容特徵與 patch-id 建立的候選關聯，不是逐行 authorship 或不可否認簽章。

Amend 與 rebase 後一定找得回 checkpoint 嗎？

不一定。diff 不變、patch-id 唯一且在修復掃描範圍內時較有機會；衝突解決若改了 diff，就可能 orphan。

Squash 後 orphan 是 bug 嗎？

未必。多個 commit 被合成後，原 session 與新 diff 不再是一對一；保守 orphan 通常比猜錯來源更可信。

Atlas redaction 會阻止秘密傳給模型商嗎？

不會。checkpoint 遮罩是 Atlas 儲存面的 best-effort 防線，不是 Claude／OpenAI provider upload 的前置秘密掃描器。

關閉 analytics 就完全沒有網路流量嗎？

不能這樣推論。agent provider、自動更新與主動 feedback 都是不同路徑；嚴格環境要用網路層驗證。

Claude Code 與 Codex 可以同時改同一個 repo 嗎？

可以共用 Git repository，但要使用不同 branch 與不同 worktree。不要讓兩個 agent 同時寫同一個 physical checkout。

匯入舊 Claude Code session 會自動找到舊 commit 嗎？

不會。alpha-0.3.0 的 importer 會讀取 JSONL 中可得的對話、tool calls 與 usage，但刻意不建立 retroactive checkpoints；它適合回看過程，不是倒推 provenance。

移除 Atlas 會破壞 Git repo 嗎？

Atlas 不改 Git hooks、config 或 refs，所以 Git 歷史不應依賴它。但刪 App 前仍要匯出需要的 session，並盤點 repo 與使用者層級資料；截至本文核對日，alpha-0.3.0 README 與官方文件未提供完整清除地圖。

Windows／Linux 現在能照這篇做嗎？

不建議。官方目前只支援 macOS；其他平台即使可能從 source build，也仍屬未測範圍。

新手最短驗收清單

1. 只下載最新公開 release，記錄版本、macOS 與 CPU 架構。
2. 先關 usage analytics，再確認 Updates 與 feedback 的獨立網路路徑。
3. 建立合成 repo，不要一開始就匯入有真秘密的工作專案。
4. Claude Code／Codex 各用一個 branch 與 worktree。
5. 核對正常 commit、amend、rebase、squash、失敗 turn 六條路徑。
6. 只用假 canary 查 checkpoint、export、transcript 與 memory，不使用真 API key。
7. 把 orphan、誤配、污染與殘留都寫進驗收報告，再決定是否導入正式 repo。

最後判斷：把 Atlas 當收據機，不要當保險箱

Atlas 最有意思的地方，不是把更多 agent 塞進同一個介面，而是嘗試把「過程」重新接回 Git 的「結果」。在 alpha-0.3.0，這條 linkage 已足以讓團隊做一輪有意義的驗收：正常變更能否追查、rewrite 後會重連或保守 orphan、錯誤共享記憶會不會污染下一個 agent。

但成熟的使用順序仍應是：worktree 先隔離，Git 負責真實歷史，Atlas 再補 session provenance。只要不把 checkpoint 誤認為逐行簽章、不把 redaction 誤認為秘密邊界，它就是一個值得關注的 agent-native source control 實驗。

想建立完整基礎，可從 AlphaLab AI 專區開始；需要系統化練習，則前往 AlphaLab 線上課程。