小优化，产品愿景，视觉规范，交互和导航大版本

2026-04-16 18:11:35 +08:00
parent 5878f7d9f4
commit 10f9c0061a
51 changed files with 5010 additions and 847 deletions
--- a/.cursor/skills/project-launcher/SKILL.md
+++ b/.cursor/skills/project-launcher/SKILL.md
@@ -32,14 +32,33 @@ description: >-
 - 前端需要 Node.js >= 18
 - **Ollama 必须在后端之前启动**：Mem0 记忆系统依赖 Ollama 提供本地 embedding 服务（`nomic-embed-text` 模型），端口 `11434`

-## 环境 PATH 须知
+## 本地环境配置（local-env.json）

-本机 Node.js 安装在 `C:\Program Files\nodejs\` 但**未加入系统 PATH**。
-新开的终端窗口默认找不到 `node` / `npm` 命令。
+设备绑定的路径和配置统一存放在 `.cursor/local-env.json`（已 gitignored），不硬编码到 Skill 中。

-**解决方式**：在启动前端的命令中，先将 Node.js 路径注入到当前会话的 `$env:PATH` 中。
+**启动前必须先读取该文件**，从中获取 `nodejs_path` 和 `shell` 字段。

-> 如果后续 Node.js 路径发生变化（如用户重新安装或使用 nvm），需要更新此处。
+| 字段 | 用途 | 示例值 |
+|------|------|--------|
+| `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。

 ## 核心操作：启动服务

@@ -48,23 +67,25 @@ description: >-
 ```
 1. 确定项目根目录（workspace 根目录下的 art-agent/）

-2. 确定操作系统和 Shell 类型（Windows / macOS / Linux）
+2. 读取 .cursor/local-env.json：
+   - 存在 → 解析 nodejs_path 和 shell
+   - 不存在 → 执行自动探测流程（见上方），生成后再读取

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

-4. 启动后端（在独立可见终端窗口中）：
-   - Windows（PowerShell 或 CMD 均适用）：
-     使用 `Start-Process` 或 `start cmd` 打开新的终端窗口
-   - macOS/Linux：
-     使用对应的终端打开方式
+4. 根据 shell 字段选择对应的启动命令模板：
+   - powershell → 使用 PowerShell 命令
+   - bash/zsh → 使用 macOS/Linux 命令

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

-6. 确认三个服务正在运行，告知用户访问地址
+6. 启动前端（在另一个独立可见终端窗口中）：
+   - 如果 nodejs_path 不为 null，先注入到 PATH
+
+7. 确认三个服务正在运行，告知用户访问地址
 ```

 ### Ollama 启动（跨平台通用）
@@ -87,44 +108,36 @@ try {
 > Ollama 启动后会常驻后台，不需要独立终端窗口。如果用户系统已将 Ollama 设为开机自启，
 > 则检测会直接通过，不会重复启动。

-### Windows 启动命令
+### 启动命令模板

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

-#### PowerShell 环境
+以下模板中的变量说明：
+- `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
 ```

-启动前端（注意注入 Node.js PATH）：
+启动前端（注入从 local-env.json 读取的 NODEJS_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
+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
 ```

-#### CMD 环境
+#### shell = "bash" / "zsh"（macOS / Linux）

 启动后端：
-```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"'
+启动前端（NODEJS_PATH 为 null 时跳过 PATH 注入）：
+```bash
+osascript -e 'tell application "Terminal" to do script "export PATH=NODEJS_PATH:$PATH && cd FRONTEND_PATH && npm run dev"'
 ```

 ### 执行注意事项
@@ -156,5 +169,6 @@ osascript -e 'tell application "Terminal" to do script "cd FRONTEND_PATH && npm

 ### 已知必要检查

-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。
+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。