skillhelper 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SkillHelper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# SkillHelper
+
+> 把散落在本机、编辑器、插件与 MCP 配置中的 AI 能力，整理成一个可搜索、可理解、可持续维护的工作台。
+
+[![npm](https://img.shields.io/npm/v/skillhelper?label=npm)](https://www.npmjs.com/package/skillhelper)
+[![license](https://img.shields.io/badge/license-MIT-7c3aed)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-339933)](https://nodejs.org/)
+
+**SkillHelper** 是产品对外名称。npm 包名和 CLI 命令当前使用可发布的小写形式 `skillhelper`。
+
+## 不再靠记忆找技能
+
+AI 工作流越来越复杂：技能文件散在不同编辑器里，插件与 MCP 配置各有入口，说明大多是英文，想确认“我到底装了什么、在哪、怎么用”往往要翻目录、查配置、切窗口。
+
+SkillHelper 把这些本地能力汇总为一个清晰的面板：
+
+- **发现**：扫描编辑器技能、个人技能库、插件、MCP 配置和项目运行手册。
+- **整理**：按来源与三级结构归类，支持搜索、筛选、排序和分组。
+- **理解**：保留原始内容，并为可翻译的说明提供中文对照；命令和代码块不被误译。
+- **识别**：优先展示本机应用的真实图标，缺失时自动回退到清晰的标识。
+
+```mermaid
+flowchart LR
+  A[本机技能与配置] --> B[扫描与去重]
+  B --> C[统一索引]
+  C --> D[搜索 / 分类 / 翻译]
+  D --> E[SkillHelper 工作台]
+```
+
+## 适合谁
+
+- 同时使用 Codex、Claude、Cursor、VS Code 等 AI 开发工具的人。
+- 在维护个人技能库、插件和 MCP 服务，却缺少统一视图的人。
+- 希望让本地 AI 工作流更可见、更可检索、更便于交接的开发者和工具作者。
+
+## 60 秒上手
+
+需要 Node.js 20 或更高版本。
+
+```bash
+npm install -g skillhelper@latest
+skillhelper start
+```
+
+命令会扫描已配置的来源、在后台启动本地服务并打开浏览器。首次使用时，可先生成并调整扫描来源：
+
+```bash
+skillhelper init
+# 编辑 ~/.config/skillhelper/sources.yaml
+skillhelper restart
+```
+
+常用命令：
+
+| 命令 | 用途 |
+| --- | --- |
+| `skillhelper start` | 扫描并启动本地工作台 |
+| `skillhelper stats` | 查看扫描统计与来源概览 |
+| `skillhelper scan` | 仅扫描并输出结构化数据 |
+| `skillhelper sync` | 将当前技能同步到选定编辑器 |
+| `skillhelper stop` | 停止后台服务 |
+
+## 开发
+
+```bash
+git clone https://github.com/aquarkgn/SkillsHelper.git
+cd SkillsHelper
+npm install
+npm run dev
+```
+
+`npm run dev` 会重启本地 API 并启动 Vite 开发服务器。常用校验：
+
+```bash
+npm test
+npm run typecheck:web
+npm run typecheck:site
+npm run build:site
+```
+
+## 本地优先，也说明边界
+
+- 扫描、索引、图标缓存和用户配置保存在本机；扫描器只读取已配置的文件来源。
+- MCP 配置在进入展示层前会做敏感字段脱敏。
+- 中文对照使用翻译服务时，需要网络连接；翻译结果会缓存在本地，避免重复请求。代码块和命令保持原样。
+
+详细扫描范围、分级与图标降级规则见 [扫描技能规则](./docs/scan_skills_rules.md)。
+
+## 项目结构
+
+```text
+packages/
+├── scanner/  # 多来源扫描、去重、图标解析
+├── server/   # Fastify API、翻译与缓存
+├── web/      # 本地工作台
+└── site/     # SkillHelper 对外介绍页
+```
+
+## 推广与产品资料
+
+推广计划、镜头资产管理、发布素材规范和视频文件索引统一维护在 `.hermes/plans/skillhelper-promotion/`。这里的文档以“真实录屏为证据、AI 只辅助包装”为原则，并会随着版本发布更新。
+
+## 贡献与许可
+
+欢迎通过 [Issues](https://github.com/aquarkgn/SkillsHelper/issues) 提交问题或建议。项目采用 [MIT License](./LICENSE)。

package/bin/lib/atomic-write.mjs

@@ -0,0 +1,72 @@
+/**
+ * @file atomic-write.mjs
+ * 原子写工具：临时文件 + rename，保证进程中断不产生半截文件。
+ *
+ * 对齐 cockpit-tools 报告的"结构化编辑 + 原子写回"原则。
+ * SkillHelper 是只读扫描工具，真实写只有三处（翻译缓存、图标缓存、
+ * state.json），频率低风险低，这里只提供原子写 + 失败回退，不上
+ * 完整审计链（价值不匹配，见迭代计划 2.3）。
+ *
+ * rename 在同文件系统内原子有效。临时文件与目标文件在同一目录，
+ * 必同文件系统。若目标路径被设到跨挂载点导致 rename 失败，
+ * 回退为直接写（保留原行为，不比现状更差）。
+ *
+ * 2026-07 阶段三：从 packages/scanner/src/core/atomic-write.mjs 提到 bin/lib，
+ * 作为底层公共模块。scanner/src/core/atomic-write.mjs 改为 re-export，保持
+ * 现有 scanner 包内引用不变。paths.mjs 的 writeJson 改调本模块。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 原子写文本文件。
+ * @param {string} file - 目标文件绝对路径
+ * @param {string} content - 文本内容
+ * @param {string} [encoding='utf8']
+ * @returns {void}
+ */
+export function atomicWriteText(file, content, encoding = 'utf8') {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, content, encoding);
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    // 回退：删除可能残留的临时文件，避免堆积
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    // rename 失败（如跨文件系统）回退为直接写，保留原行为
+    fs.writeFileSync(file, content, encoding);
+  }
+}
+
+/**
+ * 原子写二进制文件（图标 png 等）。
+ * @param {string} file - 目标文件绝对路径
+ * @param {Buffer} bytes - 二进制内容
+ * @returns {void}
+ */
+export function atomicWriteBytes(file, bytes) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, bytes);
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    fs.writeFileSync(file, bytes);
+  }
+}
+
+/**
+ * 原子写 JSON 文件（pretty 格式，与原 writeJson 输出一致）。
+ * @param {string} file - 目标文件绝对路径
+ * @param {unknown} obj - 可序列化对象
+ * @param {number} [space=2] - JSON 缩进
+ * @returns {void}
+ */
+export function atomicWriteJson(file, obj, space = 2) {
+  atomicWriteText(file, JSON.stringify(obj, null, space));
+}

