企业官网建设流程全解析

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/nocobase

nb skills check是 NocoBase CLI 提供的技能检查命令，用于检测全局安装的 NocoBase AI coding skills（@nocobase/skills）是否由 CLI 托管、当前安装版本以及是否存在可用更新。本文以仓库中的 官方命令文档 为骨架，结合 命令实现源码 与 核心逻辑 skills-manager.ts，逐层拆解该命令的用法、输出字段、判断逻辑与底层原理，帮助你快速定位技能安装问题并决定下一步是安装、更新还是保持现状。

命令概述

NocoBase 的 AI coding skills 是一组以nocobase-前缀命名、以SKILL.md为标识的 Agent 技能包，由 npm 包@nocobase/skills（源码仓库源nocobase/skills）统一发布。这些技能全局安装后可供 AI 编码助手（Agent/LLM）调用。nb skills check即用于回答三个核心问题：

1. 是否已安装：全局环境中是否存在由 NocoBase 托管的 skills；
2. 是否由 CLI 管理：这些 skills 是否是通过nb skills install安装、可被nb统一维护的；
3. 是否有更新：当前安装版本与 npm registry 上的最新版本是否一致。

用法

nb skills check [flags]

该命令属于nb skills命令族，父命令nb skills用于"检查或同步全局 NocoBase AI coding skills"（见 skills/index.ts）。子命令还包括install、update、remove，形成完整的生命周期管理。

参数

从 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 测试用例 中验证的场景一致。

输出字段详解

表格模式字段

JSON 模式额外字段

工作原理解析：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 与 managedByNb

const installedSkillNames = pickInstalledNocoBaseSkillNames(installedSkills, managedState, cachedSkillNames); const managedByNb = managedState?.packageName === NOCOBASE_SKILLS_PACKAGE_NAME;

• installed为installedSkillNames.length > 0；
• managedByNb依赖状态文件中的packageName === '@nocobase/skills'；
• pickInstalledNocoBaseSkillNames优先取"托管清单 ∪ 缓存包清单"与"实际已装"的交集，若清单为空则退化为按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. 计算 updateAvailable

let 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 输出逻辑）：

JSON 模式下则直接返回recommendedCommand字段：已安装返回nb skills update --yes，未安装返回nb skills install --yes，方便脚本直接执行。

配套命令速览

• nb skills install：全局安装 skills，已安装则不更新，支持--yes、--version、--verbose、--json；
• nb skills update：刷新已安装的 skills，仅对现有@nocobase/skills安装生效，未安装时会提示先执行 install；
• nb 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.ts）：

• registry 网络故障 → 归因于 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