huhaa-myskills 0.2.13 → 0.3.4

package/packages/web/src/components/views/SkillDetail.test.tsx

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import '@testing-library/jest-dom/vitest'
+import { render, screen } from '@testing-library/react'
+import { SkillDetail } from './SkillDetail'
+import type { SkillItem } from '@/types'
+
+vi.mock('@/lib/api', () => ({
+  fetchSkillDetail: vi.fn(),
+  copy: vi.fn(async () => ({ ok: true })),
+  open: vi.fn(async () => ({ ok: true })),
+}))
+import { fetchSkillDetail } from '@/lib/api'
+
+const item: SkillItem = {
+  id: 'demo-1',
+  kind: 'skill',
+  source: 'claude-code',
+  editor: 'Claude Code',
+  name: 'autoplan',
+  title: 'autoplan',
+  description: 'Auto-review pipeline',
+  paths: { abs: '/Users/x/.claude/skills/autoplan/SKILL.md', rootKind: 'home' },
+  preview: '预览内容',
+  updatedAt: '2026-01-01',
+}
+
+beforeEach(() => vi.clearAllMocks())
+
+describe('SkillDetail（P7 markdown 正文）', () => {
+  it('拉取 raw 并渲染 markdown 正文', async () => {
+    vi.mocked(fetchSkillDetail).mockResolvedValue({
+      ...item,
+      raw: '## 正文标题\n\n正文段落内容',
+    })
+    render(<SkillDetail item={item} />)
+    // 元数据
+    expect(screen.getByText('Claude Code')).toBeInTheDocument()
+    expect(screen.getByText((item.paths as NonNullable<typeof item.paths>).abs)).toBeInTheDocument()
+    expect(screen.getByText('复制正文')).toBeInTheDocument()
+    // markdown 渲染（异步加载后出现）
+    expect(await screen.findByText('正文标题')).toBeInTheDocument()
+    expect(screen.getByText('正文段落内容')).toBeInTheDocument()
+    expect(fetchSkillDetail).toHaveBeenCalledWith('demo-1')
+  })
+
+  it('raw 为空显示占位', async () => {
+    vi.mocked(fetchSkillDetail).mockResolvedValue({ ...item, raw: '' })
+    render(<SkillDetail item={item} />)
+    expect(await screen.findByText('（无正文内容）')).toBeInTheDocument()
+  })
+
+  it('拉取失败显示错误', async () => {
+    vi.mocked(fetchSkillDetail).mockRejectedValue(new Error('boom'))
+    render(<SkillDetail item={item} />)
+    expect(await screen.findByText('正文加载失败')).toBeInTheDocument()
+  })
+})

package/packages/web/src/components/views/SkillDetail.tsx

