添加依赖

org.noear
solon-ai-harness
${solon.version}

solon-ai-harness 同时支持 Java 8 到 Java 25，兼容性不用担心。

2. 快速上手：Hello World
   先来一个最简单的例子：构建一个只拥有四个基础工具（读、写、编辑、执行命令）的 Agent，让它帮我们完成一个任务。

import org.noear.solon.ai.agent.AgentSession;
import org.noear.solon.ai.agent.session.InMemoryAgentSession;
import org.noear.solon.ai.agent.session.AgentSessionProvider;
import org.noear.solon.ai.chat.ChatConfig;
import org.noear.solon.ai.harness.HarnessEngine;
import org.noear.solon.ai.harness.permission.ToolPermission;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

public class DemoApp {
public static void main(String[] arg) throws Throwable {
// 会话提供者：决定会话如何存储（这里用内存实现）
AgentSessionProvider sessionProvider = new AgentSessionProvider() {
private final Map<String, AgentSession> sessionMap = new ConcurrentHashMap<>();

        @Override
        public AgentSession getSession(String instanceId) {
            return sessionMap.computeIfAbsent(
                instanceId, k -> InMemoryAgentSession.of(k)
            );
        }
    };

    // 构建 Harness 引擎
    HarnessEngine engine = HarnessEngine.of("/data/work/", ".tmp")
            .systemPrompt("你是一个 AI 助手，请根据用户指令完成任务。")
            .sessionProvider(sessionProvider)
            .toolsAdd(ToolPermission.TOOL_PI)  // 仅开放 read/write/edit/bash
            .modelAdd(new ChatConfig().then(slf -> {
                slf.setApiUrl("https://api.deepseek.com");
                slf.setApiKey("sk-你的Key");
                slf.setModel("deepseek-chat");
            }))
            .build();

    // 执行任务
    engine.prompt("在当前目录下创建一个 README.md，内容为 '# Hello Harness'")
            .call();
}

}
就这么简单。HarnessEngine.of(workspace, harnessHome) 的两个参数：

workspace：Agent 的当前工作目录（文件读写、命令执行都以它为根）
harnessHome：马具主目录（会话、记忆、技能等运行态数据落在这里）
3. 核心配置详解
HarnessEngine.Builder 提供了一整套配置项，让你精细控制 Agent 的行为。

3.1 基础配置
HarnessEngine engine = HarnessEngine.of(“work”, “.soloncode/”)
.systemPrompt(“你是一个 AI 助手”) // 系统提示词
.sessionWindowSize(8) // 会话历史窗口大小（默认 8）
.compressionThreshold(30, 30_000) // 触发压缩：30 条消息或 30000 token
.maxTurns(20) // 最大循环步数（默认 20）
.autoRethink(true) // 最大步数自动续航（默认 true）
.modelRetries(3) // 模型重试次数（默认 3）
.build();
3.2 工具权限配置
toolsAdd 和 disallowedToolsAdd 控制 Agent 可以调用哪些工具：

// 开放所有工具（包括 bash、文件读写、网络搜索等）
.toolsAdd(ToolPermission.TOOL_ALL_FULL)

// 或仅开放基础工具
.toolsAdd(ToolPermission.TOOL_PI) // read, write, edit, bash

// 或精细控制：开放，再禁用某些
.toolsAdd(ToolPermission.TOOL_ALL_FULL)
.disallowedToolsAdd(ToolPermission.TOOL_BASH) // 禁止 bash 执行
工具权限分为公域和私域：

公域：read、write、edit、bash、websearch、webfetch、glob、grep、ls、skill、task 等
私域：generate（生成子代理）、高阶权限需人工确认
3.3 沙盒安全配置
HarnessEngine engine = HarnessEngine.of(“work”, “.soloncode/”)
.sandboxEnabled(true) // 启用沙盒模式
.sandboxAllowUserHome(true) // 允许访问用户主目录
.sandboxSystemRestrict(true) // 系统级限制，危险操作需人工确认
.build();
沙盒模式下，Agent 只能访问工作区和指定的挂载目录，不能越界到系统目录。

