JARVIS/docs/superpowers/implementation/phase-1-plan.md

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 适配器接口

# 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

# 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

# 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

是否现在开始？