通用 ACP 协议#

AionUi 定义了一套 Agent CLI Protocol (ACP)，作为统一的抽象层：

// 简化示例
interface AgentAdapter {
  initialize(): Promise<void>;
  sendMessage(message: string): AsyncIterator<StreamChunk>;
  abort(): void;
  getConfig(): AgentConfig;
}

内置 Gemini CLI 实现#

项目最大的亮点是内置了完整的 Gemini CLI 实现，这意味着：

• 用户无需单独安装 Google 官方 CLI 工具
• 应用启动即可直接使用 Gemini 模型
• 减少了环境配置的复杂度

技术实现上，src/agent/gemini/ 目录实现了：

• Gemini API 客户端封装
• 流式响应处理
• 上下文记忆管理
• 图像生成和识别功能

动态适配器加载#

应用启动时会自动检测本地已安装的 AI CLI 工具：

// 伪代码示例
async function detectAvailableAgents() {
  const agents = [];

  // 内置 Gemini 始终可用
  agents.push({ name: 'gemini', type: 'builtin' });

  // 检测 Claude Code
  if (await commandExists('codex')) {
    agents.push({ name: 'codex', type: 'external' });
  }

  // 检测 Ollama
  if (await commandExists('ollama')) {
    agents.push({ name: 'ollama', type: 'local' });
  }

  return agents;
}

技术架构#

workspace/
├── index.tsx                    # 容器组件 (550 行)
├── hooks/                       # 业务逻辑 Hooks
│   ├── useWorkspaceTree.ts     # 树结构管理
│   ├── useFileOperations.ts    # 文件操作
│   ├── useDragAndDrop.ts       # 拖拽功能
│   ├── useFilePreview.ts       # 预览逻辑
│   └── useAIIntegration.ts     # AI 驱动功能
├── utils/
│   ├── treeOperations.ts       # 树算法 (搜索、遍历、过滤)
│   └── fileUtils.ts            # 文件工具函数
└── types.ts                     # TypeScript 类型定义

这种容器组件 + Hooks + 工具函数的三层架构是 React 最佳实践的典范：

1. 容器组件：只负责组装 UI 和协调子组件
2. Hooks：封装可复用的业务逻辑（有状态）
3. 工具函数：纯函数，无副作用，易于测试

核心功能#

虚拟文件树：

• 支持大规模文件目录（10000+ 文件）
• 懒加载和虚拟滚动优化性能
• 实时搜索和过滤

拖拽操作：

// 使用 HTML5 Drag & Drop API
function useDragAndDrop() {
  const handleDrop = async (e: DragEvent) => {
    e.preventDefault();
    const files = Array.from(e.dataTransfer.files);

    // 批量导入文件
    await importFiles(files);

    // 通知 AI 有新文件加入
    await notifyAI({ type: 'files_added', files });
  };

  return { handleDrop };
}

AI 驱动的文件组织：

• 自动分类和标签
• 智能文件合并和拆分
• 代码重构建议

支持的格式#

实时编辑和同步#

Markdown 和代码文件支持实时编辑，技术实现：

function useRealtimePreview(filePath: string) {
  const [content, setContent] = useState('');

  // 监听文件变化
  useEffect(() => {
    const watcher = fs.watch(filePath, async () => {
      const newContent = await fs.readFile(filePath, 'utf-8');
      setContent(newContent);
    });

    return () => watcher.close();
  }, [filePath]);

  // 防抖保存
  const debouncedSave = useMemo(
    () => debounce(async (newContent: string) => {
      await fs.writeFile(filePath, newContent);
    }, 500),
    [filePath]
  );

  return { content, setContent: debouncedSave };
}

为什么选择 better-sqlite3？#

相比其他数据库方案的优势：

数据库结构#

-- 会话表
CREATE TABLE conversations (
  id TEXT PRIMARY KEY,
  title TEXT,
  agent_type TEXT,  -- 'gemini' | 'codex' | 'ollama'...
  workspace_id TEXT,
  created_at INTEGER,
  updated_at INTEGER
);

-- 消息表
CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  conversation_id TEXT,
  role TEXT,  -- 'user' | 'assistant' | 'system'
  content TEXT,
  metadata JSON,  -- 存储附加信息（图片、文件等）
  created_at INTEGER,
  FOREIGN KEY (conversation_id) REFERENCES conversations(id)
);

-- 工作空间表
CREATE TABLE workspaces (
  id TEXT PRIMARY KEY,
  name TEXT,
  root_path TEXT,
  file_tree JSON,  -- 缓存文件树结构
  created_at INTEGER
);

-- 全文搜索索引
CREATE VIRTUAL TABLE messages_fts USING fts5(
  content,
  content=messages,
  content_rowid=id
);

WAL 模式性能优化#

AionUi 启用了 SQLite 的 WAL (Write-Ahead Logging) 模式：

const db = new Database('aionui.db');
db.pragma('journal_mode = WAL');  // 启用 WAL 模式
db.pragma('synchronous = NORMAL'); // 平衡性能和安全性

WAL 模式的优势：

• 并发性能提升：读操作不阻塞写操作
• 崩溃恢复：更好的数据完整性保证
• 写入性能：减少磁盘 I/O 操作

启动 WebUI 模式#

# 本地访问（仅限 127.0.0.1）
aionui --webui

# 局域网访问（允许其他设备连接）
aionui --webui --remote

技术实现#

WebUI 模式基于 Express + WebSocket 实现：

// 简化示例
import express from 'express';
import { WebSocketServer } from 'ws';

const app = express();
const wss = new WebSocketServer({ noServer: true });

// 静态资源服务（React 构建产物）
app.use(express.static('dist/renderer'));

