defineReflection

KIT · function · 运行时值

Compile a reflection task.

Model-driven investigation through ordinary registered tools and the existing Core loop. The task always reports persisted: false: storing a report is the App's decision. Observed findings must cite evidence ids that were actually returned in this run, which is what keeps the report tied to real observations instead of model recall.

导入

TypeScript

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

JavaScript

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

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

定义

泛型参数

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

调用

defineReflection<App>(definition: ReflectionDefinition<App>): ReflectionTask<App>

Compile a reflection task.

Model-driven investigation through ordinary registered tools and the existing Core loop. The task always reports persisted: false: storing a report is the App's decision. Observed findings must cite evidence ids that were actually returned in this run, which is what keeps the report tied to real observations instead of model recall.

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

参数	类型	传递	说明
definition	ReflectionDefinition<App>	必需	—

definition 的字段

字段	类型	必需	说明
model	Pick<ModelRunner<string, readonly ModelTransportDefinition<unknown>[]>, "remainingCalls" | "createChild">	必需	只读。Parent runner; the reflection creates a child and preserves the parent's reserve.
source	ReflectionSource<App>	必需	只读。Evidence source queried through the reflection tools.
tools	readonly ToolDefinition<any, any, App>[] | undefined	可省略	只读。Additional tools exposed to the reflection model.
maxCalls	number | undefined	可省略	只读。Model calls the child may use; defaults to 4.
reserveCalls	number | undefined	可省略	只读。Parent calls kept untouched; defaults to 1.
timeoutMs	number | undefined	可省略	只读。Wall-clock limit for the whole reflection in milliseconds; defaults to 30000.
maxPages	number | undefined	可省略	只读。Maximum evidence pages read; defaults to 4.
maxEvents	number | undefined	可省略	只读。Maximum evidence items collected; defaults to 64.
maxEvidenceChars	number | undefined	可省略	只读。Maximum evidence characters placed in the model context; defaults to 12000.
authorize	(question: string, context: OperationContext<App>) => MaybePromise<void>	必需	Guards one reflection request; runs before any model call.

返回： ReflectionTask<App>。

返回值结构

字段	类型	必需	说明
run	(question: string, context: OperationContext<App>) => Promise<ReflectionReport>	必需	Answers the question from evidence; never throws for incomplete evidence alone.

使用示例

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

相关策略源码

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

相关定义

• ReflectionDefinition
• ReflectionTask