ToolCatalog

SUPPORT · interface · 类型合同

Frozen tool catalog with model tools and per-request binding.

导入

TypeScript

import type { ToolCatalog } from '@jangts/agent-core/support';

JavaScript

/** @typedef {import('@jangts/agent-core/support').ToolCatalog} ToolCatalog */

其他公开入口：@jangts/agent-core/types、@jangts/agent-core/structs、@jangts/agent-core/support。

定义

interface ToolCatalog<App, Tool>

继承或实现： ReadonlyCatalog<ToolCatalogEntry<App, Tool>>。

泛型参数

类型参数	约束	默认类型
App	—	—
Tool	ToolDefinition<unknown, unknown, App>	ToolDefinition<unknown, unknown, App>

字段结构

字段	类型	必需	说明
tools	ToolModelView<App>	必需	只读。见类型定义及调用场景。
select	<const Ids extends readonly string[]>(ids: Ids, context?: App) => ToolCatalog<App, SelectedTools<Tool, Ids[number]>>	必需	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	(context: App) => ToolCatalog<App, Tool>	必需	Active tools advertising demand-discovery use; descriptions are view-local.
bind	(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }) => ToolRuntime<Tool, App>	必需	Binds the catalog to one App request and returns an invocable runtime.
definitions	readonly Readonly<ToolCatalogEntry<App, Tool>>[]	必需	只读。Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	必需	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<ToolCatalogEntry<App, Tool>>>	必需	见类型定义及调用场景。
entries	() => IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => Readonly<ToolCatalogEntry<App, Tool>> | undefined	必需	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<ToolCatalogEntry<App, Tool>>	必需	Returns the definition or throws; use when the id is a required reference.

成员目录

成员	用途
select	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	Active tools advertising demand-discovery use; descriptions are view-local.
bind	Binds the catalog to one App request and returns an invocable runtime.
ids	Ids in the same order as definitions.
values	完整输入输出见下方重载。
entries	完整输入输出见下方重载。
has	完整输入输出见下方重载。
get	Returns the definition or undefined; the caller decides whether absence is an error.
require	Returns the definition or throws; use when the id is a required reference.

成员详情

select

Narrows the catalog while preserving declaration order; throws for unknown ids.

ToolCatalog.select<const Ids extends readonly string[]>(ids: Ids, context?: App): ToolCatalog<App, SelectedTools<Tool, Ids[number]>>

Narrows the catalog while preserving declaration order; throws for unknown ids.

类型参数	约束	默认类型
Ids	readonly string[]	—

参数	类型	传递	说明
ids	Ids	必需	—
context	App | undefined	可省略	—

返回： ToolCatalog<App, SelectedTools<Tool, Ids[number]>>。

返回值结构

字段	类型	必需	说明
tools	ToolModelView<App>	必需	只读。见类型定义及调用场景。
select	<const Ids extends readonly string[]>(ids: Ids, context?: App) => ToolCatalog<App, SelectedTools<SelectedTools<Tool, Ids[number]>, Ids[number]>>	必需	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	(context: App) => ToolCatalog<App, SelectedTools<Tool, Ids[number]>>	必需	Active tools advertising demand-discovery use; descriptions are view-local.
bind	(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }) => ToolRuntime<SelectedTools<Tool, Ids[number]>, App>	必需	Binds the catalog to one App request and returns an invocable runtime.
definitions	readonly Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>[]	必需	只读。Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	必需	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>>	必需	见类型定义及调用场景。
entries	() => IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>]>	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>> | undefined	必需	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>	必需	Returns the definition or throws; use when the id is a required reference.

withIntent

Active tools advertising demand-discovery use; descriptions are view-local.

ToolCatalog.withIntent(context: App): ToolCatalog<App, Tool>

Active tools advertising demand-discovery use; descriptions are view-local.

参数	类型	传递	说明
context	App	必需	—

返回： ToolCatalog<App, Tool>。

返回值结构

