Qwen3模型IDE插件开发：在IntelliJ IDEA中快速生成代码注释图

江卓尔

164人浏览 · 2026-03-20 00:57:49

江卓尔 · 2026-03-20 00:57:49 发布

Qwen3模型IDE插件开发：在IntelliJ IDEA中快速生成代码注释图

你有没有过这样的经历？接手一个复杂的项目，面对一段层层嵌套的业务逻辑代码，看了半天也理不清头绪。或者，自己写的代码过了几个月再回看，已经忘了当初为什么要这么设计。这时候，如果代码旁边能有一张清晰的流程图或类图，那该多省事。

传统的做法是，我们得手动打开绘图工具，一边看代码，一边画图，费时费力。现在，有了AI大模型的帮助，这件事可以变得自动化。今天，我就来分享一个实战项目：如何为IntelliJ IDEA开发一个插件，集成Qwen3模型的能力，实现“代码一键生成注释图”。

简单来说，这个插件能让你在IDEA里选中一段代码，然后插件会调用Qwen3模型，自动分析这段代码的逻辑，并生成对应的流程图、类关系图（使用Mermaid语法），最后以内联注释或侧边栏的形式展示出来。这不仅能极大提升代码审查、知识传承的效率，也让编写技术文档变得轻松不少。

1. 为什么要在IDE里集成代码图解能力？

在深入技术细节之前，我们先聊聊为什么这个场景值得投入。代码图解，或者说可视化，从来都不是一个新概念。UML图、架构图一直是我们理解和沟通软件设计的重要工具。但问题在于，画图这个动作本身是“滞后”且“费力”的。

开发者常常在写代码时思维高速运转，顾不上画图；等到需要向别人解释或者自己回顾时，又得重新梳理，消耗额外的认知资源。这种“文档负债”是很多项目的通病。

而将图解能力直接集成到IDE中，瞄准的就是“即时性”和“无感化”。你不需要切换上下文，不需要打开另一个软件，就在你写代码、读代码的同一个环境里，一键获取可视化视图。这相当于给你的IDE装了一个“实时翻译官”，能把抽象的代码逻辑“翻译”成更直观的图形语言。

对于团队协作来说，新成员能通过生成的图解快速理解模块结构；对于个人而言，它则是加强代码记忆和理解的绝佳助手。特别是处理遗留代码或复杂算法时，一张自动生成的图可能比读十遍代码都管用。

2. 整体方案设计：插件如何工作？

这个插件的核心工作流程可以概括为三步：捕获、分析、呈现。下面这张简单的序列图描绘了整个过程：

sequenceDiagram
    participant D as 开发者
    participant P as IDEA插件
    participant S as 插件后端服务
    participant Q as Qwen3模型API

    D->>P: 1. 在编辑器中选择代码块
    P->>P: 2. 提取选中代码文本
    P->>S: 3. 发送代码及生成请求（如流程图）
    S->>Q: 4. 构造Prompt，调用Qwen3 API
    Q-->>S: 5. 返回Mermaid图表代码
    S-->>P: 6. 返回图表代码或渲染后图片URL
    P->>P: 7. 解析并渲染图表
    P-->>D: 8. 以内联注释或侧边栏形式展示

第一步：捕获代码 当开发者在IntelliJ IDEA的编辑器中选中一段Java、Python或其他语言的代码后，插件会通过IDEA的PSI（程序结构接口）树获取选中区域的完整文本内容。这一步的关键是准确获取代码的上下文，有时还需要包含相关的类定义或方法签名，以便模型更好地理解。

第二步：调用AI分析 插件将捕获的代码文本，连同用户的指令（例如：“请为这段代码生成流程图”），一起发送到我们搭建的后端服务。这个服务的主要职责是构造一个精准的Prompt，然后调用Qwen3模型的API。Prompt的设计至关重要，我们需要明确告诉模型：输入是代码，期望输出是特定类型（流程图、类图、时序图）的Mermaid语法描述。

