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-agentAtomic Agent 是一个本地优先local-first的 AI 智能体它把控制循环和全部状态都放在你自己的电脑上通过 llama.cpp 驱动开源权重的本地模型操控浏览器、编辑文件、执行经批准的命令并跨会话记住上下文。它的 CLI 并不要求用户安装 Node.js 运行环境——整个项目通过 Node SEASingle 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 的打包链路分四步esbuild 打包把 src/cli/index.ts 及全部依赖打成单个 ESM 文件dist-sea/cli.mjs见 scripts/bundle-sea.ts生成 SEA blobNode 根据 sea-config.json 生成bundle/sea-prep.blob内含入口脚本与内嵌资源注入二进制复制一份当前主机的 Node 可执行文件用postject把 blob 写进去得到atomic-agentWindows 下为atomic-agent.exe见 scripts/build-binary.ts组装发行包把运行时资产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 --omitdev # 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校验。包里到底装了什么解压后的目录结构非常克制这也是单文件可执行体验的关键——零依赖、开箱即用内容作用atomic-agent[.exe]SEA 单文件可执行CLI 入口tui、run、serve 等grammars/tool-call.gbnf结构化工具调用解码用的 GBNF 语法vendor/rg[.exe]钉住版本的 ripgrepv14.1.1让os.fs.grep零配置可用node_modules/精简better-sqlite3、playwright-core运行时文件starter-skills/内置起始技能首次启动时同步到全局技能目录README.txt运行时要求与使用速记运行时要求随包内 README 说明系统需装有 Chrome 或 Edgeplaywright-core直接附着系统浏览器不下载 ChromiummacOS 首次使用需授予辅助功能与屏幕录制权限Linux 的窗口管理工具建议安装wmctrl。完整说明见 BUNDLING.md。多平台发布矩阵一览支持的目标矩阵定义在 scripts/bundle-targets.ts单一事实来源CI 与本地脚本共用运行npm run bundle:matrix -- --json即可输出供 CI 消费的任务列表目标 slug平台 / 架构CI Runner归档格式darwin-arm64macOS · Apple Siliconmacos-14tar.gzdarwin-x64macOS · Intelmacos-13tar.gzlinux-x64Linux · x86-64ubuntu-22.04tar.gzlinux-arm64Linux · ARM64ubuntu-24.04-armtar.gzwin32-x64Windows · x64windows-2022zip由于 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.7mainFormat: 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考