【2026 最新】Agent Harness 換家不失憶：Claude Code、Pi、DeepSeek Harness Swap Test

Agent Harness 換家真正昂貴的，不是重新登入或重裝工具，而是任務做到一半後，新 Harness 能不能分清楚「已證實、已排除、下一步」，並在不放大權限的前提下接著做。這篇不替 Claude Code、Pi 或 DeepSeek Harness 排總冠軍；你會做一套可重跑的 Swap Test，測出某一個具體任務從 A 搬到 B 時，究竟是成功接手，還是悄悄重做。

讀完後，你會有一份七層 Handoff Receipt、三組對照、六條遷移路徑，以及可以立即判定繼續、回滾或維持雙 Harness 的驗收閘門。若你還分不清模型與 Harness，可先把 Harness 想成替模型準備工具、上下文、權限與執行迴圈的「工作台」；更完整的入門可見 Agent Harness 白話解釋。

先說結論：搬的不是「記憶」，而是可驗證的工作狀態

• 不要把原生 Session 檔當通用格式。Claude Code、Pi 與 DeepSeek Harness 的官方文件各自定義本系統的工作歷程；Swap Test 只把產品中立的證據包送進另一套系統。
• 真正可攜的是證據包。Repo 快照、diff、測試結果、決策理由、工具契約與權限邊界，必須能由接手者重新核對。
• 用三組 Swap Test 隔離成本。原 Harness 原 Session 繼續、原 Harness 新 Session 讀 Receipt、新 Harness 新 Session 讀同一份 Receipt。
• 先驗證結果，再算速度。只要 snapshot 不符、權限擴張、外部副作用不明或 rollback 失效，就直接停止；省下多少 Token 都不能抵銷。

整篇只要記住這個式子：安全換家＝可重建的 Repo 狀態＋可驗證的 Handoff Receipt＋重新授權的最小權限。Session transcript 可以幫忙追溯，卻不是這條等式的任何一項替代品。

為什麼一般 Harness 比較回答不了這題？

一般比較從乾淨起點出發：固定任務，再看誰做得快、花得少、結果好。AlphaLab 先前的 Pi、OpenCode、DeepSeek Harness 比較與 FrontierHarness Eval正是在回答這類選型問題。Swap Test 改問另一件事：同一個做到一半的任務，換工作台後能否延續，而不是從頭再猜一次？

這個差異很重要。2026 年一篇多 Agent 團隊研究發現，即使替換的是同角色、同基礎模型的隊友，最終分數與協調成本也可能往不同方向變化；作者測的是協作遊戲，不是 coding harness，因此不能把論文比例套到 Claude Code、Pi 或 DeepSeek Harness。它真正提供的設計提示是：除了結果，還要另外記錄重新對齊與監督成本。另一篇模型升級記憶研究則顯示，轉移效果可能具有方向性，平均值會掩蓋 A→B 與 B→A 的落差；該研究使用合成歷史與兩個小型開放權重模型，同樣不是跨 Harness 實驗。兩篇原始研究可分別見 Agent 團隊可替換性與模型升級下的記憶轉移。

第一步：先鎖住比較邊界

如果 A 用一個模型、B 換另一個模型，工具與權限也一起變，你測到的是整包差異，不是 Harness 差異。開始前建立一張 Run Card，至少固定以下欄位：

• 同一個 commit 與同一份任務快照，包含未提交 diff 的雜湊。
• 每套 Harness 的實際安裝版本或 commit、release channel、Session format 與設定雜湊；引用 living docs 或 master 時另記查閱日期。
• 同一個模型、版本、供應商與推理設定；做不到時，明確標成「Harness–模型–設定組合比較」。
• 同一套驗收測試、停止條件、時間與成本預算。
• 同一組 repo 指令、Skills、MCP server 版本與 tool schema 雜湊。
• 同一個有效權限範圍：可寫目錄、網路、命令、憑證名稱與 scope。只記名稱和範圍，不把秘密值寫入 Receipt。
• 同一個獨立評分器；不要讓執行 Agent 自己宣告成功。

模型無法固定時仍然可以跑，但結論必須改成「這兩個完整工作配置，哪個接手得更好」。要先練習如何控制變因，可搭配 Claude Code vs Codex 比較方法。

第二步：建立七層 Handoff Receipt

Handoff Receipt 不是「請繼續完成」的一段摘要，而是一張可以被接手者反駁的交接單。每一項結論都要指回檔案、diff、命令輸出或測試證據。七層如下：

