企业官网建设流程全解析

NocoBase CLI 技能安装指南：nb skills install命令用法与底层实现解析

【免费下载链接】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 install是 NocoBase CLI（nb）中用于全局安装 NocoBase AI coding skills的子命令，它把官方维护的 AI 编码技能包安装到当前用户环境，供 AI 编码助手在 NocoBase 开发场景中使用。本文以官方命令参考文档为主体，结合仓库源码（命令实现、技能管理器、测试用例）展开，帮助你完整掌握该命令的参数、执行流程、幂等行为与故障排查方法。

命令概览

nb skills install用于全局安装 NocoBase AI coding skills。它有一个重要特性：如果技能已经安装，该命令不会执行更新——更新需使用nb skills update（见 更新命令）。

• 命令定位：nbCLI 的skills子命令组（skills 索引文档）
• 功能：将 NocoBase AI coding skills 安装到全局环境
• 源码实现：commands/skills/install.ts
• 核心逻辑：lib/skills-manager.ts

nb skills install [flags]

参数说明

前三个参数来自官方命令参考文档；--version参数未出现在原文档的参数表中，但在 install.ts 的 flags 定义中明确存在，用于精确控制安装的版本，适合需要锁定版本的 CI 或复现场景。

参数行为细节（源码确认）

• 确认提示：不带--yes时，命令会通过 inquirer 弹出确认问题（默认答案为true，即默认同意安装），见 install.ts。
• 加载动画与输出互斥：--json与--verbose都会抑制进度加载动画（shouldShowLoading = !flags.json && !flags.verbose），见 install.ts。这保证了 JSON 输出纯净、详细模式下的完整日志不被动画覆盖。
• 幂等提示：若技能已安装，命令返回noop动作，并提示 "already installed"；--verbose模式下会额外提示运行nb skills update进行刷新，见 install.ts。

常用示例

以下示例完整继承自官方文档，并补充了说明：

# 基本安装：弹出确认提示后执行安装 nb skills install # 跳过确认，直接安装（适合脚本与 CI） nb skills install --yes # 显示详细安装输出，便于排查问题 nb skills install --verbose # 以 JSON 格式输出安装结果 nb skills install --json

组合用法示例：

# 跳过确认并以 JSON 输出，适合自动化场景 nb skills install --yes --json # 安装指定版本 nb skills install --version 1.0.4

安装了什么：@nocobase/skills包

从源码可知，该命令安装的是 npm 包@nocobase/skills（源仓库标识为nocobase/skills），见 skills-manager.ts：

export const NOCOBASE_SKILLS_SOURCE = 'nocobase/skills'; export const NOCOBASE_SKILLS_PACKAGE_NAME = '@nocobase/skills';

该包内含多个独立的 skill，每个 skill 是一个包含SKILL.md描述文件的目录（管理器通过检查SKILL.md是否存在来识别 skill，见 skills-manager.ts）。NocoBase 官方 skill 名称以nocobase-前缀命名，例如测试用例中出现的nocobase-env-manage（见 skills-install-update-command.test.ts）。

安装位置与状态管理

全局根目录

技能被安装到 CLI 的全局 home 目录下。默认路径为：

~/.nocobase/global

路径解析逻辑见 cli-home.ts：CLI 目录名固定为.nocobase，并且可以通过环境变量NB_CLI_ROOT覆盖根目录位置。对应地，resolveGlobalSkillsRoot()返回~/.nocobase/global（见 skills-manager.ts）。

目录结构

安装后，全局目录下会形成如下结构（推断自 skills-manager.ts）：

~/.nocobase/global/ ├── skills.json # 管理状态文件（安装/更新时间、版本、skill 列表） └── cache/ └── skills/ ├── node_modules/@nocobase/skills/ # 缓存的技能包 ├── pack/ # npm pack 临时目录（安装后清理） └── extract/ # tarball 解压临时目录（安装后清理）

其中skills.json记录了packageName、sourcePackage、installedAt、updatedAt、installedVersion、skillNames等字段（见 skills-manager.ts），是后续nb skills check/nb skills update判断状态的核心依据。

底层执行流程

nb skills install的完整调用链如下：

