route

CORE · function · 运行时值

导入

TypeScript

import { route } from '@jangts/agent-core/engine';

JavaScript

import { route } from '@jangts/agent-core/engine';

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

定义

调用

route(target: string, id?: string): { id: string; targetNodeId: string; }

参数	类型	传递	说明
target	string	必需	—
id	string | undefined	可省略	—

返回： { id: string; targetNodeId: string; }。

返回值结构

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。

成员目录

成员	用途
to	完整输入输出见下方重载。
toIfEqual	完整输入输出见下方重载。
toIfEqualWith	完整输入输出见下方重载。
toIfNotEmpty	完整输入输出见下方重载。
toIfDefined	完整输入输出见下方重载。
toIf	完整输入输出见下方重载。
toIfError	完整输入输出见下方重载。
deliver	完整输入输出见下方重载。
deliverIfReady	完整输入输出见下方重载。
deliverWhenComplete	完整输入输出见下方重载。

成员详情

to

route.to(target: string, id?: string): { id: string; targetNodeId: string; }

参数	类型	传递	说明
target	string	必需	—
id	string | undefined	可省略	—

返回： { id: string; targetNodeId: string; }。

返回值结构

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。

toIfEqual

route.toIfEqual<Key extends PropertyKey, Value>(target: string, path: Key, value: Value, options?: RouteOptions): { id: string | undefined; conditionId: string | undefined; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; targetNodeId: string; description?: string; }

One conditional jump, using the same strict equality as a handwritten route.

A derived route id is only produced for symbol-free paths and primitive values, because those are the cases where String(value) is stable and unique enough to name the condition.

类型参数	约束	默认类型
Key	PropertyKey	—
Value	—	—

参数	类型	传递	说明
target	string	必需	—
path	Key	必需	—
value	Value	必需	—
options	RouteOptions | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { id: string \| undefined; conditionId: string \| undefined; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; targetNodeId: string; description?: string; }。

返回值结构

字段	类型	必需	说明
id	string | undefined	必需	见类型定义及调用场景。
conditionId	string | undefined	必需	见类型定义及调用场景。
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

toIfEqualWith

route.toIfEqualWith<Left extends PropertyKey, Right extends PropertyKey>(target: string, leftPath: Left, rightPath: Right, options?: RouteOptions): { id: string | undefined; conditionId: string | undefined; when: (state: Partial<Record<PathRoot<Left> | PathRoot<Right>, unknown>>) => boolean; targetNodeId: string; description?: string; }

Jump when two state paths resolve to strictly equal values.

No derived route id is produced for symbol paths, because a symbol cannot be embedded in a stable name.

类型参数	约束	默认类型
Left	PropertyKey	—
Right	PropertyKey	—

参数	类型	传递	说明
target	string	必需	—
leftPath	Left	必需	—
rightPath	Right	必需	—
options	RouteOptions | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { id: string \| undefined; conditionId: string \| undefined; when: (state: Partial<Record<PathRoot<Left> \| PathRoot<Right>, unknown>>) => boolean; targetNodeId: string; description?: string; }。

返回值结构

字段	类型	必需	说明
id	string | undefined	必需	见类型定义及调用场景。
conditionId	string | undefined	必需	见类型定义及调用场景。
when	(state: Partial<Record<PathRoot<Left> | PathRoot<Right>, unknown>>) => boolean	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

toIfNotEmpty

route.toIfNotEmpty<Key extends PropertyKey>(target: string, key: Key, options?: RouteOptions): { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }

Jump when a state array contains at least one entry.

A non-array value never matches, so a mistyped field cannot be treated as populated.

类型参数	约束	默认类型
Key	PropertyKey	—

参数	类型	传递	说明
target	string	必需	—
key	Key	必需	—
options	RouteOptions | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }。

返回值结构

字段	类型	必需	说明
conditionId	string	必需	见类型定义及调用场景。
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	必需	见类型定义及调用场景。
id	string	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

toIfDefined

route.toIfDefined<Key extends PropertyKey>(target: string, field: Key, options?: RouteOptions): { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }

Jump once a state field has a value.

null counts as present: only undefined means the field is still unset.

类型参数	约束	默认类型
Key	PropertyKey	—

参数	类型	传递	说明
target	string	必需	—
field	Key	必需	—
options	RouteOptions | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }。

返回值结构

