用途：Symbol API 是 IntelliJ 平台对“把 PsiReference 解析为 PsiElement”的通用替代方案。Symbol 表示某个模型（语言、框架、数据库 schema）中的语义元素，使导航、查找用法、重命名和文档与 PSI 解耦。Symbol 不要求由 PsiElement 支撑，也不应从 Symbol 反向获取 PsiElement。典型例子包括 Java 局部变量、JDK stub 中的已编译类、Spring bean、数据库列。
主要能力：通过 PsiSymbolDeclaration 提供声明（可为 0、1 或多个）；通过 PsiSymbolReference 提供引用，分为自有引用（PsiElement.getOwnReferences）、外部引用（宿主实现 PsiExternalReferenceHost，其他插件注册 PsiSymbolReferenceProvider）和隐式引用（ImplicitReferenceProvider，仅支持解析到目标，不支持从目标查找用法或重命名）。将 Symbol 接入平台功能需实现 NavigatableSymbol（导航）、SearchTarget/SearchTargetSymbol（查找用法）、RenameableSymbol/RenameTarget（重命名）和 DocumentationTarget（文档）。
使用方式：equals/hashCode 必须反映语义同一性，平台将其用作缓存键。生命周期为单个读操作：Symbol 可在同一读操作内跨 API 传递，但不可跨读操作引用；应在有效时调用 createPointer() 保存 Pointer，在下一个读操作中调用 Pointer.dereference()。声明可通过 EP com.intellij.psi.declarationProvider 注册 PsiSymbolDeclarationProvider，或直接在 PsiElement 上实现 PsiSymbolDeclaration。外部引用通过 EP com.intellij.psi.symbolReferenceProvider 注册 PsiSymbolReferenceProviderBean，声明 hostLanguage、hostElementClass、targetClass、referenceClass 和 implementationClass。隐式引用通过 EP com.intellij.psi.implicitReferenceProvider 注册。
适用场景与限制：建议优先使用 PolySymbols（PolySymbol 继承 Symbol），其查询执行器、补全基类和默认的 searchTarget/renameTarget/getDocumentationTarget/getNavigationTargets 可省去大量样板代码。仅当符号确实不符合 PolySymbols 模型时才直接使用原始 Symbol/PsiSymbolReference API，例如单次自包含解析（格式字符串占位符、Markdown 链接标签），或非项目绑定、非 PSI 支撑的符号（JDK stub 编译类、数据库列）。语言支持不应假设外部引用不存在。隐式引用不会被索引为可搜索引用，因此无法通过查找用法或从目标重命名找到。官方文档见 Symbols、Declarations and References。