ReflectionSource

KIT · interface · 类型合同

App-owned evidence source, including its own authorization.

导入

TypeScript

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

JavaScript

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

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

定义

interface ReflectionSource<App>

泛型参数

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

字段结构

字段	类型	必需	说明
id	string	必需	只读。见类型定义及调用场景。
description	string	必需	只读。见类型定义及调用场景。
authorize	(query: ReflectionQuery, context: OperationContext<App>) => MaybePromise<void>	必需	Guards one query; runs before any evidence is read.
query	(query: ReflectionQuery, context: OperationContext<App>) => Promise<ReflectionPage>	必需	Returns one page; an invalid page shape aborts the reflection.

成员目录

成员	用途
authorize	Guards one query; runs before any evidence is read.
query	Returns one page; an invalid page shape aborts the reflection.

成员详情

authorize

Guards one query; runs before any evidence is read.

ReflectionSource.authorize(query: ReflectionQuery, context: OperationContext<App>): MaybePromise<void>

Guards one query; runs before any evidence is read.

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

query 的字段

字段	类型	必需	说明
run	string | undefined	可省略	只读。Run to inspect; omitted means the App chooses the scope.
types	readonly string[] | undefined	可省略	只读。Evidence types to include; omitted means all types.
cursor	string | undefined	可省略	只读。Opaque continuation cursor from a previous page.
limit	number	必需	只读。Maximum items requested; at least 1, clamped to the remaining evidence budget.

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.

返回： MaybePromise<void>。

等待后的值： void。

query

Returns one page; an invalid page shape aborts the reflection.

ReflectionSource.query(query: ReflectionQuery, context: OperationContext<App>): Promise<ReflectionPage>

Returns one page; an invalid page shape aborts the reflection.

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

query 的字段

字段	类型	必需	说明
run	string | undefined	可省略	只读。Run to inspect; omitted means the App chooses the scope.
types	readonly string[] | undefined	可省略	只读。Evidence types to include; omitted means all types.
cursor	string | undefined	可省略	只读。Opaque continuation cursor from a previous page.
limit	number	必需	只读。Maximum items requested; at least 1, clamped to the remaining evidence budget.

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<ReflectionPage>。

等待后的值： ReflectionPage。

返回值结构

字段	类型	必需	说明
items	readonly ReflectionEvidence[]	必需	只读。Items in source order.
cursor	string | undefined	可省略	只读。Continuation cursor; absent when the source has no further items.
coverage	{ readonly consistency: "best-effort" | "snapshot"; readonly complete: boolean | null; readonly gaps: readonly string[]; }	必需	只读。见类型定义及调用场景。

使用示例

• 日志复盘：授权元数据与证据报告：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 });
}

相关策略源码

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

相关定义

• MaybePromise
• OperationContext
• ReflectionPage
• ReflectionQuery