@wang121ye/skillmanager 0.0.3 → 0.0.5

package/README.md

@@ -4,6 +4,47 @@
 
 本项目 **基于 `openskills`** 实现安装与 `AGENTS.md` 同步。
 
+## 环境要求与兼容性（重要）
+
+`skillmanager` 会调用系统里的 `git` 拉取/更新 skills 来源仓库，并通过 `openskills` 执行安装与 `AGENTS.md` 同步。因此你的环境版本过低时，可能出现“看起来配置没问题但某些机器上失败”的情况。
+
+- **Node.js（用于运行 openskills）**：建议 **>= 20.6.0**
+  - 低于该版本可能出现语法错误（例如依赖使用了 RegExp `/v` flag）。
+- **openskills**：建议 **>= 1.5.0**（本项目依赖与运行时行为以该版本为基准）
+- **git**：建议 **>= 2.34.0**
+  - 低版本在 GitHub HTTPS + partial clone（如 `--filter=blob:none`）场景下，可能更容易遇到 TLS/gnutls 相关中断（如 `gnutls_handshake()`）。
+
+常见规避方案：
+
+- **升级 git / Node / openskills**（推荐根治）
+- **改用 SSH 拉取 GitHub 仓库**（绕开 HTTPS/TLS）：
+
+```bash
+export SKILLMANAGER_GIT_PROTOCOL=ssh
+skillmanager webui
+```
+
+- **降低并发**（网络/中间设备对并发连接敏感时）：
+
+```bash
+skillmanager webui --concurrency 1
+```
+
+### 缓存自动刷新（避免“只看到旧的 skills”）
+
+为避免第三方用户忘记更新缓存，`skillmanager` 在扫描来源仓库时会检查本地缓存是否落后于远端：
+
+- 如果检测到缓存落后，默认会**自动重新拉取**最新仓库。
+- 如需手动控制，可使用 `--force-refresh` 强制刷新，或设置 `SKILLMANAGER_AUTO_REFRESH=0` 关闭自动刷新。
+
+示例：
+
+```bash
+skillmanager webui --force-refresh
+skillmanager install --force-refresh
+skillmanager update --force-refresh
+```
+
 ## 安装与使用
 
 ### 全局安装（推荐）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wang121ye/skillmanager",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Cross-platform agent skill manager (bootstrap + optional Web UI selection) built on top of openskills.",
   "keywords": [
     "skillmanager",

package/src/cli.js

@@ -30,6 +30,7 @@ async function main() {
     .option('--dry-run', '仅打印将执行的内容，不实际安装', false)
     .option('--concurrency <n>', '选择模式下的并发扫描数（默认：3）', '3')
     .option('--profile <name>', '选择配置名（默认：来自 config 或 SKILLMANAGER_PROFILE 环境变量）')
+    .option('--force-refresh', '强制刷新来源仓库缓存（重新拉取）', false)
     .action(async (opts) => {
       await bootstrap(opts);
     });
@@ -44,6 +45,7 @@ async function main() {
     .option('--output <path>', '作用：sync 输出文件路径（默认：AGENTS.md）')
     .option('--no-sync', '作用：不执行 openskills sync（仅安装/卸载，不更新 AGENTS.md）', false)
     .option('--concurrency <n>', '作用：install 模式下并发拉取/扫描来源仓库，提高速度（默认：3）', '3')
+    .option('--force-refresh', '强制刷新来源仓库缓存（重新拉取）', false)
     .action(async (opts) => {
       await webui(opts);
     });
@@ -64,6 +66,7 @@ async function main() {
     .option('--no-sync', '跳过 openskills sync', false)
     .option('--profile <name>', '按 profile 选择集更新（会重新安装选中的 skills）')
     .option('--concurrency <n>', '选择模式下的并发扫描数（默认：3）', '3')
+    .option('--force-refresh', '强制刷新来源仓库缓存（重新拉取）', false)
     .action(async (opts) => {
       await update(opts);
     });

package/src/commands/bootstrap.js

@@ -10,6 +10,7 @@ const path = require('path');
 const os = require('os');
 const { installSourceRef, syncAgents } = require('../lib/openskills');
 const { installFromLocalSkillDir } = require('../lib/local-install');
+const { warnPrereqs } = require('../lib/prereqs');
 
 
 function uniq(arr) {
@@ -17,6 +18,7 @@ function uniq(arr) {
 }
 
 async function bootstrap(opts) {
+  await warnPrereqs({ needGit: true, needOpenSkills: true });
   const paths = getAppPaths();
   await ensureDir(paths.reposDir);
   await ensureDir(paths.profilesDir);
@@ -75,7 +77,7 @@ async function bootstrap(opts) {
   const skillsById = new Map();
   const perSource = await mapWithConcurrency(enabledSources, concurrency, async (s) => {
     try {
-      const repoDir = await ensureRepo({ reposDir: paths.reposDir, source: s });
+      const repoDir = await ensureRepo({ reposDir: paths.reposDir, source: s, forceRefresh: !!opts?.forceRefresh });
       const skills = await scanSkillsInRepo({
         sourceId: s.id,
         sourceName: s.name || s.id,

package/src/commands/update.js

@@ -10,6 +10,7 @@ const { syncAgents, runOpenSkills } = require('../lib/openskills');
 const { installFromLocalSkillDir } = require('../lib/local-install');
 const { mapWithConcurrency } = require('../lib/concurrency');
 const { getEffectiveDefaultProfile } = require('../lib/config');
+const { warnPrereqs } = require('../lib/prereqs');
 
 
 function uniq(arr) {
@@ -17,6 +18,7 @@ function uniq(arr) {
 }
 
 async function update(opts) {
+  await warnPrereqs({ needGit: true, needOpenSkills: true });
   const globalInstall = !!opts?.global;
   const universal = !!opts?.universal;
 
@@ -51,7 +53,7 @@ async function update(opts) {
   const skillsById = new Map();
   const perSource = await mapWithConcurrency(enabledSources, concurrency, async (s) => {
     try {
-      const repoDir = await ensureRepo({ reposDir: paths.reposDir, source: s });
+      const repoDir = await ensureRepo({ reposDir: paths.reposDir, source: s, forceRefresh: !!opts?.forceRefresh });
       const skills = await scanSkillsInRepo({
         sourceId: s.id,
         sourceName: s.name || s.id,

package/src/commands/webui.js

@@ -14,6 +14,7 @@ const { installFromLocalSkillDir } = require('../lib/local-install');
 const { listInstalledSkills } = require('../lib/installed');
 const { syncAgents } = require('../lib/openskills');
 const { launchSelectionUi } = require('../ui/server');
+const { warnPrereqs } = require('../lib/prereqs');
 
 function resolveTargetDir({ globalInstall, universal }) {
   const folder = universal ? '.agent/skills' : '.claude/skills';
@@ -21,6 +22,7 @@ function resolveTargetDir({ globalInstall, universal }) {
 }
 
 async function webui(opts) {
+  await warnPrereqs({ needGit: true, needOpenSkills: true });
   const modeRaw = String(opts?.mode || 'install').toLowerCase();
   const mode = modeRaw === 'uninstall' ? 'uninstall' : 'install';
 
@@ -89,7 +91,7 @@ async function webui(opts) {
   const skillsById = new Map();
   const perSource = await mapWithConcurrency(enabledSources, concurrency, async (s) => {
     try {
-      const repoDir = await ensureRepo({ reposDir: paths.reposDir, source: s });
+      const repoDir = await ensureRepo({ reposDir: paths.reposDir, source: s, forceRefresh: !!opts?.forceRefresh });
       const skills = await scanSkillsInRepo({
         sourceId: s.id,
         sourceName: s.name || s.id,

package/src/lib/git.js

@@ -10,7 +10,53 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
-async function ensureRepo({ reposDir, source }) {
+function isTruthy(value) {
+  const v = String(value || '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
+function shouldAutoRefreshCache() {
+  // 默认开启自动刷新（发现远端更新时自动重新拉取）
+  // 如需关闭：SKILLMANAGER_AUTO_REFRESH=0
+  if (process.env.SKILLMANAGER_AUTO_REFRESH != null) {
+    return isTruthy(process.env.SKILLMANAGER_AUTO_REFRESH);
+  }
+  return true;
+}
+
+async function getLocalHead(repoGit) {
+  try {
+    const out = await repoGit.revparse(['HEAD']);
+    return String(out || '').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function getRemoteHead(repoGit) {
+  try {
+    const out = await repoGit.raw(['ls-remote', 'origin', 'HEAD']);
+    const first = String(out || '').trim().split(/\s+/)[0];
+    return first || null;
+  } catch {
+    return null;
+  }
+}
+
+async function isRepoStale(repoGit) {
+  const [localHead, remoteHead] = await Promise.all([getLocalHead(repoGit), getRemoteHead(repoGit)]);
+  if (!localHead || !remoteHead) return false;
+  return localHead !== remoteHead;
+}
+
+async function cloneRepo({ git, repoUrl, repoDir, cloneArgs }) {
+  await rmDir(repoDir);
+  await ensureDir(repoDir);
+  await git.clone(repoUrl, repoDir, cloneArgs);
+  return repoDir;
+}
+
+async function ensureRepo({ reposDir, source, forceRefresh = false }) {
   if (!source?.repo) {
     throw new Error(`Invalid source repo for ${source?.id || '<unknown>'}`);
   }
@@ -20,14 +66,12 @@ async function ensureRepo({ reposDir, source }) {
 
   const gitDir = path.join(repoDir, '.git');
   const git = simpleGit();
+  const cloneArgs = ['--depth', '1', '--single-branch', '--filter=blob:none'];
 
   if (!(await fileExists(gitDir))) {
-    const cloneArgs = ['--depth', '1', '--single-branch', '--filter=blob:none'];
     for (let attempt = 1; attempt <= 3; attempt++) {
       try {
-        await rmDir(repoDir);
-        await ensureDir(repoDir);
-        await git.clone(source.repo, repoDir, cloneArgs);
+        await cloneRepo({ git, repoUrl: source.repo, repoDir, cloneArgs });
         return repoDir;
       } catch (err) {
         await rmDir(repoDir);
@@ -50,6 +94,26 @@ async function ensureRepo({ reposDir, source }) {
   } catch {
     // ignore ff-only failures (e.g. detached HEAD) — user can clean manually
   }
+
+  // 如果缓存仓库落后于远端，自动重新拉取（可用 env 关闭）
+  try {
+    const stale = await isRepoStale(repoGit);
+    if (stale) {
+      const shouldRefresh = forceRefresh || shouldAutoRefreshCache();
+      if (shouldRefresh) {
+        // eslint-disable-next-line no-console
+        console.warn(`检测到缓存仓库落后于远端：${source.id}，正在重新拉取最新版本…`);
+        return await cloneRepo({ git, repoUrl: source.repo, repoDir, cloneArgs });
+      }
+      // eslint-disable-next-line no-console
+      console.warn(`检测到缓存仓库落后于远端：${source.id}。可使用 --force-refresh 或设置 SKILLMANAGER_AUTO_REFRESH=1。`);
+    }
+  } catch {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `提示：无法检查远端版本（可能网络/权限问题），缓存可能过期。可使用 --force-refresh 强制刷新，或删除 ${repoDir} 后重试。`
+    );
+  }
   return repoDir;
 }
 

package/src/lib/prereqs.js

@@ -0,0 +1,102 @@
+const { execFile } = require('child_process');
+const fsp = require('fs/promises');
+
+const MIN_GIT = { major: 2, minor: 34, patch: 0 };
+const MIN_NODE_FOR_OPENSKILLS = { major: 20, minor: 6, patch: 0 };
+const MIN_OPENSKILLS = { major: 1, minor: 5, patch: 0 };
+
+let warnedOnce = false;
+
+function parseSemverLike(input) {
+  const s = String(input || '');
+  const m = s.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+function cmpVersion(a, b) {
+  if (!a || !b) return 0;
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  return a.patch - b.patch;
+}
+
+function fmt(v) {
+  if (!v) return '(unknown)';
+  return `${v.major}.${v.minor}.${v.patch}`;
+}
+
+async function execFileText(cmd, args) {
+  return await new Promise((resolve, reject) => {
+    execFile(cmd, args, { windowsHide: true }, (err, stdout, stderr) => {
+      if (err) return reject(err);
+      resolve(String(stdout || stderr || '').trim());
+    });
+  });
+}
+
+async function getGitVersion() {
+  const out = await execFileText('git', ['--version']).catch(() => null);
+  if (!out) return null;
+  // e.g. "git version 2.25.1" / "git version 2.44.0.windows.1"
+  return parseSemverLike(out);
+}
+
+async function getOpenSkillsVersion() {
+  try {
+    const pkgPath = require.resolve('openskills/package.json');
+    const txt = await fsp.readFile(pkgPath, 'utf8');
+    const json = JSON.parse(txt);
+    return parseSemverLike(json?.version);
+  } catch {
+    return null;
+  }
+}
+
+function getNodeVersion() {
+  return parseSemverLike(process.versions.node);
+}
+
+async function warnPrereqs({ needGit = false, needOpenSkills = false } = {}) {
+  // 只在实际运行（非 help）且需要相关能力时提示一次，避免刷屏
+  if (warnedOnce) return;
+  warnedOnce = true;
+
+  const lines = [];
+
+  if (needGit) {
+    const gitV = await getGitVersion();
+    if (!gitV) {
+      lines.push('- git：未检测到 `git`（需要安装 git 才能拉取来源仓库）。');
+    } else if (cmpVersion(gitV, MIN_GIT) < 0) {
+      lines.push(
+        `- git：检测到 ${fmt(gitV)}，建议至少 ${fmt(MIN_GIT)}。低版本在 GitHub HTTPS/partial clone 场景下可能出现 TLS/gnutls 握手中断（例如 gnutls_handshake）。`
+      );
+      lines.push('  - 建议：升级 git（或设置 `SKILLMANAGER_GIT_PROTOCOL=ssh` 使用 SSH 拉取；并避免开启 partial clone filter）。');
+    }
+  }
+
+  if (needOpenSkills) {
+    const nodeV = getNodeVersion();
+    if (nodeV && cmpVersion(nodeV, MIN_NODE_FOR_OPENSKILLS) < 0) {
+      lines.push(
+        `- Node.js：检测到 ${fmt(nodeV)}，openskills 需要至少 ${fmt(MIN_NODE_FOR_OPENSKILLS)}（否则可能出现语法错误，例如 RegExp /v flag）。`
+      );
+    }
+
+    const osV = await getOpenSkillsVersion();
+    if (!osV) {
+      lines.push('- openskills：未检测到依赖（或无法读取版本）。如需 sync/安装来源，请确保已安装 openskills。');
+    } else if (cmpVersion(osV, MIN_OPENSKILLS) < 0) {
+      lines.push(`- openskills：检测到 ${fmt(osV)}，建议至少 ${fmt(MIN_OPENSKILLS)}。`);
+    }
+  }
+
+  if (lines.length) {
+    // eslint-disable-next-line no-console
+    console.warn(['\n⚠️ 环境兼容性提示（skillmanager）', ...lines, ''].join('\n'));
+  }
+}
+
+module.exports = { warnPrereqs };
+