写在前面：这篇博客基于 AionUi 仓库的全部文档、源码和技术设计文档撰写，面向三类读者：想用它做事的普通用户、想把玩源码的开发者、想深入贡献的核心参与者。内容由浅入深，可按需跳读。
第一章：它到底是什么？用一个比喻讲清楚
想象你是一家公司的老板，你现在有两个选择：
选项 A：雇一个秘书，你口述需求，他记下来，然后你们你来我往地沟通，所有事情最终还是你自己执行。
选项 B：雇一个全栈员工团队，你说"帮我把这季度的销售数据整理成报告，做成 PPT，发到 Slack 群里"，然后他们自己分工、自己干、你就等结果。
大多数 AI 聊天应用（ChatGPT、Claude.ai）是选项 A。
AionUi 是选项 B。
它是一个开源、免费、跨平台的 AI Cowork（AI协同工作）平台。AI 在你的电脑上拥有真正的执行权：读写文件、执行代码、搜索网络、生成文档，并且支持多个 AI Agent 组成团队并行工作，还能 24/7 无人值守自动运行定时任务。
┌────────────────────────────────────────────────────────────┐
│ AionUi vs 传统 AI 聊天客户端 │
├───────────────────┬────────────────┬────────────────────────┤
│ 能力 │ 传统 AI 聊天 │ AionUi │
├───────────────────┼────────────────┼────────────────────────┤
│ 读写本地文件 │ ❌ │ ✅ 内置 Agent │
│ 执行多步骤任务 │ 有限 │ ✅ 自主规划+执行 │
│ 手机/平板远程访问 │ 少见 │ ✅ WebUI + Telegram 等 │
│ 定时自动执行 │ ❌ │ ✅ Cron 24/7 │
│ 同时使用多个 AI │ ❌ │ ✅ 20+ Agent 并行 │
│ 费用 │ 付费 │ 完全免费开源 │
└───────────────────┴────────────────┴────────────────────────┘
第二章：5分钟上手（普通用户）
安装
三种方式，选一种：
# 方式一：官网下载安装包（推荐新手）
# 访问 https://github.com/iOfficeAI/AionUi/releases 下载对应平台安装包
# 方式二：macOS Homebrew
brew install aionui
# 方式三：Linux .deb
wget https://github.com/iOfficeAI/AionUi/releases/latest/download/AionUi-linux-amd64.deb
sudo dpkg -i AionUi-linux-amd64.deb
支持平台：macOS 10.15+、Windows 10+、Linux (Ubuntu 18.04+/Debian 10+/Fedora 32+)
第一次启动：3步开始工作
① 安装 AionUi
↓
② 登录方式（任选一种）：
• Google 账号登录 → 免费 Gemini Agent（推荐零成本体验）
• 粘贴 API Key → Anthropic / OpenAI / DeepSeek / 本地 Ollama 等
↓
③ 开始对话，AI 就是你的协作者
入门示例①：整理一个混乱的下载文件夹
打开 AionUi，选择"Cowork"助手，直接说：
"帮我整理 /Users/我的用户名/Downloads 文件夹，按文件类型（图片、文档、压缩包、安装包）分类到子文件夹里，重复文件保留最新的。"
AI 会自动读取文件夹、分析内容、执行移动操作，全程你可以实时看到每一步在做什么。
入门示例②：一键生成 PPT
"根据这份文字材料（拖拽 txt 文件进对话框），帮我制作一份 10 页的季度汇报 PPT，风格商务简洁，包含数据图表。"
输出是真实可编辑的 .pptx 文件，带 Morph 动效转场，直接用 PowerPoint 或 WPS 打开编辑。
入门示例③：让 AI 每天早上给你发摘要
在设置里找到定时任务，创建一个任务：
触发时间：每天 08:30（Cron: 30 8 * * *，时区 Asia/Shanghai）
执行内容："搜索今天科技圈最重要的 5 条新闻，整理成简报发给我"
执行模式：每次创建新对话
设置完成后，AionUi 会在你睡觉时自动运行，早上起来就有新鲜简报等你。
第三章：进阶玩法（进阶用户）
远程访问：把 AI 随身带
AionUi 内置 WebUI 服务器，可以让你用手机或任意设备访问。
局域网访问（家庭/办公）：
# 桌面端启动时带上 --webui --remote 参数
# macOS:
/Applications/AionUi.app/Contents/MacOS/AionUi --webui --remote
# Linux:
aionui --webui --remote
启动后打印形如 Server running at http://192.168.1.100:25808，手机浏览器直接访问这个地址就行。
外网访问（云服务器部署）：
# Linux 服务器一键启动脚本（xvfb 提供虚拟显示器）
nohup xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" \
/usr/bin/AionUi --webui --remote --no-sandbox \
> /var/log/aionui.log 2>&1 &
# 或者用 ngrok 穿透（适合没有公网 IP 的场景）
ngrok http 25808
配置完成后，架构如下：
你的手机/平板
│ 浏览器访问
▼
http://你的服务器IP:25808
│ WebSocket
▼
AionUi 服务器端
（处理 AI 逻辑、文件操作）
│ API 调用
▼
Gemini / Claude / OpenAI ...
多 AI 协同：同时使用多个 Agent
如果你已经安装了 Claude Code、Qwen Code 等 CLI 工具，AionUi 会自动检测并集成它们，在同一界面并行使用：
AionUi 支持的 CLI Agent（自动检测）：
┌──────────────┬─────────────────────────────────┐
│ 工具名称 │ 检测命令 │
├──────────────┼─────────────────────────────────┤
│ Claude Code │ claude --experimental-acp │
│ Qwen Code │ qwen --acp │
│ OpenAI Codex │ codex │
│ Goose AI │ goose acp │
│ GitHub Copilot│ copilot --acp --stdio │
│ Cursor Agent │ agent acp │
│ Kiro │ kiro-cli acp │
│ ... 共 16+ │ │
└──────────────┴─────────────────────────────────┘
你不需要任何配置，AionUi 启动时会扫描系统 PATH，有什么用什么。
接入即时通讯：Telegram 控制 AI
在设置中配置 Telegram Bot Token 后，可以直接在手机 Telegram 里对话控制你的 AI：
你 → Telegram Bot → AionUi → AI Agent → 执行任务 → 返回结果给你
同样支持：飞书（Lark）、钉钉、企业微信（WeCom）、微信。
命令队列：批量发任务不怕 AI 忙
开启 Settings → System → Enable Command Queue 后，AI 在处理任务时你可以继续排队发指令，最多 20 条，AI 依次处理：
[任务1] 整理文件 ← AI 正在执行
[任务2] 写报告 ← 已入队，等待中
[任务3] 发邮件 ← 已入队，等待中
第四章：Team Mode——多 Agent 团队协作（高级）
这是 AionUi 最强大的特性之一，也是它区别于所有同类工具的核心能力。
什么时候用 Team Mode？
当一个任务涉及多个专业方向，并且子任务可以并行执行时。比如：
- 开发一个完整的 Web 应用（前端 + 后端 + 数据库 + 部署）
- 做一份全面的市场调研报告（竞品分析 + 数据采集 + 图表制作 + 排版）
- 代码库重构（模块A + 模块B + 测试 + 文档 可以同时进行）
Team Mode 是怎么工作的
用一张时序图来说清楚：
用户 Solo Agent（单 Agent 模式） MCP Server Team Lead Team Members
│ │ │ │ │
│──"帮我做电商网站"──────▶│ │ │ │
│ │ ② 分析：涉及前端+后端+DB+运维 │ │ │
│◀──③ "建议开启团队模式"──│ │ │ │
│ │ │ │ │
│──④ "好的，开启"────────▶│ │ │ │
│ │──⑤ aion_create_team ─────────▶│ │ │
│ │ │── 创建Team │ │
│ │ │── 启动MCP Server │ │
│ │ │── 写入SQLite DB │ │
│ │◀──⑥ { teamId, route }────────│ │ │
│ │──⑦ aion_navigate ────────────▶│ │ │
│◀──⑧ 跳转到 Team 页面 ───│ │ │ │
│ │ │──发需求摘要──────▶│ │
│ │ │ │── 拆分任务 │
│ │ │ │── spawn 成员 │
│ │ │ │──分配给─────────────▶│
│ │ │ │ │── 并行执行
│◀─────────────────────── 实时看到多 Agent 并行工作进度 ──────────────────────────────────────────│
实操示例：让 AI 团队开发一个 Todo App
你只需要对任何一个 Agent 说：
"我想做一个 Todo List Web App，包含前端 React 页面、后端 Express API、PostgreSQL 数据库设计和 Docker 部署配置。帮我组建团队来完成。"
AI 会自动评估任务复杂度，建议开启 Team Mode，得到你确认后：
- Leader Agent 接收任务，制定整体计划
- 自动派生 Frontend Agent 负责 React 部分
- 自动派生 Backend Agent 负责 Express API
- 自动派生 DBA Agent 负责数据库 Schema
- 各 Agent 在同一个工作目录并行写文件，互不干扰
你在 Team 页面实时看到每个 Agent 的状态（工作中 / 等待权限确认 / 完成），每个 Agent 有独立的权限确认弹窗，你对任何一个批准或拒绝都不影响其他 Agent。
Team Mode 核心设计
Team Mode 架构（Main Process 内）：
TeamSessionService TeammateManager
│ │
│ 创建 Team DB 记录 │ 管理 Agent 生命周期
│ 分配共享 Workspace │ 动态 spawn / remove
│ │
└──────────┬─────────────────┘
│
Team MCP Server
（进程内 MCP 服务）
│
┌──────────┼──────────────┐
│ │ │
Leader Member① Member②
Agent Agent Agent
│ │ │
└──────────┴──────────────┘
共享 Workspace 文件夹
每个 Agent 独立 session
通过 MCP 邮箱通信
第五章：技术架构深解（开发者）
如果你想深入代码，这一章是你需要的。
Electron 三进程模型
AionUi 是一个标准的现代 Electron 应用，严格遵守三进程隔离原则：
┌─────────────────────────────────────────────────────────────────┐
│ AionUi 进程模型 │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────┐ │
│ │ Renderer 进程 │ │ Main 进程 │ │
│ │ │ IPC │ │ │
│ │ React 19 UI │◄───────►│ Node.js + Electron API │ │
│ │ UnoCSS 样式 │ │ SQLite 数据库 │ │
│ │ 浏览器 API │ │ Cron 定时任务 │ │
│ │ ❌ 不能用 Node.js │ │ MCP 服务管理 │ │
│ └─────────────────────┘ │ ❌ 不能用 DOM API │ │
│ ▲ └──────────┬────────────────┘ │
│ │ │ │
│ ┌──────┴───────┐ ┌────────▼──────────┐ │
│ │ Preload 脚本 │ │ Worker 进程们 │ │
│ │ │ │ │ │
│ │ contextBridge│ │ Gemini Worker │ │
│ │ 安全桥接 │ │ ACP Worker │ │
│ │ 两边都能访问 │ │ Codex Worker │ │
│ └──────────────┘ │ （各自独立进程） │ │
│ └───────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
重要规则：跨进程通信必须通过 IPC Bridge，直接访问会导致运行时崩溃。
四种运行模式
运行模式 启动命令 特点
─────────────────────────────────────────────────────────
Electron 桌面 bun start 标准桌面窗口 + 可选 WebUI
无窗口 WebUI bun run webui 无 Electron 窗口，浏览器访问
远程 WebUI bun run webui:remote 支持外网访问
纯服务器模式 bun run server:start 无 Electron 依赖，适合 Linux 服务器
※ 10个 Electron-only Bridge 不可用
WebUI 和 Electron IPC 的优雅设计：它们连接到完全相同的 Bridge Handler，不同的只是传输层（IPC vs WebSocket）。这意味着所有功能在桌面端和浏览器端完全一致。
Electron 窗口用户 ──── IPC ────────────┐
▼
Bridge Handlers + Services + DB
▲
浏览器/手机用户 ───── WebSocket ────────┘
ACP 协议——核心中的核心
ACP（Agent Communication Protocol）是 AionUi 自研的多 Agent 通信协议，理解它就理解了整个项目的灵魂。
ACP 做什么： 把 Claude Code、Qwen Code 等各种 CLI 工具抽象成统一的 JSON-RPC 接口，让 AionUi 可以用同一套代码驱动所有这些 Agent。
ACP 状态机（7个状态）：
connect()
DISCONNECTED ──────────▶ CONNECTING
│ spawn 成功
▼
INITIALIZING ──── 超时(60s) / 崩溃 ──▶ ERROR_STARTUP
│ initialize 握手完成
▼
CONNECTED
│ newSession() / loadSession()
▼
HAS_SESSION ◄──── cancelPrompt() ──┐
│ │
sendPrompt() │
│ │
▼ │
STREAMING ──────────────────────── ┘
│ 进程崩溃
▼
DISCONNECTED（自动重连）
自动重连机制： 当 sendMessage() 发现连接断了，会自动执行完整的 connect → initialize → newSession/loadSession 序列，首次失败后 300ms 重试一次，对用户完全透明。
Claude Code 的实际连接路径（有点烧脑但很有趣）
很多人以为 AionUi 是直接调用 Claude Code CLI 的，实际上有三层子进程嵌套：
AionUi (Electron Main Process)
│
│ spawn via npx
▼
@zed-industries/claude-agent-acp（ACP Bridge，~Node.js进程）
│ 负责 ACP 协议 ↔ Claude SDK 的翻译
│
│ spawn via SDK内部
▼
@anthropic-ai/claude-agent-sdk/cli.js（内嵌 Claude Code，~13MB）
│ 完整的 Claude Code 运行时
│
│ HTTPS 调用
▼
api.anthropic.com
协议层：
AionUi ←── JSON-RPC (NDJSON) ──→ ACP Bridge
ACP Bridge ←── streaming NDJSON ──→ cli.js
cli.js ←── HTTPS ──→ Anthropic API
关键发现：ACP Bridge 不从系统 PATH 找 claude 命令，它使用 SDK npm 包内嵌的 cli.js（版本锁定，~13MB 自包含运行时），所以即使你没有单独安装 Claude Code，也能使用 Claude 能力。
AcpDetector：如何自动发现所有 Agent
AionUi 启动时，AcpDetector 单例会并行从三个来源检测可用 Agent：
initialize()
│
├── detectBuiltinAgents() ← 扫描系统 PATH（which/where 命令，1秒超时）
├── detectExtensionAgents() ← 从已安装扩展获取 ACP Adapter
└── detectCustomAgents() ← 从用户配置文件读取
│
▼ 合并顺序：Aionrs > Gemini > Builtin > Other > Remote > Extension
│
└── 输出统一 agent 列表供 UI 和 IPC Bridge 使用
PATH 增强策略：AionUi 不止看系统 PATH，还会主动扫描 ~/.bun/bin、~/.cargo/bin、~/.volta/bin、nvm 目录、Homebrew 路径等，确保从 Finder 启动也能找到 CLI 工具。
src 目录完整结构
src/
├── index.ts # Main 进程入口
├── server.ts # 纯 Node.js 服务器入口（无 Electron）
├── types.d.ts # 全局类型声明
├── common/ # 跨进程共享（类型、工具、常量）
├── preload/ # contextBridge 安全桥接脚本
│
├── process/ # Main 进程业务逻辑
│ ├── acp/ # ★ ACP 协议层（新版 V2，feature flag 控制）
│ ├── agent/ # ★ AI 后端连接（AcpDetector、AcpConnection 等）
│ ├── bridge/ # IPC 处理器（cronBridge、fsBridge 等）
│ ├── channels/ # 消息通道（Telegram/微信/钉钉/飞书/WeCom）
│ ├── extensions/ # 扩展系统（Hub 市场、加载器、注册表）
│ ├── pet/ # 桌面宠物（AI 状态可视化）
│ ├── resources/ # 资源管理（助手、技能、提示词）
│ ├── services/ # 核心服务（数据库、Cron、MCP）
│ ├── task/ # 任务生命周期管理
│ ├── team/ # ★ 多 Agent 团队协作
│ ├── utils/ # 工具函数（shellEnv、进程管理）
│ ├── webserver/ # Express + WebSocket WebUI 服务
│ └── worker/ # 后台 Worker 进程（fork 模式）
│
└── renderer/ # 渲染进程（React UI）
├── components/ # 共享 UI 组件
│ ├── base/ # 基础 UI 原语（无业务逻辑）
│ ├── chat/ # 对话/消息组件
│ ├── agent/ # Agent 选择配置组件
│ └── ...
├── hooks/ # React Hooks
│ ├── agent/、chat/、file/ # 按业务域分组
│ ├── mcp/、ui/、system/
├── pages/ # 页面模块
│ ├── conversation/ # 对话页（含 ACP/Gemini 等各平台）
│ └── settings/ # 设置页
├── services/ # 客户端服务 + i18n
├── utils/ # 工具函数
├── pet/ # 桌面宠物 UI
└── main.tsx # React 挂载 + PWA 支持
数据流：一条消息的完整旅程
用户在 SendBox 输入消息
│
▼
[Renderer] 检查命令队列 → 若 AI 在忙则入队 sessionStorage
│ AI 空闲时
▼
ipcBridge.conversation.sendMessage()
│ IPC / WebSocket
▼
[Main] AcpAgentManager.sendMessage()
│
▼
AcpConnection.sendPrompt() ──── JSON-RPC → 子进程 stdin
│
▼
子进程 stdout NDJSON 流 ──── handleMessage()
│
▼
AcpAdapter.convertSessionUpdate() // 转成 TMessage 格式
│
▼
addOrUpdateMessage() // 写入 SQLite
│
▼
ipcBridge.acpConversation.responseStream.emit()
│ IPC / WebSocket
▼
[Renderer] 实时流式渲染到聊天界面
第六章：扩展开发（高级开发者）
AionUi 有一套完整的插件扩展系统，可以贡献主题、技能、助手、新 Agent 后端等。
扩展清单结构
每个扩展都有一个 aion-extension.json 描述文件，类似 VS Code 插件的 package.json：
{
"$schema": "../../schemas/aion-extension-v1.json",
"name": "my-extension",
"displayName": "我的扩展",
"version": "1.0.0",
"engine": { "aionui": "^1.0.0" },
"lifecycle": {
"onActivate": "scripts/activate.js",
"onDeactivate": "scripts/deactivate.js"
},
"permissions": {
"storage": true,
"network": false,
"shell": false,
"filesystem": "extension-only",
"events": true
},
"contributes": {
"acpAdapters": "$file:contributes/acp-adapters.json",
"mcpServers": "$file:contributes/mcp-servers.json",
"assistants": "$file:contributes/assistants.json",
"skills": "$file:contributes/skills.json",
"themes": "$file:contributes/themes.json",
"settingsTabs":"$file:contributes/settings-tabs.json"
}
}
一个扩展可以贡献的内容：
| 贡献点 | 作用 |
|---|---|
acpAdapters | 注册新的 AI CLI 后端 |
mcpServers | 提供新的 MCP 工具 |
assistants | 新的内置助手角色 |
skills | 新的 AI 技能（pptx/docx/自定义） |
themes | UI 主题 |
settingsTabs | 设置页新标签 |
三层技能系统
技能来源
├── Builtin Skills（内置）
│ └── pptx, docx, pdf, xlsx, mermaid, ...（随应用发布）
│
├── Custom Skills（用户自定义）
│ └── 在 skills/ 目录创建 .md 文件定义
│ 每个对话可独立开启/关闭
│
└── Extension Skills（扩展贡献）
└── 通过 Extension SDK 注册，自动出现在技能列表
实用示例：开发一个自定义技能
在项目的 skills/ 目录下创建 my-weekly-report.md：
# 周报生成技能
## 触发条件
当用户要求写周报时激活此技能。
## 输出格式
- 本周完成事项（3-5条）
- 遇到的问题与解决方案
- 下周计划
- 工作饱和度评估
## 风格要求
简洁专业，使用第一人称，避免空话套话。
每项不超过两行。
在对话界面的 Skill 指示器中启用它，之后这个对话里的 AI 就会按照这个模板生成周报。
第七章：开发环境搭建（贡献者）
环境准备
# 前置依赖
Node.js >= 22
Python >= 3.11（用于 native 模块编译）
Bun（包管理器）
# 安装 Bun
curl -fsSL https://bun.sh/install | bash
# 安装 PR 检查工具
npm install -g @j178/prek
# 克隆仓库
git clone https://github.com/iOfficeAI/AionUi.git
cd AionUi
# 安装依赖
bun install
# 启动开发模式
bun start
常用开发命令速查
# ─── 开发 ───
bun start # 启动 Electron 桌面模式
bun run webui # 启动无窗口 WebUI 模式
bun run start:multi # 启动第二个实例（双仓库开发用）
# ─── 代码质量 ───
bun run format # 格式化代码（oxfmt，比 Prettier 快 30 倍）
bun run lint # Lint 检查（oxlint，比 ESLint 快 50-100 倍）
bun run lint:fix # 自动修复 Lint 问题
bunx tsc --noEmit # TypeScript 类型检查
# ─── 测试 ───
bunx vitest run # 运行单元测试
bun run test:e2e # E2E 测试（Playwright）
bun run test:coverage # 覆盖率报告
# ─── 构建 ───
bun run dist:mac # 打包 macOS
bun run dist:win # 打包 Windows
bun run dist:linux # 打包 Linux
# ─── 提交前一键检查（等同于 CI）───
prek run --from-ref origin/main --to-ref HEAD
bunx vitest run
提交规范
格式：type(scope): description
type 类型：
feat 新功能
fix 修 Bug
docs 文档变更
refactor 重构（不影响功能）
test 测试相关
chore 构建/工具变动
示例：
feat(team): add per-agent confirmation dialog
fix(acp): guard agent_status emission to known session states
docs(contributing): replace examples with AionUi-specific scenarios
PR 规则：Atomic PR（一个 PR 只做一件事）
这是这个项目最重要的工程规范。在提交 PR 前，问自己：这个 diff 能拆分成多个独立的 PR 吗？ 如果能，就必须拆。
❌ 错误示例（一个 PR 做多件事）：
- fix(chat): fix scroll position
- feat(sentry): add user tracking
- perf(preview): optimize office preview
= 这必须是 3 个独立 PR
✅ 正确示例（一个 PR 一件事）：
- feat(team): add per-agent confirmation, sidebar badge, and wiggle animation
（这三个是同一个功能的不可分割部分，属于一个 PR）
PR 自动化流程
提交 PR 后，仓库的 Bot 会自动处理：
你提交 PR
│
▼
Bot 开始审查（标签: bot:reviewing）
│
┌──┴──┐
│ │
CI 通过 CI 失败
│ │
│ ▼
│ bot:ci-waiting（等你修复）
│
▼
bot:ready-to-merge
│
▼
人工维护者合并
第八章：学习路线图
根据你的角色选择不同路径：
┌─────────────────────────┐
│ 你是什么角色？ │
└────────┬────────────────┘
│
┌────────────────┼─────────────────┐
▼ ▼ ▼
普通用户 前端开发者 后端/架构开发者
│ │ │
第二章上手 第二章 + 第七章 第五章技术架构
│ 搭开发环境 重点读 ACP 部分
第三章进阶 第五章渲染层 深入 docs/tech/
│ renderer/ 目录 acp-detector.md
第四章 Team 组件/Hooks规范 architecture.md
│ docs/conventions/ queue-and-acp-state.md
享受 AI 协作！ 贡献 UI 功能 PR 贡献核心功能 PR
建议的代码阅读顺序（开发者）：
docs/tech/architecture.md— 整体架构（10分钟）src/index.ts+src/process/index.ts— Main 进程入口（了解启动流程）src/preload/— contextBridge 设计（理解 IPC 安全隔离）src/process/agent/acp/AcpConnection.ts— ACP 状态机核心（重点）docs/tech/acp-detector.md— Claude 连接的完整链路分析src/process/team/— Team Mode 实现（了解多 Agent 协调）examples/hello-world-extension/— 扩展开发参考
附录：快速参考卡
支持的 AI 平台（20+）
官方平台：Gemini / Claude (Anthropic) / OpenAI
云服务商：AWS Bedrock / OpenRouter / New API
国内平台：通义千问(Dashscope) / 智谱AI / Moonshot(Kimi)
百川(Qianfan) / 混元(Tencent) / 零一万物
ModelScope / StepFun / 字节(Ark)
海外平台：DeepSeek / MiniMax / xAI / SiliconFlow
本地模型：Ollama / LM Studio（自定义 API 端点）
数据安全说明
- 所有对话数据存储在本地 SQLite 数据库
- 没有任何数据上传到 AionUi 服务器
- 数据库位置：macOS
~/Library/Application Support/AionUi/
常见问题速查
| 问题 | 解决方案 |
|---|---|
| AI 没有检测到已安装的 Claude Code | 检查 claude 是否在 PATH 里，或在 Settings → ACP → 手动指定 CLI 路径 |
| WebUI 远程无法访问 | 检查防火墙是否放行 25808 端口；云服务器检查安全组规则 |
| WebUI 忘记密码 | aionui --resetpass（会生成新随机密码并打印到终端，所有旧 Token 失效） |
| 端口 25808 被占用 | kill $(lsof -t -i:25808) 后重启；或用环境变量 AIONUI_PORT=8081 换端口 |
| 服务器部署找不到显示器 | 需安装 Xvfb：apt install xvfb，启动加 xvfb-run 前缀 |
| Claude 连接失败提示 npx 错误 | AionUi 会自动尝试清除 npm 缓存后重试；手动清除可运行 npm cache clean --force |
| 定时任务没有触发 | 检查电脑是否休眠；AionUi 有 Keep-awake 机制，但需要程序处于运行状态 |
| 提交 PR 后 CI 失败 | 本地跑 prek run --from-ref origin/main --to-ref HEAD + bunx vitest run 排查 |
项目目录速查手册
仓库根目录
│
├── src/ ← 所有源代码
│ ├── renderer/ ← React UI（不能用 Node.js API）
│ ├── process/ ← Main 进程业务（不能用 DOM API）
│ ├── common/ ← 跨进程共享代码
│ └── preload/ ← IPC 安全桥接
│
├── docs/ ← 技术文档中心
│ ├── tech/ ← 架构图、ACP状态机、性能分析
│ ├── feature/ ← 功能设计文档（ACP重构、扩展市场等）
│ ├── design/ ← UX/交互设计文档
│ ├── conventions/ ← 代码规范（目录命名、PR自动化）
│ ├── superpowers/ ← 高级功能规格说明
│ ├── development.md ← 开发环境搭建（★ 新人必读）
│ ├── WEBUI_GUIDE.md ← WebUI 完整配置指南
│ ├── SERVER_DEPLOY_GUIDE.md ← Linux 服务器部署指南
│ └── CODE_STYLE.md ← 代码风格规范
│
├── examples/ ← 扩展开发示例
│ ├── hello-world-extension/ ← 完整扩展示例（推荐参考）
│ ├── acp-adapter-extension/ ← 自定义 Agent 后端示例
│ ├── ext-feishu/ ← 飞书 Bot 扩展示例
│ └── ext-wecom-bot/ ← 企业微信 Bot 示例
│
├── tests/ ← 测试文件（镜像 src/ 结构）
├── .aionui/ ← 内部功能开发文档
├── CONTRIBUTING.md ← 贡献指南（★ 提 PR 前必读）
├── CONTRIBUTING.zh.md ← 贡献指南中文版
├── CLAUDE.md ← Claude Code 开发规范
├── AGENTS.md ← Codex 开发规范
└── Dockerfile ← 容器化部署
技术选型一览（为什么这样选）
| 技术 | 为什么选它 |
|---|---|
| Electron | 跨平台桌面 + 内置 Node.js，文件系统操作无需额外权限 |
| React 19 | 最新并发特性，流式 AI 响应渲染性能好 |
| Bun | 比 npm/yarn 快 25 倍的包管理，内置 SQLite 驱动，运行时比 Node 快 |
| electron-vite | HMR 热更新极快，开发体验接近普通 Web 项目 |
| UnoCSS | 原子化 CSS，按需生成，打包体积小，支持自定义语义 token |
| better-sqlite3 | 同步 API，不需要 async/await，代码简洁；本地数据无需网络 |
| oxlint + oxfmt | Rust 实现，比 ESLint 快 50-100 倍、比 Prettier 快 30 倍，CI 不再是瓶颈 |
| Vitest + Playwright | 统一的单测 + E2E 工具链，与 Vite 生态深度集成 |
| croner | 比 node-cron 更精准的时区支持，防并发执行的 BusyGuard |
写在最后
AionUi 是一个野心勃勃却脚踏实地的项目。它的代码量已经很大（4782 次提交、持续活跃），但工程质量相当高：严格的 Atomic PR 规范、完善的 CI 自动化、详尽的技术文档（包括 ACP 状态机分析、Claude 三层子进程链路追踪这种深度文档），这些都是一个严肃工程团队的标志。
对普通用户来说，AionUi 是目前最接近"把 AI 变成真正助手"的免费开源工具，特别是 Team Mode + 定时任务的组合，能做到很多付费工具都做不到的事。
对开发者来说，这是一个学习 Electron 架构、AI Agent 通信协议、多进程协调的绝佳真实项目。ACP 协议的设计、三层子进程嵌套的 Claude 连接链路、统一桥接 IPC 和 WebSocket 的 Bridge 模式，都是值得研究的工程实践。
对贡献者来说，项目有活跃的中英文社区（Discord + 微信群），maintainer 响应快，Bot 自动化做得很好，是参与开源贡献体验较好的项目之一。
📌 本文参考资料（均来自仓库官方文档）
docs/tech/architecture.md— 架构总览docs/tech/acp-detector.md— ACP 检测与 Claude 连接完整链路docs/tech/queue-and-acp-state.md— 命令队列与 ACP 状态机docs/design/agent-team-guide-flow.md— Team Mode 设计流程docs/development.md— 开发环境指南docs/WEBUI_GUIDE.md— WebUI 配置指南docs/SERVER_DEPLOY_GUIDE.md— 服务器部署指南docs/conventions/file-structure.md— 文件结构规范CONTRIBUTING.md— 贡献指南examples/hello-world-extension/— 扩展开发示例readme.md— 项目主文档