// API 路由
app.use('/api/conversations', conversationRouter);
app.use('/api/messages', messageRouter);

// WebSocket 升级
server.on('upgrade', (request, socket, head) => {
  authenticate(request, (err, client) => {
    if (err) return socket.destroy();

    wss.handleUpgrade(request, socket, head, (ws) => {
      wss.emit('connection', ws, request, client);
    });
  });
});

JWT 认证系统#

WebUI 模式使用 JWT Token 进行身份验证：

// 登录接口
app.post('/api/auth/login', async (req, res) => {
  const { username, password } = req.body;

  // 验证用户名密码（存储在 SQLite）
  const user = await db.prepare(
    'SELECT * FROM users WHERE username = ?'
  ).get(username);

  if (!user || !bcrypt.compareSync(password, user.password_hash)) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // 生成 JWT Token
  const token = jwt.sign(
    { userId: user.id, username: user.username },
    process.env.JWT_SECRET,
    { expiresIn: '7d' }
  );

  res.json({ token });
});

// 认证中间件
function authenticateToken(req, res, next) {
  const token = req.headers['authorization']?.split(' ')[1];

  if (!token) return res.sendStatus(401);

  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
    if (err) return res.sendStatus(403);
    req.user = user;
    next();
  });
}

移动设备支持#

WebUI 模式特别优化了移动端体验：

• 响应式布局：基于 Arco Design 的移动端适配
• 触摸优化：支持滑动、长按等手势
• PWA 支持：可以安装到手机主屏幕
• Termux 支持：可以在 Android Termux 环境运行

MCP 架构#

┌──────────────┐
│  AI Model    │
└──────┬───────┘
       │ MCP Protocol
┌──────▼───────┐
│ MCP Server   │  ← AionUi 作为 MCP 客户端
├──────────────┤
│ • File Tool  │
│ • Web Tool   │
│ • API Tool   │
└──────────────┘

工具调用示例#

// MCP 工具定义
const fileReadTool = {
  name: 'read_file',
  description: 'Read content from a file',
  parameters: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'File path' }
    },
    required: ['path']
  },
  handler: async ({ path }) => {
    return await fs.readFile(path, 'utf-8');
  }
};

// AI 模型调用工具
const response = await model.sendMessage('Read the README.md file');
// AI 返回：需要调用 read_file 工具
const result = await mcpClient.callTool('read_file', {
  path: './README.md'
});

ESLint 规则#

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended"
  ],
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/no-floating-promises": "error",
    "react-hooks/exhaustive-deps": "warn"
  }
}

Git Hooks (Husky + lint-staged)#

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "git add"
    ]
  }
}

这确保了每次提交的代码都经过：

1. ESLint 检查：修复常见错误
2. Prettier 格式化：统一代码风格
3. TypeScript 类型检查：避免类型错误

虚拟列表渲染#

对于大量消息历史，使用虚拟滚动（react-window）：

import { FixedSizeList } from 'react-window';

function MessageList({ messages }) {
  const Row = ({ index, style }) => (
    <div style={style}>
      <MessageItem message={messages[index]} />
    </div>
  );

  return (
    <FixedSizeList
      height={600}
      itemCount={messages.length}
      itemSize={80}
      width="100%"
    >
      {Row}
    </FixedSizeList>
  );
}

性能提升：

• 渲染时间：从 1000ms 降至 50ms（1000 条消息）
• 内存占用：减少 80%

React.memo 和 useMemo#

// 避免不必要的重新渲染
const MessageItem = React.memo(({ message }) => {
  return <div>{message.content}</div>;
}, (prevProps, nextProps) => {
  return prevProps.message.id === nextProps.message.id;
});

// 缓存昂贵计算
function ConversationView({ messages }) {
  const stats = useMemo(() => {
    return calculateMessageStats(messages);
  }, [messages]);

  return <div>Total tokens: {stats.tokens}</div>;
}

索引优化#

-- 为常用查询字段创建索引
CREATE INDEX idx_messages_conversation_id
  ON messages(conversation_id);

CREATE INDEX idx_conversations_updated_at
  ON conversations(updated_at DESC);

-- 组合索引
CREATE INDEX idx_messages_conversation_created
  ON messages(conversation_id, created_at);

查询优化#

使用预编译语句（Prepared Statements）：

// ❌ 不好：每次都重新解析 SQL
function getMessages(conversationId: string) {
  return db.prepare(`
    SELECT * FROM messages
    WHERE conversation_id = '${conversationId}'
  `).all();
}

// ✅ 好：预编译 + 参数绑定
const getMessagesStmt = db.prepare(`
  SELECT * FROM messages
  WHERE conversation_id = ?
  ORDER BY created_at
`);

function getMessages(conversationId: string) {
  return getMessagesStmt.all(conversationId);
}

性能提升：3-5 倍查询速度

主进程优化#

• 异步化：主进程中耗时操作使用异步 API
• 进程间通信优化：减少 IPC 调用次数，批量传输数据
• 内存管理：及时释放不用的资源

// ❌ 不好：频繁 IPC 调用
for (const file of files) {
  await ipcRenderer.invoke('read-file', file.path);
}

// ✅ 好：批量读取
const contents = await ipcRenderer.invoke('read-files',
  files.map(f => f.path)
);

渲染进程优化#

• 代码分割：使用动态 import 按需加载
• 懒加载路由：React Router 的 lazy 组件

import { lazy, Suspense } from 'react';

const ConversationPage = lazy(() =>
  import('./pages/conversation')
);

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/conversation" element={<ConversationPage />} />
      </Routes>
    </Suspense>
  );
}