# Jarvis 个人 AI 助理 — 设计规格书

> 版本：v1.0
> 日期：2026-03-20
> 作者：Jarvis 设计团队

---

## 1. 项目概述

### 1.1 项目目标

构建一个拟人化的个人 AI 助理系统，代号 **Jarvis**。核心目标是打造一个真正"懂你"的智能体 —— 理解你的知识体系、工作安排和个人偏好，而不仅仅是关键词匹配回答问题。

### 1.2 核心价值

- **知识回溯能力** — 基于 LlamaIndex Node 关系 + 知识图谱双层架构，确保 AI 真正理解你的知识和工作的内在联系
- **拟人化协作** — 多 Agent 角色协同，每个角色有独立职责，像真实团队成员一样交流
- **全端覆盖** — Web + Android 双端，随时随地与 Jarvis 对话
- **本地部署** — 所有数据存储在 NAS，数据完全自主可控

---

## 2. 技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| **Web 前端** | Vue 3 + TypeScript | Composition API，响应式 UI |
| **移动端** | Kotlin (Android) | Jetpack Compose，轻量连接器 |
| **后端框架** | FastAPI (Python 3.12+) | 高性能 ASGI，支持 async |
| **Agent 框架** | LangGraph | 多 Agent 编排、工具调用、状态机流转 |
| **LLM 适配器** | LangChain Claude / OpenAI / Ollama | 可切换，不影响上层逻辑 |
| **知识库框架** | LlamaIndex | Node 关系索引、语义检索 |
| **向量数据库** | ChromaDB | 轻量级向量存储 |
| **关系数据库** | SQLite | 轻量数据持久化 |
| **定时任务** | APScheduler | 定时任务调度 |
| **部署环境** | NAS (本地) | Docker 容器化部署 |

---

## 3. 系统架构

### 3.1 整体架构图

```
┌─────────────────────────────────────────────────────┐
│                    用户端                            │
│  ┌──────────────────┐    ┌──────────────────┐      │
│  │    Web 前端       │    │  Android App     │      │
│  │   (Vue 3 + TS)   │    │  (Kotlin)        │      │
│  └────────┬─────────┘    └────────┬─────────┘      │
└───────────┼────────────────────────┼─────────────────┘
            │                        │
            │  HTTP / WebSocket       │
            └────────┬────────────────┘
                     │
┌────────────────────▼─────────────────────────────────┐
│               FastAPI 后端服务                        │
│                 (NAS Docker 容器)                      │
│                                                       │
│  ┌───────────────────────────────────────────────┐   │
│  │              多 Agent 调度系统                  │   │
│  │  ┌─────────┐                                   │   │
│  │  │ 主Agent │ ◄── 协调者，统一入口               │   │
│  │  │(调度员) │                                   │   │
│  │  └────┬────┘                                   │   │
│  │       ├──► 规划Agent ──► 任务拆解、计划制定    │   │
│  │       ├──► 执行Agent ──► 工具调用、任务执行     │   │
│  │       ├──► 知识管理员 ──► 知识库管理、图谱更新  │   │
│  │       └──► 分析师Agent ──► 数据分析、报告生成  │   │
│  │       └──► [可扩展] ────► 新角色注册机制        │   │
│  └───────────────────────────────────────────────┘   │
│                                                       │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐ │
│  │  LLM 适配器  │  │ 定时任务    │  │  论坛扫描    │ │
│  │ LangChain   │  │ 引擎        │  │  引擎        │ │
│  │ (可切换)     │  │            │  │              │ │
│  └─────────────┘  └─────────────┘  └──────────────┘ │
└──────────────────────────┬────────────────────────────┘
                           │
     ┌─────────────────────┼─────────────────────┐
     │                     │                     │
┌────▼────┐  ┌─────────────▼────┐  ┌──────────▼────────┐
│ ChromaDB│  │      SQLite        │  │    文件存储         │
│向量数据库│  │    (关系数据)      │  │  (NAS 共享目录)     │
└─────────┘  └───────────────────┘  └────────────────────┘
```

### 3.2 通信模式

