AionUi 开发环境搭建指南:AionCore 后端、bun 工作流与多实例调试实战

原创2026-09-18 17:21:572,648 阅读
文章标签:AI 应用AI Agent交互助手桌面应用前端移动开发跨平台

AionUi 开发环境搭建指南:AionCore 后端、bun 工作流与多实例调试实战

导读:本文是 AionUi(一个将 Gemini CLI、Claude Code、Codex 等命令行 AI Agent 包装为现代聊天界面的开源桌面应用)的开发入门手册,完整梳理了从零搭建本地开发环境、编译 Rust 后端、启动 Electron 桌面端,到多实例并行开发、prek 代码检查与 electron-vite 构建系统的全流程。读完本文,你将掌握 AionUi 的仓库布局与双仓库协作模式,能独立完成本地环境搭建、后端热更新迭代,并能熟练使用 bun run 全家桶命令进行开发、构建、测试与调试。

本文以 docs/contributing/development.md 为骨架,并结合仓库源码(如 package.json、packages/desktop/electron.vite.config.ts、packages/web-host/src/backend-launcher.ts、.pre-commit-config.yaml)逐层深入,为你呈现一份"能直接照做"的开发指南。

环境要求(Prerequisites)

AionUi 的开发环境涉及 Node.js 运行时、bun 包管理器、Rust 工具链和 Python 四类基础组件:

组件 版本要求 用途
Node.js 22 或更高(根 package.json 的 engines 字段限定为 >=22 <25) 运行 Vite、electron-vite、tsx 等构建工具
bun 最新稳定版 包管理器与脚本运行时(所有 bun run 命令的载体)
Rust stable + Cargo 最新 stable 编译本地 AionCore 后端二进制(aioncore)
Python 3.11+ 原生模块(native module)编译
prek 全局安装 @j178/prek PR 代码检查(pre-commit 的 Rust 实现)

Windows 用户需要特别注意:请安装 Rust MSVC 工具链。如果 Rust 编译因缺少原生构建工具失败,需通过 Visual Studio Installer 安装 Microsoft C++ Build Tools,然后重新打开终端再试。这是 AionCore 编译过程中最常见的 Windows 环境问题。

仓库布局:双仓库协作模式

AionUi 的开发依赖两个仓库的协同工作:

  • AionCore:构建本地后端二进制(macOS/Linux 上为 aioncore,Windows 上为 aioncore.exe),负责 SQLite 数据库、Agent 进程托管、HTTP API 等后端能力;
  • AionUi:启动 Electron 桌面应用,并在启动时自动拉起后端二进制。

官方建议将两个仓库并排放置在同一个工作目录下:

