@morehao/dsh-skills-console 0.2.3 → 0.2.4

package/README.md

@@ -41,6 +41,8 @@ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入
 
 ## 安装
 
+插件依赖里自带 `skills@1.7.4`，**不需要用户预装 Node / npm / npx**：CLI 由宿主自带的 Node 启动，装插件时随依赖一起落盘。安装技能仍需要**本机有 git**（CLI 会 `git clone` 仓库）；首次装插件需要联网拉取依赖。
+
 在 Harness 里装本地 link：
 
 ```bash
@@ -55,7 +57,7 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
       name: '@morehao/dsh-skills-console'
 ```
 
-客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。
+客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。本地 `link:` 开发时，先在仓库跑一次 `npm install`（装上 `skills`），否则 CLI 依赖层不会命中。
 
 ## 快速上手
 
@@ -66,7 +68,7 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 
 ## 可靠性
 
-- **canonical 与 CLI lock 只读**：`~/.agents/skills`、`~/.agents/.skill-lock.json` 的增删改只经 `skills` CLI，插件不直接写；探测 / 更新检查会把仓库临时 clone 到 `os.tmpdir()`（只读、用完即删），结果绝不落进 canonical 或 lock。
+- **canonical 与 CLI lock 只读**：`~/.agents/skills`、`~/.agents/.skill-lock.json`（设了 `XDG_STATE_HOME` 时为 `$XDG_STATE_HOME/skills/.skill-lock.json`）的增删改只经 `skills` CLI，插件不直接写；探测 / 更新检查会把仓库临时 clone 到 `os.tmpdir()`（只读、用完即删），结果绝不落进 canonical 或 lock。
 - **只动自己的东西**：只处理本插件创建的 `managed` 链接，以及已记账的 `managed-external`；`real` 目录和 `foreign-link` 永不改写，删除前体检直接中止。
 - **启停不改正文**：`mode` 只增删 DSH 侧链接，避免本地修改被下一次 `add` 覆盖。
 - **可回滚**：删除进回收站（7 天）；更新前快照到 `backups/`，失败自动还原（接口另提供手动回滚）。
@@ -78,7 +80,7 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 | 项 | 路径 | 归属 |
 | --- | --- | --- |
 | canonical 真身 | `~/.agents/skills` | `skills` CLI 独占 |
-| CLI lock | `~/.agents/.skill-lock.json` | `skills` CLI 独占（本插件只读） |
+| CLI lock | `~/.agents/.skill-lock.json`（设了 `XDG_STATE_HOME` 时为 `$XDG_STATE_HOME/skills/.skill-lock.json`） | `skills` CLI 独占（本插件只读） |
 | DSH 全局根 | `~/.dsh/skills` | 本插件写软链 |
 | 插件状态 | `$DSH_HOME/skills-console/state.json` | 本插件（`DSH_SKILLS_CONSOLE_HOME` 可覆盖） |
 | 备份 / 回收站 | `$DSH_HOME/skills-console/{backups,trash}` | 本插件 |
@@ -90,11 +92,12 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 | --- | --- | --- |
 | `DSH_SKILLS_CONSOLE_HOME` | `$DSH_HOME/skills-console` | 状态、备份、回收站与事件日志的根 |
 | `DSH_SKILLS_CONSOLE_CLI` | 自动定位 | 覆盖 `skills` CLI（测试桩也走这里） |
-| `DSH_SKILLS_CONSOLE_NPX_SPEC` | `skills` | 需要 `npx` 兜底时用的包名 / 版本 |
+| `DSH_SKILLS_CONSOLE_NPX_SPEC` | `skills` | 仅 legacy `npx` 兜底用；桌面端没有 npx，正常应显示 `dependency` |
 | `DSH_SKILLS_CONSOLE_TIMEOUT_MS` | `120000` | 单次 CLI 调用超时 |
 | `DSH_SKILLS_CONSOLE_GIT` | `auto` | 设为 `off` 关闭 git 通道，强制只走 GitHub REST |
 | `DSH_SKILLS_CONSOLE_GIT_TIMEOUT_MS` | `60000` | git 单次操作（`ls-remote` / `clone`）超时 |
 | `GITHUB_TOKEN` / `GH_TOKEN` | 无 | 只读环境变量；带上后 REST 配额从匿名 60 次/小时提到 5000 次/小时 |
