skillhelper 0.4.2

package/packages/server/src/labels.mjs

@@ -0,0 +1,64 @@
+export const LABELS = {
+  sources: {
+    'hermes': 'Hermes 技能库',
+    'skills': '技能中心',
+    'project-runbook': '项目文档',
+    'mcp-config': 'MCP 配置',
+    'mcp': 'MCP 工具',
+    'codex-plugin': 'Codex 插件',
+  },
+  editors: {
+    'Hermes Agent': 'Hermes 代理',
+    'Skills Hub': '技能中心',
+    'Project Docs': '项目文档',
+    'MCP': 'MCP',
+    'MCP Hub': 'MCP 中心',
+  },
+  kinds: {
+    'skill': '技能',
+    'runbook': '手册',
+    'config': '配置',
+    'mcp-tool': 'MCP 工具',
+    'mcp': 'MCP',
+    'plugin': '插件',
+  },
+  categories: {
+    'devops': '云原生运维',
+    'mlops': '机器学习运维',
+    'software-development': '软件开发',
+    'creative': '创意工具',
+    'productivity': '生产力工具',
+    'research': '研究',
+    'apple': 'Apple 生态',
+    'media': '媒体处理',
+    'gaming': '游戏',
+    'red-teaming': '红队测试',
+    'github': 'GitHub',
+    'email': '邮件',
+    'leisure': '休闲娱乐',
+    'smart-home': '智能家居',
+    'social-media': '社交媒体',
+    'mcp': 'MCP 协议',
+    'note-taking': '笔记',
+    'skillhelper': '呼哈哈-技能助手',
+    'autonomous-ai-agents': '自主 AI 代理',
+    'kanban': '看板',
+    'eslint': 'ESLint',
+  },
+  brands: {
+    'GitHub': 'GitHub',
+    'OpenAI': 'OpenAI',
+    'Anthropic': 'Anthropic',
+    'Apple': 'Apple',
+    'Docker': 'Docker',
+    'HuggingFace': 'Hugging Face',
+    'Claude Code': 'Claude Code',
+    'Suno': 'Suno',
+    'Kubernetes': 'Kubernetes',
+    'Telegram': 'Telegram',
+    'Cloudflare': 'Cloudflare',
+    'Modal': 'Modal',
+    'Linear': 'Linear',
+    'Hermes': 'Hermes',
+  }
+};

package/packages/server/src/langdetect.mjs

@@ -0,0 +1,34 @@
+// 语言判定 —— 本地零依赖，不走外网。
+// 目的：在调用翻译 API 前短路掉已是中文的文本，避免无意义的外网请求。
+//
+// 判定规则：统计 CJK 统一表意文字（U+4E00–U+9FFF）在文本中的占比。
+// 占比 >= 30% 视为中文，跳过翻译。技能描述多为英文夹中文术语
+// （如"使用 MCP 协议"），纯中文描述远超 30%，纯英文描述为 0%，
+// 阈值不敏感。
+
+/**
+ * 判定文本是否为中文
+ * @param {string} text - 待判定文本
+ * @returns {boolean} true 表示已是中文，无需翻译
+ */
+export function isChinese(text) {
+  if (!text || !text.trim()) return true; // 空文本视为无需翻译
+  const cjk = (text.match(/[一-鿿]/g) || []).length;
+  return cjk / text.length >= 0.3;
+}
+
+/**
+ * 检测文本源语言代码（用于翻译缓存的 from 字段）。
+ * google-translate-api-x 偶发不返回 from.language.code（部分文本 Google 无法判定源语言），
+ * 用本地检测兜底，避免 from 字段落盘为 'unknown'。
+ *
+ * 判定逻辑与 isChinese 一致：CJK 占比 >= 30% 视为中文，否则视为英文
+ * （技能描述以英文为主，其他语言罕见；中文已由 isChinese 判定）。
+ *
+ * @param {string} text - 待判定文本
+ * @returns {'zh'|'en'|'unknown'} 语言代码
+ */
+export function detectLanguage(text) {
+  if (!text || !text.trim()) return 'unknown';
+  return isChinese(text) ? 'zh' : 'en';
+}

package/packages/server/src/llm-client.mjs

