--- read_when: - 你正在針對即時閘道驗證路徑 3 的 SQLite 儲存切換作業 - 你需要區分預期的舊版 JSONL 漂移與執行階段失敗 - 你正在建置或審查由代理程式驅動的即時 SQLite 端對端測試框架 summary: Path 3 SQLite 工作階段／逐字稿切換的即時閘道驗證設計 title: 路徑 3 即時 SQLite 端對端測試框架 x-i18n: generated_at: "2026-07-26T08:42:22Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 2749bf47cb4967bc80a5ed37a12f2a553f3b388ed8cd90cfb3217e1b5e8afae9 source_path: reference/path3-live-sqlite-e2e-harness.md workflow: 16 --- Path 3 即時 SQLite E2E 測試工具可證明閘道使用 SQLite 作為標準工作階段與逐字記錄儲存區，而舊版 JSONL 檔案仍僅作為遷移輸入或封存資料。這是供維護者使用的驗證工具，而非一般使用者的診斷工具。 閘道處理遷移後的流量之後，舊版 JSONL 的一致性便不再是有效的執行階段健康狀態指標。健康且已遷移的閘道，其 SQLite 逐字記錄資料列可能與舊版 JSONL 的計數不同，因為新的對話輪次應只推進 SQLite 狀態。因此，即時測試工具必須在每個步驟衡量閘道行為、SQLite 資料列變化、舊版檔案靜止狀態，以及記錄健康狀態。 ## 命令形式 預期的即時命令如下： ```bash node scripts/path3-live-sqlite-e2e.mjs \ --url http://127.0.0.1:18789 \ --agent main \ --session-key agent:main:path3-live-e2e: \ --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 ` 必須顯示 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/.jsonl` 附屬檔案。 - 除非該步驟明確屬於離線遷移或封存作業，否則現有的舊版 JSONL 檔案與 `sessions.json` 均維持不變。 - 閘道程序不會開啟 `.jsonl` 或 `sessions.json` 控制代碼。 - 除非情境明確將其列入允許清單，否則自上一個游標以來的記錄不得包含 `ERROR`、`FATAL`、`SQLITE_`、 `no such column`、工作階段儲存區無法使用、重新啟動復原失敗或逐字記錄協調警告。 記錄掃描是通過／失敗合約的一部分。若閘道能回應健康狀態檢查，卻發出 SQLite 結構描述錯誤或重複發生的逐字記錄協調失敗，則 Path 3 不應判定為通過。 ## 證據成品 測試工具應將證據寫入 `.artifacts/path3-live-e2e//`，且不要納入 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 成為標準儲存區，出現即時差異便符合預期。