@morehao/dsh-skills-console 0.2.0 → 0.2.2

package/icon.svg

@@ -1,4 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Skills Manager">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="技能控制台">
+  <title>技能控制台</title>
   <defs>
     <linearGradient id="dshsc-icon-bg" x1="6" y1="2" x2="58" y2="62" gradientUnits="userSpaceOnUse">
       <stop stop-color="#3b82f6"/>

package/lib/core/cli.js

@@ -213,10 +213,12 @@ export function createCli({ env = process.env, logger = () => {} } = {}) {
 
     /**
      * 安装：`-a universal` 必带（F17），`--json` 配 `-y`（F11），`--full-depth` 必带（F24）。
+     * 技能名留空 = `--skill '*'`（整仓全部）；不能留空值的 `--skill`，那会把后面的 `-a` 当成它的参数。
      * 永不带 `--all` / `-a '*'`。
      */
     async add({ source, skills = [], timeoutMs = env.DSH_SKILLS_CONSOLE_TIMEOUT_MS ? Number(env.DSH_SKILLS_CONSOLE_TIMEOUT_MS) : 120000 }) {
-      const args = ['add', source, '--skill', ...skills, '-a', 'universal', '-g', '-y', '--json', '--full-depth'];
+      const names = skills.length > 0 ? skills : ['*'];
+      const args = ['add', source, '--skill', ...names, '-a', 'universal', '-g', '-y', '--json', '--full-depth'];
       const result = await call(args, { timeoutMs });
       return result;
     },

package/lib/core/links.js

@@ -55,7 +55,7 @@ export function inspectTarget({ linkPath, canonicalPath }) {
 }
 
 /**
- * 建链：同层用相对路径（可跨机器迁移），算不出相对就退回绝对路径并标记。
+ * 建链：同层用相对路径（可跨机器复用），算不出相对就退回绝对路径并标记。
  * Windows 用 junction + 绝对路径（对齐 CLI 的 createSymlink，F2）。
  */
 export function createLink({ linkPath, targetPath, platform = process.platform, fsImpl = fs }) {

package/lib/core/service.js

@@ -7,6 +7,7 @@ import { buildLedger, readLock, scanCanonical } from './inventory.js';
 import { createBackup, readBackup, restoreBackup, trashSkill } from './trash.js';
 import {
   checkSkill,
+  fetchDefaultBranch,
   fetchTree,
   listSkillsFromTree,
   parseSource,
@@ -30,6 +31,83 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+/** `skills add --json` 的输出：数组或 `{ installed: [...] }`，只取 name 并去重。 */
+function installedNamesFrom(stdout) {
+  try {
+    const parsed = JSON.parse(stdout);
+    const rows = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.installed) ? parsed.installed : [];
+    const names = rows.map((row) => (typeof row === 'string' ? row : row?.name)).filter(Boolean);
+    return [...new Set(names)];
+  } catch {
+    return [];
+  }
+}
+
+/** 极简 frontmatter 解析：只取 CLI 安装必需的两项（name / description）。 */
+function parseSkillFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(String(text || ''));
+  if (!match) return {};
+  const lines = match[1].split(/\r?\n/);
+  const fields = {};
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line || /^\s/.test(line)) continue;
+    const colon = line.indexOf(':');
+    if (colon <= 0) continue;
+    const key = line.slice(0, colon).trim();
+    if (key !== 'name' && key !== 'description') continue;
+    let value = line.slice(colon + 1).trim();
+    const block = /^([|>])[+-]?$/.exec(value);
+    if (block) {
+      const folded = block[1] === '>';
+      const rows = [];
+      while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+        rows.push(lines[index + 1].replace(/^\s+/, ''));
+        index += 1;
+      }
+      value = folded ? rows.join(' ') : rows.join('\n');
+    } else if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      const quote = value[0];
+      value = value.slice(1, -1);
+      if (quote === '"') value = value.replace(/\\"/g, '"').replace(/\\n/g, '\n');
+    }
+    fields[key] = value.trim();
+  }
+  return fields;
+}
+
+/** 用 raw 内容补 frontmatter 里的真实技能名/描述（CLI 按 name 安装）；取不到就回落目录名。 */
+async function enrichSkillEntries({ source, ref, entries, token, fetchImpl, concurrency = 8 }) {
+  const results = new Array(entries.length);
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < entries.length) {
+      const index = cursor;
+      cursor += 1;
+      results[index] = await inspectSkillEntry({ source, ref, entry: entries[index], token, fetchImpl });
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, entries.length) }, worker));
+  return results;
+}
+
+async function inspectSkillEntry({ source, ref, entry, token, fetchImpl }) {
+  const fallback = { name: entry.name, description: '', skillPath: entry.skillPath, valid: true };
+  try {
+    const url = `https://raw.githubusercontent.com/${source}/${ref}/${entry.skillPath.split('/').map(encodeURIComponent).join('/')}`;
+    const response = await fetchImpl(url, {
+      headers: { 'user-agent': 'dsh-skills-console', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    });
+    if (!response?.ok) return fallback;
+    const fields = parseSkillFrontmatter(await response.text());
+    // CLI 要求 name + description 都在，缺一个就整个跳过：这里同步标成 invalid，别让用户选了才发现装不上
+    if (!fields.name || !fields.description) return { ...fallback, valid: false };
+    return { name: fields.name, description: fields.description, skillPath: entry.skillPath, valid: true };
+  } catch {
+    return fallback;
+  }
+}
+
 /** 写操作全局单写者队列：`add` 会同时改 canonical 与 lock，按技能分桶没有意义（设计 §14.3）。 */
 function createQueue(logger) {
   let chain = Promise.resolve();
@@ -63,6 +141,10 @@ function createQueue(logger) {
 export function createService({ paths, store, registry, cli, logger, env = process.env, fetchImpl = fetch, visibleProvider = async () => ({ skills: [], complete: true }), workspacesProvider = async () => [] }) {
   const enqueue = createQueue(logger);
   const tokenOf = (env.GITHUB_TOKEN || env.GH_TOKEN) || null;
+  // 探测缓存：同一来源短时间内重复检测直接复用；并发的相同请求合并成一次（不重复烧 API 配额）
+  const probeCache = new Map();
+  const PROBE_TTL_MS = 60_000;
+  const PROBE_MAX = 50;
 
   function state() {
     return store.state;
@@ -78,7 +160,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
   function defaultTargets(current) {
     const targets = ['dsh-global'];
-    // null = 老语义「所有探测到的 Agent」；数组 = 用户在「自动链接」里勾选的那些
+    // null = 老语义「所有探测到的 Agent」；数组 = 用户在「自动接入」里勾选的那些
     const selected = current.settings.autoLinkTargets ?? null;
     for (const target of detectedTargets()) {
       if (target.kind !== 'agent') continue;
@@ -121,6 +203,90 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     return { created, skipped, failed };
   }
 
+  /** 订阅的分支：显式 ref > 记录里的 ref > 仓库默认分支。解析成功后顺手记住，省掉下次请求。 */
+  async function branchOf(subscription, { persist = false } = {}) {
+    if (subscription.ref) return subscription.ref;
+    let branch = null;
+    try {
+      branch = await fetchDefaultBranch({
+        source: subscription.source,
+        token: tokenOf,
+        fetchImpl,
+      });
+    } catch {
+      branch = null;
+    }
+    if (!branch) return null;
+    if (persist && !store.readOnly) {
+      store.update((draft) => {
+        const row = draft.subscriptions.find((item) => item.id === subscription.id);
+        if (row && !row.ref) row.ref = branch;
+      });
+    }
+    return branch;
+  }
+
+  /**
+   * 读一次订阅快照：只有网络与纯计算，**不写 store**。
+   * 上游失败一律抛 ServiceError —— 添加订阅必须先读到快照再记账，
+   * 否则会留下「订阅存在但一个 skill 都没有」的空壳（上游 404 时还会显示添加成功）。
+   */
+  async function readSnapshot(subscription, { force = false, withCommit = true } = {}) {
+    const source = subscription.source;
+    try {
+      const branch = await branchOf(subscription);
+      if (!branch) {
+        throw new ServiceError(
+          'error.skills.upstream-failed',
+          `读不到 ${source} 的默认分支（仓库不存在、私有，或 GitHub 接口不可用/已限流）`,
+          { source },
+        );
+      }
+      const result = await fetchTree({
+        source,
+        ref: branch,
+        etag: force ? null : subscription.snapshot?.etag || null,
+        token: tokenOf,
+        fetchImpl,
+      });
+      if (result.error) {
+        throw new ServiceError('error.skills.upstream-failed', `读取 ${source}@${branch} 失败：${result.error}`, {
+          source,
+          ref: branch,
+          status: result.status ?? null,
+        });
+      }
+      if (result.notModified) return { notModified: true, branch };
+      const entries = listSkillsFromTree({
+        tree: result.tree,
+        rootSha: result.rootSha,
+        subpath: subscription.subpath,
+        repoName: source.split('/').pop(),
+      });
+      const previousRoot = subscription.snapshot?.rootSha || null;
+      // 探测只需要文件树，不付 resolveCommit 那一次请求
+      const commit = !withCommit
+        ? null
+        : previousRoot && previousRoot === result.rootSha && subscription.snapshot?.commit
+          ? subscription.snapshot.commit
+          : await resolveCommit({ source, ref: branch, token: tokenOf, fetchImpl });
+      const changed =
+        !subscription.snapshot ||
+        previousRoot !== result.rootSha ||
+        JSON.stringify(entries) !== JSON.stringify(subscription.snapshot.entries);
+      return {
+        branch,
+        changed,
+        snapshot: { commit, rootSha: result.rootSha, entries, fetchedAt: nowIso(), etag: result.etag },
+      };
+    } catch (error) {
+      if (error instanceof ServiceError) throw error;
+      throw new ServiceError('error.skills.upstream-failed', `读取 ${source} 失败：${error?.message || error}`, {
+        source,
+      });
+    }
+  }
+
   function recordLink(name, target, linkPath, mode, created) {
     if (store.readOnly) return;
     const existing = state().links.find((item) => item.skill === name && item.target === target.target);
@@ -455,8 +621,8 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       if (!capabilities.usable) {
         throw new ServiceError('error.skills.cli-missing', 'skills CLI 不可用或不支持 --json/--full-depth，写操作已禁用', capabilities);
       }
-      const names = (skills || []).filter(Boolean);
-      if (names.length === 0) throw new ServiceError('error.skills.bad-request', 'skills 不能为空');
+      // 技能名可留空：有订阅快照就装快照里的条目，否则交给 CLI 的 `--skill '*'`（整仓全部）
+      const requested = (skills || []).filter(Boolean);
 
       return enqueue('install', async () => {
         const subscription = subscriptionId
@@ -467,10 +633,11 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         if (!parseSource(resolvedSource)) throw new ServiceError('error.skills.bad-source', '只接受 owner/repo 或 GitHub URL（公开源）');
 
         const snapshot = subscription?.snapshot || null;
+        const planned = requested.length > 0 ? requested : (snapshot?.entries || []).map((entry) => entry.name);
         const pin = commit || snapshot?.commit || subscription?.ref || null;
         const sourceArg = pin ? `${resolvedSource}#${pin}` : resolvedSource;
 
-        const result = await cli.add({ source: sourceArg, skills: names });
+        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 失败', {
@@ -478,6 +645,13 @@ export function createService({ paths, store, registry, cli, logger, env = proce
             stderr: result.stderr.slice(-2000),
           });
         }
+        // 留空时实际装了哪些技能以 CLI 的 JSON 输出为准（可能不止一个）
+        const names = planned.length > 0 ? planned : installedNamesFrom(result.stdout);
+        if (names.length === 0) {
+          throw new ServiceError('error.skills.cli-failed', 'skills add 成功，但输出里没有安装结果，无法记账', {
+            stdout: result.stdout.slice(-2000),
+          });
+        }
 
         const lock = readLock(paths);
         const installed = [];
@@ -596,7 +770,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           return {
             ok: false,
             code: 'error.skills.cli-failed',
-            message: 'skills remove 失败；已断开本插件建的链接，真身可能仍在 canonical',
+            message: 'skills remove 失败；已断开本插件建立的软链，真身可能仍在 canonical',
             detail: { code: result.code, stderr: result.stderr.slice(-2000) },
             trash: trash.key,
           };
@@ -605,26 +779,136 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       });
     },
 
+    /** 只读探测来源里的 SKILL.md，供「添加技能」多选；不写 state、不建订阅。 */
+    async probeSource({ source, ref, subpath }) {
+      const parsed = parseSource(source);
+      if (!parsed) throw new ServiceError('error.skills.bad-source', '只接受 owner/repo 或 GitHub URL（公开源）');
+      const canonicalSource = `${parsed.owner}/${parsed.repo}`;
+      const requestedRef = typeof ref === 'string' && ref.trim() ? ref.trim() : null;
+      const requestedSubpath = typeof subpath === 'string' && subpath.trim()
+        ? subpath.trim().replace(/^\/+|\/+$/g, '') || null
+        : null;
+      const key = `${canonicalSource}@${requestedRef || ''}#${requestedSubpath || ''}`;
+      const cached = probeCache.get(key);
+      if (cached && (cached.pending || Date.now() - cached.at < PROBE_TTL_MS)) {
+        return cached.pending || cached.value;
+      }
+      const pending = readSnapshot(
+        {
+          id: null,
+          source: canonicalSource,
+          ref: requestedRef,
+          subpath: requestedSubpath,
+          snapshot: null,
+        },
+        { force: true, withCommit: false },
+      ).then(async (probe) => {
+        const enriched = await enrichSkillEntries({
+          source: canonicalSource,
+          ref: probe.branch,
+          entries: probe.snapshot.entries,
+          token: tokenOf,
+          fetchImpl,
+        });
+        const skills = enriched
+          .filter((skill) => skill.valid)
+          .map(({ name, description, skillPath }) => ({ name, description, skillPath }));
+        return {
+          ok: true,
+          source: canonicalSource,
+          ref: probe.branch,
+          skills,
+          skipped: enriched.length - skills.length,
+        };
+      });
+      probeCache.set(key, { pending, at: Date.now() });
+      try {
+        const value = await pending;
+        probeCache.set(key, { value, at: Date.now() });
+        for (const oldest of probeCache.keys()) {
+          if (probeCache.size <= PROBE_MAX) break;
+          probeCache.delete(oldest);
+        }
+        return value;
+      } catch (error) {
+        // 失败不留缓存，用户改一下来源或重试就能重新探测
+        probeCache.delete(key);
+        throw error;
+      }
+    },
+
     async addSubscription({ source, ref, subpath, skills = '*' }) {
       assertWritable();
       const parsed = parseSource(source);
       if (!parsed) throw new ServiceError('error.skills.bad-source', '订阅只接受 owner/repo 或 GitHub URL');
-      const id = snapshotId({ source, ref, subpath });
-      const existing = state().subscriptions.find((item) => item.id === id);
-      if (existing) return { ok: true, subscription: existing, existing: true };
-      const record = {
-        id,
-        source: `${parsed.owner}/${parsed.repo}`,
-        ref: ref || null,
-        subpath: subpath || null,
+      const canonicalSource = `${parsed.owner}/${parsed.repo}`;
+      const requestedRef = typeof ref === 'string' && ref.trim() ? ref.trim() : null;
+      const requestedSubpath = typeof subpath === 'string' && subpath.trim()
+        ? subpath.trim().replace(/^\/+|\/+$/g, '') || null
+        : null;
+      const id = snapshotId({ source: canonicalSource, ref: requestedRef, subpath: requestedSubpath });
+      // 老记录可能用 URL / 原始字符串算过 id：按来源+ref+子目录再找一遍，避免同一仓库出现两条订阅
+      const existing =
+        state().subscriptions.find((item) => item.id === id) ||
+        state().subscriptions.find(
+          (item) =>
+            item.source === canonicalSource &&
+            (item.ref || null) === requestedRef &&
+            (item.subpath || null) === requestedSubpath,
+        );
+      // 已有快照的重复添加直接返回；空壳（旧版本失败留下的）要走一次真实拉取，成功后再补全
+      if (existing?.snapshot) return { ok: true, subscription: existing, existing: true };
+
+      const candidate = {
+        id: existing?.id || id,
+        source: canonicalSource,
+        ref: requestedRef || existing?.ref || null,
+        subpath: requestedSubpath,
         skills,
         lastCheck: null,
         snapshot: null,
       };
+
+      // 先读快照再落盘：上游失败时 state 里不能留下订阅，接口也必须如实报错
+      const probe = await readSnapshot(candidate, { force: true });
+      // 一条 skill 都没有 = 订阅了也没东西可装（多半是 subpath/ref 写错），同样不能算添加成功
+      if (probe.snapshot.entries.length === 0) {
+        throw new ServiceError(
+          'error.skills.no-skills',
+          `${canonicalSource}@${probe.branch}${requestedSubpath ? `/${requestedSubpath}` : ''} 里没有找到 SKILL.md`,
+          { source: canonicalSource, ref: probe.branch, subpath: requestedSubpath },
+        );
+      }
+
+      const record = {
+        ...candidate,
+        ...(existing?.adopted ? { adopted: true } : {}),
+        ref: probe.branch,
+        snapshot: probe.snapshot,
+        lastCheck: {
+          at: nowIso(),
+          commit: probe.snapshot.commit,
+          treeEtag: probe.snapshot.etag,
+          status: 'changed',
+        },
+      };
       store.update((draft) => {
-        draft.subscriptions.push(record);
+        const index = draft.subscriptions.findIndex((item) => item.id === record.id);
+        if (index >= 0) draft.subscriptions[index] = { ...draft.subscriptions[index], ...record };
+        else draft.subscriptions.push(record);
       });
-      return { ok: true, subscription: record, ...(await this.refreshSubscription({ id, force: true })) };
+      logger('subscription.add', {
+        id: record.id,
+        source: record.source,
+        ref: record.ref,
+        entries: record.snapshot.entries.length,
+      });
+      return {
+        ok: true,
+        changed: true,
+        entries: record.snapshot.entries.length,
+        subscription: state().subscriptions.find((item) => item.id === record.id),
+      };
     },
 
     async removeSubscription({ id, keepInstalled = true }) {
@@ -646,55 +930,39 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       assertWritable();
       const subscription = state().subscriptions.find((item) => item.id === id);
       if (!subscription) throw new ServiceError('error.skills.no-subscription', '订阅不存在');
-      const ref = subscription.ref || 'main';
-      const previous = subscription.snapshot?.etag || null;
-      const result = await fetchTree({
-        source: subscription.source,
-        ref,
-        etag: force ? null : previous,
-        token: tokenOf,
-        fetchImpl,
-      });
-      if (result.error) {
-        store.update((draft) => {
-          const row = draft.subscriptions.find((item) => item.id === id);
-          if (row) row.lastCheck = { at: nowIso(), status: 'unknown', detail: result.error };
-        });
-        return { ok: false, code: 'error.skills.upstream-failed', message: result.error };
-      }
-      if (result.notModified) {
-        store.update((draft) => {
-          const row = draft.subscriptions.find((item) => item.id === id);
-          // 304 只刷新时间，绝不把 entries 置空
-          if (row) row.lastCheck = { ...(row.lastCheck || {}), at: nowIso(), status: 'unchanged' };
-        });
-        return { ok: true, notModified: true, subscription: state().subscriptions.find((item) => item.id === id) };
+      let probe;
+      try {
+        probe = await readSnapshot(subscription, { force });
+      } catch (error) {
+        // 失败留痕（清单里能看到 lastCheck），但接口必须报错，不能把失败伪装成成功
+        if (!store.readOnly) {
+          store.update((draft) => {
+            const row = draft.subscriptions.find((item) => item.id === id);
+            if (row) row.lastCheck = { at: nowIso(), status: 'unknown', detail: error.message };
+          });
+        }
+        throw error;
       }
-
-      const entries = listSkillsFromTree({
-        tree: result.tree,
-        rootSha: result.rootSha,
-        subpath: subscription.subpath,
-        repoName: subscription.source.split('/').pop(),
-      });
-      const previousRoot = subscription.snapshot?.rootSha || null;
-      const commit =
-        previousRoot && previousRoot === result.rootSha && subscription.snapshot?.commit
-          ? subscription.snapshot.commit
-          : await resolveCommit({ source: subscription.source, ref, token: tokenOf, fetchImpl });
-
-      const changed =
-        !subscription.snapshot ||
-        previousRoot !== result.rootSha ||
-        JSON.stringify(entries) !== JSON.stringify(subscription.snapshot.entries);
+      const at = nowIso();
       store.update((draft) => {
         const row = draft.subscriptions.find((item) => item.id === id);
         if (!row) return;
-        row.snapshot = { commit, rootSha: result.rootSha, entries, fetchedAt: nowIso(), etag: result.etag };
-        row.lastCheck = { at: nowIso(), commit, treeEtag: result.etag, status: changed ? 'changed' : 'unchanged' };
+        if (!row.ref && probe.branch) row.ref = probe.branch;
+        if (probe.notModified) {
+          // 304 只刷新时间，绝不把 entries 置空
+          row.lastCheck = { ...(row.lastCheck || {}), at, status: 'unchanged' };
+          return;
+        }
+        row.snapshot = probe.snapshot;
+        row.lastCheck = { at, commit: probe.snapshot.commit, treeEtag: probe.snapshot.etag, status: probe.changed ? 'changed' : 'unchanged' };
       });
-      logger('subscription.refresh', { id, entries: entries.length, changed });
-      return { ok: true, changed, subscription: state().subscriptions.find((item) => item.id === id) };
+      if (!probe.notModified) logger('subscription.refresh', { id, entries: probe.snapshot.entries.length, changed: probe.changed });
+      return {
+        ok: true,
+        changed: !probe.notModified && probe.changed,
+        ...(probe.notModified ? { notModified: true } : {}),
+        subscription: state().subscriptions.find((item) => item.id === id),
+      };
     },
 
     async checkUpdates({ names, subscriptionId } = {}) {
@@ -708,16 +976,18 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       for (const install of installs) {
         const subscription = state().subscriptions.find((item) => item.id === install.subscriptionId);
         if (!subscription) continue;
-        const key = `${subscription.source}#${subscription.ref || 'main'}`;
-        if (!groups.has(key)) groups.set(key, { subscription, installs: [] });
-        groups.get(key).installs.push(install);
+        // 按订阅（id 已含 source/ref/subpath）分组：不能用 `ref || 'main'` 当键，否则 null-ref 与 main 会撞车
+        if (!groups.has(subscription.id)) groups.set(subscription.id, { subscription, installs: [] });
+        groups.get(subscription.id).installs.push(install);
       }
 
       const results = [];
       for (const { subscription, installs: groupInstalls } of groups.values()) {
+        // 没写 ref 的订阅（旧版本/接管建的）按仓库默认分支检查，别硬套 main
+        const ref = (await branchOf(subscription, { persist: true })) || 'main';
         const tree = await fetchTree({
           source: subscription.source,
-          ref: subscription.ref || 'main',
+          ref,
           etag: subscription.snapshot?.etag || null,
           token: tokenOf,
           fetchImpl,
@@ -779,9 +1049,10 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       if (!install) throw new ServiceError('error.skills.not-managed', `${name} 没有安装记录`);
       const subscription = state().subscriptions.find((item) => item.id === install.subscriptionId);
       if (!subscription) throw new ServiceError('error.skills.no-subscription', '该技能不属于任何订阅，无法生成更新计划');
+      const ref = (await branchOf(subscription)) || 'main';
       const tree = await fetchTree({
         source: subscription.source,
-        ref: subscription.ref || 'main',
+        ref,
         token: tokenOf,
         fetchImpl,
       });
@@ -791,7 +1062,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       const entry = tree.tree.find((item) => item.type === 'blob' && item.path === skillPath);
       if (!entry) throw new ServiceError('error.skills.upstream-deleted', '上游已移除该技能');
       const targetTreeSha = skillTreeSha({ tree: tree.tree, skillPath, rootSha: tree.rootSha });
-      const targetCommit = await resolveCommit({ source: subscription.source, ref: subscription.ref || 'main', token: tokenOf, fetchImpl });
+      const targetCommit = await resolveCommit({ source: subscription.source, ref, token: tokenOf, fetchImpl });
       const token = planToken({
         subscriptionId: subscription.id,
         from: install.commit || null,
@@ -806,6 +1077,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         token,
         fromCommit: install.commit || null,
         toCommit: targetCommit,
+        ref,
         targetTreeSha,
         skillPath,
         localModified: Boolean(install.installedHash) && contentHash(path.join(paths.canonical, name)) !== install.installedHash,
@@ -833,7 +1105,9 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           ? createBackup({ paths, skill: name, fromDir: canonicalPath, hash: install.installedHash })
           : null;
 
-        const sourceArg = plan.toCommit ? `${subscription.source}#${plan.toCommit}` : `${subscription.source}#${subscription.ref || 'main'}`;
+        const sourceArg = plan.toCommit
+          ? `${subscription.source}#${plan.toCommit}`
+          : `${subscription.source}#${plan.ref || subscription.ref || 'main'}`;
         const result = await cli.add({ source: sourceArg, skills: [name] });
         const lock = readLock(paths);
         const lockHash = lock.skills?.[name]?.skillFolderHash || null;

package/lib/core/updates.js

@@ -64,6 +64,18 @@ export async function fetchTree({ source, ref = 'main', etag, token, fetchImpl }
   };
 }
 
+/**
+ * 仓库默认分支。`ref` 缺省时以它为准：不少技能仓库默认是 `master`，
+ * 硬套 `main` 只会得到 404（例如 alchaincyf/huashu-design）。
+ */
+export async function fetchDefaultBranch({ source, token, fetchImpl } = {}) {
+  const parsed = parseSource(source);
+  if (!parsed) return null;
+  const result = await callJson(`${API}/repos/${parsed.owner}/${parsed.repo}`, { token, fetchImpl });
+  if (result.error || !result.body?.default_branch) return null;
+  return result.body.default_branch;
+}
+
 /** 解析 ref 对应的 commit（只在安装/计划时需要，检测阶段不付这笔成本）。 */
 export async function resolveCommit({ source, ref = 'main', token, fetchImpl } = {}) {
   const parsed = parseSource(source);

package/lib/routes.js

@@ -1,9 +1,28 @@
+import { readFileSync } from 'node:fs';
 import { ServiceError } from './core/service.js';
 import { StateReadOnlyError } from './core/state.js';
 
 export const ROUTE_PREFIX = '/api/morehao/skills-console';
 const MAX_BODY = 256 * 1024;
 
+/**
+ * 插件身份：包名（去掉 scope，页头显示 dsh-skills-console）+ 版本。
+ * 从 package.json 读一次，随 /state 下发 —— 前端别硬编码版本，否则两处漂移。
+ */
+export const PLUGIN_INFO = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const name = String(pkg.name || 'dsh-skills-console');
+    return {
+      name: name.includes('/') ? name.slice(name.lastIndexOf('/') + 1) : name,
+      version: pkg.version || null,
+      repository: pkg.repository?.url || null,
+    };
+  } catch {
+    return { name: 'dsh-skills-console', version: null, repository: null };
+  }
+})();
+
 function sendJson(res, status, payload) {
   const body = JSON.stringify(payload);
   res.writeHead(status, {
@@ -40,6 +59,7 @@ function matchRoute(method, pathname) {
   if (segments.length === 1 && segments[0] === 'settings' && method === 'POST') return { name: 'settings' };
   if (segments.length === 1 && segments[0] === 'links' && method === 'POST') return { name: 'links' };
   if (segments.length === 1 && segments[0] === 'install' && method === 'POST') return { name: 'install' };
+  if (segments.length === 1 && segments[0] === 'probe' && method === 'POST') return { name: 'probe' };
   if (segments.length === 1 && segments[0] === 'diagnostics' && method === 'GET') return { name: 'diagnostics' };
 
   if (segments[0] === 'skills' && segments.length === 2 && method === 'GET') {
@@ -123,8 +143,10 @@ export function createRoutes({ service, logger }) {
 
 async function dispatch(route, { body, query, service }) {
   switch (route.name) {
-    case 'state':
-      return service.getState({ cwd: query.cwd || body.cwd, workspace: query.workspace });
+    case 'state': {
+      const state = await service.getState({ cwd: query.cwd || body.cwd, workspace: query.workspace });
+      return { ...state, plugin: PLUGIN_INFO };
+    }
     case 'agents':
       return { ok: true, all: service.registry.all(), detected: service.registry.detected() };
     case 'settings':
@@ -133,6 +155,8 @@ async function dispatch(route, { body, query, service }) {
       return service.setLinks(body);
     case 'install':
       return service.install(body);
+    case 'probe':
+      return service.probeSource(body);
     case 'diagnostics':
       return service.diagnostics();
     case 'skill.body':