openclaw-parallels-smoke

OpenClaw Parallels Smoke

此技能專用於 Parallels 客端工作流程與煙霧測試解讀。請勿在一般儲存庫工作中載入。

全域規則

• Parallels 是發布後信心覆蓋（postpublish-confidence）的預設選項，而非有界限的測試版發布階段的前置條件。請針對一個確切的已發布套件版本執行，並記錄授權該套件的 Validation SHA + Tooling SHA 執行組合。Validation SHA 對應其 Code SHA 或 Release SHA；它不是第三個發布身份。
• 失敗的發布後 Parallels 通道不會追溯性地取消發布測試版。請將其分類為產品、測試工具/工具鏈/來源證明、基礎架構/憑證或包裝器失敗。只有確認的產品缺陷才會進入下一個測試版。
• 對每個獨立的客端系列使用一個協調器和一個通道。診斷並重試一個失敗的系列一次，然後重新評估；不要自動重新啟動整個矩陣。
• 在配置任何資源之前，先清查現有的虛擬機和快照。當預配置的原始快照與請求的基準相符時，切換到該快照並重複使用其使用者、工具和基本設定。不要為「全新」執行建立新的虛擬機、重新安裝 macOS 或重建客端基準。
• 「全新」意味著恢復最近相符的原始快照，而不是建立另一個快照。除非使用者明確要求或沒有合適的基準存在，否則不要建立臨時快照；恢復原始快照並在臨時執行後保持客端停止狀態。
• 在恢復快照之前檢查其狀態。一個原始的 poweron 快照可能包含預先配置的已登入工作階段；正常切換到該快照，讓 Parallels 恢復該工作階段。除非執行需要故意捨棄已儲存的工作階段並從登入視窗啟動，否則不要在測試進入點傳遞 --skip-resume。--skip-resume 可接受用於最終清理，但必須讓還原的來源客端保持停止。
• 煙霧測試中的閘道驗證應使用 openclaw gateway status --deep --require-rpc，除非正在檢查的穩定版本尚未支援此功能。
• 穩定的 2026.3.12 升級前診斷可能需要一個純粹的 gateway status --deep 回退。
• 將 precheck=latest-ref-fail 視為該穩定升級前通道的基準，而非自動視為回歸。
• 傳遞 --json 以取得機器可讀的摘要。
• 預設情況下，每個階段的日誌會存放在 .artifacts/parallels/openclaw-parallels-* 下。當執行需要不同工件卷時，可使用 OPENCLAW_PARALLELS_ARTIFACT_ROOT 覆蓋。
• 請勿在同一個全新工作區或工作階段中並行執行本機和閘道代理回合。
• 使用主機 timeout --foreground（或 gtimeout --foreground，如果該二進位可用）為每個頂層 Parallels 通道設置硬上限，以免卡住的安裝、快照切換或 prlctl exec 傳輸消耗掉整個測試時間視窗。預設值：
  • macOS：75m
  • Linux：75m
  • Windows：90m
  • 聚合 npm-update 包裝器：150m 如果通道達到上限，請停止，檢查最新的 /tmp/openclaw-parallels-* 執行目錄和階段日誌，然後修復或重新執行受影響的最小通道。不要繼續等待已達上限的通道。
• 實際的 OpenClaw npm 安裝/更新階段是比整個通道上限更嚴格的訊號：安裝階段通常應在 7 分鐘內完成，更新階段通常應在 5 分鐘內顯示有意義的進度。如果名為 install-main、install-latest、install-baseline 或 install-baseline-package 的階段超過 420 秒，或名為 update-dev / 相同客端 openclaw update 的階段超過 300 秒且沒有新的標記，則從該階段日誌和客端程序狀態開始診斷。目前 Windows 更新階段仍可能在大約 10-15 分鐘後通過，因為 doctor --fix 可能安裝外掛程式的執行時期依賴項；除非日誌確實停滯，否則將腳本硬上限維持在大約 20 分鐘。
• 對於完整的作業系統矩陣，當主機容量允許時，偏好並行執行獨立的客端系列通道：
  • timeout --foreground 75m pnpm test:parallels:macos -- --json
  • timeout --foreground 90m pnpm test:parallels:windows -- --json
  • timeout --foreground 75m pnpm test:parallels:linux -- --json 將每個通道保留在自己的 shell/工作階段中，並追蹤每個通道的執行目錄。在啟動矩陣之前，先完成任何需要的主機建置/打包閘門。當需要目前主線的 tgz 打包時，煙霧測試腳本會透過 pnpm build、庫存/暫存和 npm pack 持有共享的套件鎖定；如果該鎖定遺失或損壞，則序列化矩陣而不是接受並發的 dist 變更。
