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 upStar 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 描述为准依赖版本要求用途Node.js22 或更高运行构建工具链仓库package.json中engines声明为22 25bun最新稳定版包管理器与运行时所有脚本均通过bun run驱动Rust stable Cargo最新稳定版编译本地 AionCore 后端二进制Python3.11用于原生模块编译prek最新稳定版npm install -g j178/prekPR 代码检查工具pre-commit 的 Rust 实现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 上为aioncoreWindows 上为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 / Linuxcd 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 PowerShellcd 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 后需要重装后端二进制并重启 AionUicd ../AionCore cargo install --path crates/aionui-app --locked --force cd ../AionUi bun run start关键点当以相同AionCore 包版本重建本地改动时必须使用--force否则 Cargo 可能保留已安装的旧二进制。五、后端启动故障排查手册5.1Cannot find aioncore binaryAionUi 无法从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 开发类命令说明bun start以开发模式启动 Electron 应用桌面bun run start:multi在已有实例旁启动第二个 Electron 实例见第七节多实例开发bun run clibun start的别名bun run webui以 WebUI 模式启动浏览器访问无 Electron 窗口bun run webui:remote以 WebUI 模式启动并开启远程访问bun run webui:prod以生产模式启动 WebUIbun run webui:prod:remote以生产模式启动 WebUI 并开启远程访问bun run resetpass通过 CLI 重置用户密码其中 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 构建与分发类命令说明bun run package构建全部进程main、preload、renderer到out/bun run makebun run package的别名bun run dist构建并打包当前平台的发行版bun run dist:mac/dist:win/dist:linux分别打包 macOS / Windows / Linuxbun run build-mac同时构建 macOS arm64 与 x64 发行版bun run build-mac:arm64仅构建 Apple Silicon 发行版bun run build-mac:x64仅构建 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 buildbun run build-mac的别名6.3 独立服务器类非 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 重置密码普通 / 生产6.4 代码质量类命令说明bun run lint检查 lint 问题oxlint只读bun run lint:fix自动修复 lint 问题bun run format自动格式化代码oxfmtbun run format:check仅检查格式、不修改文件bun run i18n:types为 i18n 键生成 TypeScript 类型6.5 测试类命令说明bun run test运行全部单元测试vitestbun 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.tsbun run test:packaged:i18n针对打包构建运行 i18n 集成测试bun run test:packaged:bun运行 Bun 打包集成测试6.6 调试类命令说明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 连接七、多实例开发start:multi的隔离机制当你拥有两个仓库克隆例如AionUi与AionUi-refactor并需要同时运行时第二个实例用以下命令启动bun run start:multi该命令本质是设置AIONUI_MULTI_INSTANCE1后启动 electron-vite见 package.json 中start:multi的定义其隔离效果包括跳过 Electron 单实例锁允许多个窗口并存使用独立的 userData 目录AionUi-Dev-2避免数据库与配置冲突隔离数据/配置符号链接路径~/.aionui-dev-2、~/.aionui-config-dev-2Vite 渲染进程、CDP、WebUI 代理端口自动递增避免端口占用碰撞。端口约定在 packages/desktop/src/common/config/constants.ts 中可查生产 25808、开发 25809、多实例开发 25810。scripts/webui.ts中DEFAULT_PORT的计算逻辑与之完全对齐NODE_ENVproduction→ 25808AIONUI_MULTI_INSTANCE1→ 25810否则 25809。重要提示多实例的 WebUI 默认端口是 25810而非 25809。在浏览器访问第二个实例的 WebUI 时请使用无痕/隐私窗口——两个实例共享localhost的 cookie而 JWT 密钥不同复用同一浏览器会话会导致认证失败。八、代码检查prekpre-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 可以看到完整的检查链通用文件检查pre-commit-hooks v5.0.0YAML/JSON/TOML 语法、合并冲突、大小写冲突、大文件1000KB 报错、文件末尾换行、行尾空白均排除二进制与特殊系统文件TypeScript 类型检查bunx tsc --noEmit全项目检查pass_filenames: falseOxlintbun run lint仅检查暂存文件取代 ESLintOxfmtbun run format自动修复暂存文件格式取代 Prettieri18n 校验node scripts/check-i18n.js针对packages/desktop/src/renderer/services/i18n/locales/下的翻译文件提交信息规范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 TypeScriptroot 为packages/desktop/src/renderer采用 MPA 模式appType: mpa入口包括主界面index.html与宠物模块的多个pet*.htmlPreload 脚本Vite 打包入口为packages/desktop/src/preload/main.ts及宠物相关 preload。构建产物输出到out/目录out/ ├── main/ # Main 进程代码 ├── renderer/ # Renderer 进程代码 └── preload/ # Preload 脚本配置文件还体现了几个值得注意的工程决策版本号只信任根 package.jsonpackages/desktop/package.json是 workspace 内部占位文件恒为0.0.0用户可见版本统一从根package.json读取并通过__APP_VERSION__注入渲染进程依赖去重为规避 CodeMirror 单例失效问题对react、react-dom、codemirror/*等包做dedupe确保语法高亮 facet 注册生效单 vendor chunkReact 及与其强耦合的 Arco Design、markdown 解析链、编辑器等被打入同一个vendorchunk避免历史上因 chunk 循环 ESM 依赖导致的白屏问题HMR 直连dev server 默认端口 5173HMR host 显式设为localhost避免 WebSocket 误走 WebUI 代理造成无限刷新Sentry 源映射非开发环境且配置了SENTRY_AUTH_TOKEN时启用上传后自动删除out/**/*.map。十、技术栈一览技术用途Electron跨平台桌面框架package.json中electron ^37.xReact 19UI 框架TypeScript类型安全全仓统一tsconfig.jsonVite经 electron-vite快速打包器UnoCSS原子化 CSS 引擎配置见 uno.config.tsbetter-sqlite3本地数据库^12.xvitest测试框架配置见 vitest.config.ts十一、进阶编码规范与仓库结构速览开发指南之外仓库还有一份配套的 docs/contributing/file-structure.md它定义了整个 Electron 项目的目录与文件组织规则与本文的工程实践直接相关三层进程边界src/renderer/React UI禁止 Node.js API、src/process/主进程全部 Node.js/Electron 业务、src/common/跨进程共享层跨进程通信必须走preload.tssrc/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 upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AionUi 开发环境搭建与多进程工程实践：从 AionCore 后端到 Electron 桌面端完整指南
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 upStar 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 描述为准依赖版本要求用途Node.js22 或更高运行构建工具链仓库package.json中engines声明为22 25bun最新稳定版包管理器与运行时所有脚本均通过bun run驱动Rust stable Cargo最新稳定版编译本地 AionCore 后端二进制Python3.11用于原生模块编译prek最新稳定版npm install -g j178/prekPR 代码检查工具pre-commit 的 Rust 实现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 上为aioncoreWindows 上为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 / Linuxcd 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 PowerShellcd 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 后需要重装后端二进制并重启 AionUicd ../AionCore cargo install --path crates/aionui-app --locked --force cd ../AionUi bun run start关键点当以相同AionCore 包版本重建本地改动时必须使用--force否则 Cargo 可能保留已安装的旧二进制。五、后端启动故障排查手册5.1Cannot find aioncore binaryAionUi 无法从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 开发类命令说明bun start以开发模式启动 Electron 应用桌面bun run start:multi在已有实例旁启动第二个 Electron 实例见第七节多实例开发bun run clibun start的别名bun run webui以 WebUI 模式启动浏览器访问无 Electron 窗口bun run webui:remote以 WebUI 模式启动并开启远程访问bun run webui:prod以生产模式启动 WebUIbun run webui:prod:remote以生产模式启动 WebUI 并开启远程访问bun run resetpass通过 CLI 重置用户密码其中 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 构建与分发类命令说明bun run package构建全部进程main、preload、renderer到out/bun run makebun run package的别名bun run dist构建并打包当前平台的发行版bun run dist:mac/dist:win/dist:linux分别打包 macOS / Windows / Linuxbun run build-mac同时构建 macOS arm64 与 x64 发行版bun run build-mac:arm64仅构建 Apple Silicon 发行版bun run build-mac:x64仅构建 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 buildbun run build-mac的别名6.3 独立服务器类非 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 重置密码普通 / 生产6.4 代码质量类命令说明bun run lint检查 lint 问题oxlint只读bun run lint:fix自动修复 lint 问题bun run format自动格式化代码oxfmtbun run format:check仅检查格式、不修改文件bun run i18n:types为 i18n 键生成 TypeScript 类型6.5 测试类命令说明bun run test运行全部单元测试vitestbun 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.tsbun run test:packaged:i18n针对打包构建运行 i18n 集成测试bun run test:packaged:bun运行 Bun 打包集成测试6.6 调试类命令说明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 连接七、多实例开发start:multi的隔离机制当你拥有两个仓库克隆例如AionUi与AionUi-refactor并需要同时运行时第二个实例用以下命令启动bun run start:multi该命令本质是设置AIONUI_MULTI_INSTANCE1后启动 electron-vite见 package.json 中start:multi的定义其隔离效果包括跳过 Electron 单实例锁允许多个窗口并存使用独立的 userData 目录AionUi-Dev-2避免数据库与配置冲突隔离数据/配置符号链接路径~/.aionui-dev-2、~/.aionui-config-dev-2Vite 渲染进程、CDP、WebUI 代理端口自动递增避免端口占用碰撞。端口约定在 packages/desktop/src/common/config/constants.ts 中可查生产 25808、开发 25809、多实例开发 25810。scripts/webui.ts中DEFAULT_PORT的计算逻辑与之完全对齐NODE_ENVproduction→ 25808AIONUI_MULTI_INSTANCE1→ 25810否则 25809。重要提示多实例的 WebUI 默认端口是 25810而非 25809。在浏览器访问第二个实例的 WebUI 时请使用无痕/隐私窗口——两个实例共享localhost的 cookie而 JWT 密钥不同复用同一浏览器会话会导致认证失败。八、代码检查prekpre-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 可以看到完整的检查链通用文件检查pre-commit-hooks v5.0.0YAML/JSON/TOML 语法、合并冲突、大小写冲突、大文件1000KB 报错、文件末尾换行、行尾空白均排除二进制与特殊系统文件TypeScript 类型检查bunx tsc --noEmit全项目检查pass_filenames: falseOxlintbun run lint仅检查暂存文件取代 ESLintOxfmtbun run format自动修复暂存文件格式取代 Prettieri18n 校验node scripts/check-i18n.js针对packages/desktop/src/renderer/services/i18n/locales/下的翻译文件提交信息规范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 TypeScriptroot 为packages/desktop/src/renderer采用 MPA 模式appType: mpa入口包括主界面index.html与宠物模块的多个pet*.htmlPreload 脚本Vite 打包入口为packages/desktop/src/preload/main.ts及宠物相关 preload。构建产物输出到out/目录out/ ├── main/ # Main 进程代码 ├── renderer/ # Renderer 进程代码 └── preload/ # Preload 脚本配置文件还体现了几个值得注意的工程决策版本号只信任根 package.jsonpackages/desktop/package.json是 workspace 内部占位文件恒为0.0.0用户可见版本统一从根package.json读取并通过__APP_VERSION__注入渲染进程依赖去重为规避 CodeMirror 单例失效问题对react、react-dom、codemirror/*等包做dedupe确保语法高亮 facet 注册生效单 vendor chunkReact 及与其强耦合的 Arco Design、markdown 解析链、编辑器等被打入同一个vendorchunk避免历史上因 chunk 循环 ESM 依赖导致的白屏问题HMR 直连dev server 默认端口 5173HMR host 显式设为localhost避免 WebSocket 误走 WebUI 代理造成无限刷新Sentry 源映射非开发环境且配置了SENTRY_AUTH_TOKEN时启用上传后自动删除out/**/*.map。十、技术栈一览技术用途Electron跨平台桌面框架package.json中electron ^37.xReact 19UI 框架TypeScript类型安全全仓统一tsconfig.jsonVite经 electron-vite快速打包器UnoCSS原子化 CSS 引擎配置见 uno.config.tsbetter-sqlite3本地数据库^12.xvitest测试框架配置见 vitest.config.ts十一、进阶编码规范与仓库结构速览开发指南之外仓库还有一份配套的 docs/contributing/file-structure.md它定义了整个 Electron 项目的目录与文件组织规则与本文的工程实践直接相关三层进程边界src/renderer/React UI禁止 Node.js API、src/process/主进程全部 Node.js/Electron 业务、src/common/跨进程共享层跨进程通信必须走preload.tssrc/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 upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
的 安装、使用 教程)
