【AionUi 技术全景与实战】开源 AI Cowork 工作台、Team Mode、多 Agent 路由与自动化执行

AionUi 是面向桌面端与 WebUI 的开源 AI Cowork 工作台，把会话、项目文件、MCP、Skills 与多种编码 Agent统一到一个工作空间。本文结合 AionUi 与 AionCore 源码，拆解 Electron/Rust 架构、Agent路由、OfficeCLI 文档交付与预览、Team Mode、定时任务、会话恢复和权限边界，并给出桌面安装、源码构建与 WebUI部署方法。

GitHub仓库：https://github.com/cmyk-labs/AionUi.git

（如果这个仓库对你有帮助，欢迎在 GitHub 上点一个 Star ⭐ 支持一下。）

官方GitHub仓库：https://github.com/iOfficeAI/AionUi

官方文档：https://github.com/iOfficeAI/AionUi/wiki

官方网站：https://aionui.com/

一、AionUi 是什么：从聊天窗口走向可执行的 AI 工作空间

AionUi 对自己的定位是开源 AI Cowork 应用。与普通聊天客户端相比，它关注的不只是“模型回答了什么”，而是“Agent 在哪个项目中工作、能够访问哪些文件和工具、执行过程如何展示、权限由谁确认、下次能否继续这次任务”。

从产品形态看，AionUi 把几类原本分散的能力放到了同一个工作空间：

功能域	核心能力	执行边界
工作台与会话	项目目录、上下文、消息、计划、工具状态与多会话管理	产品层统一展示，具体执行状态仍由所选 Agent 后端维护
模型与 Assistant	管理 LLM Provider、模型参数和可复用助手配置	内置 Agent 可以使用产品模型配置；外部 Agent 可能沿用自己的账号和模型机制
外部 Agent	发现并接入 Claude Code、Codex、Gemini CLI、ACP 等后端	不保证不同 Agent 拥有相同工具、模型、会话恢复或权限语义
文件与产物	绑定目录、上传文件、预览 Markdown、图片、代码和 Office 产物	写入范围受项目目录、后端工具和审批共同影响
Team Mode	Leader、Teammate、TaskBoard 与 Mailbox 协作	按 Backend Capability 选择 Team MCP 或 CLI fallback；不同后端的支持程度并不相同
MCP 与 Skills	连接外部工具，按需加载成套工作方法	按会话选择和能力过滤，不把全部配置无条件交给模型
Cron 自动任务	冻结会话配置并在本地调度执行	依赖 AionCore 常驻、设备可用、Agent 登录状态和权限
Electron 与 WebUI	桌面系统集成，或通过 Bun Host 提供浏览器入口	WebUI 需要额外认证、网络和目录隔离，默认配置不是公网多租户服务

以下图片来自项目 GitHub 仓库 README 与 resources/ 目录，链接固定到本文所分析的源码提交。

1.1 工作台、模型、助手与多 Agent

AionUi 首页承担的是任务入口与会话管理，而不是把所有功能堆进一个聊天框。用户可以选择 Agent、模型或助手，进入具体项目后再让 Agent 读取文件、生成文档或执行工具。模型配置和助手配置被抽成独立对象，因此同一个工作台可以服务不同的任务组合。

统一工作台与任务入口	LLM 服务与模型配置
可复用的助手与任务配置	在统一界面中选择不同 Agent

AionUi 自带基于 aionrs 的 Agent，同时也能连接多种外部 Agent。需要注意，“界面支持某个 Agent”不等于“所有 Agent 共享完全相同的模型、工具和权限能力”。官方文档明确说明，外部 Agent 仍保留各自的登录方式、模型选择、工具集合和行为特征，AionUi 主要提供统一的会话入口与展示层。

1.2 文件协作与产物预览

Cowork 场景的关键是把结果落到文件中。AionUi 可以把项目目录、上传文件和对话关联起来，并在界面中预览 Agent 生成或修改的产物。例如整理文件、生成表格、创建图片或并排比较多个会话，都不需要把所有内容复制回聊天消息。

生成结果直接预览	让 Agent 整理工作目录
生成并检查表格文件	多会话并排比较

二、整体架构：Electron 只是外壳，AionCore 承担核心服务

2.1 技术分层与源码目录

AionUi 当前的工程结构可以概括为“多种宿主 + 一个本地核心服务 + 多种 Agent 后端”。桌面版使用 Electron，纯 WebUI 使用 Bun 启动静态站点和反向代理；二者都会连接 AionCore。AionCore 是 Rust 编写的独立进程，基于 Axum、Tokio 与 SQLite，提供 REST API、WebSocket 实时事件和领域服务。

┌────────────────────────────────────────────────────────────┐
│                        用户界面                             │
│  Electron Renderer                      Web Browser          │
└───────────────┬──────────────────────────────┬─────────────┘
                │ preload 暴露有限 API          │ 同源 HTTP/WS
┌───────────────▼──────────────┐  ┌────────────▼─────────────┐
│ Electron Main Process         │  │ Bun Web Host              │
│ 窗口/文件选择/更新/子进程管理 │  │ 静态资源 + API/WS 反向代理 │
└───────────────┬──────────────┘  └────────────┬─────────────┘
                └──────────────┬───────────────┘
                               │ localhost REST + WebSocket
