@cremini/skillpack-node

@cremini/skillpack-node 是 SkillPack 的节点管理器，用来把一台机器上的多个 SkillPack 实例接入 Enterprise Dashboard，并统一完成发现、启动、停止、状态校验、心跳上报和远程部署。

它本身不负责运行 Agent Runtime，而是站在 @cremini/skillpack 之上做一层“节点控制平面”。

适用场景

• 你已经用 @cremini/skillpack 创建或运行过一个或多个 SkillPack
• 你希望把这台机器注册到 Dashboard，统一查看在线状态和资源指标
• 你希望从 Dashboard 远程启动、停止、重启或部署 Pack

核心功能

• 连接 Dashboard 的 Socket.IO 长连接
• 节点注册：首次连接后上报节点信息和本机 Pack 清单
• 周期心跳：上报 CPU、内存、运行时长和 Pack 状态
• Pack 发现：读取本机 ~/.skillpack/registry.d/*.json
• Pack 校验：通过 http://127.0.0.1:<port>/api/health 校验实际运行状态
• 本地控制：支持 list、start-pack、stop-pack
• 远程控制：响应 Dashboard 下发的 start_pack、stop_pack、restart_pack、get_status、deploy_pack
• 远程部署：下载 zip，解压到 ~/.skillpack/packs/ 后自动启动

工作流程

flowchart LR
  A["Dashboard"] -->|"Socket.IO command"| B["skillpack-node"]
  B -->|"npx @cremini/skillpack run"| C["SkillPack Runtime"]
  C -->|"registry.d entry"| D["~/.skillpack/registry.d"]
  B -->|"read / validate"| D
  B -->|"GET /api/health"| C
  B -->|"register / heartbeat / ack"| A

安装

要求：

• Node.js >= 20
• 已可使用 npx @cremini/skillpack

安装：

npm install -g @cremini/skillpack-node

或直接用 npx：

npx @cremini/skillpack-node --help

快速开始

1. 先确认本机已有可运行的 SkillPack

例如：

npx @cremini/skillpack run /absolute/path/to/your-pack

如果 Pack 正常启动，它会在本机注册表中留下记录，后续可被 skillpack-node 发现。

2. 首次启动节点管理器并绑定 Dashboard

skillpack-node start \
  --token ntk_xxx \
  --name "Office Mac Mini"

首次启动时：

• --dashboard 可选，默认是 https://api.skillpack.sh
• --token 必填
• 传入的配置会保存到 ~/.skillpack/node-config.json

之后再次启动可以直接：

skillpack-node start

3. 查看本机已发现的 Pack

skillpack-node list

会输出：

• Pack 名称
• 当前状态
• 端口
• PID
• 目录

4. 手动启动或停止某个 Pack

skillpack-node start-pack /absolute/path/to/pack
skillpack-node stop-pack /absolute/path/to/pack

指定端口：

skillpack-node start-pack /absolute/path/to/pack --port 3001

CLI 命令

start

启动节点管理器并连接 Dashboard。

skillpack-node start [options]

参数：

• --dashboard <url>: Dashboard Socket.IO 地址
• --token <token>: Dashboard 发放的节点令牌
• --name <name>: 节点名称，默认是当前主机名
• --interval <seconds>: 心跳上报间隔，默认 30
• --validate-interval <seconds>: 注册表校验间隔，默认 60

说明：

• 启动后会先发现本地 Pack，再开始后台校验循环
• 连接成功后立即发送一次 register
• 后续按 reportInterval 周期发送 heartbeat
• 收到 SIGINT / SIGTERM 时会断开 Dashboard 连接并停止自身后台循环

list

列出本机通过注册表发现到的所有 SkillPack：

skillpack-node list

这个命令会先做一轮校验，因此看到的是“修正后的最新状态”，而不是单纯把旧注册表内容原样打印出来。

start-pack

启动指定目录下的 SkillPack：

skillpack-node start-pack <dir> [--port <port>]

要求：

• 目录必须存在
• 目录下必须存在 skillpack.json

实现方式：

• 后台拉起 npx -y @cremini/skillpack run <dir>
• 通过轮询注册表和 /api/health 等待 Pack 进入 running
• 默认等待超时约 20 秒

stop-pack

停止指定目录下的 SkillPack：

skillpack-node stop-pack <dir>

实现方式：

• 先发 SIGTERM
• 若进程 5 秒内未退出，再发 SIGKILL
• 然后等待注册表状态回到 stopped

配置文件

节点配置保存在：

~/.skillpack/node-config.json

当前支持字段：

{
  "dashboardUrl": "https://api.skillpack.sh",
  "nodeToken": "ntk_xxx",
  "nodeName": "Office Mac Mini",
  "reportInterval": 30,
  "validationInterval": 60
}

默认值：

• dashboardUrl: https://api.skillpack.sh
• nodeName: 当前机器主机名
• reportInterval: 30
• validationInterval: 60

Dashboard 协议

节点管理器通过 Socket.IO 与 Dashboard 通信，协议说明见：

• docs/socketio-protocol.md

当前实现的上行消息：

• register
• heartbeat
• command_ack

当前实现的下行消息：

• command

支持的命令种类：

• start_pack
• stop_pack
• restart_pack
• get_status
• deploy_pack

远程部署 zip 约束

当 Dashboard 下发 deploy_pack 时，节点管理器会：

1. 下载 zip 文件
2. 解压到临时目录
3. 校验 zip 结构
4. 移动到 ~/.skillpack/packs/<name>
5. 自动启动该 Pack

zip 需要满足：

• 顶层必须且只能有一个目录
• 该目录下必须包含 skillpack.json

如果目标目录已存在，会自动重命名为：

• pack-name
• pack-name-2
• pack-name-3

开发

安装依赖：

npm install

常用命令：

npm run build
npm run check
npm test
npm run cli:help
npm run cli:list

本地开发时，如果你要验证完整链路，通常需要同时准备：

• 一个可运行的 @cremini/skillpack Pack
• 一个实现了协议的 Dashboard 服务

已知实现边界

• 当前是 CLI-first 包，核心使用方式是命令行，而不是稳定的公开 SDK
• 注册表读取依赖 @cremini/skillpack/dist/runtime/registry.js 的内部路径约定
• Pack 存活判断依赖 @cremini/skillpack Runtime 的 /api/health 返回格式
• 心跳中的 skillpackVersion 通过本地已安装包的 package.json 推断，未找到时会回退为 unknown

License

SEE LICENSE IN LICENSE