nocobase-ai-manager

目标

准备并维护 AI 员工所需的 NocoBase AI 核心运行环境和已保存的 LLM 服务；只有在商业功能门槛通过后，才为知识库准备这些服务。配置 LLM 服务和向量数据库连接时，必须明确选择直接使用 CLI 参数还是使用 UI 流程，并将聊天模型配置、嵌入模型发现、凭据、依赖检查和验证分开处理，明确说明。

范围

• 确认目标 nb 环境、身份验证、运行时刷新情况，以及生成的 ai 命令界面。
• 发现 LLM 提供商、尚未保存的提供商模型、已保存的服务、聊天模型和嵌入模型。
• 测试提供商设置，以及创建、更新、启用、禁用、验证或安全删除已保存的 LLM 服务。
• 创建或更改 LLM 服务或向量数据库连接配置前，要求用户选择直接使用 CLI 参数还是使用文档化的 UI 流程；后续操作前验证用户完成的 UI 操作。
• 为 nocobase-ai-employee 生成结构化的核心 AI 就绪情况结果。
• 仅在 nocobase-ai-knowledge-base-manager 确认知识库功能可用后，为其生成有条件的 LLM/嵌入模型前置条件。
• 在进行可能造成影响的 LLM 服务变更前，检查员工和知识库依赖关系。

非目标

• 不维护 AI 员工记录；使用 nocobase-ai-employee。
• 不编写向量数据库、知识库或文档配置。对于向量数据库连接配置，仅负责模式选择和 UI 流程安全；直接 CLI 配置和知识库功能检查交由 nocobase-ai-knowledge-base-manager 处理。
• 不将缺少 kb 命令视为社区版的证明。
• 不管理 AI 工具、技能、全局设置、角色、员工模板或移动操作。
• 不直接启用或禁用插件；使用插件管理工作流。
• 存在受支持的 nb api 命令时，不使用 curl、直接修改数据库、隐藏操作或从包含密钥的响应中复制值。

输入约定

输入	必填	默认值	验证	澄清问题
action	是	inspect	必须是 inspect/configure/update/delete/verify 之一	“我应该执行哪项 AI 前置条件操作？”
target	修改操作必填	检查时为 llm-provider	必须是 llm-provider/llm-service/vector-db 之一；vector-db 仅用于路由/UI	“应该检查提供商、管理已保存的 LLM 服务，还是路由向量数据库连接配置？”
consumer	否	core-ai	必须是 core-ai/employee/knowledge-base 之一	“此就绪状态检查是针对核心 AI、AI 员工还是知识库？”
env	否	当前环境，来自 nb env list	已配置、可访问且已通过身份验证	“应该使用哪个 NocoBase CLI 环境？”
identifier	更新/删除/验证时视情况必填	无	精确的已保存 LLM 服务 name，或用于 UI 更新的向量数据库标识符	“服务的确切名称或向量数据库标识符是什么？”
configurationMode	配置/更新 llm-service 或 vector-db 时必填	无；绝不隐式选择	必须是 direct-cli/ui 之一	“此配置应使用直接 CLI 参数还是 NocoBase UI 流程？”
payload	通过直接 CLI 配置/更新 llm-service 时必填	无	仅允许指定字段；密钥由用户提供	“应使用哪个提供商、聊天模型、选项和启用状态？”
knowledgeBaseCapability	consumer=knowledge-base 或 target=vector-db 时，在修改/打开 UI 前必填	无	来自 nocobase-ai-knowledge-base-manager 且 runtimeCapability=available 的就绪状态结果	“知识库版本/插件能力预检是否已通过？”
confirmation	高风险操作时必填	无	显示确切目标和影响后，获得即时明确确认	“确认对这个确切的 LLM 服务进行此项有影响的更改吗？”

规则：

• 如果缺少必需输入或能力证据，请停止修改并请求澄清。
• 如果用户说“由你决定”，则仅进行检查并给出建议；不得创建、更新、禁用或删除。
• 绝不编造凭据、提供商密钥、服务名称、模型标识符、基础 URL 或隐藏 ID。
• 在创建或更改 LLM 服务或向量数据库连接配置之前，请让用户选择 direct-cli 或 ui；不得代替用户选择。
• 在 UI 模式下，仅使用有文档说明的 --ui 标志和可选的提供商选择。绝不包含请求正文中的字段、凭据或密钥。
• --ui 命令只会打开表单。打开后即停止；只有在用户报告完成后才继续，并且必须在任何依赖操作之前独立验证安全字段。
• enabledModels.models 仅接受大语言/聊天模型。绝不要将嵌入模型放在其中。
• 单独发现嵌入模型，并且仅在知识库配置时返回。
• 不得将创建操作悄悄转换为更新操作。