第三步：渲染与呈现 Qwen3模型返回的结果是一段Mermaid代码。插件需要能够解析这段代码，并在IDEA界面中渲染出来。我们有两种主要的呈现方式：一种是直接将Mermaid代码以注释的形式插入到源代码上方；另一种是在IDEA工具窗口（Tool Window）中开辟一个侧边栏，实时渲染并显示图表。后者交互体验更好，不会污染源代码。

3. 开发实战：从零搭建IDEA插件

接下来，我们进入动手环节。我会带你走过创建插件项目、集成Qwen3以及实现核心功能的关键步骤。这里假设你已经有基本的Java和IntelliJ插件开发知识。

3.1 创建插件项目与环境准备

首先，你需要安装IntelliJ IDEA（社区版或旗舰版均可），并确保安装了Plugin DevKit插件。这是官方提供的插件开发工具包。

新建项目：选择 File -> New -> Project...，在左侧选择 IntelliJ Platform Plugin。给你的项目起个名字，比如 CodeDiagramPlugin。
项目结构：创建完成后，你会看到标准的插件项目结构。重点关注 src/main/resources/META-INF/plugin.xml 文件，这是插件的配置文件，用于声明扩展点、动作等。
添加依赖：我们需要用到一个库来渲染Mermaid图表。虽然IDEA本身不直接支持Mermaid渲染，但我们可以通过集成一个基于JS的渲染库来实现。一种简单的方式是使用 JCEF（Java Chromium Embedded Framework）来嵌入一个浏览器组件，或者使用能够将Mermaid转换为SVG/PNG的Java库，如 kroki 的客户端。这里为了简化，我们假设后端服务已经将Mermaid代码转换成了图片URL返回，前端插件只需显示图片。因此，我们需要在 build.gradle.kts 或 pom.xml 中添加网络请求和图片加载的依赖，例如OkHttp和ImageIO。

3.2 实现核心动作：捕获代码与调用服务

插件的入口通常是一个Action（动作）。我们在用户右键菜单或工具栏添加一个按钮。

注册Action：在 plugin.xml 中注册一个新的 <action>。指定它的ID、显示文本，并将其分组到编辑器右键菜单（EditorPopupMenu）中。

<actions>
    <action id="GenerateCodeDiagram" class="com.yourpackage.GenerateDiagramAction"
            text="生成代码图解" description="为选中的代码生成流程图或类图">
        <add-to-group group-id="EditorPopupMenu" anchor="first"/>
    </action>
</actions>

实现Action类：创建 GenerateDiagramAction 类，继承 AnAction。重写 actionPerformed 方法。

public class GenerateDiagramAction extends AnAction {
    @Override
    public void actionPerformed(@NotNull AnActionEvent e) {
        // 获取当前项目和编辑器
        Project project = e.getProject();
        Editor editor = e.getData(CommonDataKeys.EDITOR);
        if (project == null || editor == null) return;

        // 获取选中的文本
        SelectionModel selectionModel = editor.getSelectionModel();
        String selectedText = selectionModel.getSelectedText();
        if (selectedText == null || selectedText.trim().isEmpty()) {
            Messages.showInfoMessage("请先选择一段代码。", "提示");
            return;
        }

        // 获取代码文件的类型（语言），用于提示模型
        PsiFile psiFile = PsiDocumentManager.getInstance(project).getPsiFile(editor.getDocument());
        String language = psiFile != null ? psiFile.getLanguage().getDisplayName() : "Unknown";

        // 弹出对话框，让用户选择要生成的图表类型
        // 这里省略对话框代码，假设用户选择了“流程图”
        String diagramType = "flowchart";

        // 调用后端服务
        callDiagramService(project, selectedText, language, diagramType);
    }

    private void callDiagramService(Project project, String code, String language, String diagramType) {
        // 使用OkHttp或其他HTTP客户端调用你的后端API
        // 构建请求体，包含代码、语言和图表类型
        // 处理响应，获取图片URL或Mermaid代码
        // 在主线程中更新UI，显示结果
    }
}

3.3 与Qwen3后端服务交互

callDiagramService 方法的具体实现依赖于你的后端服务设计。后端服务可以是一个简单的Spring Boot或Python Flask应用，它接收插件的请求。

