informat.knowledgebase 知识库文档操作

概述

使用 informat.knowledgebase 可以查询当前应用的知识库模块、管理和检索文档、上传原始文件并异步处理，也可以创建脚本文档并覆盖写入 Markdown 正文。

典型调用流程如下：

1. 使用 createDocument 创建一个空文档并取得文档 ID；
2. 使用 writeDocument 写入完整正文并取得摄入任务 ID；
3. 在后续脚本或业务流程中使用 getIngestTaskStatus 查询处理结果。

使用限制

• moduleId 支持当前应用中已发布知识库模块的真实 ID 或模块标识符（module key）；建议先调用 queryModuleList() 获取真实 ID。
• writeDocument 只能覆盖通过 informat.knowledgebase.createDocument 创建的文档；上传的 PDF、Word 等文件可通过 reIngestDocument 使用原文件重新处理。
• writeDocument 是全量覆盖操作，不是追加写入。
• 文档正文不能为空，UTF-8 编码后的大小不能超过 15MB。

使用前准备与操作选择

目标知识库模块须已发布，并配置可用的向量模型；当前账号需要拥有对应操作权限。上传或写入返回任务 ID 后，应保存 moduleId、docId 和本次 taskId，在后续自动化、定时任务或其他脚本调用中查询处理结果。

业务需求	推荐调用	注意事项
从 Markdown 正文新建资料	createDocument → writeDocument	新建空文档尚未开始摄入，不能直接追加
导入已有文件	uploadDocument	提供原始文件名及标准 Base64 内容
替换脚本维护的整篇正文	writeDocument	全量覆盖，仅适用于脚本创建的文档
在现有文本末尾增补资料	appendDocument	保留原文；调用方提供换行和分隔符
原文不变，重新生成分块与向量	reIngestDocument	复用原始附件及已保存配置
判断资料是否可检索	getIngestTaskStatus	等待本次任务 COMPLETED 后再检索

getDocument().status 是文档当前状态，任务接口查询的是某一次写入、追加或重新处理的进度。连续修改同一文档时，必须记录每次返回的新 taskId，不能用旧任务的成功状态判断本次修改已经完成。

接口总览

所有操作使用当前执行上下文中的团队、应用和账号，不接收切换团队、应用或操作账号的参数。普通账号按模块检查操作权限；系统账号沿用应用脚本原有执行约定。模块模型配置与 API 密钥不通过以下接口返回。

方法	功能	模块权限
queryModuleList()	查询当前应用中可访问且有查询权限的知识库模块	模块访问及查询权限
queryDocumentList(moduleId, query)	查询模块内文档及处理状态	查询
getDocument(moduleId, documentId)	查询单篇文档元数据与处理状态	查询
uploadDocument(moduleId, document)	通过 Base64 上传原始文件并异步摄入	新增
reIngestDocument(moduleId, documentId)	使用原文件及已保存分块配置重新处理	更新
deleteDocument(moduleId, documentId)	删除文档及关联分块	删除
search(moduleId, keyword)	按模块配置检索文档内容	查询
createDocument(moduleId, document)	创建空的脚本文档	新增
writeDocument(moduleId, documentId, content)	全量覆盖脚本文档正文并异步摄入	更新
appendDocument(moduleId, documentId, content)	在已有 UTF-8 文本文档末尾追加资料并异步摄入	更新
getIngestTaskStatus(moduleId, taskId)	查询摄入任务状态与进度	查询

应用知识库本身随应用模块管理，本组脚本接口不创建或删除模块，也不提供内部目录管理。

queryModuleList

var modules = informat.knowledgebase.queryModuleList();

返回模块数组，每项包含 moduleId（真实 ID）、key（标识符）、name 和 icon。无可用模块时返回空数组。模块列表仅限当前应用，不会返回其他应用的知识库。

queryDocumentList

informat.knowledgebase.queryDocumentList(moduleId, query);

query 可传 null，也可包含以下条件。接口设计为多个条件共同生效；2026-10-19 UAT 验证发现部分筛选存在缺陷，修复版本部署前请按下方“当前版本筛选限制”处理：