nb skills install └─> installNocoBaseSkills() # skills-manager.ts ├─> inspectSkillsStatus() # 检查当前安装状态 ├─> 判断是否需要安装（noop 短路） ├─> prepareLocalSkillsPackage() │ ├─> npm pack @nocobase/skills[@version] # 下载并打包（超时 120s） │ └─> 校验 tarball 包名/版本并解压到缓存 ├─> npx -y skills add <packageDir> -g -y --skill '*' # 全局添加（超时 120s） ├─> removeObsoleteManagedSkills() # 清理过期的旧 skill └─> persistManagedSkillsState() # 写入 skills.json 并复检状态

关键步骤说明（依据 skills-manager.ts）：

1. 状态检查：先调用inspectSkillsStatus()检查已安装的 skill 列表、缓存中的 skill 名、npm registry 上的最新版本等。
2. 幂等短路：当满足「已安装 + 版本匹配（未指定--version或与已装版本一致）+ 缓存 skill 无缺失 + 无过期 skill」时，直接返回noop，不执行任何安装动作。
3. 下载与校验：通过npm pack获取@nocobase/skills的 tarball，解压后校验包名必须为@nocobase/skills，且若指定了目标版本，实际解压版本必须与之一致，否则抛错中止（见 skills-manager.ts）。
4. 全局注册：调用npx -y skills add <packageDir> -g -y --skill '*'将包内所有 skill 注册到全局。
5. 过期清理：移除已安装但不再包含在新包中的旧 skill（pickObsoleteManagedSkillNames）。
6. 状态持久化：将安装结果写入skills.json，并返回最新状态。

各步骤的超时保护（见 skills-manager.ts）：skills list15 秒、npm view3 秒、npm pack120 秒、skills add120 秒。

输出格式解析

默认输出

安装成功（或已安装）时输出简短提示；--verbose模式会给出更详细的说明，例如：

Installed NocoBase AI coding skills globally.

已安装时不带--verbose只提示 "already installed"，带--verbose会追加建议：

NocoBase AI coding skills are already installed globally. Run `nb skills update` to refresh them.

JSON 输出

--json模式输出结构化结果（字段定义见 install.ts）：

{ "ok": true, "kind": "skills", "action": "installed", "globalRoot": "/home/user/.nocobase/global", "workspaceRoot": "/home/user/.nocobase/global", "installedSkillNames": ["nocobase-env-manage"], "installedVersion": "1.0.4", "installedRef": "1.0.4" }

字段含义：

• action：installed（本次完成安装）或noop（已安装，未做任何事）
• globalRoot/workspaceRoot：安装根目录（当前实现中两者一致）
• installedSkillNames：实际安装的 skill 名称列表
• installedVersion/installedRef：已安装的@nocobase/skills版本

该 JSON 结构被测试用例所验证——skills install会将version等参数正确透传给技能管理器，且--json模式下不启动加载动画（见 skills-install-update-command.test.ts）。

与相关命令的协作

nb skills install属于skills命令组，与以下命令配合使用（详见 skills 索引文档）：

典型使用链路：nb skills check查看状态 →nb skills install --yes首次安装 →nb skills update --yes日常升级。

此外，nb init初始化流程也会联动 skills 同步：当 npm registry 不可访问时会跳过安装并给出提示「等 registry 可访问后，再运行nb skills install即可」（见 zh-CN.json）。skills 管理器还内置了对 npm registry 不可用错误模式（如ENOTFOUND、超时、证书错误等）的识别（见 skills-manager.ts）。

常见问题与故障排查

• 提示已安装但不更新：这是设计行为。nb skills install是幂等命令，已安装时返回noop。需要升级请运行nb skills update --yes。
• 安装超时：npm pack与skills add的超时均为 120 秒。网络较慢时可先用--verbose观察卡在哪一步，再考虑配置 npm 镜像后重试。
• registry 不可达：命令依赖 npm registry 下载@nocobase/skills包。网络不可达或证书异常时安装会失败，可从输出中的错误提示定位（管理器可识别ENOTFOUND、ETIMEDOUT、ECONNREFUSED、证书过期等模式）。
• 版本校验失败：使用--version指定版本时，若下载到的包版本与目标不一致，命令会中止并提示实际版本，避免安装错误版本。
• 自动化场景：在脚本或 CI 中建议使用nb skills install --yes（跳过交互确认）并搭配--json（输出可解析结果）。

【免费下载链接】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