caoxiaozhu/JARVIS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add project documentation and specs

Browse Source
This commit is contained in:
DESKTOP-72TV0V4\caoxiaozhu
2026-03-21 10:13:45 +08:00
parent e76f0828b9
commit 3a7f4174ab
20 changed files with 11179 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
docs/superpowers/implementation/phase-1-plan.md Normal file
View File

@@ -0,0 +1,347 @@
# 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`
是否现在开始？