┌──────────────────────────────▼─────────────────────────────┐
│ AionCore：会话、项目、文件、Office 预览、MCP、Skills、权限 │
└──────────────┬────────────────────┬────────────────────────┘
               │                    │
        内置 aionrs Agent     外部 CLI / ACP / 兼容适配器

AionCore 的官方架构说明将 Rust Workspace 分为四层：

层次	代表模块	主要职责
基础层	common、api-types、db、runtime、process	公共类型、数据库、运行时与进程设施
能力层	auth、realtime	身份、鉴权与实时通信等横切能力
领域层	conversation、project、file、mcp、ai-agent、cron、team、office 等	承载具体业务规则
组合层	aionui-app	构造服务、注入依赖并组装 Axum 路由

AionUi 与 AionCore 是两个仓库，源码目录应分别理解：

AionUi/
├── packages/
│   ├── desktop/
│   │   └── src/
│   │       ├── process/                  # Electron 主进程与后端生命周期
│   │       ├── preload/                  # contextBridge 安全桥接
│   │       ├── renderer/                 # React 工作台与业务界面
│   │       └── common/                   # 跨进程类型与适配器
│   └── web-host/
│       └── src/                          # Bun 静态站点、反向代理与后端启动
├── scripts/
│   └── webui.ts                          # WebUI 开发与生产启动入口
└── package.json                          # Workspace、构建命令与 AionCore 版本

AionCore/
├── crates/
│   ├── aionui-app/                       # Axum 二进制入口与服务组装
│   ├── aionui-conversation/              # 会话、消息、恢复与 Skill 快照
│   ├── aionui-ai-agent/                  # Agent Registry、Factory 与运行时
│   ├── aionui-team/                      # TeamSession、Mailbox 与 TaskBoard
│   ├── aionui-mcp/                       # MCP 配置、连接与能力适配
│   ├── aionui-cron/                      # 定时任务与本地调度
│   ├── aionui-office/                    # OfficeCLI 预览、代理与格式转换
│   ├── aionui-db/                        # SQLite Repository 与迁移
│   ├── aionui-auth/                      # JWT、CSRF 与认证中间件
│   └── aionui-realtime/                  # WebSocket 与事件广播
├── ARCHITECTURE.zh-CN.md                 # 官方架构和依赖规则
└── Cargo.toml                             # Cargo Workspace 与依赖版本

宿主层只管理窗口、系统能力和本地服务生命周期，领域状态集中到 AionCore，前端因此可以在 Electron 与 WebUI 之间复用。AionCore 内部又让领域服务依赖 Repository Trait，最后由 aionui-app 统一装配，使 Agent、会话、项目文件和权限规则不必直接绑定 SQLite 或具体宿主。

2.2 Electron 的三层进程边界

桌面端将代码明确分为主进程、渲染进程和 preload：

• packages/desktop/src/process/ 运行在 Electron 主进程，负责窗口、系统能力、文件选择和后端生命周期，不能依赖 DOM；
• packages/desktop/src/renderer/ 运行界面，只使用浏览器能力，不应直接调用 Node.js API；
• packages/desktop/src/preload/ 通过 contextBridge.exposeInMainWorld 暴露经过筛选的桥接能力。

这种划分比在渲染进程中直接开放 Node 权限更容易控制攻击面。preload 并没有把整个 Electron 或文件系统对象交给页面，而是提供窗口操作、系统信息、后端端口和少量 IPC 方法。渲染层的大部分业务请求继续走 AionCore 的 HTTP 与 WebSocket 接口，因此 Electron 桌面版与 WebUI 可以复用较多前端逻辑。

应用启动时，主进程创建 BackendLifecycleManager，定位并启动 AionCore，等待健康检查通过后再让界面进入可用状态。后端二进制按以下优先级查找：

1. 环境变量 AIONUI_BACKEND_BIN 指定的路径；
2. 打包目录中的 bundled-aioncore/<platform>-<arch>/aioncore；
3. 系统 PATH 中已经安装的 aioncore。

这套解析顺序同时服务开发与分发：开发者可自行安装 AionCore，正式安装包则可以携带匹配平台的后端二进制。AionUi 的版本配置还固定了配套的 aioncoreVersion，减少 UI 与后端 API 不匹配的概率。

2.3 前端如何连接本地后端

桌面渲染层会读取 preload 同步暴露的后端端口，然后访问：

http://127.0.0.1:<aioncore-port>
ws://127.0.0.1:<aioncore-port>/...

WebUI 不直接知道 AionCore 的实际端口，而是向同源地址发送请求，由 Bun Web Host 反向代理 API 与 WebSocket。httpBridge.ts 对两种运行方式做了适配，所以业务组件不必分别实现桌面版和浏览器版客户端。

实时消息通道采用单例 WebSocket，并带有指数退避重连，重连上限约为 30 秒。这适合推送 Agent 消息、工具状态和审批请求；普通配置、列表和文件元数据仍使用 REST。需要注意，WebSocket 断开期间不是天然可靠消息队列，关键状态应由服务端持久化并允许重新查询，而不能只依赖某个瞬时前端事件。

