66 lines
4.0 KiB
Markdown
66 lines
4.0 KiB
Markdown
---
|
||
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]]
|