跳转到正文

支持与排障 ​

English · 第一次亮灯 · 安装

从选定 CLI 目录开始,只读检查:

sh
./nb1 version --json
./nb1 config path
./nb1 config show
./nb1 doctor --json

doctor 检查构建信息、daemon 健康与设备缓存,不扫描或打开 USB。包括 daemon 不可达在内,需要关注时可能退出 1。config show 只展示当前进程的解析设置,不重载运行中的 server。

常见情况 ​

现象下一步
control 连不上 daemon启动 nb1 server --devices DEVICE_SERIAL,或明确选 control --direct run;不会自动启动或回退 USB。
没有设备用 nb1 list 检查连接和原生访问;control devices 读取 daemon 已配置的缓存,不是新 USB 扫描。
配置了多只设备显式指定序列号,或用 CLI 按序列号选择第一只缓存在线设备。HTTP 和 MCP 见 Trigger 与默认设备。
Workbench 播放不可用v0.1.3 预览会在播放旁说明未就绪理由。刷新或明确选择在线目标;缺失目标会保留,不静默替换。未知 Job 应查询原 ID,不能重播。
设备忙让当前拥有者释放,包括独立 WebHID 网页/扩展;不要删除活跃锁来强行访问。
端口已占用查看现有 server,或同时选择新 --listen 与客户端 --endpoint。
提交超时保留原 endpoint 与 Job ID,先查询原任务,不自动替换或重新播放。
服务 active 但灯不可用分别检查 service status --json、HTTP 与设备状态;注册不等于 USB 就绪。

查询原 ID 与目标设备:

sh
./nb1 control job JOB_ID
./nb1 control state DEVICE_SERIAL

设备 RGB 是带时间戳的缓存,不是发光测量。Job 存在内存中,重启、过期或 LRU 淘汰都可能令记录消失;记录缺失不证明没有播放。直连 Job 不能稍后向 daemon 查询。

正式软件与硬件证据 ​

v0.1.3 由同一个程序提供 CLI、daemon 与 MCP,预编译下载支持 macOS 15 或更新版本、Linux glibc 2.38 或更新版本、Windows x64。获取 v0.1.3。从正式发行页面下载的 Apple Silicon 版 nb1,在两台固件 204 的 blink(1) MK2 上分别完成了九种 Action 和两种 Sequence 的真机测试。双设备发版记录 · 五平台构建与发布。

以下表格保留旧版本 v0.1.2 的独立验证结果。

nb1 v0.1.2 固定源码 88fc2be8326c076b6f09932054b0c8f11d89c0a0,依赖 blink1-go v0.0.2、GID v0.0.3 与 colorkit v0.1.0,原生发行使用 Go 1.27.4。

范围证据
五个原生目标与正式发布macOS/Linux arm64、amd64 及 Windows amd64 的 CLI/MCP help、版本、协议、系统依赖、解包与离线 daemon/HTTP 检查通过;13 个公开文件与五平台包内记录已下载核验;实际下载的 Mac CLI/MCP 版本、help 与协议检查通过,没有访问 USB。
主干测试与候选/daemon 检查发行源码的十六项适用软件任务通过;源码和二进制身份分别记录。
预编译运行要求CLI/server:macOS 15.0+、Linux glibc 2.38+;MCP:macOS 13.0+ 或静态 Linux ELF。Mac 包未经过 Developer ID 公证。
实体 blink(1)已有限 macOS arm64/MK2/FW204 记录保留原来源、日期和限制;本次发行没有新增实体 USB/相机验证。

既有 Mac/MK2 记录出现过可恢复 Darwin I/O 错误。软件 CI 与标签不等于 Linux/Windows 实体 USB、MK3、重启/登录、校准颜色或准确 USB 到发光时序验收。已记录平台证据。

配置与设备归属 ​

Mac/Linux 默认 ~/.config/nb1/config.yaml,设置绝对 XDG_CONFIG_HOME 时跟随该根目录。Windows 为 %APPDATA%\nb1\config.yaml。--config 优先于 NB1_CONFIG。本机颜色和 Pattern 使用默认应用库或绝对 library_dir。

Mac 归属锁仍在 ~/Library/Application Support/nb1/device-locks。仅切配置不会移动锁或默认库;覆盖锁目录时各控制器必须一致。本机 Pattern 与设备 RAM、Flash、上电设置分开。

Windows 已包含前台运行,未实现自动服务安装/启停/卸载。Linux 服务需要用户级 systemd manager;缺少它的容器使用前台 server。

报告问题时提供 OS/架构、已知型号/固件、version --json、准确命令、去敏错误及预期/实际结果。不要包含认证信息、消息正文或无关路径。完整 API 错误与恢复。

本地控制 · 使用文档