Retrieval：有额度的同步检索生命周期
把规范化、校验、去重、授权、读取和后续效果放在一条确定的调用路径中。
run(query, context) 返回 RetrievalReceipt：原 query、去重 key、成功序号、开始时间、rawResult、带请求内 sourceId 的 result 及 extensions。state(context) 提供本次请求的 queryCount、seen、sources；limit(context) 是成功查询额度。
顺序为 prepare → assertInput → 去重/额度 → authorize → 预占 seen key → execute → assertResult → 累计成功次数及来源 → effects。失败尝试已占用 seen key，不会因失败自动重试。effects 按顺序执行，失败不会假装回滚先前副作用。全部端口为同步；异步检索可由 App 自己的普通 Workflow 节点处理。默认 key 来自 retrievalQueryKey；默认来源 ID 为检索 ID、成功序号与源 ID 的组合，只是请求内引用。
由简到繁的同业务示例
为同一份产品资料配置一次读取
入门 · Node.js
ts
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);js
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
ts
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);js
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);