Atomic Agent部署与打包指南：Node SEA构建单文件可执行与多平台发布矩阵

【免费下载链接】atomic-agentAtomic Agent is a local-first AI agent. Runs open-weight models on your own machine via llama.cpp.项目地址: https://gitcode.com/gh_mirrors/at/atomic-agent

Atomic Agent 是一个本地优先（local-first）的 AI 智能体：它把控制循环和全部状态都放在你自己的电脑上，通过 llama.cpp 驱动开源权重的本地模型，操控浏览器、编辑文件、执行经批准的命令，并跨会话记住上下文。它的 CLI 并不要求用户安装 Node.js 运行环境——整个项目通过 Node SEA（Single Executable Application，单文件可执行应用）技术，把全部代码打包成一个可执行文件，再由 CI 构建出覆盖 macOS、Linux、Windows 的多平台发布矩阵。这篇完整指南将带你从零理解这套打包流程。

为什么本地 AI 智能体值得"打成单文件"

Atomic Agent 支持本地模型、云端模型，以及两者混合的 Fusion 模式（一个模型负责规划、一池 worker 负责执行）。在公开的 GAIA Level 1 基准测试中，同一个本地模型下它的准确率与速度都跑赢了对照组——本地跑得好，才值得认真分发给用户：

如果用户每次都要npm install、配 Node 版本、下载一堆依赖，本地优先的理念就打了折扣。SEA 方案让安装体验回归"解压即用"。

核心原理：Node SEA 是怎么工作的

SEA 的思路非常直观：把 JS 代码塞进一个 Node.js 二进制文件里。Atomic Agent 的打包链路分四步：

1. esbuild 打包：把 src/cli/index.ts 及全部依赖打成单个 ESM 文件dist-sea/cli.mjs，见 scripts/bundle-sea.ts；
2. 生成 SEA blob：Node 根据 sea-config.json 生成bundle/sea-prep.blob（内含入口脚本与内嵌资源）；
3. 注入二进制：复制一份当前主机的 Node 可执行文件，用postject把 blob 写进去，得到atomic-agent（Windows 下为atomic-agent.exe），见 scripts/build-binary.ts；
4. 组装发行包：把运行时资产（ripgrep、原生模块预编译件等）与二进制放在一起，打成 tar.gz / zip 并附上 sha256 校验和，见 scripts/package-bundle.ts。

几个关键细节值得新手注意：

• mainFormat: "module"：让 SEA 把入口当 ESM 处理，该能力自Node 25.7.0起可用，因此构建单文件可执行文件要求 Node ≥ 25.7（普通npm run build只需 Node ≥ 22）。scripts/build-binary.ts 会先校验版本，不达标时快速失败并给出明确提示。
• better-sqlite3与playwright-core保持 external：前者是原生模块，后者内部有 esbuild 无法静态内联的require.resolve调用；它们以精简的node_modules/树随二进制一起分发。
• 不打包 llama-server：智能体通过localModels.url连接你自有的 llama.cpp 服务，或用atomic-agent models管理本地模型——模型体积大，不适合塞进发行包。

构建单文件可执行：完整命令清单

先获取源码：

git clone https://gitcode.com/gh_mirrors/at/atomic-agent cd atomic-agent

然后在目标平台主机上依次执行（SEA 不支持交叉编译，在 macOS 上构建只能产出 macOS 二进制）：

# 1. 安装目标平台的运行时依赖 npm ci --omit=dev # 2. 编译 TypeScript 到 dist/ npm run build # 3. esbuild 打包 CLI 为 dist-sea/cli.mjs npm run bundle:sea # 4. 下载钉住版本的 ripgrep（--all 可预取全部 5 个目标平台） npm run bundle:fetch-assets # 或 npx tsx scripts/fetch-assets.ts --all # 5. 生成 SEA 单文件可执行 npm run bundle:build-binary # 6. 组装发行包 + sha256 校验文件 npm run bundle:package

产物位于bundle/atomic-agent-<目标平台>.<扩展名>及同名.sha256文件（可用shasum -a 256 -c校验）。

