@wang121ye/skillmanager 0.0.2 → 0.0.4

package/README.md

@@ -4,6 +4,32 @@
 
 本项目 **基于 `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
+```
+
 ## 安装与使用
 
 ### 全局安装（推荐）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wang121ye/skillmanager",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Cross-platform agent skill manager (bootstrap + optional Web UI selection) built on top of openskills.",
   "keywords": [
     "skillmanager",
@@ -45,6 +45,6 @@
     "gray-matter": "^4.0.3",
     "openskills": "^1.5.0",
     "simple-git": "^3.27.0",
-    "undici": "^7.4.0"
+    "undici": "^6.23.0"
   }
 }

package/src/cli.js

@@ -94,7 +94,7 @@ async function main() {
   config
     .command('set-remote-profile-url')
     .description('设置远端 profile URL（用于 config push/pull）。')
-    .argument('<url>', '例如 https://<bucket>.<region>.aliyuncs.com/skillmanager_profile.json')
+    .argument('<url>', '例如 https://<bucket>.<region>.aliyuncs.com/skillmanager/')
     .action(async (url) => {
       await setRemoteProfileUrlCmd(url);
     });

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);

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;
 

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';
 

package/src/lib/http.js

@@ -1,4 +1,6 @@
 let proxyInitialized = false;
+let fetchImpl = globalThis.fetch;
+let undiciModule = null;
 
 function getProxyUrlFromEnv() {
   return (
@@ -11,18 +13,35 @@ function getProxyUrlFromEnv() {
   );
 }
 
+function getUndici() {
+  if (undiciModule) return undiciModule;
+  try {
+    // eslint-disable-next-line global-require
+    undiciModule = require('undici');
+    return undiciModule;
+  } catch {
+    return null;
+  }
+}
+
 function ensureProxyInitialized() {
   if (proxyInitialized) return;
   proxyInitialized = true;
 
   const proxyUrl = getProxyUrlFromEnv();
+  const undici = getUndici();
+
+  // 如果有 undici，就优先用它的 fetch（这样 setGlobalDispatcher 才能生效）
+  if (undici?.fetch) fetchImpl = undici.fetch.bind(undici);
+
   if (!proxyUrl) return;
 
   try {
-    // Node 20+ ships undici. Use ProxyAgent so global fetch respects proxy.
-    // eslint-disable-next-line global-require
-    const { ProxyAgent, setGlobalDispatcher } = require('undici');
-    setGlobalDispatcher(new ProxyAgent(proxyUrl));
+    if (!undici?.ProxyAgent || !undici?.setGlobalDispatcher) {
+      throw new Error('未找到 undici ProxyAgent/setGlobalDispatcher');
+    }
+
+    undici.setGlobalDispatcher(new undici.ProxyAgent(proxyUrl));
     // eslint-disable-next-line no-console
     console.log(`使用代理：${proxyUrl}`);
   } catch (e) {
@@ -35,7 +54,10 @@ function ensureProxyInitialized() {
 
 async function httpFetch(url, options) {
   ensureProxyInitialized();
-  return await fetch(url, options);
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('当前 Node 环境不支持 fetch（需要 Node 18+ 或提供 undici.fetch）');
+  }
+  return await fetchImpl(url, options);
 }
 
 module.exports = { httpFetch };

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 };
+