三、多 Agent 怎样接入：先建立 Agent Catalog，再由 Factory 选择后端

“支持多个 Agent”最容易被误解为把所有 CLI 命令统一包装成一个 spawn()。AionCore 的实现更接近一个分层适配系统：Registry 先管理 Agent Catalog 并探测本机可用性；用户创建会话后，再由 Factory 根据 Agent 类型选择不同的运行路径。

3.1 Agent Registry：发现、元数据与可用性探测

registry.rs 将 Agent Catalog 作为内置、扩展和自定义 Agent 元数据的单一来源。Registry 会把 Catalog 信息写入或同步到存储中，缓存一份快照，并异步执行可用性探测。界面看到的名称、图标、能力和安装状态来自 Catalog，而不是每次打开选择框都遍历系统命令。

探测和握手写入通过有界 MPSC 通道串行化，避免并发探测同时修改同一 Agent 的状态。Registry 只解决“有哪些 Agent、哪些可用、它们声称支持什么”，不直接承担一次会话的执行。

当用户选定 Agent 创建会话时，factory/mod.rs 再按 session kind 分派到不同 factory：

• Aionrs：使用内置 Rust Agent 运行时；
• ACP：进入外部 Agent 的适配入口；
• Antigravity：进入独立的专用路径。

这里的 ACP 更像前端与领域层的统一类别，不代表所有外部 Agent 最终都使用完全相同的 ACP 子进程管理器。

3.2 外部 Agent 并非“一律走 ACP”

当前 factory/acp.rs 还会依据 Agent 元数据继续路由。源码中，Claude 和 Codex 使用 DirectCli 类型，由各自的 session backend 建立干净的会话任务；Antigravity 有单独的直接路径；其他满足条件的兼容 Agent才交给 AcpAgentManager。

用户选择外部 Agent
        │
        ▼
读取 catalog 元数据与能力声明
        │
        ├── Claude / Codex ──► Direct CLI Session Backend
        ├── Antigravity ─────► 专用 Direct Backend
        └── 其他兼容 Agent ─► ACP Agent Manager

这样设计比强行统一协议更务实。不同 CLI 对登录、会话恢复、权限请求、sandbox mode 和工具事件的表达差异很大。AionUi 统一的是会话产品体验和消息模型，底层适配器仍可以保留 Agent 原生能力。

以权限为例，Codex 后端会识别 sandbox 与 approval policy，Claude 后端维护自己的 permission mode，而 ACP Agent 通过 ACP permission request 进入统一审批路由。它们在 UI 上都可以呈现为“等待用户批准”，但后端实现并不相同。类似地，官方列出的 Agent 支持范围会持续变化，不能据此推断每个 Agent 都支持同样的 MCP transport、Skills 协议或会话恢复能力。

3.3 内置 aionrs Agent 的执行链

内置 Agent 由 factory/aionrs.rs 创建。它会读取当前用户加密保存的模型提供商配置，解析模型名称、基础 URL 和兼容参数，再合并这次会话选择的 MCP 与 Skills。会话文件保存到 AionUi 数据目录下，后续可以恢复。

AionCore 依赖的 aionrs crates 来自 iOfficeAI/aionrs 的固定版本标签。它承担模型循环、工具调用和 Agent 运行时等更底层的职责，AionCore 则负责把用户、会话、项目和权限这些产品级状态装配进去。

一次典型请求可以简化为：

消息进入 Conversation Service
    → 解析会话、项目与模型配置
    → 按 Agent 类型建立或恢复 Runtime
    → 注入本次会话允许的 MCP / Skills
    → Agent 进行模型调用与工具循环
    → 实时事件通过 WebSocket 返回界面
    → 消息、状态和后端会话锚点持久化

如果恢复时发现工具调用只有开始记录、没有匹配的结束结果，aionrs 路径还会清理这类孤立状态，避免上一轮异常退出破坏下一轮上下文。这说明“恢复会话”并不是简单地把数据库中的消息数组再次发送给模型，还要修复 Agent runtime 自己的执行状态。

从工程角度看，多 Agent 平台需要重点解决的不是 Agent 数量，而是统一可观察的消息事件、隔离会话上下文、明确共享文件范围，并让每个后端的能力差异能够被 UI 正确表达。AionUi 的 registry、factory 和 conversation service 正是在这些边界上分工。

3.4 Team Mode：Leader、Teammate 与任务协作机制

前面的“多 Agent”主要是让用户为一次会话选择不同后端，Team Mode 则是另一层能力：一个 Lead 接收总任务、拆分子任务并委派给多个 Teammate，成员可以并行执行，再由 Lead 汇总结果。每个成员都有独立的 conversation 和 Agent runtime，因此可以选择不同模型或后端；团队成员共享同一 workspace，文件产物可以直接协作。

图片来源：AionUi 固定版本 README

从 AionCore 的 aionui-team crate 看，Team 并不是在一个 Prompt 中要求模型“扮演多人”，而是由 TeamSession、Scheduler、Mailbox 和 TaskBoard 等组件共同协调：

