SDK 排障与错误处理
定位认证、模型、集成、并发和运行时问题，保留可追踪的错误信息。
先记录错误 code、status、request ID 和实际运行时，再决定修配置或重试。无限重试无法解决缺权限、模型无效或 Agent 正忙。
常见问题
| 错误或症状 | 检查与处理 |
|---|---|
| AuthenticationError | 用户/服务账号 key、过期和管理员禁用；Team Admin key 不支持 |
| ConfigurationError | 模型 ID/参数、文件路径、平台 helper 与配置组合 |
| IntegrationNotConnectedError | 用 provider 与 helpUrl（Python help_url）打开对应源码集成重连 |
| AgentBusyError | 云端同一 Agent 已有 CREATING/RUNNING，等待或取消后再发 |
| AgentNotFoundError | ID、cwd 和 local.store 是否与创建时一致 |
| UnsupportedRunOperationError | 接口能力与当前 Run 状态 |
| RateLimitError | 区分瞬时限流和月度用量上限 |
| NetworkError | 代理、连接、服务可用性，按可重试标记退避 |
TypeScript 的 agent_busy 标记 isRetryable: false，Python 同样为 False；立即重发不会解除忙状态。其他 409，例如 agent_archived，可能映射 ConfigurationError，不能把所有冲突都按忙处理。本地不返回同样的 AgentBusyError；force 用于过期卡住的轮，使用前确认状态。
不要丢掉错误元数据
TypeScript 错误继承 CursorSdkError，旧名 CursorAgentError 为兼容导出；检查 isRetryable、code、status、cause、endpoint、requestId、operation。helpUrl 不一定出现在默认 message 中，需要显式记录。
Python 以 CursorAgentError/CursorSDKError 捕获，使用 is_retryable 和 retry_after；retry_after 可以是秒数字符串或 HTTP 日期，不能一律 float 转换。官方简例只展示数值处理，完整客户端应按实际返回格式解析。
Python 日志与 Bridge
CURSOR_SDK_LOG=debug python my_script.py
cursor-sdk-bridge --helpCURSOR_SDK_LOG 支持 debug/info，仅配置 cursor_sdk logger，不接管宿主整体日志。Bridge 层问题再使用Bridge 诊断，区分 Python HTTP client 与嵌入运行时错误。
看似状态丢失的情况
- 再次 create 是新 Agent，继续旧对话使用 resume。
- inline MCP 与工具限制不自动跨恢复保留，重新传入必要选项。
- SDK 云端任务在界面中需要 Filter > Source > SDK。
- 本地默认 SQLite 不可用时必须配置其他 store，不能等待自动回退。
- 本地账单查询 feature_unavailable 是账号逐步开放，不代表本次没有 token 消耗。
- Python 流已消费不能再从另一 iterator 重放，读取 Run 的最终结果。
本地调用能访问文件但模型仍需 Cursor 服务，离线网络问题不会因为选择 local 消失。