DBeaver 如何通过扩展点注册新的 AI 引擎与助手

DBeaver 如何通过扩展点注册新的 AI 引擎与助手

【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver

DBeaver 的 AI 能力（补全、SQL 生成、助手问答）并不写死在核心代码里，而是通过 OSGi 扩展点对外暴露。插件org.jkiss.dbeaver.model.ai在自己的 plugin.xml 中声明了 5 个扩展点，其中两个正是本文的目标：

• com.dbeaver.ai.engine（AI integrations）：注册 AI 引擎，对应模式文件 com.dbeaver.ai.engine.exsd；
• com.dbeaver.ai.assistant（AI assistants）：注册 AI 助手，对应模式文件 com.dbeaver.ai.assistant.exsd。

同一 plugin.xml 中还声明了com.dbeaver.ai.prompt（提示词生成器）、com.dbeaver.ai.function（AI 函数）和com.dbeaver.ai.credentialsProvider（授权）三个扩展点，本文只覆盖引擎与助手两条注册路径。

前提条件

• 你能访问 DBeaver 源码，并准备一个可以贡献扩展的插件（自己的产品插件或 fork）。
• 新插件必须依赖org.jkiss.dbeaver.model.ai，因为AIEngine、AIEngineProperties、AIAssistant等契约类都在这个插件的包org.jkiss.dbeaver.model.ai.engine/org.jkiss.dbeaver.model.ai中。
• 注意 AI 功能的开关策略：plugin.xml 中org.jkiss.dbeaver.sqlCommand的 AI 命令由org.jkiss.dbeaver.core.ai.completion.enabled.by.policy控制，当工作区偏好设置了ai.disabled、环境变量设置了DBEAVER_AI_DISABLED，或org.jkiss.dbeaver.app.config中id="ai"的功能特性未启用时，AI 命令不生效。你的引擎注册本身不受此影响，但验证功能时要先确认这些开关。

注册 AI 引擎：声明 completionEngine 扩展

参照org.jkiss.dbeaver.model.ai自身声明的两个引擎，plugin.xml中的写法是：

<extension point="com.dbeaver.ai.engine"> <completionEngine id="openai" label="OpenAI" icon="icons/engine_openai.svg" class="org.jkiss.dbeaver.model.ai.engine.openai.OpenAIEngine" properties="org.jkiss.dbeaver.model.ai.engine.openai.OpenAIProperties" promoted="true" default="true" supportsFunctions="true" fallbacks="openai-pro"/> <completionEngine id="copilot" label="Github Copilot" icon="icons/engine_copilot.svg" class="org.jkiss.dbeaver.model.ai.engine.copilot.CopilotCompletionEngine" properties="org.jkiss.dbeaver.model.ai.engine.copilot.CopilotProperties" promoted="true" supportsFunctions="false" fallbacks="copilot-pro"/> </extension>

各属性在现有声明中的用途：

注册你的引擎时，把id、label、class、properties换成自己的值；promoted、default、supportsFunctions、fallbacks按实际能力取舍，不需要照抄示例。

实现引擎类与属性类

引擎实现类需要满足 AIEngine.java 定义的接口：

public interface AIEngine<PROPS extends AIEngineProperties> extends AutoCloseable { @NotNull List<AIModel> getModels(@NotNull DBRProgressMonitor monitor) throws DBException; @NotNull AIEngineResponse requestCompletion( @NotNull DBRProgressMonitor monitor, @NotNull AIEngineRequest request ) throws DBException; void requestCompletionStream( @NotNull DBRProgressMonitor monitor, @NotNull AIEngineRequest request, @NotNull AIEngineResponseConsumer listener ) throws DBException; @NotNull PROPS getProperties(); int getContextWindowSize(@NotNull DBRProgressMonitor monitor) throws DBException; @Override void close() throws DBException; }

要点：

