--- read_when: - 你正在針對即時閘道驗證路徑 3 的 SQLite 儲存切換作業 - 你需要區分預期的舊版 JSONL 漂移與執行階段失敗 - 你正在建置或審查由代理程式驅動的即時 SQLite 端對端測試框架 summary: Path 3 SQLite 工作階段／逐字稿切換的即時閘道驗證設計 title: 路徑 3 即時 SQLite 端對端測試工具 x-i18n: generated_at: "2026-07-12T14:47:59Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 15 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` 的資料列計數。 - 測試工具會記錄舊版 `sessions.json`、所參照的 JSONL 檔案及候選 驗證工作階段 JSONL 路徑的 `mtime`、`size` 和存在狀態。 - `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 成為 標準儲存區後，預期會出現即時差異。