---
title: "harness - 工具名映射与权限解析参考"
---



`AgentFactory.toolAddDo()` 是 `solon-ai-harness` 的核心方法之一，负责将工具名称映射到实际的 Talent 组件。该参考文档描述所有工具名与 Talent 组件的对应关系。

### 1、工具名到 Talent 组件的映射

| 工具名 | 别名 | 映射到的 Talent | 说明 |
|--------|------|-----------------|------|
| `read` | | `TerminalTalentProxy` | 读取文件内容 |
| `write` | | `TerminalTalentProxy` | 写入文件内容 |
| `edit` | | `TerminalTalentProxy` | 编辑文件（自动附带 read + write） |
| `glob` | | `TerminalTalentProxy` | 通配符文件搜索 |
| `grep` | | `TerminalTalentProxy` | 递归内容搜索 |
| `ls` | `list` | `TerminalTalentProxy` | 列出目录内容 |
| `bash` | | `TerminalTalentProxy` | Shell 命令执行 |
| `bash_start` | | `TerminalTalentProxy` | 启动异步 Shell 会话 |
| `bash_wait` | | `TerminalTalentProxy` | 等待异步 Shell 输出 |
| `bash_stdin` | | `TerminalTalentProxy` | 向异步 Shell 写入输入 |
| `bash_stop` | | `TerminalTalentProxy` | 停止异步 Shell 会话 |
| `todo` | `todoread`, `todowrite` | `TodoTalent` + `ClockTalent`（主代理） / `planningMode`（子代理） | 任务清单管理 |
| `now` | | `ClockTalent` | 获取系统当前日期时间与时区 |
| `skill` | | `SkillTalent` | 专家技能调用 |
| `code` | | `CodeTalent` | 编码指引 |
| `webfetch` | | `WebfetchTalent` | 网页内容抓取 |
| `websearch` | | `WebsearchTalent` | 网络搜索 |
| `codesearch` | | `CodeSearchTalent` | 网络代码搜索 |
| `task` | `subagent` | `TaskTalent` | 子代理任务委派 |
| `generate` | | `GenerateTalent` | 动态生成子代理 |
| `memory` | | `MemoryTalent` | 心智记忆管理 |
| `mcp` | | `McpGatewayTalent` | MCP 服务接入 |
| `openapi` | | `OpenApiGatewayTalent` | OpenAPI 业务接口接入 |
| `lsp` | | `LspTalent` | LSP 代码理解服务 |
| `hitl` | | `HITLInterceptor` | 人工介入审核（注册为拦截器而非 Talent） |

### 2、快捷权限展开

三种快捷权限在 `AgentFactory` 中展开为具体工具名：

#### `pi`（核心操作）

```
read, write, edit, bash, bash_start, bash_wait, bash_stdin, bash_stop
```

#### `*`（全部公域）

```
read, write, edit, glob, grep, ls, bash, bash_start, bash_wait, bash_stdin, bash_stop,
skill, todo, code, codesearch, websearch, webfetch, task, lsp
```

#### `**`（全部完整）

```
read, write, edit, glob, grep, ls, bash, bash_start, bash_wait, bash_stdin, bash_stop,
skill, todo, code, codesearch, websearch, webfetch, task, generate, mcp, openapi, hitl, lsp, memory
```

### 3、工具注册流程

1. `AgentDefinition` 的 `metadata.getTools()` 包含工具名列表（如 `["read", "bash", "code"]` 或 `["**"]`）。
2. `AgentFactory.create()` 遍历工具名列表，对每个名称调用 `toolAddDo()`。
3. `toolAddDo()` 先检查该工具是否被 `metadata.getDisallowedTools()` 或全局 `engine.getDisallowedTools()` 禁用。
4. 未被禁用的工具，根据名称的 `switch` 分支，从 `engine` 获取对应的 Talent 实例，注册到 `ReActAgent.Builder`。
5. 快捷权限（`**`、`*`、`pi`）会递归展开为具体工具名列表。
6. 文件类工具通过 `TerminalTalentProxy` 代理注册，按白名单选择性暴露。
7. 所有 `HarnessExtension` 在工具注册完成后被调用，允许外部代码注入自定义工具。

### 4、禁用工具机制

工具禁用有两个层级：

* **定义级禁用**：`AgentDefinition.metadata.getDisallowedTools()`，仅影响该代理定义。
* **全局级禁用**：`engine.getDisallowedTools()`，影响所有代理。

在 `toolAddDo()` 中，两个层级的禁用列表会同时检查：

```java
// 当前定义级禁用
if (metadata.getDisallowedTools().contains(toolName)) {
    return;
}

// 全局禁用
if (engine.getDisallowedTools().contains(toolName)) {
    return;
}
```

### 5、工具名与枚举对照

| `ToolPermission` 枚举 | 枚举名称（`getName()`） | 实际工具名（`toolAddDo`） |
|-------|-------|-------|
| `TOOL_HITL` | `hitl` | `hitl` |
| `TOOL_GENERATE` | `generate` | `generate` |
| `TOOL_RESTAPI` | `restapi` | `openapi` |
| `TOOL_MCP` | `mcp` | `mcp` |
| `TOOL_LSP` | `lsp` | `lsp` |
| `TOOL_CODE` | `code` | `code` |
| `TOOL_CODESEARCH` | `codesearch` | `codesearch` |
| `TOOL_WEBSEARCH` | `websearch` | `websearch` |
| `TOOL_WEBFETCH` | `webfetch` | `webfetch` |
| `TOOL_TODO` | `todo` | `todo` |
| `TOOL_TASK` | `task` | `task` |
| `TOOL_BASH` | `bash` | `bash` |
| `TOOL_LS` | `ls` | `ls` |
| `TOOL_GREP` | `grep` | `grep` |
| `TOOL_GLOB` | `glob` | `glob` |
| `TOOL_EDIT` | `edit` | `edit` |
| `TOOL_READ` | `read` | `read` |
| `TOOL_WRITE` | `write` | `write` |
| `TOOL_SKILL` | `skill` | `skill` |
| `TOOL_PI` | `pi` | 展开：`read, write, edit, bash+扩展` |
| `TOOL_ALL_PUBLIC` | `*` | 展开：全部公域工具 |
| `TOOL_ALL_FULL` | `**` | 展开：全部公域 + 私域工具 |

> 注意：`TOOL_RESTAPI` 的枚举名为 `restapi`，但 `toolAddDo` 中匹配的 `case` 名称为 `openapi`。当使用 `**` 通配符时，展开列表包含的是 `openapi`。如需手动指定工具名，请使用 `openapi`。