dsh-armory 1.10.0 → 2.0.0

package/lib/wb-install-state.js

@@ -0,0 +1,151 @@
+// 本地安装状态 + 来源锁（R8）—— ~/.dsh/armory/install-state.json 的读写层。
+//
+// 职责（设计文档 docs/system_design.md 8.3 / 类图 InstallStateStore）：
+//   - record(item)：按 kind+key 定位，已存在则覆盖并刷新 lastUpdated；
+//     首次写入补 installedAt。connector 不记 filesDigest，plugin/skill 记关键文件摘要。
+//   - forget(kind, key)：删除一条登记，不存在时为无害空操作。
+//   - listInstalled(kind)：返回该 kind 全部条目（顺序 = 写入序），供面板做「已安装」
+//     **全量本地筛选**（不受分页影响，与技能侧 skillOnlyInstalled 只筛当前页不同）。
+//
+// 三类安装（connector=profile、skill=目录、plugin=宿主 bundle）在各自收尾点调用 record，
+// 把分散的安装事实收敛到这一个文件里——这就是「来源锁」：登记条目带 source
+// {marketplace, url, kind}，面板据此区分「本插件装的」与「其它途径来的」。
+//
+// 纯数据层：零网络。存储根目录可注入（options.rootDir / 环境变量 DSH_ARMORY_HOME），
+// 测试绝不碰真实 ~/.dsh。写盘与 lib/wb-registry.js 同用 staging + rename 原子替换。
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const INSTALL_STATE_VERSION = 1;
+
+const KINDS = new Set(["connector", "skill", "plugin"]);
+
+/** 存储根目录：显式 rootDir > 环境变量 > 真实 ~/.dsh/armory（与 wb-registry 同一解析序）。 */
+function armoryRoot(options = {}) {
+  return options.rootDir || process.env.DSH_ARMORY_HOME || join(homedir(), ".dsh", "armory");
+}
+
+/** 状态文件绝对路径。 */
+export function statePath(options = {}) {
+  return join(armoryRoot(options), "install-state.json");
+}
+
+function asString(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asTimestamp(value, fallback = 0) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+/**
+ * 把任意原始对象规范成一条完整的 InstallStateItem：
+ * 缺失字段防御性补全，畸形来源对象折成空对象而不是抛错。
+ */
+export function normalizeItem(raw) {
+  const source = raw && typeof raw.source === "object" && raw.source !== null ? raw.source : {};
+  const filesDigest = raw && typeof raw.filesDigest === "object" && raw.filesDigest !== null && !Array.isArray(raw.filesDigest)
+    ? raw.filesDigest
+    : {};
+  return {
+    kind: KINDS.has(raw?.kind) ? raw.kind : "connector",
+    key: asString(raw?.key).trim(),
+    name: asString(raw?.name),
+    scope: asString(raw?.scope, "managed"),
+    installPath: asString(raw?.installPath),
+    version: asString(raw?.version),
+    dependencies: Array.isArray(raw?.dependencies) ? raw.dependencies.map((dep) => String(dep)) : [],
+    source: {
+      marketplace: asString(source.marketplace),
+      url: asString(source.url),
+      kind: asString(source.kind),
+    },
+    installedAt: asTimestamp(raw?.installedAt, 0),
+    lastUpdated: asTimestamp(raw?.lastUpdated, 0),
+    filesDigest,
+  };
+}
+
+/** 从磁盘读原始文档；不存在/损坏一律返回 null。 */
+async function readRawDoc(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** 拆出目录部分（路径既有 / 也有 \ 的 Windows 形态）。 */
+function dirnameOf(path) {
+  const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return cut > 0 ? path.slice(0, cut) : path;
+}
+
+/** staging + rename 原子写（与 wb-registry.writeAtomic 同一模式）。 */
+async function writeAtomic(path, doc) {
+  await mkdir(dirnameOf(path), { recursive: true });
+  await writeFile(`${path}.staging`, JSON.stringify(doc, null, 2));
+  await rm(path, { force: true });
+  await rename(`${path}.staging`, path);
+}
+
+/** 读全部条目（合并投影：文件缺失/损坏 = 空状态）。永不抛错。 */
+export async function readState(options = {}) {
+  const raw = await readRawDoc(statePath(options));
+  const items = Array.isArray(raw?.items)
+    ? raw.items.filter((item) => item && typeof item === "object" && !Array.isArray(item)).map(normalizeItem)
+    : [];
+  const version = raw && typeof raw.version === "number" ? raw.version : INSTALL_STATE_VERSION;
+  return { version, items };
+}
+
+/**
+ * 登记一条安装：同 kind+key 覆盖（刷新 lastUpdated，保留首次的 installedAt），
+ * 首次写入补 installedAt。connector 不落 filesDigest（连接器装进 profile，
+ * 没有关键文件可记）；plugin/skill 原样保留传入的 filesDigest。
+ */
+export async function record(item, options = {}) {
+  const normalized = normalizeItem(item);
+  if (!normalized.key) throw new Error("安装状态条目缺少 key，无法登记");
+  const path = statePath(options);
+  const { items } = await readState(options);
+  const now = Date.now();
+  const index = items.findIndex((entry) => entry.kind === normalized.kind && entry.key === normalized.key);
+  if (index >= 0) {
+    const existing = items[index];
+    items[index] = {
+      ...normalized,
+      installedAt: existing.installedAt || now,
+      lastUpdated: now,
+      filesDigest: normalized.kind === "connector" ? {} : (Object.keys(normalized.filesDigest).length ? normalized.filesDigest : existing.filesDigest),
+    };
+  } else {
+    items.push({
+      ...normalized,
+      installedAt: now,
+      lastUpdated: now,
+      filesDigest: normalized.kind === "connector" ? {} : normalized.filesDigest,
+    });
+  }
+  await writeAtomic(path, { version: INSTALL_STATE_VERSION, items });
+}
+
+/** 删除一条登记（kind+key 定位）。不存在时为无害空操作。 */
+export async function forget(kind, key, options = {}) {
+  const wantedKind = String(kind ?? "").trim();
+  const wantedKey = String(key ?? "").trim();
+  if (!wantedKind || !wantedKey) throw new Error("forget 需要 kind 与 key");
+  const path = statePath(options);
+  const { items } = await readState(options);
+  const kept = items.filter((entry) => !(entry.kind === wantedKind && entry.key === wantedKey));
+  if (kept.length === items.length) return; // 没删到东西：不写盘
+  await writeAtomic(path, { version: INSTALL_STATE_VERSION, items: kept });
+}
+
+/** 该 kind 的全部已安装条目（供「已安装」全量筛选）。 */
+export async function listInstalled(kind, options = {}) {
+  const wanted = String(kind ?? "").trim();
+  const { items } = await readState(options);
+  return items.filter((entry) => entry.kind === wanted);
+}

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,86 @@ 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，