136 lines
4.0 KiB
Markdown
136 lines
4.0 KiB
Markdown
|
---
|
|||
|
|
title: Tool Catalog 工具目录系统
|
|||
|
|
created: 2026-04-16
|
|||
|
|
updated: 2026-05-15
|
|||
|
|
type: entity
|
|||
|
|
tags: [tool, agent, architecture]
|
|||
|
|
sources: [packages/backend/src/modules/netaclaw/tools/catalog.ts]
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Tool Catalog 工具目录系统
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
轻量级 schema 元数据注册表，只负责注册“系统中定义了哪些工具”。它不直接决定工具是否可用，也不保存运营侧治理配置；这些职责已转移到 [[tool-governance]]。当前它更像工具体系的“源头清单”，为 resolver、manifest、runtime diagnostic 提供静态起点。
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
netaclaw/tools/
|
|||
|
|
├── catalog.ts # schema 注册表核心
|
|||
|
|
├── common.ts # AgentTool 接口与辅助函数
|
|||
|
|
├── fuzzy_match.ts # 9级模糊匹配引擎（供 patch 使用）
|
|||
|
|
├── todo_tool.ts # Todo 工具 schema
|
|||
|
|
└── builtin/
|
|||
|
|
├── bash.ts
|
|||
|
|
├── file.ts
|
|||
|
|
├── patch.ts
|
|||
|
|
├── clarify.ts
|
|||
|
|
├── memory.ts
|
|||
|
|
├── mysql.ts
|
|||
|
|
├── read_skill.ts
|
|||
|
|
├── read_skill_file.ts
|
|||
|
|
├── skill_manage.ts
|
|||
|
|
├── delegate_task.ts
|
|||
|
|
├── delegate_parallel.ts
|
|||
|
|
└── escalate.ts
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## ToolSchema
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface ToolSchema {
|
|||
|
|
name: string;
|
|||
|
|
toolset: string;
|
|||
|
|
description: string;
|
|||
|
|
visibility?: 'internal' | 'tool' | 'skill';
|
|||
|
|
capability?: 'text' | 'vision' | 'multimodal';
|
|||
|
|
isCore?: boolean;
|
|||
|
|
canDisable?: boolean;
|
|||
|
|
supportsPromptHint?: boolean;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
相比旧版，catalog 现在除了名称和工具集，还承担：
|
|||
|
|
|
|||
|
|
- 模型能力要求
|
|||
|
|
- 是否核心工具
|
|||
|
|
- 是否允许关闭
|
|||
|
|
- 是否支持 Prompt Hint
|
|||
|
|
- 可见性标记
|
|||
|
|
|
|||
|
|
但它依然不负责：
|
|||
|
|
|
|||
|
|
- 子 Agent 是否允许使用该工具
|
|||
|
|
- 当前 session 下是否需要主进程代理
|
|||
|
|
- blocked reason 和最终 runtime route
|
|||
|
|
- 前端最终展示文案
|
|||
|
|
|
|||
|
|
## 核心 API
|
|||
|
|
|
|||
|
|
| API | 说明 |
|
|||
|
|
|-----|------|
|
|||
|
|
| `registerSchema(schema)` | 注册工具 schema |
|
|||
|
|
| `getAllToolSchemas()` | 获取全部 schema |
|
|||
|
|
| `getToolSchema(name)` | 查询单个 schema |
|
|||
|
|
| `getToolNamesByToolset(toolset)` | 按 toolset 查询 |
|
|||
|
|
| `getToolNamesByToolsets(toolsets)` | 按多个 toolset 查询 |
|
|||
|
|
|
|||
|
|
## 默认工具集
|
|||
|
|
|
|||
|
|
- `TOOLSET_DEFAULTS = ['base', 'planning', 'interaction']`
|
|||
|
|
- 另外保留 `vision`、`document`、`mysql` 等常量，用于能力分组和 Agent 工具集配置。
|
|||
|
|
|
|||
|
|
## 当前工具集分类
|
|||
|
|
|
|||
|
|
| 工具集 | 说明 |
|
|||
|
|
|--------|------|
|
|||
|
|
| `base` | 基础文件与命令工具 |
|
|||
|
|
| `planning` | todo 规划工具 |
|
|||
|
|
| `interaction` | clarify / escalate |
|
|||
|
|
| `memory` | 长期记忆工具 |
|
|||
|
|
| `skill` | Skill 相关工具 |
|
|||
|
|
| `crew` | 委派工具 |
|
|||
|
|
| `mysql` | MySQL 只读问数工具，详见 [[mysql-data-source]] |
|
|||
|
|
|
|||
|
|
## 注册机制
|
|||
|
|
|
|||
|
|
`catalog.ts` 底部通过 import 触发各工具文件调用 `registerSchema()`，形成静态注册表。这个注册表随后会被：
|
|||
|
|
|
|||
|
|
- `tool_registry.ts` 用来同步和对齐 DB 治理配置。
|
|||
|
|
- `tool_resolver.ts` 用来拼装最终可用工具集。
|
|||
|
|
- `tools/manifest.ts` / `tools/runtime_policy.ts` 用来生成运行时画像与路由。
|
|||
|
|
|
|||
|
|
## 与治理层的分工
|
|||
|
|
|
|||
|
|
### Catalog 负责
|
|||
|
|
|
|||
|
|
- 系统里有哪些工具
|
|||
|
|
- 每个工具的 schema 元信息
|
|||
|
|
- 默认工具集与分类
|
|||
|
|
|
|||
|
|
### Governance 负责
|
|||
|
|
|
|||
|
|
- 全局启停
|
|||
|
|
- Agent 级启停覆盖
|
|||
|
|
- Prompt Hint 覆写
|
|||
|
|
- 模型能力过滤
|
|||
|
|
- 上下文角色限制
|
|||
|
|
- 动态运行路由与诊断输出
|
|||
|
|
|
|||
|
|
详见 [[tool-governance]]。
|
|||
|
|
|
|||
|
|
## 与 Prompt Builder 的关系
|
|||
|
|
|
|||
|
|
旧版 `collectAvailableToolNames()` 仍在 [[prompt-builder]] 中保留，但当前关键运行链路已转向 `tool_resolver.resolve()` 先给出最终 `toolNames`，再交给 Prompt Builder 组装提示词。
|
|||
|
|
|
|||
|
|
## 关联页面
|
|||
|
|
|
|||
|
|
- [[tool-system]] — 工具系统总览
|
|||
|
|
- [[tool-governance]] — catalog 之上的治理层
|
|||
|
|
- [[mysql-data-source]] — mysql toolset 的数据源、schema、query 和审计边界
|
|||
|
|
- [[prompt-builder]] — 消费最终工具列表
|
|||
|
|
- [[patch-tool]] — Patch 工具（base 工具集）
|
|||
|
|
- [[clarify-tool]] — Clarify 工具（interaction 工具集）
|
|||
|
|
- [[netaclaw-module]] — 所属模块
|