3.4 多模型配置
.modelAdd(new ChatConfig().then(slf -> {
slf.setApiUrl(“https://api.deepseek.com”);
slf.setApiKey(“sk-");
slf.setModel(“deepseek-chat”);
}))
.modelAdd(new ChatConfig().then(slf -> {
slf.setApiUrl(“https://api.openai.com/v1”);
slf.setApiKey("sk-”);
slf.setModel(“gpt-4o”);
}))
第一个添加的模型是主模型，运行时可以通过 options() 动态切换。

4. 调用与流式响应
   engine.prompt(…) 返回的是一个 ReActRequest 接口，支持同步和流式两种模式。

4.1 同步调用
engine.prompt(“帮我查一下当前目录有哪些 Java 文件”).call();
4.2 流式响应
适合需要实时展示 Agent 推理过程或逐步输出结果的场景：

engine.prompt(“分析当前项目的代码结构并生成文档”).stream();
4.3 指定会话与请求选项
// 获取或创建持久会话
AgentSession session = engine.getSession(“default”);

engine.prompt(“帮我重构 UserService 类的逻辑”)
.session(session) // 绑定持久会话（不指定则为临时会话）
.options(o -> {
// 切换大模型
o.chatModel(engine.getModelOrMain(“gpt-4o”));

        // 动态指定工作区
        o.toolContextPut(HarnessEngine.ATTR_CWD, "/data/projects/myapp");
    })
    .call();

5. 子代理与任务委派
   solon-ai-harness 内置了几个开箱即用的子代理：

名称 说明
general 通用全能专家。其他子代理不匹配时用它
explore 全域信息探索专家（本地文件 + 全网检索，无写权限）
plan 规划与计划专家（制定逻辑路径与执行步骤）
bash Bash 命令执行专家（git、命令行操作）
5.1 通过代码动态创建子代理
AgentSession session = engine.getSession(“default”);

AgentDefinition definition = new AgentDefinition();
definition.setSystemPrompt(“你是一个 Git 专家，负责执行仓库操作。”);
definition.getMetadata().addTools(ToolPermission.TOOL_BASH);

ReActAgent gitAgent = engine.createSubagent(definition).build();
gitAgent.prompt(“提交当前所有更改并推送”)
.session(session)
.call();
5.2 通过 AgentManager 管理
// 获取内置子代理
AgentDefinition bashDef = engine.getAgentManager().getAgent(“bash”);

// 构建并执行
ReActAgent bashAgent = bashDef.builder(engine).build();
bashAgent.prompt(“列出当前目录所有 Java 文件”).call();

// 获取所有可用子代理
Collection agents = engine.getAgentManager().getAgents();

// 动态注册自定义子代理
engine.getAgentManager().addAgent(customDefinition);
5.3 任务委派（task / multitask）
主代理拥有 task 工具权限时，可自主把子任务委派给子代理：

task(agentName, prompt)：委派单一任务（串行）
multitask([task1, task2, …])：并行执行多个独立子任务
子任务上下文隔离，委派时必须在 prompt 中提供所有背景信息。

6. 会话与心智记忆
   会话保存单次对话的上下文，心智记忆则在多次对话之间长期留存关键事实。

6.1 会话提供者
sessionProvider 是构建引擎的必填项：

// 自定义持久化（如文件/数据库）
.sessionProvider(sessionId -> {
// 从数据库加载或创建会话
return MyDatabase.loadSession(sessionId);
})
会话的运行态数据默认落在 {harnessHome}/sessions/ 下。

6.2 心智记忆（Memory）
心智记忆让 Agent 记住用户的偏好、项目规约等关键事实，并在需要时检索召回。

HarnessEngine engine = HarnessEngine.of(“work”, “.soloncode/”)
.memoryEnabled(true) // 默认开启
.memoryProvider(new MemorySolutionProvider() {
@Override
public MemorySolution getSolution(String workspace) {
// 每个工作区可以有不同的记忆方案
return new MarkdownMemorySolution(workspace);
}
})
.build();
记忆方案内置 Markdown 实现（零外部依赖），也支持 Redis、Lucene、向量库等。Agent 可在运行中自主进行：

提取：写入事实
召回：按 key 精确取
语义检索：自然语言检索
认知整合：碎片升维合并
修剪：删除过时认知
7. 内置拦截器
Harness 有三个内置拦截器，负责保障 Agent 的稳定运行。

7.1 上下文压缩拦截器
防止上下文超出 Token 限制：

import org.noear.solon.ai.harness.interceptor.;
import org.noear.solon.ai.harness.compression.;

CompressionStrategy strategy = new CompositeCompressionStrategy()
.addStrategy(new KeyInfoExtractionStrategy()) // 提取干货，去水
.addStrategy(new HierarchicalCompressionStrategy()); // 滚动更新摘要

ContextCompressionInterceptor interceptor = new ContextCompressionInterceptor(
40, // 消息条数阈值
60_000, // 内容长度阈值
3, // 重试次数
() -> engine.getModelOrMain(engine.getCompressionModel()),
strategy);

HarnessEngine engine = HarnessEngine.of(“work”, “.soloncode/”)
.compressionInterceptor(interceptor)
.build();
7.2 停止循环拦截器
防止 Agent 陷入死循环：

StopLoopInterceptor stopLoop = new StopLoopInterceptor(5, 10);
// 5 次相同错误 / 10 轮窗口内触发停止

HarnessEngine engine = HarnessEngine.of(“work”, “.soloncode/”)
.stopLoopInterceptor(stopLoop)
.build();
7.3 HITL 人工介入拦截器