ModelToolCatalog

CORE · type · 类型合同

A compiled entity catalog also supports the minimal stage source contract.

导入

TypeScript

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

JavaScript

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

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

定义

类型： ModelToolCatalog<Output>

类型表达式

type ModelToolCatalog<Output = unknown> = ReadonlyCatalog<RegisteredModelTool<Output>> &
  ModelToolSource<Output> & {
    /** Explicit selection, optionally filtered against a host context. */
    select(ids: readonly string[], context?: unknown): ModelToolCatalog<Output>;
    /** Demand-facing active tools; no workflow node or invocation is implied. */
    withIntent(context: unknown): ModelToolCatalog<Output>;
  };

泛型参数

类型参数	约束	默认类型
Output	—	unknown

字段结构

字段	类型	必需	说明
definitions	readonly Readonly<Readonly<ModelTool<unknown, Output, any>>>[]	必需	只读。Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	必需	Ids in the same order as definitions.
values	(() => IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>) & (() => IterableIterator<Readonly<ModelTool<unknown, Output, any>>>)	必需	见类型定义及调用场景。
entries	() => IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined	必需	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>>	必需	Returns the definition or throws; use when the id is a required reference.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => Output	必需	Resolves one selection; throws when the capability is absent from this source.
select	(ids: readonly string[], context?: unknown) => ModelToolCatalog<Output>	必需	Explicit selection, optionally filtered against a host context.
withIntent	(context: unknown) => ModelToolCatalog<Output>	必需	Demand-facing active tools; no workflow node or invocation is implied.

成员目录

成员	用途
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.
resolve	Resolves one selection; throws when the capability is absent from this source.
select	Explicit selection, optionally filtered against a host context.
withIntent	Demand-facing active tools; no workflow node or invocation is implied.

成员详情

ids

Ids in the same order as definitions.

ModelToolCatalog.ids(): readonly string[]

Ids in the same order as definitions.

无调用参数。

返回： readonly string[]。

values

ModelToolCatalog.values(): IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>

无调用参数。

返回： IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>。

entries

ModelToolCatalog.entries(): IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>

无调用参数。

返回： IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>。

has

ModelToolCatalog.has(id: string): boolean

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

返回： boolean。

get

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

ModelToolCatalog.get(id: string): Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined

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

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

返回： Readonly<Readonly<ModelTool<unknown, Output, any>>> \| undefined。

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

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string	必需	只读。Unique id within its registry; never blank.
description	string	必需	只读。Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<unknown>	必需	只读。Schema describing the arguments; must be an object schema.
active	ToolCondition<any> | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<any> | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
resolve	(input: unknown, context: Readonly<{ stageId: string; }>) => Output	必需	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.

require

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

ModelToolCatalog.require(id: string): Readonly<Readonly<ModelTool<unknown, Output, any>>>

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

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

返回： Readonly<Readonly<ModelTool<unknown, Output, any>>>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Unique id within its registry; never blank.
description	string	必需	只读。Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<unknown>	必需	只读。Schema describing the arguments; must be an object schema.
active	ToolCondition<any> | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<any> | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
resolve	(input: unknown, context: Readonly<{ stageId: string; }>) => Output	必需	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.

resolve

Resolves one selection; throws when the capability is absent from this source.

ModelToolCatalog.resolve(selection: ModelSelection, context: Readonly<{ stageId: string; }>): Output

Resolves one selection; throws when the capability is absent from this source.

参数	类型	传递	说明
selection	ModelSelection	必需	—
context	Readonly<{ stageId: string; }>	必需	—

selection 的字段

字段	类型	必需	说明
input	Record<string, unknown>	必需	只读。Arguments exactly as produced by the model, before schema parsing.
call	{ id: string; name: string; argumentChars: number; } | undefined	可省略	只读。Native function call that carried the selection, when the provider used one.
toolId	string	必需	只读。Capability the selection resolved to.

context 的字段

字段	类型	必需	说明
stageId	string	必需	见类型定义及调用场景。

返回： Output。

等待后的值： Awaited<Output>。

select

Explicit selection, optionally filtered against a host context.

ModelToolCatalog.select(ids: readonly string[], context?: unknown): ModelToolCatalog<Output>

Explicit selection, optionally filtered against a host context.

参数	类型	传递	说明
ids	readonly string[]	必需	—
context	unknown	可省略	—

