Rider接入豆包与智谱AI的插件开发实战指南

1. 项目概述：为什么 Rider 开发者需要接入豆包与智谱 AI？

Rider 是 JetBrains 推出的专注于 .NET 生态的跨平台 IDE，它不像 IntelliJ IDEA 那样原生内置 AI Assistant（2024 年前），也不像 VS Code 那样有海量社区驱动的 AI 编程插件生态。但它的底层架构与 IntelliJ 平台完全一致——这意味着，只要满足 IntelliJ 插件规范、正确调用平台提供的 Language Server 和 Editor API，就能在 Rider 中实现和 IDEA 几乎一致的 AI 辅助能力。而“Rider 接入豆包、智谱 AI”这件事，本质上不是“给 Rider 装个聊天框”，而是在 Rider 的编辑器上下文里，把本地代码结构、光标位置、选中文本、当前文件语义，实时转化为符合豆包开放平台或智谱 ZCode API 规范的请求体，并将返回的结构化响应（如补全建议、解释、重构提示）精准渲染进编辑器的智能提示区、侧边栏或悬浮窗中。

我从 2023 年底开始在团队内部推动 Rider + 自研 AI 工具链落地，覆盖 C#、F#、ASP.NET Core、Unity C# 等多个技术栈。当时我们试过三种路径：一是硬改 Rider 源码（不可行，闭源且更新频繁）；二是用外部进程 + IPC（延迟高、状态难同步）；三是走标准 IntelliJ 插件路线——最终选定第三条，也是目前唯一稳定、可维护、能随 Rider 升级平滑演进的方案。核心关键词“Rider”“豆包”“智谱”“配置”背后，实际对应的是三个真实痛点：

• Rider 用户缺开箱即用的 AI 编程支持：官方未提供，社区插件稀少且多为 Demo 级别；
• 豆包开放平台（doubao.com/open）提供稳定、低延迟、中文语义强的通用大模型服务，尤其在技术文档理解、API 用法解释、错误日志归因上表现优于多数开源模型；
• 智谱 ZCode（zhipu.ai/zcode）则专为开发者设计，其glm-4-flash和glm-5.1在代码生成、单元测试编写、SQL 生成、正则表达式推导等任务上通过了大量 .NET 场景实测，且支持流式响应、函数调用（Function Calling）、工具调用（Tool Calling）等关键能力，是构建真正“可编程 AI 助手”的基础设施。

所以这不是一个“换个 API Key 就能用”的配置教程，而是一套完整的、面向 .NET 开发者的 AI 工具链集成方案。它适合三类人：

• 正在用 Rider 做企业级 .NET 开发，厌倦了反复切窗口查文档、写重复样板代码的工程师；
• 技术负责人或 DevOps 工程师，需要为团队统一部署可控、合规、可审计的 AI 编程辅助能力；
• 对 IntelliJ 插件开发感兴趣，想深入理解 IDE 如何与大模型协同工作的技术爱好者。

接下来我会从设计思路、核心细节、实操步骤、问题排查四个维度，把这套方案拆解到每一行代码、每一个参数、每一次网络请求的粒度。不讲虚的，只说我在生产环境跑通、压测、灰度上线后验证过的做法。

2. 整体设计与思路拆解：为什么必须绕过“插件市场”，自己动手写插件？

很多人看到标题第一反应是：“去 JetBrains Marketplace 搜一下有没有现成插件？”——我试过。截至 2024 年 7 月，Marketplace 上标称支持“豆包”或“智谱”的 Rider 插件共 0 个；标称支持“AI Assistant”的插件有 3 个，其中 2 个已下架，1 个仅支持 OpenAI 兼容接口（如 Ollama、LM Studio），且无法处理 Rider 特有的PsiElement结构解析、DataContext上下文提取、CodeInsight提示注入等关键能力。换句话说，市面上没有能直接拿来用的、适配 Rider 的豆包/智谱插件。这不是偶然，而是由 Rider 的技术定位决定的。

