跳转到正文

安装与使用 nb1 v0.1.3 ​

English

v0.1.3 将 CLI、本机 daemon、MCP 与内嵌调试器打包为一个程序。下面是该版本的安装步骤。正式下载以 nb1 Releases 中列出的版本为准。

下载与核验 ​

电脑CLI 包
Apple Silicon Macnb1-v0.1.3-darwin-arm64.tar.gz
Intel Macnb1-v0.1.3-darwin-amd64.tar.gz
Linux arm64nb1-v0.1.3-linux-arm64.tar.gz
Linux amd64nb1-v0.1.3-linux-amd64.tar.gz
Windows amd64nb1-v0.1.3-windows-amd64.zip

预编译程序要求 macOS 15.0 及以上,或 Linux glibc 2.38 及以上。nb1 mcp 使用同一程序,系统要求相同。macOS 下载包未经过 Developer ID 公证。

这些二进制要求与源码兼容性分开,不保证所有操作系统或实体 USB 组合。使用较旧系统前,请查看对应 Release 的构建和平台记录。已有 macOS arm64/MK2/FW204 的有限实物证据不扩大为所有平台、MK3、重启或持久化保证。Windows 支持前台运行,不包含自动服务管理。

从同一 Release 下载所选包、release.json 和全局 SHA256SUMS,核对完整 SHA-256 与准确文件名。Apple Silicon Mac 示例:

sh
shasum -a 256 nb1-v0.1.3-darwin-arm64.tar.gz

Linux 可用 sha256sum,Windows PowerShell 可用 Get-FileHash -Algorithm SHA256。全局清单还列着其他平台的包,仅下载一个平台时不要把其他文件缺失误判成当前包损坏。校验和检查内容一致性,不是独立签名;下载包和预期清单都应来自可信的 Release 页面。

解压到独立的新目录,再检查包内清单。macOS 示例:

sh
mkdir nb1-v0.1.3
tar -xzf nb1-v0.1.3-darwin-arm64.tar.gz -C nb1-v0.1.3
cd nb1-v0.1.3
shasum -a 256 -c SHA256SUMS
./nb1 version --json

Linux tar 包用 tar -xzf 解压及 sha256sum -c 检查。Windows 解压 ZIP 后运行 nb1.exe。build.json、Release 清单和 version --json 应指向同一来源;它们描述下载的程序,不代表另一份已运行 daemon 的版本。若要注册服务,请把目录放在稳定位置。

五个平台包共用一份校验清单。该版本共八项下载:五个平台包、可选的 blink1-control-v0.1.3.zip、release.json 和 SHA256SUMS。

用 Homebrew 安装 ​

公开 b1ug tap 安装该 tap 当前实际发布的版本:

sh
brew tap b1ug/tap
brew install b1ug/tap/nb1
nb1 version

若 Homebrew 提示需要信任第三方 Formula,可先查看 Formula 源码,再执行 brew trust --formula b1ug/tap/nb1 并重新安装。

Homebrew 从已发布源码编译,并安装所需构建依赖。Formula 要求 macOS 15 或受支持的 Linux Homebrew 环境,编译需要 Go 1.27.4 或更新版本。上文预编译 Linux 程序的 glibc 下限不能直接套用到 Homebrew 源码构建。安装前查看 tap 当前版本及平台记录。使用 Homebrew 时,后续命令中的 ./nb1 改为 nb1;./nb1 指向手动解压的程序。

双语文档站提供安装与使用说明。安装 nb1 不会自动注册或启动后台服务。

打开内嵌调试器 ​

sh
./nb1 list
./nb1 server --devices DEVICE_SERIAL

把 DEVICE_SERIAL 换成真实灯的序列号,再打开 **http://127.0.0.1:5885/demo/**。从 v0.1.2 升级时,已在配置文件或已安装服务中指定的 8931 仍然有效。请打开运行中的 daemon 打印的地址。选择设备、灯效或 Sequence,直接点 Play;Preview 可选,Play 会校验当前草稿。打开页面、编辑颜色或屏幕预览不会向真实灯提交任务。

页面、字体、编辑器、3D 模型和双面 fallback 都已内嵌,无需外置 Web 目录或 CDN。默认英文,可切中文。若改过 server.listen 或 --listen,请使用实际回环监听地址加 /demo/。

浏览器、CLI 和 MCP 共用这个 daemon。HTTP 可达、设备在线、任务已接受、任务已完成分别是不同状态;操作失败或结果不确定时,按页面就近提示查询原 Job,不要换 ID 重放。Ctrl-C 请求前台 server 正常退出;清理未确认时,不为同一只灯启动第二个拥有者。独立 WebHID 网页另外占用 USB,交接前先 Disconnect。

配置多只灯时,内嵌工作台按序列号排列,首次选择第一只在线的灯。页面显示设备数量和当前序列号,刷新后保留选择。如果这只灯离线或被移出配置,请手动选择另一只灯再播放。

CLI 与显式直连 ​

把内容存为 action.json:

json
{"action":{"kind":"pulse","color":"lime","cycles":3}}

在另一个终端运行:

sh
./nb1 control run DEVICE_SERIAL action.json --wait