1. 目標與完成定義：要改什麼、禁止碰什麼、哪個檢查通過才算完成。
2. Repo 與 diff：branch、HEAD、工作樹狀態、相關檔案清單與內容雜湊。
3. 認知狀態：已證實、已推翻、尚未決定，以及各自的證據位置。
4. 指令與記憶：本次實際載入的 AGENTS.md、CLAUDE.md、Memory 或其他規則，並標出優先序。
5. 能力契約：Skills、工具名稱、server identity、版本、input/output schema，以及已知副作用。
6. 授權邊界：允許／需詢問／拒絕的動作，sandbox、網路與 credential scope 的有效差異。
7. 驗證與回滾：基線測試、目前失敗、下一個最小步驟、隔離 worktree 或副本的 rollback pointer。

可以用這份最小 JSON 作為起點；實務上應把長輸出存成獨立檔案，再在 Receipt 裡放路徑與 SHA-256，而不是貼滿整份 transcript。

{
  "handoff_id": "swap-2026-09-08-A-to-B",
  "snapshot": {"head": "<commit>", "diff_sha256": "<hash>"},
  "goal": "修正表單送出後的重複請求",
  "acceptance": ["target test passes", "baseline tests unchanged"],
  "verified": [{"claim": "問題可重現", "evidence": "qa/before.txt"}],
  "refuted": [{"claim": "由 debounce 造成", "evidence": "qa/trace.txt"}],
  "next": "只讀核對快照，再提出一個可逆動作",
  "capabilities": {"tools": "qa/tool-map.json", "permissions": "qa/auth-map.json"},
  "external_effects": [],
  "rollback": {"workspace": "<isolated-copy>", "check": "<baseline-command>"}
}

Receipt 的 hash 只有和另存於可信來源的基準值比對時，才能驗出檔案是否在基準之後改動；hash 本身不能證明作者或內容可信。除非另有簽章與可信時間錨，別把它稱為數位簽章。以 Claude Code 為例，官方文件說明工具讀取的檔案內容、命令輸出與貼上文字都可能以明文進入 transcript；完整 transcript 因而可能包含秘密與個資，保存範圍要服從既有 retention policy。

第三步：在三個 checkpoint 切出可重跑起點

不要任意挑一個「感覺做到一半」的時刻。對同一任務建立三個 checkpoint，才能看出交接成本何時開始變大：

• A｜計畫已定：需求與基線測試已確認，尚未修改程式。
• B｜第一段進展：已有局部 diff，至少一個預先指定的檢查從失敗轉成通過。
• C｜接近完成：主要功能已過，但仍留一個明確收尾項目，例如回歸測試或邊界案例。

每個 checkpoint 都跑三組：① 原 Harness 用原生 Session 繼續；② 同一 Harness 開新 Session，只讀 Receipt；③ 新 Harness 開新 Session，讀完全相同的 Receipt。第②組估計同 Harness 新 Session 只靠 Receipt 的接手成本；在其餘條件固定且重複配對下，第③與第②的差值可作為額外跨 Harness 成本的估計。若有餘力，Claude Code、Pi、DeepSeek Harness 共有六條有方向性的 A→B 路徑；不能用其中一條反推反方向。

每組都用獨立工作目錄，固定起始 hash：可以用 Git worktree 取得各自的工作樹、HEAD 與 index，或建立可驗證副本。Git worktree 不是 sandbox，仍共用 repository 資料，也不會隔離資料庫、port、queue、雲端帳號、網路或 credential。開始前先確定沒有背景工具仍在執行；碰到外部系統時，優先用唯讀 canary、測試帳號與 idempotency key。

第四步：把三種 Harness 的原生狀態翻成共同欄位

截至 2026 年 9 月 8 日查得的官方文件，三者都有自己的 Session 能力；living docs 或 master 可能領先實際安裝套件，因此以下能力仍要由 Run Card 的版本逐項核對，而「都有記錄」也不等於格式互通：

