Error Recovery¶
目的：错误恢复流图 关联：topics/error-codes.md、analysis/error-handling-overview.md
1. 错误处理总览¶
graph TD
A[Error] --> B{type}
B -->|transient| C[retry]
B -->|permanent| D[fail]
B -->|auth| E[refresh]
B -->|rate limit| F[backoff]
B -->|validation| G[fix input]
B -->|tool| H[report]
C -->|max retry| D
E -->|max refresh| I[OAuth flow]
F -->|max wait| D
I -->|user cancel| D
I -->|success| J[retry original]
G --> K[user fix]
H --> L[continue with placeholder]
D --> M[log + show user]8 路径。
2. 5 步 Retry 流¶
sequenceDiagram
participant Sys as System
participant LLM
participant User
Sys->>LLM: call 1
LLM-->>Sys: 500 error
Sys->>Sys: wait 1s
Sys->>LLM: call 2 (retry 1)
LLM-->>Sys: 500 error
Sys->>Sys: wait 2s
Sys->>LLM: call 3 (retry 2)
LLM-->>Sys: success
Sys->>User: result
Note over Sys: 3 attempts max5 步。
3. 4 步 OAuth 401 流¶
sequenceDiagram
participant Client
participant Server
participant IdP
Client->>Server: 401 Unauthorized
Client->>Client: pending401Handlers.has(serverId)?
alt already refreshing
Client->>Client: 等待
else not refreshing
Client->>IdP: refresh token
IdP-->>Client: new access_token
end
Client->>Server: retry with new token
Server-->>Client: success4 步 + 去重。
4. 5 步 Rate Limit 流¶
sequenceDiagram
participant Client
participant Server
Client->>Server: call
Server-->>Client: 429 Too Many Requests
Note over Client: check Retry-After header
Client->>Client: wait (exponential backoff)
Client->>Server: retry
alt 200
Server-->>Client: success
else 429
Server-->>Client: 429
Client->>Client: increase backoff
end5 步。
5. 3 步 Bash parse 失败¶
graph TD
A[parseBash] --> B{50ms timeout?}
B -->|yes| C[return null, fail safe]
B -->|no| D{50K nodes?}
D -->|yes| E[return null, fail safe]
D -->|no| F[parse result]
C --> G[deny as fail safe]
E --> G
F --> H[正常 check]3 步 fail safe。
6. 4 步 MCP Session Expired¶
sequenceDiagram
participant Client
participant Server
Client->>Server: tools/call (old session)
Server-->>Client: McpSessionExpiredError
Client->>Client: isMcpSessionExpiredError(e) = true
Client->>Server: reconnectMcpServer
Server-->>Client: new session
Client->>Server: tools/call (new session)
Server-->>Client: success4 步。
7. 3 步 Plugin 加载失败¶
graph TD
A[loadPlugin] --> B{error?}
B -->|manifest not found| C[skip plugin, continue]
B -->|hooks path invalid| D[skip plugin, log]
B -->|MCP error| E[skip MCP, continue]
C --> F[next plugin]
D --> F
E --> F3 步（宽容失败）。
8. 4 步 Auth Cancellation¶
graph TD
A[OAuth flow] --> B{window open}
B --> C{user action}
C -->|approve| D[complete flow]
C -->|cancel| E[AuthenticationCancelledError]
C -->|timeout| F[timeout error]
D --> G[success]
E --> H[log + show user]
F --> I[auto cancel]
H --> J[next attempt]
I --> J4 步。
9. 5 步 AbortController¶
sequenceDiagram
participant CC as Claude Code
participant Abort as AbortController
participant Op as Long Operation
CC->>Abort: create
CC->>Abort: setTimeout(1000ms, abort)
CC->>Op: with signal
Op->>Op: do work
alt completed < 1s
Op-->>CC: result
CC->>Abort: cancel timer
else timeout
Abort->>Op: abort
Op-->>CC: AbortError
CC: fail safe
end5 步。
10. 4 步 Hook 失败恢复¶
graph TD
A[run hook] --> B{exit code}
B -->|0| C[allow]
B -->|2| D[block + stderr]
B -->|other| E[error, but allow]
B -->|timeout| F[treat as exit other]
B -->|exception| G[catch, treat as error]
C --> H[next step]
D --> H
E --> H
F --> H
G --> H4 步（永不阻塞）。
11. 5 步 Classifier 失败¶
sequenceDiagram
participant Spec as speculativeChecks Map
participant LLM
Spec->>LLM: classifier call
alt 200
LLM-->>Spec: { decision, reason }
else error
LLM-->>Spec: error
Spec->>Spec: clear pending
end
Spec-->>Spec: consumeSpeculativeClassifierCheck
alt no result
Spec-->>Caller: return null
Caller->>Caller: fall back to user ask
end5 步。
12. 4 步 Telemetry 失败¶
graph TD
A[logEvent] --> B{Statsig 200?}
B -->|yes| C[ok]
B -->|no| D[retry?]
D -->|yes| E[retry 1x]
D -->|no| F[drop, continue]
E -->|success| C
E -->|fail| F
F --> G[don't block main]4 步（不影响主流程）。
13. 5 步 Keychain 失败¶
graph TD
A[getApiKeyFromMacOSKeychain] --> B{keychain ok?}
B -->|yes| C[return key]
B -->|no| D{macOS only?}
D -->|no| E[return null, fallback to env]
D -->|yes| F{key not found?}
F -->|yes| G[return null, fallback]
F -->|no| H[error, log]
E --> I[next fallback]
G --> I
H --> I5 步。
14. 3 步 AWS STS 失败¶
graph TD
A[refreshAwsAuth] --> B{STS ok?}
B -->|yes| C[cache 1h]
B -->|no| D{3 min timeout}
D -->|yes| E[wait + retry]
D -->|no| F[fail, use last cache]
C --> G[return]
E -->|success| C
E -->|fail| F
F --> G3 步。
15. 4 步 Compact 失败¶
graph TD
A[compact] --> B{success?}
B -->|yes| C[replace history]
B -->|no| D{retry?}
D -->|yes| E[compact with smaller window]
D -->|no| F[skip compact, continue]
C --> G[next turn]
E -->|success| C
E -->|fail| F
F --> G4 步。
16. 5 步 Cost 超限¶
graph TD
A[API call] --> B{cost > max_budget_usd?}
B -->|yes| C[stop, throw]
B -->|no| D{cost > 80% max?}
D -->|yes| E[warn user]
D -->|no| F{turns > max_turns?}
F -->|yes| G[stop, summarize]
F -->|no| H[continue]
C --> I[session end]
E --> H
G --> I
H --> J[next turn]5 步。
17. 4 步 Network 失败¶
graph TD
A[HTTP request] --> B{status}
B -->|timeout| C[retry with backoff]
B -->|connection refused| C
B -->|500+| C
B -->|404| D[fail, log]
B -->|401| E[refresh + retry]
C -->|max retry| F[fail]
E -->|success| G[return]
E -->|fail| F4 步。
18. 3 步 Disk Full¶
graph TD
A[write file] --> B{ENOSPC}
B -->|yes| C[log error]
C --> D[提示 user 清空间]
D --> E[retry or skip]
B -->|no| F[normal write]3 步。
19. 5 步 Plugin Hook 失败¶
graph TD
A[plugin hook] --> B{path safe?}
B -->|no| C[skip hook, log]
B -->|yes| D{command exists?}
D -->|no| C
D -->|yes| E[run with timeout]
E -->|exit 0| F[ok]
E -->|exit 2| G[block]
E -->|non-0| H[error, continue]
E -->|timeout| I[timeout error]5 步。
20. 4 步 feature('X') 失败¶
graph TD
A[feature('X')] --> B{编译时?}
B -->|yes| C[常量替换]
B -->|no| D[运行时 DCE 不生效]
C --> E[true/false]
E -->|true| F[require module]
E -->|false| G[null]
F -->|module 不存在| H[require throws]
H --> I[catch, log, fallback]
G --> J[skip, null check]4 步。
21. 总结¶
Error Recovery = 8 路径 + 5 兜底。
核心： - 22 mermaid 图 - 8 错误处理路径 - 5 兜底原则 - 永不阻塞主流程
下一步： - 渲染 SVG - 加到 mkdocs