defineKnowledgeCatalog

KIT · function · Runtime value

Compile a knowledge catalog from document declarations.

Reads are declarative: document returns the whole text, self returns exactly the named sections and subtree includes their nested sections. Section ids are validated up front, so a typo fails at read time instead of silently returning partial content.

Import

TypeScript

import { defineKnowledgeCatalog } from '@jangts/agent-core/kits/knowledge';

JavaScript

import { defineKnowledgeCatalog } from '@jangts/agent-core/kits/knowledge';

Other public entry points:@jangts/agent-core/types, @jangts/agent-core/kits/knowledge, @jangts/agent-core/kits.

Definition

Call

defineKnowledgeCatalog(documents: readonly KnowledgeDocument[], options?: KnowledgeCatalogOptions): KnowledgeCatalog

Compile a knowledge catalog from document declarations.

Reads are declarative: document returns the whole text, self returns exactly the named sections and subtree includes their nested sections. Section ids are validated up front, so a typo fails at read time instead of silently returning partial content.

Parameter	Type	Passing	Description
documents	readonly KnowledgeDocument[]	Required	—
options	KnowledgeCatalogOptions	Optional	—

Fields of options

Field	Type	Required	Description
maxChars	number | undefined	Optional	Read-only. Maximum characters per read; exceeding it throws a RangeError.
observe	((snapshot: KnowledgeSnapshot) => void | Promise<void>) | undefined	Optional	Read-only. Observer invoked with every produced snapshot.

Returns: KnowledgeCatalog.

Return value structure

Field	Type	Required	Description
sectionIds	(documentId: string) => readonly string[]	Required	Section ids of one document, in declaration order; throws for an unknown document.
assertSelection	(read: KnowledgeRead) => void	Required	Validates a read without producing content; throws when the selection is invalid.
read	(read: KnowledgeRead) => KnowledgeSnapshot	Required	Produces a snapshot for the read; throws for unknown documents, sections or budget excess.
definitions	readonly Readonly<KnowledgeDocument>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<KnowledgeDocument>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<KnowledgeDocument>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<KnowledgeDocument> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<KnowledgeDocument>	Required	Returns the definition or throws; use when the id is a required reference.

Examples

• Knowledge: documents, sections, and evidence snapshots: One document contract supports plain objects and anchored text; a selection yields an evidence snapshot with an explicit version.

First read one plain-object document

Beginner · Node.js

TypeScript

import { Knowledge } from '@jangts/agent-core/kits/knowledge';
const catalog = Knowledge.defineKnowledgeCatalog([
  { id: 'manual', revision: '1', parts: ['Agent Core 支持普通 Workflow 节点。'] },
]);
const snapshot = catalog.read({ documentId: 'manual', selection: { mode: 'document' } });
console.log(snapshot.content, snapshot.revision);

JavaScript

import { Knowledge } from '@jangts/agent-core/kits/knowledge';
const catalog = Knowledge.defineKnowledgeCatalog([
    { id: 'manual', revision: '1', parts: ['Agent Core 支持普通 Workflow 节点。'] },
]);
const snapshot = catalog.read({ documentId: 'manual', selection: { mode: 'document' } });
console.log(snapshot.content, snapshot.revision);

Add sections and a budget to the same read

Configuration · Node.js

TypeScript

import { Knowledge } from '@jangts/agent-core/kits/knowledge';
const catalog = Knowledge.defineKnowledgeCatalog([
  { id: 'manual', revision: '2', parts: [
    { id: 'start', parts: ['先运行一个节点。', { id: 'advanced', parts: ['再增加模型和工具。'] }] },
  ] },
], { maxChars: 2000 });
console.log(catalog.sectionIds('manual'));
const snapshot = catalog.read({ documentId: 'manual', selection: { mode: 'subtree', sectionIds: ['start'] } });
console.log(snapshot.content, snapshot.id);

JavaScript

import { Knowledge } from '@jangts/agent-core/kits/knowledge';
const catalog = Knowledge.defineKnowledgeCatalog([
    { id: 'manual', revision: '2', parts: [
            { id: 'start', parts: ['先运行一个节点。', { id: 'advanced', parts: ['再增加模型和工具。'] }] },
        ] },
], { maxChars: 2000 });
console.log(catalog.sectionIds('manual'));
const snapshot = catalog.read({ documentId: 'manual', selection: { mode: 'subtree', sectionIds: ['start'] } });
console.log(snapshot.content, snapshot.id);

Switch to the text adapter; later catalog and read calls stay identical

Extension · Node.js

Paired anchors must match; markers are just one input for the text adapter, and Core does not require documents to be stored as Markdown.

TypeScript

import { Knowledge } from '@jangts/agent-core/kits/knowledge';
const document = Knowledge.parseKnowledgeDocument({
  id: 'manual', revision: '3',
  text: ['<!-- agent-section:start -->', '先运行一个节点。', '<!-- /agent-section:start -->'].join('\n'),
});
const catalog = Knowledge.defineKnowledgeCatalog([document], { maxChars: 2000 });
const read = { documentId: 'manual', selection: { mode: 'self' as const, sectionIds: ['start'] } };
catalog.assertSelection(read);
console.log(catalog.read(read).content);

JavaScript

import { Knowledge } from '@jangts/agent-core/kits/knowledge';
const document = Knowledge.parseKnowledgeDocument({
    id: 'manual', revision: '3',
    text: ['<!-- agent-section:start -->', '先运行一个节点。', '<!-- /agent-section:start -->'].join('\n'),
});
const catalog = Knowledge.defineKnowledgeCatalog([document], { maxChars: 2000 });
const read = { documentId: 'manual', selection: { mode: 'self', sectionIds: ['start'] } };
catalog.assertSelection(read);
console.log(catalog.read(read).content);

Related policy source

• Selection, budget, and snapshot identity
• Text section parsing and tree compilation

Related definitions

• KnowledgeCatalog
• KnowledgeCatalogOptions
• KnowledgeDocument