工具系统

TinyElf 的工具系统由 ToolRegistry 管理工具注册与执行，TinyElfToolRegistryBuilder 负责在会话启动时构建完整的工具集合。每个工具实现 ITool 接口。

工具注册流程

graph TB
    Builder["TinyElfToolRegistryBuilder<br/>buildToolRegistry()"] --> Reg["ToolRegistry"]

    Builder -->|"1. 文件系统"| FS["createFileSystemTools()<br/>Read, Write, Edit, ListDir, Glob, Grep"]
    Builder -->|"2. Shell"| Shell["ShellTool<br/>Bash"]
    Builder -->|"3. 网络搜索"| WS["setupWebSearch()<br/>WebSearch / NativeSearch"]
    Builder -->|"4. 网页抓取"| WF["createWebFetchTool()<br/>WebFetch + 摘要器"]
    Builder -->|"5. 技能"| SK["SkillsTool + ReadSkillTool<br/>list_skills, read_skill"]
    Builder -->|"6. SkillHub"| SH["SkillHubSearchTool + InstallTool<br/>skillhub_search, skillhub_install"]
    Builder -->|"7. 子 Agent"| SA["SpawnTool<br/>spawn_agent"]
    Builder -->|"8. 子 Agent 查询"| SAQ["SubagentListTool + StatusTool"]
    Builder -->|"9. Slash 命令"| CMD["SlashCommandTool<br/>slash_command"]
    Builder -->|"10. MCP"| MCP["loadMcpTools() + loadDirectMcpTools()<br/>mcp__*"]
    Builder -->|"11. 会话"| SS["SessionsSpawn/List/Send/History"]
    Builder -->|"12. 控制"| Ctrl["NotifyTool + SessionsYieldTool"]

    FS --> Reg
    Shell --> Reg
    WS --> Reg
    WF --> Reg
    SK --> Reg
    SH --> Reg
    SA --> Reg
    SAQ --> Reg
    CMD --> Reg
    MCP --> Reg
    SS --> Reg
    Ctrl --> Reg

ITool 接口

interface ITool {
  readonly name: string;            // 唯一工具名（function_calling 使用）
  readonly description: string;     // LLM 可读的描述
  readonly parameters: JsonSchema;  // JSON Schema 参数定义
  execute(params: Record<string, unknown>): Promise<string>;
}

ToolRegistry

class ToolRegistry {
  register(tool: ITool): void;
  registerAll(tools: ITool[]): void;
  unregister(name: string): boolean;
  get(name: string): ITool | undefined;
  has(name: string): boolean;
  getAll(): ITool[];
  getNames(): string[];
  getDefinitions(): ToolDefinition[];    // OpenAI function_calling 格式
  createFiltered(allowedNames: string[]): ToolRegistry;
  execute(toolCallId, toolName, params): Promise<ToolCallResult>;
}

执行流程

查找工具 → 未找到返回错误（列出可用工具）
参数类型转换 → 处理 LLM 常见的类型错误（字符串→数字等）
必填参数校验 → 缺失则返回错误
调用 tool.execute(params)
输出截断 → 超过 maxChars（默认 50KB）截断并添加 (truncated) 标记
错误输出追加提示 → [Analyze the error above and try a different approach.]

工具过滤

createFiltered() 创建一个新的 ToolRegistry 实例，仅包含白名单中的工具。用于：

plan 模式限制为只读工具
Agent 配置的 allowedTools 字段
Slash 命令的 allowed-tools 元数据

完整工具表

FileSystem 工具

工具名	类	敏感度	参数	说明
`Read`	`ReadFileTool`	安全	`path`, `offset?`, `limit?`	读取文件内容，支持分段读取
`Write`	`WriteFileTool`	敏感	`path`, `content`	写入文件（创建或覆盖）
`Edit`	`EditFileTool`	敏感	`path`, `old_string`, `new_string`, `replace_all?`	精确字符串替换
`ListDir`	`ListDirTool`	安全	`path`	列出目录内容
`Glob`	`GlobTool`	安全	`pattern`, `path?`	文件名模式匹配
`Grep`	`GrepTool`	安全	`pattern`, `path?`, `include?`	文件内容搜索

