--- title: "harness - 配置参考" --- HarnessEngine 的配置示例： ```java HarnessEngine engine = HarnessEngine.of("work", ".soloncode/") .systemPrompt("你是一个 AI 助手") .sessionWindowSize(12) .compressionThreshold(100, 0.75D) .toolsAdd(ToolName.TOOL_ALL_FULL) // 设定工具权限 .build(); ``` 可选配置： ### 1、核心配置项 | 配置项 | 类型 | 默认值 | 描述 | |--------------------------|-----------------|-----------|-------------------------------------------------------------------| | `workspace` | `String` | `work` | 工作区 | | `harnessHome` | `String` | `.solon/` | 马具主目录（例：`.soloncode`） | | `systemPrompt` | `String` | / | 系统提示词 | | `userAgent` | `String` | / | 用户代理标识（会自动传播给所有模型） | | `tools` | `Set` | / | 工具权限配置（`**` = 所有工具；`*` = 仅公域工具） | | `disallowedTools` | `Set` | / | 禁用工具配置（使用具体工具名） | | `defaultModel` | `String` | / | 默认模型名（不指定则取 models 中第一个） | | `models` | `Map` | / | 大模型配置 | | `maxTurns` | `int` | `20` | 根代理最大循环步数 | | `autoRethink` | `boolean` | `true` | 最大步数自动续航（由 LLM 反思控制） | | `sessionWindowSize` | `int` | `8` | 会话历史窗口大小（新指令时使用几条历史消息） | | `compressionMaxMessages` | `int` | `40` | 触发上下文压缩的消息条数阈值 | | `compressionMaxTokens` | `int` | `60_000` | 触发上下文压缩的内容长度阈值 | | `compressionModel` | `String` | / | 压缩用大模型（不指定则使用主模型） | | `cacheControl` | `CacheControl` | / | 缓存控制（用于 Anthropic 等支持 prompt caching 的模型） | | `skillProvider` | `SkillProvider` | / | 技能提供者（可对接数据库等外部存储，不指定则用默认 MountManager） | models 模型配置参考：[《模型配置与请求选项》](/article/1087) ### 2、安全与行为配置 | 配置项 | 类型 | 默认值 | 描述 | |-------------------------|----------|---------|----------------------------------------------------------------| | `sandboxEnabled` | bool | `true` | 沙盒模式，启用时禁止访问绝对路径（只能访问工作区与用户主目录） | | `sandboxAllowUserHome` | bool | `true` | 沙盒模式下允许访问用户主目录 | | `sandboxSystemRestrict` | bool | `true` | 沙盒系统级限制 | | `hitlEnabled` | bool | `false` | 是否启用人工审核（危险操作需人工确认） | | `subagentEnabled` | bool | `true` | 是否启用子代理模式（自动委派任务给专家代理） | | `bashAsyncEnabled` | bool | `false` | 是否启用 Bash 异步执行 | | `memoryEnabled` | bool | `true` | 是否启用心智记忆 | | `userAgent` | `String` | / | 用户代理标识（会自动传播给所有模型） | | `apiRetries` | int | `3` | API 重试次数 | | `mcpRetries` | int | `3` | MCP 重试次数 | | `modelRetries` | int | `3` | 模型重试次数 | ### 3、扩展配置 | 配置项 | 类型 | 默认值 | 描述 | |--------------------------|---------------------------------|----------|---------------------------------------------------------| | `mounts` | `MountDir` | / | 挂载配置（alias 须以 `@` 开头） | | `mcpServers` | `Map` | / | Mcp 服务配置 | | `apiServers` | `Map` | / | Web Api 服务配置 | | `lspServers` | `Map` | / | LSP 服务配置 | | `extensions` | `List` | / | 扩展接口配置 | | `compressionInterceptor` | `ContextCompressionInterceptor` | 自动创建 | 上下文压缩拦截器 | | `stopLoopInterceptor` | `StopLoopInterceptor` | 自动创建 | 停止循环拦截器（默认参数：3 次连续相同错误 / 8 轮窗口） | | `hitlInterceptor` | `HITLInterceptor` | 自动创建 | 人工介入拦截器（默认对 bash 工具绑定 HitlStrategy） | | `sessionProvider` | `AgentSessionProvider` | / | 会话提供者（必填） | | `memoryProvider` | `MemorySolutionProvider` | / | 心智记忆存储方案 | ### 附录、工具权限配置选择（tools） | 工具名 | 类型 | 描述 | |--------------|------|------------------------------------------------------------| | `**` | - | 所有公域 + 私域工具 | | `*` | - | 仅所有公域工具 | | `pi` | 聚合 | 微形命令行工具（包括工具：read, write, edit, bash） | | | | | | `hitl` | 私域 | 人工介入审核 | | `generate` | 私域 | 动态生成子代理 | | `restapi` | 私域 | Web 服务 API 接入 | | `mcp` | 私域 | MCP 服务接入 | | `lsp` | 私域 | LSP 代码理解服务 | | | | | | `code` | 公域 | 编码指引（自动分析项目类型、编译指令等） | | `codesearch` | 公域 | 网络代码搜索 | | `websearch` | 公域 | 网络搜索 | | `webfetch` | 公域 | 网页内容抓取 | | `todo` | 公域 | 任务清单管理 | | `skill` | 公域 | 专家技能调用 | | `task` | 公域 | 子代理任务委派 | | `bash` | 公域 | Shell 命令执行 | | `ls` | 公域 | 列出目录内容 | | `grep` | 公域 | 递归内容搜索 | | `glob` | 公域 | 通配符文件搜索 | | `edit` | 公域 | 文件编辑（精准文本替换，支持多处原子编辑；含 write、read） | | `read` | 公域 | 读取文件内容 | | `write` | 公域 | 写入文件内容 | | `clock` | 公域 | 时间/定时相关能力（ClockTalent 提供） | | `memory` | 公域 | 心智记忆读写（MemoryTalent 提供） | ### 附录、运行时动态修改 `HarnessEngine` 构建完成后，仍可在运行时动态调整工具权限与模型（变更后会自动重建主代理，使其立即生效）。 - 动态调整工具权限 ```java engine.allowTool("websearch"); // 动态授权一个工具 engine.disallowTool("bash"); // 动态禁用一个工具 engine.allowToolReset(Arrays.asList("read", "write", "edit")); // 仅重置白名单（allowedTools） engine.disallowToolReset(Arrays.asList("bash")); // 仅重置黑名单（disallowedTools） engine.toolPermissionReset(Arrays.asList("read", "write"), Arrays.asList("bash")); // 同时重置白/黑名单（避免两次重建） ``` > **三种重置方法的区别**： > > - `allowToolReset(tools)` — 仅重置白名单（allowedTools），黑名单不变； > - `disallowToolReset(tools)` — 仅重置黑名单（disallowedTools），白名单不变； > - `toolPermissionReset(tools, disallowedTools)` — 同时重置白/黑名单，触发一次主代理重建，比分别调用前两者更高效。 - 动态管理模型 ```java engine.addModel(new ChatConfig().then(c -> { c.setApiUrl("https://api.deepseek.com"); c.setApiKey("sk-***"); c.setModel("deepseek-v4-flash"); })); // 添加模型 engine.setDefaultModel("deepseek-v4-flash"); // 设定默认模型（影响主代理时自动刷新） engine.removeModel("deepseek-v4-flash"); // 移除模型 ``` - 其它运行时配置 ```java engine.setMaxTurns(30); engine.setSessionWindowSize(8); engine.setCompressionThreshold(40, 60_000); engine.setSandboxEnabled(true); engine.setHitlEnabled(false); engine.setSubagentEnabled(true); engine.setMemoryEnabled(true); engine.setCacheControl(CacheControl.of(...)); engine.setSystemPrompt("新的系统提示词"); ``` - 动态管理扩展 ```java engine.addExtension((agentName, builder) -> { // 自定义拦截器或工具注入 }); engine.removeExtension(extension); // 移除扩展（触发主代理重建） ``` - 动态管理服务器与挂载点 ```java // 动态添加 MCP 服务 engine.addMcpServer("my-mcp", mcpServerParameters); engine.refreshMcpServer("my-mcp"); engine.removeMcpServer("my-mcp"); // 动态添加 OpenAPI 服务 engine.addApiServer(apiSource); engine.refreshApiServer(docUrl); engine.removeApiServer(docUrl); // 动态添加 LSP 服务 engine.addLspServer("my-lsp", lspServerParameters); engine.removeLspServer("my-lsp"); // 挂载点管理 engine.addMount(mountDir); engine.removeMount("@alias"); engine.refreshMount(null); // null 表示刷新所有 ```