AgentFamily

KIT · interface · 类型合同

Compiled family API. Every mutation returns the record after the write.

导入

TypeScript

import type { AgentFamily } from '@jangts/agent-core/kits/family';

JavaScript

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

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

定义

interface AgentFamily<State, App>

泛型参数

类型参数	约束	默认类型
State	—	—
App	—	—

字段结构

字段	类型	必需	说明
read	(id: string, context: OperationContext<App>) => Promise<FamilyRecord<State>>	必需	Reads the record; throws when the family does not exist or has expired.
create	(request: { id: string; branch: AgentBranch; state: State; }, context: OperationContext<App>) => Promise<FamilyRecord<State>>	必需	Creates the first version and makes it active.
fork	(request: { id: string; revision: number; parentId: string; branch: AgentBranch; state: State; }, context: OperationContext<App>) => Promise<FamilyRecord<State>>	必需	Appends a version forked from parentId; the active pointer does not change.
merge	(request: { id: string; revision: number; baseId: string; targetId: string; sourceId: string; }, context: OperationContext<App>) => Promise<{ saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }>	必需	Merges source into target; saved is false when the merge reported conflicts.
promote	(request: { id: string; revision: number; candidateId: string; expectedActiveId: string; }, context: OperationContext<App>) => Promise<FamilyRecord<State>>	必需	Makes candidateId active; fails when the active version changed since expectedActiveId.

成员目录

成员	用途
read	Reads the record; throws when the family does not exist or has expired.
create	Creates the first version and makes it active.
fork	Appends a version forked from parentId; the active pointer does not change.
merge	Merges source into target; saved is false when the merge reported conflicts.
promote	Makes candidateId active; fails when the active version changed since expectedActiveId.

成员详情

read

Reads the record; throws when the family does not exist or has expired.

AgentFamily.read(id: string, context: OperationContext<App>): Promise<FamilyRecord<State>>

Reads the record; throws when the family does not exist or has expired.

参数	类型	传递	说明
id	string	必需	—
context	OperationContext<App>	必需	—

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： Promise<FamilyRecord<State>>。

等待后的值： FamilyRecord<State>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Family id; also the store key.
revision	number	必需	只读。Optimistic concurrency token; every accepted mutation increments it by one.
activeId	string	必需	只读。Id of the active version; promotion moves this pointer.
expiresAtMs	number	必需	只读。Instant after which the record is no longer retained, in epoch milliseconds.
versions	readonly FamilyVersion<State>[]	必需	只读。Versions in creation order; bounded by maxVersions when configured.

create

Creates the first version and makes it active.

AgentFamily.create(request: { id: string; branch: AgentBranch; state: State; }, context: OperationContext<App>): Promise<FamilyRecord<State>>

Creates the first version and makes it active.

参数	类型	传递	说明
request	{ id: string; branch: AgentBranch; state: State; }	必需	—
context	OperationContext<App>	必需	—

request 的字段

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
branch	AgentBranch	必需	见类型定义及调用场景。
state	State	必需	见类型定义及调用场景。

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： Promise<FamilyRecord<State>>。

等待后的值： FamilyRecord<State>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Family id; also the store key.
revision	number	必需	只读。Optimistic concurrency token; every accepted mutation increments it by one.
activeId	string	必需	只读。Id of the active version; promotion moves this pointer.
expiresAtMs	number	必需	只读。Instant after which the record is no longer retained, in epoch milliseconds.
versions	readonly FamilyVersion<State>[]	必需	只读。Versions in creation order; bounded by maxVersions when configured.

fork

Appends a version forked from parentId; the active pointer does not change.

AgentFamily.fork(request: { id: string; revision: number; parentId: string; branch: AgentBranch; state: State; }, context: OperationContext<App>): Promise<FamilyRecord<State>>

Appends a version forked from parentId; the active pointer does not change.

参数	类型	传递	说明
request	{ id: string; revision: number; parentId: string; branch: AgentBranch; state: State; }	必需	—
context	OperationContext<App>	必需	—

request 的字段

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
revision	number	必需	见类型定义及调用场景。
parentId	string	必需	见类型定义及调用场景。
branch	AgentBranch	必需	见类型定义及调用场景。
state	State	必需	见类型定义及调用场景。

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： Promise<FamilyRecord<State>>。

等待后的值： FamilyRecord<State>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Family id; also the store key.
revision	number	必需	只读。Optimistic concurrency token; every accepted mutation increments it by one.
activeId	string	必需	只读。Id of the active version; promotion moves this pointer.
expiresAtMs	number	必需	只读。Instant after which the record is no longer retained, in epoch milliseconds.
versions	readonly FamilyVersion<State>[]	必需	只读。Versions in creation order; bounded by maxVersions when configured.

merge

Merges source into target; saved is false when the merge reported conflicts.

