路徑 3 即時 SQLite 端對端測試框架

Path 3 即時 SQLite E2E 測試工具可證明閘道使用 SQLite 作為標準工作階段與逐字記錄儲存區，而舊版 JSONL 檔案仍僅作為遷移輸入或封存資料。這是供維護者使用的驗證工具，而非一般使用者的診斷工具。

閘道處理遷移後的流量之後，舊版 JSONL 的一致性便不再是有效的執行階段健康狀態指標。健康且已遷移的閘道，其 SQLite 逐字記錄資料列可能與舊版 JSONL 的計數不同，因為新的對話輪次應只推進 SQLite 狀態。因此，即時測試工具必須在每個步驟衡量閘道行為、SQLite 資料列變化、舊版檔案靜止狀態，以及記錄健康狀態。

命令形式

預期的即時命令如下：

node scripts/path3-live-sqlite-e2e.mjs \  --url http://127.0.0.1:18789 \  --agent main \  --session-key agent:main:path3-live-e2e:<timestamp> \  --json

此命令會連線至已在執行的閘道。除非日後新增明確的遷移模式，否則不會啟動、停止、匯入或重新執行遷移。CI 或隔離的本機變體可使用 test/helpers/openclaw-test-instance.ts，但即時驗證路徑應檢查實際的操作員閘道及其真實的個別代理程式 SQLite 資料庫。

隔離的建置版命令列介面驗證

建置版命令列介面驗證執行器會植入隔離的舊版工作階段儲存區、啟動重新建置的閘道，並證明啟動程序會在執行階段開始讀取之前，將活躍的舊版工作階段匯入 SQLite。第一次啟動閘道之前不得執行 openclaw doctor --fix，因為如此驗證的是手動遷移路徑，而非使用者在切換後首次開機時所取得的升級路徑。

完成啟動匯入後，隔離驗證可執行 openclaw doctor --session-sqlite inspect 和 openclaw doctor --session-sqlite validate，作為診斷證據。這些 doctor 命令並非啟動升級驗證的遷移驅動程式。個別的 doctor 匯入情境應植入舊版逐字記錄檔及軌跡附屬檔案，並驗證 doctor 會封存這些成品，同時 SQLite 仍維持標準儲存區的地位。

預先檢查

預先檢查會收集基準資料；若閘道無法使用，則會在傳送驗證對話輪次前失敗：

• GET /health 和閘道深度狀態必須回報閘道正在執行且可連線。
• 命令列介面與閘道版本必須符合受測分支。
• 測試工具會記錄作用中閘道檔案記錄的游標。
• 測試工具會記錄個別代理程式 SQLite 資料表 sessions、 session_entries、transcript_events、transcript_event_identities 和 session_routes 的計數。
• 測試工具會記錄 mtime、size，以及舊版 sessions.json、被參照的 JSONL 檔案和候選驗證工作階段 JSONL 路徑是否存在。
• lsof -p <gateway-pid> 必須顯示 SQLite DB/WAL/SHM 控制代碼，且不得有作用中的 .jsonl 或 sessions.json 控制代碼。

在即時模式中，openclaw doctor --session-sqlite validate 僅供參考。 產生切換後流量後，它可能會回報相對於舊版檔案的預期差異。測試工具應使用 doctor 輸出進行分類與遷移清查，而非將其作為執行階段通過或失敗的判定依據。

代理程式驅動的情境

即時情境使用專用的驗證工作階段金鑰，並盡可能透過公開 RPC 路徑驅動閘道。單一代理程式對話輪次應足以執行一般持久化，但完整驗證應涵蓋先前必須逐項進行即時檢查的 3.1b 接合處：