• 不要同時對同一個客端系列執行多個煙霧測試通道。Tahoe 通道共享主機 HTTP 連接埠，如果兩個任務同時觸碰同一個虛擬機，Windows/Linux 通道可能在快照還原/啟動狀態上發生衝突。
• 不要並行執行聚合的 pnpm test:parallels:npm-update 包裝器和個別的 macOS/Windows/Linux 煙霧測試通道；它會觸及相同的客端系列和快照。
• 當任何不相關的主機命令可能重建、清理或重新暫存 dist 時（pnpm build、pnpm ui:build、pnpm release:check、pnpm test:install:smoke、npm pack/install 煙霧測試或執行套件/建置準備的 Docker 通道），不要啟動 Parallels 通道。先執行不相關的建置/打包閘門，讓它們完成，然後再啟動虛擬機矩陣。並發的 dist 變更可能導致主機 npm pack 因缺少檔案而失敗，並浪費一個完整的虛擬機週期。
• 在執行或最佳化矩陣時，記錄每個通道的實際時間以及來自 /tmp/openclaw-parallels-* 日誌中最慢的階段。在變更煙霧測試順序、逾時或輔助行為之前使用此時間資訊。
• 如果主機建置變更了追蹤的生成檔案（例如 src/canvas-host/a2ui/.bundle.hash），請在花費虛擬機時間之前停止。單獨提交生成的工件或修復生成器漂移，然後重新執行受影響的最小通道。
• 如果 main 正在活躍的多代理工作中移動，建議使用固定在一個提交上的分離工作樹來執行長時間的 Parallels 套件。煙霧測試腳本現在會驗證打包的 tgz 提交，而不是即時的 git rev-parse HEAD，但固定的工作樹仍然可以在重新執行期間避免嘈雜的重新建置/版本漂移。
• 對於 openclaw update --channel dev 通道，記住客端會複製 GitHub 的 main，而不是您的本機工作樹。如果存在本機修復，但重新執行時在複製的 dev 檢查中仍然失敗，在分支被推送之前，不要將其視為對該修復的否定。
• 對於 prlctl exec，請在 --current-user 之前傳遞虛擬機名稱（prlctl exec "$VM" --current-user ...），而不是相反。
• 如果工作流程從儲存庫檢出而不是從網站安裝程式/npm 發布安裝 OpenClaw，請透過安裝一個真實的客端 CLI 墊片並在新的客端 shell 中驗證來完成。儲存庫內的 pnpm openclaw ... 不足以達到交接的一致性。
• 在 macOS 客端上，偏好使用者全域安裝加上一個穩定的 PATH 可見墊片：
  • 使用 NPM_CONFIG_PREFIX="$HOME/.npm-global" npm install -g . 安裝
  • 確保 ~/.local/bin/openclaw 存在或 ~/.npm-global/bin 在 PATH 中
  • 從一個全新的客端 shell 使用 which openclaw 和 openclaw --version 進行驗證

npm 安裝然後更新

• 偏好進入點：pnpm test:parallels:npm-update
• 對於僅限 macOS 的已發布版本更新檢查，請使用：
  • timeout --foreground 75m pnpm test:parallels:npm-update -- --platform macos --package-spec openclaw@<old-version> --update-target <target-version-or-tag> --json 這保留了相同客端 openclaw update --tag ... 的覆蓋範圍，並使用共享的 macOS 目前使用者/sudo 回退，而不啟動 Windows/Linux 通道。
• 必要的覆蓋範圍：每個發布/更新回歸執行必須包含兩個通道：
  • 新快照 -> 安裝請求的套件/基準 -> 煙霧測試
  • 相同客端基準 -> 執行客端已安裝的 openclaw update ... 命令 -> 再次煙霧測試
