KnowledgeCatalog

KIT · interface · 类型合同

Compiled catalog of knowledge documents.

导入

TypeScript

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

JavaScript

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

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

定义

interface KnowledgeCatalog

继承或实现： ReadonlyCatalog<KnowledgeDocument>。

字段结构

字段	类型	必需	说明
sectionIds	(documentId: string) => readonly string[]	必需	Section ids of one document, in declaration order; throws for an unknown document.
assertSelection	(read: KnowledgeRead) => void	必需	Validates a read without producing content; throws when the selection is invalid.
read	(read: KnowledgeRead) => KnowledgeSnapshot	必需	Produces a snapshot for the read; throws for unknown documents, sections or budget excess.
definitions	readonly Readonly<KnowledgeDocument>[]	必需	只读。Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	必需	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<KnowledgeDocument>>	必需	见类型定义及调用场景。
entries	() => IterableIterator<readonly [string, Readonly<KnowledgeDocument>]>	必需	见类型定义及调用场景。
has	(id: string) => boolean	必需	见类型定义及调用场景。
get	(id: string) => Readonly<KnowledgeDocument> | undefined	必需	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<KnowledgeDocument>	必需	Returns the definition or throws; use when the id is a required reference.

成员目录

成员	用途
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	完整输入输出见下方重载。
entries	完整输入输出见下方重载。
has	完整输入输出见下方重载。
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.

成员详情

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.

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

返回： 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.

参数	类型	传递	说明
read	KnowledgeRead	必需	—

read 的字段

字段	类型	必需	说明
documentId	string	必需	只读。见类型定义及调用场景。
selection	SectionSelection	必需	只读。Must reference existing sections; an invalid selection throws.

返回： 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.

参数	类型	传递	说明
read	KnowledgeRead	必需	—

read 的字段

字段	类型	必需	说明
documentId	string	必需	只读。见类型定义及调用场景。
selection	SectionSelection	必需	只读。Must reference existing sections; an invalid selection throws.

返回： KnowledgeSnapshot。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Deterministic identity derived from document, revision and selection.
revision	string	必需	只读。Revision of the document that produced this content.
locale	string | undefined	可省略	只读。见类型定义及调用场景。
content	string	必需	只读。Rendered text, trimmed; sections are separated by blank lines.
documentId	string	必需	只读。见类型定义及调用场景。
selection	SectionSelection	必需	只读。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.

无调用参数。

返回： readonly string[]。

values

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

无调用参数。

返回： IterableIterator<Readonly<KnowledgeDocument>>。

entries

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

无调用参数。

返回： IterableIterator<readonly [string, Readonly<KnowledgeDocument>]>。

has

KnowledgeCatalog.has(id: string): boolean

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

返回： 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.

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

返回： Readonly<KnowledgeDocument> \| undefined。

返回值的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string	必需	只读。Stable document id; duplicate ids are rejected by the catalog.
revision	string	必需	只读。Revision label recorded in every snapshot so a citation names the exact content.
locale	string | undefined	可省略	只读。Locale of the content, when the App maintains translations.
parts	readonly KnowledgePart[]	必需	只读。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.

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

返回： Readonly<KnowledgeDocument>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Stable document id; duplicate ids are rejected by the catalog.
revision	string	必需	只读。Revision label recorded in every snapshot so a citation names the exact content.
locale	string | undefined	可省略	只读。Locale of the content, when the App maintains translations.
parts	readonly KnowledgePart[]	必需	只读。Ordered content.

使用示例

• Knowledge：资料、章节与证据快照：同一份资料合同支持普通对象与带锚点的文本；选读后得到明确版本的证据快照。

先读取一份普通对象资料

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

在相同 read 上增加章节与预算

配置 · 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);

相关策略源码

• 选读、预算和快照标识
• 文本章节解析与树编译

相关定义

• KnowledgeDocument
• KnowledgeRead
• KnowledgeSnapshot
• ReadonlyCatalog