KnowledgeCatalog

KIT · interface · Type contract

Compiled catalog of knowledge documents.

Import

TypeScript

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

JavaScript

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

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

Definition

interface KnowledgeCatalog

Extends or implements: ReadonlyCatalog<KnowledgeDocument>.

Field 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.

Member index

Member	Purpose
sectionIds	Section ids of one document, in declaration order; throws for an unknown document.
assertSelection	Validates a read without producing content; throws when the selection is invalid.
read	Produces a snapshot for the read; throws for unknown documents, sections or budget excess.
ids	Ids in the same order as definitions.
values	See the overload below for full inputs and outputs.
entries	See the overload below for full inputs and outputs.
has	See the overload below for full inputs and outputs.
get	Returns the definition or undefined; the caller decides whether absence is an error.
require	Returns the definition or throws; use when the id is a required reference.

Member details

sectionIds

Section ids of one document, in declaration order; throws for an unknown document.

KnowledgeCatalog.sectionIds(documentId: string): readonly string[]

Section ids of one document, in declaration order; throws for an unknown document.

Parameter	Type	Passing	Description
documentId	string	Required	—

Returns: readonly string[].

assertSelection

Validates a read without producing content; throws when the selection is invalid.

KnowledgeCatalog.assertSelection(read: KnowledgeRead): void

Validates a read without producing content; throws when the selection is invalid.

Parameter	Type	Passing	Description
read	KnowledgeRead	Required	—

Fields of read

Field	Type	Required	Description
documentId	string	Required	Read-only. See the type definition and usage context.
selection	SectionSelection	Required	Read-only. Must reference existing sections; an invalid selection throws.

Returns: void.

read

Produces a snapshot for the read; throws for unknown documents, sections or budget excess.

KnowledgeCatalog.read(read: KnowledgeRead): KnowledgeSnapshot

Produces a snapshot for the read; throws for unknown documents, sections or budget excess.

Parameter	Type	Passing	Description
read	KnowledgeRead	Required	—

Fields of read

Field	Type	Required	Description
documentId	string	Required	Read-only. See the type definition and usage context.
selection	SectionSelection	Required	Read-only. Must reference existing sections; an invalid selection throws.

Returns: KnowledgeSnapshot.

Return value structure

Field	Type	Required	Description
id	string	Required	Read-only. Deterministic identity derived from document, revision and selection.
revision	string	Required	Read-only. Revision of the document that produced this content.
locale	string | undefined	Optional	Read-only. See the type definition and usage context.
content	string	Required	Read-only. Rendered text, trimmed; sections are separated by blank lines.
documentId	string	Required	Read-only. See the type definition and usage context.
selection	SectionSelection	Required	Read-only. Must reference existing sections; an invalid selection throws.

ids

Ids in the same order as definitions.

KnowledgeCatalog.ids(): readonly string[]

Ids in the same order as definitions.

No call parameters.

Returns: readonly string[].

values

KnowledgeCatalog.values(): IterableIterator<Readonly<KnowledgeDocument>>

No call parameters.

Returns: IterableIterator<Readonly<KnowledgeDocument>>.

entries

KnowledgeCatalog.entries(): IterableIterator<readonly [string, Readonly<KnowledgeDocument>]>

No call parameters.

Returns: IterableIterator<readonly [string, Readonly<KnowledgeDocument>]>.

has

KnowledgeCatalog.has(id: string): boolean

Parameter	Type	Passing	Description
id	string	Required	—

Returns: boolean.

get

Returns the definition or undefined; the caller decides whether absence is an error.

KnowledgeCatalog.get(id: string): Readonly<KnowledgeDocument> | undefined

Returns the definition or undefined; the caller decides whether absence is an error.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<KnowledgeDocument> \| undefined.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string	Required	Read-only. Stable document id; duplicate ids are rejected by the catalog.
revision	string	Required	Read-only. Revision label recorded in every snapshot so a citation names the exact content.
locale	string | undefined	Optional	Read-only. Locale of the content, when the App maintains translations.
parts	readonly KnowledgePart[]	Required	Read-only. Ordered content.

require

Returns the definition or throws; use when the id is a required reference.

KnowledgeCatalog.require(id: string): Readonly<KnowledgeDocument>

Returns the definition or throws; use when the id is a required reference.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<KnowledgeDocument>.

Return value structure

Field	Type	Required	Description
id	string	Required	Read-only. Stable document id; duplicate ids are rejected by the catalog.
revision	string	Required	Read-only. Revision label recorded in every snapshot so a citation names the exact content.
locale	string | undefined	Optional	Read-only. Locale of the content, when the App maintains translations.
parts	readonly KnowledgePart[]	Required	Read-only. Ordered content.

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

Related policy source

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

Related definitions

• KnowledgeDocument
• KnowledgeRead
• KnowledgeSnapshot
• ReadonlyCatalog