ToolsOptions

KIT · interface · 类型合同

Construction options for a tool registry.

导入

TypeScript

import type { ToolsOptions } from '@jangts/agent-core/kits/tools';

JavaScript

/** @typedef {import('@jangts/agent-core/kits/tools').ToolsOptions} ToolsOptions */

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

定义

interface ToolsOptions<Types, Declaration>

继承或实现： ToolInvocationPorts<Types['context']>。

泛型参数

类型参数	约束	默认类型
Types	ToolRuntimeTypes	—
Declaration	ToolRegistration<Types>	—

字段结构

字段	类型	必需	说明
receiver	(() => Types["receiver"]) | undefined	可省略	只读。Supplies the receiver handed to the finalizer.
execution	ExecutionOptions | undefined	可省略	只读。Execution defaults (signal and diagnostics) applied to invocations.
errors	Pick<ToolRegistryPorts, "unavailable" | "errorCode"> | undefined	可省略	只读。Error factories shared by the registry.
registration	Policy<Declaration>	必需	只读。Registration policy for every tool.
invocationId	(decision: Types["decision"]) => string	必需	只读。Maps a decision to the invocation id that should handle it.
outputs	() => Iterable<readonly [string, ToolProtocol<Declaration>]>	必需	只读。Output protocols by id, used to validate invocation outputs.
modelOutputs	((context: Types["context"]) => Iterable<readonly [string, ToolProtocol<Declaration>]>) | undefined	可省略	只读。Optional context-dependent output protocols, exposed alongside outputs.
unavailableInvocation	((invocationId: string) => Error) | undefined	可省略	只读。Builds the error for an invocation id with no registered tool.
forbidden	(() => Error) | undefined	可省略	只读。Builds the error for a tool that is currently unavailable.
contextFragment	(tool: Declaration, field: ToolModelField<Types["placement"]>) => ContextFragment	必需	只读。Renders a model field into a context fragment.
goalIds	() => readonly string[]	必需	只读。Current goal ids, used to validate goalIds: 'all' availability.
logger	((context: Types["context"]) => import("../debug.js").SubFlowLogger | undefined) | undefined	可省略	只读。Explicit recorder selected for this invocation only.
diagnostics	((context: Types["context"]) => import("../diagnostics.js").DiagnosticContext | undefined) | undefined	可省略	只读。Diagnostic scope; omitted disables recording for this tool.
signal	((context: Types["context"]) => AbortSignal | undefined) | undefined	可省略	只读。Extra cancellation; must not replace the tool execution signal.
journal	((context: Types["context"]) => ToolJournal | undefined) | undefined	可省略	只读。Journal receiving begin/finish receipts.
checkpoint	((context: Types["context"]) => unknown) | undefined	可省略	只读。Extracts the domain checkpoint recorded with the receipt.
receipt	((context: Types["context"], checkpoint: unknown) => unknown) | undefined	可省略	只读。Builds the domain receipt from a checkpoint after execution.
receiptError	((error: unknown) => unknown) | undefined	可省略	只读。Converts an error into the receipt's replacement value.

成员目录

成员	用途
invocationId	Maps a decision to the invocation id that should handle it.
outputs	Output protocols by id, used to validate invocation outputs.
contextFragment	Renders a model field into a context fragment.
goalIds	Current goal ids, used to validate goalIds: 'all' availability.

成员详情

invocationId

Maps a decision to the invocation id that should handle it.

ToolsOptions.invocationId(decision: Types["decision"]): string

参数	类型	传递	说明
decision	Types["decision"]	必需	—

返回： string。

outputs

Output protocols by id, used to validate invocation outputs.

ToolsOptions.outputs(): Iterable<readonly [string, ToolProtocol<Declaration>]>

无调用参数。

返回： Iterable<readonly [string, ToolProtocol<Declaration>]>。

contextFragment

Renders a model field into a context fragment.

ToolsOptions.contextFragment(tool: Declaration, field: ToolModelField<Types["placement"]>): ContextFragment

参数	类型	传递	说明
tool	Declaration	必需	—
field	ToolModelField<Types["placement"]>	必需	—

field 的字段

字段	类型	必需	说明
lifetime	ContextLifetime | undefined	可省略	Validity window of the produced fragment.
maxChars	number | undefined	可省略	Character budget of the produced fragment.
placement	Types["placement"]	必需	Placement group this field belongs to; only that placement consumes it.
order	number	必需	Ordering key; lower values are emitted first within a placement.
key	string	必需	Key inside the merged model field record; later entries win.
value	unknown	必需	Field value, rendered by the registry's fragment factory.

返回： ContextFragment。

返回值结构

字段	类型	必需	说明
id	string	必需	Unique, stable id matching ^[a-z][a-zA-Z0-9:._-]*$; duplicates are rejected.
sourceId	string	必需	Owning source (module or registration) used to explain where the content came from.
trust	ContextTrust	必需	Producer trust level. user and tool content cannot become a system message.
lifetime	ContextLifetime	必需	Declared validity window of this content.
maxChars	number	必需	Hard upper bound in JSON characters; must be a positive safe integer.
role	"system" | "user"	必需	Message slot the fragment occupies when assembled.
value	string | Record<string, unknown>	必需	Rendered content. A system message accepts a string only, never a record.

goalIds

Current goal ids, used to validate goalIds: 'all' availability.

ToolsOptions.goalIds(): readonly string[]

无调用参数。

返回： readonly string[]。

使用示例

• Tools：App 工具生命周期与内容贡献：对已有复杂 App 工具统一登记工具调用、输出规则、上下文贡献和交付处理。

为已有 App 登记一个只读工具

入门 · Node.js

TypeScript

import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
  registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
  invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
  contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));

JavaScript

import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
    registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
    invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
    contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));

同一注册方式增加 App 规则和展示贡献

配置 · Node.js

active 影响真实工具可用性及描述；业务授权仍必须在实际调用边界核对服务端身份。

TypeScript

import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
  registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
  invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
  contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
  parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
  lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
}]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));

JavaScript

import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
    registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
    invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
    contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
        parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
        lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
    }]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));

相关策略源码

• 注册策略、生命周期绑定和内容投影

相关定义

• ContextFragment
• ExecutionOptions
• Policy
• ToolInvocationPorts
• ToolModelField
• ToolProtocol
• ToolRegistration
• ToolRegistryPorts
• ToolRuntimeTypes