• Claude Code：官方Session 文件提供 continue、resume 與人類可讀的 export；同頁區分了必須在 resume 時重新傳入的啟動參數（--mcp-config、--settings、--plugin-dir、--fallback-model、--add-dir），以及啟動時會重新讀取的標準 settings.json／settings.local.json。內部 JSONL 會隨版本變動，不應自行解析成跨工具介面。專案指令可由 CLAUDE.md 與 .claude/rules提供；auto memory 是本機跨 Session 筆記。它們都是 context，不是權限邊界。
• Pi：官方 v0.85.1 coding-agent 文件描述 JSONL session tree、fork／clone、compaction、HTML／JSONL export 與 Pi Session JSONL import；context loader則在每個目錄依序選取第一個存在的 AGENTS override、AGENTS 或 CLAUDE context file，再串接不同目錄的內容。這些 Session 操作仍使用 Pi 自己的格式。Pi 專案的 v0.85.1 README明確寫出「沒有內建 permission system」，預設沿用啟動它的使用者與 process 權限；換入 Pi 時要重新核對有效權限，若任務需要隔離，則由外部 container、VM 或 sandbox 提供邊界。
• DeepSeek Harness：官方 repo 的 master 分支 Session 文件把 Session 定義為 append-only event log，模型歷史由該 log 派生；Web 工作區文件說明可選取既有 Session，fork 會從來源的最後一個已完成 turn 建立子 Session 並打開。Run Card 必須另記實際安裝版本與 Session format。專案仍標示為 developer preview，安全說明稱其為實驗性、未完成安全稽核且不適合 production。這表示測試環境要用最小權限與可丟棄隔離，而不是把 sandbox 名稱當成保證。

AGENTS.md 與 Agent Skills能讓 repo 規則與工作流程更容易搬動；但 Claude Code 官方文件明確寫的是讀取 CLAUDE.md，而非直接讀取 AGENTS.md，共用時要由 CLAUDE.md 以 @AGENTS.md 匯入或使用 symlink。MCP 的 tool schema則能描述輸入輸出。這些機制處理的是工作流程封裝與工具介面；對話狀態、有效權限與外部副作用仍要在 Receipt 分別核對。兩個工具就算同名、schema 相同，也要比對 server identity、版本、批准方式、sandbox、網路政策與 credential scope。

第五步：新 Harness 先回 Receipt，再給寫入權

把 Receipt 丟進新 Session 後，不要立刻說「繼續」。先要求接手者在唯讀狀態回傳 acknowledgement：

Handoff ID 與 Receipt hash：
Snapshot match：PASS / FAIL
目標與完成定義：
重新核對的 manifest 與 baseline：
發現的不一致：
工具、sandbox、網路與 credential scope 差異：
外部或未知副作用：
下一個唯一、可逆的動作：
Rollback pointer 已驗證：YES / NO
決定：GO / STOP

只有全部一致才放行一個 canary：例如只改一個允許清單內的檔案、跑預先指定的測試，再檢查 diff scope。接手者若一開始就大範圍搜尋、重寫多個檔案或要求更高權限，這不是「主動」，而是 Swap Test 提早抓到的訊號。

第六步：量測 Agent Harness 換家，而不是聽自評

先做硬閘門，再記效率。以下欄位足以建立第一版 ledger：

• Outcome validity：目標測試、基線回歸、驗收條件是否由獨立檢查通過。
• Continuation fidelity：Receipt 的關鍵決策、限制與未決事項，有多少被正確重述並在行動中遵守。
• Reorientation cost：從接手到第一個被驗收的新增進展，消耗的 Token、時間、重讀、澄清與批准次數。
• Duplicate work：原 Session 已完成且有證據的讀檔、調查或修改，被新 Session 重做多少。
• Tool reliability：呼叫失敗、schema 不合、重試、timeout 與未知結果分開記錄。
• Permission drift：寫入路徑、網路、命令或 credential scope 是否擴張；未批准的擴張必須是零。
• Recovery：取消新工作後，能否恢復 snapshot hash、基線測試與已知外部狀態。

Token 要採供應商回報值，跨 provider 的計數方法未必可直接比較；取不到就填 null，不要估。完成時間則從 Receipt acknowledgement 開始，直到獨立驗收完成，中間的人工作業也要算。想先理解切換成本與 Receipt 對照，可讀 Handoff Tax 教學；本篇再把工具契約與權限漂移納入。

完整走一次：修正重複送出的表單

假設 Claude Code 已把問題縮小到 request layer，留下局部 diff，並用 trace 排除了 debounce。你在 checkpoint B 結束所有執行中的工具，把 HEAD、diff hash、兩份證據、基線命令與下一步「只檢查 retry path」寫入 Receipt。

接著分出三份相同 worktree。第一份讓原 Session 繼續；第二份開全新的 Claude Code Session；第三份開新的 Pi 或 DeepSeek Harness Session。後兩組都只收到同一份 Receipt。新 Harness 先唯讀核對 HEAD、diff 與 trace，列出自己的 tool/permission delta；如果它誤認 debounce 尚未檢查，Continuation fidelity 便已失分。如果它發現原本可用的測試工具不存在，則記成能力不相容，不准暗中換工具後繼續算同一組。

核對通過後，只准它在 retry path 做一個可逆修改並跑指定測試。測試與 diff scope 都通過，才解鎖剩餘任務。這個流程產生的是你自己的方向性觀測；不應把單一路徑的一次成功寫成「某 Harness 比另一個更會接手」。至少重複配對 trial，並在看結果前寫下接受門檻。

