@morehao/dsh-skills-console 0.2.1 → 0.2.2

package/README.md

@@ -29,7 +29,7 @@ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入
 | 接入 | 软链四态判定（`managed` / `managed-external` / `foreign-link` / `real`），**绝不覆盖**别人创建的东西；只列本机已安装目录，已删的 Agent 自动从列表消失 |
 | 启停 | `mode: on/off` 只摘或重建 DSH 侧链接，不动 `SKILL.md`，其他 Agent 的链接也不受影响 |
 | 作用范围 | 全局 `~/.dsh/skills`，或仅指定项目；项目可直接勾选 DSH 已登记的工作区，也可手动选目录 |
-| 订阅 | 关注 `owner/repo`（可指定 ref / 子目录），只记快照、不装技能；装好后再逐个安装 |
+| 订阅 | 关注 `owner/repo`（可指定 ref / 子目录；ref 缺省时跟随仓库默认分支，`master` 仓库也能用），只记快照、不装技能；上游读不到快照时直接报错，不会留下空订阅 |
 
 ## 界面
 
@@ -57,16 +57,14 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 
 客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。
 
-> 本机可能还装着 `@michengai/dsh-skills-manager`（显示名「技能管理」）。两者互不干扰（路由前缀 `/api/morehao/skills-console/*`、状态目录 `$DSH_HOME/skills-console/` 都不同），但会各出一个设置分区；只想留一个时把另一个 `plugin_manager set_plugin enabled:false` 即可。
-
 ## 快速上手
 
-1. **添加技能**：点右上角「添加技能」，填 `owner/repo`（需要的话再列出技能名），确认即可。安装完成后会在列表里出现。
+1. **添加技能**：点右上角「添加技能」，填 `owner/repo` 或 GitHub URL，点「检测技能」；仓库里有多个技能时勾选要装的（支持多选，默认全选，列表带每个技能的说明），只有一个会默认勾上。检测不到时可以直接手填技能名，留空则装仓库内全部。
 2. **接到别的 Agent**：点行内「接入设置」，勾选目标 Agent；需要限定项目时改选「仅以下项目」并勾工作区。之后新装技能默认接哪些 Agent，用它旁边的「自动接入」设定。
 3. **检查更新**：点列表头上的刷新图标；有更新的行会亮起「更新」，也可以一次「全部更新」。本地改过的技能会先要求确认。
 4. **临时停用**：关掉行内开关。DSH 看不到它，但文件和其他 Agent 的接入都还在；再打开就恢复。
 
-## 设计约束
+## 可靠性
 
 - **canonical 与 CLI lock 只读**：`~/.agents/skills`、`~/.agents/.skill-lock.json` 的增删改只经 `skills` CLI，插件不直接写、不克隆仓库、不代理来源。
 - **只动自己的东西**：只处理本插件创建的 `managed` 链接，以及已记账的 `managed-external`；`real` 目录和 `foreign-link` 永不改写，删除前体检直接中止。
@@ -88,43 +86,9 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 
 环境变量：`DSH_SKILLS_CONSOLE_HOME`、`DSH_SKILLS_CONSOLE_CLI`、`DSH_SKILLS_CONSOLE_NPX_SPEC`、`DSH_SKILLS_CONSOLE_TIMEOUT_MS`、`GITHUB_TOKEN` / `GH_TOKEN`。
 