字段	类型	必需	说明
conditionId	string	必需	见类型定义及调用场景。
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	必需	见类型定义及调用场景。
id	string	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

toIf

route.toIf<Key extends string>(target: Key, options?: RouteOptions): { when: (state: Partial<Record<Key, unknown>>) => boolean; conditionId: string; id: string; targetNodeId: string; description?: string; }

Jump to the node named by a truthy state field.

The same field is used as the condition and as the destination, which is the usual shape of a dispatcher that stored its own next node.

类型参数	约束	默认类型
Key	string	—

参数	类型	传递	说明
target	Key	必需	—
options	RouteOptions | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { when: (state: Partial<Record<Key, unknown>>) => boolean; conditionId: string; id: string; targetNodeId: string; description?: string; }。

返回值结构

字段	类型	必需	说明
when	(state: Partial<Record<Key, unknown>>) => boolean	必需	见类型定义及调用场景。
conditionId	string	必需	见类型定义及调用场景。
id	string	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

toIfError

route.toIfError<Key extends PropertyKey>(target: string, options: RouteOptions & { readonly errorKey: Key; }): ReturnType<typeof toIfDefined<Key>>

Route a recorded state error to its recovery node.

Defaults to the error field because that is the convention the engine relies on when reporting recoverable failures.

类型参数	约束	默认类型
Key	PropertyKey	—

参数	类型	传递	说明
target	string	必需	—
options	RouteOptions & { readonly errorKey: Key; }	必需	—

options 的字段

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().
errorKey	Key	必需	只读。见类型定义及调用场景。

返回： { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }。

返回值结构

字段	类型	必需	说明
conditionId	string	必需	见类型定义及调用场景。
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	必需	见类型定义及调用场景。
id	string	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

route.toIfError(target: string, options?: RouteOptions & { readonly errorKey?: undefined; }): ReturnType<typeof toIfDefined<"error">>

参数	类型	传递	说明
target	string	必需	—
options	(RouteOptions & { readonly errorKey?: undefined; }) | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().
errorKey	undefined	可省略	只读。见类型定义及调用场景。

返回： { conditionId: string; when: (state: Partial<Record<"error", unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }。

返回值结构

字段	类型	必需	说明
conditionId	string	必需	见类型定义及调用场景。
when	(state: Partial<Record<"error", unknown>>) => boolean	必需	见类型定义及调用场景。
id	string	必需	见类型定义及调用场景。
targetNodeId	string	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

deliver

route.deliver<Key extends PropertyKey>(field: Key, options?: Omit<RouteOptions, "conditionId">): { id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }

At a terminal node, the result must already exist.

Completing reads the field with requireWorkflowValue, so a node that forgot to produce its result fails instead of returning undefined.

类型参数	约束	默认类型
Key	PropertyKey	—

参数	类型	传递	说明
field	Key	必需	—
options	Omit<RouteOptions, "conditionId"> | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }。

返回值结构

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
complete	<State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

deliverIfReady

route.deliverIfReady<Key extends PropertyKey>(field: Key, options?: RouteOptions): { conditionId: string; when: (state: Partial<Record<Key, unknown>>) => boolean; id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }

Deliver an available result, or let the next route decide.

Unlike deliver, this route carries a condition so a following route still has a chance to match when the field is still unset.

类型参数	约束	默认类型
Key	PropertyKey	—

参数	类型	传递	说明
field	Key	必需	—
options	RouteOptions | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { conditionId: string; when: (state: Partial<Record<Key, unknown>>) => boolean; id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }。

返回值结构

字段	类型	必需	说明
conditionId	string	必需	见类型定义及调用场景。
when	(state: Partial<Record<Key, unknown>>) => boolean	必需	见类型定义及调用场景。
id	string	必需	见类型定义及调用场景。
complete	<State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

deliverWhenComplete

route.deliverWhenComplete<Key extends PropertyKey>(field: Key, options?: RouteOptions): { id: string; conditionId: string; when: (state: Partial<Record<Key, StepOutcome<unknown>>>) => boolean; complete<Value>(state: Partial<Record<Key, StepOutcome<Value>>>): Value; description?: string; }

Apply the shared continue/complete outcome contract.

The field holds a StepOutcome; only the complete variant ends the workflow, and the completion asserts the variant instead of trusting the condition.

类型参数	约束	默认类型
Key	PropertyKey	—

