normalizeDiagnosticEvent

CORE · function · 运行时值

Validate a persisted diagnostic record and return a detached copy.

Persisted data is untrusted, so the envelope version, event type, identity, ordering and the bounded sub-step shape are checked; the payload itself is not interpreted. The copy is deep cloned, so a store cannot hand back a record that later shares structure with the caller.

导入

TypeScript

import { normalizeDiagnosticEvent } from '@jangts/agent-core/diagnostics';

JavaScript

import { normalizeDiagnosticEvent } from '@jangts/agent-core/diagnostics';

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

定义

调用

normalizeDiagnosticEvent(input: unknown): import("../structs/diagnostics.js").CoreDiagnosticRecord

Validate a persisted diagnostic record and return a detached copy.

Persisted data is untrusted, so the envelope version, event type, identity, ordering and the bounded sub-step shape are checked; the payload itself is not interpreted. The copy is deep cloned, so a store cannot hand back a record that later shares structure with the caller.

参数	类型	传递	说明
input	unknown	必需	—

返回： CoreDiagnosticRecord。

返回值结构

字段	类型	必需	说明
version	2	必需	只读。Envelope version this record was written with.
eventId	string	必需	只读。见类型定义及调用场景。
type	keyof CoreEventPayloads	必需	只读。见类型定义及调用场景。
producerSequence	number	必需	只读。Per-producer monotonic sequence; at least 1.
occurredAtMs	number	必需	只读。见类型定义及调用场景。
payload	unknown	必需	只读。Unvalidated payload; only the envelope above is checked during normalization.
usedModel	boolean | undefined	可省略	只读。见类型定义及调用场景。
subSteps	readonly RecordedSubStep[]	必需	只读。见类型定义及调用场景。
subStepsDropped	number	必需	只读。见类型定义及调用场景。
subStepsTruncated	boolean	必需	只读。见类型定义及调用场景。
runId	string	必需	只读。Root run id shared by every fact of one logical run.
spanId	string	必需	只读。Span that produced the fact.
parentSpanId	string | undefined	可省略	只读。Enclosing span; absent for a root span.
invocationId	string | undefined	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
parentInvocationId	string | undefined	可省略	只读。Enclosing invocation, when one invocation triggers another.
nodeRole	"invocation" | "workflow-node" | "workflow-boundary" | "loop-step" | undefined	可省略	只读。Role the emitting span plays in the execution graph.
agentId	string | undefined	可省略	只读。App-owned agent identity.
branchId	string | undefined	可省略	只读。App-owned branch identity.
agentVersionId	string | undefined	可省略	只读。App-owned immutable version identity of the agent definition.
parentBranchId	string | undefined	可省略	只读。Branch this branch was forked from, when applicable.
parentAgentVersionId	string | undefined	可省略	只读。Version of the parent branch at the fork point.
forkPointId	string | undefined	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
workflowInvocationId	string | undefined	可省略	只读。Workflow invocation the fact belongs to.
workflowNodeId	string | undefined	可省略	只读。Workflow node invocation the fact belongs to.
definitionKind	string | undefined	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
definitionId	string | undefined	可省略	只读。Id of that definition.
definitionRevision	string | undefined	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
nodeId	string | undefined	可省略	只读。Node id inside the workflow.
nodeName	string | undefined	可省略	只读。Human-readable node name.
nodeKind	string | undefined	可省略	只读。Node kind as declared by the App.
nodeDescription	string | undefined	可省略	只读。Optional node description for diagnostics display.
stageId	string | undefined	可省略	只读。Model stage that produced the fact.
modelId	string | undefined	可省略	只读。Model binding used, when the fact concerns a model call.

使用示例

• 过程监听与节点报告：App 订阅 Core 执行事实；节点报告自身 usedModel，并用实例式子日志先记意图、再补结果，Loop 负责身份和日志。

监听任务经过的节点与模型事件

入门 · Node.js

TypeScript

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

