dsh-armory 1.9.4 → 2.0.0

package/lib/wb-market.js

@@ -23,8 +23,21 @@ import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/p
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { ZipReader } from "./wb-zip.js";
+// T02/R1：auth_injection_rules 只解析、只展示（X9 边界）——DSH 不做任何代注入，
+// 这里只借用 T01 纯函数库的解析与按连接器命中能力。
+import { parseInjectionRules, rulesFor, scanTokenSlots } from "./wb-auth-rules.js";
+// T03/R4：连接器源不再硬编码单 URL——从多市场注册表取 sourceFor("connectors")，
+// 读不到/损坏时回落内置默认（wb-registry.builtinMarketplaces 保证）。
+import { sourceFor } from "./wb-registry.js";
 
 const CONNECTOR_ZIP_URL = "https://static.workbuddy.cn/connectors-config-v2/connectors-config.zip";
+
+/** R4：连接器市场源 URL。注册表第一条 connectors 源优先，缺失/读失败回落内置默认。 */
+export async function connectorSourceUrl(options = {}) {
+  const row = await sourceFor("connectors", options);
+  const url = row && row.source && typeof row.source.url === "string" ? row.source.url : "";
+  return url || CONNECTOR_ZIP_URL;
+}
 const SKILLHUB_ORIGIN = "https://api.skillhub.cn";
 const USER_AGENT = "@2026heshao/dsh-armory (+https://github.com/2026heshao/dsh-armory)";
 // 单文件/单响应上限：connectors.json ≈ 550KB、SKILL.md 最大几十 KB，8MB 已是十倍冗余。
