ToolModelView

SUPPORT · interface · 类型合同

Model capability view of a tool catalog, retaining the host context type.

导入

TypeScript

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

JavaScript

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

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

定义

interface ToolModelView<App>

继承或实现： ModelToolRegistry。

泛型参数

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

字段结构

字段	类型	必需	说明
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	必需	见类型定义及调用场景。
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	必需	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	必需	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	必需	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	必需	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	必需	只读。Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	必需	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	必需	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	必需	Register several tools.
require	(id: string) => RegisteredModelTool	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => RegisteredModelTool | undefined	必需	见类型定义及调用场景。
seal	() => ToolModelView<App>	必需	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

成员目录

成员	用途
values	完整输入输出见下方重载。
resolve	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	Narrows the capability set to ids; throws for unregistered ids.
withIntent	Discovery retains this projection's ToolProposal result contract.
register	Register one capability.
ids	Registered ids in declaration order.
entries	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	Register several tools.
require	完整输入输出见下方重载。
has	完整输入输出见下方重载。
get	完整输入输出见下方重载。
seal	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

成员详情

values

ToolModelView.values(): IterableIterator<RegisteredModelTool<ToolProposal>>

无调用参数。

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

resolve

Resolves a model selection into a proposal; throws for unknown or invalid selections.

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

Resolves a model selection into a proposal; throws for unknown or invalid selections.

参数	类型	传递	说明
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	必需	见类型定义及调用场景。

返回： ToolProposal。

返回值结构

字段	类型	必需	说明
toolId	string	必需	只读。见类型定义及调用场景。
input	unknown	必需	只读。见类型定义及调用场景。

select

Narrows the capability set to ids; throws for unregistered ids.

ToolModelView.select(ids: readonly string[], context?: App): ToolModelView<App>

Narrows the capability set to ids; throws for unregistered ids.

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

返回： ToolModelView<App>。

返回值结构

字段	类型	必需	说明
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	必需	见类型定义及调用场景。
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	必需	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	必需	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	必需	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	必需	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	必需	只读。Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	必需	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	必需	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	必需	Register several tools.
require	(id: string) => RegisteredModelTool	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => RegisteredModelTool | undefined	必需	见类型定义及调用场景。
seal	() => ToolModelView<App>	必需	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

withIntent

Discovery retains this projection's ToolProposal result contract.

ToolModelView.withIntent(context: App): ToolModelView<App>

Discovery retains this projection's ToolProposal result contract.

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

返回： ToolModelView<App>。

返回值结构

字段	类型	必需	说明
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	必需	见类型定义及调用场景。
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	必需	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	必需	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	必需	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	必需	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	必需	只读。Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	必需	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	必需	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	必需	Register several tools.
require	(id: string) => RegisteredModelTool	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => RegisteredModelTool | undefined	必需	见类型定义及调用场景。
seal	() => ToolModelView<App>	必需	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

register

Register one capability.

ToolModelView.register<Result>(capability: ModelToolRegistration<Result>): ToolModelView<App>

Register one capability.

类型参数	约束	默认类型
Result	—	—

参数	类型	传递	说明
capability	ModelToolRegistration<Result>	必需	—

capability 的字段

字段	类型	必需	说明
id	string	必需	只读。Unique id within its registry; never blank.
description	string	必需	只读。Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<any>	必需	只读。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: any, context: Readonly<{ stageId: string; }>) => Result) | undefined	可省略	只读。见类型定义及调用场景。

返回： ToolModelView<App>。

返回值结构

字段	类型	必需	说明
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	必需	见类型定义及调用场景。
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	必需	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	必需	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	必需	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	必需	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	必需	只读。Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	必需	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	必需	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	必需	Register several tools.
require	(id: string) => RegisteredModelTool	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => RegisteredModelTool | undefined	必需	见类型定义及调用场景。
seal	() => ToolModelView<App>	必需	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

ids

Registered ids in declaration order.

ToolModelView.ids(): readonly string[]

Registered ids in declaration order.

无调用参数。

返回： readonly string[]。

entries

Live iterator over [id, definition] pairs; it reflects only entries added before sealing.

ToolModelView.entries(): IterableIterator<readonly [string, RegisteredModelTool]>

Live iterator over [id, definition] pairs; it reflects only entries added before sealing.

无调用参数。

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

registerAll

Register several tools.

ToolModelView.registerAll(definitions: Iterable<ModelToolRegistration>): ToolModelView<App>

Register several tools.

参数	类型	传递	说明
definitions	Iterable<ModelToolRegistration>	必需	—

返回： ToolModelView<App>。

返回值结构

字段	类型	必需	说明
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	必需	见类型定义及调用场景。
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	必需	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	必需	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	必需	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	必需	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	必需	只读。Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	必需	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	必需	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	必需	Register several tools.
require	(id: string) => RegisteredModelTool	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => RegisteredModelTool | undefined	必需	见类型定义及调用场景。
seal	() => ToolModelView<App>	必需	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

require

ToolModelView.require(id: string): RegisteredModelTool

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

返回： Readonly<ModelTool<unknown, unknown, 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; }>) => unknown	必需	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.

has

ToolModelView.has(id: string): boolean

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

返回： boolean。

get

ToolModelView.get(id: string): RegisteredModelTool | undefined

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

返回： Readonly<ModelTool<unknown, unknown, 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; }>) => unknown	必需	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.

seal

Close the registry to further registration.

Sealing is idempotent and does not affect existing entries.

ToolModelView.seal(): ToolModelView<App>

Close the registry to further registration.

Sealing is idempotent and does not affect existing entries.

无调用参数。

返回： ToolModelView<App>。

返回值结构

字段	类型	必需	说明
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	必需	见类型定义及调用场景。
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	必需	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	必需	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	必需	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	必需	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	必需	只读。Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	必需	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	必需	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	必需	Register several tools.
require	(id: string) => RegisteredModelTool	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => RegisteredModelTool | undefined	必需	见类型定义及调用场景。
seal	() => ToolModelView<App>	必需	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

使用示例

• 工具最佳实践：一份定义生成模型 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);

相关策略源码

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

相关定义

• ModelSelection
• ModelTool
• ModelToolRegistration
• ModelToolRegistry
• RegisteredModelTool
• ToolProposal