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-agentmercury-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 installnpm install时会自动触发postinstall为ink打补丁见 patches/ink5.2.1.patch即使补丁包不可用构建流水线也会兜底强制执行不会静默跳过。第一步标准构建 —— tsup 打包与 post-build 资产处理npm run build # 等价于 tsup node scripts/post-build.cjs npm start # node dist/index.jsbuild命令是两段式的定义于 package.jsontsup把src/下所有 TypeScript 源码捆绑为单文件dist/index.js带 shebang 头可直接作为mercury命令执行post-build由 scripts/post-build.cjs 完成四件事——强制执行 ink 补丁防 Yoga WASM 崩溃复制src/web/static到dist/web/static复制sql-wasm.wasm到静态资源目录纯 JS wasm 的 SQLite 回退方案构建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 入口无法处理顶层 awaitBun 原生运行 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 的.exenpm run build:bin:all支持的目标见 scripts/build-bin.cjs 的ALL_TARGETSmacOS arm64Apple SiliconmacOS x64IntelLinux x64Linux arm64Windows 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_DISABLE1避免 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.gzchecksums.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 testvitest 全量包完整性验证—— scripts/verify-package.cjs 做 dry-run 安装shebang 校验—— 确认dist/index.js首行是#!/usr/bin/env nodenpm 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。常见问题排查FAQbun: 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。延伸阅读构建相关核心文件官方构建文档website/docs/getting-started/build-from-source.mdx打包配置tsup.config.ts独立二进制构建脚本scripts/build-bin.cjs构建后资产处理scripts/post-build.cjs发布资产校验scripts/verify-standalone-release.cjsnpm 发布流水线scripts/publish.sh项目架构总览ARCHITECTURE.md【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考