---
name: project-launcher
description: >-
  Art Agent 项目一键启动。当用户说"启动项目"、"运行项目"、"打开前端和后端"等时触发，
  自动在独立的可见终端窗口中启动前端（Next.js）和后端（FastAPI），方便用户随时查看和关闭。
---

# Project Launcher

一键启动 Art Agent 的前端和后端服务，在**独立可见的终端窗口**中运行，
用户可以随时查看日志或手动关闭。

## 触发条件

当用户表达以下意图时触发：
- "启动项目"、"运行项目"、"跑起来"
- "打开前端和后端"、"启动服务"
- "start"、"launch"、"run dev"
- "启动后端"、"启动前端"（可单独启动其中一个）

## 项目路径

| 组件 | 路径 | 启动命令 |
|------|------|---------|
| Ollama | 系统级服务 | `ollama serve` |
| 后端 | `art-agent/backend` | `uvicorn app.main:app --reload --host 0.0.0.0 --port 8000` |
| 前端 | `art-agent/frontend` | `npm run dev` |

## 前置条件

- 后端需要激活 Python 虚拟环境（`art-agent/backend/venv`）
- 前端需要 Node.js >= 18
- **Ollama 必须在后端之前启动**：Mem0 记忆系统依赖 Ollama 提供本地 embedding 服务（`nomic-embed-text` 模型），端口 `11434`

## 环境 PATH 须知

本机 Node.js 安装在 `C:\Program Files\nodejs\` 但**未加入系统 PATH**。
新开的终端窗口默认找不到 `node` / `npm` 命令。

**解决方式**：在启动前端的命令中，先将 Node.js 路径注入到当前会话的 `$env:PATH` 中。

> 如果后续 Node.js 路径发生变化（如用户重新安装或使用 nvm），需要更新此处。

## 核心操作：启动服务

### 流程

```
1. 确定项目根目录（workspace 根目录下的 art-agent/）

2. 确定操作系统和 Shell 类型（Windows / macOS / Linux）

3. 检查并启动 Ollama：
   - 检测 Ollama 是否已在运行（请求 http://localhost:11434/api/tags）
   - 未运行 → 启动 Ollama 服务，等待就绪
   - 已运行 → 跳过

4. 启动后端（在独立可见终端窗口中）：
   - Windows（PowerShell 或 CMD 均适用）：
     使用 `Start-Process` 或 `start cmd` 打开新的终端窗口
   - macOS/Linux：
     使用对应的终端打开方式

5. 启动前端（在另一个独立可见终端窗口中）：
   - 同样在新的终端窗口中启动

6. 确认三个服务正在运行，告知用户访问地址
```

### Ollama 启动（跨平台通用）

先检测 Ollama 是否已在运行，未运行则启动：

```powershell
# 检测（PowerShell）
try {
    Invoke-WebRequest -Uri "http://localhost:11434/api/tags" -UseBasicParsing -TimeoutSec 3 | Out-Null
    # 已运行，跳过
} catch {
    # 未运行，启动
    Start-Process "ollama" -ArgumentList "serve" -WindowStyle Normal
    # 等待就绪（最多 10 秒）
    Start-Sleep -Seconds 3
}
```

> Ollama 启动后会常驻后台，不需要独立终端窗口。如果用户系统已将 Ollama 设为开机自启，
> 则检测会直接通过，不会重复启动。

### Windows 启动命令

**关键要求**：必须在**新的、可见的终端窗口**中启动，不能在 Cursor 内置终端后台运行。

#### PowerShell 环境

启动后端：
```powershell
Start-Process powershell -ArgumentList '-NoExit', '-Command', "cd 'BACKEND_PATH'; .\venv\Scripts\Activate.ps1; uvicorn app.main:app --reload --host 0.0.0.0 --port 8000" -WindowStyle Normal
```

启动前端（注意注入 Node.js PATH）：
```powershell
Start-Process powershell -ArgumentList '-NoExit', '-Command', "& { `$env:PATH = 'C:\Program Files\nodejs;' + `$env:PATH; `$Host.UI.RawUI.WindowTitle = 'Art Agent Frontend'; cd 'FRONTEND_PATH'; npm run dev }" -WindowStyle Normal
```

#### CMD 环境

启动后端：
```cmd
start "Art Agent Backend" cmd /k "cd /d BACKEND_PATH && venv\Scripts\activate && uvicorn app.main:app --reload --host 0.0.0.0 --port 8000"
```

启动前端（注意注入 Node.js PATH）：
```cmd
start "Art Agent Frontend" cmd /k "set PATH=C:\Program Files\nodejs;%PATH% && cd /d FRONTEND_PATH && npm run dev"
```

### macOS / Linux 启动命令

根据用户终端环境选择：

```bash
# 后端
osascript -e 'tell application "Terminal" to do script "cd BACKEND_PATH && source venv/bin/activate && uvicorn app.main:app --reload --host 0.0.0.0 --port 8000"'

# 前端
osascript -e 'tell application "Terminal" to do script "cd FRONTEND_PATH && npm run dev"'
```

### 执行注意事项

1. **路径拼接**：`BACKEND_PATH` 和 `FRONTEND_PATH` 必须替换为实际的绝对路径
2. **venv 存在性检查**：启动后端前先确认 `art-agent/backend/venv` 目录存在，
   不存在时提醒用户先创建虚拟环境
3. **依赖检查**：如果 `node_modules` 不存在，先提醒用户执行 `npm install`
4. **窗口标题**：尽量为窗口设置有意义的标题（如 "Art Agent Backend"、"Art Agent Frontend"），
   方便用户在任务栏中识别
5. **不使用 `block_until_ms: 0`**：不要用 Cursor 的后台命令方式，
   那样窗口不可见，用户无法直接查看和关闭

## 单独启动

如果用户只说"启动前端"或"启动后端"，只启动对应的服务即可，不需要全部启动。

## 访问信息

启动完成后告知用户：
- Ollama：http://localhost:11434（Mem0 embedding 服务）
- 后端 API：http://localhost:8000
- 后端文档：http://localhost:8000/docs
- 前端页面：http://localhost:3000

## 自迭代日志

本节记录使用本 Skill 过程中发现的必要检查项。

### 已知必要检查

1. **Node.js PATH 注入** — 本机 Node.js (`C:\Program Files\nodejs\`) 未加入系统 PATH，新开的终端窗口默认找不到 `npm`。启动前端时必须先将此路径注入到会话 PATH 中。
2. **Ollama 必须先于后端启动** — Mem0 记忆系统依赖 Ollama 的 `nomic-embed-text` 模型做本地 embedding（端口 11434）。Ollama 未运行时后端能启动但对话会报 502 错误。启动流程必须在后端之前检测并启动 Ollama。