REST 创建 Team
    → 为 Lead / Teammate 创建独立 Conversation 与 Runtime
    → 每个 Team 建立内存 TeamSession
    → Scheduler 协调唤醒、派单、空闲与失败状态
    → 按 Backend Capability 选择 Team MCP 或 Shell/CLI fallback
    → Mailbox / TaskBoard / Team 元数据写入 SQLite
    → 文件通过共享 Workspace 交换

Mailbox 保存成员间的异步消息、发送方、接收方、摘要和文件引用；TaskBoard 保存任务负责人、状态及 blocked_by 依赖关系，并在变更后广播实时事件。对声明了兼容 transport 的 Backend，Team MCP 运行在后端本地并由 Agent 进程调用；对不支持 Team MCP、但具备 Shell/CLI 能力的 Backend，协调工具通过 CLI fallback 暴露。浏览器只消费 REST 与 WebSocket 状态，不直接参与这两条 Agent 协作链。Capability 判定避免为了“协议统一”排除已有 CLI Agent，也意味着不同 Backend 的 Team 工具注入路径并不完全相同。

当前活动源码还实现了动态 spawn_agent：运行中的成员可以按可选择的 Assistant 目录增加 Teammate，新成员获得独立会话，但使用团队解析出的共享工作区。这里需要区分配置文档和活动代码：aionui-team/docs/README.md 中仍留有“动态 Spawn 未实现”的历史说明，而当前 session.rs 与 service/spawn_support.rs 已经存在对应实现，本文以固定提交的活动代码为准。

持久化与运行态也不是一回事。Team、Mailbox 和 TaskBoard 可以从 SQLite 恢复，TeamSession、调度器和 Agent 子进程仍属于内存运行态；异常退出后需要依据持久状态重新协调未读消息、失败成员和任务进度。共享 workspace 解决的是协作，不是强安全隔离：某个成员获得写权限后可以影响其他成员看到的文件，因此敏感任务仍应使用专门目录、版本控制和成员级审批。

四、MCP、Skills、会话记忆与权限：能力如何真正进入模型

这一部分决定了 AionUi 是“展示型客户端”还是能承担真实工作的 Agent 平台。MCP 与 Skills 都能扩展能力，但两者进入执行链的方式不同；会话记录与长期记忆也不是同一个概念；权限按钮之外还存在操作系统和文件路径边界。

4.1 MCP 不是全量塞给模型，而是按会话选择和能力过滤

AionCore 的 MCP 服务以用户为边界持久化配置，支持新增、编辑、启停、批量导入、连通性测试和工具查询。一个值得注意的默认值是：新添加的 MCP server 初始为禁用状态，用户需要显式启用，而不是添加后立即成为所有 Agent 的全局工具。

MCP 注入过程大致是：

1. 会话或预设保存被选择的 mcp_server_ids；
2. 创建 Agent runtime 时加载这些 server 的配置或会话快照；
3. 根据目标 Agent 声明的能力过滤 transport；
4. 只把通过过滤的 MCP server 交给对应 Agent backend；
5. Agent 自己完成工具发现，并按其协议把可用工具暴露给模型。

源码中的 MCP session injection 支持 stdio、HTTP 和 SSE 三类配置，但目标 Agent 不一定支持全部 transport。如果 Agent 没有声明 transport 能力，该组件采取偏保守的兼容策略，只默认接受 stdio。内置图片生成 MCP 也只有在目标支持 stdio 时才会被注入。

因此，“工具、MCP 是否全量一起暴露给 LLM”的准确答案是：平台先按用户、会话选择和 Agent transport 能力过滤；进入具体 Agent 后，工具如何组成模型请求，再由该 Agent 的协议与运行时决定。 AionUi 不是先把平台上所有 MCP 的全部工具描述无条件塞进每一轮 prompt，也没有一个适用于所有 Agent 的统一 LLM 工具路由器。

内置浏览器 MCP 的边界

桌面端包含基于 Chrome DevTools Protocol 的浏览器桥接。cdpBridge.ts 只向 MCP 暴露当前应用内激活的浏览器 webview，并检查 webContents 类型；CDP 端口和随机 token 通过子进程环境传给 AionCore，而不是写入数据库。

这个 token 可以减少误连接，但源码注释也明确提醒：本机其他进程仍可能观察相关信息，它不是对恶意本地进程的强身份认证。浏览器自动化能访问登录后的网页，风险往往高于普通搜索工具，使用时应把它视为高权限能力，并保留逐次审批或专用浏览器资料目录。

4.2 Skills：索引先行、正文按需加载

Skill 在 AionUi 中是包含 SKILL.md 的目录。文件 frontmatter 提供名称和描述，正文保存完整工作方法、规则或操作说明。Skill manager 会扫描内置、自定义、定时任务和扩展来源，建立缓存索引。

进入一次会话的 Skill 集合不是简单全选，而是：

(自动注入的内置 Skills − 用户排除项)
        ∪ 预设或会话显式选择的 Skills
        → 排序、去重
        → 形成 conversation skill snapshot

会话快照很重要。若用户在某次长任务进行到一半时修改全局配置，已经建立的会话不会毫无提示地换掉整套工作规则；恢复时也能知道当初选择了哪些 Skill。

