AionUi 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

AionUi 是一个以 TypeScript 为主要语言、采用 Apache-2.0 许可证的开源项目。仓库描述将其定位为面向 OpenClaw、Hermes、Claude Code、Codex、OpenCode 及其他命令行代理的 24/7 Cowork 应用，并提供自定义助手与团队协作能力。

根据给定仓库元信息，项目默认分支为 main，版本信息来自 package.json，当前为 2.2.2。仓库页面显示 Star 数为 32954、Fork 数为 3406；这些数据属于资料提供时的仓库状态，后续可能变化。

“Open-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20+ more CLI Agent | Customize your assistants | Team them up”
来源：README／仓库描述

定位与目标用户

该项目的核心定位不是单独提供某个模型，而是把命令行人工智能代理（CLI Agent）转换为图形化的聊天与协作界面。其实际价值取决于用户已经配置的代理、命令行工具、运行环境以及访问权限，AionUi 本身不能替代这些外部代理的安装和授权。

• 需要通过统一界面使用多个命令行代理的个人开发者。
• 需要自定义助手配置，并希望将多个代理组织成团队流程的研发小组。
• 需要在桌面应用、WebUI 或自托管服务器形态之间选择部署方式的运维人员。
• 需要阅读 ACP、队列、团队模式等架构资料并参与代码贡献的工程师。

“24/7”是仓库描述中的产品定位，不应直接解释为项目提供不间断运行承诺。资料没有给出服务等级协议（SLA）、可用性指标、并发上限或后台任务保证，生产部署前应自行验证。

核心功能

AionUi 的功能边界可以从仓库描述、依赖项、脚本名称和文档目录交叉确认。以下内容区分了资料明确给出的能力与实现机制，未提供的协议细节不作推断。

命令行代理的图形化交互

package.json 将项目描述为“Transform your command-line AI agent into a modern, efficient AI Chat interface”。这意味着用户输入会进入 AionUi 提供的聊天界面，再由项目连接或驱动已配置的命令行代理；代理的具体命令、模型、凭据和工作目录配置，资料中没有完整列出。

依赖中包含 @agentclientprotocol/sdk，文档目录还包含 ACP 相关架构资料，因此可以确认项目围绕 Agent Client Protocol（代理客户端协议，ACP）存在工程实现。资料没有提供完整消息格式、生命周期接口或兼容性矩阵，接入具体代理时应以仓库最新文档和源码为准。

助手自定义

仓库描述明确写有“Customize your assistants”。从产品层面看，用户可以围绕不同任务配置或选择助手；但资料未提供助手配置文件格式、字段清单、作用域和持久化方式，因此不能给出未经验证的配置示例。

仓库脚本包含 debug:custom-agent，这说明项目提供了面向自定义代理的调试入口。该入口的参数签名和输出格式未在给定资料中出现，使用时应运行仓库中对应脚本的帮助信息或查阅最新文档。

代理团队与协作模式

仓库描述包含“Team them up”，文档索引将队列（queue）和团队模式（team mode）列为架构主题，测试脚本还包含团队创建、代理生命周期、白名单和通信场景。由此可以确认项目对多代理团队流程进行了工程化处理，而不是只提供单个聊天窗口。

根据脚本名称，团队功能至少涉及创建、成员生命周期管理、通信和白名单测试。资料没有说明团队成员数量、调度算法、消息投递保证、失败重试策略或并发限制，因此这些指标不能作为部署承诺。

桌面、WebUI 与远程运行形态

项目使用 Electron Vite（Electron 构建工具链）启动桌面开发环境，并在脚本中提供 webui、webui:remote、webui:prod 和 webui:prod:remote。Dockerfile 则构建渲染器和服务器包，说明仓库同时覆盖桌面与服务端 WebUI 运行路径。

远程模式涉及 --remote 参数，Docker 运行时设置了 ALLOW_REMOTE=true。这只能说明仓库提供对应启动配置，不代表远程访问已经具备身份认证、细粒度授权或公网安全防护。

系统架构与关键模块

仓库文档按读者意图划分为 guides、contributing、architecture、specs、prds 和 readme。对使用者而言，部署资料位于 docs/guides/；对工程师而言，系统总览入口是 docs/architecture/overview.md，但该文件的具体内容未包含在本次资料中。

工作区与前端构建

