# 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`

是否现在开始？
