caoxiaozhu/JARVIS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b024a2bcb5f4a4f132464ec425ff595762a997a9
JARVIS/docs/superpowers/specs/2026-03-20-jarvis-personal-agent-design.md

603 lines
21 KiB
Markdown
Raw Normal View History

Add project documentation and specs
2026-03-21 10:13:45 +08:00
# 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 助理系统的初始设计规格，将根据开发进展持续更新。*
Reference in New Issue Copy Permalink