字段	类型	说明
status	String	文档状态，例如 COMPLETED、FAILED
documentType	String	文档类型，例如 MARKDOWN、FAQ
documentName	String	文档名称筛选
createAccountId	String	创建账号 ID

返回当前模块内符合条件的文档安全视图数组，不提供分页参数；无匹配结果返回空数组。此接口查询整个模块，不接受目录筛选。

var documents = informat.knowledgebase.queryDocumentList(moduleId, {
    documentName: 'acceptance',
});

当前版本筛选限制

2026-10-19 UAT 实测：模块内有 4 篇已完成文档，其中 2 篇为 MARKDOWN、2 篇为 DEFAULT，创建人相同。发现以下问题，尚未在该次验收中修复：

查询条件	预期	UAT 实际结果
仅按 documentType: 'FAQ' 筛选	无匹配文档，返回空数组	返回全部 4 篇，类型筛选未生效
仅按不存在的 createAccountId 筛选	返回空数组	返回全部 4 篇，创建人筛选未生效
仅按 status: 'COMPLETED' 筛选	返回 4 篇	返回空数组
同时传 status: 'COMPLETED' 和 documentType: 'MARKDOWN'	返回 2 篇	返回 2 篇

上述测试均附加测试文档名称条件，以限定本轮资料范围。即使同时提供状态和类型，createAccountId 在该版本中仍会被忽略。不要将创建人筛选当作访问权限控制，也不要将仅按状态查询的空结果直接视为文档不存在。

修复版本部署并复验前，可仅传名称条件或 null，再在脚本中筛选返回结果：

var documents = informat.knowledgebase.queryDocumentList(moduleId, {
    documentName: 'acceptance',
});
var matched = [];
// documents 为平台返回的列表；逐项筛选，不对 Java 列表直接调用 JavaScript 的 filter。
for (var document of documents) {
    if (document.status === 'COMPLETED'
        && document.documentType === 'MARKDOWN'
        && document.createAccountId === accountId) {
        matched.push(document);
    }
}
// accountId 由业务调用方提供；matched 为筛选后的 JavaScript 数组。

此临时用法仍只读取当前账号有查询权限的目标模块，不会扩大团队、应用或模块范围。无分页接口在大文档量时会返回较多数据，业务脚本应控制调用频率。后续部署修复版本后，应先复验这几类条件，再恢复服务端组合筛选。

getDocument

var document = informat.knowledgebase.getDocument(moduleId, documentId);

documentId 使用创建、上传或列表接口返回的真实 ID。列表和详情返回相同的文档安全模型：

字段	说明
id、title、description	文档 ID、标题与描述
fileName、fileSize	原始文件名与文件大小（字节）
documentType、category	文档类型与分类
status、errorMessage	当前文档状态与处理错误信息
chunkCount	已生成的子分块数量
createAccountId	创建账号 ID
createdTime、updatedTime	创建时间与最后更新时间

不返回文件存储路径、附件存储 ID 或模型配置。文档不属于当前团队、应用或模块时抛出平台异常，不会返回其他范围的数据。

uploadDocument

informat.knowledgebase.uploadDocument(moduleId, document);

上传字段	类型	说明
name	String	必填，带扩展名的文件名，不能包含 /、\、空字符，不能为 . 或 ..
base64Content	String	必填，标准 Base64 文件内容；不接受 URL、服务器路径或 data:...;base64, 前缀；解码后最多 15MB，不接受空文件
documentType	String	可选，文档类型；省略时按文件扩展名推断
category	String	可选，文档分类
description	String	可选，文档描述
chunkConfig	Object	可选，父子分块配置，字段与 createDocument 相同；省略时使用文档类型推荐配置

返回 {docId, taskId}。文件解析、文档创建和任务提交失败时抛出异常；返回任务 ID 仅表示提交成功，向量摄入在后台异步执行。需在后续调用中查询任务状态。

var uploaded = informat.knowledgebase.uploadDocument(moduleId, {
    name: 'acceptance.md',
    // 标准Base64，解码后为“# Acceptance”及换行。
    base64Content: 'IyBBY2NlcHRhbmNlCg==',
    documentType: 'MARKDOWN',
    category: '验收',
});
// 保存uploaded.docId和uploaded.taskId，供后续调用使用。

