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

2026-04-16 18:11:35 +08:00
parent 5878f7d9f4
commit 10f9c0061a
51 changed files with 5010 additions and 847 deletions
--- a/.cursor/skills/epee-orchestrator/registry.md
+++ b/.cursor/skills/epee-orchestrator/registry.md
@@ -49,10 +49,18 @@
 - **路径**: .cursor/skills/pitfall-journal/SKILL.md
 - **备注**: 与 dev-changelog 互补——changelog 记事实，pitfall 记经验；由 pitfall-recall Rule 触发自动检索

+### problem-distillery
+- **类型**: 基础设施
+- **能力**: 追踪反复出现的顽固问题，记录解决过程和弯路，定期蒸馏精炼方法论，经实践验证后自动升级为新会话常规注入
+- **触发场景**: "还有问题"、"没解决"、"还是一样"、"又出现了"、"试了好多次"、"反复出现"、Agent 意识到同一问题尝试 2 次以上未解决、"蒸馏"、"总结经验"
+- **输出**: .cursor/distillery/ 下的 problems.md、insights.md、golden-rules.md
+- **路径**: .cursor/skills/problem-distillery/SKILL.md
+- **备注**: 与 pitfall-journal 互补——pitfall 是事后快照，distillery 是过程追踪 + 知识提炼；golden-rules 由 distillery-recall Rule 每次会话注入
+
 ### project-launcher
 - **类型**: 项目级
 - **能力**: 一键启动 Art Agent 全部服务（Ollama + 后端 FastAPI + 前端 Next.js），自动检测已运行的服务并跳过
 - **触发场景**: "启动项目"、"运行项目"、"跑起来"、"打开前端和后端"、"启动服务"、"start"、"launch"、"run dev"、"启动前端"、"启动后端"
 - **输出**: Ollama 后台服务 + 两个独立的终端窗口（前端 Next.js + 后端 FastAPI）
 - **路径**: .cursor/skills/project-launcher/SKILL.md