Rider 的核心优势在于对 .NET 生态的深度理解：它能准确识别IActionResult返回类型、[ApiController]特性、DbContext生命周期、xUnit测试方法签名……这些信息如果只是简单地拼成一段文本发给大模型，效果会大打折扣。真正有效的 AI 辅助，必须是“语义感知型”的：比如当光标停在var result = await _httpClient.GetAsync(...)这一行时，插件应自动提取_httpClient的声明类型（IHttpClientFactory？HttpClient？）、GetAsync方法的完整签名、当前命名空间引用的System.Net.Http版本，并结合 Rider 的 PSI（Program Structure Interface）树，判断该调用是否在try/catch块内、是否被ConfigureAwait(false)包裹——这些才是影响 AI 给出“是否需加超时”“是否要检查 StatusCode”等建议的关键上下文。

因此，我们的整体设计不是“调 API”，而是构建一个三层协同架构：

2.1 第一层：IDE 插件层（IntelliJ Platform Plugin）

这是 Rider 中运行的 Java/Kotlin 插件，负责：

• 监听编辑器事件（光标移动、按键、选中变化）；
• 从 PSI 树中提取结构化代码信息（如当前方法名、参数列表、返回类型、所在类的继承链）；
• 构建符合豆包/智谱 API 规范的messages数组（注意：不是简单拼接字符串，而是按角色system/user/assistant分层组织，system消息中嵌入 Rider 版本、.NET SDK 版本、当前项目 SDK 类型等元信息）；
• 处理流式响应（SSE），将delta.content实时渲染为编辑器内的“AI 补全建议”（类似 VS Code 的 Copilot）；
• 支持快捷键触发（默认Alt+Q查释义，Alt+R重构，Alt+T写测试）；
• 与 Rider 的 Settings UI 深度集成，提供 Token 管理、模型切换、超时设置、代理配置等界面。

这个插件必须用 Kotlin 编写（Java 也可，但 Kotlin 更简洁），基于intellij-community的platform/core-api和platform/lang-api模块。我们不使用任何第三方 HTTP 客户端库（如 OkHttp），而是复用 Rider 自带的com.intellij.util.io.HttpRequests，确保 SSL 证书信任链、代理设置、认证机制与 Rider 主程序完全一致——这点在企业内网环境下至关重要，避免出现“浏览器能访问豆包 API，Rider 插件却报 SSLHandshakeException”的经典问题。

2.2 第二层：协议适配层（Protocol Adapter）

豆包开放平台和智谱 ZCode 的 API 并不完全兼容：

• 豆包使用POST /v1/chat/completions，model参数为doubao-pro或doubao-lite，response_format支持text或json_object；
• 智谱使用POST /v4/chat/completions，model为glm-4-flash或glm-5.1，强制要求tools字段用于函数调用，且tool_choice控制调用策略；
• 两者都支持stream: true，但豆包的 SSE event 名为message，智谱为chat.completion.chunk，字段名也不同（豆包用content，智谱用delta.content）。

如果在插件层硬编码两套逻辑，会导致维护成本指数级上升。所以我们抽象出一个AiProvider接口：

interface AiProvider { fun buildRequest( context: EditorContext, messages: List<ChatMessage>, model: String, temperature: Double ): HttpRequest fun parseResponse(chunk: String): ChatResponseChunk? fun getSupportedModels(): List<ModelInfo> }

然后分别实现DoubaoProvider和ZhipuProvider。这样，当未来豆包升级 v2 API 或智谱推出glm-6，只需修改对应 Provider 的实现，插件主逻辑完全不动。这个设计已在我们团队支撑了 5 次 API 升级，零故障。

2.3 第三层：安全网关层（可选，但强烈推荐）

在企业环境中，直接让 Rider 插件访问公网大模型 API 存在风险：

• Token 泄露（用户在 Settings 里填的 API Key 可能被恶意插件读取）；
• 请求内容审计缺失（无法记录谁在何时问了什么）；
• 网络策略限制（部分公司禁止 IDE 直连外网）。

我们的解决方案是部署一个轻量级网关服务（Go 编写，单二进制，<10MB），部署在内网 Kubernetes 集群中。它只做三件事：

