skillhelper 0.4.2

package/packages/scanner/src/core/descriptor.mjs

@@ -0,0 +1,143 @@
+/**
+ * @file descriptor.mjs
+ * ScannerDescriptor 类型与 registry。
+ *
+ * 对标 cockpit-tools 报告第一建议：把散落在各 adapter 的检测规则
+ * （目录候选、glob 模式、ignore、deep、品牌 key）显式登记成 descriptor，
+ * 方便测试、热修、置信度判定。
+ *
+ * 阶段一渐进迁移：registry 与现有 editor-tiers.mjs 配置并存，
+ * adapter 逐个改为读 descriptor。本文件只管"去哪扫、用什么 glob"，
+ * 不管"怎么解析"（解析逻辑仍由各 adapter 自持，避免行为变化）。
+ *
+ * 置信度四级（对标报告第二建议）：
+ *   L1 只发现目录 / L2 命中技能文件 / L3 解析出有效技能 / L4 完整元数据
+ */
+
+/**
+ * @typedef {Object} DetectSpec
+ * @property {string} globalPath        - 全局扫描根目录（支持 ~）
+ * @property {string} [projectPath]     - 项目级扫描相对路径
+ * @property {string[]} globPatterns    - fast-glob 模式列表
+ * @property {string[]} [ignore]        - ignore 列表
+ * @property {number} [deep]            - glob 递归深度
+ */
+
+/**
+ * @typedef {Object} ScannerDescriptor
+ * @property {string} id                - 唯一标识，如 'claude-code' / 'tier2-user' / 'tier3-other:homebrew'
+ * @property {'tier-1'|'tier-2'|'tier-3'} tier
+ * @property {string} brand             - 品牌 key（用于图标映射）
+ * @property {string} label             - 人类可读名称
+ * @property {DetectSpec} detect        - 检测规则
+ * @property {string} [editorName]      - SkillItem.editor 字段值
+ * @property {string} [sourceTag]       - SkillItem.source 字段值
+ */
+
+const registry = new Map();
+
+/**
+ * 校验 descriptor 必填字段。手写校验，不引入 zod（见迭代计划 8.2）。
+ * @param {ScannerDescriptor} desc
+ * @throws {Error} 字段缺失或类型错误时抛出
+ */
+export function validateDescriptor(desc) {
+  if (!desc || typeof desc !== 'object') {
+    throw new Error('descriptor 必须是对象');
+  }
+  const required = ['id', 'tier', 'brand', 'label', 'detect'];
+  for (const key of required) {
+    if (desc[key] === undefined || desc[key] === null) {
+      throw new Error(`descriptor 缺失必填字段: ${key}`);
+    }
+  }
+  const validTiers = ['tier-1', 'tier-2', 'tier-3'];
+  if (!validTiers.includes(desc.tier)) {
+    throw new Error(`descriptor.tier 非法: ${desc.tier}，应为 ${validTiers.join('|')}`);
+  }
+  if (!desc.detect || typeof desc.detect !== 'object') {
+    throw new Error('descriptor.detect 必须是对象');
+  }
+  if (!desc.detect.globalPath || typeof desc.detect.globalPath !== 'string') {
+    throw new Error('descriptor.detect.globalPath 必须是非空字符串');
+  }
+  if (!Array.isArray(desc.detect.globPatterns) || desc.detect.globPatterns.length === 0) {
+    throw new Error('descriptor.detect.globPatterns 必须是非空数组');
+  }
+}
+
+/**
+ * 注册一个 descriptor。同 id 覆盖（支持热修）。
+ * @param {ScannerDescriptor} desc
+ * @returns {ScannerDescriptor}
+ */
+export function registerDescriptor(desc) {
+  validateDescriptor(desc);
+  registry.set(desc.id, desc);
+  return desc;
+}
+
+/**
+ * 批量注册。
+ * @param {ScannerDescriptor[]} descs
+ */
+export function registerDescriptors(descs) {
+  for (const d of descs) registerDescriptor(d);
+}
+
+/**
+ * 按 id 查询 descriptor。
+ * @param {string} id
+ * @returns {ScannerDescriptor | null}
+ */
+export function getDescriptor(id) {
+  return registry.get(id) || null;
+}
+
+/**
+ * 列出全部 descriptor（按 tier 排序）。
+ * @returns {ScannerDescriptor[]}
+ */
+export function listDescriptors() {
+  const order = { 'tier-1': 0, 'tier-2': 1, 'tier-3': 2 };
+  return [...registry.values()].sort((a, b) => (order[a.tier] ?? 99) - (order[b.tier] ?? 99));
+}
+
+/**
+ * 按 tier 过滤。
+ * @param {'tier-1'|'tier-2'|'tier-3'} tier
+ * @returns {ScannerDescriptor[]}
+ */
+export function descriptorsByTier(tier) {
+  return listDescriptors().filter(d => d.tier === tier);
+}
+
+/**
+ * 清空 registry（仅测试用）。
+ */
+export function _resetForTest() {
+  registry.clear();
+}
+
+/**
+ * 置信度级别判定。输入扫描结果，输出该 source 的置信度。
+ *
+ * L1 只发现目录       - globalPath 存在但未命中技能文件
+ * L2 命中技能文件     - glob 匹配到至少 1 个 SKILL.md
+ * L3 解析出有效技能   - frontmatter 解析成功，name 非空
+ * L4 完整元数据       - name + description 齐全
+ *
+ * @param {Object} result
+ * @param {boolean} result.dirExists       - 检测目录是否存在
+ * @param {number}  result.matchedFiles    - glob 命中文件数
+ * @param {number}  result.parsedValid     - 解析成功（name 非空）的技能数
+ * @param {number}  result.metadataComplete - 元数据完整（name+description）的技能数
+ * @returns {'L1'|'L2'|'L3'|'L4'|null}     - dirExists 为 false 时返回 null
+ */
+export function computeConfidence({ dirExists, matchedFiles, parsedValid, metadataComplete }) {
+  if (!dirExists) return null;
+  if ((metadataComplete || 0) > 0) return 'L4';
+  if ((parsedValid || 0) > 0) return 'L3';
+  if ((matchedFiles || 0) > 0) return 'L2';
+  return 'L1';
+}

