Retrieval

KIT · constant · 运行时值

导入

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';

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

定义

成员目录

成员	用途
defineRetrieval	完整输入输出见下方重载。
retrievalQueryKey	完整输入输出见下方重载。

成员详情

defineRetrieval

Retrieval.defineRetrieval<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>, App>(definition: RetrievalDefinition<Query, Source, Result, App>): RetrievalRunner<Query, Source, Result, import("../structs/common.js").OperationContext<App>>

Compile a retrieval runner from its declared ports and effects.

Rejected queries stay in the caller's seen set, so a retry is reported as a duplicate instead of silently repeating the adapter call; only successful results increment the query count.

类型参数	约束	默认类型
Query	—	—
Source	RetrievalSource	—
Result	RetrievalResult<Source>	—
App	—	—

参数	类型	传递	说明
definition	RetrievalDefinition<Query, Source, Result, App>	必需	—

definition 的字段

字段	类型	必需	说明
id	string	必需	只读。见类型定义及调用场景。
description	string	必需	只读。见类型定义及调用场景。
tags	readonly string[] | undefined	可省略	只读。见类型定义及调用场景。
prepare	((query: Query, context: OperationContext<App>) => Query) | undefined	可省略	只读。Normalizes the query before assertions run; must be synchronous.
assertInput	(query: Query, context: OperationContext<App>) => void	必需	只读。Rejects a malformed query; must be synchronous and return void.
state	(context: OperationContext<App>) => RetrievalState<Source>	必需	只读。Returns the request-owned state that holds counters and sources.
limit	(context: OperationContext<App>) => number	必需	只读。Maximum accepted queries for the current state.
key	((query: Query) => string) | undefined	可省略	只读。Deduplication key; defaults to a canonical serialization of the query.
errors	{ readonly duplicate?: RetrievalReason<Query, OperationContext<App>> | undefined; readonly budget?: RetrievalReason<Query, OperationContext<App>> | undefined; } | undefined	可省略	只读。见类型定义及调用场景。
authorize	((query: Query, context: OperationContext<App>) => void) | undefined	可省略	只读。Resource authorization runs after duplicate/budget checks and before reserving a key.
execute	(query: Query, context: OperationContext<App>) => Result	必需	只读。Performs the actual read; must be synchronous. Throwing does not refund the query key.
assertResult	((result: Result, query: Query, context: OperationContext<App>) => void) | undefined	可省略	只读。Validates the adapter result; a throw leaves the query counted as seen but not successful.
sourceId	((source: Source, query: Query, sequence: number, context: OperationContext<App>) => string) | undefined	可省略	只读。Names a source; the assigned value replaces sourceId in the receipt result.
effects	readonly RetrievalEffect<Query, Source, Result, OperationContext<App>>[] | undefined	可省略	只读。见类型定义及调用场景。
now	(() => number) | undefined	可省略	只读。Clock override for receipt timestamps; defaults to Date.now.

返回： RetrievalRunner<Query, Source, Result, OperationContext<App>>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。见类型定义及调用场景。
description	string	必需	只读。见类型定义及调用场景。
effects	readonly RetrievalEffect<Query, Source, Result, OperationContext<App>>[]	必需	只读。Effects that run after every accepted query.
run	(input: Query, context: OperationContext<App>) => RetrievalReceipt<Query, Source, Result>	必需	Executes one query in the fixed lifecycle order and returns its receipt.

retrievalQueryKey

Retrieval.retrievalQueryKey(value: unknown): string

Serialize a query into a stable structural key.

Object keys are sorted recursively while array positions are preserved. Values that JSON cannot represent, such as functions or undefined, make JSON.stringify return undefined and therefore produce an error instead of a colliding key.

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

返回： string。

使用示例

• Retrieval：有额度的同步检索生命周期：把规范化、校验、去重、授权、读取和后续效果放在一条确定的调用路径中。

为同一份产品资料配置一次读取

入门 · Node.js

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
  id: 'manual-search', description: '读取已确认的本地演示资料',
  assertInput(query: string) { if (!query.trim()) throw new Error('查询为空'); },
  state: () => state, limit: () => 2,
  execute: (query: string) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
    id: 'manual-search', description: '读取已确认的本地演示资料',
    assertInput(query) { if (!query.trim())
        throw new Error('查询为空'); },
    state: () => state, limit: () => 2,
    execute: (query) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);

相同 run 增加规范化、授权和回执效果

配置 · Node.js

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const retrieval = Retrieval.defineRetrieval<string, Source, { sources: Source[] }, { canRead: boolean }>({
  id: 'manual-search', description: '按当前服务端权限读取资料',
  prepare: query => query.trim(),
  assertInput(query) { if (!query) throw new Error('查询为空'); },
  state: () => state, limit: () => 2,
  authorize(_query, { app }) { if (!app.canRead) throw new Error('没有资料读取权限'); },
  execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
  effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const retrieval = Retrieval.defineRetrieval({
    id: 'manual-search', description: '按当前服务端权限读取资料',
    prepare: query => query.trim(),
    assertInput(query) { if (!query)
        throw new Error('查询为空'); },
    state: () => state, limit: () => 2,
    authorize(_query, { app }) { if (!app.canRead)
        throw new Error('没有资料读取权限'); },
    execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
    effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);

相关策略源码

• 去重、预占、读取、计数和效果顺序
• 默认查询键

相关定义

• defineRetrieval
• OperationContext
• RetrievalDefinition
• retrievalQueryKey
• RetrievalRunner