IntelliJ 的 PSA 插件：自定义自动补全

PSA：利用 PSI 上下文在 IntelliJ 中实现自定义补全与导航

PSA 插件让开发者能够在 IntelliJ IDEA 内直接为项目定制补全、导航和代码模板。只需编写任意语言的脚本，分析当前的 PSI 树并返回建议，即可解决无需安装独立插件就能支持自定义框架的难题。

PSI 上下文如何工作

当您在设置中指定可执行脚本路径后，插件即被激活。触发补全（Ctrl+Space）或跳转（GoTo）时，系统会生成一个 PSA 上下文——即聚焦元素的简化 PSI 树。该树以 JSON 格式写入临时文件（受限于命令行参数长度），并通过 PSA_CONTEXT 环境变量传递给脚本。

以 PHP 为例：

<?php

function myFunc() {
    $l = '';
//        ^   光标位置
}

生成的 JSON 包含元素的层级结构：

{
  "elementType": "right single quote",
  "elementName": null,
  "elementFqn": null,
  "text": "'",
  "parent": {
    "elementType": "String",
    "text": "''",
    // ... 递归嵌套至文件层级
  }
}

每个 PSI 节点包含 elementType、elementName、elementFqn、text、textRange（起始/结束偏移）、parent/prev/next 关系以及扩展选项。

脚本接收的环境变量

脚本将获取以下变量：

• PSA_CONTEXT：包含 PSI 树的 JSON 文件路径。
• PSA_TYPE：值为 Completion 或 GoTo。
• PSA_LANGUAGE：编程语言（如 PHP、JS 等）。
• PSA_DEBUG：调试开启时设为 1。
• PSA_OFFSET：光标在元素内的位置。

脚本解析树结构，结合上下文（当前元素及其父级）判断建议内容。Completion 类型返回选项数组；GoTo 类型返回带 link 的单一结果。

脚本响应格式

返回 JSON 响应：

{
  "completions": [
    {
      "text": "插入文本",
      "link": "FileName.php:42:5", // 仅用于 GoTo
      "bold": true,
      "priority": 10
    }
  ],
  "notifications": ["调试信息"],
  "gotoElementTypes": ["FUNCTION", "CLASS"] // 性能过滤器
}

priority 用于排序结果，bold 可高亮条目。gotoElementTypes 限制跳转范围，提升性能。

文档与 Swagger 支持

插件基于 API 模型自动生成 Swagger UI，清晰展示接口结构。方法虽为模拟，但准确描述调用方式。使用 OpenAPI Generator 可快速生成脚本所需的 DTO 类。

PSI 元素结构说明：

• elementType：元素类型（如 STRING、FUNCTION）。
• elementName/Fqn：名称或全限定名。
• options：参数字典。
• text：原始源码文本。
• textRange：偏移量区间。
• 关系字段：parent、prev、next。

配置与性能优化

启用插件并指向您的脚本。开启 PSA_DEBUG 便于排查问题。通过 gotoElementTypes 过滤器减少跳转开销。

相比专用框架插件的优势：

• 项目级依赖，非全局配置。
• 支持自定义 API 和代码模板。
• 脚本语言无限制，兼容性更强。

示例脚本（伪代码）：

#!/bin/bash
context=$(cat $PSA_CONTEXT | jq .)
if [[ $PSA_TYPE == "Completion" ]]; then
  # 分析逻辑
  echo '{"completions": [{"text": "customFunc()"}]}'
fi

核心要点

• PSA 传递完整 PSI 树，确保精准上下文分析。
• 脚本可通过 priority 和 bold 实现自定义排序与高亮。
• GoTo 支持 file:line:pos 链接及 elementType 过滤。
• Swagger 文档加速 DTO 开发流程。
• 适用于任何项目语言（PHP、JS/TS 等）。

— Editorial Team