167 lines
7.9 KiB
Markdown
167 lines
7.9 KiB
Markdown
|
---
|
|||
|
|
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]]
|