在支持相应提示协议的路径中，首轮只需要给 Agent 提供 Skill 的名称、描述索引和加载说明，而不是把所有 SKILL.md 正文永久塞进上下文。当 Agent 输出 [LOAD_SKILL: skill-name] 时，manager 再加载对应正文。某些 backend 也会把选中的 Skill 目录软链接到 Agent 原生的 skill 目录，让原生机制负责加载。

所以 Skills 的准确结论是：

• 自动注入和显式选择决定候选集合；
• 会话级快照保证恢复时的配置一致性；
• 描述索引可以先进入上下文，完整正文按需加载；
• 对外呈现方式依赖 Agent backend，不保证所有 Agent 都使用同一个 prompt 模板。

这比每轮全量注入更节省 token，也降低无关规则互相冲突的概率。但 Skill 本身仍然是提示与文件，不能替代权限系统；写在 Skill 里的“不要删除文件”是行为约束，操作系统权限、sandbox 和审批才是执行约束。

4.3 Office Assistant：预设 Skill 如何交付并预览可编辑文档

AionUi 的 Office 能力分为任务预设、文件生成和产物预览三层，不能简单归结为一个前端预览组件。固定版本的 assistants.json 共定义 21 个内置专业 Assistant，其中 Word Creator、PPT Creator 和 Excel Creator 分别绑定 officecli-docx、officecli-pptx 与 officecli-xlsx；路演、财务模型、Dashboard、学术论文和可填 Word 表单等预设还会绑定更专门的 officecli-* Skill。这里的“21 个”是全部专业 Assistant 数量，并不表示有 21 个 Office Assistant。

Assistant 负责选择任务规则和固定 Skill，内置 aionrs Agent 再读取这些 OfficeCLI Skills，在绑定的项目工作区中调用 OfficeCLI 创建、检查或修改 Office 文件。真正写入 .docx、.pptx、.xlsx 的是 Agent 驱动的 OfficeCLI，不是 AionUi 前端，也不是 aionui-office 预览模块。

选择 Office 类 Assistant
  → 会话取得预设规则与固定 officecli-* Skill
  → aionrs 在项目工作区调用 OfficeCLI
  → 生成或修改 .docx / .pptx / .xlsx
      ├─ 用户打开产物 → 路径校验 → officecli watch → 受控代理 → UI 预览
      └─ 需要结构化提取 → ConversionService 转换为 Markdown 或 JSON

用户在产物区打开文件后，共用的 OfficeWatchViewer 会按 Word、PPT 或 Excel 类型调用 AionCore。后端优先在服务端解析 ChatFileRef；旧调用路径则校验 file_path 是否位于默认允许目录或显式 workspace 内。校验通过后，OfficecliWatchManager 为当前用户、文档类型和规范化路径建立会话，执行 officecli watch <file> --port <port>，等待本地端口就绪，再返回代理地址。

Electron 桌面端把该地址解析到 127.0.0.1:<port>，WebUI 则继续走 AionCore 的同源代理。WebUI 经 ProxyService 访问时，只有端口属于当前用户的活动预览会话才会向回环地址转发，因此仅猜到代理端口不能跨用户读取预览。Electron 桌面端直接连接本机回环服务，这一层主要依赖本机账户和进程边界，不应视为抵御恶意本地进程的强隔离。Viewer 卸载后会请求停止对应会话，后端随即终止 OfficeCLI 子进程。

aionui-office 的 ConversionService 与 watch/proxy 是并列分支，不是预览的前置步骤：DOCX 转 Markdown 依赖外部 Pandoc，Excel 转 JSON 使用 Calamine，PPT 转 JSON 调用 officecli ppt2json；正常 Office 预览直接走 watch 与 proxy。

OfficeCLI 缺失时，固定版本会尝试通过官方安装器安装后重试。二进制优先从 PATH 查找，也会检查 Windows 的 %LOCALAPPDATA%\OfficeCli\officecli.exe 和 Unix 的 ~/.local/bin/officecli。在 WebUI 模式下，OfficeCLI 必须安装在运行 AionCore 的后端主机，而不是访问页面的客户端；受限网络或禁止执行远程安装脚本的环境，应提前安装，并用 officecli --version 与 officecli watch --help 验证。

这条链路还有三项必须说明的边界：

• 固定前端的格式映射只把 .docx、.pptx、.xlsx 交给内嵌 Office 预览；旧版 .doc/.ppt/.xls、ODF 和宏格式被标为不支持，CSV 按文本查看。生成 Skill 的能力范围不能直接等同于内嵌预览范围。
• 启动可能因 OfficeCLI 缺失或版本过旧、安装失败、路径越界、端口冲突或约 15 秒的端口就绪等待超时而失败；界面会根据稳定错误码提供安装或重试提示。
• 名称虽然是 watch，固定源码明确说明它不会自动发现外部进程对文件的改写。AionCore 已实现强制刷新接口，但固定版本前端的刷新按钮尚未接线；Agent 改写已打开文件后，预览可能暂时显示旧内容，可关闭并重新打开标签页重新读取，不能承诺实时同步。

