dsh-armory 2.0.0 → 2.1.0

package/lib/client.js

@@ -277,7 +277,7 @@ const EN_US_MESSAGES = {
  "目录缓存已过期（更新源暂时不可达，显示的是本地缓存）。": "The cached catalog is stale (update sources unreachable; showing the local cache).",
  "DSH 社区目录有新版本（本地缓存 {0}）。点「重新加载」可拉取最新目录。": "The DSH community catalog has a newer version (local cache {0}). Click \"Reload\" to fetch the latest catalog.",
  "本地还没有 DSH 社区目录缓存，点「重新加载」可首次拉取目录。": "No local DSH community catalog cache yet. Click \"Reload\" to fetch it for the first time.",
- "DSH 社区目录更新探测失败（不影响已安装插件）。": "DSH community catalog update probe failed (installed plugins are not affected).",
+ 
  "正在加载 DSH 社区目录…": "Loading the DSH community catalog…",
  "DSH 社区目录暂时是空的": "The DSH community catalog is temporarily empty",
  "目录来自 awesome-dsh-plugins 社区清单（jsdelivr CDN 分发），拉取失败可重试。": "The catalog comes from the awesome-dsh-plugins community registry (jsdelivr CDN); retry if fetching failed.",
@@ -550,8 +550,6 @@ const EN_US_MESSAGES = {
  "正在召唤 {0}…": "Summoning {0}…",
  "正在安装 {0}…": "Installing {0}…",
  "正在扫描本机客户端配置…": "Scanning local client configs…",
- "正在拉取人设与技能清单…": "Fetching persona and skill list…",
- "正在拉取详情…": "Fetching details…",
  "正在挂载专家…": "Attaching expert…",
  "正在读取 MCP 目录…": "Reading MCP catalog…",
  "正在读取…": "Reading…",
@@ -888,6 +886,15 @@ const EN_US_MESSAGES = {
   "复制 SKILL.md 路径": "Copy SKILL.md path",
   "复制 @会话引用": "Copy @session reference",
 
+  // DSH 社区插件 README 预览弹层（点卡片打开）。
+  "查看 README 介绍与插图": "View README intro & images",
+  "{0} README 预览": "{0} · README preview",
+  "正在读取 README…": "Loading README…",
+  "README 过长，已截断显示。": "README is long; showing a truncated version.",
+  "重新读取": "Reload",
+  "读取 README 失败：未知错误": "Failed to read README: unknown error",
+  "预览服务尚未加载，请完全退出 DSH 后重新打开再试": "The preview service is not loaded yet. Fully quit DSH, reopen it, then try again.",
+
   "：": ": ",
 };
 // OPT-14 · 1.1：仅当判定为英文 locale 时装载 en-US 表；zh-CN（源语言）保持空字典
@@ -969,6 +976,18 @@ function writeAwesomeSnapshot(payload) {
   } catch { /* 配额溢出 / 隐私模式：快照只是加速，失败不致命 */ }
 }
 
+// ── 更新探测节流：把「每次进面板都 HEAD 一发」压到 6 小时一次 ────────────────
+// 目录本身已有服务端 stale-while-revalidate 在后台自动换新，这个 ETag 探测只是
+// 锦上添花；没必要每开一次面板就多打一次网络、多一次误报机会。
+const AWESOME_PROBE_AT_KEY = KEY_PREFIX + '.awesomeProbeAt.v1';
+const AWESOME_PROBE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+function readAwesomeProbeAt() {
+  try { return Number(localStorage.getItem(AWESOME_PROBE_AT_KEY)) || 0; } catch { return 0; }
+}
+function writeAwesomeProbeAt(value) {
+  try { localStorage.setItem(AWESOME_PROBE_AT_KEY, String(value)); } catch { /* 隐私模式：退化为不节流 */ }
+}
+
 // ── 安装轻提示：挂在 document.body 上的常驻浮层 ─────────────────────────────
 // 安装进度此前只存在组件本地 state（busy / busyLabel）：用户一切到别的面板或窗口，
 // 组件卸载 → 进度消失 → 看起来像「安装被取消了」。这个浮层直接挂 document.body，
@@ -1083,6 +1102,420 @@ function isInstallRunning(name) {
   return Boolean(task && task.phase === 'running');
 }
 
+// ── README 预览：极简 markdown 渲染 + 插图还原 ────────────────────────────────
+//
+// 为什么自己写：本文件没有 react-dom，也没有任何 markdown 依赖；README 又是公网
+// 数据（不可信）。于是这里只做一件事——把 markdown 扫成块，逐块构造 React 元素，
+// 全程不拼字符串、不用 innerHTML，链接一律过 URL 白名单。
+//
+// 覆盖 README 真正会用到的那部分语法：标题 / 段落 / 行内代码 / 围栏代码 / 无序与
+// 有序列表 / 引用 / 分隔线 / 表格 / 粗体 / 斜体 / 删除线 / 链接 / 图片，外加裸 HTML
+// 里的 <img>、<a>、<br>（插件展示页几乎都用 <p align="center"><img …> 摆横幅）。
+
+const README_STYLE_ID = KEY_PREFIX + '.readme-style';
+let readmeStyleInjected = false;
+
+function ensureReadmeStyle() {
+  if (readmeStyleInjected || typeof document === 'undefined') return;
+  readmeStyleInjected = true;
+  if (document.getElementById(README_STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = README_STYLE_ID;
+  style.textContent = [
+    '.dsh-mcp-readme-modal{width:min(880px,94vw);max-width:94vw;max-height:86vh}',
+    '.dsh-mcp-readme-meta{display:flex;flex-wrap:wrap;gap:8px;margin-top:6px;font-size:12px;opacity:.75}',
+    '.dsh-mcp-readme-body{margin-top:12px;overflow-wrap:anywhere}',
+    '.dsh-mcp-md-h{margin:20px 0 8px;font-weight:600;line-height:1.35;letter-spacing:0}',
+    '.dsh-mcp-md-h:first-child{margin-top:0}',
+    '.dsh-mcp-md-p{margin:8px 0;line-height:1.72}',
+    '.dsh-mcp-md-ul,.dsh-mcp-md-ol{margin:8px 0;padding-inline-start:22px}',
+    '.dsh-mcp-md-li{margin:3px 0;line-height:1.7}',
+    '.dsh-mcp-md-quote{margin:10px 0;padding:4px 12px;border-inline-start:3px solid var(--dsw-alias-border-strong,rgba(127,127,127,.4));opacity:.9}',
+    '.dsh-mcp-md-code{padding:1px 5px;border-radius:4px;background:var(--dsw-alias-bg-subtle,rgba(127,127,127,.14));font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.92em}',
+    '.dsh-mcp-md-pre{margin:10px 0;padding:10px 12px;border-radius:8px;overflow:auto;background:var(--dsw-alias-bg-subtle,rgba(127,127,127,.12));font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.88em;line-height:1.6}',
+    // 插图尺寸：README 里的截图常是 1600~3000px 的巨图，只限宽会把弹层撑成一根滚动条。
+    // 这里同时限宽与限高（40vh：小窗口自动更小，一屏必能看到整张），等比缩放不裁切；
+    // width:auto 保证小徽章不被放大糊成一片。真正的硬约束写在 img 的 inline style 上，
+    // 这两条只是同值的样式兜底，避免「样式没注入成功就失控」。
+    '.dsh-mcp-md-img{display:block;box-sizing:border-box;width:auto;max-width:100%;max-height:min(40vh,420px);height:auto;margin:10px 0;border-radius:8px;object-fit:contain;background:var(--dsw-alias-bg-subtle,rgba(127,127,127,.08))}',
+    '.dsh-mcp-md-img-inline{display:inline-block;max-height:22px;max-width:min(100%,320px);width:auto;height:auto;margin:0 2px;vertical-align:middle;border-radius:4px;object-fit:contain}',
+    // 兜底：任何来源塞进正文的 img（含裸 HTML 块里未被抽出的）都不许超出弹层宽度。
+    '.dsh-mcp-readme-body img{max-width:100%}',
+    '.dsh-mcp-readme-body table img{max-height:min(24vh,220px)}',
+    '.dsh-mcp-md-table{width:100%;margin:10px 0;border-collapse:collapse;font-size:.92em}',
+    '.dsh-mcp-md-table th,.dsh-mcp-md-table td{padding:6px 10px;border:1px solid var(--dsw-alias-border-subtle,rgba(127,127,127,.25));text-align:start;vertical-align:top}',
+    '.dsh-mcp-md-table th{background:var(--dsw-alias-bg-subtle,rgba(127,127,127,.10));font-weight:600}',
+    '.dsh-mcp-md-a{color:var(--dsw-alias-accent,#3b82f6);text-decoration:none}',
+    '.dsh-mcp-md-a:hover{text-decoration:underline}',
+    '.dsh-mcp-md-hr{margin:16px 0;border:0;border-top:1px solid var(--dsw-alias-border-subtle,rgba(127,127,127,.25))}',
+  ].join('\n');
+  document.head.appendChild(style);
+}
+
+/** 链接/图片地址白名单：只放行 http(s) 与 data:image，其余（javascript: 等）一律丢弃。 */
+function readmeSafeUrl(raw, base) {
+  const text = String(raw == null ? '' : raw).trim().replace(/^<|>$/g, '');
+  if (!text) return '';
+  if (/^data:image\//i.test(text)) return text;
+  if (/^mailto:/i.test(text)) return text;
+  if (/^\/\//.test(text)) return 'https:' + text;
+  if (/^https?:\/\//i.test(text)) return text;
+  if (text.startsWith('#')) return text;
+  if (!base) return '';
+  const rel = text.replace(/^\.\//, '');
+  if (rel.startsWith('/')) {
+    // 站内绝对路径：GitHub raw 的 base 形如 .../<owner>/<repo>/HEAD/，回到仓库根。
+    const root = /^(https:\/\/raw\.githubusercontent\.com\/[^/]+\/[^/]+\/[^/]+)\//.exec(base);
+    return root ? root[1] + '/' + rel.slice(1) : '';
+  }
+  try {
+    const resolved = new URL(rel, base);
+    // 关键：new URL('javascript:alert(1)', base) 解析成功且协议是 javascript:，
+    // 只靠 base 拼相对路径会把伪协议放行成可点击 href，这里必须再校验一次协议。
+    if (resolved.protocol !== 'http:' && resolved.protocol !== 'https:') return '';
+    return resolved.toString();
+  } catch {
+    return '';
+  }
+}
+
+/** 解析 `![alt](url "title")` / `[text](url "title")`（url 里允许成对括号）。 */
+function readmeSplitLink(token) {
+  const match = /^(!?)\[([^\]\n]*)\]\(\s*([^()\s]*(?:\([^()]*\)[^()\s]*)*)(?:\s+"([^"\n]*)")?\s*\)$/.exec(String(token || ''));
+  if (!match) return null;
+  return { image: match[1] === '!', label: match[2], url: match[3], title: match[4] || '' };
+}
+
+/* README 插图缩图代理。
+ * 直连 GitHub 原图有两个硬伤：①README 截图常见 1600~3000px、单张几百 KB 到几 MB，
+ * 跨国拉取常只有几十 KB/s，浏览器自上而下逐行解码，看起来就是「图只显示了一部分」；
+ * ②原图字节多，弹层一打开就并发十几张，把带宽抢光，整个弹层都卡。
+ * 所以 GitHub 系图片先走 wsrv.nl 缩到 880 宽（webp q72，体积通常降到 1/20），
+ * 代理不可用时 onError 回退原图一次，再失败才隐藏——不牺牲可用性。 */
+const README_IMG_PROXY = 'https://wsrv.nl/?output=webp&q=72&w=880&url=';
+const README_IMG_PROXY_HOSTS = [
+  'raw.githubusercontent.com',
+  'user-images.githubusercontent.com',
+  'private-user-images.githubusercontent.com',
+  'objects.githubusercontent.com',
+  'camo.githubusercontent.com',
+  'github.com',
+];
+
+/** 只给 GitHub 系图源生成代理地址；其他源（如 npm registry、shields.io）原样返回 ''。 */
+function readmeProxiedSrc(src) {
+  try {
+    const host = new URL(src).hostname.toLowerCase();
+    if (README_IMG_PROXY_HOSTS.indexOf(host) < 0) return '';
+    return README_IMG_PROXY + encodeURIComponent(src);
+  } catch {
+    return '';
+  }
+}
+
+/** `![alt](url)` → img；相对路径按 base 还原成绝对 URL，还原不了就跳过（不产生坏图）。
+ * 尺寸硬约束写在 inline style 上：不依赖 <style> 是否注入成功，也不怕被别处的 img 规则盖掉。 */
+function readmeImageNode(src, alt, makeKey, base, opts) {
+  const resolved = readmeSafeUrl(src, base);
+  if (!resolved) return null;
+  const inline = Boolean(opts && opts.inline);
+  const proxied = inline ? '' : readmeProxiedSrc(resolved);
+  const props = {
+    key: makeKey('img'),
+    className: inline ? 'dsh-mcp-md-img-inline' : 'dsh-mcp-md-img',
+    src: proxied || resolved,
+    alt: String(alt || ''),
+    loading: 'lazy',
+    decoding: 'async',
+    referrerPolicy: 'no-referrer',
+    style: inline
+      // 行内小图标：压到行高附近，最多占 320px 宽，不把整段文字顶开。
+      ? { display: 'inline-block', width: 'auto', height: 'auto', maxWidth: 'min(100%,320px)', maxHeight: '22px', objectFit: 'contain', verticalAlign: 'middle', margin: '0 2px' }
+      // 块级插图：同时限宽限高，等比缩放不裁切；40vh 保证小窗口也能整张看到。
+      : { display: 'block', boxSizing: 'border-box', width: 'auto', height: 'auto', maxWidth: '100%', maxHeight: 'min(40vh,420px)', objectFit: 'contain', margin: '10px 0', borderRadius: '8px', background: 'var(--dsw-alias-bg-subtle, rgba(127,127,127,.06))' },
+    onError: (event) => {
+      const node = event && event.currentTarget;
+      if (!node) return;
+      // 代理挂了退回原图一次；原图也挂了才隐藏（徽章 404 很常见，别留一排破图标）。
+      const origin = proxied ? node.getAttribute('data-readme-origin') : '';
+      if (origin) {
+        node.setAttribute('src', origin);
+        node.removeAttribute('data-readme-origin');
+        return;
+      }
+      if (node.style) node.style.display = 'none';
+    },
+  };
+  if (proxied) props['data-readme-origin'] = resolved;
+  return h('img', props);
+}
+
+const README_INLINE_RE = /(`[^`\n]+`)|(!\[[^\]\n]*\]\([^()\s]*(?:\([^()]*\)[^()\s]*)*(?:\s+"[^"\n]*")?\s*\))|(\[[^\]\n]+\]\([^()\s]*(?:\([^()]*\)[^()\s]*)*(?:\s+"[^"\n]*")?\s*\))|(\*\*[^*\n]+\*\*)|(__[^_\n]+__)|(~~[^~\n]+~~)|(\*[^*\n]+\*)|(_[^_\n]+_)|(<https?:\/\/[^>\s]+>)|(<img\b[^>]*>)|(<br\s*\/?>)/i;
+
+/** 行内语法 → React 节点数组。纯扫描，不做任何 HTML 解析。 */
+function renderReadmeInline(text, makeKey, base) {
+  const out = [];
+  const source = String(text || '');
+  // 每次调用都用独立的正则实例：renderReadmeInline 会递归（粗体/斜体/链接文字），
+  // 共享 /g 实例的 lastIndex 会被递归内层归零，外层游标因此回退到起点 → 死循环（曾整页 OOM）。
+  const re = new RegExp(README_INLINE_RE.source, 'gi');
+  let cursor = 0;
+  let match = re.exec(source);
+  const pushText = (value) => {
+    if (!value) return;
+    out.push(value);
+  };
+  while (match) {
+    pushText(source.slice(cursor, match.index));
+    const token = match[0];
+    if (token.startsWith('`')) {
+      out.push(h('code', { key: makeKey('code'), className: 'dsh-mcp-md-code' }, token.slice(1, -1)));
+    } else if (token.startsWith('![') || token.startsWith('[')) {
+      const link = readmeSplitLink(token);
+      if (!link) {
+        pushText(token);
+      } else if (link.image) {
+        const node = readmeImageNode(link.url, link.label, makeKey, base, { inline: out.length > 0 });
+        if (node) out.push(node);
+      } else {
+        const href = readmeSafeUrl(link.url, base);
+        out.push(
+          href
+            ? h('a', { key: makeKey('a'), className: 'dsh-mcp-md-a', href, title: link.title || undefined, target: '_blank', rel: 'noreferrer noopener' }, renderReadmeInline(link.label, makeKey, base))
+            : h('span', { key: makeKey('span') }, renderReadmeInline(link.label, makeKey, base)),
+        );
+      }
+    } else if (token.startsWith('**') || token.startsWith('__')) {
+      out.push(h('strong', { key: makeKey('strong') }, renderReadmeInline(token.slice(2, -2), makeKey, base)));
+    } else if (token.startsWith('~~')) {
+      out.push(h('del', { key: makeKey('del') }, renderReadmeInline(token.slice(2, -2), makeKey, base)));
+    } else if (token.startsWith('*') || token.startsWith('_')) {
+      out.push(h('em', { key: makeKey('em') }, renderReadmeInline(token.slice(1, -1), makeKey, base)));
+    } else if (token.startsWith('<http')) {
+      const href = readmeSafeUrl(token.slice(1, -1), base);
+      out.push(
+        href
+          ? h('a', { key: makeKey('a'), className: 'dsh-mcp-md-a', href, target: '_blank', rel: 'noreferrer noopener' }, token.slice(1, -1))
+          : token,
+      );
+    } else if (/^<img/i.test(token)) {
+      const srcMatch = /\bsrc\s*=\s*["']([^"']+)["']/i.exec(token);
+      const altMatch = /\balt\s*=\s*["']([^"']*)["']/i.exec(token);
+      const node = srcMatch ? readmeImageNode(srcMatch[1], altMatch ? altMatch[1] : '', makeKey, base, { inline: true }) : null;
+      if (node) out.push(node);
+    } else if (/^<br/i.test(token)) {
+      out.push(h('br', { key: makeKey('br') }));
+    }
+    cursor = match.index + token.length;
+    if (!token) break;
+    match = re.exec(source);
+  }
+  pushText(source.slice(cursor));
+  return out;
+}
+
+/** 从一段裸 HTML 里薅出 <img src>：README 的横幅几乎都藏在这种块里。 */
+function readmeHtmlImages(text) {
+  const out = [];
+  const re = /<img\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+  let match = re.exec(String(text || ''));
+  while (match) {
+    out.push(match[1]);
+    match = re.exec(String(text || ''));
+  }
+  return out;
+}
+
+/** 裸 HTML 块 → 文本（去标签、留文字），用于既没图也没链接的说明性 HTML。 */
+function readmeHtmlText(text) {
+  return String(text || '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/(p|div|tr|li|h[1-6])>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/[ \t]+\n/g, '\n')
+    .trim();
+}
+
+/**
+ * markdown → React 节点数组。`base` 用来还原相对图片/链接。
+ * 解析器只认行首块级语法，行内交给 renderReadmeInline；认不出的行按段落处理，
+ * 所以畸形 README 最差也只是排版朴素，不会崩、不会吞内容。
+ */
+function renderReadmeBlocks(markdown, base) {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const blocks = [];
+  let seq = 0;
+  const makeKey = (tag) => `md-${tag}-${seq++}`;
+  let index = 0;
+  let paragraph = [];
+
+  const flushParagraph = () => {
+    if (!paragraph.length) return;
+    const text = paragraph.join(' ').replace(/\s+/g, ' ').trim();
+    paragraph = [];
+    if (text) blocks.push(h('p', { key: makeKey('p'), className: 'dsh-mcp-md-p' }, renderReadmeInline(text, makeKey, base)));
+  };
+
+  while (index < lines.length) {
+    const line = lines[index];
+
+    // 围栏代码块：整段原样保留，不再做行内解析。
+    const fence = /^\s*(```+|~~~+)\s*([\w+#.-]*)\s*$/.exec(line);
+    if (fence) {
+      flushParagraph();
+      const marker = fence[1][0];
+      const body = [];
+      index += 1;
+      while (index < lines.length && !new RegExp('^\\s*' + marker + '{3,}\\s*$').test(lines[index])) {
+        body.push(lines[index]);
+        index += 1;
+      }
+      index += 1;
+      blocks.push(h('pre', { key: makeKey('pre'), className: 'dsh-mcp-md-pre' }, h('code', null, body.join('\n'))));
+      continue;
+    }
+
+    if (!line.trim()) {
+      flushParagraph();
+      index += 1;
+      continue;
+    }
+
+    // 分隔线（--- / *** / ___，允许 3 个以上）
+    if (/^\s*([-*_])\s*(?:\1\s*){2,}$/.test(line)) {
+      flushParagraph();
+      blocks.push(h('hr', { key: makeKey('hr'), className: 'dsh-mcp-md-hr' }));
+      index += 1;
+      continue;
+    }
+
+    // 标题：h1~h6 统一渲染成带 aria-level 的 div，别和弹窗自己的 h3 打架。
+    const heading = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+    if (heading) {
+      flushParagraph();
+      const level = heading[1].length;
+      blocks.push(
+        h(
+          'div',
+          {
+            key: makeKey('h'),
+            className: 'dsh-mcp-md-h',
+            role: 'heading',
+            'aria-level': String(Math.min(6, level + 2)),
+            style: { fontSize: level <= 1 ? '18px' : level === 2 ? '16px' : level === 3 ? '15px' : '14px' },
+          },
+          renderReadmeInline(heading[2], makeKey, base),
+        ),
+      );
+      index += 1;
+      continue;
+    }
+
+    // 表格：当前行含 | 且下一行是 |---|---| 分隔行
+    if (line.includes('|') && index + 1 < lines.length && /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/.test(lines[index + 1]) && lines[index + 1].includes('-')) {
+      flushParagraph();
+      const splitRow = (row) =>
+        String(row)
+          .replace(/^\s*\|/, '')
+          .replace(/\|\s*$/, '')
+          .split('|')
+          .map((cell) => cell.trim());
+      const header = splitRow(line);
+      index += 2;
+      const rows = [];
+      while (index < lines.length && lines[index].includes('|') && lines[index].trim()) {
+        rows.push(splitRow(lines[index]));
+        index += 1;
+      }
+      blocks.push(
+        h(
+          'table',
+          { key: makeKey('table'), className: 'dsh-mcp-md-table' },
+          h('thead', null, h('tr', null, header.map((cell, cellIndex) => h('th', { key: cellIndex }, renderReadmeInline(cell, makeKey, base))))),
+          h(
+            'tbody',
+            null,
+            rows.map((row, rowIndex) =>
+              h('tr', { key: rowIndex }, header.map((_, cellIndex) => h('td', { key: cellIndex }, renderReadmeInline(row[cellIndex] || '', makeKey, base)))),
+            ),
+          ),
+        ),
+      );
+      continue;
+    }
+
+    // 引用：连续 > 行合成一段
+    if (/^\s*>/.test(line)) {
+      flushParagraph();
+      const quote = [];
+      while (index < lines.length && /^\s*>/.test(lines[index])) {
+        quote.push(lines[index].replace(/^\s*>\s?/, ''));
+        index += 1;
+      }
+      blocks.push(h('blockquote', { key: makeKey('quote'), className: 'dsh-mcp-md-quote' }, h('p', { className: 'dsh-mcp-md-p' }, renderReadmeInline(quote.join(' '), makeKey, base))));
+      continue;
+    }
+
+    // 裸 HTML 块：先薅图片，再留文字。
+    if (/^\s*</.test(line) && !/^\s*<https?:/i.test(line)) {
+      flushParagraph();
+      const chunk = [];
+      while (index < lines.length && /^\s*</.test(lines[index]) && !/^\s*<https?:/i.test(lines[index])) {
+        chunk.push(lines[index]);
+        index += 1;
+      }
+      const rawHtml = chunk.join('\n');
+      const srcs = readmeHtmlImages(rawHtml);
+      const nodes = [];
+      srcs.forEach((src) => {
+        const node = readmeImageNode(src, '', makeKey, base, { inline: false });
+        if (node) nodes.push(node);
+      });
+      const leftover = readmeHtmlText(rawHtml);
+      if (leftover) {
+        nodes.push(h('p', { key: makeKey('htmltext'), className: 'dsh-mcp-md-p' }, renderReadmeInline(leftover.replace(/\n+/g, ' '), makeKey, base)));
+      }
+      if (nodes.length) blocks.push(h('div', { key: makeKey('html'), className: 'dsh-mcp-md-htmlblock' }, nodes));
+      continue;
+    }
+
+    // 列表项：按缩进算层级，深度用 padding 表达（README 的嵌套一般不超过 3 层）
+    const listItem = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/.exec(line);
+    if (listItem) {
+      flushParagraph();
+      const ordered = /\d/.test(listItem[2]);
+      const items = [];
+      while (index < lines.length) {
+        const current = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/.exec(lines[index]);
+        if (!current) break;
+        const depth = Math.min(3, Math.floor(current[1].replace(/\t/g, '  ').length / 2));
+        items.push({ depth, text: current[3] });
+        index += 1;
+      }
+      blocks.push(
+        h(
+          ordered ? 'ol' : 'ul',
+          { key: makeKey('list'), className: ordered ? 'dsh-mcp-md-ol' : 'dsh-mcp-md-ul' },
+          items.map((item, itemIndex) =>
+            h('li', { key: itemIndex, className: 'dsh-mcp-md-li', style: item.depth ? { marginInlineStart: item.depth * 16 + 'px' } : undefined }, renderReadmeInline(item.text, makeKey, base)),
+          ),
+        ),
+      );
+      continue;
+    }
+
+    paragraph.push(line.trim());
+    index += 1;
+  }
+  flushParagraph();
+  return blocks;
+}
+
 // ── 样式表 MCP_CSS：主题令牌别名 + 全部面板规则（一次性注入 <style>）──────────────
 /* 主题令牌别名层。DSH 的 ui-theme 拥有全部颜色、几何与字体：插件只消费语义令牌，
    不写死色值、不写局部圆角数值（docs/web-styling.md：「Use --dsw-alias-* semantic
@@ -5325,6 +5758,10 @@ const ExpertInstalledBoard = ({ call }) => {
   const [presets, setPresets] = useState([]);
   const [skills, setSkills] = useState([]);
   const [detail, setDetail] = useState(null);
+  // 正在拉详情的那张卡（plugin 名）：加载期间只把这一个卡片的「详情」按钮标成「读取中…」，
+  // 弹层等数据到手才挂载——中途先 setDetail 一个只有标题的矮盒子会「先闪小窗、再跳大窗」
+  // （.dsh-mcp-modal 高度随内容自适应）。与市场页 ExpertMarket 同一套做法。
+  const [openingPlugin, setOpeningPlugin] = useState('');
   // §4.1 在场：expertActive 是「谁真的挂在会话上」的唯一真源。没有它，「已召唤」
   // （预设已落盘，新会话才接管）和「在场」（人设真的在这轮对话里生效）就是同一个绿 tag，
   // 而这恰恰是这一页最该说清楚的区别。
@@ -5412,14 +5849,19 @@ const ExpertInstalledBoard = ({ call }) => {
     }
   };
   const openDetail = async (plugin) => {
-    setDetail({ plugin, loading: true });
+    // 弹层只在详情数据到手后挂载一次（理由同市场页：中途挂矮盒子会闪一下再变大）。
+    if (openingPlugin) return;   // 串行化：一条没回来就别再拉第二条。
+    setOpeningPlugin(plugin);
     setNote('');
     try {
       const res = await call('wbExpertDetail', { plugin });
       if (!res?.ok) throw new Error(res?.error || t('读取详情失败'));
-      setDetail({ ...res, loading: false });
+      setDetail({ ...res });
     } catch (e) {
-      setDetail({ plugin, loading: false, detailError: String(e?.message || e) });
+      // 失败也开弹层：里面有 detailError 红字，比「点了没反应」好排查。
+      setDetail({ plugin, detailError: String(e?.message || e) });
+    } finally {
+      setOpeningPlugin('');
     }
   };
 
@@ -5518,7 +5960,7 @@ const ExpertInstalledBoard = ({ call }) => {
                     }, skill)))
                 : h('div', { className: 'dsh-mcp-card-summary' }, t('无捆绑技能（预设本体在 profile 补丁）')),
               h('div', { className: 'dsh-mcp-wb-card-actions' },
-                h('button', { type: 'button', className: 'dsh-mcp-btn', onClick: () => openDetail(row.plugin) }, t('详情')),
+                h('button', { type: 'button', className: 'dsh-mcp-btn', disabled: openingPlugin === row.plugin, 'aria-busy': openingPlugin === row.plugin || undefined, onClick: () => openDetail(row.plugin) }, openingPlugin === row.plugin ? t('读取中…') : t('详情')),
                 confirming
                   // 内联确认：不弹窗、不移位——原地换成「确认/取消」，误触成本从 0 提到 1 次点击。
                   ? h(InlineConfirm, {
@@ -5565,9 +6007,7 @@ const ExpertInstalledBoard = ({ call }) => {
       ? h('div', { className: 'dsh-mcp-overlay', onClick: (e) => !busy && e.target === e.currentTarget && setDetail(null) },
           h('div', { ref: summonedRef, className: 'dsh-mcp-modal dsh-mcp-wb-modal', role: 'dialog', 'aria-modal': true, 'aria-label': t('已召唤专家详情'), tabIndex: -1, onKeyDown: (e) => { if (e.key === 'Escape' && !busy) { e.stopPropagation(); setDetail(null); } } },
             h('h3', null, detail.name ? t('{0}（{1}）', [detail.name, detail.profession || '']) : detail.plugin),
-            detail.loading
-              ? h('p', { className: 'dsh-mcp-wb-modal-note' }, t('正在拉取详情…'))
-              : h('div', null,
+            h('div', null,
                   detail.detailError ? h('p', { className: 'dsh-mcp-wb-error' }, detail.detailError) : null,
                   detail.description ? h('p', { className: 'dsh-mcp-wb-modal-desc' }, detail.description) : null,
                   Array.isArray(detail.skills) && detail.skills.length
@@ -5590,7 +6030,7 @@ const ExpertInstalledBoard = ({ call }) => {
                 ),
             h('div', { className: 'dsh-mcp-modal-actions' },
               h(Btn, { onClick: () => setDetail(null), disabled: busy, children: t('关闭') }),
-              h(Btn, { danger: true, icon: 'trash', disabled: busy || detail.loading, onClick: () => dismiss(detail.plugin, detail.name), children: t('送还') }),
+              h(Btn, { danger: true, icon: 'trash', disabled: busy, onClick: () => dismiss(detail.plugin, detail.name), children: t('送还') }),
             ),
           ),
         )
@@ -5620,6 +6060,19 @@ const ExpertMarket = ({ call }) => {
   // OPT-21：市场专家详情弹层此前没有 ref。
   const expertDetailRef = useRef(null);
   useFocusTrap(expertDetailRef, !!detail);
+  // OPT-16/26 · 3.2/3.3：详情弹层里「人设全文展开」「quickPrompts 全部展开」两个局部开关。
+  // 必须声明在组件顶层、**每次渲染都调用**：这两个 hook 原先写在
+  // `detail ? (() => { … })() : null` 这个条件 IIFE 里，首帧 detail 为 null 时一次都不调用，
+  // 点卡片「详情」后同一组件突然多调用两个 hook —— React #310
+  // 「Rendered more hooks than during the previous render」直接把整块面板打进错误边界
+  // （用户看到的就是市场专家页点详情即白屏报 #310）。开关只在打开详情时重置，
+  // 保证换一个专家进来是折叠态，而不是沿用上一条的展开状态。
+  const [personaExpanded, setPersonaExpanded] = useState(false);
+  const [showAllPrompts, setShowAllPrompts] = useState(false);
+  // 正在拉详情的那张卡片（plugin 名）：加载期间只把这一个卡片的「详情」按钮标成「读取中…」，
+  // 详情弹层等数据到手才挂载。**不要**在加载中途先 setDetail 一个只有标题的矮盒子——.dsh-mcp-modal
+  // 高度随内容自适应，那会让用户看到「先闪一个小窗、再跳成大窗」。
+  const [openingPlugin, setOpeningPlugin] = useState('');
 
   const loadInstalled = useCallback(async () => {
     const res = await call('wbExpertInstalled');
@@ -5646,14 +6099,24 @@ const ExpertMarket = ({ call }) => {
   useEffect(() => { load(); loadInstalled(); }, [load, loadInstalled]);
 
   const openDetail = async (expert) => {
-    setDetail({ ...expert, loading: true });
+    // 弹层**只在详情数据到手后挂载一次**。此前这里是「先 setDetail({…, loading:true}) 挂个矮盒子，
+    // 拿到人设与技能清单后再 setDetail 一次」：因为 .dsh-mcp-modal 高度随内容自适应，用户看到的就是
+    // 先闪一个小窗、再跳成大窗。现在加载期间只在卡片按钮上显示「读取中…」，弹层一次到位。
+    if (openingPlugin) return;   // 串行化：一条还没回来就别再拉第二条，避免后到的覆盖先到的。
+    setOpeningPlugin(expert.plugin);
     setNote('');
+    // 展开态跟着「这一次打开」重置，别让上一条专家留下的展开状态带进来。
+    setPersonaExpanded(false);
+    setShowAllPrompts(false);
     try {
       const res = await call('wbExpertDetail', { plugin: expert.plugin });
       if (!res?.ok) throw new Error(res?.error || t('读取详情失败'));
-      setDetail({ ...expert, ...res, loading: false });
+      setDetail({ ...expert, ...res });
     } catch (e) {
-      setDetail({ ...expert, loading: false, detailError: String(e?.message || e) });
+      // 失败也要把弹层开出来：里面有 detailError 的红字，比「点了没反应」好排查。
+      setDetail({ ...expert, detailError: String(e?.message || e) });
+    } finally {
+      setOpeningPlugin('');
     }
   };
   const summon = async (expert) => {
@@ -5780,7 +6243,7 @@ const ExpertMarket = ({ call }) => {
                 installedSkillPlugins.has(item.plugin) ? h(Badge, null, t('含技能')) : null,
               ),
               h('div', { className: 'dsh-mcp-wb-card-actions' },
-                h('button', { type: 'button', className: 'dsh-mcp-btn', onClick: () => openDetail(item) }, t('详情')),
+                h('button', { type: 'button', className: 'dsh-mcp-btn', disabled: openingPlugin === item.plugin, 'aria-busy': openingPlugin === item.plugin || undefined, onClick: () => openDetail(item) }, openingPlugin === item.plugin ? t('读取中…') : t('详情')),
                 // 团队型已走桥接：主理人接管会话，成员人设落盘后由主理人用 subagent 调度。
                 // stale 团队行：「更新预设」与「送还」**并列**（后端 upsert 原地重写该行，
                 // 用户也可能只想删掉旧行）。1.9.4 这里曾写成三元，导致更新按钮永不渲染。
@@ -5805,9 +6268,8 @@ const ExpertMarket = ({ call }) => {
     detail
       ? (() => {
         // 弹层里该给哪些按钮：与卡片按钮同源（expertCardActions），只是换到详情对象上算。
-        // OPT-16/26 · 3.2/3.3：persona 展开态与 quickPrompts 展开态（专家详情弹层局部）。
-        const [personaExpanded, setPersonaExpanded] = useState(false);
-        const [showAllPrompts, setShowAllPrompts] = useState(false);
+        // 注意：这个 IIFE 里**不允许再出现任何 hook**（personaExpanded / showAllPrompts 已上提到
+        // 组件顶层）——它本身就在 `detail ?` 条件分支里，一旦在此调用 hook 就是 React #310。
         const detailActions = expertCardActions({
           summoned: presets.has(detail.plugin),
           expertType: detail.expertType,
@@ -5817,9 +6279,7 @@ const ExpertMarket = ({ call }) => {
           h('div', { ref: expertDetailRef, className: 'dsh-mcp-modal dsh-mcp-wb-modal', role: 'dialog', 'aria-modal': true, 'aria-label': t('专家详情'), tabIndex: -1, onKeyDown: (e) => { if (e.key === 'Escape' && !busy) { e.stopPropagation(); setDetail(null); } } },
             h('h3', null, t('{0}（{1}）', [detail.name, detail.profession])),
             h('div', { className: 'dsh-mcp-card-vendor' }, detail.categoryName || detail.categoryId || ''),
-            detail.loading
-              ? h('p', { className: 'dsh-mcp-wb-modal-note' }, t('正在拉取人设与技能清单…'))
-              : h('div', null,
+            h('div', null,
                   detail.detailError ? h('p', { className: 'dsh-mcp-wb-error' }, detail.detailError) : null,
                   detail.description ? h('p', { className: 'dsh-mcp-wb-modal-desc' }, detail.description) : null,
                   detail.quickPrompts && detail.quickPrompts.length
@@ -5891,13 +6351,13 @@ const ExpertMarket = ({ call }) => {
             h('div', { className: 'dsh-mcp-modal-actions' },
               h(Btn, { onClick: () => setDetail(null), disabled: busy, children: t('关闭') }),
               detailActions.update
-                ? h(Btn, { primary: true, icon: 'refresh', disabled: busy || detail.loading, onClick: () => summon(detail), children: busy ? t('更新中…') : t('更新预设') })
+                ? h(Btn, { primary: true, icon: 'refresh', disabled: busy, onClick: () => summon(detail), children: busy ? t('更新中…') : t('更新预设') })
                 : null,
               detailActions.dismiss
-                ? h(Btn, { danger: true, icon: 'trash', disabled: busy || detail.loading, onClick: () => dismiss(detail), children: t('送还') })
+                ? h(Btn, { danger: true, icon: 'trash', disabled: busy, onClick: () => dismiss(detail), children: t('送还') })
                 : null,
               detailActions.summon
-                ? h(Btn, { primary: true, icon: 'plus', disabled: busy || detail.loading, onClick: () => summon(detail), children: busy ? t('召唤中…') : detail.expertType === 'team' ? t('召唤专家团') : t('召唤') })
+                ? h(Btn, { primary: true, icon: 'plus', disabled: busy, onClick: () => summon(detail), children: busy ? t('召唤中…') : detail.expertType === 'team' ? t('召唤专家团') : t('召唤') })
                 : null,
             ),
           ),
@@ -6980,15 +7440,59 @@ const WorkBuddyMarket = ({ call, pluginManager }) => {
       setAwesomeLoading(false);
     }
   }, [call]);
-  const checkAwesomeUpdate = useCallback(async () => {
+  // 探测节流 6 小时；force=true（用户点「重新加载」）跳过节流立即重探。
+  // 注意：时间戳只在真的发起探测时写，否则每次挂载都会把闸门往后推、探测永不再跑。
+  const checkAwesomeUpdate = useCallback(async (force = false) => {
+    if (!force && Date.now() - readAwesomeProbeAt() < AWESOME_PROBE_INTERVAL_MS) return;
+    writeAwesomeProbeAt(Date.now());
     try {
       const res = await call('wbAwesomeUpdateCheck');
-      setAwesomeUpdateHint(res || null);
+      // probe-failed 是环境性的瞬时失败（源不可达 / 超时 / HEAD 被拒），一律静默：
+      // 真正「更新源不可达」由 awesomeStale 那条中性提示负责，不重复喊狼来了。
+      setAwesomeUpdateHint(res && res.reason !== 'probe-failed' ? res : null);
     } catch {
       setAwesomeUpdateHint(null);
     }
   }, [call]);
   const awesomeUpdateChecked = useRef(false);
+  // ── README 预览弹层 ──────────────────────────────────────────────────────
+  // 点卡片时才按需拉一次（服务端 npm registry / GitHub raw + 7 天落盘缓存）；
+  // 目录本身仍是 13 字段瘦身版，不因预览而变重。
+  const [readmeView, setReadmeView] = useState(null);
+  const readmeSeq = useRef(0);
+  const readmeNodeRef = useRef(null);
+  useFocusTrap(readmeNodeRef, !!readmeView);
+  const closeReadme = () => {
+    readmeSeq.current += 1; // 作废在途请求，避免关掉之后又被写回来
+    setReadmeView(null);
+  };
+  const loadAwesomeReadme = useCallback(async (item, refresh = false) => {
+    if (!item) return;
+    // 弹层的排版样式随首次打开注入。放在事件回调里而不是组件顶层，是为了不引入
+    // 任何新的 Hook —— 这也正是 no-conditional-hooks 测试要防的那类崩溃。
+    ensureReadmeStyle();
+    const seq = ++readmeSeq.current;
+    const npm = typeof item.npm === 'string' ? item.npm : (item.npm && item.npm.name) || '';
+    setReadmeView({ item, loading: true, ok: false, markdown: '', base: '', error: '', source: '', reason: '', truncated: false });
+    let res = null;
+    try {
+      res = await call('wbAwesomeReadme', { name: item.name, npm, repo: item.repo || '', refresh: refresh === true });
+    } catch (error) {
+      res = { ok: false, error: error && error.message ? error.message : String(error) };
+    }
+    if (seq !== readmeSeq.current) return;
+    if (!res || res.ok !== true) {
+      const raw = (res && res.error) || '';
+      // 宿主进程若仍是旧版（新 Remote 未注册），这里会收到 404 transport failure：
+      // 换成一句可操作的话，别让用户以为功能坏了。
+      const message = /404|not\s*found/i.test(raw)
+        ? t('预览服务尚未加载，请完全退出 DSH 后重新打开再试')
+        : (raw || t('读取 README 失败：未知错误'));
+      setReadmeView({ item, loading: false, ok: false, markdown: '', base: '', error: message, source: '', reason: (res && res.reason) || '', truncated: false });
+      return;
+    }
+    setReadmeView({ item, loading: false, ok: true, markdown: res.markdown || '', base: res.base || '', error: '', source: res.source || '', reason: res.reason || '', truncated: res.truncated === true });
+  }, [call]);
   // 自动加载改成「每次挂载只发一次」：旧条件是 `awesomeLoading || awesomePlugins.length` 就跳过，
   // 一旦首屏已经有快照，真实目录就永远不会再拉——快照便成了死数据，必须去掉那个门槛。
   const awesomeAutoLoaded = useRef(false);
@@ -7590,14 +8094,14 @@ const WorkBuddyMarket = ({ call, pluginManager }) => {
         )
       : null,
     // ── T06/Awesome：DSH 社区（awesome-dsh-plugins）目录 ──
-    tab === 'plugin' && pluginSource === 'awesome' && awesomeStale ? h('div', { className: 'dsh-mcp-wb-note', role: 'status' }, t('目录缓存已过期（更新源暂时不可达，显示的是本地缓存）。'), h('button', { type: 'button', className: 'dsh-mcp-btn', disabled: awesomeLoading, onClick: () => loadAwesomeCatalog(true) }, t('重新加载'))) : null,
-    tab === 'plugin' && pluginSource === 'awesome' && awesomeUpdateHint && (awesomeUpdateHint.reason === 'update-available' || awesomeUpdateHint.reason === 'no-cache') ? h('div', { className: 'dsh-mcp-wb-note', role: 'status' }, awesomeUpdateHint.reason === 'update-available' ? t('DSH 社区目录有新版本（本地缓存 {0}）。点「重新加载」可拉取最新目录。', [awesomeUpdateHint.localEtag || t('未知错误')]) : t('本地还没有 DSH 社区目录缓存，点「重新加载」可首次拉取目录。'), h('button', { type: 'button', className: 'dsh-mcp-btn', disabled: awesomeLoading, onClick: async () => { setAwesomeUpdateHint(null); await loadAwesomeCatalog(true); } }, t('重新加载')), h('button', { type: 'button', className: 'dsh-mcp-btn', onClick: () => setAwesomeUpdateHint(null) }, t('知道了'))) : null,
-    tab === 'plugin' && pluginSource === 'awesome' && awesomeUpdateHint && awesomeUpdateHint.reason === 'probe-failed' ? h('div', { className: 'dsh-mcp-wb-error', role: 'alert' }, t('DSH 社区目录更新探测失败（不影响已安装插件）。'), h('button', { type: 'button', className: 'dsh-mcp-btn', onClick: () => { awesomeUpdateChecked.current = false; checkAwesomeUpdate(); } }, t('重新探测'))) : null,
+    tab === 'plugin' && pluginSource === 'awesome' && awesomeStale ? h('div', { className: 'dsh-mcp-wb-note', role: 'status' }, t('目录缓存已过期（更新源暂时不可达，显示的是本地缓存）。'), h('button', { type: 'button', className: 'dsh-mcp-btn', disabled: awesomeLoading, onClick: () => { writeAwesomeProbeAt(0); awesomeUpdateChecked.current = false; loadAwesomeCatalog(true); } }, t('重新加载'))) : null,
+    tab === 'plugin' && pluginSource === 'awesome' && awesomeUpdateHint && (awesomeUpdateHint.reason === 'update-available' || awesomeUpdateHint.reason === 'no-cache') ? h('div', { className: 'dsh-mcp-wb-note', role: 'status' }, awesomeUpdateHint.reason === 'update-available' ? t('DSH 社区目录有新版本（本地缓存 {0}）。点「重新加载」可拉取最新目录。', [awesomeUpdateHint.localEtag || t('未知错误')]) : t('本地还没有 DSH 社区目录缓存，点「重新加载」可首次拉取目录。'), h('button', { type: 'button', className: 'dsh-mcp-btn', disabled: awesomeLoading, onClick: async () => { setAwesomeUpdateHint(null); writeAwesomeProbeAt(0); awesomeUpdateChecked.current = false; await loadAwesomeCatalog(true); } }, t('重新加载')), h('button', { type: 'button', className: 'dsh-mcp-btn', onClick: () => setAwesomeUpdateHint(null) }, t('知道了'))) : null,
+    
     tab === 'plugin' && pluginSource === 'awesome' && awesomeError ? h('div', { className: 'dsh-mcp-wb-error', role: 'alert' }, awesomeError, h('button', { type: 'button', className: 'dsh-mcp-btn', disabled: awesomeLoading, onClick: () => loadAwesomeCatalog() }, t('重试'))) : null,
     tab === 'plugin' && pluginSource === 'awesome' && awesomeLoading && !awesomePlugins.length ? h('div', { className: 'dsh-mcp-wb-empty' }, t('正在加载 DSH 社区目录…')) : null,
     tab === 'plugin' && pluginSource === 'awesome' && !awesomeError && !awesomeLoading && !awesomePlugins.length ? h(EmptyState, { icon: 'store', title: t('DSH 社区目录暂时是空的'), hint: t('目录来自 awesome-dsh-plugins 社区清单（jsdelivr CDN 分发），拉取失败可重试。'), actions: [{ label: t('重新读取目录'), icon: 'refresh', onClick: () => loadAwesomeCatalog() }] }) : null,
     tab === 'plugin' && pluginSource === 'awesome' && awesomePlugins.length && !visibleAwesome.length ? h(EmptyState, { tight: true, title: t('没有匹配的社区插件'), hint: t('换个关键词，或清空分类与标签筛选。'), actions: [{ label: t('清空筛选'), icon: 'x', onClick: () => { setAwesomeQuery(''); setAwesomeCategory('all'); setAwesomeTags([]); } }] }) : null,
-    tab === 'plugin' && pluginSource === 'awesome' && visibleAwesome.length ? h('div', { className: 'dsh-mcp-wb-grid' }, visibleAwesome.map((item) => h('div', { key: item.name, className: 'dsh-mcp-card wb' },
+    tab === 'plugin' && pluginSource === 'awesome' && visibleAwesome.length ? h('div', { className: 'dsh-mcp-wb-grid' }, visibleAwesome.map((item) => h('div', { key: item.name, className: 'dsh-mcp-card wb dsh-mcp-card-clickable', role: 'button', tabIndex: 0, title: t('查看 README 介绍与插图'), onClick: () => loadAwesomeReadme(item), onKeyDown: (e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); loadAwesomeReadme(item); } } },
       h('div', { className: 'dsh-mcp-card-top' },
         h('div', null,
           h('div', { className: 'dsh-mcp-card-name' }, item.name),
@@ -7611,9 +8115,29 @@ const WorkBuddyMarket = ({ call, pluginManager }) => {
         item.stars ? h(Badge, null, '★ ' + item.stars) : null,
         item.category && item.category !== 'plugin' ? h(Badge, null, item.category) : null,
         (item.tags || []).map((tag) => h('span', { key: tag, className: 'dsh-mcp-tag-chip on' }, tag))),
-      h('div', { className: 'dsh-mcp-wb-card-actions' },
+      h('div', { className: 'dsh-mcp-wb-card-actions', onClick: (e) => e.stopPropagation(), onKeyDown: (e) => e.stopPropagation() },
         item.npm ? (String(item.npm).startsWith('@deepseek-ai/') ? h('span', { className: 'dsh-mcp-wb-blocked', title: t('DSH 宿主官方组件随宿主本体分发，无法也不需要从市场安装') }, t('宿主组件')) : h('button', { type: 'button', className: 'dsh-mcp-btn primary', disabled: busy || isInstallRunning(item.name), onClick: () => installPlugin(item) }, t('安装'))) : h('span', { className: 'dsh-mcp-wb-blocked', title: t('该条目未提供 npm 包名，暂不支持安装') }, t('暂不支持安装')))))) : null,
     tab === 'plugin' && pluginSource === 'awesome' && awesomePageCount > 1 ? h(Pager, { page: safeAwesomePage, pageCount: awesomePageCount, total: sortedAwesome.length, onPage: setAwesomePage }) : null,
+    // ── DSH 社区插件 README 预览（点卡片打开；插图来自 README 自身的相对/绝对地址）──
+    readmeView
+      ? h('div', { className: 'dsh-mcp-overlay', onClick: (e) => { if (e.target === e.currentTarget) closeReadme(); } },
+          h('div', { ref: readmeNodeRef, className: 'dsh-mcp-modal dsh-mcp-wb-modal dsh-mcp-readme-modal', role: 'dialog', 'aria-modal': true, 'aria-label': t('{0} README 预览', [readmeView.item && readmeView.item.name ? readmeView.item.name : '']), tabIndex: -1, onKeyDown: (e) => { if (e.key === 'Escape') { e.stopPropagation(); closeReadme(); } } },
+            h('h3', null, readmeView.item && readmeView.item.name ? readmeView.item.name : ''),
+            h('div', { className: 'dsh-mcp-readme-meta' },
+              readmeView.item && readmeView.item.repo ? h(Badge, { title: readmeView.item.repo }, String(readmeView.item.repo).replace(/^https?:\/\/github\.com\//i, '')) : null,
+              readmeView.item && readmeView.item.npm ? h(Badge, { title: readmeView.item.npm }, 'npm') : null,
+              readmeView.source ? h(Badge, null, readmeView.source === 'npm' ? 'npm registry' : 'GitHub') : null),
+            readmeView.loading
+              ? h('p', { className: 'dsh-mcp-wb-modal-note', role: 'status' }, t('正在读取 README…'))
+              : readmeView.ok
+                ? h('div', { className: 'dsh-mcp-readme-body' }, renderReadmeBlocks(readmeView.markdown, readmeView.base))
+                : h('p', { className: 'dsh-mcp-wb-error', role: 'alert' }, readmeView.error),
+            readmeView.ok && readmeView.truncated ? h('p', { className: 'dsh-mcp-wb-modal-note' }, t('README 过长，已截断显示。')) : null,
+            h('div', { className: 'dsh-mcp-modal-actions' },
+              h(Btn, { onClick: closeReadme, children: t('关闭') }),
+              readmeView.item && readmeView.item.npm ? h(Btn, { primary: true, icon: 'plus', disabled: busy || isInstallRunning(readmeView.item.name), onClick: () => { const target = readmeView.item; closeReadme(); installPlugin(target); } }, t('安装')) : null,
+              h(Btn, { onClick: () => loadAwesomeReadme(readmeView.item, true), disabled: readmeView.loading, children: t('重新读取') }))))
+      : null,
     // ── T04/R7：令牌弹窗（连接器 mcp.json 里的 ${...} 占位符）──
     // 设计约束：只收集用户输入并原样透传；槽位来自目录条目的 tokenSlots，
     // 同一占位符可能出现多次（同 server 的 env 与 header），按 placeholder 去重。
@@ -8928,6 +9452,7 @@ const MCP_CONTRIBUTION = {
     // T06/Awesome：DSH 社区插件市场（awesome-dsh-plugins）。与宿主 method、typert.js 三处必须同步。
     { id: 'dsh-armory#mcpManager/wbAwesomeCatalog', service: 'mcpManager', namespace: 'mcpManager', method: 'wbAwesomeCatalog', invocation: { kind: 'direct' }, parameters: [mcpParam('payload', 'ImportPayload')], result: mcpCodec('AwesomeCatalogResult') },
     { id: 'dsh-armory#mcpManager/wbAwesomeDetail', service: 'mcpManager', namespace: 'mcpManager', method: 'wbAwesomeDetail', invocation: { kind: 'direct' }, parameters: [mcpParam('payload', 'ImportPayload')], result: mcpCodec('AwesomeDetailResult') },
+  { id: 'dsh-armory#mcpManager/wbAwesomeReadme', service: 'mcpManager', namespace: 'mcpManager', method: 'wbAwesomeReadme', invocation: { kind: 'direct' }, parameters: [mcpParam('payload', 'ImportPayload')], result: mcpCodec('AwesomeReadmeResult') },
     { id: 'dsh-armory#mcpManager/wbAwesomeUpdateCheck', service: 'mcpManager', namespace: 'mcpManager', method: 'wbAwesomeUpdateCheck', invocation: { kind: 'direct' }, parameters: [], result: mcpCodec('WbUpdateHintResult') },
     { id: 'dsh-armory#mcpManager/wbPluginDetail', service: 'mcpManager', namespace: 'mcpManager', method: 'wbPluginDetail', invocation: { kind: 'direct' }, parameters: [mcpParam('payload', 'ImportPayload')], result: mcpCodec('WbPluginDetailResult') },
     // ── WorkBuddy 专家直连：召唤预设 + 捆绑技能（同一命名空间同一信封）──