tantingwu/GPU_GUARD_MONOREPO
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
GPU_GUARD_MONOREPO/docs/code-wiki/entities/tool-governance.md
陈二狗 cc660d19d1 初始化提交
2026-05-20 21:39:12 +08:00

7.9 KiB
Raw Blame History

title created updated type tags sources
Tool 全局治理系统 2026-04-19 2026-05-15 entity
tool
agent
config
backend
frontend
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 输出：

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

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

与 Renderer 的关系

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

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

相关页面