@@ -0,0 +1,42 @@
+export const ANTHROPIC_MODEL = 'claude-sonnet-4-6';
+
+export async function callAnthropic(prompt, { max_tokens } = {}) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    throw new Error('ANTHROPIC_API_KEY not set');
+  }
+  if (!prompt || typeof prompt !== 'string') {
+    throw new Error('prompt must be a non-empty string');
+  }
+  if (!Number.isInteger(max_tokens) || max_tokens <= 0) {
+    throw new Error('max_tokens must be a positive integer');
+  }
+
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': process.env.ANTHROPIC_API_KEY,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: ANTHROPIC_MODEL,
+      max_tokens,
+      messages: [{
+        role: 'user',
+        content: prompt,
+      }],
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Anthropic API: ${response.status} ${error}`);
+  }
+
+  const data = await response.json();
+  const text = data?.content?.[0]?.text;
+  if (typeof text !== 'string' || !text.trim()) {
+    throw new Error('Anthropic API returned empty text');
+  }
+  return text;
+}

package/packages/server/src/translate-cache.mjs

@@ -0,0 +1,132 @@
+// 翻译缓存 —— 双层结构：进程内 Map（热路径）+ 磁盘 JSON（跨重启）。
+// key = md5(text)：不同技能若描述相同则共享缓存条目；文件更新导致
+// text 变化时 md5 自然不同，自动重译，无需 mtime 比对。
+//
+// 风格对齐 icon-extractor.mjs：内存 Map 命中即返回，磁盘异步落盘。
+// purge 命令删除整个 SKILLHELPER_HOME 目录，本缓存文件随之清理。
+
+import crypto from 'node:crypto';
+import { translateCacheFile, ensureHomeDir, readJson, writeJson } from '../../../bin/lib/paths.mjs';
+
+const CACHE_VERSION = 1;
+const FLUSH_DELAY = 500; // 防抖落盘，避免高频写
+
+let memoryCache = new Map();
+let dirty = false;
+let flushTimer = null;
+let loaded = false;
+
+function md5(text) {
+  return crypto.createHash('md5').update(text, 'utf8').digest('hex');
+}
+
+// LRU 上限：避免 translate-cache.json 无限膨胀。动态读取环境变量（测试用小值）。
+function getMaxEntries() {
+  return parseInt(process.env.SKILLHELPER_TRANSLATE_CACHE_MAX || '5000', 10);
+}
+
+function load() {
+  if (loaded) return;
+  loaded = true;
+  const data = readJson(translateCacheFile(), null);
+  if (data && data.version === CACHE_VERSION && data.entries) {
+    memoryCache = new Map(Object.entries(data.entries));
+    // 加载时若超限，按 LRU 淘汰最旧条目
+    evictIfNeeded();
+  }
+}
+
+/** LRU 淘汰：Map 迭代顺序 = 插入顺序，首个即最久未使用 */
+function evictIfNeeded() {
+  const max = getMaxEntries();
+  while (memoryCache.size > max) {
+    const oldest = memoryCache.keys().next().value;
+    if (oldest === undefined) break;
+    memoryCache.delete(oldest);
+    dirty = true;
+  }
+}
+
+/**
+ * 查询缓存（LRU 命中时移到末尾，标记最近使用）
+ * @param {string} text - 原文
+ * @returns {{from:string,to:string,result:string,translatedAt:string}|null} 缓存条目或 null
+ */
+export function getCached(text) {
+  load();
+  const key = md5(text);
+  const entry = memoryCache.get(key);
+  if (entry) {
+    // LRU: 命中时移到末尾（最近使用）
+    memoryCache.delete(key);
+    memoryCache.set(key, entry);
+  }
+  return entry || null;
+}
+
+/**
+ * 写入缓存（内存立即生效，磁盘防抖落盘）。LRU 超限时淘汰最旧条目。
+ * @param {string} text - 原文
+ * @param {string} result - 译文
+ * @param {string} from - 源语言代码（如 'en'）
+ */
+export function setCached(text, result, from) {
+  load();
+  const key = md5(text);
+  // LRU: 命中时先 delete 再 set，移到末尾（最近使用）
+  if (memoryCache.has(key)) memoryCache.delete(key);
+  memoryCache.set(key, {
+    from: from || 'unknown',
+    to: 'zh-CN',
+    text,
+    result,
+    translatedAt: new Date().toISOString(),
+  });
+  evictIfNeeded();
+  dirty = true;
+  scheduleFlush();
+}
+
+function scheduleFlush() {
+  if (flushTimer) return;
+  flushTimer = setTimeout(() => {
+    flushTimer = null;
+    flush();
+  }, FLUSH_DELAY);
+}
+
+/**
+ * 立即落盘。进程退出前应调用一次（onClose 钩子）。
+ */
+export function flush() {
+  if (!dirty) return;
+  ensureHomeDir();
+  const data = { version: CACHE_VERSION, entries: Object.fromEntries(memoryCache) };
+  try {
+    writeJson(translateCacheFile(), data);
+    dirty = false;
+  } catch (e) {
+    console.warn(`[translate-cache] flush failed: ${e.message}`);
+  }
+}
+
+/**
+ * 获取缓存条目数（测试 / 诊断用）
+ */
+export function size() {
+  load();
+  return memoryCache.size;
+}
+
+/**
+ * 重置缓存（仅测试用：清空内存并标记未加载，以便切换 SKILLHELPER_HOME 后重新加载）
+ */
+export function _resetForTest() {
+  memoryCache = new Map();
+  dirty = false;
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  loaded = false;
+}

package/packages/server/src/translator.mjs

@@ -0,0 +1,53 @@
+// 旧模式：整技能对象翻译，依赖 ANTHROPIC_API_KEY（需密钥，按全局规则使用前需询问）。
+// 推荐使用 packages/server/src/index.mjs 的 translateText（Google 免费 + md5 缓存）。
+// 本模块保留以兼容 /api/translate 的 id 旧模式调用，新代码勿直接依赖。
+import { ANTHROPIC_MODEL, callAnthropic } from './llm-client.mjs';
+
+export async function translateSkill(skill, targetLang = 'zh-CN') {
+  if (targetLang !== 'zh-CN' || skill.i18n?.name_zh) return skill;
+
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.warn('[translator] ANTHROPIC_API_KEY not set, skipping translation');
+    return skill;
+  }
+
+  const prompt = `Translate these skill metadata to Chinese (简体中文). Return JSON only, no markdown.
+
+Current metadata:
+- name: ${skill.name}
+- description: ${skill.description || '(none)'}
+- category: ${skill.category || '(none)'}
+
+Return JSON format (translate only the values):
+{
+  "name_zh": "中文名称",
+  "description_zh": "中文描述",
+  "category_zh": "中文分类"
+}
+
+Guidelines:
+- Keep technical terms like "API", "MCP", "LLM" in English when appropriate
+- Use common Chinese equivalents for concepts (e.g., "skill" → "技能", "rule" → "规则")
+- Keep descriptions concise (under 100 chars)
+- Preserve the technical meaning
+- Return valid JSON only`;
+
+  try {
+    const text = await callAnthropic(prompt, { max_tokens: 500 });
+    const translated = JSON.parse(text);
+
+    return {
+      ...skill,
+      i18n: {
+        name_zh: translated.name_zh,
+        description_zh: translated.description_zh,
+        category_zh: translated.category_zh,
+        translatedAt: new Date().toISOString(),
+        translationModel: ANTHROPIC_MODEL,
+      },
+    };
+  } catch (e) {
+    console.error(`[translator] error: ${e.message}`);
+    return skill;
+  }
+}

package/packages/web/README.md

@@ -0,0 +1,36 @@
+# @skillhelper/web
+
+SkillHelper 的前端 SPA：**Vite + React 18 + TypeScript(strict) + Tailwind + shadcn 风格组件**。
+
+## 构建与托管
+
+- 产物输出到 `dist/`，由 `packages/server`（Fastify）静态托管：
+  - `dist/index.html` → `GET /`
+  - `dist/assets/*` → `GET /assets/*`
+- 仓库根目录 `npm run build:web` 会调用本包的 `vite build`。
+- 生产访问入口：`http://localhost:11520`（由 `npm start` 启动 Fastify）。
+
+## 本地开发
+
+```bash
+# 终端 A：启动后端 API（11520）
+npm start            # 仓库根目录
+
+# 终端 B：启动前端 dev server（11521，/api 代理到 11520）
+cd packages/web && npm run dev
+```
+
+## 目录
+
+```
+src/
+├── main.tsx              # 入口，挂载到 #app
+├── index.css            # 主题 token + 三栏布局类
+├── types.ts             # SkillItem / Stats（镜像后端 IR）
+├── lib/{cn,api}.ts      # 类名合并 / 后端 API 客户端
+├── hooks/useTheme.ts    # 亮/暗主题切换
+├── components/ui/        # shadcn 风格基础组件
+└── components/layout/    # Sidebar / Topbar
+```
+
+设计规范见 `docs/Frontend-Theme-Design.md`，框架说明见 `docs/Frontend-Framework-Setup.md`。