-## 开发
-
-```bash
-npm install            # 只装构建期依赖（esbuild）；运行时依赖仍为零
-npm run build:client   # 从 client/ 生成根 client.js（生成物要提交，不要手改）
-npm run dev:client     # 监听 client/ 自动重建（配合 link: 接入，改完刷新即可）
-npm test               # node --test，80 个离线用例，临时 HOME / DSH_HOME，不碰真实目录
-npm run check          # 语法自检 + 生成物一致性 + 命名/导出接线 + 打包白名单 + Release 说明投影冒烟
-npm run sync:agents -- <skills/dist/cli.mjs>   # 重新导出 agent 目录表（默认写回 lib/agent-table.json）
-```
-
-Web Client 的源码在 `client/`（`host` / `copy` / `styles` / `api` / `icons` / `hooks` / `actions` / `views/*` / `section` / `surface` / `app`），仓根 `client.js` 是 `npm run build:client` 的产物；只改产物不改源码，`npm run check` 会直接红。
-
-目录结构、测试策略与调试手段见 [docs/development.md](docs/development.md)；在本仓工作的 AI agent 请先读 [AGENTS.md](AGENTS.md)。
-
-## 发布
-
-打注记 tag `vX.Y.Z` → GitHub Actions（OIDC / Trusted Publishing）自动发布到 npm → 用 tag 注记正文建 GitHub Release，不需要任何 npm token。
-
-```bash
-# 升版本走分支 + PR；合并后在 main 最新提交上打注记 tag（正文就是 Release body）
-git tag -a v0.2.0 -m "release: v0.2.0
-<变更说明>"
-git push origin v0.2.0
-```
-
-完整流程、一次性建包配置与排障清单见 [docs/publishing.md](docs/publishing.md)。
-
-## 从 `dsh-skills-manager` 迁移
-
-`v0.2.0` 起包名、插件 id、路由前缀、状态目录与环境变量统一改为 `skills-console`，**不提供兼容读旧值**。保住旧账本（订阅、回收站、链接记录、版本缓存）只需搬一次目录：
-
-```bash
-mv ~/.dsh/skills-manager ~/.dsh/skills-console
-```
+## 开发与发布
 
-完整对照、不搬的后果与安装侧改动见 [docs/migration-from-skills-manager.md](docs/migration-from-skills-manager.md)。
+源码结构、测试策略与调试手段见 [docs/development.md](docs/development.md)（含本地 `link:` 验证与回退步骤）；发布流程与排障清单见 [docs/publishing.md](docs/publishing.md)。在本仓工作的 AI agent 请先读 [AGENTS.md](AGENTS.md)。
 
 ## 边界（明确不做）
 

package/client.js