- **协作式 + 主 Agent 协调**
- 主 Agent 作为统一入口，接收用户请求后分发到子 Agent
- 子 Agent 完成任务后汇总结果给主 Agent
- 子 Agent 之间可通过主 Agent 传递信息
- 支持新增 Agent 注册到系统中

---

## 4. 核心功能模块

### 4.1 多 Agent 调度系统

#### Agent 角色定义

| Agent | 职责 | 核心能力 |
|-------|------|---------|
| **主Agent (Jarvis)** | 协调调度、对话入口 | 意图识别、任务分发、结果汇总 |
| **规划Agent** | 制定每日计划 | 任务拆解、优先级排序、时间规划 |
| **执行Agent** | 执行具体任务 | 工具调用、进度追踪、结果反馈 |
| **知识管理员** | 管理知识库和图谱 | 文档索引、实体提取、图谱更新 |
| **分析师Agent** | 分析工作数据 | 数据统计、趋势分析、报告生成 |

#### Agent 扩展机制

- 通过配置文件或 API 注册新 Agent
- 每个 Agent 有独立的 system prompt 和工具集
- 新增 Agent 自动出现在对话上下文中

### 4.2 知识库系统

#### 文档处理流程

```
用户上传文件
    │
    ▼
文件解析
├── Markdown → 直接读取
├── PDF → PDF 解析（PyMuPDF）
├── DOCX → python-docx
└── TXT → 直接读取
    │
    ▼
LlamaIndex Node 构建
├── 按标题层级切分（Header-based Chunking）
├── 保留 Node 关系链表（PARENT, PREVIOUS, NEXT, SOURCE）
└── 每个 Node 包含 metadata（标题、章节、页码）
    │
    ▼
向量存储 → ChromaDB
    │
    ▼
知识图谱构建
├── LLM 实体识别（从 Node 内容中提取）
├── LLM 关系抽取（实体之间的关系）
└── 存入 SQLite（nodes + edges 表）
```

#### 检索流程（Small-to-Big 策略）

```
用户提问
    │
    ▼
ChromaDB 向量检索
├── 用小 Chunk 精确匹配
└── 返回多个相关 Node
    │
    ▼
上下文回溯
├── 顺着 Node 关系找到完整章节（父 Node）
└── 附加上下文给 LLM
    │
    ▼
LLM 生成回答
```

### 4.3 知识图谱系统

#### 图谱数据结构

```sql
-- 知识图谱节点表
knowledge_graph_nodes (
    id TEXT PRIMARY KEY,
    user_id TEXT,            -- 用户隔离（支持多用户）
    entity_type TEXT,        -- 实体类型：PERSON / EVENT / CONCEPT / OBJECT
    entity_name TEXT,        -- 实体名称
    description TEXT,        -- 实体描述
    source_doc_id TEXT,      -- 来源文档
    source_node_id TEXT,     -- 来源 Node
    importance REAL,         -- 重要程度 (0-1)
    created_at TIMESTAMP,
    updated_at TIMESTAMP
)

-- 知识图谱边表
knowledge_graph_edges (
    id TEXT PRIMARY KEY,
    user_id TEXT,            -- 用户隔离
    source_node_id TEXT,
    target_node_id TEXT,
    relation_type TEXT,      -- 关系类型：包含 / 依赖 / 相关 / 导致 / 属于
    weight REAL,             -- 关系权重 (0-1)
    created_at TIMESTAMP,
    FOREIGN KEY (source_node_id) REFERENCES knowledge_graph_nodes(id),
    FOREIGN KEY (target_node_id) REFERENCES knowledge_graph_nodes(id)
)
```

#### 图谱更新机制

- **事件驱动**：文档上传/任务变更时实时触发
- **定时同步**：每日凌晨增量扫描，防止遗漏
- **手动触发**：用户可主动要求重建图谱
- **增量检测**：基于文件 mtime + 内容 hash 判断文档是否变化

#### 数据模型