- **备注**: 项目专属 Skill；Ollama 必须先于后端启动（Mem0 embedding 依赖）；前后端窗口必须可见
+- **备注**: 项目专属 Skill；启动前必须先读取 `.cursor/local-env.json` 获取 nodejs_path 和 shell；Ollama 必须先于后端启动（Mem0 embedding 依赖）；前后端窗口必须可见
--- a/.cursor/skills/problem-distillery/SKILL.md
+++ b/.cursor/skills/problem-distillery/SKILL.md
@@ -0,0 +1,232 @@
+---
+name: problem-distillery
+description: >-
+  从顽固问题中蒸馏方法论的渐进式知识系统。追踪反复出现且未被彻底解决的问题，
+  记录解决过程和弯路，定期提炼精炼认知，经实践验证后自动升级为常规注入。
+  当用户表达"还有问题"、"没解决"、"还是一样"、"又出现了"等语义，
+  或 Agent 自身意识到同一问题已尝试 2 次以上仍未解决时触发。
+---
+
+# Problem Distillery
+
+从反复出现的顽固问题中，经过"追踪 → 解决 → 蒸馏 → 验证 → 注入"的完整生命周期，
+蒸馏出经过实践验证的精炼认知和方法论。
+
+与其他系统的区别：
+- **pitfall-journal**：互补。pitfall 是事后快照（debug 完记一笔），distillery 是过程追踪 + 知识提炼
+- **dev-changelog**：不重叠。changelog 记事实改动，distillery 记问题解决过程和认知沉淀
+
+## 数据文件
+
+```
+.cursor/distillery/
+  problems.md        -- 问题记录（open + resolved），操作 A/B 写入
+  insights.md        -- 蒸馏后的精炼方法论，操作 C 写入
+  golden-rules.md    -- 权重达标后升级的条目，操作 D 管理，新会话自动注入
+```
+
+## 条目格式
+
+### problems.md 条目
+
+```markdown
+### [PD-YYYYMMDD-HHMM] 一句话标题
+- **status**: open | resolved
+- **fingerprint**: 关键特征词列表（用于匹配同一问题）
+- **category**: tech | workflow | decision | other
+- **first_seen**: YYYY-MM-DD HH:MM
+- **attempts**:
+  1. [YYYY-MM-DD HH:MM] 尝试了什么 → 结果如何
+  2. [YYYY-MM-DD HH:MM] 又尝试了什么 → 结果如何
+- **resolution**: （解决后填写）最终解决方案
+- **dead_ends**: （解决后填写）走过的弯路及其失败原因
+- **spark**: （解决后填写）一句话启发——这个问题教会了什么
+- **distilled**: （蒸馏后填写）IN-xxx
+```
+
+### insights.md 条目
+
+```markdown
+### [IN-YYYYMMDD-NN] 一句话方法论
+- **source_problems**: [PD-xxx, PD-yyy]
+- **weight**: 0
+- **promoted**: false | true | demoted
+- **content**: 2-3 句精炼认知
+```
+
+文件尾部保留元数据：
+
+```markdown
+---
+last_distill_date: YYYY-MM-DD
+```
+
+### golden-rules.md
+
+```markdown
+# Golden Rules
+
+经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
+
+1. [GR-001] 一句话认知（来源: IN-xxx, 累计验证 N 次）
+2. [GR-002] ...
+```
+
+硬上限 15 条。超出时按权重排序保留 top-15，被淘汰的条目降回 insights.md（promoted 改为 demoted）。
+
+## 操作 A：追踪记录（问题进行中）
+
+### 触发条件
+
+以下**任一**场景触发：
+
+1. **用户明确表达**问题未解决：
+   - "还有问题"、"问题没有解决"、"还是一样"、"又出现了"
+   - "试了好多次了"、"这个问题反复出现"、"不行"、"没用"
+   - 以及其他表达"问题反复发生、Agent 没有完全解决"的语义
+2. **Agent 自身意识到**同一问题已经尝试了 2 次以上仍未解决
+
+### 适用范围
+
+不限于技术问题——工作流设计、产品决策等各类反复纠结的问题均适用。
+
+### 流程
+
+```
+1. 提取当前问题的指纹：
+   - 技术问题：错误信息关键词、涉及文件/模块、症状描述
+   - 非技术问题：核心矛盾点、涉及领域、反复出现的决策困境
+
+2. 读取 problems.md，用指纹匹配 status=open 的条目
+
+3. 匹配到已有条目 → 在 attempts 中追加本次尝试记录
+
+4. 无匹配 → 创建新条目：
+   - 生成 ID：PD-YYYYMMDD-HHMM
+   - status: open
+   - 记录首次尝试
+
+5. 告知用户："已开始追踪这个问题 [PD-xxx]"（首次）
+   或 "已更新追踪记录 [PD-xxx]，这是第 N 次尝试"（后续）
+```
+
+### 与 pitfall-journal 的衔接
+
+当 pitfall-journal 中某个条目的同一问题反复出现（用户再次报告相同症状），
+Agent 应意识到这已超出 pitfall 的"一次性记录"范畴，主动触发操作 A 建立追踪。
+
+## 操作 B：解决记录
+
+### 触发条件
+
+存在 status=open 的追踪条目，且满足以下**任一**：
+- 用户确认问题已解决："好了"、"解决了"、"终于可以了"
+- Agent 判断问题已解决（测试通过、错误消失等）
+
+### 流程
+
+```
+1. 填写 resolution：最终的解决方案
+2. 填写 dead_ends：走过的弯路及其失败原因（从 attempts 中归纳）
+3. 填写 spark：一句话启发——这个问题教会了什么
+4. status 改为 resolved
+5. 回复末尾附 [顽固问题已解决并记录]
+```
+
+### 注意
+
+- 如果问题在当前会话中从发现到解决只花了 1-2 次尝试，不需要走 distillery 流程
+  （那是 pitfall-journal 的范畴）
+- 只有经历了"反复尝试"的问题才值得 distillery 追踪
+
+## 操作 C：定期蒸馏
+
+### 触发条件
+
+由 `distillery-recall` Rule 在每次会话开头检查：
+- 读取 insights.md 尾部的 `last_distill_date`
+- 如果距今超过 7 天，且 problems.md 中有未标记 `distilled` 的 resolved 条目
+- 则提醒用户："你有 N 个已解决的顽固问题尚未总结，要花几分钟蒸馏一下吗？"
+- 每次会话最多提醒一次
+
+### 流程（用户同意后）
+
+```
+1. 读取所有 status=resolved 且无 distilled 标记的条目
+2. Agent 分析这些问题的共性，提出归纳建议：
+   - 哪些问题有共同的根因模式？
+   - 能提炼出什么通用的认知或方法论？
+   - 建议的表述（2-3 句精炼认知）
+3. 用户确认/修改后：
+   - 写入 insights.md（ID 格式：IN-YYYYMMDD-NN，NN 为当日序号）
+   - weight 初始为 0
+   - promoted: false
+4. 更新 insights.md 尾部的 last_distill_date
+5. 在对应 problems.md 条目上标记 distilled: IN-xxx
+```
+
+## 操作 D：验证与升级
+
+### 被动验证
+
+当操作 A 触发时（遇到新的或再次出现的顽固问题），额外执行：
+
+```
+1. 读取 insights.md，对当前问题做语义匹配
+2. 如有相关条目，向用户展示：
+   "之前总结过一条相关经验 [IN-xxx]: [内容摘要]，可能对当前问题有帮助。"
+3. 在问题解决流程中，跟踪该经验是否发挥了作用：
+   - 用户确认"这个提示有用"
+   - 或 Agent 判断解决方案与该 insight 的方向一致
+4. 确认有用 → weight += 1，在 insights.md 中更新
+5. 确认无用 → 不扣分（weight 只增不减，避免偶然失误惩罚好经验）
+```
+
+### 升级为 Golden Rule
+
+```
+1. 当某条 insight 的 weight >= 5：
+   a. 检查 golden-rules.md 当前条目数
+   b. 如 < 15 → 直接升级：
+      - 在 golden-rules.md 中追加条目（ID: GR-NNN，NNN 为递增序号）
+      - insights.md 中 promoted 改为 true
+   c. 如 = 15 → 比较权重：
+      - 新条目权重 > golden-rules.md 中最低权重条目 → 替换
+      - 被替换的条目降回 insights.md（promoted 改为 demoted）
+      - 否则不升级
+2. 升级后告知用户：
+   "经验 [IN-xxx] 已累计验证 N 次，升级为 Golden Rule [GR-NNN]，后续新会话将自动注入。"
+```
+
+### 新会话注入
+
+由 `distillery-recall` Rule 负责：
+- 每次会话开头读取 `golden-rules.md`
+- 如果非空，将全部条目作为背景知识注入上下文
+- 注入方式与 `changelog-headlines` 同级别——轻量、不显式提及来源
+
+## 容量与性能控制
+
+| 文件 | 策略 | 阈值 |
+|------|------|------|
+| problems.md | resolved 且已 distilled 的条目超过 50 条时，归档到 problems-archive.md | 50 条 |
+| insights.md | 无上限（条目本身是精炼的，每条 3-5 行） | — |
+| golden-rules.md | 硬上限，按权重淘汰 | 15 条 |
+| 新会话注入成本 | 只读 golden-rules.md（预期 < 30 行） | 极轻量 |
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `pitfall-journal` | 上游来源 | pitfall 条目反复出现时，升级为 distillery 追踪 |
+| `dev-changelog` | 不重叠 | changelog 记事实改动，distillery 记过程和认知 |
+| `distillery-recall` Rule | 下游消费者 | 负责 golden-rules 注入和蒸馏提醒 |
+| `epee-orchestrator` | 注册 | 在 registry.md 中注册本 Skill |
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+（暂无）
--- 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。