---
title: Tool Operations 接口层
created: 2026-05-02
updated: 2026-05-02
type: concept
tags: [tool, runtime, backend, architecture]
sources: [docs/superpowers/specs/2026-05-01-tool-pluggable-operations-design.md, packages/backend/src/modules/netaclaw/tools/operations/, packages/backend/src/modules/netaclaw/tools/builtin/, packages/backend/src/modules/netaclaw/service/tool_resolver.ts, packages/backend/test/tool_operations.test.ts]
---

# 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 重新创建实现对象。

## 当前落地范围

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

1. 建立 `ToolOperations` 接口、本地实现和 `tool_operations.test.ts` 契约测试。
2. 将 read/write/list、edit/patch、find/grep/bash 迁移到 factory + operations 注入模式。
3. 在 `tool_resolver.ts` 统一注入 `operations?: ToolOperations`，主进程默认使用 `getDefaultOperations()`。
4. 清理旧的 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` 等不直接做文件或进程操作的工具。

## 相关页面

- [[tool-system]]
- [[tool-governance]]
- [[tool-runtime-policy]]
- [[subagent-session]]
- [[agent-runtime]]