package.json 使用 workspaces: ["packages/*"]，说明仓库采用多包工作区布局。桌面入口引用 packages/desktop/electron.vite.config.ts，Electron 主进程入口配置为 ./out/main/index.js；渲染器和主进程的完整源码边界，需要结合实际目录进一步核查。

Dockerfile 执行 bun run build:renderer:web 和 node scripts/build-server.mjs，随后将 dist-server 与 out/renderer 复制到运行镜像。这构成了“构建阶段生成服务端与渲染器产物，运行阶段使用生产依赖启动服务”的基本链路。

服务端、数据目录与数据库

Dockerfile 将 /data 声明为 SQLite 数据卷，并设置 DATA_DIR=/data。因此，容器部署时数据持久化边界至少包含该目录；如果不挂载宿主机目录，容器重建后的数据保留行为不属于资料已证明的能力。

仓库脚本包含数据库基准测试入口 bench:db 和 Bun 测试入口 test:bun，但资料没有提供数据库表结构、迁移机制、备份策略或容量上限。运维配置应在确认源码实现后再制定。

测试与质量工具

项目使用 Vitest 执行单元、集成、契约和基准测试，并使用 Playwright 执行端到端测试。脚本还提供 oxlint、oxfmt、覆盖率测试以及多个调试入口，说明仓库把静态检查、格式化和自动化测试纳入开发流程。

这些命令是工程工具入口，并不等于所有测试在任意操作系统或任意依赖版本下都能通过。资料没有给出测试通过率、执行时长、覆盖率目标或持续集成平台信息。

依赖与运行环境

项目的运行环境由 Node.js、Bun、Electron Vite、TypeScript 工作区和桌面或服务端构建链共同组成。Dockerfile 明确使用 node:20-slim 作为构建阶段基础镜像，运行阶段使用 oven/bun:latest，并安装 libicu-dev。

• 语言与工作区：仓库元信息标注主要语言为 TypeScript，包管理和工作区安装命令在 Dockerfile 中使用 Bun。
• 桌面开发：脚本通过 electron-vite 调用 packages/desktop/electron.vite.config.ts。
• 服务端运行：生产容器执行 bun dist-server/server.mjs。
• 运行时库：Dockerfile 安装 libicu-dev，注释说明 Office 预览组件启动需要 ICU。
• 数据存储：Dockerfile 将 SQLite 数据目录映射到 /data。

完整依赖清单位于仓库的 package.json 和 bun.lock，给定资料仅展示了部分依赖。未提供的操作系统版本、浏览器版本、显卡要求、内存要求和第三方代理安装方式，官方仓库未提供该信息，建议以最新 README 为准。

快速开始：最小可运行闭环

下面的闭环使用仓库中实际存在的 Bun 安装和开发启动脚本，适用于本地开发或测试环境。它不包含外部代理凭据，也不会向未授权目标发起请求。

安装依赖

git clone https://github.com/iOfficeAI/AionUi.git
cd AionUi
bun install

bun install 来自 Dockerfile 和仓库工作流；仓库还定义了 postinstall 脚本，因此安装过程中可能执行项目的安装后处理。系统尚未安装 Bun 时，官方仓库未提供该资料中的安装命令，建议以最新开发文档为准。

启动开发环境

bun run dev

该命令对应 electron-vite dev --config packages/desktop/electron.vite.config.ts，用于启动桌面开发环境。若只需要运行 WebUI，可使用仓库中定义的 bun run webui；WebUI 的监听地址、认证方式和实际访问 URL，资料中没有完整说明。

验证构建与测试入口

bun run lint
bun run test
bun run package

这三个命令分别对应静态检查、Vitest 测试和 Electron 构建。它们可用于验证依赖安装与源码状态，但不能替代对外部代理、远程访问和生产数据持久化的验收。

配置说明

当前资料能够核实的配置主要来自 Dockerfile 和 package.json 脚本。下表只列出真实出现过的字段；“未提供”表示资料没有给出明确默认值，不应据此推导隐含行为。

例如，Dockerfile 中定义的环境变量可以在本地测试服务端时按同样含义传入，但资料没有给出直接运行 server.mjs 所需的全部构建前置步骤。不要把 ALLOW_REMOTE=true 视为认证配置；认证、反向代理和网络访问控制的细节，官方仓库未提供该信息。

进阶用法

进阶使用主要围绕多实例、WebUI、打包分发、调试和测试展开。不同入口对应不同构建目标，使用前应确认当前目录已完成依赖安装。

