---
{
  "id": "platform.local.errors-and-debugging",
  "topic": "local",
  "title": "Local Desktop Bridge 錯誤與除錯",
  "locale": "zh-TW",
  "version": "2026-08-23",
  "summary": "Local failure 應依連線、capability、path、execution、infrastructure 順序除錯，再依 typed result 決定是否可重試。",
  "content": "Local action 應依 gate 順序除錯。先處理 `LOCAL_DESKTOP_NOT_CONNECTED` 的連線；再看 capability：`LOCAL_CAPABILITY_UNAVAILABLE` 是 live runtime 缺少能力，`LOCAL_CAPABILITY_NOT_GRANTED` 是裝置／Agent 授權不符，`LOCAL_CAPABILITY_CHECK_FAILED` 是暫時檢查失敗。接著在不猜路徑、不擴張 root 的前提下處理 `LOCAL_FS_ROOT_DENIED`，再看 `DESKTOP_TOOL_TIMEOUT`／`DESKTOP_TOOL_CANCELLED`，最後才是 `DESKTOP_ROUTING_UNAVAILABLE`。\n\n每個 action 都有 registry deadline；timeout 時 server 會發 kill 並把 action 視為失敗，不能宣稱完成。Availability error 要先修復連線或授權才可重試；timeout／cancelled 後應回報觀察到的狀態，並向使用者確認桌面實際狀況再決定。平台 routing unavailable 屬暫時問題，稍後重試合理。\n\nPlatform audit 只記 action identity、argument key names 與 serialized byte count、status／error metadata，以及 optional desktop audit ID；不記 argument values、本機 path、command text、clipboard、screenshot 或 tool result。Desktop 另有自己的 activity record。當前 action result、status 與 typed error 永遠高於 catalog prose。\n",
  "aliases": [
    "local tool 失敗",
    "桌面 timeout",
    "capability denied",
    "filesystem path denied",
    "desktop routing unavailable",
    "action cancelled"
  ],
  "tags": [
    "local",
    "errors",
    "debugging",
    "audit"
  ],
  "relatedActions": [],
  "relatedActionPrefixes": [
    "arinova.local."
  ],
  "url": "https://docs.arinova.ai/zh-tw/kb/local/errors-and-debugging/"
}
---

Local action 應依 gate 順序除錯。先處理 `LOCAL_DESKTOP_NOT_CONNECTED` 的連線；再看 capability：`LOCAL_CAPABILITY_UNAVAILABLE` 是 live runtime 缺少能力，`LOCAL_CAPABILITY_NOT_GRANTED` 是裝置／Agent 授權不符，`LOCAL_CAPABILITY_CHECK_FAILED` 是暫時檢查失敗。接著在不猜路徑、不擴張 root 的前提下處理 `LOCAL_FS_ROOT_DENIED`，再看 `DESKTOP_TOOL_TIMEOUT`／`DESKTOP_TOOL_CANCELLED`，最後才是 `DESKTOP_ROUTING_UNAVAILABLE`。

每個 action 都有 registry deadline；timeout 時 server 會發 kill 並把 action 視為失敗，不能宣稱完成。Availability error 要先修復連線或授權才可重試；timeout／cancelled 後應回報觀察到的狀態，並向使用者確認桌面實際狀況再決定。平台 routing unavailable 屬暫時問題，稍後重試合理。

Platform audit 只記 action identity、argument key names 與 serialized byte count、status／error metadata，以及 optional desktop audit ID；不記 argument values、本機 path、command text、clipboard、screenshot 或 tool result。Desktop 另有自己的 activity record。當前 action result、status 與 typed error 永遠高於 catalog prose。