Knowledge

KIT · constant · 运行时值

导入

TypeScript

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

JavaScript

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

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

定义

成员目录

成员	用途
defineKnowledgeCatalog	完整输入输出见下方重载。
parseKnowledgeDocument	完整输入输出见下方重载。
defineKnowledgePublication	完整输入输出见下方重载。

成员详情

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.

参数	类型	传递	说明
documents	readonly KnowledgeDocument[]	必需	—
options	KnowledgeCatalogOptions	可省略	—

options 的字段

字段	类型	必需	说明
maxChars	number | undefined	可省略	只读。Maximum characters per read; exceeding it throws a RangeError.
observe	((snapshot: KnowledgeSnapshot) => void | Promise<void>) | undefined	可省略	只读。Observer invoked with every produced snapshot.

返回： KnowledgeCatalog。

返回值结构

字段	类型	必需	说明
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.

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.

参数	类型	传递	说明
input	{ id: string; revision: string; text: string; locale?: string; }	必需	—

input 的字段

字段	类型	必需	说明
id	string	必需	见类型定义及调用场景。
revision	string	必需	见类型定义及调用场景。
text	string	必需	见类型定义及调用场景。
locale	string | undefined	可省略	见类型定义及调用场景。

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

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.

类型参数	约束	默认类型
App	—	—

参数	类型	传递	说明
options	KnowledgePublicationOptions<App>	必需	—

options 的字段

字段	类型	必需	说明
store	KnowledgePublicationStore	必需	只读。见类型定义及调用场景。
requiredReads	readonly KnowledgeRead[] | undefined	可省略	只读。Reads that must succeed against every compiled document set, proving sections still exist.
maxReadChars	number | undefined	可省略	只读。Per-read character budget applied by the catalog compiler.
maxCandidates	number | undefined	可省略	只读。Maximum pending candidates retained; defaults to 32 and must be a positive integer.
candidateRetentionMs	number | undefined	可省略	只读。Candidate retention window; defaults to seven days.
now	(() => number) | undefined	可省略	只读。Clock override for timestamps and expiry; defaults to Date.now.
authorize	(operation: (typeof knowledgePublicationOperations)[number], context: OperationContext<App>) => MaybePromise<void>	必需	Guards one operation before any read or write.
verifySources	(sources: readonly KnowledgeSourceReference[], context: OperationContext<App>) => MaybePromise<void>	必需	Validate real provenance/revisions/visibility. A model's source list is not a grant.

返回： KnowledgePublication<App>。

返回值结构

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

使用示例

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

换成文本适配器，后续目录与读取完全相同

扩展 · Node.js

成对锚点必须匹配；标记仅是文本适配器的一种输入，Core 不要求资料必须存成 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);

相关策略源码

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

相关定义

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