Files
JARVIS/docs/superpowers/specs/2026-03-20-jarvis-personal-agent-design.md

603 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 关系抽取(实体之间的关系)
└── 存入 SQLitenodes + 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 助理系统的初始设计规格,将根据开发进展持续更新。*