用途：面向 Speckle 开发与运维场景，帮助定位认证与授权类错误，包括 HTTP 401/403、GraphQL UNAUTHENTICATED/FORBIDDEN/NOT_FOUND、PAT 作用域不匹配、OAuth2 流程配置错误、刷新令牌失效以及 SpecklePy 认证异常。
主要能力：提供认证错误决策树，按 401、403、NOT_FOUND、OAuth 失败、刷新失败分类给出排查顺序；给出错误码与协议对照表；列出各操作所需作用域与角色（如 streams:read、streams:write、profile:read、server:setup 等）；区分 401 与 403 的语义差异；覆盖 PAT 常见错误、OAuth2 challenge 与 redirect URI 匹配、访问码时效、刷新令牌单次使用等要点；并说明 Speckle Cloud 与自托管服务器在 GraphQL 端点、认证重定向、令牌交换上的差异。
使用方式：按决策树逐项检查，例如用 query { activeUser { id name } } 验证令牌有效性，用 serverInfo 查询确认目标服务器与可用认证策略，用 project 查询检查角色与细粒度权限。SpecklePy 可用 SpeckleClient 配合 authenticate_with_token 或 authenticate_with_account 进行验证。创建令牌时可使用 apiTokenCreate 指定 scopes、lifespan 与 limitResources。
适用场景：调试 Speckle API 集成、前端 OAuth 应用、自托管实例认证、PAT 权限不足、跨服务器令牌误用等问题。
限制：资料未提供具体价格、平台支持范围或性能数据；部分修复步骤依赖 Speckle 服务端配置与管理员权限，实际行为以对应服务器版本为准。