Knowledge

KIT · constant · Runtime value

Import

TypeScript

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

JavaScript

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

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

Definition

Member index

Member	Purpose
defineKnowledgeCatalog	See the overload below for full inputs and outputs.
parseKnowledgeDocument	See the overload below for full inputs and outputs.
defineKnowledgePublication	See the overload below for full inputs and outputs.

Member details

defineKnowledgeCatalog

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

parseKnowledgeDocument

Knowledge.parseKnowledgeDocument(input: { id: string; revision: string; text: string; locale?: string; }): KnowledgeDocument

Paired, nestable anchors are one text adapter. Other sources supply the same document contract directly.

Parameter	Type	Passing	Description
input	{ id: string; revision: string; text: string; locale?: string; }	Required	—

Fields of input

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
revision	string	Required	See the type definition and usage context.
text	string	Required	See the type definition and usage context.
locale	string | undefined	Optional	See the type definition and usage context.

Returns: 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.

defineKnowledgePublication

Knowledge.defineKnowledgePublication<App>(options: KnowledgePublicationOptions<App>): KnowledgePublication<App>

Compile a publication lifecycle over one App-owned atomic record.

Candidate preparation and publication share the same compiler and an App-owned atomic revision. propose compiles and validates a candidate but leaves published documents alone; publish re-verifies sources and the base revision before swapping, so a stale candidate can never overwrite newer content.

Type parameter	Constraint	Default type
App	—	—

Parameter	Type	Passing	Description
options	KnowledgePublicationOptions<App>	Required	—

Fields of options

Field	Type	Required	Description
store	KnowledgePublicationStore	Required	Read-only. See the type definition and usage context.
requiredReads	readonly KnowledgeRead[] | undefined	Optional	Read-only. Reads that must succeed against every compiled document set, proving sections still exist.
maxReadChars	number | undefined	Optional	Read-only. Per-read character budget applied by the catalog compiler.
maxCandidates	number | undefined	Optional	Read-only. Maximum pending candidates retained; defaults to 32 and must be a positive integer.
candidateRetentionMs	number | undefined	Optional	Read-only. Candidate retention window; defaults to seven days.
now	(() => number) | undefined	Optional	Read-only. Clock override for timestamps and expiry; defaults to Date.now.
authorize	(operation: (typeof knowledgePublicationOperations)[number], context: OperationContext<App>) => MaybePromise<void>	Required	Guards one operation before any read or write.
verifySources	(sources: readonly KnowledgeSourceReference[], context: OperationContext<App>) => MaybePromise<void>	Required	Validate real provenance/revisions/visibility. A model's source list is not a grant.

Returns: KnowledgePublication<App>.

Return value structure

Field	Type	Required	Description
read	(context: OperationContext<App>) => Promise<KnowledgePublicationRecord>	Required	Returns the current record, with expired candidates already pruned.
propose	(request: { revision: number; document: KnowledgeDocument; sources: readonly KnowledgeSourceReference[]; }, context: OperationContext<App>) => Promise<KnowledgePublicationRecord>	Required	Adds a candidate based on revision; fails when the record moved on.
publish	(request: { revision: number; candidateId: string; }, context: OperationContext<App>) => Promise<KnowledgePublicationRecord>	Required	Publishes one candidate and removes it from the pending list.
reject	(request: { revision: number; candidateId: string; }, context: OperationContext<App>) => Promise<KnowledgePublicationRecord>	Required	Discards one candidate without touching the published documents.

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

• defineKnowledgeCatalog
• defineKnowledgePublication
• KnowledgeCatalog
• KnowledgeCatalogOptions
• KnowledgeDocument
• KnowledgePublication
• KnowledgePublicationOptions
• parseKnowledgeDocument