huhaa-myskills 0.2.13 → 0.3.4

package/packages/web/src/index.css

@@ -0,0 +1,161 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ─────────────────────────── 设计 token ───────────────────────────
+   颜色为 HSL 通道值，配合 tailwind.config.ts 的 hsl(var(--x)) 使用。
+   取自 docs/Frontend-Theme-Design.md v2.0（Cockpit Tools 风格柔和浅色）。 */
+:root {
+  /* Light Mode（默认） */
+  --color-background: 220 20% 98%;
+  --color-foreground: 220 9% 12%;
+  --color-card: 0 0% 100%;
+  --color-card-foreground: 220 9% 12%;
+  --color-sidebar: 210 20% 99%;
+  --color-border: 220 16% 94%;
+  --color-input: 220 13% 96%;
+  --color-ring: 215 100% 46%;
+  --color-primary: 215 100% 46%;
+  --color-primary-foreground: 0 0% 100%;
+  --color-primary-soft: 215 100% 96%;
+  --color-secondary: 217 33% 17%;
+  --color-secondary-foreground: 210 40% 96%;
+  --color-destructive: 0 84% 60%;
+  --color-destructive-foreground: 0 0% 100%;
+  --color-muted: 220 13% 95%;
+  --color-muted-foreground: 217 11% 45%;
+  --color-accent: 38 92% 50%;
+  --color-accent-foreground: 220 9% 12%;
+
+  --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+  --font-mono: 'SF Mono', 'JetBrains Mono', 'Fira Code', Menlo, Consolas, monospace;
+}
+
+.dark {
+  --color-background: 222 47% 11%;
+  --color-foreground: 210 40% 96%;
+  --color-card: 217 33% 14%;
+  --color-card-foreground: 210 40% 96%;
+  --color-sidebar: 222 33% 13%;
+  --color-border: 217 33% 20%;
+  --color-input: 217 33% 17%;
+  --color-ring: 215 100% 46%;
+  --color-primary: 215 100% 46%;
+  --color-primary-foreground: 0 0% 100%;
+  --color-primary-soft: 217 40% 20%;
+  --color-secondary: 210 40% 96%;
+  --color-secondary-foreground: 217 33% 17%;
+  --color-destructive: 0 84% 60%;
+  --color-destructive-foreground: 0 0% 100%;
+  --color-muted: 217 33% 17%;
+  --color-muted-foreground: 215 14% 65%;
+  --color-accent: 38 92% 50%;
+  --color-accent-foreground: 220 9% 12%;
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  html,
+  body,
+  #app {
+    height: 100%;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+  }
+}
+
+/* ─────────────────── 三区外壳布局（topbar 横跨）───────────────────
+   类名 sidebar / topbar / detail / main-pane 同时被 build/verify.mjs
+   的 CSS 冒烟断言引用，重命名需同步修改 verify。
+   布局：顶部模块标签栏横跨 → 左侧 editor 图标导航 + 右侧内容区。 */
+@layer components {
+  .app-shell {
+    @apply grid h-full;
+    grid-template-columns: 240px 1fr;
+    grid-template-rows: 56px 1fr;
+    grid-template-areas:
+      'topbar topbar'
+      'sidebar main';
+  }
+  .topbar {
+    grid-area: topbar;
+    @apply flex items-center gap-4 border-b border-border bg-card px-4;
+  }
+  .sidebar {
+    grid-area: sidebar;
+    @apply flex flex-col gap-1 overflow-y-auto border-r border-border p-3;
+    background-color: hsl(var(--color-sidebar));
+  }
+  .main-pane {
+    grid-area: main;
+    @apply overflow-y-auto p-6;
+  }
+  .detail {
+    @apply rounded-lg border border-border bg-card p-6 text-card-foreground;
+  }
+
+  /* 点阵画布纹理（仅内容区） */
+  .canvas-dotted {
+    background-color: hsl(var(--color-background));
+    background-image: radial-gradient(hsl(var(--color-border)) 1px, transparent 1px);
+    background-size: 20px 20px;
+  }
+
+  /* markdown 正文（详情面板 raw 渲染） */
+  .markdown-body {
+    @apply text-body-sm leading-relaxed text-card-foreground;
+  }
+  .markdown-body h1 {
+    @apply mb-2 mt-5 text-h4 font-semibold;
+  }
+  .markdown-body h2 {
+    @apply mb-2 mt-5 text-body font-semibold;
+  }
+  .markdown-body h3,
+  .markdown-body h4 {
+    @apply mb-1 mt-4 text-body-sm font-semibold;
+  }
+  .markdown-body p {
+    @apply my-2;
+  }
+  .markdown-body ul {
+    @apply my-2 list-disc pl-5;
+  }
+  .markdown-body ol {
+    @apply my-2 list-decimal pl-5;
+  }
+  .markdown-body li {
+    @apply my-1;
+  }
+  .markdown-body a {
+    @apply text-primary underline;
+  }
+  .markdown-body code {
+    @apply rounded-sm bg-muted px-1 py-0.5 font-mono text-caption;
+  }
+  .markdown-body pre {
+    @apply my-3 overflow-x-auto rounded-md bg-muted p-3;
+  }
+  .markdown-body pre code {
+    @apply bg-transparent p-0 text-caption;
+  }
+  .markdown-body blockquote {
+    @apply my-2 border-l-2 border-border pl-3 text-muted-foreground;
+  }
+  .markdown-body hr {
+    @apply my-4 border-border;
+  }
+  .markdown-body table {
+    @apply my-3 w-full border-collapse text-caption;
+  }
+  .markdown-body th,
+  .markdown-body td {
+    @apply border border-border px-2 py-1 text-left;
+  }
+}