@@ -0,0 +1,81 @@
+import { useEffect, useState } from 'react'
+import { ActionButton } from '@/components/ui/ActionButton'
+import { copy, open, fetchSkillDetail } from '@/lib/api'
+import { renderMarkdown } from '@/lib/markdown'
+import { itemEditorKey } from '@/lib/editors'
+import type { SkillItem } from '@/types'
+
+interface SkillDetailProps {
+  item: SkillItem
+}
+
+type RawStatus = 'loading' | 'ready' | 'error'
+
+export function SkillDetail({ item }: SkillDetailProps) {
+  const [raw, setRaw] = useState<string>('')
+  const [status, setStatus] = useState<RawStatus>('loading')
+
+  useEffect(() => {
+    let alive = true
+    setStatus('loading')
+    setRaw('')
+    fetchSkillDetail(item.id)
+      .then((detail) => {
+        if (!alive) return
+        setRaw(detail.raw ?? '')
+        setStatus('ready')
+      })
+      .catch(() => {
+        if (alive) setStatus('error')
+      })
+    return () => {
+      alive = false
+    }
+  }, [item.id])
+
+  return (
+    <div className="detail">
+      <h2 className="text-h3 text-foreground">{item.title || item.name}</h2>
+      <p className="mt-2 text-body-sm text-muted-foreground">
+        {item.description || '（无描述）'}
+      </p>
+
+      <dl className="mt-4 grid grid-cols-[auto_1fr] gap-x-4 gap-y-2 text-body-sm">
+        <dt className="text-muted-foreground">类型</dt>
+        <dd>{item.kind}</dd>
+        <dt className="text-muted-foreground">来源</dt>
+        <dd>{itemEditorKey(item)}</dd>
+        <dt className="text-muted-foreground">路径</dt>
+        <dd className="break-all font-mono text-caption">{item.paths?.abs}</dd>
+      </dl>
+
+      <div className="mt-5 flex flex-wrap gap-2">
+        <ActionButton label="复制路径" onAction={() => copy(item.id, 'path')} />
+        <ActionButton label="复制名称" onAction={() => copy(item.id, 'name')} />
+        <ActionButton label="复制正文" onAction={() => copy(item.id, 'raw')} />
+        <ActionButton label="复制调用提示" onAction={() => copy(item.id, 'prompt')} />
+        <ActionButton label="打开" onAction={() => open(item.id, 'default')} />
+        <ActionButton label="在访达显示" onAction={() => open(item.id, 'finder')} />
+      </div>
+
+      {/* 正文（markdown 渲染） */}
+      <div className="mt-6 border-t border-border pt-5">
+        {status === 'loading' && (
+          <p className="text-body-sm text-muted-foreground">加载正文…</p>
+        )}
+        {status === 'error' && (
+          <p className="text-body-sm text-destructive">正文加载失败</p>
+        )}
+        {status === 'ready' &&
+          (raw.trim() ? (
+            <div
+              className="markdown-body"
+              dangerouslySetInnerHTML={{ __html: renderMarkdown(raw) }}
+            />
+          ) : (
+            <p className="text-body-sm text-muted-foreground">（无正文内容）</p>
+          ))}
+      </div>
+    </div>
+  )
+}

package/packages/web/src/components/views/SkillsView.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest'
+import { itemEditorKey } from './SkillsView'
+import type { SkillItem } from '@/types'
+
+function mk(partial: Partial<SkillItem>): SkillItem {
+  return {
+    id: 'id',
+    kind: 'skill',
+    source: 'hermes',
+    name: 'n',
+    paths: { abs: '/x', rootKind: 'home' },
+    preview: '',
+    updatedAt: '2026-01-01',
+    ...partial,
+  }
+}
+
+describe('itemEditorKey（与 server buildStats 口径一致）', () => {
+  it('优先 editor', () => {
+    expect(itemEditorKey(mk({ editor: 'Claude Code', source: 'claude-code' }))).toBe('Claude Code')
+  })
+  it('无 editor 落到 source', () => {
+    expect(itemEditorKey(mk({ editor: undefined, source: 'hermes' }))).toBe('hermes')
+  })
+  it('editor 与 source 皆空 → (none)', () => {
+    expect(itemEditorKey(mk({ editor: undefined, source: '' }))).toBe('(none)')
+  })
+})

package/packages/web/src/components/views/SkillsView.tsx