文件系统工具特性：

路径沙箱：所有路径相对于工作区根目录解析
restrictToWorkspace 配置项控制是否允许工作区外访问
Read 对大文件（>128KB）自动截断，>10MB 要求使用 offset/limit

Shell 工具

工具名	类	敏感度	参数	说明
`Bash`	`ShellTool`	敏感	`command`	执行 Shell 命令

Shell 工具安全特性：

命令黑名单（critical deny patterns）：rm -rf /、format、mkfs、diskpart 等
高风险命令警告：sudo、curl | sh、权限修改
工作区外路径检测
输出限制：100KB
超时：默认 2 分钟，可通过 execTimeout 配置

Web 工具

工具名	类	敏感度	参数	说明
`WebSearch`	`WebSearchServiceTool`	安全	`query`, `count?`	网页搜索
`WebFetch`	`WebFetchTool`	安全	`url`, `prompt?`, `raw?`	抓取网页内容

WebFetch 特性：

使用 Readability 提取文章正文
HTML → Markdown 转换（Turndown）
超过 4KB 的内容自动使用后台模型摘要
超时 30 秒，最大响应 5MB

网络搜索三级回退：

原生搜索（Anthropic/OpenAI/Gemini/xAI 内置）
WebSearchService（Tavily/Jina/Searxng）
不可用

Subagent 工具

工具名	类	敏感度	参数	说明
`spawn_agent`	`SpawnTool`	敏感	`prompt`, `agent?`, `model?`, `background?`, `maxIterations?`, `permissionMode?`, `tools?`	启动子 Agent
`subagent_list`	`SubagentListTool`	安全	无	列出活跃子 Agent
`subagent_status`	`SubagentStatusTool`	安全	`runId`	查询子 Agent 状态

Session 工具

工具名	类	敏感度	参数	说明
`SessionsSpawn`	`SessionsSpawnTool`	敏感	`prompt`, `agentId?`, `title?`	创建新会话
`SessionsList`	`SessionsListTool`	安全	`limit?`, `offset?`	列出会话
`SessionsSend`	`SessionsSendTool`	敏感	`sessionId`, `message`	向会话发送消息
`SessionsHistory`	`SessionsHistoryTool`	安全	`sessionId`, `limit?`	查看会话历史
`SessionsYield`	`SessionsYieldTool`	安全	`message`	结束 Agent 循环并返回消息

Skills 工具

工具名	类	敏感度	参数	说明
`list_skills`	`SkillsTool`	安全	无	列出所有可用技能
`read_skill`	`ReadSkillTool`	安全	`name`	读取技能内容
`skillhub_search`	`SkillHubSearchTool`	安全	`query`	搜索社区技能
`skillhub_install`	`SkillHubInstallTool`	安全	`skillId`	安装社区技能

MCP 工具

工具名	类	敏感度	参数	说明
`mcp__<server>__<tool>`	动态生成	敏感	由 MCP 服务器定义	外部 MCP 工具

MCP 工具通过三种方式加载：

用户 MCP（mcpServerIds）— 通过 McpService 连接用户在「设置 → MCP」中配置的 stdio/http/sse 服务器
内置 MCP（通过 McpProviderRegistry 自动装配）— 所有内置 MCP handler 都在主进程内（in-process），SDK 通过 createSdkMcpServer 包装、TinyElf 注册为 ITool、CLI 通过中央 BuiltinMcpHttpServer HTTP 桥访问。每个 agent 的可见 MCP 由 Provider 的 isEligible(ctx) 决定（不再走 Agent 配置中的 builtinMcpServers 字段 —— 该字段在 cleanup-legacy-mcp（2026-05-19）删除）
直接 MCP（directMcpServers）— Agent 配置中声明的预解析 stdio MCP（用户场景，如调用本地 Python 工具）

