InteractionProtocol

KIT · class · 运行时值

Web/AI payload family. HTTP/SSE framing and actual command execution remain separate ports.

Every command registered here gets the envelope's discriminator forced to its own id, so a payload cannot claim one command while carrying another command's data.

导入

TypeScript

import { Interaction } from '@jangts/agent-core/kits/interaction';

JavaScript

import { Interaction } from '@jangts/agent-core/kits/interaction';

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

定义

class InteractionProtocol<Value, Result, Args, Id>

泛型参数

类型参数	约束	默认类型
Value	object	Record<string, unknown>
Result	—	Value
Args	unknown[]	[]
Id	string	string

构造函数

new InteractionProtocol<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = [], Id extends string = string>(definition: InteractionProtocolDefinition<Value, Result, Args, Id>): InteractionProtocol<Value, Result, Args, Id>

参数	类型	传递	说明
definition	InteractionProtocolDefinition<Value, Result, Args, Id>	必需	—

definition 的字段

字段	类型	必需	说明
description	string | undefined	可省略	只读。见类型定义及调用场景。
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to rejections from this command. Diagnostic tags attached to every rejection from this catalog.
error	ProtocolReason<Value, Args> | undefined	可省略	只读。Rejection wording for the command as a whole.
fields	readonly string[] | Readonly<Record<string, ProtocolField>> | undefined	可省略	只读。Field declarations by name, or an ordered list of field names.
version	number | undefined	可省略	只读。Protocol version, used to reject incompatible registrations.
format	((value: Value, ...args: Args) => Result) | undefined	可省略	只读。Formats the validated value into the command result.
category	InteractionCategory | undefined	可省略	只读。Declared purpose; validated against the frozen category list.
terminal	boolean | undefined	可省略	只读。Marks a command that ends the interaction.
additionalProperties	boolean | undefined	可省略	只读。Whether fields outside the declaration are rejected; defaults to the compiler policy.
optionalPresence	"own" | "defined" | undefined	可省略	只读。'defined' rejects an explicitly undefined optional property; 'own' preserves its presence.
checks	readonly ProtocolCheck<Value, Args>[] | undefined	可省略	只读。Declarative rejection rules, evaluated in order after the structural checks.
refine	((value: Value, ...args: Args) => void) | undefined	可省略	只读。Domain checks/bindings only; invoked after structural and declarative checks.
modeField	string | undefined	可省略	只读。Field carrying the mode selector, when modes are used.
unknownError	string | Error | undefined	可省略	只读。Rejection wording for an unknown command selector.
modeError	string | Error | undefined	可省略	只读。Rejection wording for a command used outside its declared modes.
ownershipError	string | Error | undefined	可省略	只读。Rejection wording for a model-supplied owned field.
commandField	string	必需	只读。Field carrying the command id; also the canonical key in normalized output.
commandAliases	readonly string[] | undefined	可省略	只读。Accepted only on input. Schema and normalized output always use commandField.
selectionError	ProtocolReason<Value, Args> | undefined	可省略	只读。Rejection wording when a payload selects no command.
commands	Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>	必需	只读。见类型定义及调用场景。

返回： InteractionProtocol<Value, Result, Args, Id>。

静态属性

字段	类型	必需	说明
categories	readonly InteractionCategory[]	必需	只读。见类型定义及调用场景。

实例属性

字段	类型	必需	说明
commandField	string	必需	只读。Field carrying the command id in a payload.
commandSelectors	readonly string[]	必需	只读。Accepted selector names: the command field first, then any declared aliases.
commands	CommandCatalog<Value, Result, Args, Id>	必需	只读。Sealed catalog of the compiled commands.
modelJsonSchema	Record<string, unknown>	必需	只读。JSON schema for the model, expressed as a union of the per-command schemas.
inputJsonSchema	Record<string, unknown>	必需	只读。Strict JSON schema for transport input, expressed as a union of per-command schemas.

成员目录

成员	用途
define	静态。完整输入输出见下方重载。
Commands	静态。完整输入输出见下方重载。
defineCommand	静态。完整输入输出见下方重载。
commandSchema	静态。完整输入输出见下方重载。
bind	静态。完整输入输出见下方重载。
parse	Parse a payload and return only the result.
receive	Retain the selected command id separately from a formatter's output.

成员详情

define

静态成员。

InteractionProtocol.define<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = [], Id extends string = string>(definition: InteractionProtocolDefinition<Value, Result, Args, Id>): InteractionProtocol<Value, Result, Args, Id>

Construct a protocol from one definition.

类型参数	约束	默认类型
Value	object	Record<string, unknown>
Result	—	Value
Args	unknown[]	[]
Id	string	string

