mercury-agent源码构建教程：从Bun编译独立二进制到跨平台发布的完整指南-拓冰网站定制

mercury-agent源码构建教程：从Bun编译独立二进制到跨平台发布的完整指南

【免费下载链接】mercury-agentSoul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.项目地址: https://gitcode.com/gh_mirrors/me/mercury-agent

mercury-agent 是一个灵魂驱动（Soul-driven）的 AI Agent，内置权限加固的工具系统、Token 预算管理和多渠道接入（CLI、Telegram、Discord、Slack、Signal），可以 7×24 小时常驻运行。本教程带你从源码出发，完成 mercury-agent 源码构建全流程：用 tsup 打包标准产物，再用 Bun 编译独立二进制，最终交叉编译出 5 个平台的发布资产，掌握完整的跨平台发布链路。

为什么从源码构建：两种产物一次看懂

mercury-agent 提供两条构建路径，产物形态完全不同：

构建方式	产物	适用场景
标准构建	`dist/`下的 ESM 捆绑包（与 npm 发布一致）	本地开发、贡献代码、`npm link`调试
独立可执行文件	单个二进制文件，内嵌 JS 运行时和全部代码	终端用户机器上无需安装 Node.js 和 Bun

核心打包配置在 tsup.config.ts：入口为src/index.ts，目标node20，并在编译期通过define注入版本号（globalThis.__MERCURY_VERSION__），这样独立二进制运行时不必再从磁盘读取package.json获取版本。

构建环境准备：Node.js 20 + Bun 两步装好

构建工具链只需要两个运行时：

Node.js ≥ 20—— 驱动 tsup 构建工具链（见 package.json 的engines约束）；
Bun ≥ 1.3—— 仅编译独立二进制时需要，用官方安装脚本一行装好。

git clone https://gitcode.com/gh_mirrors/me/mercury-agent cd mercury-agent npm install

💡npm install时会自动触发postinstall为ink打补丁（见 patches/ink+5.2.1.patch）；即使补丁包不可用，构建流水线也会兜底强制执行，不会静默跳过。

第一步：标准构建 —— tsup 打包与 post-build 资产处理

npm run build # 等价于 tsup && node scripts/post-build.cjs npm start # node dist/index.js

build命令是两段式的（定义于 package.json）：

tsup：把src/下所有 TypeScript 源码捆绑为单文件dist/index.js，带 shebang 头，可直接作为mercury命令执行；
post-build：由 scripts/post-build.cjs 完成四件事——
1. 强制执行 ink 补丁（防 Yoga WASM 崩溃）；
2. 复制src/web/static到dist/web/static；
3. 复制sql-wasm.wasm到静态资源目录（纯 JS + wasm 的 SQLite 回退方案）；
4. 构建ui/下的 Web 仪表盘（Termux 环境自动跳过）。

想把自己的本地构建挂成全局mercury命令，只需：

npm link mercury --help

第二步：用 Bun 编译独立二进制

mercury-agent 选择bun build --compile而不是pkg或 Node SEA，原因很实际：依赖图里包含带顶层 await 的 ESM 模块（ink、yoga-layout），而 pkg 和 Node SEA 都要求 CommonJS 入口，无法处理顶层 await；Bun 原生运行 ESM 并内嵌自己的运行时，彻底绕开这个问题。

四条构建命令，覆盖所有场景

构建逻辑全部封装在 scripts/build-bin.cjs 中：

命令	目标	已存在产物时
`npm run build:bin`	仅当前系统	跳过
`npm run build:bin:all`	全部 5 平台	逐目标跳过
`npm run build:bin:force`	仅当前系统	覆盖
`npm run build:bin:all:force`	全部 5 平台	覆盖

快速上手：

npm run build:bin # 为当前 OS/架构构建 ./release/v1.2.7/mercury-macos-arm64 --help

⚠️build:bin依赖标准构建产物dist/index.js。npm 脚本已自动串联两步；若直接运行node scripts/build-bin.cjs，请先执行npm run build。

交叉编译：一台机器产出 5 个平台

