ReflectionEvidence

KIT · interface · 类型合同

Explicit metadata projection, not an arbitrary original event/payload.

导入

TypeScript

import type { ReflectionEvidence } from '@jangts/agent-core/kits/reflection';

JavaScript

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

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

定义

interface ReflectionEvidence

继承或实现： Partial< Pick<DiagnosticIdentity, (typeof reflectionIdentityFields)[number]> >。

字段结构

字段	类型	必需	说明
id	string	必需	只读。Evidence id cited by findings when they rely on this item.
runId	string	必需	只读。Run the item belongs to; queries are scoped by run.
type	string	必需	只读。Evidence type, matched against ReflectionQuery.types.
occurredAtMs	number | undefined	可省略	只读。见类型定义及调用场景。
sequence	number | undefined	可省略	只读。Ordering key inside the source; ascending.
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
status	string | undefined	可省略	只读。见类型定义及调用场景。
code	string | undefined	可省略	只读。Error or protocol code recorded on the item.
calls	number | undefined	可省略	只读。Model or tool calls represented by the item.
durationMs	number | undefined	可省略	只读。见类型定义及调用场景。
inputChars	number | undefined	可省略	只读。见类型定义及调用场景。
outputChars	number | undefined	可省略	只读。见类型定义及调用场景。
expiresAtMs	number | undefined	可省略	只读。Instant after which the item is no longer retained by the source.
spanId	string | undefined	可省略	只读。Span that produced the fact.
parentSpanId	string | undefined	可省略	只读。Enclosing span; absent for a root span.
parentInvocationId	string | undefined	可省略	只读。Enclosing invocation, when one invocation triggers another.
invocationId	string | undefined	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
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.
definitionId	string | undefined	可省略	只读。Id of that definition.

使用示例

• 日志复盘：授权元数据与证据报告：App 提供获准证据源，复盘任务通过普通模型与工具合同生成有来源的报告。

绑定复盘模型、证据源和授权

入门 · Node.js

TypeScript

import { defineReflection } from '@jangts/agent-core/kits/reflection';
import type { ReflectionSource } from '@jangts/agent-core/kits/reflection';
import type { ModelRunner, OperationContext } from '@jangts/agent-core';

export function review<App>(model: ModelRunner, source: ReflectionSource<App>,
  authorize: (question: string, context: OperationContext<App>) => Promise<void>) {
  return defineReflection({ model, source, authorize,
    maxCalls: 4, reserveCalls: 1, maxPages: 4, maxEvents: 64, maxEvidenceChars: 12000 });
}

JavaScript

import { defineReflection } from '@jangts/agent-core/kits/reflection';
export function review(model, source, authorize) {
    return defineReflection({ model, source, authorize,
        maxCalls: 4, reserveCalls: 1, maxPages: 4, maxEvents: 64, maxEvidenceChars: 12000 });
}

从日志 reader 构造同一种证据源

配置 · Node.js

reader 的目录范围、关闭与保留期由 App 管理。适配后的 source 可传入同一个 defineReflection。

TypeScript

import { defineReflectionLogSource } from '@jangts/agent-core/kits/reflection';
import type { ReflectionLogReader } from '@jangts/agent-core/kits/reflection';
import type { OperationContext } from '@jangts/agent-core';

export function logSource<App>(reader: ReflectionLogReader, traceId: string,
  authorize: (context: OperationContext<App>) => Promise<void>) {
  return defineReflectionLogSource({ reader, traceId, id: 'authorized-history', authorize });
}

JavaScript

import { defineReflectionLogSource } from '@jangts/agent-core/kits/reflection';
export function logSource(reader, traceId, authorize) {
    return defineReflectionLogSource({ reader, traceId, id: 'authorized-history', authorize });
}

相关策略源码

• 复盘证据引用和报告检查

相关定义

• DiagnosticIdentity
• reflectionIdentityFields