---
title: Tool 全局治理系统
created: 2026-04-19
updated: 2026-05-15
type: entity
tags: [tool, agent, config, backend, frontend]
sources: [packages/backend/src/modules/netaclaw/entity/tool.ts, packages/backend/src/modules/netaclaw/service/tool_registry.ts, packages/backend/src/modules/netaclaw/service/tool_resolver.ts, packages/backend/src/modules/netaclaw/tools/manifest.ts, packages/backend/src/modules/netaclaw/tools/runtime_policy.ts, packages/backend/src/modules/netaclaw/tools/presentation.ts, packages/frontend/src/modules/agent/views/tools.vue, packages/frontend/src/modules/agent/views/agent-edit.vue]
---

# Tool 全局治理系统

Tool 全局治理系统位于 [[tool-system]] 之上，负责把工具从“代码里的可调用函数”提升为“可同步、可禁用、可按 Agent 覆盖、可诊断、可进入子进程策略”的平台能力。

当前治理口径已经扩展到四类输出：

- 最终可用工具列表。
- Prompt Hint 和工具描述投影。
- Agent/子 Agent 的启停和 override 结果。
- Worker runtime profile 与 blocked reason，详见 [[tool-runtime-policy]]。

2026-04-22 之后，这一层又新增了两个重要职责：

- 生成 `toolRuntimeRoutes`，把“配置上允许”进一步收口为“当前运行态到底走 worker-local、main-process-proxy 还是 disabled”。
- 生成 `runtimeDiagnostic` / renderer capability 投影，供工具管理页、Agent 编辑页和对话页使用同一套解释。

2026-05-02 后，还需要把 [[tool-operations]] 看成工具执行后端维度：治理层决定某个工具是否进入 runtime，Operations 决定这个工具执行时用本地、mock、worker proxy 还是未来的远程/沙箱实现。两者不能混用：不要用 Operations 判断工具是否应显示，也不要用 DB governance 直接替代文件/进程后端注入。

2026-05-15 后，`mysql_*` 工具也纳入同一套治理口径：[[tool-catalog]] 注册 `mysql` toolset，`tool_resolver.ts` 注入 MySQL 数据源、schema 和查询服务，manifest 将这些工具统一路由为 `main-process-proxy`。治理层只决定工具是否对某个 Agent 可见；真正的数据源授权、SQL guard、脱敏列拒绝、连接池和查询审计仍留在 [[mysql-data-source]] 的服务端实现中。

## 数据模型

`netaclaw_tool` 记录全局工具治理配置。核心字段包括：

| 字段 | 含义 |
| --- | --- |
| `name` | 工具唯一标识 |
| `toolset` | 所属工具集 |
| `label` | 展示名称 |
| `description` | 展示描述 |
| `visibility` | `tool`、`skill`、`internal` |
| `capability` | `text`、`vision`、`multimodal` |
| `status` | 全局启停 |
| `isCore` | 是否核心工具 |
| `canDisable` | 核心工具是否允许 Agent 级关闭 |
| `supportsPromptHint` | 是否支持 Prompt Hint |
| `promptHint` | 运行提示覆盖 |
| `sort` | 展示顺序 |
| `extra` | 运行时扩展配置，如 `workerRoutingStrategy`、`allowInSubagent` |

## 核心服务

| 文件 | 职责 |
| --- | --- |
| `service/tool_registry.ts` | catalog 同步、DB 治理配置读写、管理端查询 |
| `service/tool_resolver.ts` | 根据全局治理、Agent 配置、运行上下文生成最终工具投影 |
| `tools/manifest.ts` | 为工具生成 worker/runtime manifest |
| `tools/runtime_policy.ts` | 推导子进程 policy、路由状态和 blocked reason |
| `tools/presentation.ts` | 统一前端展示文案和运行时投影格式 |
| `tools/operations/` | 工具底层执行后端接口与本地实现 |

## Resolver 输入

`tool_resolver.ts` 的有效决策不只来自全局开关，还包括：

- Agent 的 `tools.enabled` 和 `tools.disabled`。
- Agent 的 `toolOverrides`、`draftAgentTools`、`draftToolOverride`。
- `subagentConfig.enabled`、`allowedToolNames`、`allowedPresetAgentIds`。
- 当前模型能力，例如 vision/multimodal。
- 当前运行上下文，例如主 Agent、子 Agent、Crew、Skill、Memory。
- session cwd、workspace roots、shell/readonly 策略。
- 可选 `operations` 注入；测试、worker 或未来远程执行可替换底层后端。