参数	类型	传递	说明
definition	InteractionProtocolDefinition<Value, Result, Args, Id>	必需	—

definition 的字段

字段	类型	必需	说明
description	string | undefined	可省略	只读。见类型定义及调用场景。
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to rejections from this command. Diagnostic tags attached to every rejection from this catalog.
error	ProtocolReason<Value, Args> | undefined	可省略	只读。Rejection wording for the command as a whole.
fields	readonly string[] | Readonly<Record<string, ProtocolField>> | undefined	可省略	只读。Field declarations by name, or an ordered list of field names.
version	number | undefined	可省略	只读。Protocol version, used to reject incompatible registrations.
format	((value: Value, ...args: Args) => Result) | undefined	可省略	只读。Formats the validated value into the command result.
category	InteractionCategory | undefined	可省略	只读。Declared purpose; validated against the frozen category list.
terminal	boolean | undefined	可省略	只读。Marks a command that ends the interaction.
additionalProperties	boolean | undefined	可省略	只读。Whether fields outside the declaration are rejected; defaults to the compiler policy.
optionalPresence	"own" | "defined" | undefined	可省略	只读。'defined' rejects an explicitly undefined optional property; 'own' preserves its presence.
checks	readonly ProtocolCheck<Value, Args>[] | undefined	可省略	只读。Declarative rejection rules, evaluated in order after the structural checks.
refine	((value: Value, ...args: Args) => void) | undefined	可省略	只读。Domain checks/bindings only; invoked after structural and declarative checks.
modeField	string | undefined	可省略	只读。Field carrying the mode selector, when modes are used.
unknownError	string | Error | undefined	可省略	只读。Rejection wording for an unknown command selector.
modeError	string | Error | undefined	可省略	只读。Rejection wording for a command used outside its declared modes.
ownershipError	string | Error | undefined	可省略	只读。Rejection wording for a model-supplied owned field.
commandField	string	必需	只读。Field carrying the command id; also the canonical key in normalized output.
commandAliases	readonly string[] | undefined	可省略	只读。Accepted only on input. Schema and normalized output always use commandField.
selectionError	ProtocolReason<Value, Args> | undefined	可省略	只读。Rejection wording when a payload selects no command.
commands	Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>	必需	只读。见类型定义及调用场景。

返回： InteractionProtocol<Value, Result, Args, Id>。

Commands

静态成员。

new InteractionProtocol.Commands<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = [], Id extends string = string>(definitions: Iterable<readonly [Id, Command<Value, Result, Args>]>, options?: CommandCatalogOptions): CommandCatalog<Value, Result, Args, Id>

参数	类型	传递	说明
definitions	Iterable<readonly [Id, Command<Value, Result, Args>]>	必需	—
options	CommandCatalogOptions	可省略	—

options 的字段

字段	类型	必需	说明
modeField	string | undefined	可省略	只读。Field carrying the mode selector, when modes are used.
unknownError	string | Error | undefined	可省略	只读。Rejection wording for an unknown command selector.
modeError	string | Error | undefined	可省略	只读。Rejection wording for a command used outside its declared modes.
ownershipError	string | Error | undefined	可省略	只读。Rejection wording for a model-supplied owned field.
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to every rejection from this catalog.

返回： CommandCatalog<Value, Result, Args, Id>。

defineCommand

静态成员。

InteractionProtocol.defineCommand<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = []>(definition: CommandDefinition<Value, Result, Args>): Command<Value, Result, Args>

Compile declarations once. Parsing is synchronous and never executes a registered tool.

Two schemas are produced from one declaration: modelJsonSchema marks only fields the model must fill, while inputJsonSchema marks every required field. A discriminator, when present, is prepended as a required constant field.

类型参数	约束	默认类型
Value	object	Record<string, unknown>
Result	—	Value
Args	unknown[]	[]

参数	类型	传递	说明
definition	CommandDefinition<Value, Result, Args>	必需	—

definition 的字段