package/packages/web/src/lib/api.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { copy, open } from './api'
+
+interface FakeRes {
+  ok: boolean
+  json: () => Promise<unknown>
+}
+function stubFetch(res: FakeRes) {
+  const fn = vi.fn((_url: string, _init?: RequestInit) => Promise.resolve(res as unknown as Response))
+  vi.stubGlobal('fetch', fn)
+  return fn
+}
+
+afterEach(() => vi.unstubAllGlobals())
+
+describe('api copy/open 契约（C5 回归守卫）', () => {
+  it('copy 透传 what（含后端支持的 raw/prompt），POST /api/copy', async () => {
+    const fn = stubFetch({ ok: true, json: async () => ({ ok: true, what: 'raw', bytes: 12 }) })
+    const r = await copy('id-1', 'raw')
+    expect(r.ok).toBe(true)
+    const [url, init] = fn.mock.calls[0]
+    expect(url).toBe('/api/copy')
+    expect(JSON.parse(init!.body as string)).toEqual({ id: 'id-1', what: 'raw' })
+  })
+
+  it('copy 默认 what=path', async () => {
+    const fn = stubFetch({ ok: true, json: async () => ({ ok: true }) })
+    await copy('id-2')
+    const [, init] = fn.mock.calls[0]
+    expect(JSON.parse(init!.body as string).what).toBe('path')
+  })
+
+  it('open 透传 with，POST /api/open', async () => {
+    const fn = stubFetch({ ok: true, json: async () => ({ ok: true, with: 'finder' }) })
+    await open('id-3', 'finder')
+    const [url, init] = fn.mock.calls[0]
+    expect(url).toBe('/api/open')
+    expect(JSON.parse(init!.body as string)).toEqual({ id: 'id-3', with: 'finder' })
+  })
+
+  it('非 2xx 时仍读到 {ok:false,error}（不抛错吞掉 body）', async () => {
+    stubFetch({ ok: false, json: async () => ({ ok: false, error: "invalid 'what'" }) })
+    const r = await copy('id-4', 'path')
+    expect(r.ok).toBe(false)
+    expect(r.error).toMatch(/invalid/)
+  })
+})

package/packages/web/src/lib/api.ts

