dsh-armory 2.0.0 → 2.1.0

package/lib/index.js

@@ -18,7 +18,7 @@ import { probeMcpServersAuthorization, wbConnectorCatalog, wbConnectorCachedCoun
 import { readRegistry, upsertMarketplace } from "./wb-registry.js";
 import { wbPluginCatalog, wbPluginDetail, wbPluginUpdateCheck } from "./wb-plugin-market.js";
 // T06/Awesome：DSH 社区插件市场（awesome-dsh-plugins）的宿主侧数据层。
-import { wbAwesomeCatalog, wbAwesomeDetail, wbAwesomeUpdateCheck } from "./wb-awesome-market.js";
+import { wbAwesomeCatalog, wbAwesomeDetail, wbAwesomeReadme, wbAwesomeUpdateCheck } from "./wb-awesome-market.js";
 import { readState as readInstallState, record as recordInstallState, forget as forgetInstallState } from "./wb-install-state.js";
 import { applyTokens } from "./wb-auth-rules.js";
 import {
@@ -989,7 +989,7 @@ async function listMcpServers(ctx) {
 let McpManagerGateway = (() => {
 	let _classSuper = TypertRemoteService;
 	let _instanceExtraInitializers = [];
-	let _list_decorators, _status_decorators, _enable_decorators, _disable_decorators, _reconnect_decorators, _tools_decorators, _builtins_decorators, _installBuiltins_decorators, _add_decorators, _update_decorators, _remove_decorators, _reveal_decorators, _previewImport_decorators, _importJson_decorators, _listWorkspaces_decorators, _getWorkspaceView_decorators, _addWorkspaceServer_decorators, _updateWorkspaceServer_decorators, _removeWorkspaceServer_decorators, _setWorkspaceExclude_decorators, _installWorkspaceBuiltins_decorators, _previewWorkspaceImport_decorators, _importWorkspaceJson_decorators, _revealWorkspaceServer_decorators, _projectConnections_decorators, _reconnectWorkspaceServer_decorators, _updateHint_decorators, _whatsNew_decorators, _scanImportSources_decorators, _previewImportSource_decorators, _importSource_decorators, _toolTailor_decorators, _wbConnectorCatalog_decorators, _wbConnectorCachedCount_decorators, _wbConnectorPreview_decorators, _wbConnectorInstall_decorators, _wbOAuthBegin_decorators, _wbOAuthPoll_decorators, _wbOAuthCancel_decorators, _wbOAuthToken_decorators, _wbOAuthOverview_decorators, _wbOAuthOpen_decorators, _wbSkillCatalog_decorators, _wbSkillDetail_decorators, _wbSkillInstall_decorators, _wbSkillUninstall_decorators, _wbSkillInstalled_decorators, _wbMarketRegistry_decorators, _wbMarketRegistryUpsert_decorators, _wbPluginCatalog_decorators, _wbPluginDetail_decorators, _wbInstallState_decorators, _wbInstallStateRecord_decorators, _wbInstallStateForget_decorators, _wbPluginUpdateCheck_decorators, _wbAwesomeCatalog_decorators, _wbAwesomeDetail_decorators, _wbAwesomeUpdateCheck_decorators;
+	let _list_decorators, _status_decorators, _enable_decorators, _disable_decorators, _reconnect_decorators, _tools_decorators, _builtins_decorators, _installBuiltins_decorators, _add_decorators, _update_decorators, _remove_decorators, _reveal_decorators, _previewImport_decorators, _importJson_decorators, _listWorkspaces_decorators, _getWorkspaceView_decorators, _addWorkspaceServer_decorators, _updateWorkspaceServer_decorators, _removeWorkspaceServer_decorators, _setWorkspaceExclude_decorators, _installWorkspaceBuiltins_decorators, _previewWorkspaceImport_decorators, _importWorkspaceJson_decorators, _revealWorkspaceServer_decorators, _projectConnections_decorators, _reconnectWorkspaceServer_decorators, _updateHint_decorators, _whatsNew_decorators, _scanImportSources_decorators, _previewImportSource_decorators, _importSource_decorators, _toolTailor_decorators, _wbConnectorCatalog_decorators, _wbConnectorCachedCount_decorators, _wbConnectorPreview_decorators, _wbConnectorInstall_decorators, _wbOAuthBegin_decorators, _wbOAuthPoll_decorators, _wbOAuthCancel_decorators, _wbOAuthToken_decorators, _wbOAuthOverview_decorators, _wbOAuthOpen_decorators, _wbSkillCatalog_decorators, _wbSkillDetail_decorators, _wbSkillInstall_decorators, _wbSkillUninstall_decorators, _wbSkillInstalled_decorators, _wbMarketRegistry_decorators, _wbMarketRegistryUpsert_decorators, _wbPluginCatalog_decorators, _wbPluginDetail_decorators, _wbInstallState_decorators, _wbInstallStateRecord_decorators, _wbInstallStateForget_decorators, _wbPluginUpdateCheck_decorators, _wbAwesomeCatalog_decorators, _wbAwesomeDetail_decorators, _wbAwesomeReadme_decorators, _wbAwesomeUpdateCheck_decorators;
 	return class McpManagerGateway extends _classSuper {
 		static {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -1111,6 +1111,8 @@ let McpManagerGateway = (() => {
 			__esDecorate(this, null, _wbAwesomeCatalog_decorators, { kind: "method", name: "wbAwesomeCatalog", static: false, private: false, access: { has: (obj) => "wbAwesomeCatalog" in obj, get: (obj) => obj.wbAwesomeCatalog }, metadata: _metadata }, null, _instanceExtraInitializers);
 			_wbAwesomeDetail_decorators = [Remote("wbAwesomeDetail")];
 			__esDecorate(this, null, _wbAwesomeDetail_decorators, { kind: "method", name: "wbAwesomeDetail", static: false, private: false, access: { has: (obj) => "wbAwesomeDetail" in obj, get: (obj) => obj.wbAwesomeDetail }, metadata: _metadata }, null, _instanceExtraInitializers);
+			_wbAwesomeReadme_decorators = [Remote("wbAwesomeReadme")];
+			__esDecorate(this, null, _wbAwesomeReadme_decorators, { kind: "method", name: "wbAwesomeReadme", static: false, private: false, access: { has: (obj) => "wbAwesomeReadme" in obj, get: (obj) => obj.wbAwesomeReadme }, metadata: _metadata }, null, _instanceExtraInitializers);
 			_wbAwesomeUpdateCheck_decorators = [Remote("wbAwesomeUpdateCheck")];
 			__esDecorate(this, null, _wbAwesomeUpdateCheck_decorators, { kind: "method", name: "wbAwesomeUpdateCheck", static: false, private: false, access: { has: (obj) => "wbAwesomeUpdateCheck" in obj, get: (obj) => obj.wbAwesomeUpdateCheck }, metadata: _metadata }, null, _instanceExtraInitializers);
 			if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
@@ -1840,6 +1842,9 @@ let McpManagerGateway = (() => {
 	async wbAwesomeDetail(payload) {
 		return wbAwesomeDetail(payload?.name);
 	}
+	async wbAwesomeReadme(payload) {
+		return wbAwesomeReadme(payload || {});
+	}
 	async wbAwesomeUpdateCheck() {
 		return wbAwesomeUpdateCheck();
 	}

package/lib/mcp-oauth.js

@@ -29,7 +29,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 /** 插件版本：DCR 的 clientInfo 与 UA 共用一处，避免两边各自漂移。 */
-const PLUGIN_VERSION = "2.0.0";
+const PLUGIN_VERSION = "2.1.0";
 const USER_AGENT = `dsh-armory/${PLUGIN_VERSION} (+mcp-oauth)`;
 const NET_TIMEOUT_MS = 15_000;
 /** 授权流程整体存活时间：超过就判过期，避免会话表无限增长。 */

package/lib/typert.js

@@ -109,6 +109,8 @@ export const TYPERT = {
     // T06/Awesome：DSH 社区插件市场（awesome-dsh-plugins，数据层 lib/wb-awesome-market.js）。
     mv('wbAwesomeCatalog', [payloadParam], 'AwesomeCatalogResult'),
     mv('wbAwesomeDetail', [payloadParam], 'AwesomeDetailResult'),
+    // README 预览：点击卡片按需取一次（npm registry / GitHub raw），落盘缓存 7 天。
+    mv('wbAwesomeReadme', [payloadParam], 'AwesomeReadmeResult'),
     mv('wbAwesomeUpdateCheck', [], 'WbUpdateHintResult'),
     // WorkBuddy 专家直连（召唤预设 + 捆绑技能）。payload 全部 $any：数据形状由
     // lib/expert-market.js 校验，与 wb* 系列同一宽容度。

package/lib/wb-awesome-market.js

@@ -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/whats-new.js

@@ -370,4 +370,21 @@ 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 社区 → 检查更新',
+      },
+    ],
+  },
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-armory",
-  "version": "2.0.0",
+  "version": "2.1.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.",
   "repository": {
     "type": "git",