企业官网建设流程全解析

AionUi 开发环境搭建与多进程工程实践：从 AionCore 后端到 Electron 桌面端完整指南

【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20+ more CLI Agent | Customize your assistants | Team them up｜Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi

本指南面向希望在 AionUi 仓库中搭建本地开发环境、理解前后端联动机制并参与开发的工程师。AionUi 是一个开源的 24/7 AI 协作桌面应用，它把 OpenClaw、Claude Code、Codex、OpenCode 等 20+ 种 CLI Agent 封装为现代化聊天界面。读完本文，你将掌握：双仓库（AionCore + AionUi）的构建与启动流程、后端二进制从PATH被发现到被 Electron 自动拉起的完整链路、开发/构建/测试/调试全套脚本的用途、多实例并行开发的隔离机制，以及 prek 代码检查与 electron-vite 构建系统的工程约定。文中所有结论均可在仓库的 docs/contributing/development.md 与对应源码中逐一验证。

一、前置依赖与平台要求

在开始之前，请确保开发机满足以下工具链要求（均以本仓库 docs/contributing/development.md 描述为准）：

Windows 用户特别注意：需要使用 Rust MSVC 工具链；若 Rust 编译因缺少原生构建工具而失败，请从 Visual Studio Installer 安装Microsoft C++ Build Tools，然后重新打开终端再编译。

依赖安装方式请参考 bun、rustup 等工具的官方安装文档（安装包均已在上表列出）。安装完成后，可以用bun --version、rustc --version、python3 --version快速自检。

二、双仓库布局：AionCore 与 AionUi 的分工

AionUi 的开发依赖两个仓库协同工作，这是理解整个开发流程的关键：

• AionCore：负责构建本地后端二进制，macOS/Linux 上为aioncore，Windows 上为aioncore.exe。它承载 SQLite 数据库、API 服务、Agent 进程管理等后端能力。
• AionUi：启动 Electron 桌面应用，并在启动时自动拉起后端二进制。

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

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

桌面开发服务器通过bun run start继承的PATH来解析后端二进制。因此必须先安装 AionCore 并验证二进制在当前终端可见，再启动 AionUi，顺序不能颠倒。

三、快速开始：完整构建与启动流程

3.1 克隆两个仓库

git clone <AionCore 仓库地址> git clone <AionUi 仓库地址>

两个仓库默认使用main分支，除非维护者明确要求测试其他分支。

3.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或等效文件），新开终端后再次验证。

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 窗口后再次验证。

3.3 启动 AionUi

在AionUi 仓库目录、且aioncore可见的终端中执行：

cd AionUi # 安装依赖 bun install # 以开发模式启动 Electron 桌面应用 bun run start

启动过程中，AionUi 会自动拉起aioncore并把后端端口传给渲染进程——你不需要在另一个终端单独启动 AionCore。

3.4 源码视角：Electron 如何"接管"后端进程

从源码可以还原这条自动拉起链路的实现细节。入口脚本 scripts/webui.ts 与 packages/web-host/src/backend-launcher.ts 共同构成了后端进程的生命周期管理：

• 二进制解析：优先使用AIONUI_BACKEND_BIN环境变量指定的绝对路径；其次查找resources/bundled-aioncore/<platform>-<arch>/下的内置二进制；最后通过which/where在PATH中查找。三种方式都失败时抛出Cannot find "aioncore"错误。
• 启动参数：buildSpawnArgs 会拼接--port、--data-dir、--parent-pid、--log-level、--app-version等参数，并在打包场景追加--managed-resources-mode bundled。开发模式下还会注入AIONUI_CACHE_DIR、AIONUI_WORK_DIR、AIONUI_LOG_DIR三个环境变量，保证后端/api/system/info报告的系统目录与 Electron 主进程持久化的一致。
• 就绪探测：后端启动后，launcher 监听 stdout 上的AIONCORE_LISTENING <json>（端口上报）与AIONCORE_READY（权威就绪标记）两行输出，同时以 200ms 间隔轮询http://127.0.0.1:<port>/health（默认 30 秒超时），"就绪标记"与"健康检查"谁先到达谁胜出，避免误判慢启动。
• 端口选择：findAvailablePort 会避开一批 fetch 禁止端口（如 22、25、53 等），最多尝试 50 次，确保后端端口可被渲染进程正常访问。