• 接收 Rider 插件发来的/gateway/chat请求（携带加密的provider_id和user_id）；
• 根据provider_id查内部配置表，获取真实的豆包/智谱 API Key（Key 存于 Vault 中，网关启动时动态拉取）；
• 转发请求并透传响应，同时将user_id、model、prompt_tokens、completion_tokens、timestamp记入审计日志（对接公司 SIEM 系统）。

这个网关不是必须的，但如果你的团队有合规要求（如等保三级、ISO 27001），它能帮你省下至少 3 个月的安全评审时间。我们用它替代了最初直接在插件里存 Key 的方案，上线后安全团队一次过审。

提示：不要试图用 Nginx 或 Apache 做这个网关。它们无法动态注入 Token、无法做细粒度审计、无法与 Rider 插件的认证体系（如 JWT）无缝集成。必须是专用服务。

3. 核心细节解析与实操要点：从零搭建插件工程的 7 个关键决策

搭建一个能在 Rider 中稳定运行的 AI 插件，远不止“新建项目 → 写点 Kotlin → 打包”。每一个技术选型背后，都是踩过坑后的经验沉淀。以下是我在初始化插件工程时做的 7 个关键决策，每个都附带“为什么这么选”和“不这么选会怎样”。

3.1 构建工具：Gradle + Kotlin DSL（而非 Maven + XML）

Rider 插件开发官方推荐 Gradle，但很多教程仍用 Maven。我们坚持用 Gradle Kotlin DSL（build.gradle.kts），原因很实在：

• 类型安全：intellij { version = "2023.3.3" }编译期就校验版本是否存在，Maven 的<version>2023.3.3</version>到打包时才报错；
• 依赖管理清晰：Kotlin DSL 支持dependencies { implementation(intellijPlugin("com.example:my-plugin:1.0")) }，避免 Maven 中常见的dependencyManagement与dependencies冲突；
• Rider 特定配置便捷：可直接调用intellij.localPath指向本地 Rider 安装目录（如C:\Users\me\AppData\Local\JetBrains\Toolbox\apps\Rider\ch-0\bin），无需像 Maven 那样写冗长的properties。

不这么选的后果：我们曾用 Maven 搭建过一个原型，结果在 CI 流水线中因intellij.version解析失败导致构建卡住 2 小时，最后发现是 Maven 的properties未被maven-dependency-plugin正确加载。

3.2 插件 ID 命名：com.yourcompany.rider.ai（而非rider-ai或ai-plugin）

JetBrains 插件 ID 是全局唯一的，格式必须为反向域名（如com.jetbrains.rider）。我们注册了com.yourcompany.rider.ai，理由有三：

• 避免冲突：rider-ai这种短 ID 早被占用（JetBrains 官方有个rider-ai插件，但未发布）；
• 语义明确：com.yourcompany表明归属，rider.ai表明用途，比ai-assistant更精准；
• 未来扩展友好：后续可衍生com.yourcompany.rider.ai.code（代码生成）、com.yourcompany.rider.ai.doc（文档生成）等子模块。

注意：ID 一旦发布到 Marketplace 就无法更改。本地开发阶段可用local后缀（如com.yourcompany.rider.ai.local），发布前再改为正式 ID。

3.3 PSI 信息提取：用PsiTreeUtil+CSharpElementVisitor（而非正则匹配）

新手常犯的错误是：用正则从editor.document.text中提取方法名。这在简单场景可行，但遇到泛型、属性访问器、Lambda 表达式就会崩溃。正确做法是利用 Rider 的 PSI 树：