原始文件保留在当前模块文件空间中以供后续重新处理；数据库事务回滚时清理本次新增的附件。

appendDocument

在已有文档的原始文件末尾追加文本，并创建新的异步摄入任务。对应团队知识库的 informat.company.appendKnowledgeBaseDocument，应用侧使用 informat.knowledgebase.appendDocument。

var result = informat.knowledgebase.appendDocument(
    moduleId,
    documentId,
    "\n\n## 新内容\n这里是追加的资料。"
);

参数	类型	描述
moduleId	String	当前应用中知识库模块的真实 ID 或标识符
documentId	String	当前模块内已有文档的真实 ID
content	String	非空的追加文本，原样拼接到原文件末尾；换行和分隔符由调用方提供

返回 {docId, taskId}：docId 保持不变，taskId 为本次新任务 ID。返回成功仅表示任务已提交；请在后续脚本中使用 getIngestTaskStatus(moduleId, result.taskId) 查询处理结果，不要在同一次脚本中循环忙等。

• 要求目标模块的更新权限；文档必须属于当前团队、当前应用和目标模块。
• 支持原始文件名为 .md、.markdown、.txt 的文档，扩展名不区分大小写；原文件及追加文本必须为有效 UTF-8。
• 支持通过页面上传、uploadDocument 上传及 createDocument 创建的文本文件，不局限于脚本创建来源。
• 文档状态为 PENDING 或 PROCESSING 时拒绝追加；脚本新建的空文档应先通过 writeDocument 写入并完成摄入。
• 合并后的 UTF-8 文件大小不能超过 15MB。不支持直接向 PDF、Word、Excel 等二进制原文件追加文本。
• 保留原文、文档 ID、标题、创建时间、分类和已保存分块配置；更新原始附件并重新摄入完整正文。
• 使用文档行锁保护并发修改；事务回滚时删除新附件，旧附件仅在事务成功提交后清理。

writeDocument 用于全量覆盖脚本文档正文，appendDocument 用于保留原文并在末尾追加。处理失败时先查询 taskId 和文档状态，核对原文件内容后再操作，避免重复提交同一段资料。

reIngestDocument

var retried = informat.knowledgebase.reIngestDocument(moduleId, documentId);

使用已保存原文件、文档类型和分块配置重新处理，不重新上传文件，不接收任意服务器路径。保留文档 ID，返回 {docId, taskId}；后续应使用本次返回的 taskId 查询进度。文档正在 PROCESSING 时拒绝重新处理，等待当前任务结束后再试。

deleteDocument

informat.knowledgebase.deleteDocument(moduleId, documentId);

删除指定模块内文档及关联分块，成功时无返回值。文档不存在或属于其他范围时抛出异常；正在 PROCESSING 的文档不能通过此接口删除。

search

var chunks = informat.knowledgebase.search(moduleId, 'Acceptance');

按指定模块保存的检索配置查询内容，不修改共享模块配置。空白关键词返回空数组；其他结果由现有检索引擎返回，包含分块内容和相关文档信息，具体评分等字段依检索配置而定。

search 只检索材料，不调用聊天模型生成回答。文档摄入完成前可能无法检索到新内容；应确认任务状态为 COMPLETED 后再使用。

// 这些ID来自前次上传结果，在后续脚本中使用，不在单次脚本里循环忙等。
var task = informat.knowledgebase.getIngestTaskStatus(moduleId, taskId);
if (task.status === 'COMPLETED') {
    var chunks = informat.knowledgebase.search(moduleId, 'Acceptance');
} else if (task.status === 'FAILED') {
    informat.console.log(task.errorMessage);
}

createDocument

在目标知识库模块中创建一个空的脚本文档，并返回文档 ID。文档创建后状态为 PENDING，调用 writeDocument 写入正文后才会开始摄入。

informat.knowledgebase.createDocument(moduleId, document);

参数	类型	描述
moduleId	String	当前应用中知识库模块的真实 ID 或标识符
document	Object	文档配置

document 支持以下属性：