强制确认关卡

• 最多澄清轮数：2。
• 每轮最多提问：3 个。
• 修改前，确认环境、准确的服务／资源标识符、提供商、预期的聊天模型、启用状态、密钥来源、使用方和依赖影响。
• 配置／更新 LLM 服务或向量数据库连接前，必须明确指定 configurationMode。若为 ui，确认当前帮助信息中包含 --ui；打开表单后，等待用户明确表示已完成，然后独立读取并核验。
• 对于 target=vector-db，打开 UI 或将直接 CLI 操作交给知识库管理器之前，必须确认当前具备知识库能力。
• 对于知识库使用方，必须从 nocobase-ai-knowledge-base-manager 获取当前能力结果；此技能不会执行或绕过商业版门槛。
• 禁用、更换提供商、移除聊天模型或删除之前，检查所有可读取的员工和知识库依赖。
• 如果无法检查知识库依赖，则将依赖状态视为 unknown，并阻止会造成破坏的服务变更。
• 每次删除服务之前，展示确切的服务、环境、依赖和不可逆性，然后在执行 destroy 前立即获取一次新的二次确认。
• 在安全的临时文件处理机制准备就绪前，绝不执行包含密钥的命令。

工作流

1. 使用 nb env list 确定目标环境；nb env info <env> 仅用于获取环境、API、数据库和身份验证上下文，不用于检测版本。
2. 运行 nb env update <env> --verbose，然后检查 nb api ai --help、nb api ai llm-providers --help 和 nb api ai llm-services --help。
3. 阅读命令映射和 UI 模式工作流，然后仅选择当前帮助信息已确认的命令。
4. 创建或更改 LLM 服务或向量数据库连接前，请用户选择 direct-cli 或 ui；绝不推断模式。
5. 对于 ui，要求当前帮助信息中包含 --ui。对于向量数据库，还必须要求提供可用的知识库能力结果。仅运行文档中说明的 UI 命令，最多附带其可选的提供商标志；等待用户完成表单，然后独立读取安全字段，再继续操作。
6. 对于使用 direct-cli 的 target=vector-db，将操作交给 nocobase-ai-knowledge-base-manager；此技能不会写入向量数据库配置。
7. 检查提供商和模型。在构建任何直接写入 LLM 服务的操作之前，将发现的每个模型归类为聊天／LLM 模型或嵌入模型。
8. 对于新的或有更改的直接 CLI 提供商设置，使用受保护的正文文件，发现尚未保存的模型，并在保存前使用聊天模型运行 test-flight。
9. 查询确切的服务名称。如果不存在，则创建；如果存在且安全字段等效，则报告已满足；如果不同，则展示安全字段的差异，并询问是更新还是跳过。
10. 当 consumer=knowledge-base 时，使用传入的能力结果，并单独发现嵌入模型。绝不将其添加到已保存服务的 enabledModels 中。
11. 禁用、更换提供商／模型或删除之前，检查员工引用。仅通过可用的知识库能力检查知识库引用；如果无法读取该依赖，则停止会造成破坏的变更。
12. 每次只执行一个请求的变更。抑制包含密钥的响应输出，绝不回显提供商的 options。
13. 读取并核验安全字段，确认 name、title、provider、enabled 和仅包含聊天模型的 enabledModels。
14. 返回结构化的就绪状态契约，将 coreAI 与有条件的 knowledgeBasePrerequisites 分开；并在适用时包含配置模式以及 UI 完成状态／读取核验结果。
15. 成功、失败、中断或回滚时，均移除受保护的临时文件。

参考资料加载图

参考资料	使用时机	说明
命令图	选择准确的环境、提供商、服务、模型、员工或知识库依赖命令时。	包含排除的命令范围和能力边界。
UI 模式工作流	通过 UI 创建或更改大模型服务或向量数据库连接时。	定义模式选择、支持的 --ui 命令、必需的暂停步骤和独立回读。
大模型服务工作流	测试、创建、更新、禁用、删除或验证已保存的服务时。	定义聊天与嵌入的分离、幂等性、就绪状态和依赖行为。
安全与故障排除	处理凭据或运行时、身份验证、提供商、能力、超时或回滚故障时。	定义受保护的文件和安全输出。

安全门禁

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