多实例开发

bun run start:multi

该脚本通过 cross-env AIONUI_MULTI_INSTANCE=1 设置开关，再启动相同的 Electron Vite 配置。资料没有说明多实例之间的数据隔离、端口分配和状态共享规则，因此不宜直接将其视为生产集群机制。

WebUI 与远程模式

bun run webui
bun run webui:remote
bun run webui:prod
bun run webui:prod:remote

四个入口分别覆盖普通 WebUI、远程 WebUI、生产模式 WebUI 和生产远程 WebUI。监听端口、访问路径、认证方式以及远程模式的授权边界没有在资料中展开，部署到非本机网络前必须补充访问控制和隔离验证。

构建分发包

bun run dist:mac
bun run dist:win
bun run dist:linux

脚本名称表明仓库提供 macOS、Windows 和 Linux 的分发构建入口；另有 ARM64、x64 和 Debian 构建脚本。实际产物格式、签名流程、安装包位置和系统最低版本没有在给定资料中列明。

可观测性与运维

仓库提供性能、数据库、MCP 和启动基准相关脚本，但资料没有给出统一日志格式、指标协议、告警规则或运维控制台。部署时应先把应用日志、容器生命周期、数据目录和代理进程状态纳入可观测范围。

• debug:perf 设置 ACP_PERF=1 和 PERF_MONITOR=1 后启动应用。
• debug:perf:report 调用性能报告脚本。
• bench:startup 和 bench:full 用于启动或完整基准流程。
• debug:mcp、debug:mcp:list 和 debug:mcp:validate 用于 MCP 调试相关入口。

Docker 部署时，建议对 /data 执行备份、恢复和磁盘占用验证，并记录镜像版本与依赖锁文件。资料未提供备份命令、健康检查端点、日志轮转策略和升级回滚方案，不能把这些内容当作项目内置能力。

安全与合规边界

AionUi 会连接命令行代理，并且仓库提供远程 WebUI 配置，因此安全边界不仅在界面本身，还包括代理权限、工作目录、环境变量、网络访问和持久化数据。以下建议仅适用于拥有明确授权的本地、测试或组织内部环境。

• 只为已获授权的代码库、主机、文档和数据配置代理工作目录。
• 不要在聊天输入、日志或配置文件中暴露 API 密钥、访问令牌和个人隐私数据；资料未提供密钥托管机制。
• 启用远程模式前，应配置网络隔离、身份认证、访问控制和 HTTPS；仓库资料没有证明这些能力由 AionUi 自动提供。
• 对代理可执行的命令、文件读写范围和网络权限采用最小权限原则，并在测试环境验证副作用。
• 涉及个人信息、源代码、客户数据或受监管数据时，应根据组织政策完成数据分类、留存和审计评估。

项目不是安全扫描器、渗透测试工具或授权管理系统。不得将代理团队、远程 WebUI 或 CLI 集成用于绕过访问控制、攻击未授权目标或自动化违反服务条款的行为。

许可证与商用条款

仓库使用 Apache License 2.0（Apache-2.0），package.json 的 license 字段与 LICENSE 文件一致。该许可证授予在满足许可证条件的前提下复制、修改、公开展示、公开执行、再许可和分发源代码或目标代码的版权许可。

Apache-2.0 允许商业使用，但商业分发仍需遵守仓库 LICENSE 中的版权声明、许可证文本、修改说明和专利条款等要求。具体分发形式应逐条核对 LICENSE，不能仅依据“允许商用”四个字简化处理。

• 分发项目或衍生作品时，应保留适用的版权、许可证和声明文件。
• 对修改内容应按照 Apache-2.0 的要求进行说明。
• 许可证不提供商标、专利或其他权利的无限制授权；专利授权和终止条件以 LICENSE 第 3 节为准。
• 第三方依赖可能具有各自许可证，整体分发前应分别核查。

本文不构成法律意见。涉及闭源商业产品、二次分发、SaaS 服务或专利风险时，应以仓库 LICENSE、依赖许可证和专业法律意见为准。

局限性与已知限制

本节集中列出资料能够确认的空白，避免把未公开信息包装成项目能力。部署决策应将这些空白转化为测试项。