属性	类型	必填	描述
name	String	是	文档名称
category	String	否	文档分类
description	String	否	文档描述
documentType	String	否	文档类型，默认为 MARKDOWN
chunkConfig	Object	否	自定义分块配置；不传时使用文档类型的推荐配置

documentType 支持以下值：

值	适用内容
DEFAULT	通用文本
CODE	代码文档
API	API 文档
MARKDOWN	Markdown 文档
FAQ	常见问题
ARTICLE	文章
TABLE	表格型文本
EXCEL	Excel 转换后的文本
CUSTOM	使用自定义分隔符的文本

chunkConfig 支持以下属性：

属性	类型	默认值	描述
parentMaxLen	Integer	1500	父分块最大字符数
childMaxLen	Integer	400	子分块最大字符数
childMinLen	Integer	80	子分块最小字符数
childOverlapLen	Integer	50	相邻子分块重叠字符数
enableOverlap	Boolean	true	是否启用子分块重叠
parentSeparator	String	\\n\\n	父块分隔符，仅 CUSTOM 类型使用
childSeparator	String	\\n	子块分隔符，仅 CUSTOM 类型使用

返回值

文档 ID，类型为 String。

示例

const documentId = informat.knowledgebase.createDocument('knowledgeModuleId', {
    name: '产品接口说明',
    category: '技术文档',
    description: '由应用脚本自动维护',
    documentType: 'MARKDOWN',
    chunkConfig: {
        parentMaxLen: 1500,
        childMaxLen: 400,
        childMinLen: 80,
        childOverlapLen: 50,
        enableOverlap: true,
    },
});

调用账号需要拥有目标知识库模块的新增权限。

writeDocument

全量覆盖目标脚本文档的正文，并提交异步摄入任务。

informat.knowledgebase.writeDocument(moduleId, documentId, content);

参数	类型	描述
moduleId	String	当前应用中知识库模块的真实 ID 或标识符
documentId	String	createDocument 返回的文档 ID
content	String	完整的 Markdown 正文

返回值

返回值类型为 Object，包含以下属性：

属性	类型	描述
docId	String	文档 ID
taskId	String	异步摄入任务 ID

示例

const result = informat.knowledgebase.writeDocument(
    'knowledgeModuleId',
    documentId,
    `# 产品接口说明

## 创建订单

调用创建订单接口前，需要先取得访问令牌。`,
);

informat.console.log(`文档ID：${result.docId}`);
informat.console.log(`任务ID：${result.taskId}`);

调用账号需要拥有目标知识库模块的更新权限。同一文档处于 PROCESSING 状态时不能再次覆盖，等待当前任务完成或失败后再重新写入。

数据一致性

写入操作会协调源文件替换、旧分块清理和摄入任务创建。数据库事务失败时，新文件和 Redis 任务会执行补偿清理；事务提交后，旧源文件才会删除。

getIngestTaskStatus

查询异步摄入任务状态。

informat.knowledgebase.getIngestTaskStatus(moduleId, taskId);

参数	类型	描述
moduleId	String	任务所属知识库模块的真实 ID
taskId	String	writeDocument 返回的任务 ID

返回值

返回值类型为 Object，包含以下属性：

属性	类型	描述
taskId	String	任务 ID
docId	String	文档 ID
status	String	任务状态
totalChunks	Integer	总子分块数
processedChunks	Integer	已处理子分块数
progress	Number	处理进度百分比
errorMessage	String	失败原因；任务未失败时为空
startTime	String	ISO-8601 格式的开始时间
endTime	String	ISO-8601 格式的结束时间；任务未结束时为空
duration	Long	执行时长，单位为毫秒

status 可能为以下值：

状态	描述
PENDING	任务已创建，等待执行
PROCESSING	正在分块并生成向量数据
COMPLETED	摄入完成，文档可以用于检索
FAILED	摄入失败，可通过 errorMessage 查看原因

示例

const task = informat.knowledgebase.getIngestTaskStatus(
    'knowledgeModuleId',
    taskId,
);