@@ -67,8 +80,11 @@ async function loadConnectorZip() {
   if (cachedZip) return cachedZip;
   await mkdir(cacheDir(), { recursive: true });
   const meta = (await readJson(metaPath())) || {};
+  // R4：注册表取源（缺失回落内置默认），ZIP 路径/缓存键不变——
+  // 注册表只是改了「从哪下」，没有改「下到哪」。
+  const sourceUrl = await connectorSourceUrl();
   const download = async (etag) => {
-    const response = await fetch(CONNECTOR_ZIP_URL, {
+    const response = await fetch(sourceUrl, {
       headers: { "user-agent": USER_AGENT, ...(etag ? { "if-none-match": etag } : {}) },
       signal: AbortSignal.timeout(120_000),
     });
@@ -115,21 +131,115 @@ async function loadConnectorZip() {
 function isWorkbuddyOnlyCommand(command) {
   return typeof command === "string" && (command.includes("connectors-marketplace") || command.includes(".workbuddy"));
 }
-function serverInstallability(serverName, rawServer) {
+
+// ── T02 投影函数（R1/R2/R3）───────────────────────────────────────────
+// 三个都是纯函数：输入 connectors.json 的原始形状，输出面板行需要的展示字段。
+// 放在这里而不是 client.js，是因为它们处理的是「远端数据的形状防御」，与
+// serverInstallability 同层；UI 只消费结果，不重复判形状。
+
+/** R1：某条连接器的 token 注入规则标注。只数条数、不给注入物（X9：只展示不注入）。 */
+export function injectionRuleNote(indexJson, connectorId) {
+  const rules = rulesFor(parseInjectionRules(indexJson), connectorId);
+  if (!rules.length) return { count: 0, note: "" };
+  return {
+    count: rules.length,
+    note: `存在 ${rules.length} 条 token 注入规则（依赖 WB 账号体系，DSH 不代注入）`,
+  };
+}
+
+/**
+ * R2：visible_in 透传 + 标签筛选。实测为 key 数组（如 ["workbuddy","cline"]）；
+ * 畸形（缺失/非数组/元素非字符串）一律归一成 []，调用方不需要再判形状。
+ * 空数组 ≠ 「不可见」：上游没标就当作全部可见，筛选函数里不拦截。
+ */
+export function visibleInOf(entry) {
+  const raw = entry?.visible_in;
+  if (!Array.isArray(raw)) return [];
+  return raw.map((tag) => (typeof tag === "string" ? tag.trim() : "")).filter(Boolean);
+}
+
+/** R2：本地筛选。visibleTags 为空（上游未标）= 不受该维度过滤；非空才要求包含。 */
+export function matchesVisibleIn(rowVisibleTags, selectedTags) {
+  if (!Array.isArray(selectedTags) || !selectedTags.length) return true;
+  if (!Array.isArray(rowVisibleTags) || !rowVisibleTags.length) return true;
+  const owned = new Set(rowVisibleTags.map((tag) => String(tag).toLowerCase()));
+  return selectedTags.every((tag) => owned.has(String(tag).toLowerCase()));
+}
+
+/**
+ * R3：examples 优先的展示文案。规则（设计文档 R3）：
+ *   有 examples 且非空 → 正文用 examples（按语言 zh/en 选取）；
+ *   否则回落 description；两者都无 → 空串（UI 自行回落到 name）。
+ * 入参都是 connectors.json 条目的原样字段，畸形一律防御性回落。
+ */
+export function displayCopyOf(entry) {
+  const pick = (list) => (Array.isArray(list) ? list.filter((item) => typeof item === "string" && item.trim()).filter(Boolean) : []);
+  const zhExamples = pick(entry?.examples_zh);
+  const enExamples = pick(entry?.examples_en);
+  const examples = zhExamples.length ? zhExamples : enExamples;
+  if (examples.length) {
+    return { body: examples.join("\n"), from: "examples", examples };
+  }
+  const zh = typeof entry?.description_zh === "string" ? entry.description_zh : "";
+  const fallbackZh = typeof entry?.description === "string" ? entry.description : "";
+  const en = typeof entry?.description_en === "string" ? entry.description_en : "";
+  const body = zh || fallbackZh || en;
+  return { body, from: body ? "description" : "", examples: [] };
+}
+
+export function serverInstallability(serverName, rawServer, authMode = "") {
   const reasons = [];
+  // R8：oauth / oneid-token 类不再拒装，而是标记「需走浏览器授权」，
+  // 由 lib/mcp-oauth.js 在安装时驱动 RFC 9728/8414/7591/7636 全链路。
+  let needsOAuth = false;
   const nested = rawServer && typeof rawServer.transport === "object" ? rawServer.transport : rawServer;
-  const transport = String(nested?.type ?? "").toLowerCase();
-  if (transport === "streamablehttp" || transport === "streamable-http" || transport === "http") return { ok: true, transport: "streamable-http" };
+  // mcp.json 里的 stdio 条目本来就只有 command、不写 type（官方示例与各家 README 皆如此）。
+  // 早前这里只认 nested.type：command 型条目 transport 落成空串，被文件末尾的
+  // 「未知传输类型」判为拒装——凡是标准 stdio 连接器都装不上。缺 type 但有 command
+  // 时按 stdio 处理，与下面返回处的 `transport || "stdio"` 兜底保持同一判断。
+  const declaredType = String(nested?.type ?? "").toLowerCase();
+  const transport = declaredType || (typeof nested?.command === "string" && nested.command.trim() ? "stdio" : "");
+  // R7：先扫占位符槽位（env/headers 里的 ${...}）。这一扫描必须发生在 transport 的
+  // 提前 return 之前——否则 streamable-http 型连接器的 header 占位符会被整段跳过，
+  // 而 80+ 条 auth_mode=token 的连接器正是这个传输形态，正是「装不了」的成因之一。
+  const tokenSlots = scanTokenSlots({ [serverName]: rawServer });
+  const hasReplaceableSlots = tokenSlots.length > 0;
+  // 索引 auth_mode 是比 mcp.json 更权威的鉴权声明：mcp.json 可能漏标（如 tec-do 裸 URL），
+  // 但索引里标了鉴权的连接器 DSH 无法自动注入凭据，装上必 401，必须在列表层就拦下。
+  const mode = String(authMode || "").trim().toLowerCase();
+  if (mode === "token") {
+    // R7：token 型由「一律拒装」改为「可装但需引导填 token」。
+    // 有可替换占位符 → 放行（UI 弹令牌框）；无占位符 → 用户无从填起，仍然拒装。
+    if (!hasReplaceableSlots) {
+      reasons.push("该连接器需要 token 凭据，但 mcp.json 未声明可替换的 ${...} 槽位，DSH 无法代填");
+    }
+  } else if (mode === "oauth" || mode === "oneid-token") {
+    // R8：凭据改由插件侧 OAuth 授权流程获取（浏览器授权 → token 落盘 → 注入
+    // authorization header），所以这里放行并打上需授权标记。
+    needsOAuth = true;
+  } else if (mode === "server-side" || mode === "mcp") {
+    reasons.push(`该连接器需要 ${mode} 凭据，DSH 无法自动注入`);
+  } else if (mode) {
+    // 未知 auth_mode 值保守处理：宁可少装不错装（与本文件「能装的标准从严」同一纪律）。
+    reasons.push(`该连接器需要未知类型的鉴权（auth_mode=${mode}），DSH 无法自动注入`);
+  }
+  const needsTokens = hasReplaceableSlots;
+  if (transport === "streamablehttp" || transport === "streamable-http" || transport === "http") {
+    return { ok: reasons.length === 0, transport: "streamable-http", reasons, tokenSlots, needsTokens, needsOAuth };
+  }
   if (transport === "sse" || transport === "ws") reasons.push(`传输 ${transport} 不受 DSH 支持`);
   if (rawServer?.preAuth) reasons.push("需要 WorkBuddy 的 preAuth 鉴权链路");
   if (typeof nested?.command === "string" && isWorkbuddyOnlyCommand(nested.command)) reasons.push("command 依赖 WorkBuddy 本机连接器目录");
   const envKeys = Object.keys(nested?.env || {});
   const headerKeys = Object.keys(nested?.headers || {});
-  if (envKeys.some((key) => /token|secret|key/i.test(key)) || headerKeys.some((key) => /authorization|token/i.test(key))) {
+  // R7：已有可替换占位符的，交给 needsTokens 引导用户填，不再重复算作拒装理由；
+  // 反之（键名像凭据但值里没有 ${...} 槽位）无从填起，仍然拒装。
+  if (!hasReplaceableSlots
+    && (envKeys.some((key) => /token|secret|key/i.test(key)) || headerKeys.some((key) => /authorization|token/i.test(key)))) {
     reasons.push("需要 WorkBuddy 的 token 注入，DSH 无法代填");
   }
   if (!reasons.length && transport !== "stdio") reasons.push(`未知传输类型 ${transport || "（缺失）"}`);
-  return { ok: reasons.length === 0, transport: transport || "stdio", reasons };
+  return { ok: reasons.length === 0, transport: transport || "stdio", reasons, tokenSlots, needsTokens, needsOAuth };
 }
 
 /** connectors.json 索引 + 每条的可装性标注。UI 列表唯一数据源。 */
@@ -155,17 +265,32 @@ export async function wbConnectorCatalog() {
     }
     // mcp.json 可能一条目录带多个 mcpServers；逐个判可装性，全部可装才算可装（安装时逐条写入）。
     const servers = mcpJson?.mcpServers && typeof mcpJson.mcpServers === "object" ? Object.entries(mcpJson.mcpServers) : [];
-    const checks = servers.map(([serverName, rawServer]) => ({ serverName, rawServer, ...serverInstallability(serverName, rawServer) }));
+    const checks = servers.map(([serverName, rawServer]) => ({ serverName, rawServer, ...serverInstallability(serverName, rawServer, entry.auth_mode) }));
     const blocked = checks.filter((check) => !check.ok);
+    // R3：examples 优先（zh → en 回落），description 只作兜底正文。
+    const copy = displayCopyOf(entry);
     rows.push({
       id,
       name: entry.name || id,
       nameEn: entry.name_en || "",
       description: entry.description_zh || entry.description || entry.description_en || "",
       descriptionEn: entry.description_en || "",
+      // R3 投影：UI 优先用 displayBody（examples 语义），from 让 UI 知道在展示什么。
+      displayBody: copy.body,
+      displayFrom: copy.from,
+      examples: copy.examples,
+      // R2：visible_in 标签（上游未标 = 空数组 = 不受筛选）。
+      visibleIn: visibleInOf(entry),
+      // R1：token 注入规则条数标注（只展示；DSH 不代注入）。
+      injectionRuleCount: injectionRuleNote(index, id).count,
+      // R7：可装性拆分投影——needsTokens 为 true 时 UI 应弹令牌引导框。
+      needsTokens: checks.some((check) => check.needsTokens),
+      // R8：needsOAuth 为 true 时 UI 应走「浏览器授权」引导（而不是拒装/令牌框）。
+      needsOAuth: checks.some((check) => check.needsOAuth),
+      tokenSlots: checks.flatMap((check) => check.tokenSlots || []),
       authMode: entry.auth_mode || "",
+      version: entry.version || "",
       type: entry.type || "",
-      examples: entry.examples_zh || entry.examples_en || [],
       skillCount,
       serverNames: checks.map((check) => check.serverName),
       transport: checks[0]?.transport || "",
@@ -190,6 +315,105 @@ export async function wbConnectorPreview(connectorId) {
   return { connectorId: id, mcpServers: servers };
 }
 
+/**
+ * 装前 401 探测：对 streamable-http 型 server 发一次 MCP initialize JSON-RPC，
+ * 服务器明确回 401/403 就中止安装。索引 auth_mode 会漏标（tec-do 的 mcp.json 是裸 URL、
+ * 索引 auth_mode 也为空，装完连接必 401 "Version negotiation failed"）——这是漏标鉴权的
+ * 最后防线。判定刻意保守：只有 401/403 拦，超时/5xx/网络错误/其他状态一律放行——
+ * 探测挂了不能误伤正常连接器，宁可让个别服务器在连接时报错。
+ * 返回 { authorized: true }（放行）或 throw（要求授权，中止整个安装）。
+ */
+export async function probeServerAuthorization(serverName, rawServer) {
+  const nested = rawServer && typeof rawServer.transport === "object" ? rawServer.transport : rawServer;
+  const transport = String(nested?.type ?? "").toLowerCase();
+  // 只探测 HTTP 型：stdio 没有可探测的 URL，sse/ws 本来就被准入闸拦下。
+  if (transport !== "streamablehttp" && transport !== "streamable-http" && transport !== "http") return { authorized: true, skipped: true };
+  const url = String(nested?.url || "").trim();
+  if (!url) return { authorized: true, skipped: true };
+  const body = JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2025-03-26",
+      capabilities: {},
+      clientInfo: { name: "dsh-armory", version: "1.0.0" },
+    },
+  });
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        // 透传 mcp.json 里该 server 已声明的 headers（例如部分连接器带公共 UA/token 模板）。
+        ...Object.fromEntries(Object.entries(nested?.headers || {}).map(([key, value]) => [String(key).toLowerCase(), String(value)])),
+        "user-agent": USER_AGENT,
+      },
+      body,
+      signal: AbortSignal.timeout(8_000),
+    });
+  } catch {
+    // 超时 / DNS 失败 / 连接拒绝：探测不了就放行，安装后由用户实测。
+    return { authorized: true, error: "probe-unreachable" };
+  }
+  if (response.status === 401 || response.status === 403) {
+    // R8：不再把 401 当致命错误。改回传结构化「需授权」，由上层触发浏览器授权流程：
+    // 解析 WWW-Authenticate 里的 resource_metadata，交给 lib/mcp-oauth.js 继续走
+    // RFC 9728（资源元数据）→ RFC 8414（AS 元数据）→ RFC 7591（动态注册）→ RFC 7636（PKCE）。
+    const wwwAuthenticate = String(response.headers.get("www-authenticate") || "");
+    return {
+      authorized: false,
+      needsAuth: true,
+      status: response.status,
+      url,
+      serverName,
+      wwwAuthenticate,
+      resourceMetadata: extractResourceMetadata(wwwAuthenticate),
+    };
+  }
+  // 200/202/4xx 其他/5xx：都视为「没有明确拒绝匿名握手」，放行。
+  return { authorized: true, status: response.status };
+}
+
+/** 从 WWW-Authenticate 里取 resource_metadata="..."（RFC 9728 的入口指针）。 */
+function extractResourceMetadata(header) {
+  const match = String(header || "").match(/resource_metadata\s*=\s*"([^"]+)"/i)
+    || String(header || "").match(/resource_metadata\s*=\s*([^\s,]+)/i);
+  return match ? match[1].trim() : "";
+}
+
+/** 安装前对整份 mcpServers 逐个探测；把「需授权」的 server 聚合成清单回报，绝不中止安装。 */
+export async function probeMcpServersAuthorization(mcpServers) {
+  const servers = mcpServers && typeof mcpServers === "object" ? Object.entries(mcpServers) : [];
+  const needsAuth = [];
+  for (const [serverName, rawServer] of servers) {
+    const probe = await probeServerAuthorization(serverName, rawServer);
+    if (probe?.needsAuth) needsAuth.push(probe);
+  }
+  return { ok: true, checked: servers.length, needsAuth };
+}
+
+/**
+ * 只读磁盘缓存的市场条目计数（供顶栏 chip 常驻显示，绝不联网）。
+ * 磁盘上有 connectors-config.zip 就直接解索引计数；没有就返回 total:null，
+ * 等「市场页真实打开过一次」（那会走完整下载并落缓存）之后再查就有数字了。
+ * 单独存在的意义：wbConnectorCatalog 即使热缓存也会做一次 304 网络探测，
+ * 冷缓存更是 24MB 下载——为顶栏一个数字触发这两者都不值得。
+ */
+export async function wbConnectorCachedCount() {
+  try {
+    const local = await readFile(zipPath());
+    const zip = new ZipReader(local);
+    const index = JSON.parse(zip.extract(".codebuddy-connector/connectors.json").toString("utf8"));
+    const connectors = Array.isArray(index.connectors) ? index.connectors : [];
+    return { total: connectors.filter((entry) => String(entry.id || entry.source || "").trim()).length };
+  } catch {
+    return { total: null };
+  }
+}
+
 // ── SkillHub 技能市场 ─────────────────────────────────────────────────
 // 列表：/api/skills?sortBy=downloads|installs|stars|score&page=N&pageSize=60&keyword=..&category=..
 // 详情：/api/v1/skills/:slug?namespace=<handle>（带 latestVersion、publisher、securityReports）

package/lib/wb-plugin-market.js

@@ -0,0 +1,291 @@
+// CodeBuddy 插件市场（T03/R5）—— sourceFor("plugins") 的 ZIP 数据源与目录投影。
+//
+// 数据链路（与连接器市场同一套形状，缓存目录不同）：
+//   1. 源：lib/wb-registry.js sourceFor("plugins") —— 内置默认
+//      codebuddy-plugins-official（https://download.codebuddy.cn/...zip），
+//      用户注册表条目可覆盖；读不到源时抛错（不发明第二处硬编码）。
+//   2. 缓存：~/.dsh/armory/plugin-market/ 下 plugin.zip + meta.json{etag,fetchedAt}，
+//      ETag 命中就不重复下载（与 wb-market.js 的连接器缓存同构；目录挂在 armory
+//      根下而不是 ~/.dsh/wb-market/，因为这是 armory 自己引入的市场）。
+//   3. 解析（zip 内嵌套清单，实测形状）：
+//      .codebuddy-plugin/marketplace.json —— 市场索引（plugins 数组，取插件目录名）
+//      external_plugins/<name>/.codebuddy-plugin/plugin.json —— 每个插件的清单，
+//      投影 {name,description,author,repository,homepage,license,version,dependencies,lspServers}。
+//
+// 纪律：安装动作不在这里（客户端直接走官方 pluginManager.installBundle，T04 的 R8
+// 才接 wb-install-state 记账）；本文件只做「取数 + 投影」，零副作用除缓存写盘。
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ZipReader } from "./wb-zip.js";
+import { sourceFor } from "./wb-registry.js";
+
+const USER_AGENT = "@2026heshao/dsh-armory (+https://github.com/2026heshao/dsh-armory)";
+const MAX_ZIP_BYTES = 64 * 1024 * 1024;
+
+/** 缓存根目录：~/.dsh/armory/plugin-market（测试可用 options.rootDir 覆盖）。 */
+function pluginMarketDir(options = {}) {
+  return join(options.rootDir || process.env.DSH_ARMORY_HOME || join(homedir(), ".dsh", "armory"), "plugin-market");
+}
+function zipPathOf(options) {
+  return join(pluginMarketDir(options), "plugin.zip");
+}
+function metaPathOf(options) {
+  return join(pluginMarketDir(options), "meta.json");
+}
+
+async function readJsonAt(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** 模块级缓存：一次进程内只解析一次 zip（与 wb-market cachedZip 同构）。 */
+let cachedPluginZip = null;
+
+async function downloadPluginZip(sourceUrl, etag) {
+  const response = await fetch(sourceUrl, {
+    headers: { "user-agent": USER_AGENT, ...(etag ? { "if-none-match": etag } : {}) },
+    signal: AbortSignal.timeout(120_000),
+  });
+  if (response.status === 304 && etag) return null;
+  if (!response.ok) throw new Error(`插件市场下载失败：HTTP ${response.status}`);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (buffer.length > MAX_ZIP_BYTES) throw new Error(`插件市场包超过 ${Math.round(MAX_ZIP_BYTES / 1024 / 1024)}MB 上限，疑似异常响应`);
+  return { buffer, etag: response.headers.get("etag") || "" };
+}
+
+/** 下载（或复用磁盘缓存）并解析插件市场 zip。返回 { zip, loadedFrom }。 */
+async function loadPluginZip(options = {}) {
+  if (cachedPluginZip) return cachedPluginZip;
+  const source = await sourceFor("plugins", options);
+  const sourceUrl = source?.source?.url;
+  if (typeof sourceUrl !== "string" || !sourceUrl) throw new Error("注册表里没有可用的 plugins 市场源");
+  const dir = pluginMarketDir(options);
+  await mkdir(dir, { recursive: true });
+  const meta = (await readJsonAt(metaPathOf(options))) || {};
+  const writeThrough = async (fresh) => {
+    await writeFile(zipPathOf(options), fresh.buffer);
+    await writeFile(metaPathOf(options), JSON.stringify({ etag: fresh.etag, fetchedAt: Date.now() }));
+  };
+  let zip = null;
+  if (meta.etag) {
+    try {
+      const local = await readFile(zipPathOf(options));
+      zip = new ZipReader(local);
+      const fresh = await downloadPluginZip(sourceUrl, meta.etag);
+      if (fresh === null) {
+        cachedPluginZip = { zip, loadedFrom: "disk" };
+        return cachedPluginZip;
+      }
+      zip = new ZipReader(fresh.buffer);
+      await writeThrough(fresh);
+      cachedPluginZip = { zip, loadedFrom: "network" };
+      return cachedPluginZip;
+    } catch {
+      zip = null; // 磁盘缓存损坏 → 走完整重下
+    }
+  }
+  const fresh = await downloadPluginZip(sourceUrl, "");
+  zip = new ZipReader(fresh.buffer);
+  await writeThrough(fresh);
+  cachedPluginZip = { zip, loadedFrom: "network" };
+  return cachedPluginZip;
+}
+
+// ── 清单解析（嵌套投影）──────────────────────────────────────────────────
+
+/** 字符串字段防御读取。 */
+function asString(value, fallback = "") {
+  return typeof value === "string" ? value.trim() : fallback;
+}
+
+/**
+ * marketplace.json → 插件目录名列表。实测形状 { plugins: ["name-a", ...] }；
+ * 兼容 { plugins: [{ name }] } 与 { plugins: { ... } }（对象键即目录名）两种变体。
+ * 畸形一律返回 []，不抛错。
+ */
+export function pluginNamesFromMarketplace(indexJson) {
+  const raw = indexJson?.plugins;
+  if (Array.isArray(raw)) {
+    return raw
+      .map((item) => (typeof item === "string" ? item : asString(item?.name)))
+      .filter(Boolean);
+  }
+  if (raw && typeof raw === "object") return Object.keys(raw).filter(Boolean);
+  return [];
+}
+
+/** 去掉末尾斜杠并统一为 / 分隔（listByPrefix 是小写前缀匹配，路径形态无关紧要）。 */
+/** zip 内插件清单的标准嵌套路径（导出给测试对形状做锚定）。 */
+export function pluginJsonPath(name) {
+  return `external_plugins/${name}/.codebuddy-plugin/plugin.json`;
+}
+
+/**
+ * plugin.json → 面板投影。防御性提取：全部字段缺失不炸；dependencies 缺失 = []
+ * （R6：实测清单无该字段，出现时展示、绝不自动安装）；lspServers 仅透传展示（X7）。
+ */
+export function projectPlugin(name, pluginJson) {
+  const raw = pluginJson && typeof pluginJson === "object" ? pluginJson : {};
+  const deps = Array.isArray(raw.dependencies)
+    ? raw.dependencies
+        .map((dep) => (typeof dep === "string"
+          ? { name: dep.trim(), version: "" }
+          : { name: asString(dep?.name), version: asString(dep?.version || dep?.spec || "") }))
+        .filter((dep) => dep.name)
+    : [];
+  return {
+    name: asString(raw.name) || asString(name),
+    description: asString(raw.description),
+    author: asString(raw.author),
+    repository: asString(raw.repository),
+    homepage: asString(raw.homepage),
+    license: asString(raw.license),
+    version: asString(raw.version),
+    dependencies: deps,
+    lspServers: raw.lspServers && typeof raw.lspServers === "object" ? raw.lspServers : null,
+  };
+}
+
+/**
+ * 从已解析的 ZipReader 枚举全部插件投影。先读市场索引拿目录名，再逐条读
+ * external_plugins/<name>/.codebuddy-plugin/plugin.json（缺清单的目录跳过并计数）。
+ */
+export function readPluginCatalog(zip) {
+  const marketManifestName = ".codebuddy-plugin/marketplace.json";
+  if (!zip.has(marketManifestName)) {
+    return { plugins: [], skipped: 0 };
+  }
+  let indexJson = null;
+  try {
+    indexJson = JSON.parse(zip.extract(marketManifestName).toString("utf8"));
+  } catch {
+    return { plugins: [], skipped: 0 };
+  }
+  const names = pluginNamesFromMarketplace(indexJson);
+  const plugins = [];
+  let skipped = 0;
+  for (const name of names) {
+    const manifestPath = pluginJsonPath(name);
+    if (!zip.has(manifestPath)) {
+      skipped += 1;
+      continue;
+    }
+    try {
+      const pluginJson = JSON.parse(zip.extract(manifestPath).toString("utf8"));
+      plugins.push(projectPlugin(name, pluginJson));
+    } catch {
+      skipped += 1; // 单个插件清单损坏不拖垮整个目录
+    }
+  }
+  return { plugins, skipped };
+}
+
+/**
+ * 目录投影：catalog 返回 {ok, total, loadedFrom, plugins, skipped}。
+ * 投影只保留列表需要的字段（详情从 detail 再取全量），保持响应轻。
+ */
+export async function wbPluginCatalog(options = {}) {
+  const { zip, loadedFrom } = await loadPluginZip(options);
+  const { plugins, skipped } = readPluginCatalog(zip);
+  return {
+    ok: true,
+    loadedFrom,
+    total: plugins.length,
+    skipped,
+    plugins: plugins.map((plugin) => ({
+      name: plugin.name,
+      description: plugin.description,
+      author: plugin.author,
+      repository: plugin.repository,
+      version: plugin.version,
+      license: plugin.license,
+      dependencies: plugin.dependencies,
+    })),
+  };
+}
+
+/**
+ * 单插件详情：全量投影（repository/homepage/lspServers 只在详情透出）。
+ * name 未给或 zip 里没有 → ok:false（不抛错，客户端按「不可用」渲染）。
+ */
+export async function wbPluginDetail(name, options = {}) {
+  const wanted = String(name ?? "").trim();
+  if (!wanted) return { ok: false, error: "缺少插件名" };
+  const { zip, loadedFrom } = await loadPluginZip(options);
+  const manifestPath = pluginJsonPath(wanted);
+  if (!zip.has(manifestPath)) return { ok: false, error: `zip 里没有插件 ${wanted}` };
+  try {
+    const pluginJson = JSON.parse(zip.extract(manifestPath).toString("utf8"));
+    return { ok: true, loadedFrom, plugin: projectPlugin(wanted, pluginJson) };
+  } catch (error) {
+    return { ok: false, error: `插件清单解析失败：${error.message}` };
+  }
+}
+
+/** 供测试与未来 R8（T04）检查缓存是否在场；只读，不联网。 */
+export async function wbPluginCachedInfo(options = {}) {
+  const meta = (await readJsonAt(metaPathOf(options))) || {};
+  return { hasCache: Boolean(meta.etag), etag: meta.etag || "", fetchedAt: meta.fetchedAt || 0 };
+}
+
+// writeAtomic 同款 staging+rename（本文件缓存写用直写即可，这里导出给测试复用形态）。
+export async function writeCacheStaging(path, data) {
+  await mkdir(join(path, ".."), { recursive: true });
+  await writeFile(`${path}.staging`, data);
+  await rm(path, { force: true });
+  await rename(`${path}.staging`, path);
+}
+
+/**
+ * R9（T05）：插件市场更新探测 —— 只做条件请求，**绝不落盘**。
+ *
+ * 判定口径（设计文档）：ETag 与上次落盘的 meta.json 不一致即有更新；
+ * HTTP 304 = 无更新，HTTP 200 = 有更新。HEAD 不传包体做轻量探测；
+ * 服务端对 HEAD 返回 405/501 时降级为 GET，并立即 cancel() 丢弃响应体，
+ * 不把 zip 读进内存。纯探测：不写 zip、不写 meta.json、不更新内存缓存。
+ */
+export async function wbPluginUpdateCheck(options = {}) {
+  try {
+    const source = await sourceFor("plugins", options);
+    const sourceUrl = source?.source?.url;
+    const meta = (await readJsonAt(metaPathOf(options))) || {};
+    const localEtag = meta.etag || "";
+    if (typeof sourceUrl !== "string" || !sourceUrl) {
+      // 市场源检查必须先于 no-cache 分支：市场没配置时绝不能提示「有新版本」。
+      return { ok: false, hasUpdate: false, reason: "no-source", localEtag, remoteEtag: "", checkedAt: Date.now(), error: "注册表里没有可用的 plugins 市场源" };
+    }
+    if (!localEtag) {
+      // 本地没缓存过 → 无法比较，视为有更新，引导用户首次加载（纯探测仍不下载）。
+      return { ok: true, hasUpdate: true, reason: "no-cache", localEtag: "", remoteEtag: "", checkedAt: Date.now() };
+    }
+    const headers = { "user-agent": USER_AGENT, "if-none-match": localEtag };
+    let response;
+    try {
+      response = await fetch(sourceUrl, { method: "HEAD", headers, signal: AbortSignal.timeout(30_000) });
+      if (response.status === 405 || response.status === 501) {
+        // HEAD 不被支持 → 降级 GET，立刻 cancel() 丢弃响应体，不读进内存。
+        response.body?.cancel?.();
+        response = await fetch(sourceUrl, { method: "GET", headers, signal: AbortSignal.timeout(30_000) });
+        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") || "";
+      const hasUpdate = remoteEtag !== localEtag;
+      return { ok: true, hasUpdate, reason: hasUpdate ? "update-available" : "up-to-date", localEtag, remoteEtag, checkedAt: Date.now() };
+    }
+    return { ok: false, hasUpdate: false, reason: "probe-failed", localEtag, remoteEtag: "", checkedAt: Date.now(), error: `插件市场更新探测失败：HTTP ${response.status}` };
+  } catch (error) {
+    return { ok: false, hasUpdate: false, reason: "probe-failed", localEtag: "", remoteEtag: "", checkedAt: Date.now(), error: `更新探测异常：${error.message}` };
+  }
+}