字段	类型	必需	说明
category	InteractionCategory | undefined	可省略	只读。Declared purpose; validated against the frozen category list.
version	number | undefined	可省略	只读。Protocol version, used to reject incompatible registrations.
description	string | undefined	可省略	只读。见类型定义及调用场景。
terminal	boolean | undefined	可省略	只读。Marks a command that ends the interaction.
discriminator	{ readonly field: string; readonly value: string; } | undefined	可省略	只读。Constant field identifying the command; its value is forced to the command id.
fields	readonly string[] | Readonly<Record<string, ProtocolField>>	必需	只读。Field declarations by name, or an ordered list of field names.
ownedFields	readonly string[] | undefined	可省略	只读。Fields the program writes; may name fields not declared in fields.
additionalProperties	boolean | undefined	可省略	只读。Whether fields outside the declaration are rejected; defaults to the compiler policy.
optionalPresence	"own" | "defined" | undefined	可省略	只读。'defined' rejects an explicitly undefined optional property; 'own' preserves its presence.
modes	readonly string[] | undefined	可省略	只读。App-declared modes in which the command is available.
error	ProtocolReason<Value, Args> | undefined	可省略	只读。Rejection wording for the command as a whole.
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to rejections from this command.
checks	readonly ProtocolCheck<Value, Args>[] | undefined	可省略	只读。Declarative rejection rules, evaluated in order after the structural checks.
refine	((value: Value, ...args: Args) => void) | undefined	可省略	只读。Domain checks/bindings only; invoked after structural and declarative checks.
format	((value: Value, ...args: Args) => Result) | undefined	可省略	只读。Formats the validated value into the command result.

返回： Command<Value, Result, Args>。

返回值结构

字段	类型	必需	说明
category	InteractionCategory | undefined	可省略	只读。见类型定义及调用场景。
version	number | undefined	可省略	只读。见类型定义及调用场景。
description	string | undefined	可省略	只读。见类型定义及调用场景。
terminal	boolean | undefined	可省略	只读。见类型定义及调用场景。
fieldSchemas	Record<string, unknown>	必需	只读。Per-field schemas, including the forced discriminator field.
modelJsonSchema	Record<string, unknown>	必需	只读。Schema for model output; only modelRequired fields are required here.
inputJsonSchema	Record<string, unknown>	必需	只读。Schema for runtime input; every required field is required here.
modes	readonly string[] | undefined	可省略	只读。见类型定义及调用场景。
ownedFields	readonly string[]	必需	只读。Field names the program owns; the model must not supply them.
keys	(value: Record<string, unknown>) => string[]	必需	Selector values carried by value, used to resolve the command before parsing.
assert	(value: Value, ...args: Args) => void	必需	Validates without formatting; throws on the first failed check.
parse	(value: Value, ...args: Args) => Result	必需	Validates and returns the formatted result.

commandSchema

静态成员。

InteractionProtocol.commandSchema(id: string, protocol: ProtocolShape, discriminator?: string): Record<string, unknown>

Build a JSON schema for one command id.

Prefer compiled schemas; retain the existing open-schema contract for dynamic host protocols. A protocol without fieldSchemas falls back to an open object that only pins the discriminator, which keeps legacy hosts working without weakening compiled ones.

参数	类型	传递	说明
id	string	必需	—
protocol	ProtocolShape	必需	—
discriminator	string	可省略	—

protocol 的字段

字段	类型	必需	说明
modelJsonSchema	Record<string, unknown> | undefined	可省略	只读。Optional schema for model output.
inputJsonSchema	Record<string, unknown> | undefined	可省略	只读。Optional schema for runtime input.
fieldSchemas	Record<string, unknown> | undefined	可省略	只读。Optional per-field schemas.
keys	(value: Record<string, unknown>) => string[]	必需	Selector values carried by value.

返回： Record<string, unknown>。

bind

静态成员。

InteractionProtocol.bind<Value extends object, Parsed, Args extends unknown[], Id extends string, Context, Output>(protocol: { readonly commands: Pick<InteractionProtocol<Value, Parsed, Args, Id>["commands"], "manifest">; receive(value: Value, ...args: Args): { id: Id; result: Parsed; }; }, handlers: InteractionHandlers<Id, Parsed, Context, Output>): Readonly<{ catalog: readonly Readonly<{ id: string; category: InteractionCategory | undefined; description: string | undefined; terminal: boolean | undefined; modes: readonly string[] | undefined; }>[]; dispatch(value: Value, context: Context, ...args: Args): Output; }>

Bind every registered transfer command to a local handler. Models cannot add handlers.

类型参数	约束	默认类型
Value	object	—
Parsed	—	—
Args	unknown[]	—
Id	string	—
Context	—	—
Output	—	—

参数	类型	传递	说明
protocol	{ readonly commands: Pick<InteractionProtocol<Value, Parsed, Args, Id>["commands"], "manifest">; receive(value: Value, ...args: Args): { id: Id; result: Parsed; }; }	必需	—
handlers	Readonly<Record<Id, (value: Parsed, context: Context) => Output>>	必需	—

protocol 的字段

字段	类型	必需	说明
commands	Pick<CommandCatalog<Value, Parsed, Args, Id>, "manifest">	必需	只读。见类型定义及调用场景。
receive	(value: Value, ...args: Args) => { id: Id; result: Parsed; }	必需	见类型定义及调用场景。