if (task.status === 'COMPLETED') {
    informat.console.log(`摄入完成，共生成 ${task.totalChunks} 个子分块`);
} else if (task.status === 'FAILED') {
    throw new Error(task.errorMessage || '知识库文档摄入失败');
} else {
    informat.console.log(`当前进度：${task.progress}%`);
}

调用账号需要拥有目标知识库模块的查询权限。任务记录在 Redis 中保存 7 天，过期后不能再通过任务 ID 查询。

不要在脚本中忙等待

摄入任务在后台异步执行。不要使用循环持续查询任务状态，否则会长时间占用脚本执行线程。可以在后续自动化、定时任务或其他业务入口中查询处理结果。

服务重启与任务恢复

摄入任务的状态、租户上下文和待处理正文都保存在 Redis 中，不依赖服务进程内存。服务重启后，系统会定期扫描 PENDING 和 PROCESSING 任务并恢复执行。

• 恢复任务使用任务级分布式锁，避免多个服务节点重复处理同一任务；
• 已经完整写入数据库的父分块会作为续传断点，不会从头重复写入；
• Redis 不可用时，任务创建会直接失败并回滚，不会降级为仅保存在内存中的任务；
• 状态为 FAILED 的任务不会自动重试。排除错误后，可以再次调用 writeDocument 创建新的摄入任务。

服务刚恢复时，任务可能短暂保持 PENDING 或 PROCESSING，通常会在下一次恢复扫描后继续执行。

完整示例

export function publishGuide(moduleId, markdown) {
    const documentId = informat.knowledgebase.createDocument(moduleId, {
        name: '应用使用指南',
        category: '产品文档',
        description: '由发布脚本维护',
        documentType: 'MARKDOWN',
    });

    return informat.knowledgebase.writeDocument(
        moduleId,
        documentId,
        markdown,
    );
}

export function getPublishStatus(moduleId, taskId) {
    return informat.knowledgebase.getIngestTaskStatus(moduleId, taskId);
}

常见问题

提示模块不存在或不是知识库模块

确认传入的是当前应用中已发布知识库模块的真实 ID 或模块标识符，不能使用模块显示名称；可通过 queryModuleList() 获取真实 ID。

提示只能写入 informat.knowledgebase 创建的文档

writeDocument 不能覆盖通过界面上传或其他入口创建的文档。请先调用 createDocument，再使用返回的文档 ID 写入正文。

文档长时间保持 PENDING

检查 Redis、向量模型和知识库模块配置是否可用。服务重启或异步线程池繁忙时，任务会由恢复扫描重新调度。

任务状态为 FAILED

查看 errorMessage，检查向量模型配置、网络连接和正文分块配置。修复问题后再次调用 writeDocument。

追加完成后怎样确认原文没有丢失

先确认本次追加返回的任务为 COMPLETED，再分别用原文和新增资料中的唯一关键词调用 search，核对返回的 docId 和 content。2026-10-19 UAT 已验证连续两次追加后，原文及两次新增资料均可被检索到；对上传的 Markdown 和大写 .TXT 原文件也完成了追加验证。

追加请求超时或处理失败时，不要直接重复发送同一段内容。先核对文档状态、任务状态和原始资料，避免把相同内容追加两次；如原始资料已成功更新而摄入失败，可在排除配置或模型问题后使用 reIngestDocument 重新处理。

UAT 验证覆盖与未覆盖范围

2026-10-19 在 UAT 应用的设计器脚本调试入口实测全部 11 个接口。模块列表、文档详情、创建、覆盖写入、文件上传、追加、重新处理、任务状态、检索和删除的主流程通过；文档列表的部分筛选失败，详见“当前版本筛选限制”，该次验收不代表全部功能通过。

同时验证了跨模块文档与任务访问拒绝、处理中重复追加和删除拒绝、上传文档不能被 writeDocument 覆盖、非法 Base64、路径文件名、空文件、不合法分块配置以及超过大小上限的请求拒绝。删除测试文档后，列表和检索中均不再出现这些测试资料。

该次验证使用当前登录账号，未覆盖不同权限角色，也未验证服务重启、Redis 故障恢复或所有文件格式。验收结束后已删除测试文档和临时脚本，并还原本轮未发布的应用草稿，未发布应用。