348 lines
12 KiB
Markdown
348 lines
12 KiB
Markdown
# Jarvis 个人 AI 助理 — Phase 1 实现计划
|
||
|
||
> 生成日期：2026-03-20
|
||
> 目标：完成 Jarvis 核心功能的 MVP 版本
|
||
|
||
---
|
||
|
||
## 技术栈确认
|
||
|
||
| 组件 | 技术选型 |
|
||
|------|---------|
|
||
| **后端框架** | FastAPI (Python 3.12+) |
|
||
| **Agent 框架** | LangGraph（多 Agent 编排、工具调用、状态机） |
|
||
| **LLM 适配器** | LangChain Claude / OpenAI / Ollama（可切换） |
|
||
| **知识库框架** | LlamaIndex（Node 关系索引、语义检索） |
|
||
| **向量数据库** | ChromaDB |
|
||
| **关系数据库** | SQLite + SQLAlchemy |
|
||
| **前端框架** | Vue 3 + TypeScript + Vite |
|
||
| **移动端** | Kotlin (Android) |
|
||
| **定时任务** | APScheduler |
|
||
| **部署** | Docker（NAS 本地运行） |
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
MyAgents/
|
||
├── backend/ # 后端项目
|
||
│ ├── app/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── main.py # FastAPI 入口
|
||
│ │ ├── config.py # 配置管理
|
||
│ │ ├── database.py # SQLAlchemy 数据库连接
|
||
│ │ ├── models/ # 数据库模型
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── user.py
|
||
│ │ │ ├── document.py
|
||
│ │ │ ├── task.py
|
||
│ │ │ ├── forum.py
|
||
│ │ │ ├── agent.py
|
||
│ │ │ ├── conversation.py
|
||
│ │ │ └── knowledge_graph.py
|
||
│ │ ├── schemas/ # Pydantic 请求/响应模型
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── auth.py
|
||
│ │ │ ├── conversation.py
|
||
│ │ │ ├── document.py
|
||
│ │ │ ├── task.py
|
||
│ │ │ ├── forum.py
|
||
│ │ │ └── graph.py
|
||
│ │ ├── routers/ # API 路由
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── auth.py
|
||
│ │ │ ├── conversation.py
|
||
│ │ │ ├── document.py
|
||
│ │ │ ├── task.py
|
||
│ │ │ ├── forum.py
|
||
│ │ │ └── graph.py
|
||
│ │ ├── agents/ # LangGraph Agent 系统
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── graph.py # 主 Agent 图定义
|
||
│ │ │ ├── nodes/ # Agent 节点
|
||
│ │ │ │ ├── __init__.py
|
||
│ │ │ │ ├── master.py # 主调度 Agent
|
||
│ │ │ │ ├── planner.py # 规划 Agent
|
||
│ │ │ │ ├── executor.py # 执行 Agent
|
||
│ │ │ │ ├── librarian.py # 知识管理员 Agent
|
||
│ │ │ │ └── analyst.py # 分析师 Agent
|
||
│ │ │ ├── tools/ # Agent 工具集
|
||
│ │ │ │ ├── __init__.py
|
||
│ │ │ │ ├── search.py # 知识库检索工具
|
||
│ │ │ │ ├── task.py # 任务操作工具
|
||
│ │ │ │ ├── forum.py # 论坛操作工具
|
||
│ │ │ │ └── graph.py # 图谱操作工具
|
||
│ │ │ └── prompts/ # Agent 提示词
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── master_prompt.py
|
||
│ │ │ └── sub_agent_prompts.py
|
||
│ │ ├── services/ # 业务逻辑服务
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── llm_service.py # LLM 调用服务
|
||
│ │ │ ├── knowledge_service.py # 知识库服务
|
||
│ │ │ ├── graph_service.py # 知识图谱服务
|
||
│ │ │ ├── scheduler_service.py # 定时任务服务
|
||
│ │ │ └── agent_service.py # Agent 调用服务
|
||
│ │ ├── knowledge/ # 知识库核心
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── indexer.py # LlamaIndex 索引器
|
||
│ │ │ ├── chunker.py # 文档分块策略
|
||
│ │ │ └── retriever.py # 检索器
|
||
│ │ └── utils/ # 工具函数
|
||
│ │ ├── __init__.py
|
||
│ │ └── security.py
|
||
│ ├── tests/ # 测试
|
||
│ │ ├── __init__.py
|
||
│ │ ├── test_agents.py
|
||
│ │ ├── test_knowledge.py
|
||
│ │ └── test_api.py
|
||
│ ├── pyproject.toml
|
||
│ ├── uv.lock
|
||
│ └── Dockerfile
|
||
│
|
||
├── frontend/ # 前端项目
|
||
│ ├── src/
|
||
│ │ ├── App.vue
|
||
│ │ ├── main.ts
|
||
│ │ ├── api/ # API 调用
|
||
│ │ │ ├── index.ts
|
||
│ │ │ ├── conversation.ts
|
||
│ │ │ ├── document.ts
|
||
│ │ │ ├── task.ts
|
||
│ │ │ ├── forum.ts
|
||
│ │ │ └── graph.ts
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── views/ # 页面视图
|
||
│ │ │ ├── ChatView.vue # 主对话页
|
||
│ │ │ ├── KnowledgeView.vue # 知识库页
|
||
│ │ │ ├── GraphView.vue # 知识图谱页
|
||
│ │ │ ├── ForumView.vue # 论坛页
|
||
│ │ │ ├── KanbanView.vue # 看板页
|
||
│ │ │ └── LoginView.vue # 登录页
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── router/ # Vue Router
|
||
│ │ ├── types/ # TypeScript 类型
|
||
│ │ └── styles/ # 全局样式
|
||
│ ├── public/
|
||
│ ├── package.json
|
||
│ └── vite.config.ts
|
||
│
|
||
├── android/ # Android 项目（后续）
|
||
│
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 开发阶段
|
||
|
||
### Phase 1 — 核心骨架（第 1-2 周）
|
||
|
||
**目标**：跑通最基础的服务，能对话、能上传文档、能检索
|
||
|
||
1. **搭建后端项目** — FastAPI + 项目结构 + 依赖安装
|
||
2. **搭建前端项目** — Vue 3 + Vite + TypeScript + 基础路由
|
||
3. **实现 LLM 适配器** — LangChain Claude/OpenAI/Ollama 统一接口
|
||
4. **实现简单对话** — 单 Agent + WebSocket 流式输出
|
||
5. **实现知识库上传** — LlamaIndex + ChromaDB + 文档分块
|
||
6. **实现基础检索** — 向量检索 + 返回结果
|
||
|
||
### Phase 2 — 多 Agent 系统（第 3-4 周）
|
||
|
||
**目标**：多 Agent 协作跑起来
|
||
|
||
1. **实现主 Agent** — LangGraph 状态机 + 工具注册
|
||
2. **实现子 Agent** — 规划、执行、知识管理、分析师 4 个角色
|
||
3. **实现工具集** — 知识检索、任务操作、论坛操作工具
|
||
4. **Agent 通信** — 协作式 + 主 Agent 协调模式
|
||
|
||
### Phase 3 — 知识图谱（第 5-6 周）
|
||
|
||
**目标**：文档知识能沉淀到图谱中
|
||
|
||
1. **实体识别** — LLM 从文档 Node 中提取实体
|
||
2. **关系抽取** — LLM 抽取实体间关系
|
||
3. **图谱存储** — nodes + edges 存入 SQLite
|
||
4. **图谱可视化** — 前端 D3.js / ECharts 渲染
|
||
|
||
### Phase 4 — 论坛 + 看板（第 7-8 周）
|
||
|
||
**目标**：论坛发帖、AI 扫描执行、看板任务管理
|
||
|
||
1. **论坛 CRUD** — 帖子发布、回复、列表
|
||
2. **AI 扫描引擎** — 定时扫描论坛、识别可执行指令
|
||
3. **看板 CRUD** — 任务卡片、优先级、状态
|
||
4. **AI 每日规划** — 凌晨分析完成情况、生成次日建议
|
||
|
||
### Phase 5 — 前端完整 UI（第 9-10 周）
|
||
|
||
**目标**：所有功能页面完成，科幻风格 UI
|
||
|
||
1. **主对话界面** — 流式输出、Agent 角色切换
|
||
2. **知识库界面** — 文件上传、检索、结果展示
|
||
3. **图谱可视化** — 可交互的节点关系图
|
||
4. **论坛界面** — 发帖、列表、AI 执行标记
|
||
5. **看板界面** — 拖拽卡片、状态流转、AI 建议
|
||
|
||
### Phase 6 — Android App（第 11-12 周）
|
||
|
||
**目标**：移动端能对话、能看看板
|
||
|
||
1. **Android 项目搭建** — Kotlin + Jetpack Compose
|
||
2. **对话界面** — WebSocket 连接后端、流式对话
|
||
3. **看板视图** — 任务列表、状态切换
|
||
4. **基础设置** — 服务器地址配置
|
||
|
||
### Phase 7 — 部署 + 优化（第 13-14 周）
|
||
|
||
**目标**：部署到 NAS，稳定运行
|
||
|
||
1. **Docker 打包** — 后端 + 前端镜像
|
||
2. **NAS 部署** — Docker Compose 一键启动
|
||
3. **性能优化** — 缓存、异步、数据库索引
|
||
4. **安全加固** — JWT、API 限流、数据加密
|
||
|
||
---
|
||
|
||
## Phase 1 详细任务
|
||
|
||
### 1.1 后端项目初始化
|
||
|
||
```
|
||
backend/
|
||
├── pyproject.toml
|
||
│ ├── fastapi>=0.115.0
|
||
│ ├── uvicorn[standard]>=0.30.0
|
||
│ ├── langgraph>=0.2.0
|
||
│ ├── langchain-anthropic>=0.3.0
|
||
│ ├── langchain-openai>=0.2.0
|
||
│ ├── llama-index>=0.12.0
|
||
│ ├── llama-index-vector-stores-chroma>=0.3.0
|
||
│ ├── chromadb>=0.5.0
|
||
│ ├── sqlalchemy>=2.0.0
|
||
│ ├── aiosqlite>=0.20.0
|
||
│ ├── pydantic>=2.0.0
|
||
│ ├── pydantic-settings>=2.0.0
|
||
│ ├── python-jose[cryptography]>=3.3.0
|
||
│ ├── passlib[bcrypt]>=1.7.4
|
||
│ ├── APScheduler>=3.10.0
|
||
│ ├── python-multipart>=0.0.12
|
||
│ ├── websockets>=12.0
|
||
│ └── aiofiles>=24.0.0
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── main.py
|
||
│ ├── config.py
|
||
│ └── database.py
|
||
└── Dockerfile
|
||
```
|
||
|
||
### 1.2 前端项目初始化
|
||
|
||
```
|
||
frontend/
|
||
├── Vite + Vue 3 + TypeScript
|
||
├── Pinia (状态管理)
|
||
├── Vue Router 4
|
||
├── Axios (HTTP 客户端)
|
||
├── VueUse (工具函数)
|
||
├── TailwindCSS (样式)
|
||
└── Lucide Vue (图标)
|
||
```
|
||
|
||
### 1.3 LLM 适配器接口
|
||
|
||
```python
|
||
# backend/app/services/llm_service.py
|
||
|
||
from langchain_anthropic import ChatAnthropic
|
||
from langchain_openai import ChatOpenAI
|
||
from langchain_ollama import ChatOllama
|
||
from abc import ABC, abstractmethod
|
||
|
||
class LLMAdapter(ABC):
|
||
@abstractmethod
|
||
async def invoke(self, messages: list[dict]) -> str:
|
||
...
|
||
|
||
@abstractmethod
|
||
async def stream(self, messages: list[dict]):
|
||
...
|
||
|
||
class ClaudeAdapter(LLMAdapter):
|
||
def __init__(self, api_key: str, model: str = "claude-sonnet-4-20250514"):
|
||
self.llm = ChatAnthropic(api_key=api_key, model=model)
|
||
|
||
class OpenAIAdapter(LLMAdapter):
|
||
def __init__(self, api_key: str, model: str = "gpt-4o"):
|
||
self.llm = ChatOpenAI(api_key=api_key, model=model)
|
||
|
||
class OllamaAdapter(LLMAdapter):
|
||
def __init__(self, base_url: str = "http://localhost:11434", model: str = "llama3"):
|
||
self.llm = ChatOllama(base_url=base_url, model=model)
|
||
|
||
# 工厂函数，根据配置返回对应适配器
|
||
def get_llm_adapter(provider: str, **kwargs) -> LLMAdapter:
|
||
adapters = {
|
||
"claude": ClaudeAdapter,
|
||
"openai": OpenAIAdapter,
|
||
"ollama": OllamaAdapter,
|
||
}
|
||
return adapters[provider](**kwargs)
|
||
```
|
||
|
||
### 1.4 简单对话 API
|
||
|
||
```python
|
||
# POST /api/chat
|
||
# Body: { "message": "你好 Jarvis", "conversation_id": "uuid" }
|
||
# Response: WebSocket 连接，流式返回
|
||
|
||
@app.websocket("/ws/chat/{conversation_id}")
|
||
async def websocket_chat(websocket, conversation_id: str):
|
||
async for message in websocket:
|
||
# 1. 存入历史
|
||
# 2. 调用 LangGraph Agent
|
||
# 3. 流式返回结果
|
||
yield "data: ..."
|
||
|
||
# GET /api/conversations — 对话历史列表
|
||
# POST /api/conversations — 创建新对话
|
||
# DELETE /api/conversations/{id} — 删除对话
|
||
```
|
||
|
||
### 1.5 知识库上传 API
|
||
|
||
```python
|
||
# POST /api/documents/upload
|
||
# Body: multipart/form-data, file + metadata
|
||
# 返回: document_id, chunk_count
|
||
|
||
# GET /api/documents — 文档列表
|
||
# GET /api/documents/{id} — 文档详情 + chunks
|
||
# DELETE /api/documents/{id} — 删除文档
|
||
|
||
# POST /api/documents/search
|
||
# Body: { "query": "查找...", "top_k": 5 }
|
||
# 返回: 检索结果列表
|
||
```
|
||
|
||
---
|
||
|
||
## 第一步操作
|
||
|
||
现在开始执行 Phase 1.1 — 搭建后端项目结构。
|
||
|
||
需要创建：
|
||
1. `backend/pyproject.toml`
|
||
2. `backend/app/__init__.py`
|
||
3. `backend/app/main.py`
|
||
4. `backend/app/config.py`
|
||
5. `backend/app/database.py`
|
||
6. `backend/.env.example`
|
||
|
||
是否现在开始？
|