nocobase-ai-knowledge-base-manager

目标

为 NocoBase AI 知识库提供一种按版本感知、以能力为先的工作流。开始前说明需要专业版或更高版本；通过实际情况证明授权、插件和运行时能力，不要猜测版本；如果必需插件已安装但未启用，询问用户是否要启用，并在获得用户明确同意后通过插件管理启用；随后安全地管理向量数据库、知识库、文档、检索测试和员工绑定输入。

必需依赖

• @nocobase/plugin-ai-knowledge-base 是商业插件，最低要求为专业版；企业版也受支持，社区版和标准版不受支持。
• 必须先启用 @nocobase/plugin-ai，知识库插件才能运行。
• 只有在此技能的能力预检通过，且所选 KB 类型需要 LLM/嵌入前置条件时，才运行 nocobase-ai-manager。
• 本地文档工作流还需要可用的文件存储；ZIP/后台处理取决于当前启用的异步任务能力。
• 最终员工记录写入由 nocobase-ai-employee 负责；此技能负责准备并验证绑定输入。

范围

• 分别判定知识库授权、插件安装/启用状态、API 能力和 ACL。
• 如果必需插件已安装但未启用，询问用户是否要在指定环境中启用指定软件包；获得用户明确同意后，使用 nocobase-plugin-manage 启用，验证启用后的状态，刷新运行时元数据，并继续预检。
• 发现、测试、创建、更新、验证并安全删除 PGVector 数据库配置。
• 推荐并维护 LOCAL、READONLY 和 EXTERNAL 知识库。
• 列出、获取、上传、独立地重新向量化/重试并安全删除文档。
• 运行独立的语义命中测试。
• 准备并验证 AI 员工绑定交接信息，包括已启用的 KB 键和检索默认值。
• 严格遵守不可变字段、异步完成边界、受保护的密钥以及反向依赖清理规则。

非目标

• 不要根据缺少 kb 命令、缺少许可证密钥、nb env info 或 nb license status 来声称当前版本。
• 不要在此技能中安装、同步或禁用插件。只有在用户明确同意后，才能通过 nocobase-plugin-manage 启用已安装但未启用的必需插件；如果该工作流可用，不要只是告诉用户运行命令。
• 不要配置已保存的 LLM 服务；通过能力预检后使用 nocobase-ai-manager。
• 不要直接写入 AI 员工记录；最终的绑定/解绑更新应使用 nocobase-ai-employee。
• 不要管理知识库分段、隐藏的向量存储变更操作或专用异步任务命令。
• 不要自动轮询上传、ZIP 导入、分段或向量化的完成状态。
• 上传成功后不要询问是否要进行向量化；上传操作已经启动或排队等待向量化。
• 不要绕过 ACL、依赖保护、现有表确认或不可变字段规则。

输入契约

输入项	必填	默认值	验证	澄清问题
action	是	对知识库意图请求使用 preflight，否则使用 inspect	必须是 preflight/inspect/create/update/upload/revectorize/test/prepare-binding/delete 之一	“我应该执行哪种知识库操作？”
target	变更操作：是	对预检使用 capability	必须是 capability/vector-db/knowledge-base/document/employee 之一	“我应该管理哪种资源？”
env	否	当前环境，取自 nb env list	已配置、可访问且已通过身份验证	“我应该针对哪个 NocoBase CLI 环境？”
identifier	对 update/upload/revectorize/test/prepare-binding/delete：是	无	准确的向量键、知识库键/ID、文档 ID 或员工用户名	“确切的目标标识符是什么？”
knowledgeBaseType	对 create：是	建议使用 LOCAL；仅凭建议不得执行变更	必须是 LOCAL/READONLY/EXTERNAL 之一	“应该由 NocoBase 管理文档（Local）、读取外部 PGVector 数据（Readonly），还是使用外部提供商？”
configurationMode	对 vector-db create/update：是	无；绝不隐式选择	必须是 direct-cli/ui 之一	“此向量数据库连接应该使用直接 CLI 参数，还是 NocoBase UI 流程？”
payload	对直接 CLI 的 create/update 或 test/prepare-binding：是	仅在用户接受时使用文档中说明的产品默认值	符合特定类型的允许字段和值范围	“应该使用哪些向量、知识库、检索或绑定参数？”
file	对 upload：是	无	可读取且受支持的文件或 ZIP；知识库必须为 LOCAL	“应该将哪个文件上传到哪个 Local 知识库？”
pluginEnableConsent	必需插件处于 installed-disabled 状态时必填	无；绝不假定用户已同意	针对确切的软件包名称和环境的明确批准	“必需插件已安装，但在 <env> 中处于禁用状态。现在启用 <package> 并继续知识库预检吗？”
confirmation	高风险操作：是	无	展示影响后，针对确切目标进行的最新确认	“确认执行这项确切的破坏性操作或依赖项变更吗？”