package/bin/lib/paths.mjs

@@ -0,0 +1,65 @@
+// XDG-style paths for skillhelper.
+// All user-side state lives under SKILLHELPER_HOME (default: ~/.config/skillhelper).
+// Nothing is written outside this dir, so `purge` cleans everything.
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { atomicWriteJson } from './atomic-write.mjs';
+
+export function homeDir() {
+  if (process.env.SKILLHELPER_HOME && process.env.SKILLHELPER_HOME.trim()) {
+    return path.resolve(expandTilde(process.env.SKILLHELPER_HOME));
+  }
+  // XDG_CONFIG_HOME respected if set, else ~/.config
+  const xdg = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim()
+    ? path.resolve(expandTilde(process.env.XDG_CONFIG_HOME))
+    : path.join(os.homedir(), '.config');
+  return path.join(xdg, 'skillhelper');
+}
+
+export function configFile() {
+  return path.join(homeDir(), 'sources.yaml');
+}
+
+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');
+}
+
+export function ensureHomeDir() {
+  const dir = homeDir();
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function expandTilde(p) {
+  if (!p) return p;
+  if (p === '~' || p.startsWith('~/')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+export function writeJson(file, obj) {
+  // v0.4 阶段三：原子写（临时文件 + rename），进程中断不残留半截 JSON。
+  // ensureHomeDir 由 atomicWriteJson 内部 mkdirSync 处理，但保留以确保与旧行为一致。
+  ensureHomeDir();
+  atomicWriteJson(file, obj);
+}
+
+export function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}

package/bin/lib/port.mjs

@@ -0,0 +1,23 @@
+// Pick a free port starting from `preferred`, walking up to `preferred + range`.
+// Returns the port that successfully bound (we then close immediately so the
+// real server can claim it). On any error or full exhaustion, returns null.
+
+import net from 'node:net';
+
+export async function pickPort(preferred = 11520, range = 10) {
+  for (let p = preferred; p <= preferred + range; p++) {
+    if (await isFree(p)) return p;
+  }
+  return null;
+}
+
+function isFree(port) {
+  return new Promise(resolve => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.once('error', () => resolve(false));
+    srv.listen({ port, host: '127.0.0.1' }, () => {
+      srv.close(() => resolve(true));
+    });
+  });
+}