```sql
-- 文档表
documents (
    id TEXT PRIMARY KEY,
    user_id TEXT,            -- 用户隔离
    filename TEXT,
    file_type TEXT,          -- pdf / markdown / docx / txt
    file_path TEXT,          -- NAS 存储路径
    file_hash TEXT,          -- 内容 hash，用于增量检测
    summary TEXT,            -- AI 生成的文档摘要
    file_size INTEGER,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
)

-- 文档分块表（LlamaIndex Node 映射）
document_chunks (
    id TEXT PRIMARY KEY,
    user_id TEXT,            -- 用户隔离
    document_id TEXT,
    chunk_index INTEGER,     -- 在文档中的顺序
    content TEXT,            -- 原始文本内容
    metadata JSON,           -- LlamaIndex Node metadata（包含 title、chapter、relationships 等）
    embedding_id TEXT,       -- ChromaDB 中的向量 ID
    created_at TIMESTAMP,
    FOREIGN KEY (document_id) REFERENCES documents(id)
)
```

#### 图谱可视化

- 前端 Web 端展示交互式知识图谱
- 节点可点击查看详情
- 支持按类型筛选、按时间筛选
- 支持搜索实体名称

### 4.4 论坛系统

#### 功能设计

- **发布内容** — 你在论坛发布想法、指令、问题
- **AI 扫描** — Jarvis 定时扫描论坛内容
- **任务识别** — 识别可执行的任务转为看板任务
- **互动回应** — AI 在帖子下回复，像团队成员讨论

#### 数据模型

```sql
forum_posts (
    id TEXT PRIMARY KEY,
    user_id TEXT,          -- 发帖用户
    title TEXT,
    content TEXT,
    parent_id TEXT,        -- 回复的帖子 ID（自关联，支持嵌套回复）
    status TEXT,           -- pending / processing / completed
    created_at TIMESTAMP,
    updated_at TIMESTAMP
)
```

### 4.5 看板系统

#### 功能设计

- **任务管理** — 创建、编辑、删除任务
- **状态流转** — 待办 / 进行中 / 已完成 / 已取消
- **优先级** — P0 / P1 / P2 / P3
- **AI 凌晨分析** — 每日凌晨分析完成情况，规划次日任务
- **AI 建议** — 根据你的工作模式给出优先级建议

#### 数据模型

```sql
tasks (
    id TEXT PRIMARY KEY,
    user_id TEXT,          -- 用户隔离
    title TEXT,
    description TEXT,
    priority TEXT,         -- P0 / P1 / P2 / P3
    status TEXT,           -- todo / in_progress / done / cancelled
    deadline TIMESTAMP,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    completed_at TIMESTAMP
)

task_history (
    id TEXT PRIMARY KEY,
    task_id TEXT,
    action TEXT,           -- created / updated / completed / cancelled
    old_value TEXT,
    new_value TEXT,
    timestamp TIMESTAMP,
    FOREIGN KEY (task_id) REFERENCES tasks(id)
)
```

### 4.6 Markdown 编辑器

#### 功能设计

- 浏览器端在线编辑 Markdown
- 支持实时预览
- AI 辅助功能：
  - AI 续写
  - AI 润色
  - AI 总结
- 自动保存到知识库
- 支持创建新文档和编辑已有文档

### 4.7 定时任务引擎

#### 内置定时任务

| 任务 | 触发时间 | 功能 |
|------|---------|------|
| 论坛扫描 | 可配置（默认每小时） | 扫描新帖子，识别可执行任务 |
| 图谱增量同步 | 每日凌晨 2:00 | 扫描文档变化，更新知识图谱 |
| 每日规划 | 每日早上 8:00 | 分析昨日任务完成情况，规划当日 |
| 知识摘要 | 每周一凌晨 | 生成上周工作摘要 |

---

## 5. 数据库设计

### 5.1 ER 图

```
users
  │
  ▼
documents ──► document_chunks ──► embeddings (ChromaDB)
  │
  ▼
knowledge_graph_nodes ◄──► knowledge_graph_edges
  │
  ▼
tasks ◄─── task_history
  │
  ▼
forum_posts (自关联: parent_id ──► forum_posts.id)
  │
  ▼
conversations ──► messages
```

### 5.2 核心表结构

