随着 Claude Code、Qwen Code、OpenAI Codex 等命令行 AI 工具的兴起，开发者面临一个现实困境：每个工具都有独立的交互界面、独立的会话管理、独立的文件操作逻辑。当需要在不同模型之间切换，或同时与多个 agent 协作时，环境切换成本显著上升。AionUi 作为一款开源的本地 AI CLI 聚合器，尝试通过 ACP（Agent Communication Protocol）协议构建统一的运行时抽象层，将分散的 CLI 工具纳入一致的管理框架。本文将深入剖析 AionUi 的核心架构设计，聚焦工具发现机制、协议抽象层与本地会话管理的工程实现细节。
本地运行时定位与设计取舍
AionUi 的核心定位是「本地优先的 CLI AI 工具聚合平台」，这一定位决定了其架构设计的几个关键约束。首先，所有对话数据存储在本地 SQLite 数据库中，不经过任何云端中转，这一设计满足了对数据隐私敏感的企业用户需求。其次，工具本身仍由各 provider 独立维护，AionUi 只负责发现、调度与结果呈现，不介入 agent 的内部推理过程。这种「轻量级包装、重运行时聚合」的思路，使得 AionUi 能够保持对各 CLI 工具的版本兼容，同时避免维护复杂的多模型适配层。
从部署模式来看，AionUi 区分了两种核心运行模式：Gemini CLI 模式与 Multi-Agent 模式。Gemini CLI 模式是 AionUi 内置的完整功能集，用户下载即用，包含了图像生成、工具调度、多 API Key 轮转等高级特性。Multi-Agent 模式则面向已有 Claude Code、Qwen Code 等 CLI 工具的用户，通过 ACP 协议将外部工具接入统一的 GUI 界面。当前 Multi-Agent 模式的功能相对精简，主要提供会话管理、工作目录配置与权限确认等基础能力，未来规划通过 MCP（Model Context Protocol）集成实现更深度的高级功能对齐。
ACP 协议：多 CLI 工具的标准化接入层
ACP（Agent Communication Protocol）是 AionUi 实现多 agent 统一管理的核心协议。它定义了一套标准化的 RESTful 接口规范，用于客户端与 agent 服务之间的请求响应、状态同步与错误处理。从协议架构来看，ACP 采用经典的 client-server 模型：ACP server 负责封装具体的 CLI 工具并暴露 HTTP 端点，ACP client（即 AionUi 主程序）负责发现可用 agent、发起请求并渲染结果。这种设计允许一个进程同时扮演 server 与 client 角色，从而支持复杂的多 agent 编排场景。
在 AionUi 的具体实现中，ACP 协议承载了四类核心交互。第一类是 agent 发现与注册：AionUi 启动时会扫描系统 PATH 环境变量，通过 which（macOS/Linux）或 where（Windows）命令检测已安装的 CLI 工具，提取版本信息后注册到内部的 agent 列表。第二类是会话生命周期管理：每个 CLI 工具的会话被抽象为独立的上下文单元，拥有独立的工作目录、权限配置与消息历史。第三类是工具调用转发：当用户在 GUI 中发送消息时，AionUi 将请求封装为 ACP 格式，通过 HTTP 调用传递给对应的 CLI 进程，接收流式响应并实时渲染。第四类是权限确认交互：多数 CLI 工具在执行文件操作前会请求用户授权，AionUi 将这些确认对话框统一呈现在 GUI 中，支持临时授权与永久授权两种模式。
目前 AionUi 通过 ACP 协议支持接入的外部 agent 包括 Claude Code（命令 claude）、Qwen Code（命令 qwen）、CodeX（命令 codex）与 iFlow CLI（命令 iflow）。每个 agent 的集成都需要处理三个层面的差异：认证流程的适配（各 provider 采用不同的 login 机制）、输出格式的解析（不同 CLI 的流式响应协议存在差异）、以及工具能力的映射（部分工具支持图像生成、部分支持代码执行）。ACP 协议通过元数据机制描述每个 agent 的能力边界，AionUi 据此动态调整 UI 呈现与功能暴露。
工具发现的工程实现路径
工具发现是 AionUi 实现「即插即用」体验的关键环节。其实现逻辑可以分解为环境探测、版本校验与能力评估三个阶段。在环境探测阶段，AionUi 通过 child_process.execSync 执行平台相关的命令查找逻辑，以获取各 CLI 工具的可执行文件路径。随后，通过调用 claude --version、qwen --version 等命令获取版本号，用于兼容性判断与日志记录。
值得注意的是，工具发现并非一次性操作。AionUi 在每次启动时都会重新扫描 PATH，这一设计决策背后有明确的考量：用户可能在两次启动之间通过 npm 全局安装了新的 CLI 工具，动态扫描确保这些变化能够被及时感知。同时，AionUi 提供了手动触发重新检测的入口，用于处理 PATH 变更后需要即时生效的场景。在检测结果的处理上，AionUi 将可用 agent 列表存储在本地配置中，包含每个 agent 的路径、版本、默认工作目录与认证状态，这些信息在会话创建时会被读取并用于初始化连接参数。
会话隔离与上下文管理机制
多会话支持是 AionUi 与原生 CLI 工具的重要差异点。原生 CLI 工具通常采用单一会话模型，用户在一个终端中发起的对话会持续累积上下文，直到会话结束或达到上下文窗口限制。AionUi 的多会话架构则允许用户同时打开多个独立对话，每个对话拥有独立的上下文内存、独立的文件操作范围与独立的历史记录。这种设计在需要对比不同模型回答、或同时处理多个独立任务时尤为实用。
会话隔离的实现依赖于两个层面的机制：在 CLI 层面，AionUi 为每个会话创建独立的子进程实例，确保不同会话的输出流不会混淆。每个子进程配置独立的工作目录（可通过 GUI 指定或使用默认目录），这意味着文件操作的影响范围被严格限定在会话级别。在 GUI 层面，AionUi 使用 React 组件管理多会话状态，每个会话对应一个独立的聊天面板，面板之间通过消息总线进行事件传递而非直接状态共享。这种架构使得切换会话时的状态恢复成本降到最低，用户可以在不同 agent 之间快速切换而不丢失各自的对话进度。
会话数据的持久化采用 SQLite 作为存储后端。每个会话的消息历史、文件变更记录与元数据都保存在本地数据库文件中，支持跨会话查询与历史回溯。这一设计也支撑了 AionUi 的「本地数据安全」承诺：所有对话内容不经过任何云端服务，仅在用户授权的情况下才会被写入磁盘。
WebUI 模式与远程访问架构
AionUi 提供了可选的 WebUI 模式，允许用户通过浏览器从任意网络设备访问本地运行的服务。这一模式的典型使用场景是在服务器或开发机上运行 AionUi，从个人电脑或移动设备发起交互。从技术实现来看，WebUI 模式在主进程中启动一个额外的 HTTP 服务器，默认监听本地端口（可通过 --remote 参数开放给局域网访问），将 GUI 的渲染层替换为 HTML/JS/CSS 的响应式页面。
WebUI 模式的核心挑战在于如何在浏览器与本地 CLI 进程之间建立高效的通信链路。AionUi 采用了 WebSocket 与 HTTP 相结合的方案：对于流式响应（如 agent 的逐字输出），使用 WebSocket 保证实时性；对于会话管理、配置变更等操作，使用 REST API 保证幂等性。安全层面，WebUI 模式默认不启用认证，这是基于「本地信任网络」假设的设计决策。如果需要暴露到不受信的网络，建议通过反向代理或 VPN 隧道实现访问控制。
从部署实践来看，WebUI 模式在 Linux 服务器上的稳定性表现良好，主要得益于 Electron 主进程与 Node.js 运行时环境的成熟度。但在资源受限的嵌入式设备上，长时间运行的 WebUI 服务可能出现内存泄漏问题，建议定期重启或使用容器化部署方案。
跨平台兼容与系统集成细节
AionUi 的跨平台支持覆盖了 macOS（10.15+）、Windows（10+）与主流 Linux 发行版（Ubuntu 18.04+、Debian 10+、Fedora 32+），但不同平台的集成深度存在差异。在 macOS 上，AionUi 通过 Homebrew 提供安装包，支持自动更新与命令行调用。在 Windows 上，AionUi 以 MSI 安装包形式分发，支持添加到系统 PATH 与文件关联。在 Linux 上，AionUi 提供了 AppImage 与 deb 包两种选择，后者能够更好地集成到系统应用菜单与启动器。
系统集成的关键差异点在于进程管理与权限处理。在 macOS 上，Electron 应用需要通过公证（notarization）才能正常启动子进程，否则系统会拦截未经签名的外部命令调用。在 Windows 上，文件操作权限继承自父进程，用户在管理员权限的终端中启动 AionUi 后，子进程也拥有相应的提升权限。在 Linux 上，由于各发行版的权限模型差异，AionUi 需要显式处理 D-Bus 会话总线访问、用户目录权限等常见问题。
架构演进的当前局限与未来方向
尽管 AionUi 已经实现了多 CLI 工具的统一聚合，但其当前架构仍存在几个值得关注的局限。首先，Multi-Agent 模式下的功能完备性不及 Gemini CLI 模式：图像生成、多 API Key 轮转等高级特性仅在内置的 Gemini CLI 模式中可用，通过 ACP 接入的外部 agent 无法直接享受这些能力。其次，ACP 协议本身仍在演进中，当前版本对流式响应的处理依赖各 CLI 工具的私有输出格式，兼容性维护成本较高。第三，多 agent 协作场景的支持尚在规划阶段：用户可以同时打开多个会话，但无法在单个任务中让不同 agent 按序协作处理。
展望未来，AionUi 的演进方向包括 MCP 协议的深度集成、跨会话的上下文共享、以及基于路由的 agent 选择机制。MCP 集成将使 Multi-Agent 模式能够复用 AionUi 的工具生态，缩小与内置模式的功能差距。跨会话上下文共享则允许用户在多个独立会话之间传递文件或中间结果，形成更灵活的工作流编排能力。路由机制的引入则可以根据任务类型自动选择最适合的 agent，无需用户手动切换。
资料来源：本文技术细节参考 AionUi 官方 GitHub 仓库（https://github.com/iOfficeAI/AionUi）与 ACP 协议规范文档（https://agentcommunicationprotocol.dev）。