Tool Catalog 工具目录系统

概述

轻量级 schema 元数据注册表，只负责注册“系统中定义了哪些工具”。它不直接决定工具是否可用，也不保存运营侧治理配置；这些职责已转移到 tool-governance。当前它更像工具体系的“源头清单”，为 resolver、manifest、runtime diagnostic 提供静态起点。

目录结构

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

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

4.0 KiB Raw Blame History Unescape Escape