需要只看计划、不播放时,单独运行 ./nb1 control preview action.json。结果 JSON 写 stdout,诊断写 stderr;丢失接受回执后,应保留原 Job ID 与地址查询,而不是重新提交。字段、默认值、错误及恢复规则见 API 参考。

无需 daemon 的一次前台播放,应先让原控制器释放设备,再显式直连:

sh
./nb1 control --direct run DEVICE_SERIAL action.json

直连始终等待,Job 只属于本次进程。HTTP 不可达不会自动切 USB。成功的 hold 可以保留灯色;需要熄灭时明确执行 Off。

CLI 的帮助与程序诊断在英文、中文和其他 locale 下均保留英文;Web 工作台有独立语言切换。终端颜色按实际输出流判断:任意非空 NO_COLOR(包括 yes)优先禁用全部 ANSI;CLICOLOR=0 禁用普通着色。没有设置 NO_COLOR 时,可用 CLICOLOR_FORCE=1 或 true 强制颜色。Force 值按 Go 的布尔规则解析:false、0,以及 2 等非布尔值,都回到普通终端规则。管道或 TERM=dumb 默认使用纯文本。JSON 始终不着色。

面向人的帮助与错误由 Fang 呈现,stderr 上的程序诊断使用 Charm Log;--debug 还会显示调用位置和 PID。--log-file PATH 保留原有 JSON 文件格式、10 MiB 轮转、备份压缩和保留规则。命令结果 JSON、daemon 的 JSON 事件流及 MCP JSON-RPC 各自保持独立。CLI 翻译仍为独立工作。从源码构建 nb1 要求 Go 1.25.8 或更新版本,与上文下载包及 Homebrew 构建要求分开。

Fang 暂时使用基于官方 v2.0.1 的修复分支,准确的公开模块版本与校验和记录在发行清单中。显式选择背景的选项已作为 官方 Fang PR #111 提出。 可选参数显示顺序的修正已独立提交为 官方 Fang PR #112;帮助中的 [SERIAL] FILE 与实际执行顺序一致。

可选用户服务 ​

下载/解压不会安装或启动服务。macOS 或有用户级 systemd manager 的 Linux 上,先停掉前台 server,再从选定的稳定目录显式安装:

sh
./nb1 service install --devices DEVICE_SERIAL
./nb1 service start
./nb1 service status --json

install 安排以后登录时可能加载;未加 --start 不请求本次立即启动。默认使用当前程序,可用 --binary 显式选择另一份可信绝对路径。注册/active 不等于 HTTP 或 USB 已就绪。

service stop 保留登录配置;service uninstall --stop 明确允许停止并删除托管配置。Windows 没有自动安装/启停/卸载服务;没有用户 manager 的 Linux 容器使用前台 nb1 server。

手动解压升级时,保留旧目录、核验并解压新版本,然后显式卸载旧托管服务并从新程序重新安装,使用相同 profile 和设备设置。不要删除服务仍引用的目录。Homebrew 用 brew upgrade b1ug/tap/nb1 升级,再在合适时显式停止/启动托管 daemon。默认服务绑定跟随稳定的 opt/nb1/bin/nb1 入口;显式 --binary 仍指向固定路径。操作见 tap 生命周期说明。服务由 nb1 service 管理,不使用 brew services。

配置、MCP 与 Skill ​

./nb1 config path/init/show 可以不访问 USB 地查看位置、创建模板与检查解析结果。Mac/Linux 默认 profile 为 ~/.config/nb1/config.yaml,设置绝对 XDG_CONFIG_HOME 时跟随该根目录;Windows 使用原生应用配置目录。本机颜色和 Pattern 存在电脑上,不是设备 RAM/Flash。

连接本机 MCP 客户端 ​

先启动 daemon。在 MCP 客户端中,把可执行文件设为已安装的 nb1 的绝对路径(Windows 为 nb1.exe),首个参数填 mcp。以下配置连接默认端口上的 daemon。

json
{
  "mcpServers": {
    "nb1": {"command": "/absolute/path/to/nb1", "args": ["mcp"]}
  }
}

从 v0.1.2 升级。 将原来指向 nb1-mcp 的路径改为新程序,在原参数列表最前面加入 mcp。显式指定的端口可以保留。例如,["mcp", "--endpoint", "http://127.0.0.1:8931", "--timeout", "10s"] 仍连接旧端口上的 daemon。重新加载客户端,检查能否发现工具。如果仍运行 v0.1.2,请使用 v0.1.2 安装指南。

本机启用鉴权时,在参数中加入 --token-file PATH。另一台电脑上的客户端可连接 daemon 的 HTTPS /mcp 地址。远程接入与本机鉴权

安装可选的 Skill ​

将 blink1-control-v0.1.3.zip 解压到新的 blink1-control 文件夹,再完整复制到项目的 .agents/skills/ 下,保留 SKILL.md、agents/ 与 references/。Agent 指引

本版支持 Action、Sequence、Job 和本机库。Trigger 可播放保存的 Pattern,省略串号时由 daemon 选灯,Job 会记录实际串号。多格式目录、公开排队与抢占、设备原生部署 API 继续独立推进。Trigger 配置与选灯规则 开发候选安装指南保留 release:false 的 CI 套件约定,不能把它和本正式版包混用。

本地控制 · 使用文档