@@ -0,0 +1,77 @@
+import type { SkillItem, Stats } from '@/types'
+
+// 生产环境前端与 Fastify 同源（11520）；dev 模式由 vite proxy 转发 /api。
+const API_BASE = '/api'
+
+async function get<T>(path: string): Promise<T> {
+  const res = await fetch(`${API_BASE}${path}`)
+  if (!res.ok) throw new Error(`GET ${path} 失败: ${res.status}`)
+  return res.json() as Promise<T>
+}
+
+async function post<T>(path: string, body?: unknown): Promise<T> {
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  if (!res.ok) throw new Error(`POST ${path} 失败: ${res.status}`)
+  return res.json() as Promise<T>
+}
+
+/** 容忍非 2xx 的 POST：copy/open 在非法输入时返回 {ok:false,error}（4xx/5xx），需读取该 body */
+async function postTolerant<T>(path: string, body?: unknown): Promise<T> {
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  return res.json() as Promise<T>
+}
+
+/** 列表：返回不含 raw 的 SkillItem[] */
+export function fetchSkills(): Promise<SkillItem[]> {
+  return get<SkillItem[]>('/skills')
+}
+
+/** 详情：返回含完整 raw 的 SkillItem */
+export function fetchSkillDetail(id: string): Promise<SkillItem> {
+  return get<SkillItem>(`/skills/${encodeURIComponent(id)}`)
+}
+
+/** 统计聚合 */
+export function fetchStats(): Promise<Stats> {
+  return get<Stats>('/stats')
+}
+
+/** 手动触发重新扫描 */
+export function reload(): Promise<{ ok: boolean; items: number }> {
+  return post('/reload')
+}
+
+/** 后端 pickCopyText 支持的 what 取值（packages/server/src/index.mjs:352） */
+export type CopyWhat = 'path' | 'dir' | 'rel' | 'name' | 'raw' | 'prompt'
+export type OpenWith = 'default' | 'cursor' | 'finder'
+
+export interface CopyResult {
+  ok: boolean
+  bytes?: number
+  what?: string
+  error?: string
+}
+export interface OpenResult {
+  ok: boolean
+  opened?: string
+  with?: string
+  error?: string
+}
+
+/** 复制技能内容 / 路径到剪贴板（由后端执行） */
+export function copy(id: string, what: CopyWhat = 'path'): Promise<CopyResult> {
+  return postTolerant<CopyResult>('/copy', { id, what })
+}
+
+/** 用指定编辑器 / 访达打开技能文件 */
+export function open(id: string, withApp: OpenWith = 'default'): Promise<OpenResult> {
+  return postTolerant<OpenResult>('/open', { id, with: withApp })
+}

package/packages/web/src/lib/cn.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/** 合并 className：clsx 处理条件，tailwind-merge 去重冲突的工具类 */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}

package/packages/web/src/lib/editors.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+import { getEditorMeta, isNoneEditor, editorLabel } from '@/lib/editors'
+
+describe('editors 映射（D2 主轴 = editor）', () => {
+  it('按关键字归一着色（Claude/Codex/Hermes/Cursor）', () => {
+    expect(getEditorMeta('Claude Code').color).toBe('#D97757')
+    expect(getEditorMeta('codex').color).toBe('#10A37F')
+    expect(getEditorMeta('Hermes Agent').color).toBe('#4A5FC7')
+    expect(getEditorMeta('Cursor').color).toBe('#1F2937')
+  })
+
+  it('label 透传原值，(none) → 未分类', () => {
+    expect(getEditorMeta('Claude Code').label).toBe('Claude Code')
+    expect(getEditorMeta('(none)').label).toBe('未分类')
+    expect(editorLabel('Cursor')).toBe('Cursor')
+    expect(editorLabel('(none)')).toBe('未分类')
+  })
+
+  it('未知 editor 走兜底色（C6）', () => {
+    const meta = getEditorMeta('SomeNewTool 9000')
+    expect(meta.color).toBe('#6B7280')
+    expect(meta.icon).toBeTruthy()
+  })
+
+  it('isNoneEditor 识别空/(none)', () => {
+    expect(isNoneEditor('(none)')).toBe(true)
+    expect(isNoneEditor('')).toBe(true)
+    expect(isNoneEditor('Claude Code')).toBe(false)
+  })
+})

package/packages/web/src/lib/editors.ts