| 表名 | 说明 |
|------|------|
| `users` | 用户信息 |
| `documents` | 上传的文档元数据 |
| `document_chunks` | LlamaIndex Node 映射（保留关系） |
| `knowledge_graph_nodes` | 知识图谱节点 |
| `knowledge_graph_edges` | 知识图谱边 |
| `tasks` | 看板任务 |
| `task_history` | 任务变更历史 |
| `forum_posts` | 论坛帖子（含回复，通过 parent_id 自关联） |
| `conversations` | 主对话会话 |
| `messages` | 对话消息 |
| `knowledge_summaries` | 历史对话摘要 |

#### 对话数据模型

```sql
conversations (
    id TEXT PRIMARY KEY,
    user_id TEXT,            -- 用户隔离
    title TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
)

messages (
    id TEXT PRIMARY KEY,
    conversation_id TEXT,
    role TEXT,               -- user / assistant
    content TEXT,
    model TEXT,              -- 使用的模型
    created_at TIMESTAMP,
    FOREIGN KEY (conversation_id) REFERENCES conversations(id)
)

knowledge_summaries (
    id TEXT PRIMARY KEY,
    user_id TEXT,
    period TEXT,             -- daily / weekly / monthly
    period_start DATE,
    period_end DATE,
    summary TEXT,            -- 摘要内容
    created_at TIMESTAMP
)
```

---

## 6. API 设计

### 6.1 主要 API 端点

> **通用规则**：所有列表接口支持分页参数 `page`（页码，默认 1）和 `page_size`（每页数量，默认 20）。返回格式统一为 `{ data: [...], total: N, page: X, page_size: Y }`。

#### 认证接口
- `POST /api/auth/register` — 用户注册
- `POST /api/auth/login` — 用户登录，返回 JWT Token
- `POST /api/auth/refresh` — 刷新 Token
- `POST /api/auth/logout` — 登出

#### 对话接口
- `POST /api/chat` — 发送消息，获取 AI 回复
- `GET /api/conversations?page=&page_size=` — 获取对话历史列表
- `GET /api/conversations/{id}/messages?page=&page_size=` — 获取对话消息

#### 知识库接口
- `POST /api/documents/upload` — 上传文档（支持 multipart/form-data，最大 50MB）
- `GET /api/documents?page=&page_size=` — 获取文档列表
- `DELETE /api/documents/{id}` — 删除文档
- `POST /api/documents/{id}/reindex` — 重建索引（幂等操作）
- `POST /api/search` — 语义搜索
  - 请求体：`{ "query": "搜索内容", "top_k": 5, "filters": {} }`

#### 知识图谱接口
- `GET /api/knowledge-graph` — 获取图谱数据
- `POST /api/knowledge-graph/rebuild` — 触发图谱重建（幂等，带锁防止并发）
- `GET /api/knowledge-graph/search?q=` — 搜索实体

#### 看板接口
- `GET /api/tasks?page=&page_size=&status=` — 获取任务列表
- `POST /api/tasks` — 创建任务
- `PUT /api/tasks/{id}` — 更新任务
- `DELETE /api/tasks/{id}` — 删除任务

#### 论坛接口
- `GET /api/forum/posts?page=&page_size=` — 获取帖子列表
- `POST /api/forum/posts` — 发布帖子
- `GET /api/forum/posts/{id}` — 获取帖子详情（含回复树）
- `POST /api/forum/posts/{id}/reply` — 回复帖子

#### Markdown 编辑器接口
- `GET /api/notes?page=&page_size=` — 获取笔记列表
- `POST /api/notes` — 创建笔记
- `PUT /api/notes/{id}` — 更新笔记
- `DELETE /api/notes/{id}` — 删除笔记
- `POST /api/notes/{id}/ai-assist` — AI 辅助操作
  - 请求体：`{ "action": "continue" | "polish" | "summarize" }`

### 6.2 WebSocket 实时通信

消息格式统一为 JSON：
```json
// 通用消息结构
{
  "type": "chat_message" | "graph_update" | "task_update",
  "payload": { ... },
  "timestamp": "ISO8601"
}
```

- `/ws/chat` — 实时对话（流式输出）
- `/ws/knowledge-graph` — 图谱更新实时推送
- `/ws/tasks` — 任务状态变化实时推送

---

## 7. 前端设计

### 7.1 Web 端页面结构