Control 工具

工具名	类	敏感度	参数	说明
`Notify`	`NotifyTool`	安全	`title`, `body?`	发送桌面通知
`slash_command`	`SlashCommandTool`	安全	`command`, `args?`	执行 Slash 命令

工具敏感度分类

private static readonly SAFE_TOOLS = new Set([
  'Read', 'ListDir', 'Glob', 'Grep',
  'WebSearch', 'WebFetch',
  'list_skills', 'read_skill',
  'Notify', 'SessionsYield', 'SessionsHistory',
]);

判定规则：

在 SAFE_TOOLS 集合中 → 永不需要确认
acceptEdits 模式下 Write 和 Edit 也不需要确认
所有其他工具（含 MCP 工具）→ 需要确认

工具继承

子 Agent 可以从父 Agent 继承部分工具：

const inheritableToolNames = new Set([
  'list_skills', 'read_skill', 'slash_command'
]);
// + 所有以 mcp__ 开头的 MCP 工具

关键文件

文件	路径	说明
ITool 接口	`tinyelf/tools/ToolInterface.ts`	工具基础接口
ToolRegistry	`tinyelf/tools/ToolRegistry.ts`	工具注册表
ToolRegistryBuilder	`tinyelf/TinyElfToolRegistryBuilder.ts`	工具构建器
FileSystemTools	`tinyelf/tools/FileSystemTools.ts`	文件系统工具
ShellTool	`tinyelf/tools/ShellTool.ts`	Shell 工具
WebTools	`tinyelf/tools/WebTools.ts`	WebFetch
WebSearchServiceTool	`tinyelf/tools/WebSearchServiceTool.ts`	WebSearch
SpawnTool	`tinyelf/tools/SpawnTool.ts`	子 Agent 工具
SessionTools	`tinyelf/tools/SessionTools.ts`	会话管理工具
SkillsTool	`tinyelf/tools/SkillsTool.ts`	技能工具
SkillHubTools	`tinyelf/tools/SkillHubTools.ts`	SkillHub 工具
McpToolAdapter	`tinyelf/tools/McpToolAdapter.ts`	MCP 工具适配
NotifyTool	`tinyelf/tools/NotifyTool.ts`	通知工具
YieldTool	`tinyelf/tools/YieldTool.ts`	循环终止工具
SubagentTools	`tinyelf/tools/SubagentTools.ts`	子 Agent 查询
SlashCommandTool	`tinyelf/tools/SlashCommandTool.ts`	Slash 命令

所有路径相对于 packages/desktop/app/main/services/agent-core/engine/。

扩展点

新增工具：实现 ITool 接口 → 在 TinyElfToolRegistryBuilder 中注册
修改敏感度：在 TinyElfAgentLoop.SAFE_TOOLS 集合中添加/移除
自定义工具继承：修改 inheritableToolNames 集合
MCP 工具加载：通过 McpToolAdapter 适配新的 MCP 传输方式

模块	路径	关系
TinyElfAgentLoop	`tinyelf/TinyElfAgentLoop.ts`	工具执行调用方
ExecutionFirewall	`platform/security/ExecutionFirewall.ts`	文件工具路径检查
McpService	`capabilities/tools/mcp-users/McpService.ts`	MCP 工具来源
SkillsLoader	`tinyelf/skills/SkillsLoader.ts`	技能工具依赖
SubagentManager	`tinyelf/tools/SpawnTool.ts`	spawn_agent 依赖

工具注册流程​

ITool 接口​

ToolRegistry​

执行流程​

工具过滤​

完整工具表​

FileSystem 工具​

Shell 工具​

Web 工具​

Subagent 工具​

Session 工具​

Skills 工具​

MCP 工具​

Control 工具​

工具敏感度分类​

工具继承​

关键文件​

扩展点​

相关模块​