• 更新通道必須實際執行 OpenClaw 的內部更新程式。不要將直接的 npm install -g <tgz-or-spec> 或工具端套件交換計為更新流程覆蓋；這些僅是安裝煙霧測試。
• 對於已發布的目標，先安裝舊的基準套件（例如 [email protected]），然後使用預期的頻道/標籤（例如 openclaw update --channel beta --yes --json）執行已安裝的客端 CLI，並在命令後驗證 openclaw --version、openclaw update status --json、閘道 RPC 和一個代理回合。
• 對於未發布的目標，在主機上打包候選版本，透過測試工具 HTTP 伺服器提供 .tgz，並將客端更新程式指向該提供的套件。偏好使用 openclaw update --tag http://<host-ip>:<port>/openclaw-<version>.tgz --yes --json；當頻道持久性也很重要時，請傳遞 --channel <stable|beta> 並在客端更新環境中將 OPENCLAW_UPDATE_PACKAGE_SPEC 設定為相同的提供 URL。正在測試的命令必須仍然是 openclaw update，而不是直接的 npm。
• 對於未發布的本機修復驗證，請記住舊的基準更新程式程式碼仍然控制著第一個躍點。僅存在於新更新程式程式碼中的修復無法改變已經在執行的舊程序；提供的候選版本必須保持與基準主機相容的套件/外掛程式中繼資料，否則基準本身必須包含更新程式修復。
• 對於測試版/穩定版驗證，請在執行前立即解析標籤（npm view openclaw@beta version dist.tarball 或 npm view openclaw@latest ...）。在長時間的虛擬機矩陣正在執行時，標籤可能會移動；當預期的預發布版本在早期註冊表 404/標籤延遲檢查後出現時，重新啟動矩陣。
• 使用配置的秘密工作流程僅注入 OpenAI/Anthropic 通道所需的提供者金鑰。不要列印秘密或環境變數轉儲；透過客端執行環境傳遞提供者秘密。
• 相同客端更新驗證應在代理回合之前將預設模型明確設定為 openai/gpt-5.4，並使用一個全新的明確 --session-id，以便舊的工作階段模型狀態不會洩漏到檢查中。
• 聚合的 npm-update 包裝器必須在全新和更新通道之前，使用與 parallels-linux-smoke.sh 相同的 Ubuntu 回退策略解析 Linux 虛擬機。當確切的預設虛擬機遺失時，將主要版本 >= 24 的任何 Ubuntu 客端視為可接受，偏好具有最新 poweroff 快照的最新版本 Ubuntu 客端。在 Peter 目前的主機上，請使用 Ubuntu 26.04。
• 在 macOS 相同客端更新檢查中，在 npm 升級後、gateway status / agent 之前重新啟動閘道；否則 launchd 可能回報已載入的服務，而舊程序已退出且新程序尚未準備好 RPC。
• npm-update 聚合的 macOS 更新部分會以 root 身分寫入客端更新腳本，然後以桌面使用者身分執行。如果 prlctl exec "$MACOS_VM" --current-user ... 無法驗證，請透過純 root prlctl exec 加上 sudo -u <desktop-user> /usr/bin/env HOME=/Users/<desktop-user> USER=<desktop-user> LOGNAME=<desktop-user> PATH=/opt/homebrew/bin:/opt/homebrew/opt/node/bin:/usr/bin:/bin:/usr/sbin:/sbin ... 重試。這是 Parallels 傳輸回退；仍然需要驗證 openclaw --version、閘道 RPC 和更新後的代理回合。
• 在 Windows 相同客端更新檢查中，在 npm 升級後、gateway status / agent 之前重新啟動閘道；否則，就地全域 npm 更新可能會使執行中服務中過時的 hashed dist/* 模組導入保持活躍。
• 在這些 Windows 相同客端更新檢查中，不要將一次非零的 openclaw gateway restart 視為確定性失敗。目前的登入項目重新啟動可能在背景服務再次變得可觀察之前報告失敗；隨後進行更長的 RPC 就緒等待，並且僅在就緒狀態永遠不回傳時，才將 gateway start 用作復原步驟。
• 在該 Windows 重新啟動後，不要相信在固定休眠後進行的一次 gateway status --deep --require-rpc 呼叫。重試 RPC 就緒探測大約 30 秒並記錄每次嘗試；目前的客端可以在新的 RPC 端點仍在啟動時保持連接埠 18789 綁定。
• 對於 Windows 相同客端更新檢查，偏好使用完成檔案/日誌排出的 PowerShell 執行器模式，而不是一個長時間執行的 prlctl exec ... powershell -EncodedCommand ... 傳輸。客端可能在外部 prlctl exec 仍然掛起時成功完成。
• Windows 相同客端更新輔助程式應在其日誌中寫入階段標記，特別是在長時間步驟如 tgz 下載和 npm install -g 之前，以便外部進度監視器不會在健康但安靜的安裝期間停留在 等待第一個日誌行。
• Linux 相同客端更新驗證也應匯出 HOME=/root，透過 prlctl exec ... /usr/bin/env 傳遞 OPENAI_API_KEY，並使用 openclaw agent --local；新的 Linux 基準不依賴持久化的閘道憑證。
• npm-update 包裝器現在從嵌套的日誌檔案列印每個通道的進度。如果一個通道看起來仍然卡住，請先檢查 runDir 中的嵌套日誌（macos-fresh.log、windows-fresh.log、linux-fresh.log、macos-update.log、windows-update.log、linux-update.log），而不是假設外部包裝器掛起。
• 每次執行都會寫入 summary.json 和 summary.md；先讀取 Markdown 以進行快速人工分類，然後再使用 JSON/計時進行自動化。
• 對於標籤發布後的完整測試版驗證，偏好一個命令：
  • timeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta3 --json 這會將 beta3 解析為最新的 *-beta.3 版本，執行 latest->that-version 相同客端更新覆蓋，然後在所選的相同作業系統矩陣上為該確切的已發布目標執行全新安裝煙霧測試。使用 --platform macos|windows|linux 來縮小重新執行範圍。
• 對於帶有代理回合的測試版 4 npm 驗證，已知的良好形狀是：
  • gtimeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta4 --model openai/gpt-5.4 --json 在驗證特定的預發布版本號時，偏好明確的 beta4 別名而非 openclaw@beta；npm 標籤可能會移動。
• 如果包裝器失敗一個通道，請閱讀...

[原文已截斷以利翻譯]