这也是为什么开发文档反复强调"同一终端、PATH 一致"——后端二进制查找完全依赖启动 AionUi 时继承的环境。

四、更新本地后端：--force的正确用法

当你拉取或修改 AionCore 后，需要重装后端二进制并重启 AionUi：

cd ../AionCore cargo install --path crates/aionui-app --locked --force cd ../AionUi bun run start

关键点：当以相同AionCore 包版本重建本地改动时，必须使用--force，否则 Cargo 可能保留已安装的旧二进制。

五、后端启动故障排查手册

5.1Cannot find "aioncore" binary

AionUi 无法从bun run start继承的PATH中找到后端。请在启动 AionUi 的同一终端中检查：

# macOS / Linux which aioncore # Windows PowerShell where.exe aioncore

命令失败则把 Cargo 二进制目录加入PATH，然后新开终端再启动。

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

请确保bun run start是在能执行aioncore --help的同一个终端环境中启动的。IDE 内置终端与 GUI 启动的 shell 可能继承不同的PATH；更新PATH后请重启 IDE，或从终端启动 IDE。

5.3 后端改动不生效

退出 AionUi，用cargo install --path crates/aionui-app --locked --force重装 AionCore，再重新启动 AionUi。开发期间 Electron 应用持有后端子进程，运行中的 AionUi 实例不会拾取新安装的二进制，必须重启。

5.4 Windows Rust 编译错误

使用 Rust MSVC 工具链并安装 Microsoft C++ Build Tools；安装或切换工具链后，新开 PowerShell 窗口重新执行 AionCore 安装命令。

六、脚本参考大全（与 package.json 逐条对应）

以下所有命令均在仓库根 package.json 的scripts字段中定义，按用途分组说明。

6.1 开发类

其中 WebUI 系列由纯 Bun CLI scripts/webui.ts 实现——它不启动 Electron，而是"后端 + 静态服务器 + 认证"三者合一。该脚本暴露了完整的可调环境变量：AIONUI_PORT（静态服务器端口，默认开发 25809）、AIONUI_HOST（监听地址，设为0.0.0.0等价于开启--remote）、AIONUI_ALLOW_REMOTE、AIONUI_DATA_DIR、AIONUI_LOG_DIR、AIONUI_STATIC_DIR、AIONUI_BACKEND_BIN、AIONUI_OPEN_BROWSER等。

值得留意的是 WebUI 的数据目录隔离设计：脚本默认把数据放在~/.aionui-web（生产）或~/.aionui-web-dev（开发），而不是 Electron 使用的~/.aionui[-dev]。原因在源码注释中有详细说明——macOS 上 Electron 会把~/.aionui-dev创建为指向~/Library/Application Support/AionUi-Dev/aionui的符号链接，若 WebUI 抢先占用了该位置作为真实目录，会导致之后安装的 Electron 无法建立 CLI 安全符号链接，进而让桌面应用内所有 ACP Agent 的 CLI 命令全部失败。

6.2 构建与分发类

6.3 独立服务器类（非 Electron）

6.4 代码质量类

6.5 测试类

6.6 调试类

七、多实例开发：start:multi的隔离机制

当你拥有两个仓库克隆（例如AionUi与AionUi-refactor）并需要同时运行时，第二个实例用以下命令启动：

bun run start:multi

该命令本质是设置AIONUI_MULTI_INSTANCE=1后启动 electron-vite（见 package.json 中start:multi的定义），其隔离效果包括：

• 跳过 Electron 单实例锁，允许多个窗口并存；
• 使用独立的 userData 目录（AionUi-Dev-2），避免数据库与配置冲突；
• 隔离数据/配置符号链接路径（~/.aionui-dev-2、~/.aionui-config-dev-2）；
• Vite 渲染进程、CDP、WebUI 代理端口自动递增，避免端口占用碰撞。

端口约定在 packages/desktop/src/common/config/constants.ts 中可查：生产 25808、开发 25809、多实例开发 25810。scripts/webui.ts中DEFAULT_PORT的计算逻辑与之完全对齐（NODE_ENV=production→ 25808，AIONUI_MULTI_INSTANCE=1→ 25810，否则 25809）。