包里到底装了什么

解压后的目录结构非常克制，这也是"单文件可执行"体验的关键——零依赖、开箱即用：

运行时要求（随包内 README 说明）：系统需装有 Chrome 或 Edge（playwright-core直接附着系统浏览器，不下载 Chromium）；macOS 首次使用需授予辅助功能与屏幕录制权限；Linux 的窗口管理工具建议安装wmctrl。完整说明见 BUNDLING.md。

多平台发布矩阵一览

支持的目标矩阵定义在 scripts/bundle-targets.ts（单一事实来源，CI 与本地脚本共用），运行npm run bundle:matrix -- --json即可输出供 CI 消费的任务列表：

由于 SEA 无法交叉编译，CI 为每个 (平台, 架构) 组合各开一个构建作业，在匹配的 Runner 上执行同一套 6 步流程，最后汇总所有工件发布。用户侧只需一条命令：macOS/Linux 用scripts/install.sh、Windows 用scripts/install.ps1，安装器自动下载归档、校验 sha256、落地二进制与资产目录。

签名与公证：让 macOS 用户无感启动

这是新手最容易踩的坑：Apple Silicon 上postject改写 Mach-O 后，Node 自带的 ad-hoc 代码签名失效，内核会直接以 SIGKILL 杀掉进程——终端里只有一行神秘的killed。scripts/build-binary.ts 在注入后自动执行codesign --sign - --force恢复 ad-hoc 签名，保证本地构建可运行；正式发布则由 CI 中的 scripts/sign-mac-binary.sh 和 scripts/notarize-mac-binary.sh 换上 Developer ID 签名并完成公证。排查口诀：codesign -dv看签名、用com.apple.quarantine（而非 provenance）判断隔离、node dist-sea/cli.mjs --help能跑而 SEA 二进制被杀，问题就在签名或 SEA 配置而非 JS 代码。

版本发布：一条命令触发全流程

scripts/release.sh 负责"改版本号 → 提交 → 打 tag"三步：

npm run release:patch # 0.6.6 → 0.6.7 npm run release:minor # 0.6.x → 0.7.0

推送 tag（形如v0.7.0）后，CI 的 release 工作流自动构建完整矩阵、签名公证 macOS 产物，并发布为 Release。版本号同时会被 esbuild 在打包期烧进二进制（define: __ATOMIC_AGENT_VERSION__），保证单文件可执行无需附带package.json也能正确报出版本。

常见问题速查 🛠️

问：为什么我的构建报 "node is too old"？答：bundle:build-binary要求 Node ≥ 25.7（mainFormat: "module"的下限）。nvm install 25 && nvm use 25后重试即可；日常npm run build/npm test用 Node ≥ 22 没问题。

问：在 Windows 上构建有什么要注意的？答：scripts/build-binary.ts 对npm/npx走了 shell 启动并对参数做了引号转义，规避.cmdshim 的ENOENT/EINVAL问题，直接运行命令即可。

问：为什么包里没有浏览器和模型？答：这是明确的设计取舍（Non-goals）：不下 Chromium（用系统浏览器）、不下 llama-server（连你自己的服务）、不做交叉编译（靠 CI 扇出矩阵），发行包只保留小体量的starter-skills/。

问：如何覆盖内置的 ripgrep？答：设置环境变量ATOMIC_AGENT_RG_PATH=/path/to/rg指向其他二进制，无需重新打包。

结语

一套 esbuild + postject + CI 矩阵的组合，就让 Atomic Agent 这种功能丰富的本地 AI 智能体拥有了"一个文件、五端可用"的分发体验。如果你也想为自己的 Node 项目做单文件可执行，本文的 BUNDLING.md 与 scripts/ 目录就是可以直接参考的完整范本。

【免费下载链接】atomic-agentAtomic Agent is a local-first AI agent. Runs open-weight models on your own machine via llama.cpp.项目地址: https://gitcode.com/gh_mirrors/at/atomic-agent