package/packages/scanner/src/core/path-hash.mjs

@@ -0,0 +1,89 @@
+/**
+ * @file path-hash.mjs
+ * 路径规范化 + MD5 哈希计算
+ * 用于去重和菜单分层显示
+ *
+ * 2026-07 阶段零：从 hash/path-hash.mjs 迁入 core/。
+ * 原 hash/path-hash.mjs 改为 re-export，保持现有 import 路径不变。
+ */
+
+import crypto from 'node:crypto';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * 规范化路径，然后计算 MD5 哈希
+ * 规范化步骤：
+ * 1. 展开 ~ 为 $HOME
+ * 2. 转换为绝对路径（resolve 符号链接）
+ * 3. 统一路径分隔符（使用 /）
+ *
+ * @param {string} filePath - 待处理路径
+ * @returns {string} MD5 哈希值（32位十六进制）
+ */
+export function getPathHash(filePath) {
+  // Step 1: 展开 ~
+  const expanded = filePath.startsWith('~')
+    ? path.join(os.homedir(), filePath.slice(1))
+    : filePath;
+
+  // Step 2: 转换为绝对路径
+  const absolute = path.resolve(expanded);
+
+  // Step 3: 统一分隔符（转为 POSIX 风格）
+  const normalized = absolute.split(path.sep).join('/');
+
+  // Step 4: 计算 MD5
+  return crypto.createHash('md5').update(normalized).digest('hex');
+}
+
+/**
+ * LRU 缓存，避免重复计算哈希
+ */
+export class PathHashCache {
+  constructor(maxSize = 1000) {
+    this.maxSize = maxSize;
+    this.cache = new Map(); // path -> hash
+  }
+
+  get(filePath) {
+    return this.cache.get(filePath);
+  }
+
+  set(filePath, hash) {
+    if (this.cache.size >= this.maxSize) {
+      // 移除最旧的条目（第一个）
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(filePath, hash);
+  }
+
+  /**
+   * 获取或计算哈希
+   */
+  getOrCompute(filePath) {
+    let hash = this.cache.get(filePath);
+    if (!hash) {
+      hash = getPathHash(filePath);
+      this.set(filePath, hash);
+    }
+    return hash;
+  }
+
+  /**
+   * 清空缓存
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * 获取缓存大小
+   */
+  get size() {
+    return this.cache.size;
+  }
+}
+
+export const pathHashCache = new PathHashCache();

package/packages/scanner/src/core/registry.mjs

@@ -0,0 +1,128 @@
+/**
+ * @file registry.mjs
+ * 从 editor-tiers.mjs 现有配置派生 ScannerDescriptor 并注册。
+ *
+ * 设计原则：配置单一来源仍是 editor-tiers.mjs（现有测试直接引用其导出，
+ * 不破坏）。registry 是派生层，adapter 改为从 registry 读 descriptor。
+ *
+ * 阶段一渐进迁移：本模块在 scanner 入口加载时调用 registerAll()，
+ * 之后 tier1/2/3 adapter 用 getDescriptor(id) 替代硬编码。
+ */
+
+import {
+  EDITOR_TIER_1_CONFIGS,
+  USER_TIER_2_CONFIG,
+  OTHER_TIER_3_CONFIGS,
+} from '../config/editor-tiers.mjs';
+import {
+  registerDescriptors,
+  listDescriptors,
+  getDescriptor,
+  descriptorsByTier,
+} from './descriptor.mjs';
+
+// 三个 tier 共用的 ignore 列表（从原 adapter 硬编码提取，保持一致）
+const DEFAULT_IGNORE = ['**/node_modules/**', '**/.git/**', '**/dist/**'];
+const DEFAULT_DEEP = 10;
+
+// glob 模式以相对形式存储（不含 basePath 前缀），adapter 拼接实际 basePath。
+// 这样 globalPath 和 projectPath 扫描可复用同一组模式。
+
+// Tier 1 的三种大小写不敏感 glob 模式（从 tier1-editor-skills.mjs:88-92 提取）
+const TIER1_PATTERNS = [
+  `**/[sS][kK][iI][lL][lL][sS]/**/[sS][kK][iI][lL][lL].[mM][dD]`,
+  `**/SKILL.md`,
+  `**/skill.md`,
+];
+
+// Tier 2 的两种模式（从 tier2-user-skills.mjs:37-40 提取）
+const TIER2_PATTERNS = [
+  `**/SKILL.md`,
+  `**/skill.md`,
+];
+
+// Tier 3 仅小写 skill.md（从 tier3-other-skills.mjs:44 提取，有意的大小写敏感）
+const TIER3_PATTERNS = [`**/skill.md`];
+
+let initialized = false;
+
+/**
+ * 把 editor-tiers.mjs 三种配置转成统一 descriptor 并注册。
+ * 幂等：重复调用不重复注册（同 id 覆盖）。
+ */
+export function registerAll() {
+  const descs = [];
+
+  // Tier 1: 22 个编辑器
+  for (const editor of EDITOR_TIER_1_CONFIGS) {
+    descs.push({
+      id: `tier1:${editor.brand}`,
+      tier: 'tier-1',
+      brand: editor.brand,
+      label: editor.name,
+      editorName: editor.name,
+      detect: {
+        globalPath: editor.globalPath,
+        projectPath: editor.projectPath,
+        globPatterns: TIER1_PATTERNS,
+        ignore: DEFAULT_IGNORE,
+        deep: DEFAULT_DEEP,
+      },
+    });
+  }
+
+  // Tier 2: 用户根目录技能库（单个）
+  descs.push({
+    id: 'tier2:user-skills',
+    tier: 'tier-2',
+    brand: 'my-skills',
+    label: USER_TIER_2_CONFIG.name,
+    editorName: 'my-skills',
+    sourceTag: 'tier2-user',
+    detect: {
+      globalPath: USER_TIER_2_CONFIG.globalPath,
+      globPatterns: TIER2_PATTERNS,
+      ignore: DEFAULT_IGNORE,
+      deep: DEFAULT_DEEP,
+    },
+  });
+
+  // Tier 3: 其他位置（多个，每个一个 descriptor）
+  for (const location of OTHER_TIER_3_CONFIGS) {
+    descs.push({
+      id: `tier3:${location.name}`,
+      tier: 'tier-3',
+      brand: 'other-skills',
+      label: location.name,
+      editorName: 'other-skills',
+      sourceTag: 'tier3-other',
+      detect: {
+        globalPath: location.path,
+        globPatterns: TIER3_PATTERNS,
+        ignore: DEFAULT_IGNORE,
+        deep: DEFAULT_DEEP,
+      },
+    });
+  }
+
+  registerDescriptors(descs);
+  initialized = true;
+}
+
+/** 确保 registry 已初始化（懒加载，首次访问时触发） */
+export function ensureRegistered() {
+  if (!initialized) registerAll();
+}
+
+/** 重新加载（测试用：config 改动后强制重建） */
+export function reload() {
+  initialized = false;
+  registerAll();
+}
+
+/** 重置 registry 与初始化标志（仅测试用，配合 descriptor._resetForTest） */
+export function _resetForTest() {
+  initialized = false;
+}
+
+export { listDescriptors, getDescriptor, descriptorsByTier };

package/packages/scanner/src/hash/path-hash.mjs

@@ -0,0 +1,8 @@
+/**
+ * @file path-hash.mjs
+ * 2026-07 阶段零：实现已迁入 core/path-hash.mjs。
+ * 本文件保留为 re-export，保持现有 import 路径不变（7 处引用未改动）。
+ * 新代码请直接引用 ../core/path-hash.mjs。
+ */
+
+export { getPathHash, PathHashCache, pathHashCache } from '../core/path-hash.mjs';

package/packages/scanner/src/icon/brand-map.mjs

@@ -0,0 +1,268 @@
+// brand-map.mjs — maps a skill/command brand to official icon sources.
+//
+// 本文件只登记官方来源：本机 .app 的 bundle/appName，或品牌官方网站上的 icon URL。
+// 无法确认官方来源的品牌保留 entry 但不配置 officialIconUrls，前端会显示中性占位，
+// 避免使用“看起来像官方”的自制 logo。
+
+/**
+ * @typedef {object} BrandAppSpec
+ * @property {string[]} bundleIds             — candidate CFBundleIdentifier values
+ * @property {string[]} appNames              — candidate .app display names (no extension)
+ * @property {string[]} [aliases]             — alternate brand keys normalized to this entry
+ * @property {string[]} [officialIconPages]   — human-readable official pages documenting source context
+ * @property {string[]} [officialIconUrls]    — official HTTPS image URLs eligible for local caching
+ * @property {boolean} [remoteIconCache]       — whether remote download/cache is allowed
+ * @property {string} [emoji]                 — legacy metadata fallback; UI should prefer neutral placeholder
+ */
+
+/** @type {Record<string, BrandAppSpec>} */
+export const BRAND_APP_MAP = {
+  cursor: {
+    bundleIds: ['com.todesktop.230313mzl4w4u92'],
+    appNames: ['Cursor'],
+    officialIconPages: ['https://cursor.com/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['cursor.com', 'cursor.sh'],
+    emoji: '🖱️',
+  },
+  vscode: {
+    bundleIds: ['com.microsoft.VSCode', 'com.microsoft.VSCodeInsiders'],
+    appNames: ['Visual Studio Code', 'Code', 'Visual Studio Code - Insiders'],
+    aliases: ['vs-code', 'code'],
+    officialIconPages: ['https://code.visualstudio.com/brand'],
+    officialIconUrls: ['https://code.visualstudio.com/assets/apple-touch-icon.png'],
+    remoteIconCache: true,
+    fingerprints: ['code.visualstudio.com', 'visualstudio.com'],
+    emoji: '📝',
+  },
+  claude: {
+    bundleIds: ['com.anthropic.claude', 'com.anthropic.claudefordesktop'],
+    appNames: ['Claude'],
+    aliases: ['claude-code', 'anthropic'],
+    officialIconPages: ['https://claude.ai/', 'https://www.anthropic.com/'],
+    officialIconUrls: ['https://claude.ai/favicon.ico'],
+    remoteIconCache: true,
+    fingerprints: ['claude.ai', 'anthropic.com'],
+    emoji: '🤖',
+  },
+  obsidian: {
+    bundleIds: ['md.obsidian'],
+    appNames: ['Obsidian'],
+    officialIconPages: ['https://obsidian.md/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['obsidian.md'],
+    emoji: '🧠',
+  },
+  docker: {
+    bundleIds: ['com.docker.docker'],
+    appNames: ['Docker', 'Docker Desktop'],
+    officialIconPages: ['https://www.docker.com/products/docker-desktop/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['docker.com'],
+    emoji: '🐳',
+  },
+  // CLI / agent brands. Codex may be available as a local app; no stable official
+  // public icon URL is registered here, so remote fallback intentionally stays empty.
+  codex: {
+    bundleIds: [],
+    appNames: ['Codex'],
+    officialIconPages: ['https://openai.com/codex/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['openai.com', 'codex.com'],
+    emoji: '📋',
+  },
+  hermes: {
+    bundleIds: [],
+    appNames: ['Hermes'],
+    // 官方图标来源：用户提供的 Hermes Agent icon，已烘焙到本地 public/icons/hermes-{size}.png。
+    // 远程抓取成本高且容易命中营销 banner，这里禁用远程回退，只走 localIconBase。
+    officialIconPages: [],
+    officialIconUrls: [],
+    remoteIconCache: false,
+    // 本地兜底：web/public/icons/hermes-{size}.png，必须在 dist 中存在
+    localIconBase: 'icons/hermes',
+    fingerprints: ['hermes-agent.nousresearch.com'],
+    emoji: '⚡',
+  },
+  gstack: {
+    bundleIds: [],
+    appNames: [],
+    officialIconPages: [],
+    officialIconUrls: [],
+    remoteIconCache: false,
+    emoji: '⚡',
+  },
+  mcp: { bundleIds: [], appNames: [], officialIconUrls: [], remoteIconCache: false, emoji: '🔌' },
+  google: {
+    bundleIds: ['com.google.chrome'],
+    appNames: ['Google Chrome', 'Chrome'],
+    officialIconPages: ['https://www.google.com/chrome/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['google.com', 'googleapis.com', 'gemini.google.com'],
+    emoji: '🌐',
+  },
+  github: {
+    bundleIds: ['com.github.github', 'com.github.GitHubClient'],
+    appNames: ['GitHub', 'GitHub Desktop'],
+    officialIconPages: ['https://github.com/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['github.com', 'githubusercontent.com'],
+    emoji: '🐙',
+  },
+  notion: {
+    bundleIds: ['notion.id'],
+    appNames: ['Notion'],
+    officialIconPages: ['https://www.notion.com/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['notion.com', 'notion.so'],
+    emoji: '📓',
+  },
+  // Trae 字节跳动 AI IDE。trae-cn 本机装了 Trae CN.app，走本地 .app 图标提取。
+  'trae-cn': {
+    bundleIds: ['cn.trae.app'],
+    appNames: ['Trae CN'],
+    officialIconPages: ['https://www.trae.cn/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['trae.cn'],
+    emoji: '🛸',
+  },
+  trae: {
+    bundleIds: ['cn.trae.app'],
+    appNames: ['Trae', 'Trae CN'],
+    aliases: ['trae-intl'],
+    officialIconPages: ['https://www.trae.com/'],
+    officialIconUrls: [],
+    remoteIconCache: true,
+    fingerprints: ['trae.com', 'trae.cn'],
+    emoji: '🛸',
+  },
+  // 仅保留元数据 fallback（无单一可确认官方图标 URL）
+  apple: { bundleIds: [], appNames: [], officialIconUrls: [], remoteIconCache: false, emoji: '🍎' },
+  rust: { bundleIds: [], appNames: [], officialIconUrls: [], remoteIconCache: false, emoji: '🦀' },
+  python: { bundleIds: [], appNames: [], officialIconUrls: [], remoteIconCache: false, emoji: '🐍' },
+  suno: { bundleIds: [], appNames: [], officialIconUrls: [], remoteIconCache: false, emoji: '🎵' },
+};
+
+const ALIAS_TO_CANONICAL = new Map();
+for (const [brand, spec] of Object.entries(BRAND_APP_MAP)) {
+  ALIAS_TO_CANONICAL.set(brand, brand);
+  for (const alias of spec.aliases || []) {
+    ALIAS_TO_CANONICAL.set(alias.toLowerCase().trim(), brand);
+  }
+}
+
+/**
+ * Normalize a brand/source key to the canonical manifest key.
+ * @param {string} key
+ * @returns {string | null}
+ */
+export function normalizeBrandKey(key) {
+  if (!key) return null;
+  const normalized = String(key).toLowerCase().trim();
+  return ALIAS_TO_CANONICAL.get(normalized) || (BRAND_APP_MAP[normalized] ? normalized : null);
+}
+
+/**
+ * Resolve a brand/source key (or a raw bundle id) into a lookup spec.
+ * A value containing a dot is treated as an explicit bundle id.
+ * @param {string} key
+ * @returns {BrandAppSpec | null}
+ */
+export function resolveBrandSpec(key) {
+  if (!key) return null;
+  const canonical = normalizeBrandKey(key);
+  if (canonical && BRAND_APP_MAP[canonical]) return BRAND_APP_MAP[canonical];
+  // Looks like a bundle identifier (e.g. "com.microsoft.VSCode")
+  if (/^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(key)) {
+    return { bundleIds: [key], appNames: [], officialIconUrls: [], remoteIconCache: false, emoji: undefined };
+  }
+  return null;
+}
+
+/**
+ * Emoji fallback metadata for a brand/source key.
+ * @param {string} key
+ * @returns {string | undefined}
+ */
+export function emojiForBrand(key) {
+  const canonical = normalizeBrandKey(key);
+  return canonical ? BRAND_APP_MAP[canonical]?.emoji : undefined;
+}
+
+// ───────────────────────── provider fingerprint (v0.4) ──────────────────────
+// 对标 cockpit-tools codexProviderPresets 的 baseUrl 规范化匹配，补一层
+// hostname suffix 匹配，让反代/多 region 场景也能命中正确品牌，而不是
+// 一律回退 custom。本模块保持纯数据/纯函数，不读文件；用户手动覆写由
+// 调用方（icon-extractor）注入 overrides 参数。
+
+/**
+ * 从 URL 或裸 hostname 提取小写 hostname。
+ * @param {string} urlOrHost - URL 或 hostname
+ * @returns {string | null}
+ */
+export function extractHostname(urlOrHost) {
+  if (!urlOrHost) return null;
+  const s = String(urlOrHost).trim().toLowerCase();
+  if (!s) return null;
+  // 带 scheme
+  try {
+    const u = new URL(s.startsWith('http') ? s : `https://${s}`);
+    return u.hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 按 hostname suffix 多层匹配品牌。
+ *
+ * 匹配层级（优先级从高到低）：
+ *   1. 用户 overrides（hostnameSuffix -> brand，由调用方注入）
+ *   2. BRAND_APP_MAP 各项的 fingerprints（hostname suffix 匹配，支持多级子域）
+ *   3. 无匹配返回 null（调用方可回退 custom）
+ *
+ * @param {string} urlOrHost - URL 或 hostname
+ * @param {Record<string, string>} [overrides] - 用户手动覆写：{ hostnameSuffix: brandKey }
+ * @returns {string | null} canonical brand key
+ */
+export function resolveBrandByFingerprint(urlOrHost, overrides) {
+  const host = extractHostname(urlOrHost);
+  if (!host) return null;
+
+  // 1. 用户 overrides 优先（精确匹配，再 suffix 匹配）
+  if (overrides && typeof overrides === 'object') {
+    if (overrides[host]) {
+      const canonical = normalizeBrandKey(overrides[host]);
+      if (canonical) return canonical;
+    }
+    for (const [suffix, brand] of Object.entries(overrides)) {
+      if (host === suffix || host.endsWith(`.${suffix}`)) {
+        const canonical = normalizeBrandKey(brand);
+        if (canonical) return canonical;
+      }
+    }
+  }
+
+  // 2. BRAND_APP_MAP fingerprints：hostname suffix 匹配
+  //    host === 'claude.ai' 或 host.endsWith('.claude.ai') 均命中 claude
+  for (const [brand, spec] of Object.entries(BRAND_APP_MAP)) {
+    const fps = spec.fingerprints;
+    if (!fps || !fps.length) continue;
+    for (const suffix of fps) {
+      const s = String(suffix).toLowerCase().trim();
+      if (host === s || host.endsWith(`.${s}`)) {
+        return brand;
+      }
+    }
+  }
+
+  return null;
+}