3. 安装：通过 npm 安装
npm 会自动下载与你系统匹配的预编译二进制。无需 Rust 工具链。
3.1 一行命令安装
npm install -g @omicverse/omicos
安装完成后验证：
omicos --version
预期输出：
omicos 0.3.29+a1b2c3d
--version 打印 <semver>+<git 短哈希>。开发构建多一个 (debug) 后缀，正式发布版没有。想看完整构建信息（目标平台、构建配置），在守护进程运行后查询 /api/version：
curl -sS http://127.0.0.1:5055/api/version
预期输出：
{"build_profile":"release","display":"0.3.29+a1b2c3d","git_rev":"a1b2c3d","semver":"0.3.29","target_triple":"aarch64-apple-darwin"}
3.2 各平台安装说明
- 装 Node.js（
brew install node或官网安装包）。 - 执行
npm install -g @omicverse/omicos。 - 执行
omicos --version确认。
Apple Silicon 与 Intel 各有原生二进制，npm 自动选择，不需要 Rosetta。
- 装 Node.js（官网 MSI 安装包会一并写好
PATH）。 - 在 PowerShell 里执行
npm install -g @omicverse/omicos。 - 关掉再重开 PowerShell，执行
omicos --version。
PATH 是终端启动时读取的，装完不重开窗口就会"明明装好了却找不到命令"。ARM64 设备（如 Surface Pro X）同样有原生包。
- 用 nvm 或发行版包管理器装 Node.js ≥ 16。
- 执行
npm install -g @omicverse/omicos。 - 执行
omicos --version确认。
发行版仓库里的 Node 常年偏旧（Debian/CentOS 尤甚），低于 16 会导致平台子包装不上，建议用 nvm。HPC 登录节点的装法见第 8 章。
3.3 它是怎么工作的
@omicverse/omicos 是一个 wrapper 包，本身不含二进制。它用 npm 的 optionalDependencies 声明六个平台子包。npm 根据 os 和 cpu 只安装匹配的那一个：
| npm 子包 | 平台 |
|---|---|
@omicverse/omicos-linux-x64 |
Linux x86_64 |
@omicverse/omicos-linux-arm64 |
Linux ARM64 |
@omicverse/omicos-darwin-x64 |
macOS Intel |
@omicverse/omicos-darwin-arm64 |
macOS Apple Silicon |
@omicverse/omicos-win32-x64 |
Windows x64 |
@omicverse/omicos-win32-arm64 |
Windows ARM64 |
包里的 bin/omicos.js 是一层薄壳，运行时直接执行已安装的原生二进制。所以 omicos 跑的就是 Rust 编译的本体，没有 Node 运行时开销。
npm install 时如果加了 --no-optional，或者 npm 版本太老（< 7）不认 optionalDependencies，wrapper 会装上而二进制不会——于是 omicos 命令存在但一跑就报错。这不是网络问题，重装再多次也没用，需要改的是 npm 版本或安装参数。
3.4 故障排查
提示 command not found: omicos
npm 的全局 bin 目录不在 PATH 里。先查这个目录：
npm prefix -g
预期输出：
/Users/you/.npm-global
把它的 bin 加进 PATH。写进 ~/.zshrc 或 ~/.bashrc 可永久生效：
export PATH="$(npm prefix -g)/bin:$PATH"
权限报错（EACCES）
sudo npm install -g
用 sudo 装出来的文件归 root 所有。omicos 的自动更新需要写自己的二进制，权限不足时这一步会失败，而表现只是"版本号一直不变"——不会有明显报错。正确做法是换一个用户级的全局目录，一次配置永久受益。
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @omicverse/omicos
装上了但平台子包没装上
确认 npm 版本够新（≥ 7，能正确处理 optionalDependencies），且命令里没有 --no-optional。
3.5 升级
omicos 内置自动更新。运行时会检查云端发布清单，发现新版本就在后台下载、做 SHA-256 校验、原子替换二进制，下次启动生效。多数情况无需手动升级。
需要手动升到最新版：
npm install -g @omicverse/omicos@latest
升级后确认版本：
omicos --version
预期输出：
omicos 0.3.29+a1b2c3d