# 灵犀 AI Agent：从零构建本地优先的桌面 AI 工作台 —— 架构设计与项目全景

> **灵犀 AI Agent** 是一个开源的本地优先桌面 AI Agent 工作台，采用 Electron + React + Go 三层架构，支持多模型多供应商接入、智能体工厂、技能管理、知识库 RAG、MCP 工具、Agent 间对话协作等能力。本文将深入剖析项目的整体架构设计、技术选型背后的决策逻辑，以及如何在一个桌面应用中实现完整的 AI Agent 生态。
>
> GitHub 地址：[https://github.com/OdysseyFather/lingxi](https://github.com/OdysseyFather/lingxi)

---

## 一、为什么要做灵犀？

在 AI 爆发式增长的 2024-2026 年，我们看到了一个有趣的现象：市面上的 AI 工具层出不穷，但大多数产品都走向了两个极端——

**极端一：轻量级 Chat 应用。** 包装一个聊天界面，调用一个模型 API，这类产品上手极快，但能力上限极低。你不能创建专属的智能体，不能给 AI 装备工具，不能让多个 AI 协作完成复杂任务。

**极端二：重量级企业平台。** Dify、Coze 等产品功能强大，但部署复杂（需要 Docker、数据库、后端服务），数据需要上传到云端，对个人用户和小团队来说，门槛过高。

灵犀要做的，是在这两个极端之间找到一个甜蜜点：

- **本地优先**：所有数据（会话、配置、密钥、知识库）保存在本地 SQLite，零云端依赖
- **开箱即用**：macOS 双击即可运行，无需 Python、Docker 或任何后端服务
- **能力完整**：智能体工厂、技能系统、知识库 RAG、MCP 工具、IM 集成、Agent 间对话——一个都不少
- **多模型自由**：14+ 供应商一键切换，不被任何单一供应商锁定

<!-- 截图占位：灵犀首页工作台全景 -->
![灵犀工作台首页](images/首页截图.png)

---

## 二、三层架构：Electron + React + Go

灵犀的架构设计遵循一个核心原则：**每一层做自己最擅长的事**。

```
┌─────────────────────────────────────────────────┐
│                  Electron 36                     │
│  桌面容器 · 窗口管理 · 安全存储 · 系统集成        │
│  ┌─────────────┐  ┌───────────────────────────┐ │
│  │  preload.js  │  │        main.js            │ │
│  │  IPC Bridge  │  │  子进程管理 · safeStorage  │ │
│  └──────┬───────┘  │  截屏 · 更新 · 快捷键     │ │
│         │          └───────────────────────────┘ │
├─────────┼───────────────────────────────────────┤
│         ▼                                        │
│  ┌─────────────────────────────────────────┐    │
│  │           React 19 + Vite 8              │    │
│  │  Tailwind CSS 3.4 · Zustand 5           │    │
│  │  Framer Motion 12 · 虚拟滚动             │    │
│  │  6 套主题 · 丝滑动画 · 原子组件体系      │    │
│  └──────────────┬──────────────────────────┘    │
│                 │ HTTP / WebSocket               │
├─────────────────┼───────────────────────────────┤
│                 ▼                                │
│  ┌─────────────────────────────────────────┐    │
│  │            Go 1.24 + Gin                 │    │
│  │  SQLite · AI 引擎路由 · 流式 WebSocket   │    │
│  │  定时调度 · mDNS 发现 · IM 连接器        │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘
```

### 2.1 为什么选 Go 做后端？

这是一个经常被问到的问题：为什么不用 Node.js 统一前后端？为什么不用 Python？

**Go 的优势恰好命中了灵犀的核心需求：**

1. **单二进制部署**。`go build` 产出一个无依赖的二进制文件，不需要安装运行时。Electron 启动时 `spawn` 这个二进制即可，极大简化了打包流程。

2. **并发模型天然适合 AI 场景**。灵犀的后端需要同时处理：流式 WebSocket 推送、多个 AI 引擎的并发调用、mDNS 局域网扫描、定时任务调度、IM 消息路由——Go 的 goroutine 模型处理这些场景得心应手。

3. **纯 Go SQLite**。使用 `ncruces/go-sqlite3`（WASM 实现），完全不需要 CGO，交叉编译毫无障碍。这意味着在 macOS 上可以直接编译出 Windows 版本。

4. **启动速度快**。Go 编译出的二进制启动时间通常在几十毫秒级别，用户从双击应用到看到界面的等待时间极短。

```go
// 后端 main.go 入口极简——路由注册清晰，无框架魔法
func main() {
    cfg := config.Get()
    db.Init()
    go handler.BootstrapInstalledSkills()

    gin.SetMode(gin.ReleaseMode)
    r := gin.Default()

    // 70+ 个 API 端点，覆盖完整的 Agent 生态
    api := r.Group("/api")
    api.GET("/sessions", handler.ListSessions)
    api.POST("/chat", handler.Chat)
    // ... 更多路由
}
```

### 2.2 前端技术选型的思考

前端选择 **React 19 + Vite 8 + Tailwind CSS 3.4** 这套组合，每个选择都有明确的理由：

| 技术 | 选择理由 |
|------|----------|
| **React 19** | 生态最完善，社区最大，Electron 场景下的兼容性经过充分验证 |
| **Vite 8** | 开发体验极佳，HMR 毫秒级热更新，构建速度远超 Webpack |
| **Tailwind CSS 3.4** | 原子化 CSS 与主题系统完美配合，6 套主题仅靠 CSS 变量切换 |
| **Zustand 5** | 轻量（<1KB gzipped），API 极简，天然支持 React 19 |
| **Framer Motion 12** | 页面切换、列表动画一站式解决，AnimatePresence 处理退场动画 |
| **@tanstack/react-virtual 3** | 100+ 条消息时自动启用虚拟滚动，保持 60fps 流畅 |

**一个关键的设计决策是：不使用任何 UI 框架（如 Ant Design、Material UI），而是自建原子组件体系。**

```jsx
// primitives.jsx 中定义了所有原子组件
// Button、Input、Textarea、Select、Badge、Card、Modal、ToastStack、Tooltip
// 所有页面组件只使用这些原子组件，确保视觉一致性

// 样式完全通过 CSS 变量控制，主题切换只需改变变量值
<div className="bg-[color:var(--bg)] text-[color:var(--text)]">
  <Card className="bg-[color:var(--bg-elev)]">
    <Button className="bg-[color:var(--accent)]">操作</Button>
  </Card>
</div>
```

这样做的好处是：
1. **包体积极小**——不引入任何 UI 库的 CSS 和 JS
2. **主题切换零闪烁**——所有样式都基于 CSS 变量，切换主题只需改变 `data-theme` 属性
3. **设计一致性强**——所有组件的视觉语言完全统一

### 2.3 Electron：不仅是浏览器壳

很多人对 Electron 有偏见，认为它就是一个"网页套壳"。但在灵犀的架构中，Electron 层承担了大量关键职责：

**安全存储（safeStorage）**：API 密钥使用操作系统级加密存储，而不是明文保存在配置文件中。Electron 的 `safeStorage` 在 macOS 上对接 Keychain，在 Windows 上对接 DPAPI。

```javascript
// 密钥加密存储的实现
function encryptSecretBase64(plain) {
    if (!safeStorage.isEncryptionAvailable()) {
        // 降级为 Base64 混淆（保证可用）
        return 'b64:' + Buffer.from(plain, 'utf8').toString('base64');
    }
    // 使用操作系统级加密
    return 'sf:' + safeStorage.encryptString(plain).toString('base64');
}
```

**子进程生命周期管理**：Go 后端作为 Electron 的子进程运行，Electron 负责启动、监控和优雅退出。

**冷启动优化**：灵犀实现了 Splash 页面策略——Electron 窗口立即显示 Splash 动画，后端 Go 进程在后台启动，就绪后无缝切换到主应用。用户感知的启动时间通常不超过 2 秒。

```javascript
// 冷启动优化流程
app.whenReady().then(async () => {
    createWindow();        // 立即显示 Splash
    startBackend();        // 后台启动 Go
    await waitForBackend(); // 等待 /api/ping 返回 200
    switchToApp();         // 无缝切换到主应用
});
```

**自动更新**：内置 `electron-updater`，支持增量更新。启动后 10 秒自动检查，之后每 4 小时轮询。

---

## 三、数据架构：本地 SQLite 一统天下

灵犀的所有数据存储在一个 SQLite 文件中：`~/Library/Application Support/灵犀/smart-agent.db`。

### 3.1 核心数据表设计

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   sessions   │────▶│   messages   │     │   agents     │
│  会话        │     │  消息        │     │  智能体      │
│  id          │     │  id          │     │  id          │
│  title       │     │  session_id  │     │  name        │
│  agent_id    │     │  role        │     │  system_prompt│
│  pinned      │     │  content     │     │  temperature │
│  summary     │     │  usage       │     │  max_tokens  │
│  folder      │     │  feedback    │     │  post_actions│
└──────────────┘     │  pinned      │     └──────────────┘
                     └──────────────┘
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  memories    │     │ scheduled_   │     │ api_profiles │
│  长期记忆    │     │ tasks        │     │  接入点      │
│  agent_id    │     │  定时任务    │     │  provider    │
│  content     │     │  cron_expr   │     │  model       │
│  category    │     │  stateful    │     │  auth_token  │
└──────────────┘     └──────────────┘     └──────────────┘

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ nexus_peers  │     │nexus_contacts│     │ a2a_         │
│  局域网实例  │     │  建联记录    │     │conversations │
│  peer_id     │     │  shared_     │     │  A2A 对话    │
│  host:port   │     │  secret      │     │  topic/goal  │
│  agents_json │     │  status      │     │  max_rounds  │
└──────────────┘     └──────────────┘     └──────────────┘
```

### 3.2 为什么不用 PostgreSQL 或 MySQL？

对于一个桌面应用来说，SQLite 是唯一正确的选择：

1. **零运维**——不需要启动数据库服务，不需要配置连接字符串
2. **单文件**——整个数据库就是一个文件，备份只需复制这个文件
3. **性能足够**——个人使用场景下，SQLite 的读写性能绰绰有余
4. **无 CGO**——使用 `ncruces/go-sqlite3`（WASM 实现），交叉编译无障碍

### 3.3 文件系统布局

```
~/Library/Application Support/灵犀/
├── smart-agent.db          # SQLite 数据库
├── knowledge/              # 知识库文件
│   ├── docs/               # 文档类
│   ├── qa/                 # 问答类
│   └── data/               # 数据类
├── uploads/                # 用户上传的图片
├── ai-home/                # AI 引擎隔离 HOME
│   └── .claude/
│       ├── settings.json   # 引擎配置
│       ├── skills/         # 已安装技能
│       └── CLAUDE.md       # 系统提示
└── bridge-home/            # Bridge 路由层数据
```

注意 `ai-home/` 目录——这是一个关键的设计决策。灵犀的 AI 引擎（基于 Claude Code CLI）需要一个 HOME 目录来存放配置。为了**不污染用户真实的 `~/.claude/` 目录**，灵犀为引擎创建了完全隔离的 HOME 环境。

---

## 四、AI 引擎路由层：打通 14+ 供应商

灵犀支持的不是一个模型，而是 14+ 家供应商的模型。这背后有一个精巧的路由层设计。

### 4.1 双协议架构

```
用户选择的供应商
     │
     ▼
┌─────────────────────────┐
│   是 Anthropic 协议吗？  │
└───────┬────────┬────────┘
        │Yes     │No
        ▼        ▼
  ┌──────────┐  ┌──────────────────────┐
  │ 直接调用  │  │  Bridge 路由层       │
  │ Claude    │  │  (LiteLLM / llm-    │
  │ Code CLI  │  │   bridge)            │
  └──────────┘  │                      │
                │ OpenAI ←→ Anthropic  │
                │ 协议双向翻译          │
                └──────────────────────┘
```

当用户使用 Anthropic 官方 API 时，请求直接通过 Claude Code CLI 处理。当用户使用 OpenAI 兼容协议的供应商（如 DeepSeek、Qwen、Gemini 等）时，灵犀会在本地启动一个 Bridge 进程，实现协议的双向翻译。

Bridge 优先使用 LiteLLM（Python），因为它的工具调用协议兼容性更好。如果 Python 环境不可用，则回退到 Node.js 版本的 llm-bridge。

### 4.2 密钥安全机制

```
┌──────────────┐    加密     ┌──────────────┐
│  前端输入    │───────────▶│  SQLite 存储  │
│  API Key     │  Electron  │  密文         │
│              │  safeStorage              │
└──────────────┘             └──────┬───────┘
                                    │
                   ┌────────────────┼────────────────┐
                   │ Electron 启动时解密               │
                   │ 通过内存传递给 Go 后端            │
                   │ POST /api/runtime/active-secret  │
                   └──────────────────────────────────┘
```

密钥永远不会以明文形式写入任何文件。它在 Electron 层加密后存入数据库，运行时由 Electron 解密后通过内存（HTTP 接口）一次性传递给 Go 后端。即使有人拿到了数据库文件，也无法还原密钥。

---

## 五、实时通信：WebSocket 流式架构

灵犀的对话体验是完全流式的——用户发送消息后，可以实时看到 AI 的思考过程和逐字输出。这背后是一套精心设计的 WebSocket 事件系统。

### 5.1 事件流设计

```
Go 后端                        前端 Zustand Store
  │                                  │
  ├── agent_state (THINKING) ──────▶ isStreaming = true
  ├── thinking (token) ────────────▶ liveBlocks += thinking
  ├── text (token) ────────────────▶ liveBlocks += text
  ├── tool_start ──────────────────▶ liveBlocks += tool
  ├── tool_end ────────────────────▶ tool.done = true
  ├── message_usage ───────────────▶ 固化为 message
  └── done ────────────────────────▶ isStreaming = false
```

前端的 Zustand Store 维护两个关键数组：
- `messages[]`：已完成的历史消息
- `liveBlocks[]`：正在流式生成的内容块

每个内容块有三种类型：`text`（文本）、`thinking`（思考过程）、`tool`（工具调用）。前端根据类型渲染不同的 UI——思考过程可折叠，工具调用显示执行状态和耗时。

### 5.2 智能滚动

在流式输出场景下，滚动行为需要特别处理。灵犀实现了 **stick-to-bottom** 逻辑：

- 用户没有手动上滚时，新内容自动追加并滚动到底部
- 用户手动上滚查看历史消息时，不强制拉回底部
- 用户滚动回底部后，重新启用自动滚动

这个看似简单的功能，在实现上需要精确检测滚动位置和区分用户行为与程序行为。

---

## 六、构建与打包

灵犀的构建脚本 `build-desktop.sh` 实现了一键打包，整个过程分为 5 个步骤：

```bash
▶ [1/5] 编译 Go 后端         # GOOS=darwin GOARCH=arm64 go build
▶ [2/5] 构建前端              # npm run build (Vite 8)
▶ [3/5] 准备内置 AI 引擎      # 复制 Claude CLI + 创建包装脚本
▶ [3.5] 准备 Bridge 路由层    # llm-bridge 依赖安装
▶ [3.6] 准备 LiteLLM Bridge  # Python litellm 依赖
▶ [3.7] 准备 whisper.cpp     # 离线语音识别引擎 + 模型
▶ [4/5] 准备 Node.js 运行时   # 内嵌 Node.js（不依赖系统环境）
▶ [5/5] 打包 Electron App    # electron-builder 产出 .app / .dmg
```

最终产物包含：
- `灵犀.app`：可直接运行的 macOS 应用
- `灵犀-{version}-arm64.dmg`：安装包
- `灵犀-{version}-arm64-mac.zip` + `.blockmap` + `latest-mac.yml`：增量自动更新包

整个应用完全自包含——内嵌了 Go 后端、Node.js 运行时、AI 引擎、Bridge 路由层、whisper.cpp 语音识别引擎。用户不需要安装任何依赖。

---

## 七、项目文件结构总览

```
lingxi-agent/
├── backend-desktop/          # Go 后端（~15 个 handler，5000+ 行核心代码）
│   ├── main.go               # 入口 + 路由注册（70+ API 端点）
│   ├── db/                   # SQLite 数据层
│   ├── handler/              # HTTP Handler（对话、智能体、技能、知识库...）
│   ├── nexus/                # Agent 间对话引擎
│   ├── scheduler/            # 定时任务调度器
│   ├── connector/            # IM 连接器（企微/钉钉/飞书）
│   └── router/               # AI 引擎路由
│
├── frontend-desktop/         # React 前端（20+ 页面组件）
│   └── src/
│       ├── ui/               # 通用 UI（AppShell、primitives、侧边栏）
│       ├── chat/             # 对话模块（ChatView、Composer、Bubble）
│       ├── settings/         # 设置页（接入点、主题、记忆、Nexus 设置）
│       ├── nexus/            # Agent 间对话 UI（NexusPage、A2A 对话视图）
│       └── state/            # Zustand 全局状态
│
├── electron/                 # Electron 主进程
│   ├── main.js               # 窗口管理、子进程、安全存储、自动更新
│   ├── preload.js            # IPC Bridge
│   └── resources/            # 运行时资源（AI 引擎、Bridge、whisper）
│
└── build-desktop.sh          # 一键构建脚本
```

---

## 八、总结与展望

灵犀 AI Agent 的架构设计体现了几个核心理念：

1. **本地优先，隐私至上**——数据不出本机，密钥加密存储
2. **自包含，零配置**——一个应用包含一切，双击即用
3. **模块化，可扩展**——技能系统、MCP 工具、知识库都是可插拔的扩展点
4. **跨模型，不锁定**——14+ 供应商自由切换，Bridge 层抹平协议差异

在后续的文章中，我们将深入每个功能模块，详细解析：

- **智能体工厂**：如何设计一个灵活的智能体创建系统
- **Project Nexus**：如何实现局域网内多 Agent 自动发现和双向流式对话
- **对话体验**：多模态输入、RAG 引用可视化、规划模式的实现细节
- **技能与知识库**：AI 生成技能、Smithery 市场集成、知识库 RAG 的完整链路

---

> **灵犀** —— 让 AI 成为你的工作伙伴，而不只是聊天对象。
>
> GitHub：[https://github.com/OdysseyFather/lingxi](https://github.com/OdysseyFather/lingxi)
>
> 如果觉得项目有价值，欢迎 Star 支持！
