錯誤碼 - Vibex

Vibex 的失敗以結構化錯誤碼返回，介面會顯示為 錯誤碼: 說明。提交 Issue 時請附上完整的錯誤碼字串——它比日誌正文更有用。

遠端與配對

錯誤碼	含義	處理
`remote_pairing_code_invalid`	配對碼錯誤、已被使用或不存在。	在權威端重新生成。
`remote_pairing_code_expired`	配對碼已過期（預設 5 分鐘，最長 30 分鐘）。	重新生成並儘快使用。
`remote_pairing_link_invalid`	連線串格式錯誤，或其中地址不是允許的區域網地址。	使用權威端列印的完整連線串。
`device_revoked`	裝置已被撤銷。	重新配對。
`resync_required`	檢測到序號或游標缺口。	等待權威端重新同步。
`server_shutdown`	權威執行階段正在關閉。	重啟後重連。
`permission_denied`	當前裝置權限級別不足。	用更高權限級別重新配對。

會話與工作區

錯誤碼	含義	處理
`remote_agent_workspace_root_missing`	會話請求的工作區目錄在權威端不存在。	確認目錄已掛載且位於 `VIBEX_WORKSPACE_ROOTS` 內。
`remote_agent_workspace_mode_mismatch`	請求的工作區模式與權威端記錄不一致。	在權威端重新選擇工作區。

檔案與內容

錯誤碼	含義	處理
`file_external_revision_changed`	儲存時檔案已被外部程序修改。	重新載入後再決定如何合併。
`office_legacy_format_unsupported`	`doc` / `xls` / `ppt` 無法渲染。	用系統預設應用開啟，或轉換為新格式。

配置與匯入

錯誤碼	含義	處理
`provider_native_import_source_missing`	找不到要匯入的原生配置來源。	確認對應 Agent 的配置檔案存在。

用量統計

錯誤碼	含義	處理
`agent_usage_query_too_large`	查詢超過 100000 行上限。	縮小時間範圍或增加篩選條件。

釋出與更新

錯誤碼	含義	處理
`release_channel_override_rejected`	試圖在執行階段切換髮布通道。	安裝對應通道的版本。
`stable_channel_requires_release_build`	Stable 通道需要正式釋出構建。	使用正式釋出的安裝包。

SSH 與 WSL

錯誤碼	含義	處理
`ssh_client_missing` / `ssh_spawn_failed`	桌面端沒有可用的 SSH 客戶端。	安裝 OpenSSH；Windows 使用 WSL。
`ssh_host_key_unknown`	主機金鑰不在 `known_hosts` 中。	先在終端機連線並核對指紋。
`ssh_host_key_changed`	主機金鑰與記錄不一致。	與主機所有者核對後再決定是否更新 `known_hosts`。
`ssh_auth_failed`	非互動認證失敗。	檢查 Key、ssh-agent 和 IdentityFile。
`ssh_connection_refused`	目標沒有 SSH 服務。	安裝/啟動 sshd，或用 bootstrap。
`ssh_environment_glibc_too_old` / `ssh_environment_missing_glibc`	遠端 glibc 低於 2.35 或缺失。	換受支援的發行版；musl 主機不支援。
`ssh_environment_disk_low`	遠端 home 空間不足。	至少釋放 512 MiB。
`ssh_environment_port_busy`	執行階段埠被佔用。	釋放埠或重試。
`ssh_runtime_start_failed` / `ssh_runtime_health_timeout`	執行階段沒有啟動或健康檢查超時。	檢視遠端 `server.log`，修復後重試。
`ssh_tunnel_*`	隧道建立、保持或停止失敗。	檢查本地埠和 SSH 連線，重試。
`ssh_upgrade_incompatible`	執行階段與桌面端版本不相容。	按相容性狀態更新執行階段或 Vibex。

瀏覽器

錯誤碼	含義	處理
`browser_missing`	找不到 Chrome、Chromium 或 Edge。	安裝受支援的瀏覽器。
`browser_unavailable`	瀏覽器服務不可用或正在關閉。	重新打開面板；檢查執行階段日誌。
`browser_ref_stale`	元素引用已過期。	重新觀察頁面後再操作。
`browser_element_not_found` / `browser_element_not_visible`	目標元素不存在或不可見。	重新觀察；必要時滾動或等待。
`browser_navigation_denied` / `browser_navigation_approval_required`	導航被拒絕或需要批准。	在面板裡確認；不要繞過核准。
`browser_wait_timeout`	等待條件超時。	檢查選擇器或頁面狀態。
`browser_feature_disabled`	當前執行階段或平台關閉了瀏覽器面板。	檢查設定和平台支援。

電腦操作

錯誤碼	含義	處理
`computer_feature_disabled`	總開關關閉。	在設定 → 電腦操作開啟。
`computer_engine_missing` / `computer_driver_daemon_missing`	驅動或 helper 未安裝/未執行。	安裝驅動並重新檢測。
`computer_accessibility_bridge_missing`	Linux 上輔助功能匯流排不可用。	安裝/啟動 AT-SPI；X11 下仍可能降級。
`computer_credential_target_blocked`	目標是密碼管理器或安全輸入框。	硬拒絕，不能批准。
`computer_element_reference_stale`	元素引用已過期。	重新觀察應用。
`computer_stopped_by_user`	你按下了應急停止。	手動重新開啟後才能繼續。
`computer_paused_offline`	客戶端斷線，操作已暫停。	重新連線並確認恢復。

供應商與閘道器

錯誤碼	含義	處理
`provider_authentication_required`	供應商或 Agent 需要認證。	登入 Agent 或補充 Provider Key。
`provider_profile_not_found`	配置不存在或已刪除。	重新整理配置中心，重新選擇。
`agent_model_interface_unsupported`	當前 Agent 不支援所選介面協議。	換協議或換 Agent。
`model_gateway_port_invalid`	閘道器埠低於 1024 或不可用。	換一個高於 1023 的空閒埠。
`model_gateway_cooldown_invalid`	冷卻時間不在 1 毫秒到 1 天之間。	調整冷卻設定。
`model_gateway_token_limit_invalid`	Token 上限無效。	輸入正整數或留空。
`reasoning_effort_unavailable`	所選思考檔位不被模型支援。	換檔位或留空。

狀態值

這些不是錯誤，但經常被誤讀：

值	出現在	含義
`stale`	終端機、執行狀態	上次觀察到的狀態已失效，不代表程序仍存活。
`revoked`	裝置	授權已被撤銷。
`running`	會話	只是上次觀察到的狀態，重啟後需要重新探測。
`Not reported` / `Partial`	用量上報覆蓋	資料缺失或不全，不要當作零。

通用排查順序

確認權威執行階段正在執行，以及當前連的是哪一個（本地內嵌，還是遠端伺服器）。
確認當前專案和工作區正確——Local 和 Worktree 是不同目錄。
確認裝置權限級別足夠（寫操作需要 full_control）。
檢視時間線最近一條事件，確認是否在等待你處理核准或詢問表單。
仍無法解決時，按故障排查提交脫敏資訊。