錯誤模型

先從症狀判斷

工具失敗時，先把看得到的症狀對應到可能原因與第一個處理動作，再往下檢查詳細欄位。

錯誤或症狀	可能原因	第一個動作
`connect` 回傳 `SecurityError`	target 不在 `WPFDEVTOOLS_MCP_ALLOWED_TARGETS`，或 installed package / security check 失敗	確認 exact local absolute executable path，並確認 installed server path 位於 `<InstallRoot>\<arch>\current\bin\`。
`InvalidPolicyConfiguration`	policy environment variable 格式錯誤	修正 variable value、移除 ambiguous entries，然後重啟 MCP server/client process。
`ArchitectureMismatch`	Raw injection 需要與 target process bitness 相同的 bootstrapper	使用 matching x86/x64 package；如果是自有 app，優先改用 SDK-hosted reuse。
`PipeReadyTimeout`	Bootstrap 已啟動，但 Inspector pipe 沒有在時間內 ready	重新 connect，確認 elevation / architecture，並讀取 `recovery.requiresReconnect` 與 `recovery.timeoutSeconds`。
`InteractionNotReady` 或互動後沒有可見效果	element 可能 hidden、disabled、blocked、offscreen，或不是你真正想操作的元素	已取得具體 `elementId` 後，先跑 `get_interaction_readiness` 或 `get_element_snapshot(elementId)`。
Mutation timeout 且 state unknown	request 可能在 timeout 前已改變 target state	重新連線、重新讀取 state，並以 `recovery.stateAfterTimeoutUnknown` 為準。
Rate limit response	session 超過 server-side limit	依 `recovery.retryAfterSeconds` 或 `recovery.retryAfter` back off。

失敗層級

一個工具呼叫可能在多個層級失敗：

MCP transport 或 protocol 層
Server tool execution 層
Inspector response 層
Injection/bootstrap 層

建議檢查欄位

若回應中有這些欄位，建議依序檢查：

isError（MCP response 層）
success（structured content 層）
error
errorCode
recovery，提供自動恢復指引的 canonical recovery object
errorData

為了相容舊版 client，相同值也可能在回應中投影成這些 top-level compatibility projection fields。若 recovery.* 與 top-level 欄位同時存在，請優先使用 recovery.*：

hint
suggestedAction
requiresReconnect
stateAfterTimeoutUnknown
processId
timeoutSeconds
retryAfterSeconds
retryAfter
availableTokens
availableEvents

與 injection 相關的失敗

重要的 injection 階段結果包含：

ArchitectureMismatch
BootstrapFailed
PipeReadyTimeout

解讀方式

Architecture mismatch：ArchitectureMismatch 是 injection/bootstrapper error。raw injection 需要與目標行程 bitness 一致的 server/bootstrapper build；SDK-hosted reuse 透過 named pipes 通訊，target-side host 已啟動後不要求 server process 與 target process bitness 相同。
Bootstrap failed：bootstrapper 已啟動，但在 inspector 完全 ready 之前就失敗。
Pipe ready timeout：managed bridge 可能已被呼叫，但 named pipe 沒有在時限內 ready。

Recovery contract 重點

新的工具回應除了 errorCode 之外，還可能提供 canonical recovery object 作為可直接執行的 recovery 提示。請先讀取 canonical recovery object，再將 top-level compatibility projection fields 視為提供給舊版 client 的 additive mirror。

recovery.suggestedAction：給人類或 agent 的明確下一步，例如 retry、reconnect，或以系統管理員權限重新啟動 MCP server。
recovery.requiresReconnect：表示先前的 pipe-backed session 應視為 stale，重試前需要重新呼叫 connect。
recovery.stateAfterTimeoutUnknown：表示 timeout 的 mutation 或 pipe-backed 操作可能已改變 target state；應先 reconnect 並重新讀取狀態，再判斷成功或失敗。
recovery.processId：與 reconnect 或 timeout 提示相關的目標 process。
recovery.timeoutSeconds：本次逾時所對應的 server-side timeout 預算。
recovery.retryAfterSeconds 與 recovery.retryAfter：提供 rate limit 的 deterministic backoff 提示。

例子：

Timeout 回應可能同時帶有 errorCode、recovery.requiresReconnect、recovery.stateAfterTimeoutUnknown、recovery.processId 與 recovery.timeoutSeconds，讓 client 分辨是 stale pipe、target state unknown，還是單純操作太慢。
Rate-limit 回應可能帶有 recovery.retryAfterSeconds 與 recovery.retryAfter，方便 agent 排程重試。
Elevation 或 access denied 回應可能將 errorCode 與 recovery.suggestedAction 配對，避免 client 只能從錯誤文字猜測下一步。

給 AI agent 的回報建議

當操作失敗時，請讓 agent 一併回報：

工具名稱
目標 process ID
完整錯誤文字
recovery object，以及任何 mirror 出來的 suggestedAction、requiresReconnect、stateAfterTimeoutUnknown 或 retryAfterSeconds compatibility 欄位
涉及的架構
目前 build 是 Debug 還是 Release

這些資訊足夠讓大多數安裝與連線問題快速被定位。