什麼時候該換、該回滾，或保留雙 Harness？

• 繼續換家：三個硬閘門都通過，且第③組相對第②組沒有不可接受的額外接手成本。
• 留在原 Harness：結果同樣正確，但工具轉譯、重讀與人工批准吃掉原本期待的收益。
• 立刻回滾：snapshot 不符、關鍵決策遺失、未知外部副作用、未批准權限擴張、越界 diff，或 rollback 無法重現。
• 維持雙 Harness：一個擅長探索、另一個擅長驗證，而 Receipt 與只讀交接已穩定；把寫入權留給單一 owner，可減少互相覆寫。

回滾不是一條 git reset --hard。先停止新 Harness，從 provider log 或 idempotency record 對帳外部副作用，再回到隔離 snapshot，核對檔案 hash 與基線測試。git restore處理的是可由版本庫來源重建的 working-tree／index 內容；部署、資料庫、API 呼叫或 repo 外的工具狀態，必須在 Receipt 裡各自有復原方式。

五個常見失敗

1. 直接搬 transcript：聊天很完整，卻沒有 snapshot、驗收與權限；新 Harness 只能相信舊敘事。
2. 同時換模型與工具：最後無法判斷差異來自哪一層。
3. 只看最後測試：結果碰巧通過，卻可能重做整段調查、改到範圍外或取得更多權限。
4. 把 schema 當語意：同名工具的副作用、批准與網路邊界可能完全不同。
5. 先寫入才核對：snapshot 已被污染後，便失去公平對照與乾淨 rollback。

如果你的問題其實是規則、Skill、Hook 與 MCP 應該先裝哪一層，請回到 AI Coding Agent 最小配置；如果要追蹤 Session 到 commit 的來源關係，則看 Atlas Agent Source Control。把這些基礎做好，再做 Swap Test 才能知道遺失的是狀態、能力，還是權限。

FAQ：Agent Harness 換家常見問題

1. 可以把 Claude Code Session 直接匯入 Pi 或 DeepSeek Harness 嗎？

不要直接互餵原生 Session 檔。Claude Code 的 /export產生人類可讀純文字；Pi 的 /import接收 Pi Session JSONL；DeepSeek Harness master 的 Web /export下載其 Session log ZIP。這些產品原生操作的輸入輸出不同；跨 Harness 應使用模型中立 Receipt，讓新工具重新核對 repo 與證據。

2. 有 AGENTS.md 就等於狀態可攜嗎？

不等於。AGENTS.md 可以作為 repo 指令的共用來源；Claude Code 需透過 CLAUDE.md 匯入或 symlink 才會讀取。它仍不能代表目前對話、已驗證決策、有效權限與外部副作用；這些要另寫 Receipt。

3. 使用同一個模型，就只剩 Harness 差異嗎？

不一定。provider、system prompt、context 管理、tool schema、sandbox、預設值與預算都可能不同。無法固定時，把結論標成完整配置比較。

4. Receipt 越長越好嗎？

不是。Receipt 的價值來自可定位的證據與明確邊界。大段 transcript 應保留在符合政策的原始位置，Receipt 只放結論、路徑與 hash。

5. Swap Test 一次成功就能決定換家嗎？

不能。Agent 路徑本身有波動；至少做配對重複，涵蓋不同 checkpoint，且 A→B 與 B→A 分開看。

6. 權限規則文字相同就算 parity 嗎？

不算。要測有效行為：哪些路徑能寫、哪些命令會詢問、網路能到哪裡、credential scope 多大，以及拒絕是否真的生效。

7. 用 Git 就能完整回滾嗎？

不能。Git 管的是納入版本控制的檔案；部署、資料庫、訊息、API 與 repo 外檔案要另外追蹤、對帳與補償。

8. 新手應該從哪個 checkpoint 開始？

從 A 開始。計畫已定但尚未寫入，能先驗證 Receipt 與權限流程而不碰程式修改；穩定後再挑戰帶有局部 diff 的 B。

給新手的 7 個重點

1. Harness 換家是受控重啟，不是搬運「腦袋」。
2. 先固定 repo、模型、工具、權限、預算與驗收。
3. 用七層 Receipt 傳證據，不用一段漂亮摘要取代證據。
4. 用原 Session、同 Harness 新 Session、新 Harness 三組分離成本。
5. 每條方向、每個 checkpoint 都獨立評估。
6. 結果與權限先過關，才比較 Token 和時間。
7. 先唯讀 acknowledgement，再做單一可逆 canary。