• 一般聊天輪次：建立或重複使用驗證工作階段、傳送真實的代理程式提示、等待最終助理結果，並驗證 chat.history 或同等的閘道投影。
• 逐字記錄識別資訊：驗證相同的標記會出現在閘道歷程記錄與 SQLite 逐字記錄資料列中，包括存在時的穩定事件識別資訊資料列。
• 工作階段中繼資料存取器：透過閘道／工作階段存取器讀取驗證工作階段及選定的現有即時工作階段，並與 SQLite 資料列比較。
• 工作階段修補投影：對驗證工作階段套用可還原的模型／工作階段中繼資料變更，然後驗證投影資料列與閘道回應一致。
• 壓縮檢查點生命週期：僅針對驗證工作階段或測試工具建立的合成測試工作階段，列出、分支及還原檢查點。
• 重新啟動復原：針對受控的驗證工作階段或隔離的測試執行個體，執行安全復原標記路徑；只有目標工作階段集合明確且可還原時，即時模式才能執行此步驟。
• 清理生命週期：刪除或重設驗證工作階段，然後驗證 SQLite 生命週期資料列與已封存的逐字記錄狀態。

無法在即時操作員閘道上安全執行的傳輸方式特定接合處，例如 WhatsApp 或語音通話輸入，應針對相同的 SQLite 合約使用擁有者層級的執行階段探針，而非偽造外部傳輸方式。

個別步驟的判定條件

每個步驟都會擷取前後狀態快照，並寫入結構化判定記錄：

• SQLite 資料列計數只在預期的位置增加。
• 對於記錄執行階段事件、由標記支援的驗證工作階段，其軌跡執行階段資料列會增加。
• 驗證工作階段資料列具有預期的 session_id、狀態、時間戳記、中繼資料和路由資料列。
• 閘道歷程記錄／工作階段投影與 SQLite 逐字記錄尾端相符。
• 不會建立或修改任何驗證工作階段 JSONL 檔案。
• 不會建立任何驗證工作階段 .trajectory.jsonl、.trajectory-path.json 或 衍生自標記的 trajectory/<session>.jsonl 附屬檔案。
• 除非該步驟明確屬於離線遷移或封存作業，否則現有的舊版 JSONL 檔案與 sessions.json 均維持不變。
• 閘道程序不會開啟 .jsonl 或 sessions.json 控制代碼。
• 除非情境明確將其列入允許清單，否則自上一個游標以來的記錄不得包含 ERROR、FATAL、SQLITE_、 no such column、工作階段儲存區無法使用、重新啟動復原失敗或逐字記錄協調警告。

記錄掃描是通過／失敗合約的一部分。若閘道能回應健康狀態檢查，卻發出 SQLite 結構描述錯誤或重複發生的逐字記錄協調失敗，則 Path 3 不應判定為通過。

證據成品

測試工具應將證據寫入 .artifacts/path3-live-e2e/<timestamp>/，且不要納入 git：

• summary.json：命令引數、閘道版本、結果、失敗的判定條件及成品路徑。
• sqlite-before.json 和 sqlite-after.json：資料列計數及選定的驗證資料列。
• legacy-files.json：舊版檔案是否存在、mtime、大小，以及每個檔案是否變更。
• gateway-log-scan.json：游標範圍、相符的記錄行及允許清單判定。
• events.jsonl：依序排列且適合用於 PR 驗證留言的個別步驟觀察結果。

PR 驗證應摘要說明這些成品，而非貼上完整逐字記錄或私人訊息內容。

安全規則

• 即時模式絕不可在閘道執行期間重新匯入舊版 JSONL。
• 除非是明確選定且可還原的修復探針，否則即時模式不得變更非驗證工作階段。
• 任何破壞性或大範圍的遷移步驟，都必須先建立受影響 SQLite DB 與舊版工作階段目錄的全新備份。
• 備份範圍應限於受影響的代理程式 DB／工作階段目錄，並在單次驗證執行期間重複使用，以避免磁碟用量無限增長。
• 除非呼叫端傳入 --keep-artifacts，否則清理步驟完成後不得留下任何驗證工作階段、驗證 JSONL 或已修改的舊版檔案。

通過結果

即時執行通過表示閘道接受了真實的代理程式驅動工作階段流程、所有觀察到的標準狀態都位於 SQLite、舊版執行階段檔案維持靜止，且在衡量期間內記錄健康狀態保持正常。這並不表示即時流量產生後，舊版 JSONL 的一致性仍維持正常；一旦 SQLite 成為標準儲存區，出現即時差異便符合預期。