+| `XDG_STATE_HOME` | 未设置 | 设置后 CLI lock 移到 `$XDG_STATE_HOME/skills/.skill-lock.json`，插件跟随读取 |
 
 关于 GitHub 配额：**匿名 REST 是 60 次/小时，按出口 IP 共享**（公司、校园网出口常被同网段的人一起打满），打满后探测与更新会收到 403。本插件默认让探测、更新检查与 git 兜底走系统 `git`（`ls-remote` + `clone --filter=blob:none --no-checkout`），不占 REST 配额、也不需要 token；git 不可用时才回退 REST，所以原本能用的环境不会因为这条路径变坏。限流且 git 也不可用时，错误文案会给出恢复时间，并提示设置 `GITHUB_TOKEN`。
 

package/lib/core/cli.js

@@ -40,10 +40,15 @@ function findInPath(command, envPath) {
 }
 
 /**
- * CLI 定位四层（设计 §8.2）：显式覆盖 → 插件/宿主自带依赖 → PATH → npx。
+ * CLI 定位顺序：显式覆盖 → 本插件依赖 → 宿主 profile → PATH → npx（legacy）。
+ * 插件依赖排在 profile 前面：版本随插件锁死，不被 PATH 或别的插件带的旧版抢占。
  * 每一层都记来源，诊断页要展示"这次到底跑的哪一个"。
  */
