dsh-armory 2.0.0 → 2.2.0

package/lib/wb-awesome-market.js

@@ -1,4 +1,4 @@
-// awesome-dsh-plugins 市场数据层（T01，docs/system-design-awesome.md）。
+// awesome-dsh-plugins 市场数据层（T01）。
 //
 // 与既有 codebuddy 插件市场（lib/wb-plugin-market.js 的 zip 管线）完全解耦：
 // awesome 源是单文件裸 JSON（~13.4MB，全量 5 千余条，其中 unverified/broken 占
@@ -186,7 +186,7 @@ async function fetchChain(etag) {
       if (!data || typeof data !== "object" || Array.isArray(data) || !Array.isArray(data.plugins)) {
         throw new Error("响应缺少 plugins 数组");
       }
-      return { ok: true, data, etag: response.headers.get("etag") || "" };
+      return { ok: true, data, etag: response.headers.get("etag") || "", source: sourceUrl };
     } catch (error) {
       lastError = `${sourceUrl} → ${error.message}`;
       continue;
@@ -196,13 +196,15 @@ async function fetchChain(etag) {
 }
 
 /** 瘦身结果 + 元信息原子落盘（slim.json + meta.json），返回 counts。
- *  同时刷新进程内缓存层，后续调用免掉 readFile + JSON.parse。 */
-async function persistSlim(entries, etag, updated, options = {}) {
+ *  同时刷新进程内缓存层，后续调用免掉 readFile + JSON.parse。
+ *  source 记录「这份缓存是从哪个源拿到的」：探测时优先回同一源比对 ETag，
+ *  避免主源挂掉走备用源取到缓存后、探测却只问主源而误报失败。 */
+async function persistSlim(entries, etag, updated, options = {}, source = "") {
   const counts = countsOf(entries);
   const fetchedAt = Date.now();
   await writeAtomic(slimPathOf(options), JSON.stringify(entries));
-  await writeAtomic(metaPathOf(options), JSON.stringify({ etag, fetchedAt, updated, counts }));
-  setMemSlim(options, entries, { etag, fetchedAt, updated, counts });
+  await writeAtomic(metaPathOf(options), JSON.stringify({ etag, fetchedAt, updated, counts, source }));
+  setMemSlim(options, entries, { etag, fetchedAt, updated, counts, source });
   return counts;
 }
 
@@ -317,7 +319,7 @@ function catalogResult(entries, meta, loadedFrom, extra = {}) {
 /** 拉取链成功后的统一走线：瘦身 → 原子落盘 → 组装 network 响应。 */
 async function refreshFromNetwork(chain, options = {}) {
   const entries = slimEntries(chain.data.plugins);
-  const counts = await persistSlim(entries, chain.etag, typeof chain.data.updated === "string" ? chain.data.updated : "", options);
+  const counts = await persistSlim(entries, chain.etag, typeof chain.data.updated === "string" ? chain.data.updated : "", options, typeof chain.source === "string" ? chain.source : "");
   return {
     ok: true,
     loadedFrom: "network",
@@ -392,12 +394,43 @@ export async function wbAwesomeDetail(name, options = {}) {
 }
 
 /**
- * ETag 条件探测（wbPluginUpdateCheck 同款语义，源固定取 AWESOME_SOURCES[0]）：
- * **绝不落盘**，只取 headers。reason 五枚举：no-source / probe-failed / no-cache /
- * up-to-date / update-available —— 本实现源是模块常量恒有源，no-source 分支不出现，
- * 保留枚举位仅为与 UI 侧契约对齐（wb-update-hint 的 reason 映射表）。
+ * 单源 ETag 条件探测：HEAD（被 405/501 拒绝则降级 GET 并立刻 cancel 响应体）。
+ * 绝不落盘，只取 headers。返回 { ok: true, remoteEtag } 或 { ok: false, error }。
+ */
+async function probeEtagAt(sourceUrl, localEtag) {
+  const headers = { "user-agent": USER_AGENT, "if-none-match": localEtag };
+  let response;
+  try {
+    response = await fetch(sourceUrl, { method: "HEAD", headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    if (response.status === 405 || response.status === 501) {
+      // HEAD 不被支持 → 降级 GET，立刻 cancel() 丢弃响应体，不读进内存。
+      response.body?.cancel?.();
+      response = await fetch(sourceUrl, { method: "GET", headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+      response.body?.cancel?.();
+    }
+  } catch (error) {
+    return { ok: false, error: `${sourceUrl} → ${error.message}` };
+  }
+  if (response.status === 304) return { ok: true, remoteEtag: localEtag };
+  if (response.ok) {
+    const remoteEtag = response.headers.get("etag") || "";
+    // 探测只信 ETag：响应没有 ETag 就无法判定，宁可报探测失败也不误报「有更新」。
+    if (!remoteEtag) return { ok: false, error: `${sourceUrl} → 响应缺少 ETag` };
+    return { ok: true, remoteEtag };
+  }
+  return { ok: false, error: `${sourceUrl} → HTTP ${response.status}` };
+}
+
+/**
+ * ETag 条件探测（wbPluginUpdateCheck 同款语义）：**绝不落盘**，只取 headers。
+ * reason 五枚举：no-source / probe-failed / no-cache / up-to-date / update-available。
  * 无缓存（meta 无 etag）→ hasUpdate: false + no-cache（与插件市场不同：awesome 首次
  * 由 catalog 链兜底加载，探测层不引导更新）。
+ *
+ * 探测与目录拉取必须走同一条源链：过去只问 AWESOME_SOURCES[0]，于是「主源不通、
+ * 目录靠备用源成功」的机器上目录能正常加载、探测却每次 probe-failed —— 这正是
+ * 「DSH 社区目录更新探测失败」的来源。现在按「缓存实际来源 → 全部源」顺序逐个试，
+ * 首个拿到 ETag 的源胜出；全部失败才报 probe-failed。
  */
 export async function wbAwesomeUpdateCheck(options = {}) {
   try {
@@ -406,34 +439,20 @@ export async function wbAwesomeUpdateCheck(options = {}) {
     if (!localEtag) {
       return { ok: true, hasUpdate: false, reason: "no-cache", localEtag: "", remoteEtag: "", checkedAt: Date.now() };
     }
-    const sourceUrl = AWESOME_SOURCES[0];
-    const headers = { "user-agent": USER_AGENT, "if-none-match": localEtag };
-    let response;
-    try {
-      response = await fetch(sourceUrl, { method: "HEAD", headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
-      if (response.status === 405 || response.status === 501) {
-        // HEAD 不被支持 → 降级 GET，立刻 cancel() 丢弃响应体，不读进内存。
-        response.body?.cancel?.();
-        response = await fetch(sourceUrl, { method: "GET", headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
-        response.body?.cancel?.();
-      }
-    } catch (error) {
-      return { ok: false, hasUpdate: false, reason: "probe-failed", localEtag, remoteEtag: "", checkedAt: Date.now(), error: `更新探测失败：${error.message}` };
-    }
-    if (response.status === 304) {
-      // 304：ETag 命中，服务端不回显 ETag；回显 localEtag 便于客户端展示。
-      return { ok: true, hasUpdate: false, reason: "up-to-date", localEtag, remoteEtag: localEtag, checkedAt: Date.now() };
-    }
-    if (response.ok) {
-      const remoteEtag = response.headers.get("etag") || "";
-      if (!remoteEtag) {
-        // 探测只信 ETag：响应没有 ETag 就无法判定，宁可报探测失败也不误报「有更新」。
-        return { ok: false, hasUpdate: false, reason: "probe-failed", localEtag, remoteEtag: "", checkedAt: Date.now(), error: "更新探测失败：响应缺少 ETag" };
+    // 先问拿到这份缓存的源（ETag 同源可比），再兜底其余源。
+    const cachedSource = typeof meta.source === "string" ? meta.source : "";
+    const candidates = [...new Set([cachedSource, ...AWESOME_SOURCES].filter(Boolean))];
+    let lastError = "";
+    for (const sourceUrl of candidates) {
+      const probe = await probeEtagAt(sourceUrl, localEtag);
+      if (!probe.ok) {
+        lastError = probe.error;
+        continue;
       }
-      const hasUpdate = remoteEtag !== localEtag;
-      return { ok: true, hasUpdate, reason: hasUpdate ? "update-available" : "up-to-date", localEtag, remoteEtag, checkedAt: Date.now() };
+      const hasUpdate = probe.remoteEtag !== localEtag;
+      return { ok: true, hasUpdate, reason: hasUpdate ? "update-available" : "up-to-date", localEtag, remoteEtag: probe.remoteEtag, checkedAt: Date.now() };
     }
-    return { ok: false, hasUpdate: false, reason: "probe-failed", localEtag, remoteEtag: "", checkedAt: Date.now(), error: `awesome 市场更新探测失败：HTTP ${response.status}` };
+    return { ok: false, hasUpdate: false, reason: "probe-failed", localEtag, remoteEtag: "", checkedAt: Date.now(), error: `awesome 市场更新探测失败：${lastError}` };
   } catch (error) {
     return { ok: false, hasUpdate: false, reason: "probe-failed", localEtag: "", remoteEtag: "", checkedAt: Date.now(), error: `更新探测异常：${error.message}` };
   }
@@ -451,3 +470,252 @@ export async function wbAwesomeCachedInfo(options = {}) {
     updated: typeof meta.updated === "string" ? meta.updated : "",
   };
 }
+
+// ── README 预览（按需拉取 + 落盘缓存，纯只读）────────────────────────────────
+//
+// 为什么单独一条 RPC：目录 slim 里不放 README（13MB 全量本身就只留 13 个字段，
+// 塞进 README 会把瘦身缓存撑爆）。README 只在用户点开某张卡片时按需取一次，
+// 取到后按「npm 包名或仓库」落盘缓存，同一插件再点就秒开、也不怕断网。
+
+/** 预览是用户点击触发的一次短请求，不能像目录那样等 120s。 */
+const README_TIMEOUT_MS = 20_000;
+/** 正文上限：超长的 CHANGELOG 类 README 截断，别把几 MB 文本塞进浏览器。 */
+const README_MAX_CHARS = 160_000;
+/** 磁盘缓存 TTL：README 变动不频繁，7 天足够，过期再取一次。 */
+const README_CACHE_TTL_MS = 7 * 24 * 3600_000;
+/** GitHub raw 里按顺序尝试的文件名（大小写在不同仓库里真的不一样）。 */
+const README_FILES = ["README.md", "readme.md", "Readme.md", "README.MD", "README.markdown", "README_EN.md"];
+const NPM_REGISTRY = "https://registry.npmjs.org";
+
+function readmeCacheDir(options = {}) {
+  return join(awesomeMarketDir(options), "readme");
+}
+
+/** 缓存文件名：来源标识压成安全短名（不用 crypto，避免多一个依赖）。 */
+function readmeCachePath(key, options = {}) {
+  const safe = String(key || "").toLowerCase().replace(/[^a-z0-9._-]+/g, "_").slice(0, 96) || "item";
+  return join(readmeCacheDir(options), `${safe}.json`);
+}
+
+/**
+ * 从各种形态的仓库字段里提取 `owner/repo`；不是 GitHub 或提取不到返回 ""。
+ * 吃到过的形态：`owner/repo`、`https://github.com/o/r`、`git+https://github.com/o/r.git`、
+ * `git@github.com:o/r.git`、带 `#readme` / `/tree/main` 尾巴的。
+ */
+export function parseGithubRepo(value) {
+  if (typeof value !== "string") return "";
+  let text = value.trim();
+  if (!text) return "";
+  const ssh = /^git@github\.com:([^/\s]+)\/([^/\s#]+?)(?:\.git)?$/i.exec(text);
+  if (ssh) return `${ssh[1]}/${ssh[2].replace(/\.git$/i, "")}`;
+  text = text.replace(/^git\+/i, "");
+  const http = /^https?:\/\/(?:www\.)?github\.com\/([^/\s]+)\/([^/\s#?]+)/i.exec(text);
+  if (http) return `${http[1]}/${http[2].replace(/\.git$/i, "")}`;
+  const bare = /^([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9._-]+)$/.exec(text);
+  if (bare) return `${bare[1]}/${bare[2].replace(/\.git$/i, "")}`;
+  return "";
+}
+
+/** 正文规整：去 BOM、统一换行、按字符上限截断。 */
+function normalizeReadme(text) {
+  let out = String(text || "").replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  if (out.length > README_MAX_CHARS) {
+    return { markdown: out.slice(0, README_MAX_CHARS), truncated: true };
+  }
+  return { markdown: out, truncated: false };
+}
+
+/** 单次文本 GET（带超时）；非 2xx 也把 body 读掉，避免连接悬挂。 */
+async function fetchReadmeText(url, accept) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), README_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, {
+      headers: { "user-agent": USER_AGENT, accept },
+      signal: controller.signal,
+      redirect: "follow",
+    });
+    if (!response.ok) {
+      try {
+        await response.text();
+      } catch {
+        // 忽略：只为释放连接
+      }
+      return { ok: false, reachable: true, status: response.status, error: `HTTP ${response.status}` };
+    }
+    return { ok: true, reachable: true, status: response.status, text: await response.text(), url: response.url || url };
+  } catch (error) {
+    const reason = error && error.name === "AbortError" ? `超时（${README_TIMEOUT_MS}ms）` : String((error && error.message) || error);
+    return { ok: false, reachable: false, status: 0, error: reason };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** npm 侧取 README：先打 `/<pkg>/latest`（小），没有再退全量 packument。 */
+async function readmeFromNpm(npmName) {
+  const encoded = String(npmName).replace(/\//g, "%2F");
+  const latest = await fetchReadmeText(`${NPM_REGISTRY}/${encoded}/latest`, "application/json");
+  if (latest.ok) {
+    let doc = null;
+    try {
+      doc = JSON.parse(latest.text);
+    } catch {
+      doc = null;
+    }
+    if (doc && typeof doc.readme === "string" && doc.readme.trim()) {
+      return { ok: true, markdown: doc.readme, repo: parseGithubRepo(doc.repository), file: doc.readmeFilename || "README.md" };
+    }
+  }
+  const full = await fetchReadmeText(`${NPM_REGISTRY}/${encoded}`, "application/json");
+  if (!full.ok) {
+    return { ok: false, error: full.error };
+  }
+  let packument = null;
+  try {
+    packument = JSON.parse(full.text);
+  } catch {
+    return { ok: false, error: "npm 返回的不是合法 JSON" };
+  }
+  const markdown = packument && typeof packument.readme === "string" ? packument.readme : "";
+  if (!markdown.trim()) {
+    return { ok: false, error: latest.ok ? "npm 包没有 README" : `${latest.error}；npm 包没有 README` };
+  }
+  return { ok: true, markdown, repo: parseGithubRepo(packument.repository), file: packument.readmeFilename || "README.md" };
+}
+
+/**
+ * GitHub 侧 README 的候选基底，按「先直连、后被墙可用」排序。
+ * raw.githubusercontent.com 在部分网络（含国内常见环境）会直接 DNS 失败，
+ * 因此补 jsDelivr 的 GitHub 镜像（@main / @master 两个默认分支都试）。
+ * 每个基底各自独立：谁先拿到正文，就用谁的目录当相对图片的解析基准。
+ */
+function readmeGithubBases(repo) {
+  return [
+    `https://raw.githubusercontent.com/${repo}/HEAD/`,
+    `https://cdn.jsdelivr.net/gh/${repo}@main/`,
+    `https://cdn.jsdelivr.net/gh/${repo}@master/`,
+    `https://fastly.jsdelivr.net/gh/${repo}@main/`,
+    `https://fastly.jsdelivr.net/gh/${repo}@master/`,
+  ];
+}
+
+/**
+ * GitHub 侧取 README：按 README_FILES 顺序在候选基底上试。
+ * 一旦某个基底返回过任何 HTTP 响应，就认定网络可达：此时把该基底的
+ * 文件名全试完即可收工（不再换基底，避免对一个没 README 的仓库打 30 次请求）。
+ */
+async function readmeFromGithub(repo) {
+  let lastError = "";
+  let sawReachable = false;
+  for (const base of readmeGithubBases(repo)) {
+    for (const file of README_FILES) {
+      const attempt = await fetchReadmeText(`${base}${file}`, "text/plain");
+      if (attempt.ok && attempt.text.trim()) {
+        return { ok: true, markdown: attempt.text, base, file };
+      }
+      if (attempt.ok) {
+        lastError = "文件为空";
+        sawReachable = true;
+        continue;
+      }
+      if (attempt.reachable) {
+        lastError = attempt.error;
+        sawReachable = true;
+        continue;
+      }
+      lastError = attempt.error;
+      break; // 该基底整体不可达（DNS/超时），换下一个
+    }
+    if (sawReachable) break;
+  }
+  return { ok: false, error: lastError || "未找到 README" };
+}
+
+/**
+ * 读取某个市场条目的 README，供客户端详情弹窗预览。
+ *
+ * 入参：`{ name, npm, repo, refresh }`（`npm` 可传字符串或 `{name}`）。
+ * 返回：`{ ok, reason: "cache" | "network" | "no-source" | "readme-unavailable",
+ *          markdown, truncated, source: "npm" | "github", base, repo, npm, fetchedAt }`。
+ *
+ * `base` 是相对图片/链接的解析基准（GitHub raw 目录），客户端据此把 README 里的
+ * 相对路径 `assets/a.png` 还原成可加载的绝对 URL —— 不还原的话插图全是坏图。
+ */
+export async function wbAwesomeReadme(payload = {}) {
+  const name = typeof payload.name === "string" ? payload.name.trim() : "";
+  const npmName =
+    typeof payload.npm === "string"
+      ? payload.npm.trim()
+      : payload.npm && typeof payload.npm === "object" && typeof payload.npm.name === "string"
+        ? payload.npm.name.trim()
+        : "";
+  let repo = parseGithubRepo(payload.repo);
+  const wantRefresh = payload.refresh === true;
+  if (!npmName && !repo) {
+    return { ok: false, reason: "no-source", name, npm: "", repo: "", markdown: "", truncated: false, source: "", base: "", fetchedAt: 0, error: "该条目没有 npm 包名或 GitHub 仓库地址，无法读取 README" };
+  }
+  const cacheKey = npmName || repo;
+  const cachePath = readmeCachePath(cacheKey, payload);
+  if (!wantRefresh) {
+    const cached = await readJsonAt(cachePath);
+    if (
+      cached &&
+      typeof cached.markdown === "string" &&
+      cached.markdown &&
+      Date.now() - Number(cached.fetchedAt || 0) < README_CACHE_TTL_MS
+    ) {
+      return {
+        ok: true,
+        reason: "cache",
+        name,
+        npm: npmName,
+        repo: typeof cached.repo === "string" ? cached.repo : repo,
+        markdown: cached.markdown,
+        truncated: Boolean(cached.truncated),
+        source: typeof cached.source === "string" ? cached.source : "",
+        base: typeof cached.base === "string" ? cached.base : "",
+        fetchedAt: Number(cached.fetchedAt || 0),
+      };
+    }
+  }
+  let markdown = "";
+  let source = "";
+  let base = "";
+  const errors = [];
+  if (npmName) {
+    const fromNpm = await readmeFromNpm(npmName);
+    if (fromNpm.ok) {
+      markdown = fromNpm.markdown;
+      source = "npm";
+      repo = repo || parseGithubRepo(fromNpm.repo);
+      base = repo ? `https://raw.githubusercontent.com/${repo}/HEAD/` : "";
+    } else {
+      errors.push(`npm：${fromNpm.error}`);
+    }
+  }
+  if (!markdown && repo) {
+    const fromGithub = await readmeFromGithub(repo);
+    if (fromGithub.ok) {
+      markdown = fromGithub.markdown;
+      source = "github";
+      base = fromGithub.base;
+    } else {
+      errors.push(`github：${fromGithub.error}`);
+    }
+  }
+  if (!markdown.trim()) {
+    return { ok: false, reason: "readme-unavailable", name, npm: npmName, repo, markdown: "", truncated: false, source: "", base: "", fetchedAt: 0, error: `读取 README 失败：${errors.join("；") || "没有可用来源"}` };
+  }
+  const normalized = normalizeReadme(markdown);
+  const fetchedAt = Date.now();
+  try {
+    await writeAtomic(
+      cachePath,
+      JSON.stringify({ name, npm: npmName, repo, markdown: normalized.markdown, truncated: normalized.truncated, source, base, fetchedAt }),
+    );
+  } catch {
+    // 缓存写不进去不影响这次预览
+  }
+  return { ok: true, reason: "network", name, npm: npmName, repo, markdown: normalized.markdown, truncated: normalized.truncated, source, base, fetchedAt };
+}

package/lib/wb-install-state.js

@@ -1,6 +1,6 @@
 // 本地安装状态 + 来源锁（R8）—— ~/.dsh/armory/install-state.json 的读写层。
 //
-// 职责（设计文档 docs/system_design.md 8.3 / 类图 InstallStateStore）：
+// 职责（对应设计 §8.3，类图 InstallStateStore）：
 //   - record(item)：按 kind+key 定位，已存在则覆盖并刷新 lastUpdated；
 //     首次写入补 installedAt。connector 不记 filesDigest，plugin/skill 记关键文件摘要。
 //   - forget(kind, key)：删除一条登记，不存在时为无害空操作。

package/lib/wb-market.js

@@ -420,8 +420,23 @@ export async function wbConnectorCachedCount() {
 // 文件：/api/v1/skills/:slug/files?namespace=<handle>[&version=]；/file 同形 + &path=
 // namespace 用 namespace.handle（列表项里是对象）， 不是 canonicalName。
 const SKILLHUB_SORTS = new Set(["downloads", "installs", "stars", "score"]);
-async function skillhubJson(path) {
-  const buffer = await fetchWithLimits(`${SKILLHUB_ORIGIN}${path}`);
+// 2026-10 实测（api.skillhub.cn）：`sortBy=downloads` 已不再是可用值——TCP 能连上、
+// 但服务端不回任何字节，一直挂到客户端 AbortSignal 超时；installs / stars / score /
+// updated 仍正常，非法值（download、hot、new…）会立刻 400 而不是挂起。
+// 所以下载量排序不再发给上游，改成本地按当前页排序（见 wbSkillCatalog 尾部）。
+const SKILLHUB_REMOTE_SORTS = new Set(["installs", "stars", "score"]);
+async function skillhubJson(path, { timeoutMs = 15_000 } = {}) {
+  let buffer;
+  try {
+    buffer = await fetchWithLimits(`${SKILLHUB_ORIGIN}${path}`, { timeoutMs });
+  } catch (e) {
+    // 超时是上游最常见的一种失败（挂起而非 4xx），把 Node 的英文原文换成能看懂的中文。
+    const name = e && e.name;
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw new Error(`SkillHub 在 ${Math.round(timeoutMs / 1000)} 秒内没有响应，已放弃本次请求；稍后重试即可。`);
+    }
+    throw e;
+  }
   const body = JSON.parse(buffer.toString("utf8"));
   // SkillHub 的业务错误也在 200 里（code !== 0）。
   if (body && typeof body.code === "number" && body.code !== 0) throw new Error(`SkillHub 返回错误：${body.message || body.code}`);
@@ -431,13 +446,38 @@ export async function wbSkillCatalog(payload = {}) {
   const page = Math.max(1, Math.min(200, Number(payload.page) || 1));
   const pageSize = Math.max(1, Math.min(60, Number(payload.pageSize) || 20));
   const sort = SKILLHUB_SORTS.has(payload.sort) ? payload.sort : "downloads";
-  const params = new URLSearchParams({ sortBy: sort, page: String(page), pageSize: String(pageSize) });
+  const remoteSort = SKILLHUB_REMOTE_SORTS.has(sort) ? sort : "";
+  // 只把上游确认可用的排序发出去：`sortBy=downloads` 会挂起（见 SKILLHUB_REMOTE_SORTS）。
+  // 不带 sortBy 时上游按自己的默认序返回，参数缺失不会 400（已实测）。
+  const params = new URLSearchParams({ page: String(page), pageSize: String(pageSize) });
+  if (remoteSort) params.set("sortBy", remoteSort);
   const keyword = String(payload.keyword || "").trim();
   if (keyword) params.set("keyword", keyword.slice(0, 64));
   const category = String(payload.category || "").trim();
   if (category) params.set("category", category.slice(0, 64));
   const body = await skillhubJson(`/api/skills?${params.toString()}`);
   const skills = Array.isArray(body?.data?.skills) ? body.data.skills : [];
+  const rows = skills.map((skill) => ({
+    slug: String(skill.slug || ""),
+    name: String(skill.name || skill.slug || ""),
+    namespace: String(skill.namespace?.handle || ""),
+    canonical: String(skill.namespace?.canonicalName || ""),
+    description: String(skill.description_zh || skill.description || ""),
+    descriptionEn: String(skill.description_en || ""),
+    downloads: Number(skill.downloads) || 0,
+    installs: Number(skill.installs) || 0,
+    stars: Number(skill.stars) || 0,
+    score: Number(skill.score) || 0,
+    version: String(skill.version || ""),
+    verified: !!skill.verified,
+    updatedAt: Number(skill.updated_at) || 0,
+    category: String(skill.category || ""),
+    tags: Array.isArray(skill.tags) ? skill.tags.slice(0, 6).map(String) : [],
+    upstreamUrl: String(skill.upstream_url || skill.homepage || ""),
+  })).filter((skill) => skill.slug && skill.namespace);
+  // 下载量排序上游已不可用，退化为「当前页内按下载量降序」：跨页顺序仍是上游默认序，
+  // 所以这是页内排序而不是全库排序（UI 侧「最多下载」的含义随之收窄，见下）。
+  if (!remoteSort) rows.sort((a, b) => b.downloads - a.downloads);
   return {
     page,
     pageSize,
@@ -445,24 +485,7 @@ export async function wbSkillCatalog(payload = {}) {
     keyword,
     category,
     total: Number(body?.data?.total) || 0,
-    skills: skills.map((skill) => ({
-      slug: String(skill.slug || ""),
-      name: String(skill.name || skill.slug || ""),
-      namespace: String(skill.namespace?.handle || ""),
-      canonical: String(skill.namespace?.canonicalName || ""),
-      description: String(skill.description_zh || skill.description || ""),
-      descriptionEn: String(skill.description_en || ""),
-      downloads: Number(skill.downloads) || 0,
-      installs: Number(skill.installs) || 0,
-      stars: Number(skill.stars) || 0,
-      score: Number(skill.score) || 0,
-      version: String(skill.version || ""),
-      verified: !!skill.verified,
-      updatedAt: Number(skill.updated_at) || 0,
-      category: String(skill.category || ""),
-      tags: Array.isArray(skill.tags) ? skill.tags.slice(0, 6).map(String) : [],
-      upstreamUrl: String(skill.upstream_url || skill.homepage || ""),
-    })).filter((skill) => skill.slug && skill.namespace),
+    skills: rows,
   };
 }
 export async function wbSkillDetail(payload = {}) {

package/lib/wb-registry.js

@@ -1,6 +1,6 @@
 // 多市场注册表（R4）—— ~/.dsh/armory/marketplaces.json 的读写层。
 //
-// 职责（设计文档 docs/system_design.md 8.3 / 类图 MarketRegistry）：
+// 职责（对应设计 §8.3，类图 MarketRegistry）：
 //   - 注册表文件不存在或损坏时，回落到**内置默认两条**：连接器源（与 lib/wb-market.js:27
 //     的 CONNECTOR_ZIP_URL 保持同一现值，禁止在此发明第二处硬编码真相）与
 //     codebuddy-plugins-official 插件源；首读时把默认项落盘。

package/lib/whats-new.js

@@ -370,4 +370,50 @@ export const WHATS_NEW = [
       },
     ],
   },
+  {
+    version: '2.1.0',
+    items: [
+      {
+        text: '**社区插件能看 README 了**：点开 DSH 社区里的任意一张卡片，就地把该仓库的 README 拉下来渲染成可读正文（标题、段落、列表、代码块、表格、引用），不用跳浏览器。只在点开时按需取一次（20s 超时 / 16 万字符上限），取到后按「仓库或 npm 包名」落盘缓存 7 天，同一插件再点秒开、断网也能看。图片走只读代理绕开防盗链；渲染器是自写的，**不碰 `dangerouslySetInnerHTML`**，`javascript:` 这类伪协议链接一律降级成纯文本',
+        where: '插件 → DSH 社区 → 点开任意卡片',
+      },
+      {
+        text: '**社区目录不再卡在旧快照上**：首屏先渲染 localStorage 快照（0 网络 0 IPC），但真实目录结果回来后必须覆盖快照。之前快照一渲染，真实结果就被丢掉，目录于是一直停在旧快照上——现在两条路径都落到同一份状态，秒开与新鲜兼得',
+        where: '插件 → DSH 社区',
+      },
+      {
+        text: '**「更新探测失败」修好了**：过去探测只问主源，主源不通、目录靠备用源加载成功的机器上，目录能开、探测却每次都报失败。现在探测与目录走同一条源链——先问这份缓存实际来自哪个源（ETag 同源才可比），再兜底其余源，首个拿到 ETag 的源胜出，全部失败才报 `probe-failed`',
+        where: '插件 → DSH 社区 → 检查更新',
+      },
+    ],
+  },
+  {
+    version: '2.2.0',
+    items: [
+      {
+        text: '**自定义套件**：把常一起用的 skill 打包成一套，召唤菜单里点一次，就按成员顺序展开成多个 `/name` 插进草稿。Skill 看板工具栏「套件」里新建 / 编辑：点 + 或把技能拖进来添加，拖拽排序，删除要就地二次确认；保存是整集合覆盖，落 `~/.dsh/armory/suites.json`（staging + rename 原子写）。上限 100 个套件 / 每套 40 个成员',
+        where: '技能 →「套件」；输入框召唤菜单 →「技能」→ 套件分组',
+      },
+      {
+        text: '**技能看板能卸载了**：用户级 / 项目级目录里的 skill 可在详情里直接卸载（就地二次确认，永久删除、不进回收站）；随 DSH 分发、运行时注册与自定义目录的 skill 仍只读。卸载走本插件的 `removeSkill`，带来源白名单、根目录包含性、符号链接只删链接等校验',
+        where: '技能 → 任一本机 skill → 详情',
+      },
+      {
+        text: '**装 / 卸即时刷新**：在市场里安装或卸载技能后，顶部 **Skill** 数量角标与技能看板列表立即对齐新集合，不用切页或重开面板；异步重取带序号守卫，快速连点也不会被旧回包回滚',
+        where: '市场 ↔ 技能',
+      },
+      {
+        text: '**工具裁缝补上时间维度**：按天采样 `request/header` 里**真实下发**的工具清单，算出线上真实税，并给出「窗口内清单变过几次」「最近一次变化时间」；与注册表快照不一致时直接说明是「改了没生效」还是「线上多发了工具」。本机日志跨度短于所选窗口、或有调用缺时间戳时，也会在说明栏明示',
+        where: '工具裁缝 → 指标卡下方的税趋势',
+      },
+      {
+        text: '**SkillHub「下载量」排序不再挂起**：上游 `sortBy=downloads` 现在收下请求却不回包，插件改为不把它发给上游、在当前页内按下载量降序；其余排序照常走远程。请求 15 秒无响应即放弃，并把 Node 的英文超时换成中文说明',
+        where: '市场 → 技能 → 排序',
+      },
+      {
+        text: '工具裁缝账本缓存行改为只读：删掉「清空缓存」按钮（实测既不回收空间、也不修任何事，还会一直停在「正在清空缓存…」）',
+        where: '工具裁缝 → 账本信息',
+      },
+    ],
+  },
 ]

package/lib/workspace-runtime.js

@@ -310,7 +310,7 @@ function releaseSharedConnection(ctx, entry) {
 // 上游 @modelcontextprotocol/client 的 stdio transport 里，`close()` 等的是子进程的 `'close'`
 // 事件；孙进程（npx/uvx 包装器、server 内部的 helper）继承并持有 stdio 管道时，`'close'`
 // 永不触发，回收就永久挂在等待上。既无法从这侧打断，就只能把「已经等了多久、有没有超阈、
-// 上次花了多久」变成可见事实，让人自己决定重启宿主。上游提案见 docs/host-proposal-mcp-teardown.md。
+// 上次花了多久」变成可见事实，让人自己决定重启宿主。上游提案的结论见 .github/release-notes/v1.10.0.md。
 //
 // OPT-15：每次 teardown 的耗时落档，按 app root 分桶，桶内按 connKey 只留最近一条。
 // 只留一条的理由：面板要回答的是「这条连接现在还卡不卡」，不是审计历史；留全量会让

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-armory",
-  "version": "2.0.0",
-  "description": "Unified Skill + MCP + Expert + Plugin board for DeepSeek Harness (desktop app and Web GUI) — global panel page, JSON import, WorkBuddy connector & SkillHub & Expert & CodeBuddy plugin & awesome-dsh-plugins market installs, MCP OAuth authorization, tool-usage tailor, and profile-backed Host Remote management.",
+  "version": "2.2.0",
+  "description": "Unified Skill + MCP + Expert + Plugin board for DeepSeek Harness (desktop app and Web GUI) — custom skill suites, skill install/uninstall with live refresh, global panel page, JSON import, WorkBuddy connector & SkillHub & Expert & CodeBuddy plugin & awesome-dsh-plugins market installs, MCP OAuth authorization, tool-usage tailor with wire-tax trends, and profile-backed Host Remote management.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/2026heshao/dsh-armory.git"