retrievalQueryKey

CORE · function · 运行时值

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.

导入

TypeScript

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

JavaScript

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

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

定义

调用

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 { commonPrefixLength } from '@jangts/agent-core';
console.log(commonPrefixLength('服务：正常', '服务：繁忙')); // 3

JavaScript

import { commonPrefixLength } from '@jangts/agent-core';
console.log(commonPrefixLength('服务：正常', '服务：繁忙')); // 3

对象键顺序不同，查询语义保持同一结构

配置 · Node.js

TypeScript

import { retrievalQueryKey } from '@jangts/agent-core';
const first = retrievalQueryKey({ query: '服务状态', filters: { region: 'cn', active: true } });
const second = retrievalQueryKey({ filters: { active: true, region: 'cn' }, query: '服务状态' });
console.log(first === second); // true
console.log(retrievalQueryKey({ ids: ['a', 'b'] }) === retrievalQueryKey({ ids: ['b', 'a'] })); // false

JavaScript

import { retrievalQueryKey } from '@jangts/agent-core';
const first = retrievalQueryKey({ query: '服务状态', filters: { region: 'cn', active: true } });
const second = retrievalQueryKey({ filters: { active: true, region: 'cn' }, query: '服务状态' });
console.log(first === second); // true
console.log(retrievalQueryKey({ ids: ['a', 'b'] }) === retrievalQueryKey({ ids: ['b', 'a'] })); // false

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

入门 · 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);

相关策略源码

• 结构键的排序与序列化
• 公共前缀的比较实现
• 去重、预占、读取、计数和效果顺序
• 默认查询键