SolonCode Extensions 是基于 Java 技术栈的扩展机制，类似于 ClaudeCode 的 Hook 或 OpenCode 的 Plugin。

它通过实现 `HarnessExtension` 接口，深度介入 `ReActAgent.Builder` 的装配过程，支持开发者为 Agent 添加工具 (Tools)、设置拦截器 (Interceptors) 等。相比高层接口，这是一种更基础、更自由且全面的定制方式。


### 1、核心接口

所有扩展插件都需要实现 `HarnessExtension` 接口。通过 `configure` 方法，你可以获得当前 Agent 的名称及其构建器实例，从而进行增强。

引入依赖（注意：soloncode 已依赖的包，都要标为 provided）

```xml
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-harness</artifactId>
    <scope>provided</scope>
</dependency>
```

编写代码（仅为示意）

```java
public class Extension1 implements HarnessExtension {
    @Override
    public void configure(String agentName, ReActAgent.Builder agentBuilder) {
        // 在此处对 agentBuilder 进行定制，例如添加 Tool 或 Interceptor
        agentBuilder.defaultInterceptorAdd(new ReActInterceptor() {
            @Override
            public void onAgentStart(ReActTrace trace) {
                System.out.println("任务要开始了...");
            }

            @Override
            public void onReason(ReActTrace trace, AssistantMessage message) {
                System.out.println("又思考了...");
            }

            @Override
            public ChatResponse interceptCall(ChatRequest req, CallChain chain) throws IOException {
                System.out.println("要调用工具了...");
                return chain.doIntercept(req);
            }
        });
    }
}
```

### 2、安装方式

编译打包后，将生成的 JAR 包存放在以下目录：

* 路径： `~/.soloncode/extensions/`


### 3、装配与生效

SolonCode 提供两种装配方式：**手动显式配置 和 基于 Solon SPI 的自动装配**。


#### 方式 A：手动配置 (Manual)

适用于需要精确控制加载顺序或仅在特定环境下启用的扩展。

在配置文件中指定扩展类的全限定名：


```yaml
soloncode:
  extensions:
    - "org.codecli.ext1.MyExtension"
```

#### 方式 B：自动装配 (Auto-Configuration)

推荐方式。基于 Solon Plugin 机制，实现“即插即用”，无需在 YAML 中手动声明。


1) **创建插件类**：

```java
public class MyExtensionPlugin implements Plugin {
    @Override
    public void start(AppContext context) throws Throwable {
        // 将扩展类注册到容器中，SolonCode 会自动识别并加载
        context.beanMake(MyExtension.class);
    }
}
```

2) **配置 SPI**：

在资源目录 `META-INF/solon/` 下创建插件声明文件（参考：[Solon SPI 机制](/article/58)）。