workspace/
|-- AionCore/
`-- AionUi/

从源码看,桌面开发服务器通过 bun run start 继承的 PATH 来解析后端二进制(见 packages/web-host/src/backend-launcher.ts 的 resolveBackend 与 BackendBinaryResolver 类型,以及 scripts/webui.ts 中 resolveBackendBinary() 对 which/where 的调用)。因此必须先安装 AionCore,并在同一个终端里确认二进制可见,再启动 AionUi,否则会出现下文所述的 Cannot find "aioncore" binary 错误。

快速开始(Quick Start)

第 1 步:克隆两个仓库

git clone https://github.com/iOfficeAI/AionCore.git
git clone https://github.com/iOfficeAI/AionUi.git

两个仓库均使用 main 分支开发,除非维护者要求你测试其他分支。

第 2 步:构建并安装 AionCore

在 AionCore 仓库目录下执行:

macOS / Linux

cd AionCore
cargo clean
cargo install --path crates/aionui-app --locked

# 让 Cargo 安装的二进制对当前 shell 可见(如需)
export PATH="$HOME/.cargo/bin:$PATH"

# 验证 AionUi 能找到后端
which aioncore
aioncore --help

如果 which aioncore 无输出,将 export PATH="$HOME/.cargo/bin:$PATH" 写入你的 shell 配置文件(~/.zshrc、~/.bashrc 或对应 shell 的等价文件),打开新终端后再次验证。

Windows PowerShell

cd AionCore
cargo clean
cargo install --path crates/aionui-app --locked

# 让 Cargo 安装的二进制对当前 PowerShell 会话可见(如需)
$env:Path = "$env:USERPROFILE\.cargo\bin;$env:Path"

# 验证 AionUi 能找到后端
where.exe aioncore
aioncore --help

如果 where.exe aioncore 无输出,请确保 %USERPROFILE%\.cargo\bin 已加入用户 Path 环境变量,然后打开新的 PowerShell 窗口再次验证。

关于 --locked 参数:cargo install --path ... --locked 强制使用 Cargo.lock 中锁定的依赖版本,保证构建可复现。注意 --locked 只锁依赖,不会覆盖已安装的同版本二进制——这正是"更新后端"一节必须加 --force 的原因。

第 3 步:启动 AionUi

在 aioncore 可被发现的同一个终端里,进入 AionUi 仓库执行:

cd AionUi

# 安装依赖
bun install

# 以开发模式启动 Electron 桌面应用
bun run start

启动过程中,AionUi 会自动拉起 aioncore 并把后端端口传递给渲染进程——无需另开终端手动启动 AionCore。

从源码看,bun run start 实际执行的是 electron-vite dev --config packages/desktop/electron.vite.config.ts(见 package.json 的 scripts.start)。而后端拉起逻辑的核心在 packages/web-host/src/backend-launcher.ts 的 BackendLifecycleManager:

  • 端口协商:findAvailablePort() 会避开浏览器 fetch 协议禁用的端口(代码中的 FETCH_FORBIDDEN_PORTS 集合,含 1、7、9、22、25、53 等),最多尝试 50 次,确保后端端口可被 fetch 正常访问;
  • 启动参数:buildSpawnArgs() 会拼装 --port、--data-dir、--parent-pid、--log-level(开发模式默认 debug)、--app-version、--local 等参数传给 aioncore;
  • 就绪检测:后端通过 stdout 输出 AIONCORE_LISTENING <json>(携带端口号)与 AIONCORE_READY 就绪标记,同时启动器还会以 200ms 间隔轮询 http://127.0.0.1:<port>/health,两者谁先到达谁胜出;
  • 崩溃重启:运行期崩溃时,handleCrash 会在 60 秒窗口内最多重启 3 次(maxRestarts = 3、restartWindowMs = 60_000)。

这些实现细节解释了为什么"必须先装好 AionCore 再启动 AionUi"——启动器在 resolve_binary 阶段失败会直接抛出 BackendStartupError。

更新本地后端

当你 pull 或修改了 AionCore 后,需要重装后端二进制并重启 AionUi:

cd ../AionCore
cargo install --path crates/aionui-app --locked --force

cd ../AionUi
bun run start

使用 --force 是为了在 AionCore 包版本不变时强制覆盖已安装的二进制;否则 Cargo 可能保留旧二进制,导致你看到的仍是旧行为。

开发期所有权提醒:Electron 应用在开发期间"拥有"后端子进程。正在运行的 AionUi 不会自动加载新安装的二进制,必须退出后重启才生效(详见下文"后端变更不生效"一节)。

后端启动故障排查

报错 Cannot find "aioncore" binary

AionUi 无法从 bun run start 继承的 PATH 中找到后端。请在启动 AionUi 的同一个终端里执行:

# macOS / Linux
which aioncore

# Windows PowerShell
where.exe aioncore

命令失败则把 Cargo 的 bin 目录加入 PATH,并从新终端启动 AionUi。

从源码看,WebUI 路径(scripts/webui.ts 的 resolveBackendBinary())的查找顺序是:AIONUI_BACKEND_BIN 环境变量 → resources/bundled-aioncore/<platform-arch>/ 目录下的预捆绑二进制 → which/where 的 PATH 查找,全部失败才会抛出 Cannot find "aioncore" binary 错误。桌面端 packages/desktop/src/index.ts 与 packages/web-host/src/backend-launcher.ts 的解析逻辑同理,但可通过设置 AIONUI_BACKEND_BIN 显式指定二进制绝对路径。

终端里 aioncore 可用,但 AionUi 仍找不到

请确认 bun run start 是在能执行 aioncore --help 的同一个终端环境里启动的。IDE 内置终端和 GUI 启动的 shell 可能继承了不同的 PATH;更新 PATH 后请重启 IDE,或从终端启动 IDE。

后端变更不生效

退出 AionUi,用 cargo install --path crates/aionui-app --locked --force 重装 AionCore,再重新启动 AionUi。原因如前所述:开发期间 Electron 应用持有后端子进程,运行中的实例不会拾取新二进制。

Windows Rust 构建错误

使用 Rust MSVC 工具链并安装 Microsoft C++ Build Tools。安装或切换工具链后,打开新的 PowerShell 窗口并重新执行 AionCore 的安装命令——新窗口才能正确加载更新后的环境变量与工具链路径。

脚本参考(Scripts Reference)

AionUi 的所有开发、构建、测试命令都集中在根 package.json 的 scripts 字段。以下按类别整理(与官方文档一致,并补充了实际执行的底层命令)。

开发(Development)

命令 说明 底层实现(package.json)
bun start 开发模式启动 Electron 应用 electron-vite dev --config packages/desktop/electron.vite.config.ts
bun run start:multi 在已有实例旁启动第二个 Electron 实例(见"多实例开发") cross-env AIONUI_MULTI_INSTANCE=1 electron-vite dev ...
bun run cli bun start 的别名 同上
bun run webui 以 WebUI 模式启动(浏览器访问,无 Electron 窗口) tsx scripts/webui.ts
bun run webui:remote 以 WebUI 模式启动并开启远程访问 tsx scripts/webui.ts --remote
bun run webui:prod 以生产模式启动 WebUI cross-env NODE_ENV=production tsx scripts/webui.ts
bun run webui:prod:remote 生产模式 + 远程访问 同上加 --remote
bun run resetpass 通过 CLI 重置用户密码 tsx scripts/resetpass.ts

bun run webui 系列在 scripts/webui.ts 中实现了完整的独立运行逻辑:默认端口开发 25809 / 生产 25808 / 多实例 25810(与 packages/desktop/src/common/config/constants.ts 的 WEBUI_DEFAULT_PORT 一致);数据目录默认 ~/.aionui-web[-dev][-2];首次启动时自动构建渲染层(可用 --no-build 跳过);若 SQLite 尚无管理员,会自动生成初始密码并打印在终端。支持的环境变量包括 AIONUI_PORT、AIONUI_HOST、AIONUI_ALLOW_REMOTE、AIONUI_DATA_DIR、AIONUI_STATIC_DIR、AIONUI_BACKEND_BIN 等。

构建与分发(Build & Distribution)

命令 说明
bun run package 构建全部进程(main、preload、renderer)到 out/
bun run make bun run package 的别名
bun run dist 为当前平台构建并打包可分发的安装包
bun run dist:mac / dist:win / dist:linux 分别为 macOS / Windows / Linux 构建
bun run build-mac 同时构建 macOS arm64 与 x64 安装包
bun run build-mac:arm64 / build-mac:x64 仅构建 Apple Silicon / Intel 版
bun run build-win 构建 Windows 安装包
bun run build-win:arm64 / build-win:x64 构建 Windows ARM64 / x64 版
bun run build-deb 构建 Linux(.deb)安装包
bun run build bun run build-mac 的别名

分发构建统一由 node scripts/build-with-builder.js 驱动(基于 electron-builder),并可通过 ELECTRON_BUILDER_COMPRESSION_LEVEL、--config.win.signAndEditExecutable 等环境变量/参数调整打包行为。

独立服务器(Standalone Server,非 Electron)

命令 说明
bun run build:renderer:web 为独立 Web 部署构建渲染层
bun run build:server 构建独立服务器 bundle 到 dist-server/
bun run server:start 开发模式运行独立服务器
bun run server:start:remote 运行独立服务器并开启远程访问
bun run server:start:prod 生产模式运行独立服务器
bun run server:start:prod:remote 生产模式 + 远程访问
bun run server:resetpass / server:resetpass:prod 通过独立服务器 CLI 重置密码

代码质量(Code Quality)

命令 说明
bun run lint 检查 lint 问题(oxlint,只读)
bun run lint:fix 自动修复 lint 问题
bun run format 自动格式化代码(oxfmt)
bun run format:check 只检查格式、不修改文件
bun run i18n:types 为 i18n key 生成 TypeScript 类型

测试(Testing)

命令 说明
bun run test 运行全部单元测试(vitest)
bun run test:watch 监听模式运行测试
bun run test:coverage 运行测试并生成覆盖率报告
bun run test:contract 运行契约测试
bun run test:integration 运行集成测试
bun run test:bun 运行 Bun 专用数据库驱动测试
bun run test:e2e 运行端到端测试(Playwright,配置见 playwright.config.ts)
bun run test:packaged:i18n 对打包构建运行 i18n 集成测试
bun run test:packaged:bun 运行 Bun 打包集成测试

调试(Debug)

命令 说明
bun run debug:perf 开启性能监控启动应用
bun run debug:perf:report 生成性能报告
bun run debug:mcp 调试 MCP 服务器连接
bun run debug:mcp:list 列出已配置的 MCP 服务器
bun run debug:mcp:validate 校验 MCP 服务器配置
bun run debug:custom-agent 调试自定义 Agent 连接

多实例开发(Multi-Instance Development)

当你同时持有两个仓库克隆(例如 AionUi 和 AionUi-refactor)并需要并行运行时,第二个实例用以下命令启动:

bun run start:multi

该命令设置 AIONUI_MULTI_INSTANCE=1(实际执行 cross-env AIONUI_MULTI_INSTANCE=1 electron-vite dev ...),其效果如下:

  • 跳过 Electron 单实例锁:见 packages/desktop/src/index.ts 第 87 行,skipSingleInstanceLock = isE2ETestMode || process.env.AIONUI_MULTI_INSTANCE === '1',第二个实例不会因单实例锁直接退出;
  • 使用独立 userData 目录(AionUi-Dev-2):避免数据库与配置冲突;
  • 隔离数据/配置符号链接路径(~/.aionui-dev-2、~/.aionui-config-dev-2):见 packages/desktop/src/common/config/appEnv.ts 的 getEnvAwareName(),它在开发模式下根据 AIONUI_MULTI_INSTANCE 追加 -dev 或 -dev-2 后缀,确保两个实例的目录名互不重叠;
  • Vite 渲染层、CDP、WebUI 代理端口自动递增避免冲突:其中 WebUI 端口由 packages/desktop/src/common/config/constants.ts 的 WEBUI_DEFAULT_PORT 控制——多实例开发时从 25809 变为 25810(Vite dev server 端口则默认 5173,被占用时自动递增,见 packages/desktop/electron.vite.config.ts)。

注意:多实例 WebUI 默认端口为 25810(而非 25809)。在浏览器访问第二个实例的 WebUI 时,请使用无痕/隐私窗口——两个实例共享 localhost 的 cookie 存储,而它们的 JWT 密钥不同,复用同一浏览器会话会导致鉴权失败。

代码检查(prek)

项目使用 prek(pre-commit 的 Rust 实现)进行代码检查,配置位于根目录 .pre-commit-config.yaml:

# 安装 prek
npm install -g @j178/prek

# 安装 git hooks(可选,提交前自动检查)
prek install

# 对暂存文件运行检查
prek run

# 对相对 main 的变更运行检查(与 CI 相同)
prek run --from-ref origin/main --to-ref HEAD

从 .pre-commit-config.yaml 看,本仓库的检查链包含:

Hook 检查内容
check-yaml / check-json / check-toml 配置文件语法校验
check-merge-conflict / check-case-conflict 冲突标记与大小写冲突检测
check-added-large-files 大文件限制(--maxkb=1000)
end-of-file-fixer / trailing-whitespace 文件结尾与行尾空白修复
typecheck 全项目 TypeScript 类型检查(bunx tsc --noEmit)
oxlint lint 检查(替代 ESLint)
oxfmt 代码格式化(替代 Prettier)
i18n-check i18n 翻译文件校验(node scripts/check-i18n.js)
conventional-pre-commit 提交信息必须符合 Conventional Commits(feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert,且强制 scope)

这样保证本地检查与 CI 检查完全一致,prek run --from-ref origin/main --to-ref HEAD 即为 CI PR 检查的等价命令。

构建系统:electron-vite 与 out/ 目录

AionUi 使用 electron-vite 完成快速打包:

  • 主进程(Main process):Vite 打包(ESM)
  • 渲染进程(Renderer process):Vite 打包(React + TypeScript)
  • 预加载脚本(Preload scripts):Vite 打包

构建产物输出到 out/ 目录:

out/
├── main/        # 主进程代码
├── renderer/    # 渲染进程代码
└── preload/     # 预加载脚本

从 packages/desktop/electron.vite.config.ts 可以读到大量构建细节:

  • 入口:主进程入口为 packages/desktop/src/index.ts;preload 除主入口外还打包了宠物窗口(pet)相关的多个预加载脚本;渲染层是 MPA(多页面应用),入口包括 index.html、pet/pet.html、pet-hit.html、pet-confirm.html;
  • 别名体系:@(packages/desktop/src)、@common、@renderer、@process、@worker 等,贯穿主进程与渲染层;
  • 资源复制:生产构建时通过 viteStaticCopy 将 logo 资源复制到 static/images;
  • 代码分割:通过 manualChunks 将 React 及强耦合的 UI 生态(Arco、react-markdown、CodeMirror、Monaco、KaTeX、WaveDrom 等)聚合进单一 vendor chunk,以规避 ESM chunk 循环导致的 React.createContext 未初始化白屏问题;
  • 版本注入:__APP_VERSION__ 从根 package.json 读取真实版本注入渲染层,避免使用工作区内 packages/desktop/package.json 中占位的 0.0.0;
  • Sentry Source Map:非开发环境且设置了 SENTRY_AUTH_TOKEN 时自动上传 source map。

技术栈(Tech Stack)

技术 用途
Electron 跨平台桌面框架(v37+,见 package.json devDependencies)
React 19 UI 框架
TypeScript 类型安全
Vite 快速打包器(经 electron-vite 集成)
UnoCSS 原子化 CSS 引擎
better-sqlite3 本地数据库
vitest 测试框架(另有 Playwright 用于 E2E)

此外从 package.json 的依赖可以看出:项目集成了 Arco Design 组件库(@arco-design/web-react)、MCP SDK(@modelcontextprotocol/sdk)、多平台 Agent SDK(@anthropic-ai/sdk、openai、@google/genai 等)、Markdown/文档渲染(react-markdown、mermaid、katex、docx、mammoth、officeparser 等)以及多渠道接入(grammy、@larksuiteoapi/node-sdk、@wecom/aibot-node-sdk、dingtalk-stream),是一个典型的"桌面壳 + 本地后端 + 丰富前端生态"的架构。

延伸阅读

登录后查看全文
AionUi