@@ -0,0 +1,226 @@
+'use client'
+
+import { useMemo, useState } from 'react'
+import Fuse from 'fuse.js'
+import { Card, CardHeader, CardTitle, CardDescription } from '@/components/ui/card'
+import { SkillDetail } from './SkillDetail'
+import { cn } from '@/lib/cn'
+import { isNoneEditor, itemEditorKey } from '@/lib/editors'
+import { useSkillIcons } from '@/hooks/useSkillIcons'
+import type { SkillItem } from '@/types'
+
+/**
+ * 技能图标组件（R6 真实应用图标）
+ * 优先展示真实应用图标，加载失败自动回退到 tier/brand emoji。
+ * 对标 Pearcleaner 的真实应用图标展示逻辑。
+ */
+function SkillIcon({ item, size = 20 }: { item: SkillItem; size?: number }) {
+  const [hasError, setHasError] = useState(false)
+  const icons = useSkillIcons(item)
+  // Tier 1 工具优先使用真实应用图标；其余 Tier 使用 tier emoji
+  const iconUrl = item.brand && icons.isTier1 ? `/api/icons/${encodeURIComponent(item.brand)}?size=${size}` : null
+
+  if (iconUrl && !hasError) {
+    return (
+      <img
+        src={iconUrl}
+        alt=""
+        width={size}
+        height={size}
+        loading="lazy"
+        onError={() => setHasError(true)}
+        className="shrink-0 rounded-sm object-contain"
+        style={{ width: size, height: size }}
+      />
+    )
+  }
+
+  return (
+    <span
+      className="inline-flex shrink-0 items-center justify-center"
+      style={{ width: size, height: size, fontSize: size * 0.85 }}
+    >
+      {icons.brandIcon}
+    </span>
+  )
+}
+
+interface SkillsViewProps {
+  items: SkillItem[]
+  editorFilter: string | null
+  query: string
+  onQuery: (q: string) => void
+  kindFilter: string | null
+  onKind: (k: string | null) => void
+  selectedId: string | null
+  onSelect: (id: string) => void
+}
+
+/** 单条目的 editor 归属 key，与 server buildStats 口径一致。 */
+export { itemEditorKey }
+
+export function SkillsView({
+  items,
+  editorFilter,
+  query,
+  onQuery,
+  kindFilter,
+  onKind,
+  selectedId,
+  onSelect,
+}: SkillsViewProps) {
+  // 1) editor 过滤
+  const byEditor = useMemo(() => {
+    if (editorFilter === null) return items
+    if (isNoneEditor(editorFilter)) return items.filter((it) => isNoneEditor(itemEditorKey(it)))
+    return items.filter((it) => itemEditorKey(it) === editorFilter)
+  }, [items, editorFilter])
+
+  // 2) kind chips 选项（来自当前 editor 子集）
+  const kinds = useMemo(() => {
+    const m = new Map<string, number>()
+    for (const it of byEditor) m.set(it.kind, (m.get(it.kind) ?? 0) + 1)
+    return [...m.entries()].sort((a, b) => b[1] - a[1])
+  }, [byEditor])
+
+  // 3) Fuse 搜索（在 editor 子集上）
+  const fuse = useMemo(
+    () =>
+      new Fuse(byEditor, {
+        keys: ['name', 'title', 'description', 'category', 'brand', 'dirName', 'tags'],
+        threshold: 0.4,
+        ignoreLocation: true,
+      }),
+    [byEditor],
+  )
+
+  const filtered = useMemo(() => {
+    let list = query.trim() ? fuse.search(query).map((r) => r.item) : byEditor
+    if (kindFilter) list = list.filter((it) => it.kind === kindFilter)
+    return list
+  }, [byEditor, fuse, query, kindFilter])
+
+  const selected = useMemo(
+    () => filtered.find((it) => it.id === selectedId) ?? null,
+    [filtered, selectedId],
+  )
+
+  return (
+    <div className="flex h-full flex-col gap-4">
+      {/* 搜索栏 */}
+      <input
+        type="search"
+        value={query}
+        onChange={(e) => onQuery(e.target.value)}
+        placeholder="搜索技能、插件、自定义…"
+        className="h-10 w-full rounded-md border border-border bg-input px-3 text-body-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      />
+
+      {/* kind chips (secondary filter) */}
+      <div className="flex flex-wrap gap-1.5">
+        <button
+          onClick={() => onKind(null)}
+          className={cn(
+            'rounded-full px-2.5 py-0.5 text-caption transition-colors',
+            kindFilter === null
+              ? 'bg-primary text-primary-foreground'
+              : 'bg-muted text-muted-foreground hover:text-foreground',
+          )}
+        >
+          全部类型
+        </button>
+        {kinds.map(([k, c]) => (
+          <button
+            key={k}
+            onClick={() => onKind(k)}
+            className={cn(
+              'rounded-full px-2.5 py-0.5 text-caption transition-colors',
+              kindFilter === k
+                ? 'bg-primary text-primary-foreground'
+                : 'bg-muted text-muted-foreground hover:text-foreground',
+            )}
+          >
+            {k} ({c})
+          </button>
+        ))}
+      </div>
+
+      {/* 列表 + 详情 */}
+      <div className="grid min-h-0 flex-1 grid-cols-1 gap-4 lg:grid-cols-[1fr_1.2fr]">
+        <section className="flex min-h-0 flex-col gap-2 overflow-y-auto pr-1">
+          <p className="text-caption text-muted-foreground">共 {filtered.length} 项</p>
+          {filtered.length === 0 && (
+            <p className="text-body-sm text-muted-foreground">没有匹配的条目</p>
+          )}
+          {filtered.map((it) => {
+            const icons = useSkillIcons(it)
+            return (
+              <button key={it.id} onClick={() => onSelect(it.id)} className="text-left">
+                <Card
+                  className={cn(
+                    'cursor-pointer transition-colors hover:border-primary',
+                    it.id === selectedId ? 'border-primary bg-primary-soft' : '',
+                  )}
+                >
+                  <CardHeader>
+                    {/* R6：真实应用图标（对标 Pearcleaner），加载失败自动回退 emoji */}
+                    <CardTitle className="flex items-center gap-2">
+                      <SkillIcon item={it} size={24} />
+                      <span>{it.title || it.name}</span>
+                    </CardTitle>
+
+                    {/* Tier 2 specific: show dirName as secondary label */}
+                    {icons.isTier2 && it.dirName && (
+                      <p className="text-caption text-muted-foreground">
+                        目录: <code className="rounded bg-muted px-1.5 py-0.5">{it.dirName}</code>
+                      </p>
+                    )}
+
+                    <CardDescription>
+                      {it.description || it.preview || '（无描述）'}
+                    </CardDescription>
+
+                    {/* Tags and metadata */}
+                    <div className="mt-1 flex flex-wrap gap-1.5">
+                      {/* Kind tag */}
+                      <span className="rounded-sm bg-muted px-1.5 py-0.5 text-caption text-muted-foreground">
+                        {it.kind}
+                      </span>
+
+                      {/* Tier label (NEW) */}
+                      <span
+                        className={cn(
+                          'rounded-sm px-1.5 py-0.5 text-caption font-medium',
+                          icons.isTier1 && 'bg-blue-100 text-blue-700 dark:bg-blue-900 dark:text-blue-200',
+                          icons.isTier2 && 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900 dark:text-emerald-200',
+                          icons.isTier3 && 'bg-slate-100 text-slate-700 dark:bg-slate-800 dark:text-slate-300',
+                        )}
+                      >
+                        {icons.tierLabel}
+                      </span>
+
+                      {/* Editor/Source */}
+                      <span className="rounded-sm bg-muted px-1.5 py-0.5 text-caption text-muted-foreground">
+                        {itemEditorKey(it)}
+                      </span>
+                    </div>
+                  </CardHeader>
+                </Card>
+              </button>
+            )
+          })}
+        </section>
+
+        <section className="min-h-0 overflow-y-auto">
+          {selected ? (
+            <SkillDetail item={selected} />
+          ) : (
+            <div className="detail text-muted-foreground">
+              <p className="text-body-sm">从左侧选择一项查看详情</p>
+            </div>
+          )}
+        </section>
+      </div>
+    </div>
+  )
+}