预览用于快速检查结构和内容，不等同于最终兼容性认证。交付前仍应在目标版本的 Microsoft Office、WPS 或其他实际阅读器中复核字体、图表、公式、动画和宏等运行时效果。

4.4 “独立记忆”实际保存了什么

AionUi README 会用“每个对话独立记忆”描述会话隔离。从源码能够确认的事实包括：

• conversation 表保存用户、Agent 类型、模型 JSON、额外配置、状态以及项目或文件夹绑定；
• message 表保存消息类型、结构化内容、顺序、状态、隐藏标志和后端 turn anchor；
• 每个 conversation 创建独立 Agent runtime，上下文不会自动混入其他对话；
• Aionrs、ACP、Claude、Codex 等路径分别保存可恢复的 session ID、thread 或 session 文件；
• 恢复对话时会尝试重新附着到 Agent 原生会话，而不是只依赖 UI 文本记录。

系统同时保存产品侧会话历史，并保留各 Agent 后端用于恢复的 session/thread 标识。本文所检查的代码没有证明系统已经提供跨所有会话、自动提炼并通过向量检索召回的全局语义长期记忆，因此不应把“独立记忆”扩大解释成一个已实现的长期记忆知识库。

对 Agent 平台而言，两类状态最好明确分开：

状态	典型内容	作用
产品会话状态	消息、项目、模型、Skills/MCP 选择、任务状态	重建 UI，管理用户数据和权限
Agent 原生状态	session ID、thread ID、工具调用进度、运行时文件	让具体 Agent 连续执行和恢复

只存第一类，恢复时可能丢失工具执行上下文；只存第二类，平台又无法可靠展示历史和实施用户级隔离。这是多 Agent 平台需要同时处理的复杂度。

4.5 权限请求怎样到达用户

ACP 路径有独立的 PermissionRouter。当 Agent 请求执行工具时，router 以 tool call ID 保存 pending request，通过实时通道发送给界面，然后使用 oneshot 等待用户选择；用户批准或拒绝后，结果再返回 Agent。如果窗口刷新或连接短暂断开，pending 请求仍可以重新列出；停止会话时则统一取消未决请求。

Direct CLI 路径沿用各自的协议。Codex backend 会处理 sandbox mode 和 approval policy，默认配置倾向 workspace-write 与 on-request；Claude backend 确保会话带有已识别的 permission mode，并能回复原生工具审批。不同 Agent 对“只读”“工作区可写”“完全访问”的含义不完全一致，UI 不能假设一个模式名适用于全部后端。

权限还可以形成记忆键，例如按 action[:command_type] 记录同类操作的决定。但“记住允许”应谨慎使用：命令类型相同，不代表目标路径、参数和数据敏感性相同。对于删除、外发、凭据读取和生产环境操作，逐次确认通常更安全。

文件路径保护与例外

AionCore 的文件 API 会 canonicalize 目标路径和允许的根目录，拒绝 .. 或符号链接逃逸；写入不存在的文件时会先校验其父目录。项目上传引用还必须位于受管 upload root 内。

不过，用户通过系统文件选择器明确选择的 Local 文件，会保留 canonicalized 主机路径，并不强制塞进上传沙箱。这是合理的桌面端能力，也是必须说明的例外：不能说 AionUi 的“所有文件访问都被固定在一个硬沙箱内”。真实边界由三部分共同组成：

• 用户选择的项目目录或本地文件；
• Agent backend 的 sandbox / permission mode；
• AionCore 文件与项目 API 的路径校验。

部署时应使用专门工作目录，避免直接把主目录、浏览器配置目录、SSH 密钥或云凭据目录作为项目根。即使 API 阻止路径穿越，获得命令执行权限的外部 CLI 仍可能受其自身 sandbox 配置影响。

4.6 SQLite 能力与并发边界

AionCore 使用文件型 SQLite，启用外键、WAL 模式和约 5 秒 busy_timeout，连接池最大连接数为 5；数据库 migration 内嵌并在启动时运行。启动阶段还有 advisory lock，用于降低多个实例同时迁移或抢占同一数据目录的风险。发现数据库损坏时，恢复操作需要显式授权，而不是静默覆盖用户数据。

这套配置很适合个人桌面应用和小规模受控 WebUI：部署简单、数据集中、无需额外数据库。但它不是高并发 SaaS 架构的证明。WAL 可以改善读写并行，却没有改变 SQLite 单文件写入协调的基本特征；连接池为 5 也表明当前设计重点是本地可靠性，而非大量租户同时写入。

如果要把 AionUi 改造成团队级公网服务，需要重新评估身份隔离、任务队列、水平扩展、数据库后端、文件对象存储和 Agent 进程资源配额，而不是只在 WebUI 命令后加一个公网监听参数。

4.7 定时任务怎样冻结配置并自动执行

AionUi 的定时任务不只是界面保存一条 Cron 表达式。aionui-cron 把调度分成 At、Every 和带可选时区的 Cron 三类；Cron 同时接受标准五段表达式和带秒的六段表达式，五段输入会自动补零秒。任务还会将消息、目标 conversation、Agent 类型以及模型、workspace、reasoning 等 Agent 配置保存到 CronJob。它既可以继续已有 conversation，也可以按配置创建新 conversation，因此“自动执行”仍复用正常的会话与权限链，而不是绕过 Conversation Service 另起一套 Agent。

