huhaa-myskills 0.3.5 → 0.3.7

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/huhaa-myskills.mjs

@@ -12,6 +12,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const REPO_ROOT = path.resolve(__dirname, '..');
 const PKGS_ROOT = path.join(REPO_ROOT, 'packages');
+const DISPLAY_NAME = 'HuHaa AI 助手';
 
 const require = createRequire(import.meta.url);
 
@@ -69,7 +70,7 @@ async function cmdVersion() {
 }
 
 async function cmdHelp() {
-  console.log(`huhaa-myskills v${VERSION} — local skill / plugin / MCP aggregation hub
+  console.log(`huhaa-myskills v${VERSION} — ${DISPLAY_NAME}：本地技能 / 插件 / MCP 聚合中心
 
 Usage:
   huhaa-myskills <command> [options]
@@ -96,6 +97,7 @@ Env:
   HUHAA_HOME      override user data dir (default: ~/.config/huhaa-myskills)
   PORT            override preferred port (default: 11520, falls back +10)
   HUHAA_SYNC      comma-separated list of editors to sync (e.g. "cursor,vscode")
+  HUHAA_NO_OPEN   set to 1/true/yes to skip opening the browser
 
 Paths:
   config   ${configFile()}
@@ -143,7 +145,7 @@ async function cmdStop() {
   }
   try {
     process.kill(state.pid, 'SIGTERM');
-    console.log(`✓ 已停止 HuHaa-MySkills (pid ${state.pid}, port ${state.port ?? '未知'})`);
+    console.log(`✓ 已停止 ${DISPLAY_NAME} (pid ${state.pid}, port ${state.port ?? '未知'})`);
   } catch (err) {
     console.error(`[stop] 停止失败: ${err.message}`);
     return false;
@@ -191,7 +193,7 @@ async function cmdUninstall() {
   const question = (q) => new Promise(resolve => rl.question(q, resolve));
 
   const dir = homeDir();
-  console.log('\n[uninstall] 即将卸载 HuHaa-MySkills，将执行以下操作：');
+  console.log(`\n[uninstall] 即将卸载 ${DISPLAY_NAME}，将执行以下操作：`);
   console.log('  1. 停止运行中的后台服务');
   console.log(`  2. 删除用户数据目录: ${dir}`);
   console.log('  3. 卸载全局 npm 包: huhaa-myskills');
@@ -275,7 +277,7 @@ async function cmdStats() {
 
   const sortDesc = (obj) => Object.entries(obj).sort((a, b) => b[1] - a[1]);
 
-  console.log(`\nHuHaa-MySkills scan stats`);
+  console.log(`\n${DISPLAY_NAME} scan stats`);
   console.log(`==========================`);
   console.log(`total items:        ${items.length}`);
   console.log(`parse errors:       ${errors.length}`);
@@ -341,7 +343,7 @@ async function cmdDuplicates() {
   const contentDups = [...byContent.entries()].filter(([k, arr]) => !k.endsWith(':00000000') && arr.length > 1);
   const pathDups = [...byAbs.entries()].filter(([k, arr]) => k && arr.length > 1);
 
-  console.log('\nHuHaa-MySkills duplicate diagnostics');
+  console.log(`\n${DISPLAY_NAME} duplicate diagnostics`);
   console.log('====================================');
   console.log(`total items:          ${items.length}`);
   console.log(`duplicate names:      ${nameDups.length} groups`);
@@ -393,7 +395,7 @@ async function cmdStart() {
       const stateData = JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
       if (stateData.pid && isProcessRunning(stateData.pid)) {
         const logFile = path.join(homeDir(), 'huhaa.log');
-        console.log(`✓ HuHaa-MySkills 已在运行: http://localhost:${stateData.port}`);
+        console.log(`✓ ${DISPLAY_NAME} 已在运行: http://localhost:${stateData.port}`);
         console.log(`📝 日志: ${logFile}`);
         return;
       }
@@ -428,7 +430,7 @@ async function startBackgroundServer(port, logFile, homeDirectory) {
   try {
     const stateData = JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
     if (stateData.pid && isProcessRunning(stateData.pid)) {
-      console.log(`✓ HuHaa-MySkills 已在运行: http://localhost:${stateData.port}`);
+      console.log(`✓ ${DISPLAY_NAME} 已在运行: http://localhost:${stateData.port}`);
       console.log(`📝 日志: ${logFile}`);
       return;
     }
@@ -449,15 +451,39 @@ async function startBackgroundServer(port, logFile, homeDirectory) {
     }
   });
 
+  let childExited = false;
+  let exitInfo = '';
+  child.once('exit', (code, signal) => {
+    childExited = true;
+    exitInfo = signal ? `signal ${signal}` : `exit ${code}`;
+  });
+  child.once('error', (err) => {
+    childExited = true;
+    exitInfo = err.message;
+  });
+
   child.unref();
 
-  // 等待子进程启动，检查端口是否开放
-  await new Promise(resolve => setTimeout(resolve, 1000));
+  const healthy = await waitForHealth(port, 10000, () => childExited);
 
-  // 关闭日志文件描述符（子进程已继承）
-  fs.closeSync(logFd);
+  try { fs.closeSync(logFd); } catch {}
 
-  console.log(`✓ HuHaa-MySkills 已在后台运行: http://localhost:${port}`);
+  if (!healthy) {
+    if (!childExited) {
+      try { process.kill(child.pid, 'SIGTERM'); } catch {}
+    }
+    try { fs.unlinkSync(stateFile()); } catch {}
+    const tail = readLogTail(logFile, 40);
+    console.error(`[start] ${DISPLAY_NAME} 后台启动失败${exitInfo ? `（${exitInfo}）` : ''}`);
+    console.error(`日志: ${logFile}`);
+    if (tail) {
+      console.error('\n最近日志:');
+      console.error(tail);
+    }
+    process.exit(1);
+  }
+
+  console.log(`✓ ${DISPLAY_NAME} 已在后台运行: http://localhost:${port}`);
   console.log(`📝 日志: ${logFile}`);
   console.log(`💡 查看日志: tail -f ${logFile}`);
   console.log(`💡 停止服务: huhaa-myskills stop`);
@@ -472,18 +498,56 @@ function isProcessRunning(pid) {
   }
 }
 
-async function runServer(port, logFile, homeDirectory) {
-  writeJson(stateFile(), { port, pid: process.pid, startedAt: new Date().toISOString() });
+async function waitForHealth(port, timeoutMs, shouldStop) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (shouldStop && shouldStop()) return false;
+    if (await fetchHealth(port)) return true;
+    await delay(250);
+  }
+  return false;
+}
 
+async function fetchHealth(port) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 500);
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: controller.signal });
+    if (!res.ok) return false;
+    const data = await res.json();
+    return data && data.ok === true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function readLogTail(file, lines = 40) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    return text.trimEnd().split(/\r?\n/).slice(-lines).join('\n');
+  } catch {
+    return '';
+  }
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function runServer(port, logFile, homeDirectory) {
   const { startServer } = await import(path.join(PKGS_ROOT, 'server/src/index.mjs'));
-  await startServer({ port });
+  const server = await startServer({ port });
+  const actualPort = server.port || port;
+  writeJson(stateFile(), { port: actualPort, pid: process.pid, startedAt: new Date().toISOString() });
 
-  console.log(`\n  HuHaa-MySkills 运行中:  http://localhost:${port}\n`);
+  console.log(`\n  ${DISPLAY_NAME} 运行中:  http://localhost:${actualPort}\n`);
   console.log(`  数据目录: ${homeDirectory}`);
   console.log(`  日志: ${logFile}`);
   console.log(`  按 Ctrl+C 停止。\n`);
 
-  openBrowser(`http://localhost:${port}`);
+  openBrowser(`http://localhost:${actualPort}`);
 
   const cleanup = () => {
     try { fs.unlinkSync(stateFile()); } catch {}
@@ -636,6 +700,8 @@ async function ensureConfigOrInit() {
 }
 
 function openBrowser(url) {
+  if (shouldSkipBrowserOpen()) return;
+
   const platform = process.platform;
   let cmd, args;
   if (platform === 'darwin') { cmd = 'open'; args = [url]; }
@@ -647,3 +713,8 @@ function openBrowser(url) {
     // best-effort; user can copy-paste the URL
   }
 }
+
+function shouldSkipBrowserOpen() {
+  const value = process.env.HUHAA_NO_OPEN;
+  return value === '1' || value?.toLowerCase() === 'true' || value?.toLowerCase() === 'yes';
+}

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/pack-smoke.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn, spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'huhaa-pack-smoke-'));
+const packDir = path.join(tempRoot, 'pack');
+const installRoot = path.join(tempRoot, 'install');
+const home = path.join(tempRoot, 'home');
+const childOutput = [];
+const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+
+fs.mkdirSync(packDir, { recursive: true });
+fs.mkdirSync(installRoot, { recursive: true });
+fs.mkdirSync(home, { recursive: true });
+
+function run(name, args, options = {}) {
+  console.log(`\n[pack-smoke] $ ${name} ${args.join(' ')}`);
+  const res = spawnSync(name, args, {
+    cwd: repoRoot,
+    stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    env: options.env || process.env,
+    encoding: 'utf8',
+  });
+  if (res.status !== 0) {
+    if (options.capture) {
+      process.stdout.write(res.stdout || '');
+      process.stderr.write(res.stderr || '');
+    }
+    throw new Error(`${name} ${args.join(' ')} failed with exit ${res.status}`);
+  }
+  return res;
+}
+
+function write(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+async function getFreePort() {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      server.close(() => resolve(address.port));
+    });
+  });
+}
+
+async function waitForHealth(base, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = '';
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${base}/api/health`);
+      const text = await res.text();
+      if (res.ok) {
+        const body = JSON.parse(text);
+        if (body.ok === true) return body;
+      }
+      lastError = `${res.status}: ${text}`;
+    } catch (err) {
+      lastError = err.message;
+    }
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  throw new Error(`health check timed out: ${lastError}`);
+}
+
+async function waitForChildClose(child) {
+  if (child.exitCode != null || child.signalCode != null) return;
+  await new Promise(resolve => {
+    const timer = setTimeout(resolve, 2000);
+    child.once('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+function assertTarballEntries(tarball) {
+  const res = run('tar', ['-tf', tarball], { capture: true });
+  const entries = res.stdout.trim().split(/\r?\n/).filter(Boolean);
+  assert.ok(entries.length > 0, 'tarball should not be empty');
+
+  const forbidden = entries.filter(entry =>
+    entry.includes('/node_modules/') ||
+    entry.includes('/.vite/') ||
+    entry.endsWith('/node_modules') ||
+    entry.endsWith('/.vite')
+  );
+  assert.deepEqual(forbidden, [], 'tarball must not contain node_modules or .vite cache');
+
+  for (const required of [
+    'package/packages/web/dist/index.html',
+    'package/packages/web/dist/favicon.ico',
+    'package/packages/web/dist/site.webmanifest',
+    'package/packages/web/public/favicon.ico',
+    'package/packages/server/src/index.mjs',
+    'package/packages/scanner/src/index.mjs',
+  ]) {
+    assert.ok(entries.includes(required), `tarball missing ${required}`);
+  }
+}
+
+async function assertInstalledCli(tarball) {
+  run('npm', ['install', '--prefix', installRoot, '--silent', '--omit=dev', tarball]);
+
+  const bin = path.join(installRoot, 'node_modules', '.bin', 'huhaa-myskills');
+  const version = run(bin, ['--version'], { capture: true });
+  assert.match(version.stdout, new RegExp(`^huhaa-myskills v${escapeRegExp(pkg.version)}`, 'm'));
+
+  write(path.join(home, '.hermes', 'skills', 'pack-smoke', 'SKILL.md'), `---
+name: pack-smoke
+description: Pack smoke skill
+---
+# Pack smoke skill
+`);
+  write(path.join(home, 'sources.yaml'), `limits:
+  maxFiles: 100
+  maxFileBytes: 1048576
+`);
+
+  const port = await getFreePort();
+  const base = `http://127.0.0.1:${port}`;
+  const env = {
+    ...process.env,
+    HOME: home,
+    HUHAA_HOME: home,
+    HUHAA_NO_OPEN: '1',
+    LOG_LEVEL: 'error',
+    PORT: String(port),
+  };
+  const child = spawn(bin, ['start', '--foreground'], {
+    cwd: installRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  child.stdout.on('data', data => childOutput.push(data.toString()));
+  child.stderr.on('data', data => childOutput.push(data.toString()));
+
+  try {
+    const health = await waitForHealth(base, 15000);
+    assert.equal(health.ok, true);
+    assert.equal(health.version, pkg.version);
+
+    const icon = await fetch(`${base}/favicon.ico`);
+    const bytes = Buffer.from(await icon.arrayBuffer());
+    assert.equal(icon.ok, true);
+    assert.equal((icon.headers.get('content-type') || '').split(';')[0], 'image/x-icon');
+    assert.deepEqual([...bytes.subarray(0, 4)], [0x00, 0x00, 0x01, 0x00]);
+  } catch (err) {
+    const tail = childOutput.join('').trim().split(/\r?\n/).slice(-60).join('\n');
+    throw new Error(`${err.message}\n\nCLI output:\n${tail}`);
+  } finally {
+    if (child.exitCode == null && child.signalCode == null) {
+      child.kill('SIGTERM');
+    }
+    await waitForChildClose(child);
+  }
+}
+
+async function main() {
+  try {
+    run('npm', ['pack', '--pack-destination', packDir]);
+    const tarballs = fs.readdirSync(packDir)
+      .filter(name => name.endsWith('.tgz'))
+      .map(name => path.join(packDir, name));
+    assert.equal(tarballs.length, 1, 'npm pack should create exactly one tarball');
+    const tarball = tarballs[0];
+
+    assertTarballEntries(tarball);
+    await assertInstalledCli(tarball);
+    console.log('\n[pack-smoke] PASS tarball contents + installed CLI smoke');
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+main().catch(err => {
+  console.error('\n[pack-smoke] FAIL');
+  console.error(err && err.stack || err);
+  process.exit(1);
+});

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);
@@ -104,13 +106,25 @@ limits:
       assert.equal(css.contentType.split(';')[0], 'text/css');
       assert.ok(css.body.includes('topbar') || css.body.includes('sidebar') || css.body.includes('detail'));
 
-      console.log('\n[verify] PASS build + tests + HTTP/API/static smoke checks');
+      const manifest = await fetchJson(`${base}/site.webmanifest`);
+      assert.equal(manifest.name, 'HuHaa AI 助手');
+      assert.ok(manifest.icons.some(icon => icon.sizes === '192x192'));
+      assert.ok(manifest.icons.some(icon => icon.sizes === '512x512'));
+
+      const favicon = await fetchBuffer(`${base}/favicon.ico`);
+      assert.equal(favicon.contentType.split(';')[0], 'image/x-icon');
+      assert.deepEqual([...favicon.body.subarray(0, 4)], [0x00, 0x00, 0x01, 0x00]);
     } finally {
       await app.close();
     }
+
+    run('node', ['build/pack-smoke.mjs']);
+    console.log('\n[verify] PASS build + tests + HTTP/API/static/package smoke checks');
   } 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 });
   }
 }
@@ -129,6 +143,13 @@ async function fetchText(url, init) {
   return { body, contentType: res.headers.get('content-type') || '' };
 }
 
+async function fetchBuffer(url, init) {
+  const res = await fetch(url, init);
+  const body = Buffer.from(await res.arrayBuffer());
+  assert.equal(res.ok, true, `${url} returned ${res.status}: ${body.toString('utf8', 0, 200)}`);
+  return { body, contentType: res.headers.get('content-type') || '' };
+}
+
 main().catch(err => {
   console.error('\n[verify] FAIL');
   console.error(err && err.stack || err);

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` 时不触发远程下载，但仍可读取已有本地缓存。
+
 ---
 
 # 三、框架说明