```
┌─────────────────────────────────────────┐
│  顶部导航栏                              │
│  [对话] [知识库] [图谱] [看板] [论坛] [笔记] │
└─────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│                                         │
│           主内容区域                      │
│                                         │
└─────────────────────────────────────────┘
```

### 7.2 核心页面

| 页面 | 功能 |
|------|------|
| **对话页** | 主对话界面，Jarvis 头像，消息列表，输入框 |
| **知识库页** | 文档列表，上传入口，搜索框 |
| **图谱页** | 交互式知识图谱，节点详情侧边栏 |
| **看板页** | 任务看板（Kanban 布局），AI 规划建议 |
| **论坛页** | 帖子列表，发帖入口，AI 回复展示 |
| **笔记页** | Markdown 编辑器，笔记列表 |

### 7.3 Android 端

- 独立对话窗口，直接与 Jarvis 对话
- 任务查看和简单编辑
- 推送通知（每日规划提醒、任务到期提醒）
- 核心是**对话遥控**，重度操作建议用 Web 端

---

## 8. 部署架构

### 8.1 NAS 部署方案

```
┌──────────────────────────────────────────────────┐
│                    NAS                            │
│                                                   │
│  ┌────────────────────────────────────────────┐  │
│  │              Docker Compose                 │  │
│  │                                            │  │
│  │  ┌──────────────┐  ┌──────────────────┐   │  │
│  │  │  Jarvis API   │  │   ChromaDB       │   │  │
│  │  │  (FastAPI)    │  │   (向量数据)     │   │  │
│  │  └──────────────┘  └──────────────────┘   │  │
│  │                                            │  │
│  │  ┌──────────────┐  ┌──────────────────┐   │  │
│  │  │   SQLite     │  │   文件存储        │   │  │
│  │  │  (关系数据)   │  │  /data/files     │   │  │
│  │  └──────────────┘  └──────────────────┘   │  │
│  └────────────────────────────────────────────┘  │
│                                                   │
│  NAS 共享目录 /data 挂载到容器                     │
└──────────────────────────────────────────────────┘
```

### 8.2 环境变量配置

```env
# LLM 配置
LLM_PROVIDER=claude  # claude / deepseek / ollama
CLAUDE_API_KEY=xxx
DEEPSEEK_API_KEY=xxx
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3

# 数据库配置
DATABASE_URL=sqlite+aiosqlite:///data/jarvis.db
CHROMA_PERSIST_DIR=/data/chroma

# 文件存储
FILE_STORAGE_DIR=/data/files

# 定时任务配置
FORUM_SCAN_INTERVAL=3600  # 秒
DAILY_PLAN_TIME=08:00
GRAPH_SYNC_TIME=02:00

# JWT 认证
JWT_SECRET=xxx
JWT_ALGORITHM=HS256
```

---

## 9. 安全设计

- **JWT 认证** — 所有 API 需要 Token 验证
- **数据加密** — SQLite 数据库可配置加密
- **文件隔离** — 用户上传文件存储在独立目录
- **API 限流** — 防止 API 滥用
- **敏感信息** — API Key 等存储在环境变量，不进入代码库

---

## 10. 未来扩展方向

- **多模态支持** — 图片、音频、视频解析
- **更多 Agent** — 按领域细分的专业助手
- **插件系统** — 第三方工具集成
- **团队协作** — 多用户知识共享
- **云端同步** — 异地数据备份

---

## 11. 开发阶段建议

> **注意**：Phase 3 的知识图谱依赖 Phase 1 的知识库基础设施。Phase 1-3 为核心 MVP，需按顺序开发。

| 阶段 | 内容 | 优先级 |
|------|------|--------|
| **Phase 1** | 基础框架搭建、对话系统、知识库上传检索 | P0 |
| **Phase 2** | 看板系统、论坛系统、Markdown 编辑器 | P0 |
| **Phase 3** | 知识图谱构建与可视化、多 Agent 协同 | P0 |
| **Phase 4** | 定时任务引擎、AI 每日规划功能 | P1 |
| **Phase 5** | Android App 开发 | P1 |
| **Phase 6** | 优化与扩展 | P2 |

---

*本文档为 Jarvis 个人 AI 助理系统的初始设计规格，将根据开发进展持续更新。*