规则：

• 如果缺少必填输入，停止变更并向用户询问缺少的值。
• 对每个知识库意图请求，在探测能力前说明最低版本要求。
• 如果用户说“由你决定”，执行预检/检查，并建议在常规的托管文档场景中使用 LOCAL；不要创建或执行变更。
• 根据实际的 list/get 结果解析标识符；绝不猜测 ID 或键。
• 创建或更改向量数据库连接前，必须明确选择 direct-cli 或 ui；不要替用户选择。
• 对于 ui，使用 AI 管理器文档中说明的 UI 模式工作流，等待用户完成操作，并独立验证向量数据库字段安全后再继续。
• 如果必需插件已安装但处于禁用状态，且可管理插件，不要止步于手动启用说明；应征求用户同意，并在获得批准后执行启用操作。
• 如果用户拒绝启用，则在执行知识库变更前停止，并报告插件仍处于禁用状态。
• 普通上传成功、ZIP 任务提交、重新向量化受理、命中测试结果和操作完成，是彼此不同的结果。
• 每次删除都必须在执行对应的 destroy 前立即单独获得最新确认。

强制确认门槛

• 最多确认轮数：2。
• 每轮最多提问：3。
• 启用必需插件前，展示确切的环境和软件包名称，说明插件运行时状态将发生变化，并要求用户明确同意。
• 同意启用一个软件包，并不代表授权启用其他任何软件包；仅当 @nocobase/plugin-ai 也处于已安装但未启用状态且确有需要时，才将其一并列入请求。
• 获得同意后，在安全模式下使用 nocobase-plugin-manage，要求读取并确认插件列表，刷新环境，然后重新执行知识库 API/ACL 检查。如果用户拒绝同意或启用失败，须在修改知识库前停止。
• 创建或更新向量数据库前，必须确认 configurationMode。对于 ui，仅当知识库功能检查通过后，才移交给 nocobase-ai-manager；对于 direct-cli，在此技能中继续操作。
• 使用 skipTableExistedCheck=true 前，必须收到服务器返回的 TABLE_ALREADY_EXISTS，并获得明确的表复用确认。
• 更改不可变字段或向量依赖项前，须停止操作，或展示确切的迁移/检索影响，并视情况取得确认。
• 删除任何向量数据库、知识库或文档前，必须展示确切的目标、环境、依赖项、数据影响和回滚限制，然后在执行该项删除前立即重新取得确认。
• 如果授权证据未知，仅当确切的知识库插件已安装并启用、生成的知识库命令可用、安全的知识库读取成功且 ACL 允许时，才可继续。插件/运行时/ACL 证据未知或相互冲突时，必须停止修改。

工作流