用户或 Agent 创建 CronJob
    → 校验时间、时区与目标会话
    → SQLite 保存任务、下次运行时间和配置快照
    → CronScheduler 为任务创建 Tokio timer
    → 到点后 Executor 准备或恢复 Conversation Runtime
    → 发送预设消息并沿正常 Agent 链执行
    → 记录结果、重试次数与下一次运行时间

Scheduler 为每个已启用任务维护可取消的 Tokio handle；一次性任务睡眠到目标时间，间隔任务使用 interval，Cron 任务则根据表达式与时区计算下一次触发。目标 conversation 已被当前轮占用时，Executor 不会并发写入：未启用 queue_enabled 时按 30 秒间隔延迟重试，达到 max_retries 后记为 skipped；启用 queue_enabled 时，任何重叠执行直接记为 skipped。对于新建会话模式，执行器还会提前检查上一轮 Cron 会话是否仍在活动，避免堆积一串新会话。这种设计保护了执行顺序，但任务数量上升时，每任务一个内存 timer 和本地 SQLite 的组合并不等同于分布式调度系统。

休眠恢复也是重要边界。服务会重新加载已启用任务和可恢复的重试；如果普通触发时间已经错过，当前固定源码会将本次记为 missed、写入提示并重新计算后续时间，而不是唤醒后无条件补跑旧任务。定时任务可以做到本机常驻自动化，却仍依赖 AionCore 进程、设备唤醒、目标 Agent 登录状态和工具权限，不能把它描述成脱离运行环境的云端 24×7 保证。

五、安装、源码构建与 WebUI 部署

普通用户优先使用官方 Release；需要二次开发时再从源码同时准备 AionUi 与 AionCore。WebUI 适合局域网、VPN 或 SSH 隧道中的受控访问，不应把当前源码默认启动方式当成已经完成公网多用户加固的服务。

5.1 使用 Release 安装桌面版

进入官方仓库的 Releases，根据操作系统下载安装包。项目当前提供 macOS、Windows 与 Linux 构建，具体格式以 Release 页面为准。

macOS 还可以通过 Homebrew 安装：

brew install aionui

首次启动后可以先使用内置 Agent 并配置 LLM provider。若要使用 Claude Code、Codex、Gemini CLI 等外部 Agent，需要按照对应 Agent 的官方方式完成安装和认证；AionUi 负责发现与连接，并不会替代外部 Agent 自己的账号或 API 配置。

第一次使用时，先完成模型的最小对话测试，再给会话绑定独立测试目录。只启用任务必需的 MCP 与 Skills，并保持审批模式；确认 Agent 的文件和命令边界后，再逐步扩大自动化范围。

建议用下面的闭环验证产品层、Agent 后端和文件系统确实协作：

1. 配置一个可用 Provider，或完成某个外部 Agent 的官方登录；
2. 选择内置 Agent 或已经通过可用性探测的外部 Agent；
3. 给会话绑定专用测试目录，要求生成一个名称固定、内容可人工检查的文件；
4. 对文件写入、命令或外部工具请求逐项审批，在消息流中核对工具事件；
5. 在产物预览区打开文件，并确认它真实存在于测试目录；
6. 关闭并重新打开会话，检查消息历史与该 Agent 的 Session/Thread 是否能够恢复。

成功判据是模型响应正常、目标文件真实落盘、审批事件可见、重开后能继续对应会话。不同 Agent 的工具和恢复机制并不完全一致；某个外部 Agent 未通过其中一项时，应按它自己的适配器和登录状态排查，不能据此推断所有后端都失败。

5.2 从源码启动桌面应用

官方开发文档要求 Node.js 22+、Bun、Rust stable + Cargo 和 Python 3.11+；当前根目录 package.json 将 Node engine 约束为 >=22 <25。为了减少版本差异，建议使用 Node 22 LTS，并确保 Bun、Rust 与 Python 都能从终端直接调用。

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

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

安装后，确认 Cargo 的 bin 目录已经加入 PATH。Linux/macOS 通常是 ~/.cargo/bin，Windows 通常是用户目录下的 .cargo\bin。随后进入 AionUi：

cd ../AionUi
bun install
bun run start

启动脚本会运行 Electron 开发环境，并按前文的二进制查找顺序启动 AionCore。若系统中存在多个 AionCore，可以显式指定：

# Linux / macOS
export AIONUI_BACKEND_BIN=/absolute/path/to/aioncore
bun run start

PowerShell 对应写法：

$env:AIONUI_BACKEND_BIN = "C:\absolute\path\to\aioncore.exe"
bun run start

常用构建命令如下：

# 只构建 main、preload 与 renderer
bun run package

# 构建当前平台安装包
bun run dist

# 分平台构建
bun run dist:mac
bun run dist:win
bun run dist:linux

跨平台打包通常还受签名证书、系统工具链和原生依赖影响。最稳妥的方式是在目标平台或项目 CI 环境中构建，而不是假设一台机器能完整生成所有签名安装包。

5.3 启动纯 WebUI