字段	类型	必需	说明
tools	ToolModelView<App>	必需	只读。见类型定义及调用场景。
select	<const Ids extends readonly string[]>(ids: Ids, context?: App) => ToolCatalog<App, SelectedTools<Tool, Ids[number]>>	必需	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	(context: App) => ToolCatalog<App, Tool>	必需	Active tools advertising demand-discovery use; descriptions are view-local.
bind	(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }) => ToolRuntime<Tool, App>	必需	Binds the catalog to one App request and returns an invocable runtime.
definitions	readonly Readonly<ToolCatalogEntry<App, Tool>>[]	必需	只读。Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	必需	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<ToolCatalogEntry<App, Tool>>>	必需	见类型定义及调用场景。
entries	() => IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => Readonly<ToolCatalogEntry<App, Tool>> | undefined	必需	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<ToolCatalogEntry<App, Tool>>	必需	Returns the definition or throws; use when the id is a required reference.

bind

Binds the catalog to one App request and returns an invocable runtime.

ToolCatalog.bind(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }): ToolRuntime<Tool, App>

Binds the catalog to one App request and returns an invocable runtime.

参数	类型	传递	说明
request	{ app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }	必需	—

request 的字段

字段	类型	必需	说明
app	App	必需	见类型定义及调用场景。
execution	ExecutionOptions | undefined	可省略	见类型定义及调用场景。
errors	Pick<ToolRegistryPorts, "unavailable" | "errorCode"> | undefined	可省略	见类型定义及调用场景。

返回： ToolRuntime<Tool, App>。

返回值结构

字段	类型	必需	说明
tools	ToolModelView<App>	必需	只读。The catalog's model tools, shared with the catalog instance.
events	readonly ToolExecutionEvent<string>[]	必需	只读。Execution events recorded by this runtime so far, in occurrence order.
invokeSync	{ <const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): ToolResult<ToolOutput<Tool, Id>>; (request: ToolInvocationRequest): ToolResult<unknown>; }	必需	Synchronous invocation; rejects tools declared as asynchronous.
invoke	{ <const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): Promise<ToolResult<ToolOutput<Tool, Id>>>; (request: ToolInvocationRequest): Promise<ToolResult<unknown>>; }	必需	Asynchronous invocation; still bounded by the bound execution signal and errors.

ids

Ids in the same order as definitions.

ToolCatalog.ids(): readonly string[]

Ids in the same order as definitions.

无调用参数。

返回： readonly string[]。

values

ToolCatalog.values(): IterableIterator<Readonly<ToolCatalogEntry<App, Tool>>>

无调用参数。

返回： IterableIterator<Readonly<ToolCatalogEntry<App, Tool>>>。

entries

ToolCatalog.entries(): IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>

无调用参数。

返回： IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>。

has

ToolCatalog.has(id: string): boolean

参数	类型	传递	说明
id	string	必需	—

返回： boolean。

get

Returns the definition or undefined; the caller decides whether absence is an error.

ToolCatalog.get(id: string): Readonly<ToolCatalogEntry<App, Tool>> | undefined

Returns the definition or undefined; the caller decides whether absence is an error.

参数	类型	传递	说明
id	string	必需	—

返回： Readonly<ToolCatalogEntry<App, Tool>> \| undefined。

返回值的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	ToolCatalogEntry<App, Tool>["id"]	必需	只读。Stable id; also the name the model calls.
description	ToolCatalogEntry<App, Tool>["description"]	必需	只读。Model-visible explanation of when to call the tool.
resolve	ToolCatalogEntry<App, Tool>["resolve"] | undefined	可省略	只读。见类型定义及调用场景。
inputSchema	ToolCatalogEntry<App, Tool>["inputSchema"]	必需	只读。Schema applied to raw model arguments before authorize and execute.
active	ToolCatalogEntry<App, Tool>["active"] | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	ToolCatalogEntry<App, Tool>["asIntent"] | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
kind	ToolCatalogEntry<App, Tool>["kind"]	必需	只读。Declared grouping used by registries and documentation; not an authorization boundary.
authorize	ToolCatalogEntry<App, Tool>["authorize"]	必需	Host permission check. Runs before execution and may be asynchronous.
execute	ToolCatalogEntry<App, Tool>["execute"]	必需	Executes the already-authorized input; must not repeat authorization decisions.
debugSteps	ToolCatalogEntry<App, Tool>["debugSteps"] | undefined	可省略	Optional result hook; writes through context.createSubFlowLogger() are recorded immediately.
parseOutput	ToolCatalogEntry<App, Tool>["parseOutput"]	必需	Validates untrusted output (for example a cached replay) before it is returned.