参数	类型	传递	说明
field	Key	必需	—
options	RouteOptions | undefined	可省略	—

参数 options的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string | undefined	可省略	只读。Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	可省略	只读。Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

返回： { id: string; conditionId: string; when: (state: Partial<Record<Key, StepOutcome<unknown>>>) => boolean; complete<Value>(state: Partial<Record<Key, StepOutcome<Value>>>): Value; description?: string; }。

返回值结构

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
conditionId	string	必需	见类型定义及调用场景。
when	(state: Partial<Record<Key, StepOutcome<unknown>>>) => boolean	必需	见类型定义及调用场景。
complete	<Value>(state: Partial<Record<Key, StepOutcome<Value>>>) => Value	必需	见类型定义及调用场景。
description	string | undefined	可省略	只读。Human-readable description surfaced by describe().

使用示例

• route：生成完整配置，沉淀常用判断：route 函数组生成普通 WorkflowRoute 配置；手写对象与生成配置遵守同一个合同。

最小跳转与结束

入门 · Node.js

TypeScript

import { route } from '@jangts/agent-core/engine';
const jump = route('reply');
const sameJump = route.to('reply');
const finish = route.deliver('answer');
console.log(jump, sameJump, finish);

JavaScript

import { route } from '@jangts/agent-core/engine';
const jump = route('reply');
const sameJump = route.to('reply');
const finish = route.deliver('answer');
console.log(jump, sameJump, finish);

同一业务的常用分支

配置 · Node.js

TypeScript

import { route } from '@jangts/agent-core/engine';
const reviewRoutes = [
  route.toIfError('failure'),
  route.toIf('recovered'),
  route.toIfNotEmpty('candidate', 'candidates'),
  route.toIfDefined('reply', 'answer'),
  route.toIfEqual('status', 'intent.id', 'status'),
  route.toIfEqualWith('reuse', 'cache.0.id', 'request.id'),
  route.to('fallback'),
];
const completionRoutes = [route.deliverIfReady('answer'), route.to('retry')];
const outcomeRoutes = [route.deliverWhenComplete('outcome'), route.to('retry')];
console.log(reviewRoutes, completionRoutes, outcomeRoutes);

JavaScript

import { route } from '@jangts/agent-core/engine';
const reviewRoutes = [
    route.toIfError('failure'),
    route.toIf('recovered'),
    route.toIfNotEmpty('candidate', 'candidates'),
    route.toIfDefined('reply', 'answer'),
    route.toIfEqual('status', 'intent.id', 'status'),
    route.toIfEqualWith('reuse', 'cache.0.id', 'request.id'),
    route.to('fallback'),
];
const completionRoutes = [route.deliverIfReady('answer'), route.to('retry')];
const outcomeRoutes = [route.deliverWhenComplete('outcome'), route.to('retry')];
console.log(reviewRoutes, completionRoutes, outcomeRoutes);

按业务需要覆盖身份，手写对象也支持占位符

扩展 · Node.js

conditionId 不承担授权。它帮助日志解释命中了哪次判断。

TypeScript

import { defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { answer?: string; reviewError?: string };
const workflow = defineWorkflow<State, string>({ id: 'review', nodes: [
  { id: 'check', description: '检查既有结果', startsRound: true, routes: [
    route.toIfError('failure', { errorKey: 'reviewError', id: 'review-error' }),
    { id: 'ready', conditionId: '{nid}.{rid}', when: state => state.answer !== undefined,
      complete: state => state.answer! },
    route.to('failure'),
  ] },
  { id: 'failure', description: '给出当前缺失信息',
    run: () => ({ answer: '当前没有可交付结果' }), routes: [route.deliver('answer')] },
] });
console.log(workflow.describe());

JavaScript

import { defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'review', nodes: [
        { id: 'check', description: '检查既有结果', startsRound: true, routes: [
                route.toIfError('failure', { errorKey: 'reviewError', id: 'review-error' }),
                { id: 'ready', conditionId: '{nid}.{rid}', when: state => state.answer !== undefined,
                    complete: state => state.answer },
                route.to('failure'),
            ] },
        { id: 'failure', description: '给出当前缺失信息',
            run: () => ({ answer: '当前没有可交付结果' }), routes: [route.deliver('answer')] },
    ] });
console.log(workflow.describe());

相关策略源码

• 各 route 生成器的默认规则与判断过程