Tool Operations 接口层

Tool Operations 是 2026-05-01 后引入的工具执行后端抽象层。它把 tool-system 中 bash、read_file、write_file、list_dir、find_files、grep、edit、patch 这些内置工具的业务逻辑，与底层文件系统 / 子进程 / 搜索命令调用解耦。

它不是替代 tool-governance 或 tool-runtime-policy：治理层仍决定工具是否可见、是否能进子 Agent、走哪种 worker route；Operations 层只负责“被允许执行后，具体由哪个后端完成 I/O 和进程操作”。

三组接口

tools/operations/types.ts 定义三组接口，并聚合为 ToolOperations：

接口	核心方法	用途
`FileOperations`	`readFile`、`writeFile`、`appendFile`、`access`、`readDir`、`mkdir`、`realpath`	文件读写、目录枚举、写队列 realpath key
`ProcessOperations`	`exec(command, cwd, options)`	shell 命令执行、流式 stdout/stderr、超时和 abort
`SearchOperations`	`ripgrep`、`fd`	`grep` / `find_files` 的搜索后端

tools/operations/local.ts 是默认本地实现，使用 fs/promises 和 comm/child_process.spawn。getDefaultOperations() 通过 tools/operations/index.ts 提供单例，避免每次 resolver 重新创建实现对象。

当前落地范围

最近提交已完成四个阶段：

建立 ToolOperations 接口、本地实现和 tool_operations.test.ts 契约测试。
将 read/write/list、edit/patch、find/grep/bash 迁移到 factory + operations 注入模式。
在 tool_resolver.ts 统一注入 operations?: ToolOperations，主进程默认使用 getDefaultOperations()。
清理旧的 queue 签名和 bash 自有 operations，工具业务文件不再直接承担底层 spawn / fs 抽象职责。

因此新增或测试内置文件工具时，应优先 mock ToolOperations，而不是真实读写宿主机文件系统。

与子 Agent 的关系

subagent-session 仍以 tool-runtime-policy 的 manifest route 判断某个工具是 worker-local、main-process-proxy 还是 disabled。Operations 改造后的价值是让 worker / 主进程可以在构建工具实例时注入不同后端，而不用改工具的参数校验、diff 计算、输出截断等业务逻辑。

当前实现先保持原有工具粒度路由，不把权限下沉到每个 file/process 方法。未来如果需要远程 workspace、Docker 沙箱或 SSH 后端，可以新增 ToolOperations 实现，再由 resolver 按会话策略注入。

运行时细节

LocalProcessOperations.exec() 统一通过 comm/child_process.spawn，继承 Windows 下隐藏控制台窗口的处理。
bash 输出中的 ANSI escape code 在 LocalOperations 层剥离，避免每个工具重复清理。
withFileMutationQueueOps() 用注入的 FileOperations.realpath() 取队列 key，后续远程文件系统可以自定义“同一文件”的判断。
SearchOperations 单独抽出是因为 ripgrep/fd 的缺失、fallback 和参数语义与普通 shell 命令不同。

设计边界

Operations 不负责判断工具是否可用；最终可见性仍看 tool-governance 的 resolver 输出。
Operations 不改变 LLM 看到的工具 schema；prompt 和参数兼容旧工具。
Operations 不负责 Session Tree 写入；工具结果仍由 agent-runtime / session-tree-runtime 记录。
Operations 不包含 memory_*、delegate_*、clarify、todo 等不直接做文件或进程操作的工具。

4.0 KiB Raw Blame History Unescape Escape