后端服务的关键任务（Python示例）：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import requests
# 假设使用OpenAI兼容的API调用Qwen3
import openai

app = FastAPI()
openai.api_base = "https://your-qwen3-api-endpoint/v1" # Qwen3服务地址
openai.api_key = "your-api-key"

class DiagramRequest(BaseModel):
    code: str
    language: str
    diagram_type: str # flowchart, class, sequence, etc.

@app.post("/generate_diagram")
async def generate_diagram(request: DiagramRequest):
    # 构造精准的Prompt
    prompt = f"""
    你是一个代码分析专家。请将以下 {request.language} 代码转换为 Mermaid {request.diagram_type} 图表。
    只输出Mermaid代码，不要有任何额外的解释、描述或markdown代码块标记。

    代码：
    ```
    {request.code}
    ```
    """
    try:
        response = openai.ChatCompletion.create(
            model="qwen-plus", # 或其他Qwen3模型名称
            messages=[{"role": "user", "content": prompt}],
            temperature=0.1, # 低温度保证输出稳定性
            max_tokens=1000
        )
        mermaid_code = response.choices[0].message.content.strip()
        # 清理可能出现的markdown代码块标记
        mermaid_code = mermaid_code.replace('```mermaid', '').replace('```', '').strip()
        
        # 可选：将Mermaid代码转换为图片（使用Kroki等服务）
        # image_url = convert_mermaid_to_image(mermaid_code)
        # return {"mermaid": mermaid_code, "image_url": image_url}
        
        return {"mermaid": mermaid_code}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

插件中的HTTP调用：

private void callDiagramService(Project project, String code, String language, String diagramType) {
    // 使用协程或后台线程，避免阻塞UI
    ApplicationManager.getApplication().executeOnPooledThread(() -> {
        OkHttpClient client = new OkHttpClient();
        MediaType JSON = MediaType.get("application/json; charset=utf-8");
        
        String json = String.format("{\"code\": \"%s\", \"language\": \"%s\", \"diagram_type\": \"%s\"}",
                StringEscapeUtils.escapeJson(code), language, diagramType); // 注意转义
        
        RequestBody body = RequestBody.create(json, JSON);
        Request request = new Request.Builder()
                .url("http://your-backend-host:port/generate_diagram")
                .post(body)
                .build();
        
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful()) {
                String responseBody = response.body().string();
                // 解析JSON，获取mermaid_code或image_url
                // 回到UI线程更新界面
                ApplicationManager.getApplication().invokeLater(() -> {
                    displayDiagramInIDE(project, parsedMermaidCode);
                });
            }
        } catch (IOException e) {
            // 处理错误
        }
    });
}

3.4 在IDEA中渲染展示图表

拿到Mermaid代码或图片URL后，我们需要把它展示出来。这里介绍侧边栏工具窗口的方式，体验更佳。

创建工具窗口：在 plugin.xml 中注册一个 ToolWindow。

<extensions defaultExtensionNs="com.intellij">
    <toolWindow id="Code Diagram" anchor="right"
                factoryClass="com.yourpackage.DiagramToolWindowFactory"/>
</extensions>

实现ToolWindowFactory：创建 DiagramToolWindowFactory 类，实现 ToolWindowFactory 接口。在 createToolWindowContent 方法中创建并返回一个用于显示图表内容的 JComponent。

public class DiagramToolWindowFactory implements ToolWindowFactory {
    @Override
    public void createToolWindowContent(@NotNull Project project, @NotNull ToolWindow toolWindow) {
        // 创建一个面板，用于后续动态更新内容
        DiagramDisplayPanel panel = new DiagramDisplayPanel();
        ContentFactory contentFactory = ContentFactory.SERVICE.getInstance();
        Content content = contentFactory.createContent(panel, "", false);
        toolWindow.getContentManager().addContent(content);
        // 将panel的引用存储到项目级的组件中，以便其他地方更新
        project.putUserData(DIAGRAM_PANEL_KEY, panel);
    }
}