## Resolver 输出

后端应该返回统一 projection，而不是让前端三处页面各自推导：

- `toolNames`: 当前真正进入 runtime 的工具名。
- `tools`: 可执行工具实例或工具元数据。
- `toolPromptHints`: Prompt Builder 消费的 hint。
- `disabledReasons`: 解释工具为何没有生效。
- `runtimeDiagnostic`: 工具运行画像、worker route、blocked reason。
- `effectiveRuntimeProfile`: 对当前 Agent 生效的 runtime profile。
- `effectiveSubagentAllowed`: 对当前 Agent/子 Agent 生效的可用性。
- `toolRuntimeRoutes`: 当前会话和策略下每个工具的实际运行路由。

这保证工具管理页、Agent 编辑页、对话页看到同一套结果。

其中有两个边界需要特别强调：

- `effectiveRuntimeProfile` 偏静态画像，描述该工具通常需要哪些权限、支持哪种 worker routing hint。
- `toolRuntimeRoutes` 偏动态结果，描述在当前 session cwd、workspace roots、allowShell、readonly 条件下的最终实际路由。

只有把这两层都看完，才能判断一个工具为什么“看起来允许但运行时被挡住”。

新增 `execute_skill` 后，Skill 工具集的治理也需要区分：`read_skill` / `read_skill_file` 是 prompt/toolkit skill 的读取入口，`execute_skill` 只应在 Agent 绑定 compute-entry skill 且工具治理允许时进入 runtime。详见 [[skill-runtime]]。

## 前端页面职责

### 工具管理页

`packages/frontend/src/modules/agent/views/tools.vue` 面向全局治理：

- 查看和同步 catalog。
- 编辑全局启停、核心工具、是否可关闭、Prompt Hint、排序。
- 展示工具 runtime profile、worker routing、renderer 绑定、文件能力标签。
- 页面需要可滚动，避免工具增多后看不到底部内容。
- 支持调用 `/admin/netaclaw/tool/runtimeDiagnostic` 查看在指定 session cwd / workspace roots / shell / readonly 条件下的真实诊断结果。

### Agent 编辑页

`packages/frontend/src/modules/agent/views/agent-edit.vue` 面向局部配置：

- 配置当前 Agent 的工具开启/关闭。
- 配置子 Agent 是否启用、并发、可用预设 Agent、允许工具。
- 预览后端返回的 effective projection。
- 保存本地存储、workspace、运行策略相关配置时，应影响子 Agent 工具推导。

这一页现在不只是“勾选工具”：

- 会直接展示每个工具的 `effectiveRuntimeProfile`。
- 会直接标记 `effectiveSubagentAllowed`，帮助判断该工具是否允许进入子代理。
- 会结合 `toolRuntimeRoutes` 告诉用户配置保存后，子 Agent 最终走哪条执行路径。

### 对话页

`packages/frontend/src/modules/agent/views/chat.vue` 面向实际运行结果：

- 展示工具调用过程。
- 展示子 Agent 批次工具路由。
- 对 blocked reason 使用同一套文案。
- 通过 [[session-tree-runtime]] 恢复历史。
- 对子 Agent 任务只显示本批次请求到的工具路由，而不是整套全局路由。

## 与 Prompt Builder 的关系

Prompt Builder 不直接读取 catalog，而是消费 resolver 输出：

```text
tool_registry/catalog
  -> tool_resolver
  -> toolNames + toolPromptHints + runtimeDiagnostic
  -> prompt_builder
  -> runAgent
```

这样工具行为提示、禁用原因、模型能力过滤可以在一处收敛。

## 与 Renderer 的关系

治理系统已经不只决定“能不能执行”，还决定“前端怎么展示”：

- `tools/presentation.ts` 负责输出 renderer capability projection。
- 工具管理页会显示某个工具是自定义渲染器还是默认绑定。
- 这使“新增工具但页面表现很差”也成为治理问题的一部分，而不只是前端细节。

## 相关页面

- [[tool-system]]
- [[tool-runtime-policy]]
- [[tool-operations]]
- [[tool-catalog]]
- [[mysql-data-source]]
- [[agent-runtime]]
- [[subagent-session]]
- [[prompt-builder]]
- [[frontend-architecture]]