---
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]] — 所属模块