caoxiaozhu/JARVIS

Fork 0

Files

DESKTOP-72TV0V4\caoxiaozhu 3a7f4174ab Add project documentation and specs

2026-03-21 10:13:45 +08:00

21 KiB

Raw Blame History

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 知识图谱系统

图谱数据结构

-- 知识图谱节点表
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 判断文档是否变化

数据模型

-- 文档表
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 在帖子下回复，像团队成员讨论

数据模型

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 建议 — 根据你的工作模式给出优先级建议

数据模型

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`	历史对话摘要

对话数据模型

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：

// 通用消息结构
{
  "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 环境变量配置

# 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 助理系统的初始设计规格，将根据开发进展持续更新。

21 KiB Raw Blame History Unescape Escape

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

1. 项目概述

1.1 项目目标

1.2 核心价值

2. 技术栈

3. 系统架构

3.1 整体架构图

3.2 通信模式

4. 核心功能模块

4.1 多 Agent 调度系统

Agent 角色定义

Agent 扩展机制

4.2 知识库系统

文档处理流程

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

4.3 知识图谱系统

图谱数据结构

图谱更新机制

数据模型

图谱可视化

4.4 论坛系统

功能设计

数据模型

4.5 看板系统

功能设计

数据模型

4.6 Markdown 编辑器

功能设计

4.7 定时任务引擎

内置定时任务

5. 数据库设计

5.1 ER 图

5.2 核心表结构

对话数据模型

6. API 设计

6.1 主要 API 端点

认证接口

对话接口

知识库接口

知识图谱接口

看板接口

论坛接口

Markdown 编辑器接口

6.2 WebSocket 实时通信

7. 前端设计

7.1 Web 端页面结构

7.2 核心页面

7.3 Android 端

8. 部署架构

8.1 NAS 部署方案

8.2 环境变量配置

9. 安全设计

10. 未来扩展方向

11. 开发阶段建议

21 KiB

Raw Blame History