RetrievalPorts

KIT · interface · 类型合同

Host ports and policy for one retrieval kind.

导入

TypeScript

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

JavaScript

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

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

定义

interface RetrievalPorts<Query, Source, Result, Context>

泛型参数

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

字段结构

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

成员目录

成员	用途
assertInput	Rejects a malformed query; must be synchronous and return void.
state	Returns the request-owned state that holds counters and sources.
limit	Maximum accepted queries for the current state.
execute	Performs the actual read; must be synchronous. Throwing does not refund the query key.

成员详情

assertInput

Rejects a malformed query; must be synchronous and return void.

RetrievalPorts.assertInput(query: Query, context: Context): void

参数	类型	传递	说明
query	Query	必需	—
context	Context	必需	—

返回： void。

state

Returns the request-owned state that holds counters and sources.

RetrievalPorts.state(context: Context): RetrievalState<Source>

参数	类型	传递	说明
context	Context	必需	—

返回： RetrievalState<Source>。

返回值结构

字段	类型	必需	说明
queryCount	number	必需	Successful queries so far; compared against the current limit.
seen	Set<string>	必需	只读。Query keys already attempted, including rejected ones, so retries count as duplicates.
sources	Source[]	必需	只读。Sources from successful queries, in acceptance order.

limit

Maximum accepted queries for the current state.

RetrievalPorts.limit(context: Context): number

参数	类型	传递	说明
context	Context	必需	—

返回： number。

execute

Performs the actual read; must be synchronous. Throwing does not refund the query key.

RetrievalPorts.execute(query: Query, context: Context): Result

参数	类型	传递	说明
query	Query	必需	—
context	Context	必需	—

返回： Result。

使用示例

• 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);

相关策略源码

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

相关定义

• RetrievalEffect
• RetrievalReason
• RetrievalResult
• RetrievalSource
• RetrievalState