defineCandidateSelection

KIT · function · 运行时值

Compile an alternative-proposal envelope contract.

Alternative proposals are bounded and shallow; accepting a task closes this capability. A value that is not an object, or that does not carry the candidate field, is treated as a single implicit candidate and returned as-is. Once the envelope is present it must contain only that field, and its array must hold between minCandidates (default 1) and maxCandidates distinct candidate objects that do not themselves repeat the field.

导入

TypeScript

import { defineCandidateSelection } from '@jangts/agent-core/kits/candidates';

JavaScript

import { defineCandidateSelection } from '@jangts/agent-core/kits/candidates';

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

定义

调用

defineCandidateSelection(definition: CandidateSelectionDefinition): Readonly<{ field: string; minCandidates: number; maxCandidates: number; parse: ({ value, allowed }: { value: unknown; allowed: boolean; }) => unknown[]; }>

Compile an alternative-proposal envelope contract.

Alternative proposals are bounded and shallow; accepting a task closes this capability. A value that is not an object, or that does not carry the candidate field, is treated as a single implicit candidate and returned as-is. Once the envelope is present it must contain only that field, and its array must hold between minCandidates (default 1) and maxCandidates distinct candidate objects that do not themselves repeat the field.

参数	类型	传递	说明
definition	CandidateSelectionDefinition	必需	—

definition 的字段

字段	类型	必需	说明
field	string	必需	只读。Reply field that carries the alternatives.
minCandidates	number | undefined	可省略	只读。Minimum number of distinct candidates once the envelope is present; defaults to 1.
maxCandidates	number	必需	只读。Maximum number of candidates; must be a safe integer not below the minimum.
error	BreakReason | undefined	可省略	只读。Rejection wording, either fixed, a pre-built error or a lazy factory.
tags	readonly string[] | undefined	可省略	只读。Diagnostic tags attached to every rejection from this contract.

返回： Readonly<{ field: string; minCandidates: number; maxCandidates: number; parse: ({ value, allowed }: { value: unknown; allowed: boolean; }) => unknown[]; }>。

返回值结构

字段	类型	必需	说明
field	string	必需	见类型定义及调用场景。
minCandidates	number	必需	见类型定义及调用场景。
maxCandidates	number	必需	见类型定义及调用场景。
parse	({ value, allowed }: { value: unknown; allowed: boolean; }) => unknown[]	必需	见类型定义及调用场景。

使用示例

• Candidates：有界候选封套：同一结果可以是单项提议或候选清单；候选权限与数量由应用控制。

接受单一提议或最多三个候选

入门 · Node.js

TypeScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', maxCandidates: 3 });
console.log(selection.parse({ value: { action: 'read' }, allowed: true }));
console.log(selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: true }));

JavaScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', maxCandidates: 3 });
console.log(selection.parse({ value: { action: 'read' }, allowed: true }));
console.log(selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: true }));

相同 parse 增加下界和应用阶段约束

配置 · Node.js

TypeScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', minCandidates: 2, maxCandidates: 3, error: '当前阶段不接受这份候选' });
const taskAccepted = true;
try {
  selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: !taskAccepted });
} catch (error) { console.log((error as Error).message); }

JavaScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', minCandidates: 2, maxCandidates: 3, error: '当前阶段不接受这份候选' });
const taskAccepted = true;
try {
    selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: !taskAccepted });
}
catch (error) {
    console.log(error.message);
}

相关策略源码

• 候选封套、数量与浅层限制

相关定义

• CandidateSelectionDefinition