TextSearch

KIT · class · 运行时值

Optional App-side full-text index. No storage, identity, model calls or Core dependencies.

Only declared fields are indexed and only storedFields come back with a hit, so a document never leaks extra properties into search results.

导入

TypeScript

import { TextSearch } from '@jangts/agent-core/kits/search';

JavaScript

import { TextSearch } from '@jangts/agent-core/kits/search';

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

定义

class TextSearch<Document>

泛型参数

类型参数	约束	默认类型
Document	{ id: string }	—

构造函数

new TextSearch<Document extends { id: string; }>(registration: TextSearchOptions<Document>): TextSearch<Document>

Compile the index configuration and validate it before any document is added.

参数	类型	传递	说明
registration	TextSearchOptions<Document>	必需	—

registration 的字段

字段	类型	必需	说明
indexRevision	string	必需	只读。App-owned revision of the field/tokenizer configuration; a change invalidates snapshots.
fields	readonly (keyof Document & string)[]	必需	只读。Fields that are indexed and searchable.
storedFields	readonly (keyof Document & string)[]	必需	只读。Fields returned in a hit; the indexed body is not implicitly returned.
tokenize	((text: string, fieldName?: string) => string[]) | undefined	可省略	只读。Tokenizer override; defaults to MiniSearch's default tokenizer.
boost	Readonly<Partial<Record<keyof Document & string, number>>> | undefined	可省略	只读。Per-field relevance multiplier; omitted fields keep the default weight.
combineWith	"AND" | "OR" | undefined	可省略	只读。How multiple query terms combine; defaults to the engine default (OR).

返回： TextSearch<Document>。

成员目录

成员	用途
restore	静态。Rebuild an index from a snapshot.
upsert	Insert or replace one document.
search	Search the index and return at most limit hits.
remove	Remove one document. Vacuum before returning so deleted terms do not survive the next serialized checkpoint.
clear	Drop every document while keeping the compiled configuration.
snapshot	Serialize the index together with the configuration used to build it.

成员详情

restore

静态成员。

Rebuild an index from a snapshot.

TextSearch.restore<Document extends { id: string; }>(definition: TextSearchOptions<Document>, snapshot: TextSearchSnapshot): TextSearch<Document>

Rebuild an index from a snapshot.

类型参数	约束	默认类型
Document	{ id: string; }	—

参数	类型	传递	说明
definition	TextSearchOptions<Document>	必需	—
snapshot	TextSearchSnapshot	必需	—

definition 的字段

字段	类型	必需	说明
indexRevision	string	必需	只读。App-owned revision of the field/tokenizer configuration; a change invalidates snapshots.
fields	readonly (keyof Document & string)[]	必需	只读。Fields that are indexed and searchable.
storedFields	readonly (keyof Document & string)[]	必需	只读。Fields returned in a hit; the indexed body is not implicitly returned.
tokenize	((text: string, fieldName?: string) => string[]) | undefined	可省略	只读。Tokenizer override; defaults to MiniSearch's default tokenizer.
boost	Readonly<Partial<Record<keyof Document & string, number>>> | undefined	可省略	只读。Per-field relevance multiplier; omitted fields keep the default weight.
combineWith	"AND" | "OR" | undefined	可省略	只读。How multiple query terms combine; defaults to the engine default (OR).

snapshot 的字段

字段	类型	必需	说明
version	2	必需	只读。Snapshot format version; other versions are not loaded.
engine	"minisearch-7"	必需	只读。Engine that produced the snapshot; a different engine cannot restore it.
configurationFingerprint	string	必需	只读。Fingerprint of the field and tokenizer configuration that built the index.
serializedIndex	string	必需	只读。Serialized MiniSearch index.

返回： TextSearch<Document>。

upsert

实例方法。

Insert or replace one document.

upsert(document: Document): void

Insert or replace one document.

参数	类型	传递	说明
document	Document	必需	—

返回： void。

search

实例方法。

Search the index and return at most limit hits.

search(options: TextSearchQuery<Document> & { query: string; }): TextSearchHit<Document>[]

Search the index and return at most limit hits.

参数	类型	传递	说明
options	TextSearchQuery<Document> & { query: string; }	必需	—

options 的字段

字段	类型	必需	说明
limit	number	必需	只读。Maximum number of hits returned.
filter	(document: Readonly<Partial<Document>> & { id: string; }) => boolean	必需	只读。Required on every query; the application owns authorization and applicability.
query	string	必需	见类型定义及调用场景。