@@ -0,0 +1,70 @@
+import {
+  Sparkles,
+  Terminal,
+  Bot,
+  Code2,
+  Wind,
+  Ghost,
+  Cpu,
+  Boxes,
+  type LucideIcon,
+} from 'lucide-react'
+import type { SkillItem } from '@/types'
+
+/**
+ * editor 元数据映射（D2：导航/筛选主轴 = editor，非 brand）。
+ * editor 取值来自 Stats.byEditor 的 key（it.editor || it.source || '(none)'），
+ * 形如 "Claude Code" / "Hermes Agent" / "Cursor" / "codex" / "(none)"。
+ *
+ * 按关键字归一着色取图标；未知/缺失走兜底（C6：(none) 由调用方过滤或标注）。
+ */
+export interface EditorMeta {
+  label: string
+  /** 品牌色（hex），用于图标前景 + 半透明底 */
+  color: string
+  icon: LucideIcon
+}
+
+interface Rule {
+  test: RegExp
+  color: string
+  icon: LucideIcon
+}
+
+// 关键字优先匹配（顺序敏感：更具体的放前面）
+const RULES: Rule[] = [
+  { test: /claude|anthropic/i, color: '#D97757', icon: Sparkles },
+  { test: /codex|openai/i, color: '#10A37F', icon: Cpu },
+  { test: /hermes/i, color: '#4A5FC7', icon: Bot },
+  { test: /cursor/i, color: '#1F2937', icon: Code2 },
+  { test: /windsurf/i, color: '#10B6C4', icon: Wind },
+  { test: /kiro/i, color: '#8B5CF6', icon: Ghost },
+  { test: /copilot|github/i, color: '#24292F', icon: Terminal },
+  { test: /gemini/i, color: '#4285F4', icon: Sparkles },
+  { test: /mcp/i, color: '#2563EB', icon: Boxes },
+]
+
+const FALLBACK: Omit<EditorMeta, 'label'> = { color: '#6B7280', icon: Boxes }
+
+/** 是否为「无归属」桶（C6）——调用方据此过滤或标注「未分类」。 */
+export function isNoneEditor(key: string): boolean {
+  return !key || key === '(none)' || key.toLowerCase() === 'none'
+}
+
+/** 单条目的 editor 归属 key，与 server buildStats 口径一致（it.editor || it.source || '(none)'）。 */
+export function itemEditorKey(it: SkillItem): string {
+  return it.editor || it.source || '(none)'
+}
+
+/** 把原始 editor key 转为展示用 label（(none) → 未分类）。 */
+export function editorLabel(key: string): string {
+  return isNoneEditor(key) ? '未分类' : key
+}
+
+export function getEditorMeta(key: string): EditorMeta {
+  const label = editorLabel(key)
+  for (const r of RULES) {
+    if (r.test.test(key)) return { label, color: r.color, icon: r.icon }
+  }
+  return { label, ...FALLBACK }
+}

package/packages/web/src/lib/markdown.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest'
+import { renderMarkdown } from './markdown'
+
+describe('renderMarkdown', () => {
+  it('渲染标题与段落', () => {
+    expect(renderMarkdown('# Hi')).toContain('<h1>Hi</h1>')
+    expect(renderMarkdown('hello')).toContain('<p>hello</p>')
+  })
+
+  it('围栏代码块带 language- 前缀', () => {
+    const html = renderMarkdown('```js\nconst a = 1\n```')
+    expect(html).toContain('<pre>')
+    expect(html).toContain('language-js')
+  })
+
+  it('转义内联 HTML（防 XSS，html:false）', () => {
+    const html = renderMarkdown('<script>alert(1)</script>')
+    expect(html).not.toContain('<script>')
+    expect(html).toContain('&lt;script&gt;')
+  })
+
+  it('空/undefined 输入返回空串', () => {
+    expect(renderMarkdown('')).toBe('')
+    expect(renderMarkdown(undefined)).toBe('')
+    expect(renderMarkdown(null)).toBe('')
+  })
+})

package/packages/web/src/lib/markdown.ts

@@ -0,0 +1,14 @@
+import MarkdownIt from 'markdown-it'
+
+// html:false → 源文本里的内联 HTML 被转义（防 XSS）；只输出 markdown-it 生成的安全标签。
+// 代码块输出 <pre><code class="language-xxx">，由 index.css 的 .markdown-body 着色。
+const md = new MarkdownIt({
+  html: false,
+  linkify: true,
+  breaks: false,
+  langPrefix: 'language-',
+})
+
+export function renderMarkdown(src: string | undefined | null): string {
+  return md.render(src ?? '')
+}

package/packages/web/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from '@/App'
+import '@/index.css'
+
+const container = document.getElementById('app')
+if (!container) throw new Error('挂载节点 #app 不存在')
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+)

package/packages/web/src/types/index.ts