重要提示：多实例的 WebUI 默认端口是 25810（而非 25809）。在浏览器访问第二个实例的 WebUI 时，请使用无痕/隐私窗口——两个实例共享localhost的 cookie，而 JWT 密钥不同，复用同一浏览器会话会导致认证失败。

八、代码检查：prek（pre-commit 的 Rust 实现）

项目使用 prek，该配置被设计为"本地检查与 CI 检查完全一致"。

# 安装 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 可以看到完整的检查链：

1. 通用文件检查（pre-commit-hooks v5.0.0）：YAML/JSON/TOML 语法、合并冲突、大小写冲突、大文件（>1000KB 报错）、文件末尾换行、行尾空白（均排除二进制与特殊系统文件）；
2. TypeScript 类型检查：bunx tsc --noEmit，全项目检查（pass_filenames: false）；
3. Oxlint：bun run lint，仅检查暂存文件（取代 ESLint）；
4. Oxfmt：bun run format，自动修复暂存文件格式（取代 Prettier）；
5. i18n 校验：node scripts/check-i18n.js，针对packages/desktop/src/renderer/services/i18n/locales/下的翻译文件；
6. 提交信息规范：conventional-pre-commit v4.2.0，--strict --force-scope，允许类型为feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert，作用于commit-msg阶段。

九、构建系统：electron-vite 与三层产物

AionUi 使用electron-vite进行快速打包（配置文件为 packages/desktop/electron.vite.config.ts），三个进程分别处理：

• Main 进程：Vite 打包（ESM），入口为packages/desktop/src/index.ts，通过externalizeDepsPlugin外部化依赖（fix-path与@aionui/web-host例外，需内联打包）；
• Renderer 进程：Vite 打包（React + TypeScript），root 为packages/desktop/src/renderer，采用 MPA 模式（appType: 'mpa'），入口包括主界面index.html与宠物模块的多个pet*.html；
• Preload 脚本：Vite 打包，入口为packages/desktop/src/preload/main.ts及宠物相关 preload。

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

out/ ├── main/ # Main 进程代码 ├── renderer/ # Renderer 进程代码 └── preload/ # Preload 脚本

配置文件还体现了几个值得注意的工程决策：

• 版本号只信任根 package.json：packages/desktop/package.json是 workspace 内部占位文件（恒为0.0.0），用户可见版本统一从根package.json读取，并通过__APP_VERSION__注入渲染进程；
• 依赖去重：为规避 CodeMirror 单例失效问题，对react、react-dom、@codemirror/*等包做dedupe，确保语法高亮 facet 注册生效；
• 单 vendor chunk：React 及与其强耦合的 Arco Design、markdown 解析链、编辑器等被打入同一个vendorchunk，避免历史上因 chunk 循环 ESM 依赖导致的白屏问题；
• HMR 直连：dev server 默认端口 5173，HMR host 显式设为localhost，避免 WebSocket 误走 WebUI 代理造成无限刷新；
• Sentry 源映射：非开发环境且配置了SENTRY_AUTH_TOKEN时启用，上传后自动删除out/**/*.map。

十、技术栈一览

十一、进阶：编码规范与仓库结构速览

开发指南之外，仓库还有一份配套的 docs/contributing/file-structure.md，它定义了整个 Electron 项目的目录与文件组织规则，与本文的工程实践直接相关：

• 三层进程边界：src/renderer/（React UI，禁止 Node.js API）、src/process/（主进程，全部 Node.js/Electron 业务）、src/common/（跨进程共享层），跨进程通信必须走preload.ts+src/process/bridge/*.ts的 IPC 通道；
• 目录命名双轨制：渲染进程内的组件/功能模块目录用 PascalCase，其余（分类目录、平台目录如acp/、gemini/）一律小写；
• 测试文件镜像映射：测试必须与源码一一对应（如CronService.ts→tests/unit/cronService.test.ts），且tests/unit/超过 10 个直接子项后要按源码结构分子目录；
• 目录规模上限：单个目录直接子项不得超过 10 个，接近上限时按职责拆分。

结合本指南的 development.md 与 file-structure.md 两篇文档，你可以完整走通"环境搭建 → 双仓库构建 → 启动调试 → 编码规范 → 提交检查"的整条开发链路。

【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20+ more CLI Agent | Customize your assistants | Team them up｜Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi