Knowledge：资料、章节与证据快照
同一份资料合同支持普通对象与带锚点的文本；选读后得到明确版本的证据快照。
defineKnowledgeCatalog(documents, options?) 编译资料树，拒绝重复文档/章节、无版本、循环结构。read({documentId,selection}) 返回 {documentId,selection,revision,locale,content,id}。selection.mode 可为 document、self 或 subtree；self/subtree 还需非空、无重复的 sectionIds。self 只读该章节自己的文本，subtree 包含其子章节。
maxChars 限制本次选中且 trim 后的正文，超限抛错，不静默截断。assertSelection 只检查引用和选择形状，不执行正文预算校验。sectionIds 查看真实章节；普通 get/require 返回已编译资料定义。
revision 由 App 提供，id 是基于资料身份、版本、语言与选读序列化的快照标识，不是正文 hash、权限凭据或数据库 ID。相同 revision 下不能偷偷改内容；后续生成、复核应传递同一快照。文件加载、来源可信度、权限和发布不属于这个 Kit。
由简到繁的同业务示例
先读取一份普通对象资料
入门 · Node.js
ts
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);js
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
ts
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);js
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。
ts
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);js
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);