返回： TextSearchHit<Document>[]。

remove

实例方法。

Remove one document.

Vacuum before returning so deleted terms do not survive the next serialized checkpoint.

remove(id: string): Promise<boolean>

Remove one document.

Vacuum before returning so deleted terms do not survive the next serialized checkpoint.

参数	类型	传递	说明
id	string	必需	—

返回： Promise<boolean>。

等待后的值： boolean。

clear

实例方法。

Drop every document while keeping the compiled configuration.

clear(): void

Drop every document while keeping the compiled configuration.

无调用参数。

返回： void。

snapshot

实例方法。

Serialize the index together with the configuration used to build it.

snapshot(): TextSearchSnapshot

Serialize the index together with the configuration used to build it.

无调用参数。

返回： TextSearchSnapshot。

返回值结构

字段	类型	必需	说明
version	2	必需	只读。Snapshot format version; other versions are not loaded.
engine	"minisearch-7"	必需	只读。Engine that produced the snapshot; a different engine cannot restore it.
configurationFingerprint	string	必需	只读。Fingerprint of the field and tokenizer configuration that built the index.
serializedIndex	string	必需	只读。Serialized MiniSearch index.

使用示例

• TextSearch：App 侧全文索引：按已声明字段建立局部索引，查询必须给出应用过滤器。

先索引两份接口说明

入门 · Node.js

TypeScript

import { TextSearch } from '@jangts/agent-core/kits/search';
type Document = { id: string; title: string; body: string };
const index = new TextSearch<Document>({ indexRevision: 'manual-v1', fields: ['title', 'body'], storedFields: ['title'] });
index.upsert({ id: 'workflow', title: 'Workflow', body: 'Define reusable agent nodes.' });
index.upsert({ id: 'model', title: 'Model', body: 'Bind a model provider.' });
console.log(index.search({ query: 'agent', limit: 5, filter: () => true }));

JavaScript

import { TextSearch } from '@jangts/agent-core/kits/search';
const index = new TextSearch({ indexRevision: 'manual-v1', fields: ['title', 'body'], storedFields: ['title'] });
index.upsert({ id: 'workflow', title: 'Workflow', body: 'Define reusable agent nodes.' });
index.upsert({ id: 'model', title: 'Model', body: 'Bind a model provider.' });
console.log(index.search({ query: 'agent', limit: 5, filter: () => true }));

相同 search 增加访问过滤、权重和快照

配置 · Node.js

允许用于过滤的元数据须登记为 storedFields；字段过滤必须依赖可信 App 身份，不能让模型自报身份。

TypeScript

import { TextSearch } from '@jangts/agent-core/kits/search';
type Document = { id: string; title: string; body: string; audience: string };
const options = { indexRevision: 'manual-v2', fields: ['title', 'body'] as const, storedFields: ['title', 'audience'] as const, boost: { title: 3 }, combineWith: 'AND' as const };
const index = new TextSearch<Document>(options);
index.upsert({ id: 'workflow', title: 'Agent Workflow', body: 'Define reusable nodes.', audience: 'public' });
index.upsert({ id: 'private', title: 'Agent internals', body: 'Internal notes.', audience: 'owner' });
const restored = TextSearch.restore<Document>(options, index.snapshot());
console.log(restored.search({ query: 'agent', limit: 5, filter: document => document.audience === 'public' }));
await restored.remove('workflow');

JavaScript

import { TextSearch } from '@jangts/agent-core/kits/search';
const options = { indexRevision: 'manual-v2', fields: ['title', 'body'], storedFields: ['title', 'audience'], boost: { title: 3 }, combineWith: 'AND' };
const index = new TextSearch(options);
index.upsert({ id: 'workflow', title: 'Agent Workflow', body: 'Define reusable nodes.', audience: 'public' });
index.upsert({ id: 'private', title: 'Agent internals', body: 'Internal notes.', audience: 'owner' });
const restored = TextSearch.restore(options, index.snapshot());
console.log(restored.search({ query: 'agent', limit: 5, filter: document => document.audience === 'public' }));
await restored.remove('workflow');

相关策略源码

• 索引字段、过滤、快照指纹与删除

相关定义

• TextSearchHit
• TextSearchOptions
• TextSearchQuery
• TextSearchSnapshot