175 lines
6.8 KiB
Markdown
175 lines
6.8 KiB
Markdown
---
|
||
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`
|
||
|
||
## 本地环境配置（local-env.json）
|
||
|
||
设备绑定的路径和配置统一存放在 `.cursor/local-env.json`（已 gitignored），不硬编码到 Skill 中。
|
||
|
||
**启动前必须先读取该文件**，从中获取 `nodejs_path` 和 `shell` 字段。
|
||
|
||
| 字段 | 用途 | 示例值 |
|
||
|------|------|--------|
|
||
| `nodejs_path` | Node.js 安装目录（含 node/npm） | `C:\Users\xxx\AppData\Local\nodejs` |
|
||
| `shell` | 当前设备使用的 shell 类型 | `powershell` / `bash` / `zsh` |
|
||
|
||
**文件不存在时的自动探测流程**：
|
||
|
||
```
|
||
1. 创建空的 JSON 对象 {}
|
||
2. 探测 Node.js 路径：
|
||
- 运行 `where.exe node`（Windows）或 `which node`（macOS/Linux）
|
||
- 取其父目录作为 nodejs_path
|
||
- 如果找不到，将 nodejs_path 设为 null，后续启动前端时提醒用户手动配置
|
||
3. 探测 shell 类型：
|
||
- Windows 默认 "powershell"
|
||
- macOS/Linux 读取 $SHELL 环境变量，提取末尾（bash/zsh/fish 等）
|
||
4. 写入 .cursor/local-env.json
|
||
5. 告知用户已自动生成本地配置，可手动调整
|
||
```
|
||
|
||
**Node.js 不在系统 PATH 时**：启动前端的命令中需要将 `nodejs_path` 注入到当前会话的 PATH。
|
||
|
||
## 核心操作：启动服务
|
||
|
||
### 流程
|
||
|
||
```
|
||
1. 确定项目根目录（workspace 根目录下的 art-agent/）
|
||
|
||
2. 读取 .cursor/local-env.json：
|
||
- 存在 → 解析 nodejs_path 和 shell
|
||
- 不存在 → 执行自动探测流程（见上方），生成后再读取
|
||
|
||
3. 检查并启动 Ollama：
|
||
- 检测 Ollama 是否已在运行（请求 http://localhost:11434/api/tags）
|
||
- 未运行 → 启动 Ollama 服务，等待就绪
|
||
- 已运行 → 跳过
|
||
|
||
4. 根据 shell 字段选择对应的启动命令模板：
|
||
- powershell → 使用 PowerShell 命令
|
||
- bash/zsh → 使用 macOS/Linux 命令
|
||
|
||
5. 启动后端（在独立可见终端窗口中）
|
||
|
||
6. 启动前端（在另一个独立可见终端窗口中）：
|
||
- 如果 nodejs_path 不为 null，先注入到 PATH
|
||
|
||
7. 确认三个服务正在运行，告知用户访问地址
|
||
```
|
||
|
||
### 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 设为开机自启，
|
||
> 则检测会直接通过，不会重复启动。
|
||
|
||
### 启动命令模板
|
||
|
||
**关键要求**：必须在**新的、可见的终端窗口**中启动，不能在 Cursor 内置终端后台运行。
|
||
|
||
以下模板中的变量说明：
|
||
- `BACKEND_PATH` / `FRONTEND_PATH`：替换为实际绝对路径
|
||
- `NODEJS_PATH`：从 `local-env.json` 的 `nodejs_path` 字段读取
|
||
|
||
#### shell = "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
|
||
```
|
||
|
||
启动前端（注入从 local-env.json 读取的 NODEJS_PATH）：
|
||
```powershell
|
||
Start-Process powershell -ArgumentList '-NoExit', '-Command', "& { `$env:PATH = 'NODEJS_PATH;' + `$env:PATH; `$Host.UI.RawUI.WindowTitle = 'Art Agent Frontend'; cd 'FRONTEND_PATH'; npm run dev }" -WindowStyle Normal
|
||
```
|
||
|
||
#### shell = "bash" / "zsh"（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"'
|
||
```
|
||
|
||
启动前端（NODEJS_PATH 为 null 时跳过 PATH 注入）：
|
||
```bash
|
||
osascript -e 'tell application "Terminal" to do script "export PATH=NODEJS_PATH:$PATH && 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. **先读 local-env.json** — 启动前必须读取 `.cursor/local-env.json` 获取 `nodejs_path` 和 `shell`。文件不存在时执行自动探测并生成。绝不在 Skill 中硬编码设备相关的路径。
|
||
2. **Node.js PATH 注入** — 如果 `nodejs_path` 不为 null，说明 Node.js 未在系统 PATH 中，启动前端时必须将该路径注入到会话 PATH。
|
||
3. **Ollama 必须先于后端启动** — Mem0 记忆系统依赖 Ollama 的 `nomic-embed-text` 模型做本地 embedding（端口 11434）。Ollama 未运行时后端能启动但对话会报 502 错误。启动流程必须在后端之前检测并启动 Ollama。
|