package/packages/web/src/hooks/QUICK_REFERENCE.md

@@ -0,0 +1,165 @@
+# useOtherSkills - Quick Reference Card
+
+## 最常用的 3 个用法
+
+### 1️⃣ 基础：获取和分组
+
+```typescript
+import { useOtherSkills, GroupBy } from '@/hooks/useOtherSkills'
+
+const { groups } = useOtherSkills({ groupBy: GroupBy.CATEGORY })
+
+groups.map(g => `${g.icon} ${g.label} (${g.count})`)
+// => "🤖 Ai (5) | 📝 Editor (3) | ..."
+```
+
+### 2️⃣ 搜索
+
+```typescript
+const [query, setQuery] = useState('')
+const { items } = useOtherSkills({ query })
+
+// 自动搜索：名字、描述、标签、品牌、来源
+```
+
+### 3️⃣ 排序和过滤
+
+```typescript
+const { items } = useOtherSkills({
+  sortBy: SortBy.UPDATED,
+  sortOrder: SortOrder.DESC,
+  filterBrand: 'hermes',
+})
+```
+
+## 完整 API
+
+```typescript
+// 导入
+import { useOtherSkills, GroupBy, SortBy, SortOrder } from '@/hooks/useOtherSkills'
+
+// 调用
+const result = useOtherSkills(options)
+
+// options
+{
+  query?: string                    // 搜索词
+  sortBy?: SortBy                   // NAME | UPDATED | CATEGORY
+  sortOrder?: SortOrder             // ASC | DESC
+  groupBy?: GroupBy                 // CATEGORY | BRAND | SOURCE | NONE
+  filterBrand?: string              // 过滤品牌
+  filterCategory?: string           // 过滤分类
+  filterSource?: string             // 过滤来源
+  limit?: number                    // 分页大小
+  offset?: number                   // 分页偏移
+}
+
+// 返回值
+{
+  items: OtherSkill[],              // 技能列表
+  groups: OtherSkillGroup[],        // 分组结果
+  isLoading: boolean,               // 加载中
+  error: OtherSkillsError | null,   // 错误
+  total: number,                    // 总数
+  filtered: number,                 // 过滤后数
+  refetch: () => Promise<void>,     // 刷新
+}
+```
+
+## 分组结果结构
+
+```typescript
+groups[0] = {
+  groupKey: 'ai',          // 分组键
+  label: 'Ai',             // 显示标签
+  icon: '🤖',              // icon
+  items: [...],            // 该组内的技能
+  count: 5,                // 该组内的数量
+}
+```
+
+## 技能项结构
+
+```typescript
+OtherSkill {
+  id: string              // 唯一 id
+  name: string            // 技能名
+  title?: string          // 显示标题
+  description?: string    // 描述
+  category?: string | string[]  // 分类
+  brand?: string          // 品牌
+  source?: string         // 来源
+  tags?: string[]         // 标签
+  icon?: string           // 自定义 icon
+  docs?: string           // 文档链接
+  links?: { label, url }[]
+  examples?: string[]
+  updatedAt?: string      // ISO 时间戳
+  parseError?: string     // 错误
+}
+```
+
+## 常见错误和解决方案
+
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| `Cannot read properties of undefined` | options 不存在 | 提供默认值或检查 |
+| `isLoading 一直为 true` | API 未响应 | 检查 `/api/other-skills` 端点 |
+| `error.code === 'INVALID_FORMAT'` | 返回格式不对 | 确保返回 `OtherSkill[]` |
+| 搜索无结果 | 搜索词未匹配 | 检查搜索词大小写（不敏感） |
+| 分组为空 | 都被过滤掉了 | 检查 filter 条件 |
+
+## 性能提示
+
+```typescript
+// ❌ 不好：每次都创建新对象
+const { items } = useOtherSkills({
+  sortBy: SortBy.NAME,
+  groupBy: GroupBy.CATEGORY,
+})
+
+// ✅ 好：使用 useMemo
+const options = useMemo(() => ({
+  sortBy: SortBy.NAME,
+  groupBy: GroupBy.CATEGORY,
+}), [])
+
+const { items } = useOtherSkills(options)
+```
+
+## 测试示例
+
+```typescript
+import { renderHook } from '@testing-library/react'
+
+// 纯函数测试（推荐）
+const skills = [{ id: '1', name: 'Docker', ... }]
+const filtered = skills.filter(s => 
+  s.name.toLowerCase().includes('docker')
+)
+expect(filtered).toHaveLength(1)
+
+// Hook 测试
+const { result } = renderHook(() => 
+  useOtherSkills({ query: 'docker' })
+)
+```
+
+## 核心特性对比
+
+| 功能 | 实现 |
+|------|------|
+| 搜索 | 6 个字段（OR 逻辑） |
+| 排序 | 3 个字段 × 升降序 |
+| 分组 | 4 种分组方式 |
+| 过滤 | 3 个条件（可组合） |
+| 分页 | limit + offset |
+| 缓存 | useMemo 自动优化 |
+| 错误 | 自定义错误类 |
+
+## 快速导航
+
+- 📖 完整文档: `packages/web/src/hooks/README.md`
+- 🧪 测试文件: `packages/web/src/hooks/__tests__/useOtherSkills.test.ts`
+- 📝 实现代码: `packages/web/src/hooks/useOtherSkills.ts`
+- 🔷 类型定义: `packages/web/src/types/other-skill.ts`