Tools zh

工具

上游工具注册、schema 和执行管线在 Edge 中的适配。

上游参考：Tools

上游提供了什么

ToolRuntime（ctx.tools）是中心化的工具注册表和执行引擎。它管理：

• 注册 — register() 接受通过 defineTool() 构建的 ToolDefinition，包含类型化参数、输出 schema、执行函数和 UI 展示回调。
• Schema 生成 — schemas() 通过允许列表和限制规则投射模型可见的工具定义。
• 执行管线 — 7 阶段瀑布流：pre-execute（审批）→ 单调守卫 → around-dispatch → 工具主体 → post-execute → finalizeContent → result emit。每个阶段可以允许、拒绝、替换或观察。
• 并发 — 工具声明 isConcurrencySafe 选择并行执行；agent loop 据此形成屏障和滚动池。

各个工具是独立的插件（ToolFs、ToolGoal、ToolWeb），在 apply() 时调用 ctx.tools.register()。运行时不知道有哪些工具——它只提供注册表和管线。

Edge 改了什么

直接复用 ToolRuntime

ToolRuntime 原封安装。完整的执行管线——pre-execute 瀑布、守卫、post-execute 钩子、内容最终化、schema 投射——运行未修改的上游代码。

直接复用 上游工具插件

三个上游工具插件直接安装：

• ToolFs — 文件 read/write/edit/read_image（底层 EdgeFileSystem）
• ToolGoal — create_goal/get_goal/update_goal
• ToolWeb — web 搜索（fetch 禁用）

替换件 Edge bash 工具

createEdgeBashTool() 通过标准的 ctx.tools.register() API 注册自定义 bash 工具。使用 defineTool() 和上游相同的 schema 词汇。工具通过 just-bash（纯 JS shell）在 Computer VFS 上执行命令，替代上游的 node:child_process。

注册通过 ctx.effect() 进行，工具绑定到 cordis 生命周期，在 disposal 时正确清理。

直接复用 管线扩展

SpillPolicy（post-execute 输出截断）和 TimeoutPolicy（工具调用超时）原封安装，参与上游管线，无 Edge 专属代码。

Edge 没有改什么

• 工具注册 API、schema DSL 和验证
• 7 阶段执行管线和瀑布语义
• 并发调度和屏障逻辑
• UI 展示词汇（卡片类型、diff 视图、终端视图）
• 错误处理（ToolArgsError、ToolOutputError、ToolNotFoundError）
• 作用域注册和限制过滤

性能特征

工具注册

所有工具在 EdgeSessionStore.initialize() 期间注册。注册是同步的 schema 编译——无 I/O。bash 工具通过 ctx.effect() 注册，增加一个 cordis 生命周期条目。总注册开销：可忽略（所有工具合计亚毫秒）。

执行管线开销

每次工具调用遍历 7 阶段管线。Edge 不添加自定义阶段——只有上游的 SpillPolicy（检查输出字节长度，条件性写入 VFS）和 TimeoutPolicy（用 AbortSignal.timeout() 包装执行）。两者每次调用 O(1)。管线本身是同步瀑布分发，阶段间无 I/O。

Bash 工具执行

bash 工具的性能由 just-bash 命令解析和 VFS I/O 决定，而非工具管线。详见 Bash wiki。

架构总结

组件	分类	Edge 代码
ToolRuntime	复用	一行 ctx.plugin() 调用
ToolFs, ToolGoal, ToolWeb	复用	三行 ctx.plugin() 调用
SpillPolicy, TimeoutPolicy	复用	两行 ctx.plugin() 调用
Edge bash 工具	替换	createEdgeBashTool() 通过 defineTool()

关键观察：工具子系统是架构宪章"最大化利用上游能力"原则的教科书案例。Edge 使用标准的 defineTool() + ctx.tools.register() API 插入自定义 bash 实现——与任何上游工具插件使用的 API 完全相同。运行时、管线、schema 系统和 UI 词汇完全是上游。Edge 只拥有一个工具定义。