AgentFamily.merge(request: { id: string; revision: number; baseId: string; targetId: string; sourceId: string; }, context: OperationContext<App>): Promise<{ saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }>

Merges source into target; saved is false when the merge reported conflicts.

参数	类型	传递	说明
request	{ id: string; revision: number; baseId: string; targetId: string; sourceId: string; }	必需	—
context	OperationContext<App>	必需	—

request 的字段

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
revision	number	必需	见类型定义及调用场景。
baseId	string	必需	见类型定义及调用场景。
targetId	string	必需	见类型定义及调用场景。
sourceId	string	必需	见类型定义及调用场景。

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： Promise<{ saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }>。

等待后的值： { saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }。

返回值结构

字段	类型	必需	说明
saved	boolean	必需	见类型定义及调用场景。
record	FamilyRecord<State>	必需	见类型定义及调用场景。
conflicts	readonly string[]	必需	见类型定义及调用场景。

promote

Makes candidateId active; fails when the active version changed since expectedActiveId.

AgentFamily.promote(request: { id: string; revision: number; candidateId: string; expectedActiveId: string; }, context: OperationContext<App>): Promise<FamilyRecord<State>>

Makes candidateId active; fails when the active version changed since expectedActiveId.

参数	类型	传递	说明
request	{ id: string; revision: number; candidateId: string; expectedActiveId: string; }	必需	—
context	OperationContext<App>	必需	—

request 的字段

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
revision	number	必需	见类型定义及调用场景。
candidateId	string	必需	见类型定义及调用场景。
expectedActiveId	string	必需	见类型定义及调用场景。

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： Promise<FamilyRecord<State>>。

等待后的值： FamilyRecord<State>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Family id; also the store key.
revision	number	必需	只读。Optimistic concurrency token; every accepted mutation increments it by one.
activeId	string	必需	只读。Id of the active version; promotion moves this pointer.
expiresAtMs	number	必需	只读。Instant after which the record is no longer retained, in epoch milliseconds.
versions	readonly FamilyVersion<State>[]	必需	只读。Versions in creation order; bounded by maxVersions when configured.

使用示例

• Agent 分支：版本、合并与显式启用：在真实 CAS 存储上管理数据分支，候选版本经检查和授权后显式启用。

配置状态检查、来源验证和三方合并

配置 · Node.js

TypeScript

import { defineAgentFamily } from '@jangts/agent-core/kits/family';
import type { FamilyStore } from '@jangts/agent-core/kits/family';
import type { OperationContext } from '@jangts/agent-core';

type State = { goal: string; sourceRevision: string };
export function family<App>(store: FamilyStore<State>,
  authorize: (context: OperationContext<App>) => Promise<void>,
  verify: (state: State) => Promise<void>) {
  return defineAgentFamily<State, App>({
    store, maxVersions: 16, retentionMs: 7 * 86400000,
    isState: (value): value is State => !!value && typeof (value as State).goal === 'string'
      && typeof (value as State).sourceRevision === 'string',
    authorize: (_operation, _record, context) => authorize(context),
    validate: candidate => verify(candidate.state),
    async merge({ base, target, source }) {
      if (target.goal !== base.goal && source.goal !== base.goal && target.goal !== source.goal)
        return { conflicts: ['goal'] };
      return { value: target.goal === base.goal ? source : target, conflicts: [] };
    },
  });
}

JavaScript

import { defineAgentFamily } from '@jangts/agent-core/kits/family';
export function family(store, authorize, verify) {
    return defineAgentFamily({
        store, maxVersions: 16, retentionMs: 7 * 86400000,
        isState: (value) => !!value && typeof value.goal === 'string'
            && typeof value.sourceRevision === 'string',
        authorize: (_operation, _record, context) => authorize(context),
        validate: candidate => verify(candidate.state),
        async merge({ base, target, source }) {
            if (target.goal !== base.goal && source.goal !== base.goal && target.goal !== source.goal)
                return { conflicts: ['goal'] };
            return { value: target.goal === base.goal ? source : target, conflicts: [] };
        },
    });
}

显式启用已批准的候选版本

扩展 · Node.js

App 在真实审批后调用；promote 仍重新执行来源、授权、版本和 CAS 检查。

TypeScript

import type { AgentFamily } from '@jangts/agent-core/kits/family';
import type { OperationContext } from '@jangts/agent-core';

export async function activate<State, App>(family: AgentFamily<State, App>, id: string,
  candidateId: string, context: OperationContext<App>) {
  const record = await family.read(id, context);
  return family.promote({ id, revision: record.revision, candidateId,
    expectedActiveId: record.activeId }, context);
}

JavaScript

export async function activate(family, id, candidateId, context) {
    const record = await family.read(id, context);
    return family.promote({ id, revision: record.revision, candidateId,
        expectedActiveId: record.activeId }, context);
}

相关策略源码

• 分支版本冲突与启用检查

相关定义

• AgentBranch
• FamilyRecord
• OperationContext