实现显示面板：DiagramDisplayPanel 可以是一个简单的 JPanel。如果后端返回的是图片URL，我们可以用 ImageIO 读取网络图片并显示；如果返回的是Mermaid代码，我们可以尝试在面板内嵌一个浏览器组件（通过JCEF）来实时渲染Mermaid。由于JCEF集成稍复杂，另一种折中方案是，将Mermaid代码再次发送给一个在线渲染服务（如mermaid.ink），获取图片后显示。

// 简化版：显示图片
public class DiagramDisplayPanel extends JPanel {
    private JLabel imageLabel;
    
    public DiagramDisplayPanel() {
        setLayout(new BorderLayout());
        imageLabel = new JLabel("图表将在这里显示", SwingConstants.CENTER);
        add(new JScrollPane(imageLabel), BorderLayout.CENTER);
    }
    
    public void updateDiagram(Image image) {
        imageLabel.setIcon(new ImageIcon(image));
        imageLabel.setText("");
    }
    
    public void updateDiagram(String mermaidCode) {
        // 调用一个本地或在线服务将mermaidCode转为图片，然后调用updateDiagram(Image)
        // 例如：String imageUrl = "https://mermaid.ink/img/" + Base64.getUrlEncoder().encodeToString(mermaidCode.getBytes());
        // 然后下载并显示这个图片
    }
}

更新显示：在 callDiagramService 的成功回调中，获取到存储的 DiagramDisplayPanel，并调用其 updateDiagram 方法。

4. 效果展示与实际应用场景

开发完成后，这个插件用起来是什么感觉呢？我来描述几个典型的应用场景。

场景一：理解复杂业务逻辑 你看到一段处理订单状态机的代码，有大量的 if-else 和 switch 语句。选中这段代码，点击“生成代码图解”，选择“流程图”。几秒钟后，右侧边栏出现了一张清晰的流程图，清晰地展示了“下单”、“支付”、“发货”、“完成”、“取消”等各种状态之间的转换条件和路径。你一眼就看懂了核心逻辑，比逐行阅读代码快得多。

场景二：梳理类关系 在阅读一个陌生的模块时，你选中了其中几个核心的类文件。插件可以分析它们之间的继承、实现、依赖和关联关系，生成一张UML类图。这张图帮你快速构建起了模块的静态结构模型，对于理解设计意图非常有帮助。

场景三：辅助编写文档 当你需要为某个API接口编写说明文档时，你可以选中接口的实现方法，生成一张时序图。这张图清晰地展示了从控制器到服务层，再到数据层的调用序列，直接粘贴到你的Markdown文档里，图文并茂，专业又清晰。

实际效果的关键点：

准确性：Qwen3模型对代码逻辑的理解能力决定了图表的准确度。在实践中，对于结构清晰的代码，生成流程图和类图的准确率很高。对于特别复杂或模糊的代码，可能需要人工稍作调整。
速度：从选中代码到图表呈现，整个流程通常在几秒到十几秒之间，取决于代码长度和网络延迟，基本可以满足“即时反馈”的需求。
集成度：与IDEA深度集成，操作流程无缝，真正做到了“所想即所得”，不会打断开发者的编码心流。

5. 总结与展望

开发这样一个插件，本质上是在打造一个“智能开发伴侣”。它把AI对代码的深层理解能力，以最直观、最便捷的方式送到了开发者的手边。从技术实现上看，它融合了IDE插件开发、大模型API调用、前后端交互等多个环节，是一个非常好的全栈实践项目。

实际用下来，这个工具在代码审查、新人入职引导、技术文档编写等场景下，确实能带来效率的显著提升。它降低了对复杂代码的理解门槛，让“代码即文档”的理想更近了一步。当然，它也不是万能的，生成的图表有时需要人工校验和微调，但对于大多数常规代码逻辑，已经足够可靠。

如果你也想尝试开发类似插件，我的建议是从一个简单的功能开始，比如只支持生成流程图，只返回Mermaid代码在通知栏显示。先跑通整个链路，再逐步完善UI和增加图表类型。未来，这个插件还有很多可以探索的方向，比如支持更多的图表类型（架构图、状态图）、与代码版本管理结合生成差异图、甚至根据图表反向生成代码骨架等。