在維運 AI 環境或開發桌面應用時，團隊在開啟 Hermes Desktop 的過程中，常會遇到畫面長時間停留在「Preparing Node dependencies」的狀況。直覺上，大家第一反應往往是網路不穩導致 npm 套件下載太慢，或是套件包過大卡住，甚至直接選擇把軟體重裝。
但實務經驗告訴我們，如果這時去手動執行安裝，通常只要半分鐘就能跑完。這代表問題根本不在 Node 依賴本身，而是 CLI launcher（命令列啟動器）的編排（Orchestration）出了狀況。可能是等待條件沒有被解除，或是 Electron 啟動階段漏接了安裝完成的訊號。要徹底解決這個問題，排查的核心在於把依賴安裝與啟動器的運作拆開來看。
本篇目錄
卡住時先記錄當前狀態，別急著重裝
看到畫面不動，千萬別急著強制關閉或盲目重裝，這會破壞最原始的錯誤現場。請先記下當前的 Hermes 版本、Desktop 版本，以及 Node 和 npm 的版本號。
接著，打開系統的資源監控工具，觀察背後的程序狀態。如果發現 npm 相關的程序已經退出，但畫面上的 launcher 卻還在原地等待，這就是一個非常明確的訊號，代表啟動器本身的邏輯卡死了。反之，如果網路流量和磁碟讀寫都還在持續飆高，代表真的還在下載套件，這時候才需要去檢查 npm registry 來源或公司的代理伺服器（Proxy）設定。
透過手動安裝區分故障點
為了進一步確認是不是單純的安裝問題，我們可以將環境切換到 Hermes Desktop 實際運作的專案目錄（請務必在不包含真實帳號或機密路徑的測試環境進行），手動跑一次等價的 npm install 指令。
執行手動安裝時，記得留意開始與結束的時間，以及最終的結束碼（exit code）。手動安裝成功不代表 Desktop 就修好了，但能證明你的 registry、Node 環境與基本依賴來源是健康的。如果手動安裝非常快速就成功了，我們就可以把焦點完全鎖定在 launcher 是如何呼叫指令與處理回傳結果的。
確認實際呼叫的 Node 版本與工作目錄
排查過程中，最常踩到的陷阱就是「版本與路徑不一致」。我們在終端機裡輸入 node --version 看到的版本，往往不等於 Desktop 啟動器底層真正吃到的版本。因此，務必利用 which node 或從啟動日誌中，確認 Electron 實際抓到的執行路徑。
除此之外，還要再三確認手動執行安裝的「工作目錄（Working Directory）」。如果依賴安裝在 A 目錄順利完成，但 Desktop 內部設定等待的卻是 B 目錄，畫面自然永遠不會更新。
可驗證的臨時繞行方式
當確認是啟動器的問題時，若官方文件允許，可以嘗試直接以 Electron 或「已完成依賴安裝的啟動入口」來開啟 Desktop。請把這當成診斷用的臨時繞行方案（Workaround），在介面成功載入後，隨便建立一個「不改寫外部資料」的最小測試任務跑跑看。如果直接啟動完全正常，而 CLI launcher 依然卡死，這就進一步證實了問題出在 launcher orchestration。
回報維護團隊前，先整理啟動時間線
當你需要向維護團隊提交 issue 或是記錄內部技術文件時，給予精確的資訊能大幅縮短修復時間。請保留以下這份精簡的啟動時間線：
- launcher 開始運行的時間點。
- npm 開始與結束的時間，以及每一步的 exit code。
- Electron 啟動、畫面顯示 Preparing 的精確時間。
附上版本組合、可重現步驟與手動安裝的結果。這些具體數據能讓開發者一眼看出到底是等待條件沒被觸發，還是錯誤訊息被吞掉了。
恢復日常工作前，先確認這五項指標
在宣布解決並準備恢復日常工作流程前，團隊可以順手檢查這五個關鍵點，確保環境真的穩定了：
- 手動安裝與 launcher 呼叫的 Node/npm 版本是否完全一致。
- 依賴安裝的工作目錄與 Desktop 預期讀取的目錄是否相符。
- npm 的 exit code 是否已被 launcher 正確接收，無卡死或丟失。
- 直接啟動的 workaround 是否已明確標示為「暫時方案」，而非最終修復。
- 最小測試任務是否可順利完成且不影響外部資料。
團隊常見的排查疑問 (FAQ)
可能是 launcher 沒收到完成訊號（例如進程被吞掉）、等待了錯誤的路徑，或是 Electron 實際上使用了不同的工作目錄。
建議先保留錯誤現場與日誌證據。只有在確認依賴確實損壞時，才在測試環境中嘗試重建。
不算。這只是繞過 launcher 的暫時性驗證方式，本質上並未解決 launcher 的編排問題，仍需等待正式修復。
請務必附上詳細的版本組合、啟動時間線、exit code、可重現步驟，以及已去除機敏資訊（如真實路徑或 Token）的錯誤訊息。