type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({
  id: 'greeting',
  nodes: [{
    id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
    run: state => ({ answer: '你好，' + state.name }),
    routes: [route.deliver('answer')],
  }],
});
const agent = new AgentCoreEngine({ workflow, execution: {
  observe: { event(event) { console.log(event.type, event.eventId); } },
} });
console.log(await agent.run({ name: 'Ivan' }));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({
    id: 'greeting',
    nodes: [{
            id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
            run: state => ({ answer: '你好，' + state.name }),
            routes: [route.deliver('answer')],
        }],
});
const agent = new AgentCoreEngine({ workflow, execution: {
        observe: { event(event) { console.log(event.type, event.eventId); } },
    } });
console.log(await agent.run({ name: 'Ivan' }));

节点执行时报告业务阶段

配置 · Node.js

节点只报告它知道的事实；Core 负责节点身份和执行关联。

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({ id: 'greeting', nodes: [{
  id: 'greet', description: '生成问候', startsRound: true,
  run(state, context) {
    context.report({ payload: { phase: 'formatting' } });
    return { answer: '你好，' + state.name };
  }, routes: [route.deliver('answer')],
}] });
const agent = new AgentCoreEngine({ workflow, execution: {
  observe: { event(event) { console.log(event.type); } },
} });
console.log(await agent.run({ name: 'Ivan' }));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'greeting', nodes: [{
            id: 'greet', description: '生成问候', startsRound: true,
            run(state, context) {
                context.report({ payload: { phase: 'formatting' } });
                return { answer: '你好，' + state.name };
            }, routes: [route.deliver('answer')],
        }] });
const agent = new AgentCoreEngine({ workflow, execution: {
        observe: { event(event) { console.log(event.type); } },
    } });
console.log(await agent.run({ name: 'Ivan' }));

先记异步计划，再补结果

配置 · Node.js

受限 logger 自动绑定分组并只修订自己的 write；readAll 仍可读全量。每次 fix 追加独立记录并关联原 write，节点无需提交 logger。

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { result?: string };
const workflow = defineWorkflow<State, string>({ id: 'prepare', nodes: [{
  id: 'prepare', description: '准备资料', async run(_, context) {
    const subs = context.createSubFlowLogger();
    const read = subs.fork('material-read');
    const id = read.write({ name: '读取资料', kind: 'read', type: 'material.read' });
    read.fix(id, { status: 'running' });
    const result = await Promise.resolve('已准备');
    read.fix(id, { status: 'success', usedModel: false, payload: { result } });
    context.report({ usedModel: false });
    console.log(read.readAll());
    return { result };
  }, routes: [route.deliver('result')],
}] });
const agent = new AgentCoreEngine({ workflow, execution: { observe: {
  accepts: ({ event, content }) => content === 'metadata' || event === 'node.progress',
  event(event) { if (event.type === 'node.progress') console.log(event.payload.subStep, event.subSteps); },
} } });
console.log(await agent.run({}));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'prepare', nodes: [{
            id: 'prepare', description: '准备资料', async run(_, context) {
                const subs = context.createSubFlowLogger();
                const read = subs.fork('material-read');
                const id = read.write({ name: '读取资料', kind: 'read', type: 'material.read' });
                read.fix(id, { status: 'running' });
                const result = await Promise.resolve('已准备');
                read.fix(id, { status: 'success', usedModel: false, payload: { result } });
                context.report({ usedModel: false });
                console.log(read.readAll());
                return { result };
            }, routes: [route.deliver('result')],
        }] });
const agent = new AgentCoreEngine({ workflow, execution: { observe: {
            accepts: ({ event, content }) => content === 'metadata' || event === 'node.progress',
            event(event) { if (event.type === 'node.progress')
                console.log(event.payload.subStep, event.subSteps); },
        } } });
console.log(await agent.run({}));

相关策略源码

• 共享执行事实源和消费隔离
• 子步骤状态及推进关系

相关定义

• CoreDiagnosticRecord