@@ -148,11 +148,23 @@ var DICT = {
     "banner.visible": "模型可见技能与本地账本不一致，差异已列在下方",
     "form.source": "来源（owner/repo 或 GitHub URL）",
     "form.sourceHint": "例如 morehao/ai-kit",
+    "form.probe": "检测技能",
+    "form.probing": "读取中…",
+    "form.probingHint": "正在读仓库的文件树，稍等一下…",
+    "form.detected": "检测到 {n} 个技能，勾选要安装的",
+    "form.skipped": "另有 {n} 个 SKILL.md 缺少 name/description，CLI 无法安装，已跳过",
+    "form.selectAll": "全选",
+    "form.selectNone": "全不选",
+    "form.pickHint": "先填来源并检测；仓库里有多个技能时可以多选，只有一个会默认勾上。",
+    "form.noSkills": "仓库里没找到 SKILL.md，可以直接填技能名安装",
+    "form.probeFailed": "检测失败，仍可手动填技能名",
     "form.skills": "技能名（多个用逗号分隔）",
     "form.ref": "ref（分支 / tag，可空）",
+    "form.refHint": "留空则自动跟随仓库默认分支",
     "form.subpath": "子目录（可空）",
     "form.hint": "会立即下载并写入 ~/.agents/skills，并按「自动接入」设置接到对应 Agent。",
     "form.subHint": "只记录你关注这个仓库，不会安装任何技能。",
+    "subscription.defaultRef": "默认分支",
     "confirm.deleteTitle": "删除技能",
     "confirm.deleteBody": "会从本机移除，断开本插件建立的软链并调 skills CLI 卸载；目录先备份到回收站（保留 7 天）。不会删除你的源仓库。",
     "confirm.updateTitle": "本地有改动",
@@ -266,11 +278,23 @@ var DICT = {
     "banner.visible": "Model-visible skills differ from the local ledger",
     "form.source": "Source (owner/repo or GitHub URL)",
     "form.sourceHint": "e.g. morehao/ai-kit",
+    "form.probe": "Detect",
+    "form.probing": "Reading…",
+    "form.probingHint": "Reading the repository tree…",
+    "form.detected": "Found {n} skills; pick the ones to install",
+    "form.skipped": "{n} SKILL.md file(s) skipped: missing name/description",
+    "form.selectAll": "Select all",
+    "form.selectNone": "Clear",
+    "form.pickHint": "Enter a source and detect first. Pick one or more when the repo has several.",
+    "form.noSkills": "No SKILL.md found; type skill names instead",
+    "form.probeFailed": "Detection failed; you can still type names",
     "form.skills": "Skill names (comma separated)",
     "form.ref": "ref (branch / tag, optional)",
+    "form.refHint": "empty follows the repository default branch",
     "form.subpath": "Subdirectory (optional)",
     "form.hint": "Downloads into ~/.agents/skills and links agents per the auto-link setting.",
     "form.subHint": "Only records the repository; installs nothing.",
+    "subscription.defaultRef": "default branch",
     "confirm.deleteTitle": "Delete skill",
     "confirm.deleteBody": "Removes it locally, disconnects this plugin’s links and calls skills remove. A snapshot stays in trash for 7 days. Your source repo is untouched.",
     "confirm.updateTitle": "Local changes",
@@ -888,6 +912,10 @@ var CSS = `
     border: 1px solid var(--dsw-alias-border-l2); background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); outline: none; }
   .dshsc-field input:focus { border-color: var(--dsw-alias-brand-primary);
     box-shadow: 0 0 0 2px color-mix(in srgb, var(--dsw-alias-brand-primary) 18%, transparent); }
+  /* 来源输入 + 检测按钮同一行；输入框吃掉剩余宽度，按钮不被挤压 */
+  .dshsc-inline { display: flex; gap: 6px; align-items: stretch; }
+  .dshsc-inline input { flex: 1; min-width: 0; }
+  .dshsc-inline .dshsc-btn { flex: none; }
 
   .dshsc-check { display: flex; align-items: center; gap: 9px; font-size: 13px; padding: 5px 8px; border-radius: 8px; cursor: pointer; }
   .dshsc-check:hover { background: var(--dsw-alias-bg-layer-1); }
@@ -905,6 +933,14 @@ var CSS = `
   .dshsc-check input:disabled { opacity: .55; cursor: not-allowed; }
   .dshsc-check small { color: var(--dsw-alias-label-secondary); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
   .dshsc-check span { white-space: nowrap; }
+  /* 添加技能：每个技能一行，名字 + 两行描述 + 路径；描述太长时截断，不把弹窗撑高 */
+  .dshsc-skill { align-items: flex-start; }
+  .dshsc-skill input[type="checkbox"] { margin-top: 3px; }
+  .dshsc-skill-main { display: flex; flex-direction: column; gap: 1px; min-width: 0; flex: 1; }
+  .dshsc-skill-name { font-weight: 600; }
+  .dshsc-check .dshsc-skill-desc { display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical;
+    overflow: hidden; white-space: normal; line-height: 1.4; }
+  .dshsc-check .dshsc-skill-path { font-size: 11px; opacity: .75; }
 
   .dshsc-panel { border: 1px solid var(--dsw-alias-border-l1); border-radius: 10px; background: var(--dsw-alias-bg-layer-1);
     padding: 4px; max-height: 300px; overflow: auto; display: flex; flex-direction: column; }
@@ -1009,11 +1045,13 @@ function useSkillActions({ t, rows, reload, run, setBusy, setToast, setModal })
   function requestAddSubscription() {
     setModal({ type: "add-subscription" });
   }
-  async function addSkill(form) {
-    const names = form.skills.split(/[,，\s]+/).map((item) => item.trim()).filter(Boolean);
+  async function probeSkills(source) {
+    return apiCall("POST", "/probe", { source: String(source || "").trim() });
+  }
+  async function installSkills({ source, skills }) {
     setModal(null);
     await run("install", async () => {
-      const result = await apiCall("POST", "/install", { source: form.source.trim(), skills: names });
+      const result = await apiCall("POST", "/install", { source: String(source || "").trim(), skills });
       const warnings = result.warnings?.length || 0;
       setToast({
         kind: warnings ? "err" : "ok",
@@ -1060,7 +1098,8 @@ function useSkillActions({ t, rows, reload, run, setBusy, setToast, setModal })
     saveLinks,
     requestAddSkill,
     requestAddSubscription,
-    addSkill,
+    probeSkills,
+    installSkills,
     addSubscription,
     refreshSubscription,
     deleteSubscription,
@@ -1768,7 +1807,7 @@ function SubscriptionsTab({
           onClick: () => onToggle(subscription.id)
         }, h(CaretIcon, { open })),
         h("span", { className: "dshsc-name" }, subscription.source),
-        h("span", { className: "dshsc-tag" }, subscription.ref || "default"),
+        h("span", { className: "dshsc-tag" }, subscription.ref || t("subscription.defaultRef")),
         h(
           "span",
           { className: "dshsc-substat" },
@@ -1848,6 +1887,9 @@ function Overlay({ t, title, children, footer, onCancel }) {
 }
 function FormModal({ t, title, hint, fields, onCancel, onSubmit }) {
   const [form, setForm] = import_react3.default.useState(() => Object.fromEntries(fields.map((field) => [field.key, ""])));
+  const incomplete = fields.some(
+    (field) => field.required !== false && !String(form[field.key] || "").trim()
+  );
   return h(
     Overlay,
     {
@@ -1859,7 +1901,7 @@ function FormModal({ t, title, hint, fields, onCancel, onSubmit }) {
         h("button", {
           key: "s",
           className: "dshsc-btn primary",
-          disabled: !form[fields[0].key]?.trim?.() || fields.some((f) => f.key === "skills") && !form.skills?.trim(),
+          disabled: incomplete,
           onClick: () => onSubmit(form)
         }, t("action.save"))
       ]
@@ -2029,18 +2071,153 @@ function AutoLinkModal({ t, settings, agents, onCancel, onSave }) {
     h("p", { className: "dshsc-sub" }, t("autoLink.hint"))
   );
 }
+function AddSkillModal({ t, onCancel, onProbe, onInstall }) {
+  const [source, setSource] = import_react3.default.useState("");
+  const [phase, setPhase] = import_react3.default.useState("idle");
+  const [options, setOptions] = import_react3.default.useState([]);
+  const [selected, setSelected] = import_react3.default.useState(() => /* @__PURE__ */ new Set());
+  const [manual, setManual] = import_react3.default.useState("");
+  const [skipped, setSkipped] = import_react3.default.useState(0);
+  const [error, setError] = import_react3.default.useState(null);
+  const reset = (value) => {
+    setSource(value);
+    setPhase("idle");
+    setOptions([]);
+    setSelected(/* @__PURE__ */ new Set());
+    setSkipped(0);
+    setError(null);
+  };
+  const probe = async () => {
+    const value = source.trim();
+    if (!value || phase === "probing") return;
+    setPhase("probing");
+    setError(null);
+    try {
+      const result = await onProbe(value);
+      const found = Array.isArray(result?.skills) ? result.skills : [];
+      setOptions(found);
+      setSelected(new Set(found.map((item) => item.name)));
+      setSkipped(Math.max(0, Number(result?.skipped) || 0));
+      setPhase(found.length > 0 ? "picked" : "empty");
+    } catch (err) {
+      setError(err?.message || String(err));
+      setPhase("failed");
+    }
+  };
+  const toggle = (name) => setSelected((prev) => {
+    const next = new Set(prev);
+    if (next.has(name)) next.delete(name);
+    else next.add(name);
+    return next;
+  });
+  const names = manual.split(/[,，\s]+/).map((item) => item.trim()).filter(Boolean);
+  const skippedText = skipped > 0 ? t("form.skipped").replace("{n}", String(skipped)) : null;
+  const manualMode = phase === "empty" || phase === "failed";
+  const skills = phase === "picked" ? [...selected] : names;
+  const canSubmit = phase === "picked" ? selected.size > 0 : manualMode ? names.length > 0 : false;
+  const submit = () => {
+    if (!canSubmit) return;
+    onInstall({ source: source.trim(), skills });
+  };
+  return h(
+    Overlay,
+    {
+      t,
+      title: t("action.addSkill"),
+      onCancel,
+      footer: [
+        h("button", { key: "c", className: "dshsc-btn ghost", onClick: onCancel }, t("action.cancel")),
+        h("button", {
+          key: "s",
+          className: "dshsc-btn primary",
+          disabled: !canSubmit,
+          onClick: submit
+        }, t("action.save"))
+      ]
+    },
+    h("p", { className: "dshsc-sub" }, t("form.pickHint")),
+    h(
+      "div",
+      { className: "dshsc-field" },
+      h("span", null, t("form.source")),
+      h(
+        "div",
+        { className: "dshsc-inline" },
+        h("input", {
+          value: source,
+          placeholder: t("form.sourceHint"),
+          onChange: (event) => reset(event.target.value),
+          onKeyDown: (event) => {
+            if (event.key === "Enter") void probe();
+          }
+        }),
+        h("button", {
+          className: "dshsc-btn",
+          disabled: !source.trim() || phase === "probing",
+          onClick: () => void probe()
+        }, phase === "probing" ? t("form.probing") : t("form.probe"))
+      )
+    ),
+    phase === "picked" ? h(
+      "div",
+      { key: "picked" },
+      h("div", { className: "dshsc-group" }, t("form.detected").replace("{n}", String(options.length))),
+      h(
+        "div",
+        { style: { display: "flex", gap: 6, marginBottom: 6 } },
+        h("button", {
+          className: "dshsc-btn ghost",
+          onClick: () => setSelected(new Set(options.map((item) => item.name)))
+        }, t("form.selectAll")),
+        h("button", {
+          className: "dshsc-btn ghost",
+          onClick: () => setSelected(/* @__PURE__ */ new Set())
+        }, t("form.selectNone"))
+      ),
+      h("div", { className: "dshsc-panel" }, options.map((option) => h(
+        "label",
+        { className: "dshsc-check dshsc-skill", key: option.name },
+        h("input", {
+          type: "checkbox",
+          checked: selected.has(option.name),
+          onChange: () => toggle(option.name)
+        }),
+        h(
+          "span",
+          { className: "dshsc-skill-main" },
+          h("span", { className: "dshsc-skill-name" }, option.name),
+          option.description ? h("small", { className: "dshsc-skill-desc" }, option.description) : null,
+          h("small", { className: "dshsc-skill-path" }, option.skillPath)
+        )
+      ))),
+      skippedText ? h("p", { className: "dshsc-sub" }, skippedText) : null
+    ) : null,
+    phase === "probing" ? h("p", { className: "dshsc-sub" }, t("form.probingHint")) : null,
+    manualMode ? h(
+      "div",
+      { key: "manual" },
+      h("p", { className: "dshsc-sub" }, phase === "empty" ? skippedText || t("form.noSkills") : `${t("form.probeFailed")}${error ? ` · ${error}` : ""}`),
+      h(
+        "label",
+        { className: "dshsc-field" },
+        h("span", null, t("form.skills")),
+        h("input", {
+          value: manual,
+          placeholder: "git-kit, handoff",
+          onChange: (event) => setManual(event.target.value)
+        })
+      )
+    ) : null,
+    h("p", { className: "dshsc-sub" }, t("form.hint"))
+  );
+}
 function Modals({ t, modal, data, autoLinkAgents, pickDirectory, actions, onClose, onSaveAutoLink }) {
   if (modal.type === "add-skill") {
-    return h(FormModal, {
+    return h(AddSkillModal, {
       t,
-      title: t("action.addSkill"),
-      hint: t("form.hint"),
-      fields: [
-        { key: "source", label: t("form.source"), placeholder: t("form.sourceHint") },
-        { key: "skills", label: t("form.skills"), placeholder: "git-kit, handoff" }
-      ],
       onCancel: onClose,
-      onSubmit: (form) => void actions.addSkill(form)
+      onProbe: actions.probeSkills,
+      onInstall: actions.installSkills
     });
   }
   if (modal.type === "add-subscription") {
@@ -2050,8 +2227,8 @@ function Modals({ t, modal, data, autoLinkAgents, pickDirectory, actions, onClos
       hint: t("form.subHint"),
       fields: [
         { key: "source", label: t("form.source"), placeholder: t("form.sourceHint") },
-        { key: "ref", label: t("form.ref"), placeholder: "main" },
-        { key: "subpath", label: t("form.subpath"), placeholder: "skills" }
+        { key: "ref", label: t("form.ref"), placeholder: t("form.refHint"), required: false },
+        { key: "subpath", label: t("form.subpath"), placeholder: "skills", required: false }
       ],
       onCancel: onClose,
       onSubmit: (form) => void actions.addSubscription(form)
@@ -2267,7 +2444,8 @@ function Section({ t, page = false, pickDirectory, onPlacementChange }) {
       autoLinkAgents: autolinkTargets,
       pickDirectory,
       actions: {
-        addSkill: actions.addSkill,
+        probeSkills: actions.probeSkills,
+        installSkills: actions.installSkills,
         addSubscription: actions.addSubscription,
         saveLinks: actions.saveLinks
       },

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;
@@ -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 = [];
@@ -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

@@ -59,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') {
@@ -154,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':

package/package.json

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