@@ -0,0 +1,62 @@
+// 前端镜像后端 IR（packages/scanner/src/types.d.ts 的 SkillItem）。
+// 二者需保持同步：后端字段变更时同步此文件。
+
+export type SkillKind =
+  | 'skill'
+  | 'plugin'
+  | 'mcp'
+  | 'mcp-tool'
+  | 'runbook'
+  | 'instruction'
+  | 'config'
+  | 'doc'
+  | 'agent-rule'
+
+export interface SkillItem {
+  id: string
+  kind: SkillKind
+  source: string
+  name: string
+  title?: string
+  description?: string
+  category?: string
+  editor?: string
+  brand?: string
+  product?: string
+  triggers?: string[]
+  tags?: string[]
+  paths: {
+    abs: string
+    rel?: string
+    rootKind: 'home' | 'project' | 'icloud'
+  }
+  preview: string
+  /** /api/skills 列表接口会剥离 raw，仅 /api/skills/:id 返回 */
+  raw?: string
+  links?: { label: string; url: string }[]
+  updatedAt: string
+  parseError?: string
+}
+
+export interface Stats {
+  total: number
+  bySource: Record<string, number>
+  byEditor: Record<string, number>
+  byKind: Record<string, number>
+  byCategory: Record<string, number>
+  byBrand: Record<string, number>
+  labels?: Record<string, unknown>
+}
+
+// OtherSkill 类型导出 - 前端 Hook 改造后的新类型
+export type {
+  OtherSkill,
+  OtherSkillGroup,
+  OtherSkillsOptions,
+} from './other-skill'
+export {
+  OtherSkillCategory,
+  SortBy,
+  SortOrder,
+  GroupBy,
+} from './other-skill'

package/packages/web/src/types/other-skill.ts

@@ -0,0 +1,88 @@
+/**
+ * 其它技能分类枚举 - 支持按分类、品牌、来源分组
+ */
+export enum OtherSkillCategory {
+  COMMAND = 'command',      // CLI 命令
+  EDITOR = 'editor',        // 编辑器集成
+  TOOL = 'tool',            // 工具/插件
+  CLOUD = 'cloud',          // 云服务
+  AI = 'ai',                // AI 能力
+}
+
+/**
+ * 排序顺序
+ */
+export enum SortOrder {
+  ASC = 'asc',
+  DESC = 'desc',
+}
+
+/**
+ * 排序字段
+ */
+export enum SortBy {
+  NAME = 'name',
+  UPDATED = 'updatedAt',
+  CATEGORY = 'category',
+}
+
+/**
+ * 分组方式
+ */
+export enum GroupBy {
+  CATEGORY = 'category',
+  BRAND = 'brand',
+  SOURCE = 'source',
+  NONE = 'none',
+}
+
+/**
+ * 其它技能项 - 匹配真实 SKILL.md 数据结构
+ */
+export interface OtherSkill {
+  id: string
+  name: string
+  title?: string                    // 人类可读标题
+  category?: string | string[]      // 语义分类标签（可多个）
+  brand?: string                    // 品牌标识（用于 icon）
+  source?: string                   // 来源（hermes、claude-code、cursor 等）
+  description?: string              // 简短描述
+  icon?: string                     // 自定义 icon（emoji 或字符）
+  iconUrl?: string                  // 真实应用图标 URL（如 /api/icons/cursor?size=64）
+  iconFallback?: string             // 图标加载失败时的 emoji 兜底
+  tags?: string[]                   // 搜索标签
+  docs?: string                     // 文档链接
+  links?: Array<{                   // 相关链接
+    label: string
+    url: string
+  }>
+  examples?: string[]               // 使用示例
+  updatedAt?: string                // ISO 8601 时间戳
+  parseError?: string               // 解析错误（如有）
+}
+
+/**
+ * 其它技能分组（支持多种分组方式）
+ */
+export interface OtherSkillGroup {
+  groupKey: string                  // 分组键（category、brand 等）
+  label: string                     // 显示标签
+  icon: string                      // 分组 icon
+  items: OtherSkill[]              // 该分组中的技能项
+  count: number                     // 项数统计
+}
+
+/**
+ * 搜索和过滤选项
+ */
+export interface OtherSkillsOptions {
+  query?: string                    // 搜索词
+  sortBy?: SortBy                   // 排序字段
+  sortOrder?: SortOrder             // 排序方向
+  groupBy?: GroupBy                 // 分组方式
+  filterBrand?: string              // 按品牌过滤
+  filterCategory?: string           // 按分类过滤
+  filterSource?: string             // 按来源过滤
+  limit?: number                    // 限制结果数
+  offset?: number                   // 分页偏移
+}