• 未提供完整代理兼容性列表、各代理的安装步骤和版本矩阵。
• 未提供并发代理数量、团队规模、队列吞吐量、延迟或资源消耗指标。
• 未提供 WebUI 的认证、授权、审计和公网暴露方案。
• 未提供 SQLite 数据结构、迁移命令、备份恢复工具和数据保留策略。
• 未提供桌面端与服务端的最低操作系统、CPU、内存和磁盘要求。
• 未提供生产环境的 SLA、官方支持周期和安全漏洞响应承诺。

根据本文作者的经验判断，最需要优先验证的是代理进程的权限边界、长时间运行时的数据增长、远程模式的访问控制以及多代理任务失败后的恢复行为；这些判断不代表仓库已经声明存在对应缺陷。

适合谁

以下信号同时满足较多时，AionUi 的技术路线更值得评估。判断重点是已有代理栈、部署方式和团队工作流，而不是 Star 数量。

• 团队已经使用 OpenClaw、Hermes、Claude Code、Codex、OpenCode 或其他命令行代理，需要统一交互入口。
• 研发人员希望在桌面应用和 WebUI 之间切换，并愿意维护 Node.js、Bun 或 Electron 构建环境。
• 任务需要自定义助手，或需要把多个代理组织为团队流程，并且能够自行验证 ACP 和队列行为。
• 组织可以提供本地或隔离测试环境，能够自行承担代理权限、密钥保护和数据备份责任。
• 团队愿意阅读 TypeScript 多包工作区、测试脚本和架构文档，并在缺少指标时建立自己的验收标准。

不适合谁

以下信号表明应谨慎采用，或先选择更封闭、边界更明确的现有工具。这里不涉及未在资料中出现的替代产品名称。

• 需要官方提供明确 SLA、并发容量、合规认证或全天候技术支持，却无法自行进行压力和故障测试。
• 组织禁止命令行代理访问本地文件、外部网络或内部源代码，而项目又必须依赖这些代理完成工作。
• 团队只接受单一供应商托管服务，不希望维护 Bun、Electron、Docker、SQLite 或代理运行时。
• 场景要求完整的企业身份管理、细粒度审计、密钥托管和数据生命周期证明，而当前评估无法补齐这些外围系统。
• 任务属于高风险自动化，且无法建立授权记录、沙箱、人工审批和可回滚机制。

常见问题与排查（FAQ / Troubleshooting）

排查顺序应从依赖、启动脚本、运行模式和数据目录逐层缩小范围。资料没有提供统一错误码，因此下面只引用能够从仓库脚本和 Dockerfile 确认的检查入口。

执行 bun run dev 失败怎么办

先确认当前目录是仓库根目录，并执行 bun install。随后核对 packages/desktop/electron.vite.config.ts 是否存在；该路径来自 package.json 的开发脚本。如果仍然失败，官方仓库未提供该错误场景的固定排查表，建议以最新 README 和开发文档为准。

为什么远程 WebUI 不能直接暴露到公网

webui:remote 只说明脚本传入了 --remote，Dockerfile 中的 ALLOW_REMOTE=true 只说明运行时启用了远程配置。资料没有证明项目自动提供身份认证、TLS、限流或审计，因此公网部署前必须由部署方补充这些控制。

容器重启后数据如何保留

Dockerfile 将 /data 声明为卷，并设置 DATA_DIR=/data；部署时应把持久化存储挂载到该路径。具体备份命令、SQLite 文件名、迁移流程和恢复验证方式未在资料中给出，不能仅凭卷声明推断完整灾备能力。

如何运行团队相关测试

bun run test:e2e:team
bun run test:e2e:team:create
bun run test:e2e:team:lifecycle
bun run test:e2e:team:whitelist
bun run test:e2e:team:comm

这些命令来自 package.json，分别覆盖团队端到端测试、创建、生命周期、白名单和通信场景。资料没有说明测试所需的外部代理、浏览器安装步骤和环境变量，运行失败时应查阅 Playwright 配置与项目测试文档。

如何检查 MCP 相关配置

bun run debug:mcp:list
bun run debug:mcp:validate

脚本名表明这两个入口分别用于列出和验证 MCP 配置，但输出格式和配置来源没有在给定资料中出现。不要把命令输出当作安全审计结论，仍需核对实际连接目标与权限范围。

项目地址与资源

以下链接仅列出资料中出现的项目仓库和官方站点，适合用于获取源码、文档和后续版本信息。

• AionUi GitHub 仓库
• AionUi 官网与文档