ContextRecord

CORE · type · 类型合同

One journal entry: a model call, a tool request or a tool result.

The three variants are distinguished by type; value/input stay unknown because their domain meaning belongs to the App.

导入

TypeScript

import type { ContextRecord } from '@jangts/agent-core/context';

JavaScript

/** @typedef {import('@jangts/agent-core/context').ContextRecord} ContextRecord */

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

定义

类型： ContextRecord

类型表达式

type ContextRecord = RecordIdentity &
  /** A model call was made for `stageId`; `value` is what the call produced. */
  (
    | { readonly type: 'model'; readonly stageId: string; readonly value: unknown }
    /** A tool call was requested; `input` is the raw request payload. */
    | { readonly type: 'tool'; readonly toolId: string; readonly input: unknown }
    /** A tool call settled; `value` carries the result or the failure detail. */
    | {
        readonly type: 'tool-result';
        readonly toolId: string;
        readonly status: 'success' | 'error' | 'cancelled';
        readonly value: unknown;
      }
  );

联合分支结构

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

分支 1

字段	类型	必需	说明
runId	string | undefined	可省略	只读。Root run this invocation belongs to, when the host runs inside a diagnostics scope.
spanId	string | undefined	可省略	只读。Diagnostics span of this invocation.
parentSpanId	string | undefined	可省略	只读。Span that caused this invocation; absent for a root invocation.
parentInvocationId	string | undefined	可省略	只读。Enclosing invocation when one call triggers another.
invocationId	string	必需	只读。Opaque per-invocation id shared by receipt, events and diagnostic records. Invocation that produced the record.
startedAtMs	number	必需	只读。Start instant in epoch milliseconds.
durationMs	number	必需	只读。Elapsed milliseconds from start to completion.
producerSequence	number	必需	只读。Monotonic order within this journal; starts at 1 and never repeats.
occurredAtMs	number	必需	只读。Instant the record was written, in epoch milliseconds.
type	"model"	必需	只读。见类型定义及调用场景。
stageId	string	必需	只读。见类型定义及调用场景。
value	unknown	必需	只读。见类型定义及调用场景。

分支 2

字段	类型	必需	说明
runId	string | undefined	可省略	只读。Root run this invocation belongs to, when the host runs inside a diagnostics scope.
spanId	string | undefined	可省略	只读。Diagnostics span of this invocation.
parentSpanId	string | undefined	可省略	只读。Span that caused this invocation; absent for a root invocation.
parentInvocationId	string | undefined	可省略	只读。Enclosing invocation when one call triggers another.
invocationId	string	必需	只读。Opaque per-invocation id shared by receipt, events and diagnostic records. Invocation that produced the record.
startedAtMs	number	必需	只读。Start instant in epoch milliseconds.
durationMs	number	必需	只读。Elapsed milliseconds from start to completion.
producerSequence	number	必需	只读。Monotonic order within this journal; starts at 1 and never repeats.
occurredAtMs	number	必需	只读。Instant the record was written, in epoch milliseconds.
type	"tool"	必需	只读。见类型定义及调用场景。
toolId	string	必需	只读。见类型定义及调用场景。
input	unknown	必需	只读。见类型定义及调用场景。

分支 3

字段	类型	必需	说明
runId	string | undefined	可省略	只读。Root run this invocation belongs to, when the host runs inside a diagnostics scope.
spanId	string | undefined	可省略	只读。Diagnostics span of this invocation.
parentSpanId	string | undefined	可省略	只读。Span that caused this invocation; absent for a root invocation.
parentInvocationId	string | undefined	可省略	只读。Enclosing invocation when one call triggers another.
invocationId	string	必需	只读。Opaque per-invocation id shared by receipt, events and diagnostic records. Invocation that produced the record.
startedAtMs	number	必需	只读。Start instant in epoch milliseconds.
durationMs	number	必需	只读。Elapsed milliseconds from start to completion.
producerSequence	number	必需	只读。Monotonic order within this journal; starts at 1 and never repeats.
occurredAtMs	number	必需	只读。Instant the record was written, in epoch milliseconds.
type	"tool-result"	必需	只读。见类型定义及调用场景。
toolId	string	必需	只读。见类型定义及调用场景。
status	"error" | "success" | "cancelled"	必需	只读。见类型定义及调用场景。
value	unknown	必需	只读。见类型定义及调用场景。

使用示例

• ContextJournal：回执的请求内投影：将真实调用回执变成可用于后续上下文的请求内记录，不另起持久日志系统。

读取 Runner 已记录的模型回执

入门 · Node.js

TypeScript

import { ModelRunner } from '@jangts/agent-core';
const runner = new ModelRunner({ provider: { async *stream() { yield '服务运行正常'; } } });
const result = await runner.invoke('查询服务状态');
console.log(result.invocation.invocationId);
console.log(runner.journal.snapshot());

JavaScript

import { ModelRunner } from '@jangts/agent-core';
const runner = new ModelRunner({ provider: { async *stream() { yield '服务运行正常'; } } });
const result = await runner.invoke('查询服务状态');
console.log(result.invocation.invocationId);
console.log(runner.journal.snapshot());

应用适配器记录它实际执行的本地工具

配置 · Node.js

TypeScript

import { ContextJournal } from '@jangts/agent-core/journal';
const journal = new ContextJournal();
const invocationId = journal.beginTool({ toolId: 'get_status', input: {} });
// 此处由 App 实际执行本地读取；不是模型提供的回执。
const status = '服务运行正常';
journal.finishTool({ invocationId, status: 'success', value: status });
console.log(journal.snapshot());

JavaScript

import { ContextJournal } from '@jangts/agent-core/journal';
const journal = new ContextJournal();
const invocationId = journal.beginTool({ toolId: 'get_status', input: {} });
// 此处由 App 实际执行本地读取；不是模型提供的回执。
const status = '服务运行正常';
journal.finishTool({ invocationId, status: 'success', value: status });
console.log(journal.snapshot());

相关定义

• InvocationMetadata