• 删除任何大模型服务，包括回滚或清理时的删除；
• 禁用员工或知识库正在使用的服务；
• 更改被引用服务的提供商、凭据或已启用的聊天模型；
• 知识库依赖状态无法读取时仍继续操作；
• UI 表单打开后，未获得用户明确完成操作并进行独立回读就继续；
• 暴露提供商 options、API 密钥、访问令牌、UI 凭据或包含机密的响应正文。

二次确认模板：

• “确认执行：在 <env> 中对大模型服务 <name> 执行 <action>。预期影响：<employee/knowledge-base dependency and availability impact>。输入 confirm 以继续。”

回滚指南：

• 创建验证失败：保留证据；删除新服务需要另行进行新一轮确认。
• 更新不匹配：恢复之前的安全字段；必须重新提供凭据，且不得从日志中恢复。
• 删除：没有原始提供商机密和模型配置就无法恢复。
• UI 结果缺失或不匹配：停止操作并报告实际状态；不得推断操作成功，也不得在没有新的明确模式选择时改用直接 CLI。
• KB 依赖状态未知：不要修改；应先恢复能力可见性，而不是猜测。

验证清单

• 已确认目标环境、API 基础 URL 和身份验证上下文。
• 已完成运行时刷新，并且所需的 ai 命令组已存在。
• 每次创建或更新大模型服务或向量数据库连接之前，用户都已明确选择 direct-cli 或 ui。
• UI 模式在当前帮助信息中可用，不包含请求正文或机密标志，已暂停等待用户完成操作，并通过安全字段独立回读。
• 已从目标环境发现提供商和所请求的模型标识符。
• 每个请求的 enabledModels.models[] 项目都是聊天/大模型。
• enabledModels 中没有嵌入模型。
• 在更改大模型/嵌入配置之前，知识库使用方已提供可用的能力结果。
• 更改后的提供商设置已使用聊天模型通过 test-flight。
• 写入载荷仅包含文档所述的可写服务字段，不包含 modelOptions。
• 每次创建/更新后都进行了安全字段独立回读。
• 在进行有破坏性的更改之前，已检查员工依赖。
• 已检查 KB 依赖；若其状态未知，则已阻止有破坏性的操作。
• 每次执行 destroy 前，都针对该确切服务立即获得了新的确认。
• 命令摘要和最终输出中均未包含机密和完整的 options。
• 正确报告了至少一种允许的配置和一种被拒绝的情形。
• 已分别说明错误、部分成功、回滚限制和剩余待办事项。

最小测试场景

1. 仅检查：刷新运行时，并列出提供商和已保存的服务，不进行任何变更。
2. UI 模式：打开 LLM 服务或已获能力批准的向量数据库表单，暂停并等待用户明确完成，然后独立验证安全字段，再进行后续操作。
3. 配置：测试未保存的设置，保存仅用于聊天的 enabledModels，读取并确认；另行报告已获能力批准的知识库使用方的嵌入模型。
4. 缺少输入：省略提供商凭据、服务名称、模式选择或必需的知识库能力证据，并验证系统会阻止变更。
5. 身份验证／运行时故障：刷新或 ai 帮助失败时，技能停止并提供可执行的恢复指导。
6. 依赖安全：删除服务期间无法查看知识库依赖项时，即使员工引用为空，也会阻止删除。
7. 高风险删除：仅在进行新鲜的精确目标确认并验证目标不存在后，才销毁无依赖的服务。

输出约定

最终回复必须包含：

• 目标环境、请求的操作、目标和使用方；
• 已检查运行时／帮助能力；
• 选定的 direct-cli 或 ui 模式；若使用 UI，还须包含用户的完成报告和独立读取结果；
• 提供商、服务名称、聊天模型，以及单独发现的嵌入模型；
• 已执行的命令，不含机密值；
• 安全字段的读取结果；
• 结构化的 coreAI 和有条件的 knowledgeBasePrerequisites 就绪状态；
• 依赖项状态，包括任何未知的知识库可见性；
• 受保护的操作、部分成功、回滚限制和交接事项；
• 应用的默认值或假设。

参考资料

• NocoBase 官方文档：检查当前 AI 插件和 CLI 行为时使用。[verified: 2026-08-01]
• 命令映射：了解受支持的 nb env 和 nb api ai 命令范围。
• UI 模式工作流：了解如何明确选择模式、受支持的 --ui 命令、必须等待用户完成的暂停步骤，以及 UI 操作后的验证。
• LLM 服务工作流：了解提供商发现、测试、CRUD、就绪状态和依赖项检查。
• 安全与故障排查：了解机密处理、能力故障、安全输出和回滚。