NocoBase CLI `nb skills check` 命令详解：检查全局 AI Coding Skills 的状态与更新

NocoBase CLInb skills check命令详解检查全局 AI Coding Skills 的状态与更新【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobasenb skills check是 NocoBase CLI 提供的技能检查命令用于检测全局安装的 NocoBase AI coding skillsnocobase/skills是否由 CLI 托管、当前安装版本以及是否存在可用更新。本文以仓库中的 官方命令文档 为骨架结合 命令实现源码 与 核心逻辑 skills-manager.ts逐层拆解该命令的用法、输出字段、判断逻辑与底层原理帮助你快速定位技能安装问题并决定下一步是安装、更新还是保持现状。命令概述NocoBase 的 AI coding skills 是一组以nocobase-前缀命名、以SKILL.md为标识的 Agent 技能包由 npm 包nocobase/skills源码仓库源nocobase/skills统一发布。这些技能全局安装后可供 AI 编码助手Agent/LLM调用。nb skills check即用于回答三个核心问题是否已安装全局环境中是否存在由 NocoBase 托管的 skills是否由 CLI 管理这些 skills 是否是通过nb skills install安装、可被nb统一维护的是否有更新当前安装版本与 npm registry 上的最新版本是否一致。用法nb skills check [flags]该命令属于nb skills命令族父命令nb skills用于检查或同步全局 NocoBase AI coding skills见 skills/index.ts。子命令还包括install、update、remove形成完整的生命周期管理。参数参数类型说明--jsonboolean输出 JSON 格式的结果默认false从 check.ts 源码 可以看到该 flag 的定义static override flags { json: Flags.boolean({ description: Output the result as JSON, default: false, }), };--json是nb skills check目前唯一的参数。它面向脚本化、CI/CD 或需要被 Agent 程序解析的场景——JSON 输出包含比表格输出更完整的字段如npmPackageName、sourcePackage、packageSkillNames、recommendedCommand、registryError等。示例# 以人类可读的表格形式输出检查结果 nb skills check # 以 JSON 形式输出便于脚本解析 nb skills check --json表格模式输出示例Field Value Skills home /home/user/.nocobase Installed yes Managed by nb yes Installed skills nocobase-env-manage, nocobase-ui-builder Installed version 1.0.4 Latest version 1.0.5 Update available yes表格模式非--json通过renderTable([Field, Value], [...])渲染仅展示 7 个关键字段见 check.ts 实现。JSON 模式输出示例nb skills check --json输出结构字段定义见 SkillsStatus 类型{ ok: true, kind: skills, globalRoot: /home/user/.nocobase, workspaceRoot: /home/user/.nocobase, installed: true, managedByNb: true, sourcePackage: nocobase/skills, npmPackageName: nocobase/skills, packageSkillNames: [nocobase-env-manage, nocobase-ui-builder], installedSkillNames: [nocobase-env-manage], installedVersion: 1.0.4, latestVersion: 1.0.5, installedRef: 1.0.4, latestRef: 1.0.5, updateAvailable: true, recommendedCommand: nb skills update --yes, registryError: null }上例中的字段组合含packageSkillNames与installedSkillNames分离与 skills-check-command.test.ts 测试用例 中验证的场景一致。输出字段详解表格模式字段字段含义取值说明Skills home全局 skills 根目录即globalRoot默认位于~/.nocobaseInstalled是否已安装 NocoBase skillsyes/no由installedSkillNames是否非空决定Managed by nb是否由 CLI 托管yes/no由托管状态文件中的packageName是否为nocobase/skills决定Installed skills已安装的技能名列表逗号分隔若无则显示(none)Installed version当前安装版本未知时显示(unknown)Latest versionregistry 上的最新版本未知时显示(unknown)Update available是否有可用更新yes/no/unknown无法确定时JSON 模式额外字段字段含义ok/kind固定为true/skills便于统一解析globalRoot/workspaceRoot全局根目录两者当前指向同一目录sourcePackage技能来源固定为nocobase/skillsnpmPackageName对应 npm 包名nocobase/skillspackageSkillNames缓存包中声明提供的技能名含未实际安装的installedSkillNames实际已安装的技能名installedVersion/latestVersion当前版本 / 最新版本installedRef/latestRef旧版字段向后兼容与版本字段一致updateAvailable是否有更新true/false/null表示未知recommendedCommand建议执行的下一步命令registryError查询 npm registry 时的错误信息无错误时为undefined工作原理解析inspectSkillsStatus 的检测流程命令核心调用的是 skills-manager.ts 中的inspectSkillsStatus其检测流程分为四步1. 并行收集三类信息const [installedSkills, managedState, cachedSkillNames] await Promise.all([ listGlobalSkills({ globalRoot, commandOutputFn: options.commandOutputFn }), readManagedSkillsState(globalRoot), readCachedPackageSkillNames(globalRoot), ]);listGlobalSkills执行npx -y skills list -g --json列出全局已安装技能。出于冷启动考虑该命令设置了 15 秒超时SKILLS_LIST_TIMEOUT_MS 15000因为npx解析并启动包可能耗时数秒见 skills-manager.ts 常量定义readManagedSkillsState读取全局根目录下的skills.json托管状态文件记录packageName、installedVersion、skillNames等readCachedPackageSkillNames扫描缓存目录cache/skills/node_modules/nocobase/skills/skills/下所有包含SKILL.md的目录得到包内声明的技能名。2. 判定 installed 与 managedByNbconst installedSkillNames pickInstalledNocoBaseSkillNames(installedSkills, managedState, cachedSkillNames); const managedByNb managedState?.packageName NOCOBASE_SKILLS_PACKAGE_NAME;installed为installedSkillNames.length 0managedByNb依赖状态文件中的packageName nocobase/skillspickInstalledNocoBaseSkillNames优先取托管清单 ∪ 缓存包清单与实际已装的交集若清单为空则退化为按nocobase-前缀过滤避免把用户自装的同名/无关技能误判为 NocoBase 托管技能。3. 查询最新版本带网络容错if (installedSkillNames.length 0 || managedByNb) { const published await readPublishedSkillsVersion({ globalRoot, commandOutputFn: options.commandOutputFn }); latestVersion published.version; registryError published.error; ... }通过npm view nocobase/skills version --json查询 registry 上的最新版本超时仅 3 秒SKILLS_NPM_VIEW_TIMEOUT_MS 3000。查询失败不会让命令崩溃而是将错误写入registryError并在表格模式下以Update check warning: ...提示。4. 计算 updateAvailablelet updateAvailable: boolean | null installedSkillNames.length 0 ? null : false; ... if (installedVersion latestVersion) { updateAvailable compareVersions(latestVersion, installedVersion) 0; }未安装时恒为false已安装但版本信息不全时为null显示unknown两个版本都已知时通过compareVersions比较最新版本大于当前版本即为true。全局根目录的确定globalRoot由 cli-home.ts 解析默认取os.homedir()下的.nocobase目录即~/.nocobase也可通过环境变量NB_CLI_ROOT覆盖该目录同时存放skills.json状态文件与cache/skills/缓存。检查后的建议动作命令会根据检查结果给出下一步指引见 check.ts 输出逻辑检查结果CLI 提示未安装Run \nb skills install to install the NocoBase AI coding skills globally.已安装且有更新Run \nb skills update to refresh the global NocoBase AI coding skills.查询 registry 失败Update check warning: 错误信息JSON 模式下则直接返回recommendedCommand字段已安装返回nb skills update --yes未安装返回nb skills install --yes方便脚本直接执行。配套命令速览nb skills install全局安装 skills已安装则不更新支持--yes、--version、--verbose、--jsonnb skills update刷新已安装的 skills仅对现有nocobase/skills安装生效未安装时会提示先执行 installnb skills remove移除由nb托管的全局 skills并清理skills.json状态文件只删除托管技能保留用户自装的无关技能。从 skills-manager.test.ts 的测试可以看到install/update 内部同样先调用inspectSkillsStatus做前置检查例如已安装且版本一致、缓存技能完整、无废弃技能时install直接返回noop而update在包内技能缺失或存在不再属于包的废弃技能时会触发重装与清理npx skills remove name -g -y。网络异常与超时处理check命令在离线或 registry 不可达时依然可用。源码中维护了一组 registry 不可用的错误特征模式enotfound、eai_again、etimedout、fetch failed、socket hang up、证书类错误等见 skills-manager.ts 的 NPM_REGISTRY_UNAVAILABLE_PATTERNS并提供了isNpmRegistryUnavailable判定函数。行为归纳测试用例见 skills-manager.test.tsregistry 网络故障 → 归因于 registry 不可用registryError携带原始错误命令正常退出并给出警告本地包校验失败如 tarball 包名不匹配nocobase/skills→ 不属于 registry 问题会被当作真实错误抛出skills list超时15 秒也会被识别为 registry 不可用场景之一。小结nb skills check是维护 NocoBase AI coding skills 健康状态的第一入口通过一次命令即可确认技能是否安装、是否由 CLI 托管、版本是否最新并在网络异常时优雅降级为警告而非报错。配合install、update、remove三个命令即可完整覆盖检查 → 安装 → 更新 → 卸载的闭环管理。若需要二次开发或深入理解其判定逻辑可直接阅读 命令实现 与 底层管理器并以 命令测试、管理器测试 为行为参考。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考