• requestCompletion与requestCompletionStream（流式）都要实现；请求限流时按接口约定抛出TooManyRequestsException，表示请求可重试。
• 包内提供了可继承的抽象基类 BaseCompletionEngine.java，以及 HTTP 客户端基类 AbstractHttpAIClient.java（OpenAI 引擎OpenAIEngine就是在这套基类上实现的），可以复用其骨架。

属性类需要实现 AIEngineProperties.java：

public interface AIEngineProperties { int DEFAULT_TIMEOUT = 30; String getModel(); Integer getContextWindowSize(); double getTemperature(); boolean isValidConfiguration(); boolean isLoggingEnabled(); void setLoggingEnabled(boolean loggingEnabled); int getTimeout(); void setTimeout(int timeout); void resolveSecrets(@NotNull AIConfigurationProfile profile) throws DBException; void saveSecrets(@NotNull AIConfigurationProfile profile) throws DBException; void deleteSecrets(@NotNull AIConfigurationProfile profile) throws DBException; }

isValidConfiguration()用于校验必填项是否齐全；resolveSecrets/saveSecrets/deleteSecrets负责把密钥在配置配置档（AIConfigurationProfile）中解析、保存与删除。已有属性类 BaseAIEngineProperties.java 可作为参考实现，例如 OpenAI 的属性类 OpenAIProperties.java。

注册 AI 助手：声明 assistant 扩展

助手扩展的声明见 plugin.xml：

<extension point="com.dbeaver.ai.assistant"> <assistant id="ce-assistant" priority="1" class="org.jkiss.dbeaver.model.ai.impl.AIAssistantImpl" sqlFormatter="org.jkiss.dbeaver.model.ai.impl.SimpleSqlFormatterImpl"/> </extension>

• class：助手实现类，必须实现AIAssistant接口（AIAssistant.java），且提供以DBPWorkspace为参数的构造器——实例化时由描述符按此签名创建。
• sqlFormatter：助手配套的 SQL 格式化类，实现AISqlFormatter接口。
• priority：多个助手扩展共存时，AIAssistantRegistry 只保留priority最大的那一个作为全局助手；不写priority时按CommonUtils.toInt解析为 0。

助手的解析逻辑在 AIAssistantDescriptor.java：它读取class（创建助手）、sqlFormatter（创建格式化器）、priority三个属性。

验证注册结果

注册是否生效，按代码中的解析路径核对：

1. 扩展被扫描到：AIAssistantRegistry构造时遍历Platform.getExtensionRegistry()中com.dbeaver.ai.assistant下所有assistant元素；如果启动后getDescriptor()返回null，说明扩展没被解析（检查pointid 拼写和元素名是否为assistant）。
2. 助手可创建：createAssistant通过描述符按AIAssistant.class+DBPWorkspace参数实例化。若创建抛DBException，会记录Error creating AI assistant错误日志并回退到内置的AIAssistantImpl——看到这条日志就说明你的class没写对或实现不满足接口。
3. 引擎出现在选择控件中：引擎描述器同样由扩展注册表实例化class指向的AIEngine实现；promoted="true"的引擎会排在选择控件前列。如果你的引擎没有出现在 AI 引擎列表中，先确认class实现类可被平台加载，再确认 AI 功能开关（ai.disabled偏好、DBEAVER_AI_DISABLED环境变量、id="ai"功能特性）没有把 AI 命令禁用。

限制

• 助手扩展只有一份全局生效（priority最高者胜出），同一工作区不会并行加载多个助手。
• 引擎与助手的契约类（AIEngine、AIEngineProperties、AIAssistant、AISqlFormatter）位于org.jkiss.dbeaver.model.ai插件，升级 DBeaver 时接口可能变化，TooManyRequestsException、AIEngineRequest/Response等类型都在同一包内，应随源码一起核对。
• exsd模式文件中目前只文档化了class与promoted两个属性（引擎）和class（助手），其余属性（label、icon、properties、default、supportsFunctions、fallbacks、priority、sqlFormatter）以现有声明为参考；PDE 提示校验以模式为准，属性值按描述符代码的实际读取逻辑解析。

【免费下载链接】dbeaverFree universal database tool and SQL client项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver