huhaa-myskills 0.3.5 → 0.3.6

package/README.md

@@ -16,3 +16,82 @@
 ---
 
 **快速开始**：见 docs/Frontend-Spec.md §VI 「快速启动指南」
+
+## 🔑 关键技术决策
+
+### 后端设计
+- **API 端点**: `/api/other-skills`（列表）、`/api/icons/:brand`（真实图标）
+- **扫描器**: 通用 `skill-adapter.mjs`，支持任意 SKILL.md 位置
+- **文件匹配**: `**/SKILL.md` glob 递归扫描，目录名大小写不敏感、文件名大小写敏感
+- **图标**: macOS 内置命令（`mdfind`/`plutil`/`sips`）提取，无 Swift 依赖；非 macOS 自动降级 emoji
+
+### 前端设计
+- **数据获取**: Hook 模式（`useOtherSkills`），支持搜索/排序/分组
+- **图标展示**: `SkillIcon` 组件，真实图标优先、emoji 兜底
+- **UI 布局**: 响应式双列（list + detail）
+- **错误处理**: 自定义 `OtherSkillsError` 类
+
+### 数据流
+```
+SKILL.md 文件 (160+)
+    ↓
+skill-adapter.mjs (扫描 + frontmatter 解析 + icon 字段)
+    ↓
+/api/other-skills (注入 iconUrl/iconFallback)  ──►  /api/icons/:brand (按需提取真实图标 PNG + 缓存)
+    ↓
+useOtherSkills Hook (搜索、过滤、排序、分组)
+    ↓
+OtherSkillsView + SkillIcon (真实图标 / emoji 降级)
+```
+
+---
+
+## 🚀 快速开始
+
+### 开发模式
+```bash
+cd /Users/mac/Project/HuHaa-MySkills
+
+# 启动后端服务（默认 11520，占用则自动切换）
+npm start
+
+# 前端开发（Vite）
+npm run dev
+
+# 点击菜单：其它技能 → 查看真实技能 + 真实工具图标
+```
+
+### 验证
+```bash
+# 列表数据（含 iconUrl 字段）
+curl -s "http://127.0.0.1:11520/api/other-skills?roots=~/.hermes/skills&fileGlob=**/SKILL.md" | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>console.log(JSON.parse(d).skills.length))"
+
+# 真实图标（Cursor / VS Code）
+curl -s -o /tmp/i.png "http://127.0.0.1:11520/api/icons/cursor?size=64" && file /tmp/i.png
+
+# 后端测试
+npm test          # 12/12
+npm run typecheck:web
+```
+
+---
+
+## 📊 版本历史
+
+| 版本 | 日期 | 主要功能 | 状态 |
+|------|------|--------|------|
+| v0.3.2 | - | 基础架构 | ✅ |
+| v0.3.3 | 2026-06-30 | Dashboard + Skills Sources | ✅ |
+| v0.3.4 | 2026-07-01 | Other Skills（真实数据） | ✅ |
+| v0.3.5 | 2026-07-01 | 真实图标(R6) + 扫描性能(R7) · 规则 v3.0 | ✅ 已实现，待发布 |
+| 待定 | - | 桌面模式 / 功能扩展 | 📋 规划中 |
+
+---
+
+## 🔍 项目规范
+
+所有开发须遵循：
+- **CLAUDE.md** — AI 协作规则（全中文、strict mode）
+- **docs/Frontend-Engineering.md** — 技术栈和编码规范
+- **根目录整洁** — 仅保留 README.md、CLAUDE.md、package.json 等核心文件
+- **计划文档** — 统一放 `.hermes/plans/`

package/bin/lib/paths.mjs

@@ -25,6 +25,11 @@ export function cacheFile() {
   return path.join(homeDir(), 'cache.json');
 }
 
+// 翻译结果持久化缓存（md5 key → 译文）。purge 删除整个 homeDir 时随之清理。
+export function translateCacheFile() {
+  return path.join(homeDir(), 'translate-cache.json');
+}
+
 export function stateFile() {
   return path.join(homeDir(), 'state.json');
 }

package/build/verify.mjs

@@ -10,7 +10,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, '..');
 const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'huhaa-verify-'));
 const oldHome = process.env.HUHAA_HOME;
+const oldUserHome = process.env.HOME;
 process.env.HUHAA_HOME = path.join(tempRoot, 'home');
+process.env.HOME = process.env.HUHAA_HOME;
 
 const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
 const testFiles = [
@@ -40,7 +42,7 @@ async function main() {
     run('npm', ['run', 'test:web']);
     run('node', ['--test', ...testFiles]);
 
-    const skillRoot = path.join(tempRoot, 'skills');
+    const skillRoot = path.join(process.env.HOME, '.hermes', 'skills');
     write(path.join(skillRoot, 'demo', 'verify-skill', 'SKILL.md'), `---
 name: verify-skill
 description: Verify smoke skill
@@ -83,7 +85,7 @@ limits:
 
       const stats = await fetchJson(`${base}/api/stats`);
       assert.equal(stats.total, 1);
-      assert.equal(stats.bySource.hermes, 1);
+      assert.equal(stats.byBrand.hermes, 1);
 
       const reload = await fetchJson(`${base}/api/reload`, { method: 'POST' });
       assert.equal(reload.ok, true);
@@ -111,6 +113,8 @@ limits:
   } finally {
     if (oldHome == null) delete process.env.HUHAA_HOME;
     else process.env.HUHAA_HOME = oldHome;
+    if (oldUserHome == null) delete process.env.HOME;
+    else process.env.HOME = oldUserHome;
     fs.rmSync(tempRoot, { recursive: true, force: true });
   }
 }

package/docs/Frontend-Spec.md

@@ -602,8 +602,19 @@ localStorage.setItem('theme', next)
 | 三区布局类（sidebar/topbar/detail/main-pane） | `packages/web/src/index.css`（`@layer components`） |
 | 主题切换 | `packages/web/src/hooks/useTheme.ts` |
 | editor 色映射 | `packages/web/src/lib/editors.ts` |
+| 官方品牌图标（Skill + Command） | `packages/scanner/src/icon/icon-extractor.mjs` + `packages/scanner/src/icon/brand-map.mjs`（后端 `/api/icons/:brand`） |
+| 前端官方图标组件 | `packages/web/src/components/ui/OfficialBrandIcon.tsx` |
 | verify 断言约束 | `build/verify.mjs`（`#app`；CSS 子串 OR 含 `topbar`/`sidebar`/`detail` 任一） |
 
+### 官方品牌 icon 资源策略
+
+Skill 与 Command 模块统一通过 `/api/icons/:brand` 读取官方 icon，前端不再打包自制品牌 SVG，也不使用 emoji / lucide 品牌图标伪装官方 icon：
+
+1. **本机官方 `.app` 图标优先**：后端按 `brand-map.mjs` 中的 Bundle ID / App 名称扫描并提取系统应用图标。
+2. **官方远程 URL 兜底**：本机无图标时，仅从 `brand-map.mjs` 登记的 HTTPS 官方 URL 下载；结果缓存到 `~/.config/huhaa-myskills/icon-cache/`。
+3. **中性占位**：没有本机图标且没有可确认官方远程 URL（如 `hermes` / `gstack`）时，前端显示中性占位。
+4. **禁用联网**：`HUHAA_ICON_REMOTE=0` 时不触发远程下载，但仍可读取已有本地缓存。
+
 ---
 
 # 三、框架说明

package/docs/scan_skills_rules.md

@@ -0,0 +1,381 @@
+# 技能扫描规则（Scan Rules）
+
+> 本文档定义 HuHaa-MySkills 的技能扫描规范，是稳定的工程规则，供扫描器（`packages/scanner`）与服务端（`packages/server`）遵循。
+> 版本：v4.0 · 上次更新：2026-07-02
+
+设计参考开源项目 **Pearcleaner**（macOS 清理工具，Swift/SwiftUI）的「软件扫描逻辑」与「图标获取展示」，在 Node.js + Fastify + React 架构下等价落地。
+
+---
+
+## R0 扫描优先级策略 ⭐⭐⭐
+
+扫描器按以下**三层优先级**递进扫描技能。优先级高的层级命中的技能路径不能与低优先级层级重复，使用 MD5 哈希值标记技能路径实现去重。
+
+### 第1层：编辑器工具全局和项目目录（最高优先级）
+
+定位以下20+编辑器工具的技能/工作流目录，按以下优先级尝试：
+
+#### 编辑器工具清单
+
+| 排序 | 编辑器工具 | 全局路径 | 项目路径 | 品牌标识 |
+|------|-----------|--------|--------|---------|
+| 1 | **Hermes** | `~/.hermes/skills` | `.hermes/skills` | `hermes` |
+| 2 | **Claude** | `~/.claude/skills` | `.claude/skills` | `claude` |
+| 3 | **Cursor** | `~/.cursor/skills` | `.cursor/skills` | `cursor` |
+| 4 | **VSCode** | `~/.vscode/skills` | `.vscode/skills` | `vscode` |
+| 5 | **Codeium** | `~/.codeium/skills` | `.codeium/skills` | `codeium` |
+| 6 | **Windsurf** | `~/.windsurf/skills` | `.windsurf/skills` | `windsurf` |
+| 7 | **Continue** | `~/.continue/skills` | `.continue/skills` | `continue` |
+| 8 | **Tauri** | `~/.tauri/skills` | `.tauri/skills` | `tauri` |
+| 9 | **Trae** | `~/.trae/skills` | `.trae/skills` | `trae` |
+| 10 | **Trae-CN** | `~/.trae-cn/skills` | `.trae-cn/skills` | `trae-cn` |
+| 11 | **QoDer** | `~/.qoder/skills` | `.qoder/skills` | `qoder` |
+| 12 | **Codex** | `~/.codex/skills` | `.codex/skills` | `codex` |
+| 13 | **Vim** | `~/.vim/skills` | `.vim/skills` | `vim` |
+| 14 | **Neovim** | `~/.config/nvim/skills` | `.nvim/skills` | `neovim` |
+| 15 | **Emacs** | `~/.emacs.d/skills` | `.emacs.d/skills` | `emacs` |
+| 16 | **Sublime** | `~/.config/sublime-text/skills` | `.sublime-text/skills` | `sublime` |
+| 17 | **Jetbrains IDE** | `~/.config/JetBrains/skills` | `.jetbrains/skills` | `jetbrains` |
+| 18 | **Nova** | `~/.nova/skills` | `.nova/skills` | `nova` |
+| 19 | **Zed** | `~/.config/zed/skills` | `.zed/skills` | `zed` |
+| 20 | **GitHub Copilot** | `~/.copilot/skills` | `.copilot/skills` | `copilot` |
+| 21 | **Replit** | `~/.replit/skills` | `.replit/skills` | `replit` |
+| 22 | **Glot.io** | `~/.glot/skills` | `.glot/skills` | `glot` |
+
+**扫描规则**：
+- 递归匹配 `**/SKILL.md` 或 `**/skill.md`（文件名**不区分大小写**）
+- 目录名称：所有变体允许（`skills` / `Skills` / `SKILLS` 等，**不区分大小写**）
+- **路径去重**：计算每个扫描到的 SKILL.md 的绝对路径 MD5 哈希值，存储在扫描结果中作为 `pathHash`
+
+### 第2层：用户根目录技能库（中等优先级）
+
+定位用户 HOME 目录下的技能库：
+
+- 目录路径：`~/skills` 或任意大小写变体（`~/SKILLS` / `~/Skills` 等）
+- **扫描规则**：递归匹配 `**/SKILL.md` 或 `**/skill.md`（文件名**不区分大小写**）
+- **路径去重**：同样计算 MD5 哈希值，与第1层的 `pathHash` 集合对比，**如果已存在则跳过该技能**
+
+### 第3层：其他所有位置（最低优先级）⭐
+
+扫描范围外或通配位置，仅在开启专项扫描时激活：
+
+- **扫描规则**：**仅** 递归匹配 `**/skill.md`（小写，**精确大小写敏感**）
+- **路径去重**：计算 MD5 哈希值，与第1、2层的 `pathHash` 集合对比，**如果已存在则跳过该技能**
+- **扫描范围**（可配置，默认仅包括标准系统路径）：
+  - `/opt/` 及其子目录（自定义软件安装位置）
+  - `/usr/local/` 及其子目录
+  - `~/opt/` 及其子目录
+  - 其他用户指定的自定义扫描路径
+
+**激活条件**：
+- 通过配置文件或 API 参数 `scanTier3=true` 显式启用
+- 默认不扫描第3层，仅返回第1、2层结果
+
+---
+
+## R1 扫描根目录
+
+- 支持多个技能根目录：`roots: string[]`，由 R0 的三层优先级策略动态生成。
+- `~` 展开为 `$HOME`。
+- 每个 root 必须存在，否则返回 400。
+- glob 返回精确且无重复的文件列表。
+
+---
+
+## R2 目录和文件名大小写规则 ⭐
+
+### 目录名称（所有层级都不敏感）
+
+- 技能目录可能命名为 `skills` / `Skills` / `SKILLS` / `sKiLLs`，扫描器接受所有变体。
+- 按存在性和优先级返回第一个匹配的目录。
+
+### 文件名规则（按层级区分）
+
+- **第1层（编辑器工具）& 第2层（用户根目录）**：`SKILL.md` 或 `skill.md` 均匹配（**不区分大小写**）
+- **第3层（其他）**：仅匹配 `skill.md`（小写，**精确大小写敏感**）
+
+---
+
+## R3 文件匹配与递归扫描
+
+- 使用 `fast-glob` 递归匹配对应层级的文件名规则（见 R2）。
+- 每个文件仅读取一次；多个 root 命中同一文件时按 `filePath` 去重。
+- 扫描采用分块并发（见 R7），但返回列表按路径字典序稳定排序，保证幂等。
+
+---
+
+## R4 Frontmatter 解析
+
+- frontmatter 必须以 `---` 开始和结束；YAML 无效时返回 400。
+- `name` / `description` 必填，缺失时返回 400。
+- 其余字段缺失时用默认值或 null。
+
+支持字段：
+
+```yaml
+---
+name: string              # 必须
+description: string       # 必填
+category?: string
+brand?: string            # 图标解析主要依据（如 cursor / vs-code / claude-code）
+source?: string           # 图标解析次要依据
+tier?: 'tool' | 'directory' | 'other'
+tags?: string[]
+icon?: string             # 可选：显式指定图标，优先级最高
+                          #   - "app:com.todesktop.230313mzl4w4u92"（指定 Bundle ID）
+                          #   - "emoji:🤖"（强制 emoji）
+                          #   - "url:https://..."（远程/本地图标）
+---
+```
+
+---
+
+## R5 返回数据格式
+
+```typescript
+SkillItem {
+  id, name, description, filePath,
+  pathHash,          // MD5(filePath)，用于去重和菜单分层显示
+  tier,              // 'tier-1' | 'tier-2' | 'tier-3'，标记所属层级
+  category?, brand?, tier?, tags?,
+  iconUrl?,          // 真实图标端点，如 "/api/icons/cursor?size=64"；无真实图标时为空
+  iconFallback?,     // emoji 兜底值，如 "🤖"
+  createdAt?, updatedAt?
+}
+
+ScanResult {
+  skills,            // 按 tier 分组的技能列表
+  total, limit, offset, roots, scannedAt, duration,
+  pathHashes,        // 已扫描的所有 pathHash 集合，用于去重检测
+  tier1Count, tier2Count, tier3Count  // 各层级技能数量统计
+}
+```
+
+排序：按 tier（1 → 2 → 3）优先，同 tier 内按 category 分组后按 name 字典序。
+
+---
+
+## R6 真实工具/编辑器图标获取 ⭐
+
+技能列表展示其所属工具/编辑器的**真实应用图标**，对标 Pearcleaner 的 `AppInfoUtils.fetchAppIcon(...)`。
+
+### R6.1 品牌 → 应用映射表
+
+维护 `brand/source → 候选 Bundle ID + 候选应用名` 的映射表（`packages/scanner/src/icon/brand-map.mjs`），包含 R0 列出的所有22个编辑器工具品牌。无对应 GUI 应用的品牌（如 `hermes`、`mcp`）按 R6.5 回退 emoji。
+
+### R6.2 应用定位
+
+按优先级定位 `.app`：
+
+1. **Bundle ID 精确定位**（最快最准）：`mdfind "kMDItemCFBundleIdentifier == '<bundleId>'"`
+2. **应用名扫描**：遍历 `/Applications`、`~/Applications`、`/System/Applications`，`.app` 目录名大小写不敏感匹配
+3. 命中多个时取修改时间最新者
+
+### R6.3 图标提取（Node.js 等价 `NSWorkspace.icon(forFile:)`）
+
+对定位到的 `<App>.app`：
+
+1. 读 `Contents/Info.plist` 的 `CFBundleIconFile`（`plutil -extract CFBundleIconFile raw`）
+2. 拼出 `Contents/Resources/<IconFile>.icns`（缺省兜底：目录下首个 `.icns`，优先含 `icon` 的文件）
+3. 用系统内置 `sips` 转 PNG：
+   ```bash
+   sips -s format png -Z 64 "<icns>" --out "<cachePng>"
+   ```
+   支持尺寸 `32 / 64 / 128` 三档。
+
+### R6.4 图标缓存
+
+- 缓存目录：`~/.config/huhaa-myskills/icon-cache/`（受 `HUHAA_HOME` / `XDG_CONFIG_HOME` 影响）
+- 文件名：`{appSlug}-{size}.png`
+- **失效策略**：源 `.app` 的 mtime 新于缓存 PNG 时重建
+- 进程内维护 `brand → appPath` / `brand:size → pngPath` 内存索引，避免重复 `sips`
+
+### R6.5 图标优先级与降级链
+
+```
+1. frontmatter.icon 显式指定（app:/emoji:/url:）  —— 最高优先级
+2. 真实应用图标（R6.1–R6.4 成功）
+3. emoji 映射表（BRAND_ICONS / CATEGORY_ICONS）    —— 兜底降级
+4. 通用占位图标                                     —— 最终兜底
+```
+
+找不到 app 时静默降级，不报错。
+
+### R6.6 图标服务 API
+
+```
+GET /api/icons/:brand?size=64
+  → 200 image/png   （命中真实图标，cache-control: public, max-age=86400）
+  → 404 JSON { ok:false, fallback:true, brand }   （无对应 app，前端回退 emoji）
+```
+
+`size` 会被 clamp 到 `[32, 128]`，非法值回退 64。
+
+---
+
+## R7 左侧菜单栏分层显示 ⭐⭐⭐
+
+技能在左侧菜单栏中按 tier 分组显示，每个分组有独立的 icon 和分类标签。
+
+### R7.1 菜单栏分组结构
+
+前端左侧菜单栏采用**二级导航**结构：
+
+```
+左侧菜单栏
+│
+├─ 📦 编辑器工具技能（Tier 1）
+│  ├─ Hermes
+│  ├─ Claude
+│  ├─ Cursor
+│  └─ ... (其他编辑器工具)
+│
+├─ 👤 我的技能库（Tier 2）
+│  ├─ skill-1
+│  ├─ skill-2
+│  └─ ...
+│
+└─ 🔍 其他技能（Tier 3）← 仅在 scanTier3=true 时显示
+   ├─ skill-x
+   ├─ skill-y
+   └─ ...
+```
+
+### R7.2 分组 Icon 设计
+
+| 分组 | 显示名称 | 建议 Icon | 说明 |
+|-----|---------|---------|------|
+| **Tier 1** | 编辑器工具技能 | `📦` 或 `⚙️` | 代表工具集合、生态环境 |
+| **Tier 2** | 我的技能库 | `👤` 或 `⭐` | 代表个人、用户私有 |
+| **Tier 3** | 其他技能 | `🔍` 或 `🌐` | 代表外部、探索发现 |
+
+**优先选择**：使用 emoji（跨平台一致），或从设计系统中选择对应的 SVG icon。
+
+### R7.3 展开/折叠行为
+
+- **Tier 1 和 Tier 2**：默认展开（因为用户常用）
+- **Tier 3**：默认折叠（降低视觉噪音，仅在需要时展开）
+- 用户可手动点击分组 header 切换展开/折叠状态
+- 展开/折叠状态持久化到本地存储（localStorage）
+
+### R7.4 Tier 1 内部结构
+
+Tier 1（编辑器工具技能）在菜单栏中进一步按**编辑器品牌分组**：
+
+```
+编辑器工具技能（Tier 1）
+├─ 🔷 Hermes
+│  ├─ skill-1
+│  └─ skill-2
+├─ 🔹 Claude
+│  ├─ skill-3
+│  └─ skill-4
+├─ 🔶 Cursor
+│  └─ skill-5
+└─ ... (其他编辑器)
+```
+
+每个编辑器品牌使用 **R6 获取的真实应用 icon**（如 Cursor 的真实图标、VS Code 的真实图标）。
+
+### R7.5 技能计数 Badge
+
+菜单栏分组 header 显示该分组的技能计数：
+
+```
+编辑器工具技能（📦 125）
+我的技能库（👤 42）
+其他技能（🔍 18）
+```
+
+动态更新，基于 `ScanResult` 的 `tier1Count / tier2Count / tier3Count`。
+
+---
+
+## R8 扫描性能优化 ⭐
+
+对标 Pearcleaner 的「并发扫描 + 两阶段加载 + Spotlight 元数据」。
+
+### R8.1 两阶段加载
+
+- **阶段 1（mini，快）**：返回轻量行（`id / name / description / category / brand / tier / iconUrl / iconFallback`），前端立即渲染列表。
+- **阶段 2（full，补全）**：后台补齐 `tags / links / preview / frontmatter 全字段 / 时间戳 / pathHash`，前端合并升级。
+
+服务端通过 `stage=mini|full` 区分；前端先取 mini 快速渲染，再后台取 full 升级。图标 `<img loading="lazy">` 惰性加载。
+
+### R8.2 并发分块扫描
+
+- `fast-glob` 拿到文件列表后，用有界并发池（默认 = CPU 核数，范围 `[4, 16]`）并发解析。
+- 每个 worker 顺序读文件、解析 frontmatter，避免一次性打开过多文件句柄。
+- 结果合并后按路径字典序排序（保证 R3 幂等）。
+
+### R8.3 Spotlight 元数据（可选）
+
+- 文件时间戳优先用 `mdls -name kMDItemFSCreationDate -name kMDItemFSContentChangeDate`（批量，每批 50）。
+- Spotlight 不可用时回退 `fs.stat` 的 mtime。
+- 默认关闭，通过 `useSpotlight=1` 开启，失败静默回退。
+
+---
+
+## R9 路径去重算法 ⭐⭐
+
+确保第2、3层的技能不与第1层重复，防止同一技能在多个层级中出现。
+
+### R9.1 MD5 哈希计算
+
+```javascript
+// 伪代码
+const crypto = require('crypto');
+
+function getPathHash(absolutePath) {
+  // 规范化路径：展开 ~ 为 $HOME，统一为绝对路径，规范化 / 符号
+  const normalized = path.resolve(path.expanduser(absolutePath));
+  // 计算 MD5 哈希
+  const hash = crypto.createHash('md5').update(normalized).digest('hex');
+  return hash;
+}
+```
+
+### R9.2 去重流程
+
+```
+Step 1: 扫描第1层（编辑器工具）
+  → 收集所有 pathHash，存入集合 tier1Hashes
+  → 返回所有第1层技能
+
+Step 2: 扫描第2层（用户根目录）
+  → 对每个扫描到的技能，计算 pathHash
+  → 如果 pathHash ∈ tier1Hashes，则跳过（已在第1层存在）
+  → 否则，加入 tier2Hashes，返回该技能
+
+Step 3: 扫描第3层（其他，仅当 scanTier3=true）
+  → 对每个扫描到的技能，计算 pathHash
+  → 如果 pathHash ∈ (tier1Hashes ∪ tier2Hashes)，则跳过
+  → 否则，返回该技能
+
+Return: [tier1Skills, tier2Skills, tier3Skills] + { tier1Hashes, tier2Hashes }
+```
+
+### R9.3 缓存策略
+
+- 扫描结果中包含 `pathHashes: { tier1: Set<string>, tier2: Set<string> }`，方便前端或后续请求快速判断。
+- 内存中维护 LRU 缓存（最多 1000 条），避免重复计算同一路径的哈希值。
+
+---
+
+## 系统依赖与兼容性
+
+- 依赖 macOS 内置命令：`sips` / `mdfind` / `plutil` / `mdls`（均无需额外安装）。
+- 非 macOS 环境：图标提取直接按 R6.5 降级为 emoji，扫描功能不受影响。
+- `iconUrl` / `iconFallback` 为可选字段，旧客户端不受影响；无真实图标时行为等同 emoji 模式。
+
+---
+
+## 附录：v3.0 规则原文（存档）
+
+改版前 v3.0 的 R1–R5 定义，语义已升级为 v4.0：
+
+- **R1 扫描根目录**：支持多个技能根目录，`~` 展开为 `$HOME`，每个 root 必须存在（否则 400），glob 返回精确且无重复的文件列表。
+- **R2 目录名称大小写不敏感**：`Skills` / `SKILLS` / `skills` / `sKiLLs` 均可匹配，按优先级返回第一个存在的目录；文件名 `SKILL.md` 大小写敏感。
+- **R3 文件匹配与递归扫描**：`fast-glob` 递归匹配 `**/SKILL.md`，每个文件仅读一次，返回按路径字典序排序。
+- **R4 Frontmatter 解析**：frontmatter 以 `---` 开始和结束；YAML 无效时 400；`name`/`description` 必填。
+- **R5 返回数据格式**：`SkillItem { id, name, description, filePath, category?, brand?, tier?, tags?, createdAt?, updatedAt? }`；`ScanResult { skills, total, limit, offset, roots, scannedAt, duration }`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huhaa-myskills",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "private": false,
   "description": "Local skill / plugin / MCP aggregation hub. Browse all your AI agent skills at http://localhost:11520.",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "init": "node bin/huhaa-myskills.mjs init",
     "purge": "node bin/huhaa-myskills.mjs purge",
     "uninstall": "node bin/huhaa-myskills.mjs uninstall",
-    "dev": "node bin/huhaa-myskills.mjs start && cd packages/web && npm run dev",
+    "dev": "node bin/huhaa-myskills.mjs restart && cd packages/web && npm run dev",
     "dev-bg": "bash scripts/start-dev.sh",
     "sync": "node bin/huhaa-myskills.mjs sync",
     "build:web": "node build/build-web.mjs",

package/packages/scanner/src/adapters/scan-tier.mjs

@@ -0,0 +1,99 @@
+/**
+ * @file scan-tier.mjs
+ * v4.0 三层优先级扫描器
+ * 集成 Tier 1（编辑器工具）+ Tier 2（用户根目录）+ Tier 3（其他）
+ */
+
+import { scanTier1EditorSkills } from './tier1-editor-skills.mjs';
+import { scanTier2UserSkills } from './tier2-user-skills.mjs';
+import { scanTier3OtherSkills } from './tier3-other-skills.mjs';
+import { pathHashCache } from '../hash/path-hash.mjs';
+
+/**
+ * 三层优先级扫描
+ *
+ * @param {Object} options
+ * @param {boolean} [options.scanTier1=true] - 是否扫描第1层（编辑器工具）
+ * @param {boolean} [options.scanTier2=true] - 是否扫描第2层（用户根目录）
+ * @param {boolean} [options.scanTier3=false] - 是否扫描第3层（其他位置）
+ * @param {string} [options.projectRoot] - 项目根目录（用于扫描 .hermes/skills 等）
+ * @param {Object} [options.limits] - { maxFiles, maxFileBytes }
+ * @returns {Promise<{items: SkillItem[], stats: Object}>}
+ */
+export async function scanTierSkills(options = {}) {
+  const { 
+    scanTier1 = true,
+    scanTier2 = true, 
+    scanTier3 = false, 
+    projectRoot = process.cwd(), 
+    limits = {} 
+  } = options;
+
+  const mergedLimits = {
+    maxFiles: limits.maxFiles ?? 5000,
+    maxFileBytes: limits.maxFileBytes ?? 1024 * 1024,
+  };
+
+  // Step 1: 扫描第1层
+  console.log('[scan] Tier 1: scanning editor tools...');
+  const tier1Result = await scanTier1EditorSkills({ projectRoot, limits: mergedLimits });
+  const tier1Items = tier1Result.items;
+  const tier1PathHashes = tier1Result.pathHashes;
+  console.log(`[scan] Tier 1: found ${tier1Items.length} skills`);
+
+  // Step 2: 扫描第2层（排除第1层已有的）
+  console.log('[scan] Tier 2: scanning user skills library...');
+  const tier2Result = await scanTier2UserSkills({
+    tier1PathHashes,
+    limits: mergedLimits,
+  });
+  const tier2Items = tier2Result.items;
+  const tier2PathHashes = tier2Result.pathHashes;
+  console.log(`[scan] Tier 2: found ${tier2Items.length} skills`);
+
+  // Step 3: 扫描第3层（如果启用，排除第1、2层已有的）
+  let tier3Items = [];
+  if (scanTier3) {
+    console.log('[scan] Tier 3: scanning other locations...');
+    const tier3Result = await scanTier3OtherSkills({
+      tier1PathHashes,
+      tier2PathHashes,
+      limits: mergedLimits,
+    });
+    tier3Items = tier3Result.items;
+    console.log(`[scan] Tier 3: found ${tier3Items.length} skills`);
+  }
+
+  // 合并结果
+  const allItems = [...tier1Items, ...tier2Items, ...tier3Items];
+
+  // 按 tier → category → name 排序
+  allItems.sort((a, b) => {
+    const tierOrder = { 'tier-1': 0, 'tier-2': 1, 'tier-3': 2 };
+    const tierCmp = (tierOrder[a.tierId] ?? 99) - (tierOrder[b.tierId] ?? 99);
+    if (tierCmp !== 0) return tierCmp;
+
+    const catCmp = (a.category || '').localeCompare(b.category || '');
+    if (catCmp !== 0) return catCmp;
+
+    return a.name.localeCompare(b.name);
+  });
+
+  return {
+    items: allItems,
+    stats: {
+      tier1Count: tier1Items.length,
+      tier2Count: tier2Items.length,
+      tier3Count: tier3Items.length,
+      total: allItems.length,
+      pathHashes: {
+        tier1: Array.from(tier1PathHashes),
+        tier2: Array.from(tier2PathHashes),
+      },
+      cacheSize: pathHashCache.size,
+      scannedAt: new Date().toISOString(),
+    },
+  };
+}
+
+export { pathHashCache };