返回： ModelToolCatalog<Output>。

返回值结构

字段	类型	必需	说明
definitions	readonly Readonly<Readonly<ModelTool<unknown, Output, any>>>[]	必需	只读。Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	必需	Ids in the same order as definitions.
values	(() => IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>) & (() => IterableIterator<Readonly<ModelTool<unknown, Output, any>>>)	必需	见类型定义及调用场景。
entries	() => IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined	必需	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>>	必需	Returns the definition or throws; use when the id is a required reference.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => Output	必需	Resolves one selection; throws when the capability is absent from this source.
select	(ids: readonly string[], context?: unknown) => ModelToolCatalog<Output>	必需	Explicit selection, optionally filtered against a host context.
withIntent	(context: unknown) => ModelToolCatalog<Output>	必需	Demand-facing active tools; no workflow node or invocation is implied.

withIntent

Demand-facing active tools; no workflow node or invocation is implied.

ModelToolCatalog.withIntent(context: unknown): ModelToolCatalog<Output>

Demand-facing active tools; no workflow node or invocation is implied.

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

返回： ModelToolCatalog<Output>。

返回值结构

字段	类型	必需	说明
definitions	readonly Readonly<Readonly<ModelTool<unknown, Output, any>>>[]	必需	只读。Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	必需	Ids in the same order as definitions.
values	(() => IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>) & (() => IterableIterator<Readonly<ModelTool<unknown, Output, any>>>)	必需	见类型定义及调用场景。
entries	() => IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined	必需	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>>	必需	Returns the definition or throws; use when the id is a required reference.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => Output	必需	Resolves one selection; throws when the capability is absent from this source.
select	(ids: readonly string[], context?: unknown) => ModelToolCatalog<Output>	必需	Explicit selection, optionally filtered against a host context.
withIntent	(context: unknown) => ModelToolCatalog<Output>	必需	Demand-facing active tools; no workflow node or invocation is implied.

使用示例

• 模型传输与阶段投影：从 Tool 定义生成封存目录与阶段投影，原生函数和 JSON 适配复用同一 Tool 合同。
• Support：推荐用法的聚合入口：Support 聚合推荐的构造、策略与同源配置生成；Core 运行不依赖这个命名空间。

创建具名文本传输

入门 · Node.js

TypeScript

import { ModelRunner, Support } from '@jangts/agent-core';
const text = Support.createTextTransport({ id: 'brief', options: { temperature: 0.2 } });
const runner = new ModelRunner({ provider: { async *stream() { yield '服务正常'; } }, transports: [text] });
console.log((await runner.invoke({ input: '简答服务状态', transport: text })).value);

JavaScript

import { ModelRunner, Support } from '@jangts/agent-core';
const text = Support.createTextTransport({ id: 'brief', options: { temperature: 0.2 } });
const runner = new ModelRunner({ provider: { async *stream() { yield '服务正常'; } }, transports: [text] });
console.log((await runner.invoke({ input: '简答服务状态', transport: text })).value);

从同源 Tool 生成两个阶段的传输

配置 · 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 tools = Support.defineModelTools([
  { id: 'greet', description: '问候', inputSchema, resolve: () => 'greet' },
  { id: 'status', description: '状态查询', inputSchema, resolve: () => 'status' },
]);
const transport = Support.createStageModelTransport({ id: 'intent', tools,
  stages: [{ id: 'recognize', toolIds: ['greet', 'status'] }, { id: 'status-only', toolIds: ['status'] }],
});
console.log(transport.prepare('status-only').schemaChars);

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 tools = Support.defineModelTools([
    { id: 'greet', description: '问候', inputSchema, resolve: () => 'greet' },
    { id: 'status', description: '状态查询', inputSchema, resolve: () => 'status' },
]);
const transport = Support.createStageModelTransport({ id: 'intent', tools,
    stages: [{ id: 'recognize', toolIds: ['greet', 'status'] }, { id: 'status-only', toolIds: ['status'] }],
});
console.log(transport.prepare('status-only').schemaChars);

相关策略源码

• 阶段清单校验与动态源快照
• 显式模型交互适配器目录
• 正文与多工具调用的会话传输

相关定义

• ModelSelection
• ModelTool
• ModelToolSource
• ReadonlyCatalog
• RegisteredModelTool