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

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

1、工具名到 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() 中，两个层级的禁用列表会同时检查：

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

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

5、工具名与枚举对照

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