-export function locateCli({ env = process.env, logger = () => {} } = {}) {
+export function locateCli({
+  env = process.env,
+  logger = () => {},
+  resolvePackage = () => require.resolve('skills/package.json'),
+} = {}) {
   const override = env.DSH_SKILLS_CONSOLE_CLI;
   if (override && override.trim()) {
     const parts = override.trim().split(/\s+/);
@@ -51,7 +56,20 @@ export function locateCli({ env = process.env, logger = () => {} } = {}) {
     return { command: parts[0], prefixArgs: parts.slice(1), source: 'env-override', jsonCapable: true };
   }
 
-  // 宿主 profile 里的 skills 依赖（最常见的实际位置）。
+  // 插件自己的 runtime 依赖：装插件时由宿主 pnpm 一起装好，用户不需要 Node/npm/npx。
+  try {
+    const pkg = resolvePackage();
+    const bin = path.join(path.dirname(pkg), 'bin', 'cli.mjs');
+    if (fs.existsSync(bin)) {
+      return { command: process.execPath, prefixArgs: [bin], source: 'dependency', jsonCapable: true };
+    }
+    // 包在但入口丢了，说明安装不完整；交给后面的层兜底，但要留痕
+    logger('cli.dependency.bin-missing', { pkg, bin });
+  } catch {
+    // 没装在本插件可见范围内（例如 link: 开发仓库还没 npm install），继续往下走
+  }
+
+  // 宿主 profile 里的 skills 依赖（兼容旧插件 / 其他插件已经带进来的版本）。
   // 注意：GUI 启动的宿主进程常常拿不到 DSH_PROFILE_DIR，所以再按 DSH_HOME/profiles/* 兜一层探测。
   const profileDir = env.DSH_PROFILE_DIR;
   if (profileDir) {
@@ -74,16 +92,6 @@ export function locateCli({ env = process.env, logger = () => {} } = {}) {
     // 没有 profiles 目录就继续往下走
   }
 
-  try {
-    const pkg = require.resolve('skills/package.json');
-    const bin = path.join(path.dirname(pkg), 'bin', 'cli.mjs');
-    if (fs.existsSync(bin)) {
-      return { command: process.execPath, prefixArgs: [bin], source: 'dependency', jsonCapable: true };
-    }
-  } catch {
-    // 没有作为依赖装在本插件可见范围内，继续往下走
-  }
-
   const onPath = findInPath('skills', env.PATH);
   if (onPath) return { command: onPath, prefixArgs: [], source: 'path', jsonCapable: true };
 
@@ -105,8 +113,13 @@ export function runCli(location, args, { timeoutMs = 120000, signal, env = proce
       stdio: ['ignore', 'pipe', 'pipe'],
       env: {
         ...env,
+        // 桌面宿主本身就是 Electron 的 Node 模式；显式补上，避免调用方传了裁剪过的 env
+        ...(process.versions.electron && location.command === process.execPath ? { ELECTRON_RUN_AS_NODE: '1' } : {}),
         CI: '1',
         NO_COLOR: '1',
+        // CLI 的遥测只看这两个变量；CI=1 不会关闭，只会在上报里打 ci=1 标记
+        DO_NOT_TRACK: '1',
+        DISABLE_TELEMETRY: '1',
         TERM: 'dumb',
         GIT_TERMINAL_PROMPT: '0',
         GIT_HTTP_LOW_SPEED_LIMIT: '1',
@@ -151,12 +164,12 @@ export function runCli(location, args, { timeoutMs = 120000, signal, env = proce
   });
 }
 
-export function createCli({ env = process.env, logger = () => {} } = {}) {
+export function createCli({ env = process.env, logger = () => {}, resolvePackage } = {}) {
   let cached = null;
   let capabilities = null;
 
   function location() {
-    if (!cached) cached = locateCli({ env, logger });
+    if (!cached) cached = locateCli({ env, logger, resolvePackage });
     return cached;
   }
 
@@ -178,7 +191,16 @@ export function createCli({ env = process.env, logger = () => {} } = {}) {
     /** 能力位：`--json` 与 `--full-depth` 任一不支持都要在 UI 上禁用写操作（漏装比不可用更危险）。 */
     async capabilities({ force = false } = {}) {
       if (capabilities && !force) return capabilities;
-      const loc = location();
+      let loc;
+      try {
+        loc = location();
+      } catch (error) {
+        if (!(error instanceof CliUnavailableError)) throw error;
+        // 不缓存：用户补好依赖 / PATH 后，下一次 /state 就能恢复，不必重启宿主；
+        // 同时清掉旧的成功缓存，避免 force 探测到 missing 后又回落到上一轮的 usable。
+        capabilities = null;
+        return { version: null, json: false, fullDepth: false, source: 'missing', usable: false };
+      }
       if (!loc.jsonCapable) {
         capabilities = { version: null, json: false, fullDepth: false, source: loc.source, usable: false };
         return capabilities;

package/lib/core/paths.js

@@ -12,6 +12,10 @@ export function createPaths(env = process.env, overrides = {}) {
   const dshHome = overrides.dshHome ?? env.DSH_HOME ?? path.join(home, '.dsh');
   const stateDir =
     overrides.stateDir ?? env.DSH_SKILLS_CONSOLE_HOME ?? path.join(dshHome, 'skills-console');
+  // 与 skills CLI 的 getSkillLockPath 对齐：设了 XDG_STATE_HOME 时 lock 在 XDG 下
+  const lockFile = env.XDG_STATE_HOME
+    ? path.join(env.XDG_STATE_HOME, 'skills', '.skill-lock.json')
+    : path.join(home, '.agents', '.skill-lock.json');
 
   return {
     home,
@@ -20,8 +24,8 @@ export function createPaths(env = process.env, overrides = {}) {
     stateDir,
     /** canonical 真身：CLI 唯一的落点（F1） */
     canonical: path.join(home, '.agents', 'skills'),
-    /** CLI 全局 lock（F4） */
-    lockFile: path.join(home, '.agents', '.skill-lock.json'),
+    /** CLI 全局 lock（F4）；XDG_STATE_HOME 优先，与 CLI 一致 */
+    lockFile,
     /** DSH 原生 user-dsh 根（rank 400） */
     dshGlobalSkills: path.join(dshHome, 'skills'),
     stateFile: path.join(stateDir, 'state.json'),

package/lib/core/service.js

@@ -33,6 +33,27 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+// skills CLI 对任意 GitHub 仓库走 git clone；没装 git 时它把错误打在 stdout（spinner）里
+const GIT_MISSING_RE = /spawn git ENOENT|git: command not found|not recognized as an internal or external command/i;
+
+/** 把 CLI 的 add 失败翻译成可执行错误；git 缺失时不要只给一句 spawn ENOENT。 */
+function cliAddFailure(result, action) {
+  const detail = {
+    code: result.code,
+    stderr: (result.stderr || '').slice(-2000),
+    stdout: (result.stdout || '').slice(-2000),
+  };
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  if (GIT_MISSING_RE.test(output)) {
+    return new ServiceError(
+      'error.skills.git-missing',
+      '安装/更新技能需要本机有 git（skills CLI 会 clone 仓库）；请安装 git 后重试',
+      detail,
+    );
+  }
+  return new ServiceError('error.skills.cli-failed', `skills ${action} 失败`, detail);
+}
+
 /** 本机时区的 `HH:mm`。手写而不是 `toLocaleTimeString`：不受 ICU / locale 差异影响。 */
 function formatClock(ms) {
   const at = new Date(ms);
@@ -192,6 +213,19 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     if (store.readOnly) throw new StateReadOnlyError(store.problem);
   }
 
+  /** 所有会调 CLI 的写操作共用；缺失时给 400，不要把裸 CliUnavailableError 漏成 500。 */
+  async function requireUsableCli() {
+    const capabilities = await cli.capabilities();
+    if (!capabilities.usable) {
+      throw new ServiceError(
+        'error.skills.cli-missing',
+        'skills CLI 不可用或不支持 --json/--full-depth，写操作已禁用',
+        capabilities,
+      );
+    }
+    return capabilities;
+  }
+
   function detectedTargets() {
     return registry.detected();
   }
@@ -831,10 +865,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
     async install({ source, subscriptionId, skills = [], commit, targets, scopeProjects = [] }) {
       assertWritable();
-      const capabilities = await cli.capabilities();
-      if (!capabilities.usable) {
-        throw new ServiceError('error.skills.cli-missing', 'skills CLI 不可用或不支持 --json/--full-depth，写操作已禁用', capabilities);
-      }
+      await requireUsableCli();
       // 技能名可留空：有订阅快照就装快照里的条目，否则交给 CLI 的 `--skill '*'`（整仓全部）
       const requested = (skills || []).filter(Boolean);
 
@@ -853,12 +884,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
         const result = await cli.add({ source: sourceArg, skills: planned });
         if (result.timedOut) throw new ServiceError('error.skills.cli-timeout', 'skills add 超时');
-        if (result.code !== 0) {
-          throw new ServiceError('error.skills.cli-failed', 'skills add 失败', {
-            code: result.code,
-            stderr: result.stderr.slice(-2000),
-          });
-        }
+        if (result.code !== 0) throw cliAddFailure(result, 'add');
         // 留空时实际装了哪些技能以 CLI 的 JSON 输出为准（可能不止一个）
         const names = planned.length > 0 ? planned : installedNamesFrom(result.stdout);
         if (names.length === 0) {
@@ -947,6 +973,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
     async remove({ name }) {
       assertWritable();
+      await requireUsableCli(); // 快照与体检之前就拒绝，避免留下孤儿 trash
       return enqueue(`remove:${name}`, async () => {
         const canonicalPath = path.join(paths.canonical, name);
         if (!fs.existsSync(canonicalPath)) {
@@ -1341,6 +1368,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
     async applyUpdate({ name, token, overwrite = false }) {
       assertWritable();
+      await requireUsableCli();
       return enqueue(`apply:${name}`, async () => {
         const plan = await this.planUpdate({ name });
         if (token && token !== plan.token) {
@@ -1371,12 +1399,21 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
         if (result.code !== 0 || !present || !verified) {
           if (backup) restoreBackup({ backup, toDir: canonicalPath });
+          const failure = result.code !== 0 ? cliAddFailure(result, 'add') : null;
+          const gitMissing = failure?.code === 'error.skills.git-missing';
           logger('updates.apply.failed', { name, code: result.code, verified, present });
+          const suffix = backup ? '；已回滚到上一版' : '；没有可回滚的备份';
           return {
             ok: false,
-            code: 'error.skills.update-failed',
-            message: backup ? '更新失败，已回滚到上一版' : '更新失败，没有可回滚的备份',
-            detail: { cliCode: result.code, verified, present, stderr: result.stderr.slice(-2000) },
+            code: gitMissing ? failure.code : 'error.skills.update-failed',
+            message: gitMissing ? `${failure.message}${suffix}` : `更新失败${suffix}`,
+            detail: {
+              cliCode: result.code,
+              verified,
+              present,
+              stderr: (result.stderr || '').slice(-2000),
+              ...(failure?.detail || {}),
+            },
             backup: backup?.key || null,
           };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morehao/dsh-skills-console",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "统一管理本地技能的安装、更新、删除与接入，让同一份技能在多个 Agent 间复用。A skill manager for DeepSeek Harness: install, update, remove, link and toggle agent skills.",
   "license": "MIT",
   "author": "morehao <morehao@qq.com>",
@@ -68,6 +68,9 @@
     "dsh-plugin",
     "skills"
   ],
+  "dependencies": {
+    "skills": "1.7.4"
+  },
   "devDependencies": {
     "esbuild": "0.28.2"
   }