InteractionProtocolDefinition

KIT · type · 类型合同

Transfer envelope plus its registered command family; no change to HTTP or SSE framing.

导入

TypeScript

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

JavaScript

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

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

定义

类型： InteractionProtocolDefinition<Value, Result, Args, Id>

类型表达式

type InteractionProtocolDefinition<Value extends object, Result = Value, Args extends unknown[] = [], Id extends string = string> = Omit<
  Partial<CommandDefinition<Value, Result, Args>>,
  'discriminator' | 'modes' | 'ownedFields'
> &
  CommandCatalogOptions & {
    /** Field carrying the command id; also the canonical key in normalized output. */
    readonly commandField: string;
    /** Accepted only on input. Schema and normalized output always use commandField. */
    readonly commandAliases?: readonly string[];
    /** Rejection wording when a payload selects no command. */
    readonly selectionError?: ProtocolReason<Value, Args>;
    readonly commands: Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>;
  };

泛型参数

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

字段结构

字段	类型	必需	说明
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>>>	必需	只读。见类型定义及调用场景。

使用示例

• 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);

相关策略源码

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

相关定义

• CommandCatalogOptions
• CommandDefinition
• ProtocolCheck
• ProtocolField
• ProtocolReason