Bun 为每个目标平台自带运行时，因此在任意一台机器上都能编译出全部 5 个平台（比如在你的 Mac 上产出 Windows 的.exe）：

npm run build:bin:all

支持的目标（见 scripts/build-bin.cjs 的ALL_TARGETS）：

macOS arm64（Apple Silicon）
macOS x64（Intel）
Linux x64
Linux arm64
Windows x64

唯一的原生依赖better-sqlite3被声明为optional（见 package.json），交叉编译时自动跳过，运行时回退到sql.js（纯 JS + wasm），所以交叉编译产物完全可用。

版本化输出目录，绝不覆盖历史发布

构建脚本从package.json读取版本号，把二进制写入版本化子目录，旧版本永远不会被覆盖，多个版本可并排保留：

release/ ├── latest → 指向最新版本 ├── v1.1.9/ │ ├── mercury-macos-arm64 │ ├── mercury-macos-x64 │ ├── mercury-linux-x64 │ ├── mercury-linux-arm64 │ ├── mercury-win-x64.exe │ ├── web.tar.gz │ └── checksums.txt （SHA-256 校验和） └── v1.2.7/

每次构建还会：

把dist/web打包成web.tar.gz（用COPYFILE_DISABLE=1避免 macOS 的._*垃圾条目混入）；
生成checksums.txt，可用shasum -a 256 -c checksums.txt校验完整性；
编译失败自动重试 3 次（间隔 2s/4s）；
刷新release/latest符号链接指向当前版本。

发布质量门禁：verify-standalone-release 自动校验

build:bin:all结束后会自动执行 scripts/verify-standalone-release.cjs，它是一道严格的质量门禁：

发布目录里只允许5 个平台二进制 +web.tar.gz+checksums.txt，出现多余文件直接报错；
逐个文件重算 SHA-256 并与checksums.txt比对；
解包web.tar.gz检查所有条目必须以web/开头，拦截路径穿越类的不安全归档，且不允许.DS_Store、.map等垃圾文件。

任何一项不通过，构建即失败，从机制上保证发布资产干净一致。

跨平台发布流程：publish.sh 的六步流水线

npm 包的发布由 scripts/publish.sh 一条命令完成六步流水线：

类型检查——npm run typecheck（即tsc --noEmit）；
运行测试——npm run test（vitest 全量）；
包完整性验证—— scripts/verify-package.cjs 做 dry-run 安装；
shebang 校验—— 确认dist/index.js首行是#!/usr/bin/env node；
npm publish——--access public发布到 npm；
打 Git 标签——git tag -a v<版本>。

独立二进制侧，则把release/v<版本>/整个目录作为发布资产对外分发，用户端通过安装脚本（见 scripts/install.sh）自动匹配当前平台下载对应二进制——构建与分发两端都靠 SHA-256 校验和保证可信。

构建验证：跑通你的第一行 mercury

构建完成后，做三件事确认一切正常：

# 1. 二进制能执行 ./release/latest/mercury-<你的平台> --version # 2. 校验和通过 cd release/v1.2.7 && shasum -a 256 -c checksums.txt # 3. 标准构建可启动 npm start && mercury --help

首次运行mercury会进入引导向导（Onboarding Wizard），引导你配置 AI 提供商、选择渠道并初始化 Agent 人格（Soul）。

常见问题排查（FAQ）

bun: command not found安装 Bun 后重启 shell，或显式使用~/.bun/bin/bun。

ERROR: dist/index.js not found直接运行了 bin 脚本但没先做标准构建。先执行npm run build，或直接使用npm run build:bin（已自动串联）。

二进制静默退出（返回码 0）通常是版本查找失败。构建流水线通过 tsup 的define在编译期注入版本号；如果你改过入口文件，请确保 src/index.ts 中pkgVersion的回退路径完整。

release/latest符号链接过期重新运行任意build:bin命令，链接会自动修复指向当前package.json版本。

macOS Gatekeeper 拦截本地使用：右键 → 打开一次即可。分发场景需做代码签名与公证（codesign + notarytool）。

资讯详情

mercury-agent源码构建教程：从Bun编译独立二进制到跨平台发布的完整指南