返回： Readonly<{ catalog: readonly Readonly<{ id: string; category: InteractionCategory \| undefined; description: string \| undefined; terminal: boolean \| undefined; modes: readonly string[] \| undefined; }>[]; dispatch(value: Value, context: Context, ...args: Args): Output; }>。

返回值结构

字段	类型	必需	说明
catalog	readonly Readonly<{ id: string; category: InteractionCategory | undefined; description: string | undefined; terminal: boolean | undefined; modes: readonly string[] | undefined; }>[]	必需	见类型定义及调用场景。
dispatch	(value: Value, context: Context, ...args: Args) => Output	必需	见类型定义及调用场景。

parse

实例方法。

Parse a payload and return only the result.

parse(value: Value, ...args: Args): Result

Parse a payload and return only the result.

参数	类型	传递	说明
value	Value	必需	—
args	Args	剩余参数	—

返回： Result。

等待后的值： Awaited<Result>。

receive

实例方法。

Retain the selected command id separately from a formatter's output.

receive(value: Value, ...args: Args): { id: Id; result: Result; }

Retain the selected command id separately from a formatter's output.

参数	类型	传递	说明
value	Value	必需	—
args	Args	剩余参数	—

返回： { id: Id; result: Result; }。

返回值结构

字段	类型	必需	说明
id	Id	必需	见类型定义及调用场景。
result	Result	必需	见类型定义及调用场景。

使用示例

• Interaction：声明命令并绑定本地处理器：命令的字段、目的、选择器、检查和 handler 来自同一声明，模型不能添加可执行处理器。

先定义一种说明命令并校验

入门 · Node.js

TypeScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
  commandField: 'type', commands: {
    reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } },
      checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
  },
});
console.log(protocol.receive({ type: 'reply', text: '普通对象也能实现接口。' }));
console.log(protocol.modelJsonSchema);

JavaScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
    commandField: 'type', commands: {
        reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } },
            checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
    },
});
console.log(protocol.receive({ type: 'reply', text: '普通对象也能实现接口。' }));
console.log(protocol.modelJsonSchema);

保留同一协议，增加完整 handler 绑定

配置 · Node.js

TypeScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
  commandField: 'type', commands: {
    reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } }, checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
    unavailable: { category: 'receipt', description: '说明资料不可用', fields: {} },
  },
});
const dispatcher = Interaction.bind(protocol, {
  reply: value => '说明：' + String(value.text),
  unavailable: () => '资料暂不可用',
});
console.log(dispatcher.dispatch({ type: 'reply', text: '普通对象也能实现接口。' }, undefined));
console.log(dispatcher.catalog);

JavaScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
    commandField: 'type', commands: {
        reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } }, checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
        unavailable: { category: 'receipt', description: '说明资料不可用', fields: {} },
    },
});
const dispatcher = Interaction.bind(protocol, {
    reply: value => '说明：' + String(value.text),
    unavailable: () => '资料暂不可用',
});
console.log(dispatcher.dispatch({ type: 'reply', text: '普通对象也能实现接口。' }, undefined));
console.log(dispatcher.catalog);

直接复用单命令与批量编译入口

扩展 · Node.js

使用 Interaction 时选择器由它生成；自行用 defineCommand 时也可以显式提供 discriminator。此例没有执行任何工具。

TypeScript

import { defineCommand, compileCommands, commandSchema, CommandCatalog } from '@jangts/agent-core/kits/interaction';
const reply = defineCommand({ fields: { text: { required: true } }, checks: [{ occur: value => typeof value.text !== 'string', error: '需要文本' }] });
console.log(reply.parse({ text: '接口说明' }));
const compiled = compileCommands({ reply: { fields: { text: { required: true } } } });
const commands = new CommandCatalog(Object.entries(compiled));
console.log(commandSchema('reply', commands.require('reply')), commands.manifest());

JavaScript

import { defineCommand, compileCommands, commandSchema, CommandCatalog } from '@jangts/agent-core/kits/interaction';
const reply = defineCommand({ fields: { text: { required: true } }, checks: [{ occur: value => typeof value.text !== 'string', error: '需要文本' }] });
console.log(reply.parse({ text: '接口说明' }));
const compiled = compileCommands({ reply: { fields: { text: { required: true } } } });
const commands = new CommandCatalog(Object.entries(compiled));
console.log(commandSchema('reply', commands.require('reply')), commands.manifest());

相关策略源码

• 字段、检查与模型 Schema
• 选择器与命令接收
• 按已校验命令绑定本地 handler

相关定义

• CommandCatalog
• CommandCatalogOptions
• CommandDefinition
• defineInteractionProtocol
• InteractionProtocolDefinition