源码中的 scripts/webui.ts 可以不启动 Electron，直接用 Bun 提供前端静态资源和反向代理，并管理 AionCore 子进程：

cd AionUi
bun install
bun run webui:prod

bun run webui 是开发模式，默认端口为 25809；上面的 webui:prod 才是生产模式，默认端口为 25808。两者默认只监听本机地址，WebUI 使用独立数据目录，通常不会直接复用桌面版数据。需要在受控局域网以生产模式监听时可以使用：

bun run webui:prod:remote

已打包应用也支持 WebUI 入口，命令形式以当前版本帮助信息为准，典型用法为：

AionUi --webui
AionUi --webui --remote

远程访问演示如下。图片来源：项目 GitHub 仓库固定提交的 resources/ 目录。

浏览器访问 WebUI	在工作台中管理自动任务

当前 WebUI 的安全边界

这里有一个必须依据当前源码说明的差异：官方指南可能介绍密码登录，但本文检查的 Web Host 启动器当前会给 AionCore 传入 --local；local identity 模式下，中间件注入固定本地用户，跳过 JWT，路由也不启用非本地模式的 CSRF 保护。--remote 则会让 Web Host 监听 0.0.0.0。因此，不能仅因为页面能通过浏览器打开，就认定当前启动方式已经是可直接暴露公网的多用户系统。

更安全的实践是：

• 默认保持 127.0.0.1 监听，通过 SSH 隧道访问；
• 或仅在可信 VPN、零信任网络和主机防火墙之后开放；
• 如使用反向代理，在代理层增加强认证、TLS、访问来源限制和请求日志；
• 为服务使用独立系统账户、独立数据目录和受限工作区；
• 不把 Agent 全访问模式与公开 WebUI 同时启用。

SSH 隧道示例：服务端保持默认本机监听，在客户端执行：

ssh -L 25808:127.0.0.1:25808 user@server

然后在客户端浏览器访问 http://127.0.0.1:25808。这样无需让 AionUi 直接监听公网地址。

六、从源码看 AionUi 的工程价值与适用边界

AionUi 的价值不只是支持了多少模型或 Agent，而是把多种异构执行后端组织成一个可交互的桌面工作空间。Registry 管理 Agent Catalog，Factory 决定实际路由，Conversation Service 关联项目与持久化状态，MCP/Skills 在会话级过滤和快照后进入运行时，权限请求再通过不同 Backend 的协议回到用户。

6.1 值得借鉴的设计点

• 统一产品层，但保留底层差异：Claude、Codex、ACP 与内置 aionrs 共享工作台，同时使用各自的 session、permission 和工具适配器。
• 能力配置进入会话快照：MCP 和 Skills 的选择可恢复，长任务不会因全局配置变化而悄悄更换规则。
• 宿主与核心服务解耦：Electron 管理桌面能力和子进程，AionCore 承担领域服务，WebUI 因而能复用核心。
• 安全依靠多层组合：项目根目录、路径校验、Agent sandbox、交互审批和系统账户共同构成边界。
• 同时保存产品与 Agent 状态：消息历史重建 UI，session/thread anchor 恢复具体 Agent 的执行上下文。

6.2 适合哪些使用场景

AionUi 更适合以下场景：

• 希望在一个桌面界面中比较或切换多个编码 Agent；
• 需要让 Agent 围绕本地项目目录持续工作，并预览生成文件；
• 希望用 MCP 与 Skills 构建个人研究、文档或办公自动化流程；
• 需要保留审批环节，而不是直接把所有命令交给无人值守脚本；
• 想研究多 Agent 桌面平台的前后端分离、会话恢复和权限架构。

以下场景需要额外工程投入：

• 直接面向公网的大规模多租户服务；
• 要求严格集中式 RBAC、审计归档和企业合规的生产系统；
• 需要高并发任务调度、水平扩容和分布式数据库；
• 希望不同 Agent 在 MCP、Skills、权限和模型行为上完全一致；
• 无人值守地操作高价值生产数据或敏感账号。

长期使用时应坚持“最小权限、独立目录、逐步放开”：重要仓库配合 Git 分支、提交前 diff 和外部备份。二次开发则应重点维护 Agent 能力声明、协议兼容、会话 migration 和权限语义，为快速更新的外部 CLI 保留版本探测与失败降级。

总体而言，AionUi 让模型走出聊天框，又没有把全部能力无条件交给模型。它以本地核心服务连接文件、工具与多种 Agent，再通过会话快照、审批和路径控制约束执行范围，适合搭建个人 AI 工作台，也适合研究多 Agent 客户端架构。

参考资料

1. AionUi GitHub 仓库：https://github.com/cmyk-labs/AionUi
2. AionUi 官方 GitHub 仓库：https://github.com/iOfficeAI/AionUi
3. AionUi 官方文档：https://github.com/iOfficeAI/AionUi/wiki
4. AionUi 官方网站：https://aionui.com/
5. AionCore 官方 GitHub 仓库：https://github.com/iOfficeAI/AionCore
6. OfficeCLI 官方 GitHub 仓库：https://github.com/iOfficeAI/OfficeCLI

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/weixin_66397563/article/details/163800522