# 小白龙架构文档

## 系统架构概览

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户界面层 (UI Layer)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  聊天界面    │  │  记忆图谱    │  │  系统监控   │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  语音面板    │  │  流程可视化  │  │  Jarvis控制 │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      前端逻辑层 (Frontend)                       │
│                     src/ui/brain-ui/app.js                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │ Chat Module │  │JarvisBridge │  │VisionAssist │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │UserProfile  │  │SystemMonitor│  │ScriptGen    │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      后端服务层 (Backend)                        │
│                       src/index.js                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  LLM 服务   │  │  记忆系统    │  │  任务队列   │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  语音处理   │  │  社交集成    │  │  能力执行   │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Jarvis Bridge (外部服务)                      │
│                    jarvis-bridge/server.js                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  Puppeteer  │  │  SystemInfo │  │  PowerShell │              │
│  │  浏览器控制  │  │  系统监控   │  │  脚本执行   │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│  ┌─────────────┐  ┌─────────────┐                                │
│  │  Screenshot │  │  Tesseract  │                                │
│  │  屏幕截图   │  │  OCR识别    │                                │
│  └─────────────┘  └─────────────┘                                │
└─────────────────────────────────────────────────────────────────┘
```

## 核心模块说明

### 1. 记忆系统 (Memory System)

**位置**: `src/memory/`

| 文件 | 功能 |
|------|------|
| `recognizer.js` | 记忆识别器，从对话中提取关键信息 |
| `injector.js` | 记忆注入器，将相关记忆注入到上下文中 |
| `focus.js` | 专注度管理，维护 Focus Stack |
| `consolidation-loop.js` | 记忆巩固循环，定期整理记忆 |
| `concept-extractor.js` | 概念提取，构建知识图谱 |

**数据流**:
```
对话输入 → 概念提取 → 记忆存储 → 记忆注入 → 上下文增强
```

### 2. 语音系统 (Voice System)

**位置**: `src/voice/`

| 文件 | 功能 |
|------|------|
| `manager.js` | 语音管理器，协调 ASR/TTS |
| `cloud-asr.js` | 云端语音识别 (Whisper) |
| `tts-providers.js` | TTS 提供商管理 |

### 3. 社交集成 (Social Integration)

**位置**: `src/social/`

| 文件 | 功能 |
|------|------|
| `dispatch.js` | 消息分发中心 |
| `wechat-clawbot.js` | 微信机器人集成 |
| `discord.js` | Discord 连接器 |

### 4. Jarvis Bridge 系统控制

**位置**: `jarvis-bridge/`

独立运行的 Node.js 服务，提供系统级控制能力：

- **浏览器自动化**: Puppeteer 控制 Chrome
- **系统监控**: systeminformation 获取硬件信息
- **屏幕视觉**: screenshot-desktop + Tesseract.js OCR
- **脚本执行**: node-powershell 执行 PowerShell
- **应用控制**: child_process 启动应用

**通信方式**:
```
前端 (app.js) ←──HTTP──→ Jarvis Bridge (port 18766) ←──→ 系统API
```

### 5. 前端架构

**位置**: `src/ui/brain-ui/`

| 文件 | 功能 |
|------|------|
| `app.js` | 主应用逻辑，包含所有 Jarvis 功能模块 |
| `app-shell.js` | UI 组件定义与模板 |
| `styles.css` | 样式表 |
| `chat.js` | 聊天功能 |
| `thought-stream.js` | 思维流显示 |

**Jarvis 功能模块** (在 app.js 中):

```javascript
// 系统控制桥接
JarvisBridge

// 视觉助手 (截图+OCR)
VisionAssistant

// 脚本生成器 (自然语言→PowerShell)
ScriptGenerator

// 系统监控
SystemMonitor

// 自然语言执行器
NaturalLanguageExecutor

// 用户画像
UserProfile

// 主动助手 (提醒)
ProactiveAssistant

// 信息聚合
InfoAggregator

// 工作流学习
WorkflowLearner
```

## 数据流架构

### 消息处理流程

```
用户输入
    │
    ▼
┌─────────────┐
│  消息队列    │
└─────────────┘
    │
    ▼
┌─────────────┐    ┌─────────────┐
│ 上下文收集   │───→│ 记忆注入    │
└─────────────┘    └─────────────┘
    │
    ▼
┌─────────────┐    ┌─────────────┐
│  LLM 调用   │←───│ 系统提示词  │
└─────────────┘    └─────────────┘
    │
    ▼
┌─────────────┐    ┌─────────────┐
│ 工具调用    │───→│ JarvisBridge│
└─────────────┘    └─────────────┘
    │
    ▼
┌─────────────┐
│  响应输出    │
└─────────────┘
```

### 记忆生命周期

```
提取 (Extract) → 存储 (Store) → 注入 (Inject) → 巩固 (Consolidate)
     │                │               │               │
     ▼                ▼               ▼               ▼
概念提取          SQLite          上下文增强       定期整理
关键词提取        向量存储        相关性排序       记忆压缩
```

## 技术选型

| 功能 | 技术 | 原因 |
|------|------|------|
| 桌面框架 | Electron | 跨平台，成熟的生态 |
| 数据库 | SQLite | 轻量，无需配置，适合本地存储 |
| 可视化 | D3.js | 强大的数据可视化能力 |
| 浏览器控制 | Puppeteer | Chrome DevTools Protocol |
| OCR | Tesseract.js | 开源，支持中文 |
| 系统信息 | systeminformation | 全面的系统信息获取 |
| 语音合成 | MiniMax/Edge TTS | 高质量中文语音 |
| 语音识别 | Whisper | 高准确率多语言支持 |

## 扩展点

### 添加新的工具能力

1. 在 `src/capabilities/` 创建新的执行器
2. 在 `src/capabilities/schemas.js` 定义参数 schema
3. 在 LLM 系统提示词中描述新能力

### 添加新的社交连接器

1. 在 `src/social/` 创建新的连接器文件
2. 在 `src/social/index.js` 注册连接器
3. 在 `src/social/dispatch.js` 添加分发逻辑

### 扩展 Jarvis Bridge

1. 在 `jarvis-bridge/server.js` 添加新的 API 端点
2. 在 `src/ui/brain-ui/app.js` 添加对应的 JarvisBridge 方法
3. 在自然语言执行器中添加命令映射

## 性能考虑

- **记忆查询**: 使用 SQLite FTS5 全文搜索加速
- **向量检索**: 使用本地嵌入模型，避免网络延迟
- **系统监控**: 5秒轮询，避免过度占用资源
- **浏览器实例**: 复用 Puppeteer 实例，减少启动时间