1. 确认目标环境，并立即说明：@nocobase/plugin-ai-knowledge-base 需要 NocoBase Professional Edition 或更高版本。
2. 阅读版本与功能预检。检查可用的许可证证明、已安装/已启用的插件状态、基础 AI 依赖、运行时刷新、生成的 kb 帮助信息，以及安全读取。
3. 如果已安装但未启用 @nocobase/plugin-ai-knowledge-base 或其基础依赖 @nocobase/plugin-ai，请显示确切的包名称和环境，并询问是否启用。如果用户同意，调用 nocobase-plugin-manage 并设置 action=enable，验证启用后的状态，刷新运行时，并继续预检。如果用户拒绝或操作失败，则停止，不修改 KB；不要让用户自行运行启用命令。
4. 如果在适用的、基于用户同意的启用和刷新之后，运行时仍不具备相关功能，则停止，不修改大模型、嵌入、存储、PGVector、KB、文档或员工数据。不要根据薄弱证据猜测是 Community Edition。
5. 检查当前的向量数据库、知识库、文档、存储和所请求的员工上下文；阅读命令映射。
6. 选择 KB 类型。一般托管文档建议使用 LOCAL；仅对外部维护的 PGVector 数据使用 READONLY，仅在存在提供方时使用 EXTERNAL。
7. 对于 LOCAL/READONLY，运行 nocobase-ai-manager，并使用一个已启用的服务、仅聊天的已保存模型配置，以及单独发现的嵌入模型。对于 LOCAL，还要确定文件存储。
8. 对于 PGVector 创建/更新，首先要求用户选择 direct-cli 或 ui。在 ui 模式下，通过功能检查后将操作交接给 nocobase-ai-manager，等待用户完成，并使用其独立的安全字段回读结果。在 direct-cli 模式下，遵循向量数据库工作流：发现提供方、执行受保护的连接测试、创建/更新、检查表复用条件、评估依赖影响，并进行安全回读。
9. 对于 KB 创建/更新，遵循知识库与文档：类型字段、不可变的键/存储规则、分段默认值、向量变更影响、单次写入和回读。
10. 对于上传，验证 Local 类型和文件限制，执行一次 multipart 上传，然后报告已接受的自动后台处理；不要轮询或声称处理已完成。
11. 仅在用户单独请求重试/重建时运行文档 vectorization。仅在用户明确请求时运行命中测试；这两项都不是上传后的自动操作。
12. 对于员工绑定，遵循AI 员工绑定，准备确切的已启用键、提示词/默认值/范围要求，并将最终写入交接给 nocobase-ai-employee。
13. 对于清理操作，按依赖关系逆序进行，并在每个破坏性步骤前分别获取最新确认。
14. 分别报告预检证据、适用时的用户同意与插件后置状态、写入、回读、已接受的异步任务、部分成功、回滚限制，以及尚待处理的交接事项。

参考资料加载图

参考资料	适用场景	说明
版本和能力预检	任何涉及 KB 资源、文档、检索或绑定的请求。	专业版及更高版本的披露要求、证据层级、状态以及停止／继续矩阵。
命令图	选择许可证、插件、运行时、KB、存储、文档或交接命令。	包含排除的操作范围。
向量数据库	测试或更改 PGVector 配置。	密钥、表验证／复用、依赖项、回读。
知识库和文档	选择 KB 类型、创建／更新 KB、上传、重试、测试或删除。	不可变字段、文件限制、后台语义和默认值。
AI 员工绑定	准备绑定或解绑请求。	最终的员工写入操作委托给 AI 员工技能。

安全门槛

以下高风险操作属于重大影响操作：

• 删除任何向量数据库、知识库和文档；
• 复用现有 PGVector 表；
• 更改向量数据库、LLM 服务、嵌入模型或外部向量存储配置；
• 尝试更改不可变的 KB 键或 Local 存储；
• 暴露数据库密码或 vectorStoreProps[].value；
• 未获得对确切软件包／环境的明确许可就启用 Plugin；
• 明知能力证据表明未获许可、已禁用、不可用、存在冲突或未知，仍继续操作；
• 未经 AI 员工技能确认就更改员工 KB 答案来源。

二次确认模板：

• “确认执行：在 <env> 中对 <resource identifier> 执行 <action>。预期影响：<table/data/retrieval/employee dependency impact>。输入 confirm 继续。”

回滚指引：

• 创建不匹配：删除新建的向量／KB 对象需要另行进行全新的确认。
• 更新不匹配：恢复之前的非机密可写字段；必须重新提供机密信息。
• 更改不可变的键／存储：不要修补；应改为规划新 KB 并明确迁移方案。
• 上传、ZIP 任务提交和已接受的后台处理可能无法撤销。
• 因依赖项受阻而无法删除：保留该对象；切勿绕过防护机制。
• Plugin 启用失败：保留观察到的操作后状态，不要自动禁用或无限重试；任何回滚禁用操作都必须先征求许可。

验证清单