require

Returns the definition or throws; use when the id is a required reference.

ToolCatalog.require(id: string): Readonly<ToolCatalogEntry<App, Tool>>

Returns the definition or throws; use when the id is a required reference.

参数	类型	传递	说明
id	string	必需	—

返回： Readonly<ToolCatalogEntry<App, Tool>>。

返回值结构

字段	类型	必需	说明
id	ToolCatalogEntry<App, Tool>["id"]	必需	只读。Stable id; also the name the model calls.
description	ToolCatalogEntry<App, Tool>["description"]	必需	只读。Model-visible explanation of when to call the tool.
resolve	ToolCatalogEntry<App, Tool>["resolve"] | undefined	可省略	只读。见类型定义及调用场景。
inputSchema	ToolCatalogEntry<App, Tool>["inputSchema"]	必需	只读。Schema applied to raw model arguments before authorize and execute.
active	ToolCatalogEntry<App, Tool>["active"] | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	ToolCatalogEntry<App, Tool>["asIntent"] | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
kind	ToolCatalogEntry<App, Tool>["kind"]	必需	只读。Declared grouping used by registries and documentation; not an authorization boundary.
authorize	ToolCatalogEntry<App, Tool>["authorize"]	必需	Host permission check. Runs before execution and may be asynchronous.
execute	ToolCatalogEntry<App, Tool>["execute"]	必需	Executes the already-authorized input; must not repeat authorization decisions.
debugSteps	ToolCatalogEntry<App, Tool>["debugSteps"] | undefined	可省略	Optional result hook; writes through context.createSubFlowLogger() are recorded immediately.
parseOutput	ToolCatalogEntry<App, Tool>["parseOutput"]	必需	Validates untrusted output (for example a cached replay) before it is returned.

使用示例

• 工具最佳实践：一份定义生成模型 Tool 与执行运行时：把 Schema、授权、执行和输出校验登记一次，按请求绑定 App，避免维护两份工具清单。

定义并使用一项只读工具

入门 · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
  jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
  parse(value: unknown) {
    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new TypeError('需要空对象');
    return {};
  },
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
  authorize() {},
  execute() { return '服务运行正常'; },
  parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());

JavaScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
    jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
    parse(value) {
        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
            throw new TypeError('需要空对象');
        return {};
    },
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
        authorize() { },
        execute() { return '服务运行正常'; },
        parseOutput(value) { if (typeof value !== 'string')
            throw new TypeError('需要字符串'); return value; },
    }]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());

保留清单，增加本次权限与服务依赖

配置 · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
import type { OperationContext } from '@jangts/agent-core/types';
type App = { allowed: boolean; readStatus(): Promise<string> };
const inputSchema = Support.defineSchema({
  jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
  parse(value: unknown) {
    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new TypeError('需要空对象');
    return {};
  },
});
const catalog = Support.defineToolCatalog<App>([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
  authorize(_input: {}, { app }: OperationContext<App>) { if (!app.allowed) throw new Error('当前请求没有读取权限'); },
  execute(_input: {}, { app }: OperationContext<App>) { return app.readStatus(); },
  parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
  execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);

JavaScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
    jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
    parse(value) {
        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
            throw new TypeError('需要空对象');
        return {};
    },
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
        authorize(_input, { app }) { if (!app.allowed)
            throw new Error('当前请求没有读取权限'); },
        execute(_input, { app }) { return app.readStatus(); },
        parseOutput(value) { if (typeof value !== 'string')
            throw new TypeError('需要字符串'); return value; },
    }]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
    execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);

相关策略源码

• 授权与工具能力投影来自同源定义

相关定义

• ExecutionOptions
• ReadonlyCatalog
• SelectedTools
• ToolCatalogEntry
• ToolDefinition
• ToolModelView
• ToolRegistryPorts
• ToolRuntime