Interaction：声明命令并绑定本地处理器
命令的字段、目的、选择器、检查和 handler 来自同一声明，模型不能添加可执行处理器。
defineCommand 编译单命令；compileCommands/CommandCatalog 编译一组；Interaction.define（即 defineInteractionProtocol）再提供 commandField 与命令选择。receive 返回 {id,result}，parse 只返回 result；dispatch 根据已校验的命令 ID 调用已绑定 handler，不按 format 返回值重新分发。
字段声明生成模型 Schema，并检查字段存在、未知字段、选择器、ownedFields、checks 和 refine。字段的 jsonSchema 不等于自动执行完整 JSON Schema 类型校验；类型和业务约束应在 checks/refine 或自己的 SchemaAdapter 中实现。默认 additionalProperties=false、optionalPresence='own'。occur 为遇到即拒绝；when 只决定启用此检查。
category 只能是 query/action/presentation/input/receipt，是命令用途，不是权限等级或执行成功的声明。HTTP、SSE、实际工具执行与服务端鉴权不属于这个协议编译器。
由简到繁的同业务示例
先定义一种说明命令并校验
入门 · Node.js
ts
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);js
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
ts
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);js
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。此例没有执行任何工具。
ts
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());js
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());