• 在开展知识库工作前，已说明 Professional+ 最低要求。
• 分别报告了授权、插件状态、运行时能力和 ACL。
• 没有仅凭缺少命令或许可证元数据推断版本。
• 对已安装但已禁用的必需插件，询问了是否同意在指定环境中启用该插件，而非仅指示用户手动操作。
• 获批启用后使用 nocobase-plugin-manage；恢复运行时/API/ACL 检查前，已确认插件处于启用状态。
• 执行任何变更前，已验证 @nocobase/plugin-ai 和 KB 插件的运行时能力。
• 用户拒绝启用或启用失败时，在修改 KB 前停止。
• 仅在能力检查通过后，才使用所需的 LLM/embedding 就绪状态。
• 已保存服务的 enabledModels 仅包含聊天模型；embedding 单独配置。
• 目标 KB 类型及所有条件字段均有效。
• KB key 和 Local 存储的不可变性得到保障。
• 分段选项满足 chunkOverlap < chunkSize。
• 每次创建或更新向量数据库前，都明确选择了 direct-cli 或 ui；UI 模式会暂停以等待用户完成操作，并通过独立的安全字段回读检查。
• 通过 direct-CLI 创建或更新前，PGVector 连接测试成功。
• 仅在出现 TABLE_ALREADY_EXISTS 并获得明确确认后，才复用现有表。
• 每次创建或更新向量数据库/KB 后，均进行安全回读检查。
• 上传结果报告为已接收/已排队，而非已完成；已检查支持的文件/PDF/ZIP 限制。
• 仅在用户独立提出请求时才进行重新向量化和命中测试。
• 绑定交接包含可用能力、已启用的 key、提示词占位符和检索范围。
• 每次销毁操作执行前，都针对确切目标重新获取最新确认。
• 摘要和输出中不包含机密信息。
• 至少正确报告一个允许的案例和一个受阻案例。
• 分别说明错误、部分成功、异步状态不确定性、回滚限制和交接事项。

最小测试场景

1. 能力验证成功：在已获许可或可运行的开发环境中，插件已启用、KB API 已生成，且安全读取均成功。
2. 用户同意启用已禁用的插件：询问是否在目标环境中启用确切的已安装但已禁用的程序包；获批后通过插件管理启用，确认启用后的状态，刷新运行时元数据，并继续检查 KB API/ACL。
3. 用户拒绝启用已禁用的插件：保留禁用状态，不执行任何 KB 变更，并报告受阻的后续步骤，而不指示用户手动运行命令。
4. 明确的授权限制：商业插件列表不包含 KB 程序包，且不执行任何变更。
5. 授权状态未知但插件可运行：运行时能力检查成功，版本仍未验证；说明 Professional+ 要求后，可继续进行安全的 KB 操作。
6. Local 正常流程：准备存储/LLM/embedding/PGVector，创建 KB，上传受支持的文件，并报告后台自动处理，不进行轮询。
7. 向量数据库 UI 模式：能力检查通过后，将 UI 流程交由 AI 管理员处理，等待用户明确确认完成，并在继续 KB 工作前验证向量数据库的安全字段。
8. 无效更新：尝试更改 KB key 或 Local 存储，并确认写入被拒绝，同时提供迁移指导。
9. 员工绑定：准备有效的交接，然后将最终的开关/提示词/检索写入操作委派给 AI 员工技能。
10. 身份验证/能力失败：区分 401/403 与许可证/插件缺失，并在执行任何变更前停止。
11. 高风险清理：删除每个文档、KB 和向量数据库前，均须单独获取最新确认。

输出约定

最终回复必须包含：

• 目标环境、请求的操作、资源类型和标识符；
• 最低版本声明和软件包名称；
• 权益、插件操作前状态、启用同意与结果、插件操作后状态、运行时/API 能力以及 ACL 证据；
• 所选向量数据库的 direct-cli 或 ui 模式，以及适用时的 UI 完成情况和回读结果；
• 已使用的前置 LLM/嵌入/存储/向量结果；
• 已执行的命令，不含密钥值；
• 配置写入的安全字段回读结果；
• 上传/任务/重新向量化/命中测试的结果及异步边界；
• 相关时的员工绑定交接；
• 受保护的操作、依赖错误、部分成功、回滚限制和剩余工作；
• 应用的默认值或假设。

参考资料

• NocoBase 知识库文档：用于了解当前的知识库类型、向量配置、文档、RAG 和产品行为。[已验证：2026-08-01]
• NocoBase CLI 文档：用于了解当前的 env、license-plugin、plugin-list 和生成的 API 命令。[已验证：2026-08-01]
• 版本与能力预检：用于 Professional+ 门槛判断和证据分类。
• 命令映射：用于选择受支持的命令。
• 向量数据库：用于 PGVector 的安全性和生命周期。
• 知识库与文档：用于类型选择、不可变字段、文档和后台处理。
• AI 员工绑定：用于经过验证的绑定交接。