val psiFile = PsiDocumentManager.getInstance(project).getCachedPsiFile(editor.document) as? CSharpFile val elementAtCaret = psiFile?.findElementAt(editor.caretModel.offset) val method = elementAtCaret?.parent?.parent?.let { it as? CSharpMethodDeclaration ?: it.parent as? CSharpMethodDeclaration } if (method != null) { val methodName = method.nameIdentifier?.text ?: "" val returnType = method.returnType?.text ?: "void" // 后续构建 prompt... }

这里的关键是CSharpMethodDeclaration—— Rider 的 PSI 类型，它比PsiElement更具体，能直接访问nameIdentifier、returnType、parameterList等属性。我们封装了一个CSharpContextExtractor工具类，覆盖 92% 的 .NET 开发场景（包括 ASP.NET Core Controller Action、Entity Framework LINQ 查询、XUnit[Fact]方法）。

3.4 HTTP 客户端：复用HttpRequests（而非 Retrofit 或 Ktor）

如前所述，Rider 自带com.intellij.util.io.HttpRequests，它：

• 自动继承 Rider 的代理设置（HTTP Proxy、SOCKS、No Proxy）；
• 自动处理证书（包括公司自签 CA）；
• 支持异步回调（connectAsync）且与 Rider 的 Event Dispatch Thread（EDT）兼容；
• 不引入额外依赖，插件体积增加 <50KB。

我们曾尝试用 Ktor，结果在客户现场因公司代理服务器不支持 HTTP/2 而全部失败；换成HttpRequests后，一行代码解决：

HttpRequests.request(url).tuner { it.connectTimeout = 30000 it.readTimeout = 60000 it.header("Authorization", "Bearer $apiKey") }.postString(body) { response -> // 处理响应 }

3.5 流式响应解析：用HttpRequests.StreamProcessor（而非手动读取 InputStream）

大模型的流式响应（SSE）是分块的，每块以data: {...}\n\n分隔。手动解析容易出错（如换行符处理、JSON 解析异常）。HttpRequests提供了StreamProcessor：

val processor = object : HttpRequests.StreamProcessor() { override fun process(data: ByteArray) { val line = String(data).trim() if (line.startsWith("data: ")) { val json = line.substring(6) if (json != "[DONE]") { val chunk = Gson().fromJson(json, ZhipuChunk::class.java) // 更新 UI... } } } } HttpRequests.request(url).postString(body, processor)

这个StreamProcessor会自动按\n\n切分数据块，且保证线程安全（在 EDT 中回调），比自己写BufferedReader稳定得多。

3.6 Token 管理：用 Rider 的StateStore（而非 Properties 文件）

用户在 Settings 里输入的 API Key 必须加密存储。Rider 提供了PersistentStateComponent，它：

• 自动序列化/反序列化对象；
• 数据存于 Rider 的config/options/目录下，与用户配置同步；
• 支持@Tag注解控制存储位置（如@Tag("ai_settings")）；
• 可配合com.intellij.ide.passwordSafe.PasswordSafe加密敏感字段。

我们定义了一个AiSettings类：

class AiSettings : PersistentStateComponent<AiSettings.State> { data class State( @Tag("doubao_api_key") var doubaoApiKey: String = "", @Tag("zhipu_api_key") var zhipuApiKey: String = "", @Tag("default_provider") var defaultProvider: String = "doubao" ) : Cloneable() { override fun clone(): State = State(doubaoApiKey, zhipuApiKey, defaultProvider) } private var state = State() override fun getState(): State = state.clone() override fun loadState(state: State) { this.state = state } }

这样，Key 永远不会以明文形式出现在配置文件中，且 Rider 升级时自动迁移。

3.7 UI 配置页：用Configurable+DialogPanel（而非 Swing 原生组件）

Rider 的 Settings UI 基于DialogPanel（JetBrains 封装的现代化 UI 框架），它：

• 自动适配深色/浅色主题；
• 支持响应式布局（RowLayout,ColumnLayout）；
• 与 Rider 的键盘导航（Tab 键切换焦点）完美兼容；
• 可直接绑定TextField到AiSettings的属性。

我们用DialogPanel构建的配置页，代码量比纯 Swing 少 40%，且用户反馈“看起来就是 Rider 原生的”。

实操心得：不要在配置页里放“Test Connection”按钮。它会误导用户以为“点一下就能用”，而实际需要先填 Key、选模型、设超时。我们改为在保存时自动触发一次最小化请求（如发送{"messages":[{"role":"user","content":"hi"}]}），并在状态栏显示“✓ Connected to Doubao”或“✗ Failed: 401 Unauthorized”，更符合用户心智模型。

4. 实操过程与核心环节实现：从创建项目到真机运行的完整流程

现在进入最硬核的部分：手把手带你从零完成整个流程。我以 Windows 10 + Rider 2023.3.3 + JDK 17 为例（macOS/Linux 步骤基本一致，仅路径不同），所有命令、路径、配置均来自我们团队的真实 CI 流水线。

4.1 环境准备：安装必要工具链

你不需要下载 Rider 源码，但需要以下工具：

提示：Rider 的bin目录必须加入PATH，否则 Gradle 插件无法找到rider.bat。我的路径是C:\Users\me\AppData\Local\JetBrains\Toolbox\apps\Rider\ch-0\bin。

4.2 创建插件项目：用官方模板脚手架

JetBrains 提供了gradle-intellij-plugin模板，但官方文档太简略。我们用团队封装的create-rider-ai-plugin.sh（Windows 下用 PowerShell）：

# 在空目录中执行 $projectName = "rider-ai-doubao-zhipu" $groupId = "com.yourcompany" $version = "1.0.0" # 1. 初始化 Gradle 项目 gradle init --type kotlin-application --dsl kotlin --test-framework junit-jupiter # 2. 添加 intellij 插件 Add-Content build.gradle.kts @" plugins { id("org.jetbrains.intellij") version "1.15.0"" } "@ # 3. 配置 intellij 插件 Add-Content build.gradle.kts @" intellij { version.set("2023.3.3") type.set("RD") // RD = Rider downloadSources.set(true) updateSinceUntilBuild.set(false) } "@

执行完后，目录结构为：

rider-ai-doubao-zhipu/ ├── build.gradle.kts ├── settings.gradle.kts ├── src/ │ └── main/ │ ├── kotlin/ │ │ └── com/yourcompany/rider/ai/ // 主包 │ └── resources/ │ └── META-INF/ │ └── plugin.xml // 插件描述文件

4.3 编写核心插件类：AiPlugin与AiAction

插件入口是AiPlugin类，它继承ApplicationComponent，负责初始化：

class AiPlugin : ApplicationComponent { override fun initComponent() { // 注册 Action ActionManager.getInstance().registerAction("AiExplainAction", AiExplainAction()) ActionManager.getInstance().registerAction("AiRefactorAction", AiRefactorAction()) // 初始化 Provider DoubaoProvider.init() ZhipuProvider.init() // 注册 Settings SettingsEditor.register(AiSettingsEditor()) } override fun disposeComponent() { // 清理资源 } }

AiExplainAction是用户按Alt+Q时触发的逻辑：

class AiExplainAction : AnAction() { override fun actionPerformed(e: AnActionEvent) { val project = e.project ?: return val editor = e.getData(CommonDataKeys.EDITOR) ?: return val file = e.getData(CommonDataKeys.PSI_FILE) as? CSharpFile ?: return // 1. 提取上下文 val context = CSharpContextExtractor.extract(editor, file) // 2. 构建 Prompt val messages = listOf( SystemMessage("你是一名资深 .NET 开发专家，正在帮助 Rider 用户理解代码。请用中文回答，简洁准确，不超过 3 句话。"), UserMessage("请解释以下代码的作用：${context.codeSnippet}") ) // 3. 调用 Provider val provider = AiSettings.getInstance().defaultProvider when (provider) { "doubao" -> DoubaoProvider.sendRequest(project, messages, "doubao-pro") "zhipu" -> ZhipuProvider.sendRequest(project, messages, "glm-4-flash") } } }

4.4 配置plugin.xml：声明权限与扩展点

plugin.xml是 Rider 识别插件的唯一依据，必须精确配置：

<idea-plugin> <id>com.yourcompany.rider.ai</id> <name>Rider AI Assistant</name> <version>1.0.0</version> <vendor email="dev@yourcompany.com" url="https://yourcompany.com">Your Company</vendor> <description><![CDATA[ 为 Rider 提供豆包、智谱 AI 编程辅助能力。 ]]></description> <change-notes><![CDATA[ - 支持豆包开放平台 v1 API - 支持智谱 ZCode v4 API - 新增代码解释、重构、测试生成功能 ]]></change-notes> <!-- 必须声明 Rider 依赖 --> <depends>com.jetbrains.rider</depends> <!-- 声明需要的 API 权限 --> <depends>com.intellij.modules.lang</depends> <depends>com.intellij.modules.platform</depends> <!-- 声明 Actions --> <actions> <action id="AiExplainAction" class="com.yourcompany.rider.ai.AiExplainAction" text="Explain Code" description="Explain selected code with AI"> <add-to-group group-id="EditorPopupMenu" anchor="last"/> <keyboard-shortcut keymap="$default" first-keystroke="alt Q"/> </action> </actions> <!-- 声明 Settings 页面 --> <extensions defaultExtensionNs="com.intellij"> <applicationConfigurable parentId="tools" instance="com.yourcompany.rider.ai.settings.AiSettingsEditor" id="rider.ai.settings" displayName="Rider AI"/> </extensions> </idea-plugin>

关键点：<depends>com.jetbrains.rider</depends>这行不能少，否则 Rider 启动时会忽略该插件；<keyboard-shortcut>中的keymap="$default"确保快捷键在所有键盘布局下生效。

4.5 实现豆包 Provider：处理认证与流式响应

豆包 API 要求Authorization: Bearer <token>，且Content-Type: application/json。DoubaoProvider.sendRequest方法如下：

fun sendRequest(project: Project, messages: List<ChatMessage>, model: String) { val apiKey = AiSettings.getInstance().doubaoApiKey if (apiKey.isBlank()) { Notifications.Bus.notify(Notification("AI Assistant", "豆包 API Key 未配置", "请在 Settings → Tools → Rider AI 中填写", NotificationType.ERROR)) return } val url = "https://api.doubao.com/v1/chat/completions" val body = mapOf( "model" to model, "messages" to messages.map { it.toMap() }, "stream" to true, "temperature" to 0.3 ).toJson() HttpRequests.request(url).tuner { it.connectTimeout = 30000 it.readTimeout = 120000 it.header("Authorization", "Bearer $apiKey") it.header("Content-Type", "application/json") }.postString(body) { response -> if (response.responseCode == 200) { // 启动流式处理器 val processor = DoubaoStreamProcessor(project, messages) HttpRequests.request(url).postString(body, processor) } else { showError(project, "豆包请求失败: ${response.responseCode}") } } }

DoubaoStreamProcessor继承HttpRequests.StreamProcessor，核心逻辑是：

override fun process(data: ByteArray) { val line = String(data).trim() if (line.startsWith("data: ")) { val json = line.substring(6) if (json == "[DONE]") return try { val obj = Gson().fromJson(json, JsonObject::class.java) val content = obj.getAsJsonObject("choices")?.getAsJsonArray("0")?.getAsJsonObject("delta")?.get("content")?.asString ?: "" if (content.isNotEmpty()) { // 在 EDT 中更新 UI ApplicationManager.getApplication().invokeLater { showInlineHint(content) // 渲染到编辑器右侧 } } } catch (e: Exception) { // JSON 解析失败，跳过此块 } } }

4.6 实现智谱 Provider：支持函数调用与工具集成

智谱的亮点是tools，可用于调用本地工具。例如，当用户问“把这段 SQL 生成 Entity Framework 模型”，我们可以定义一个SqlToEfTool：

data class Tool( val type: String = "function", val function: FunctionDef ) data class FunctionDef( val name: String, val description: String, val parameters: JsonObject ) val sqlToEfTool = Tool( function = FunctionDef( name = "sql_to_ef_model", description = "将 SQL CREATE TABLE 语句转换为 C# Entity Framework 实体类", parameters = JsonObject().apply { addProperty("sql", "CREATE TABLE Users (Id INT PRIMARY KEY, Name NVARCHAR(50))") } ) )

在ZhipuProvider.sendRequest中，将tools注入请求体：

val body = mapOf( "model" to model, "messages" to messages.map { it.toMap() }, "tools" to listOf(sqlToEfTool, httpClientTool), // 可扩展更多工具 "tool_choice" to "auto", "stream" to true ).toJson()

智谱返回tool_calls后，插件解析并执行对应工具：

if (obj.has("tool_calls")) { val toolCalls = obj.getAsJsonArray("tool_calls") for (i in 0 until toolCalls.size()) { val call = toolCalls.get(i).asJsonObject val name = call.getAsJsonObject("function").get("name").asString when (name) { "sql_to_ef_model" -> { val sql = call.getAsJsonObject("function").getAsJsonObject("arguments").get("sql").asString val csharp = SqlToEfConverter.convert(sql) // 本地转换逻辑 // 将 csharp 插入编辑器 } } } }

这就是“AI Agent”的雏形：大模型负责决策（调哪个工具），插件负责执行（本地代码生成），形成闭环。

4.7 打包与安装：生成.zip并本地加载

执行gradle buildPlugin，输出位于build/distributions/目录下的rider-ai-doubao-zhipu-1.0.0.zip。

在 Rider 中安装：

1. File → Settings → Plugins → ⚙️ → Install Plugin from Disk…
2. 选择生成的.zip文件；
3. Restart IDE。

启动后，你会在 Settings → Tools → Rider AI 中看到配置页，填入豆包/智谱的 API Key（从 doubao.com/open 和 zhipu.ai/zcode 获取），保存即可。

实测心得：首次运行时，Rider 会弹出“未知插件”警告，点击“Trust and Enable”即可。这是 JetBrains 的安全机制，非 bug。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

即使严格按照上述步骤操作，你仍可能遇到一些“只在此山中，云深不知处”的问题。以下是我在 12 个客户现场、37 次部署中整理的高频问题与独家排查技巧，按发生频率排序。

5.1 问题：插件安装后 Settings 里看不到配置页，Action 也无法触发

现象：.zip安装成功，Rider 重启，但 Settings 中无 “Rider AI” 选项，快捷键无效。

排查步骤：

1. 查看 Rider 日志：Help → Show Log in Explorer → 打开idea.log；
2. 搜索com.yourcompany.rider.ai，看是否有PluginException；
3. 最常见原因是plugin.xml中的id与build.gradle.kts中的intellij.pluginId不一致。检查build.gradle.kts是否有：

intellij { pluginId = "com.yourcompany.rider.ai" // 必须与 plugin.xml 中的 <id> 完全一致 }

4. 如果日志中出现Class not found: com.yourcompany.rider.ai.AiPlugin，说明AiPlugin类未被正确编译进 JAR。检查src/main/kotlin/路径是否正确，Kotlin 文件是否在正确包下。

根本原因：Gradle 的intellij插件在打包时，会扫描plugin.xml中的class属性（如<application-components><component class="com.yourcompany.rider.ai.AiPlugin"/>），如果类路径不对，就静默失败。

5.2 问题：豆包 API 返回 401，但 Key 在 Postman 中能用

现象：Settings 里填了 Key，点击 Test 或执行 Action 时，日志显示HTTP 401 Unauthorized。

排查技巧：

• 豆包的 Key 格式是sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx，共 64 位十六进制字符。复制时是否多了一个空格？用echo "$KEY" | wc -c检查长度；
• Rider 的PasswordSafe在存储时会自动 trim 空格，但某些剪贴板工具（如 Ditto）会粘贴隐藏的 Unicode 字符（如U+200B零宽空格）。解决方案：在 Settings 输入框中，用Ctrl+A全选，再Ctrl+V粘贴，避免从网页直接拖选；
• 检查 Rider 的代理设置：File → Settings → Appearance & Behavior → System Settings → HTTP Proxy。如果公司用 PAC 脚本，确保Use browser proxy settings已勾选。

独家技巧：在DoubaoProvider.sendRequest中，加一行日志打印实际发送的 Header：

it.header("Authorization", "Bearer $apiKey").also { logger.info("Sending request to Doubao with key: ${apiKey.take(8)}...${apiKey.takeLast(4)}") }

这样能确认 Key 是否被截断或污染。

5.3 问题：流式响应卡住，UI 无任何提示，日志无报错

现象：Action 触发后，光标变成沙漏，但 2 分钟后无响应，日志中只有HttpRequests.request的发起日志，无process回调。

根因分析：这是典型的SSE 连接未正确关闭导致的线程阻塞。HttpRequests.postString默认使用connectAsync，但如果StreamProcessor.process中抛