dsh-armory 1.9.3 → 1.10.0

package/lib/mcp-import-sources.js

@@ -527,6 +527,127 @@ function parseFailure(error, text) {
   return 0
 }
 
+// ---------------------------------------------------------------------------
+// VS Code `${input:...}`：逐条降级，不整份拒绝
+// ---------------------------------------------------------------------------
+
+/**
+ * VS Code 的 `${input:名称}`：值由人在**导入时**填写，DSH 读配置的时候无从知道。
+ * 它是 VS Code 专属写法，出现在别的客户端配置里也代表同一件事。
+ */
+const VSCODE_INPUT = /\$\{input:([^}]*)\}/g
+
+/** 一个字符串里出现的 input 名，按出现顺序去重。 */
+function vscodeInputNames(value) {
+  if (typeof value !== 'string' || !value.includes('${input:')) return []
+  const names = []
+  for (const match of value.matchAll(VSCODE_INPUT)) {
+    const name = match[1].trim()
+    if (name && !names.includes(name)) names.push(name)
+  }
+  return names
+}
+
+/** 报错/提示里统一用 `${input:x}` 原样回显名字（名字本身不是密钥）。 */
+const showInputs = (names) => names.map((name) => `\${input:${name}}`).join('、')
+
+/** 条目会走哪条传输：只用于把不支持项说清楚，不参与归一化判定。 */
+function guessTransport(raw) {
+  if (typeof raw.type === 'string' && raw.type.trim()) return raw.type.trim()
+  if (typeof raw.transport === 'string' && raw.transport.trim()) return raw.transport.trim()
+  if (typeof raw.command === 'string' && raw.command.trim()) return 'stdio'
+  const url = raw.url ?? raw.serverUrl ?? raw.server_url
+  return typeof url === 'string' && url.trim() ? 'streamable-http' : 'unknown'
+}
+
+/**
+ * 把一条 VS Code 条目里的 `${input:...}` 按位置分三类处理：
+ *
+ * - **url / command / cwd**：地址或可执行文件本身就是交互值，剔掉就没得导了，
+ *   所以整条标记为不支持、不进 `entries`。
+ * - **env / headers 的某一项**：先剔掉那一项，剩下的照常导入——少一个环境变量
+ *   会变成一个看得见的启动/鉴权失败，比整条消失更容易被用户理解和补救。
+ * - **args 的某一个元素**：同上，剔掉那个参数。
+ *
+ * 返回 `blocked` 非空表示整条不可用；否则 `raw` 是剔干净后的副本。
+ */
+function splitVscodeInputs(name, raw) {
+  // 顺序固定成 url → command → cwd → args → env → headers：前面出现就整条判死，
+  // 后面即使也用到 input 也一并记进 names，方便用户一次看全。
+  const hard = []
+  for (const field of ['url', 'serverUrl', 'server_url', 'command', 'cwd']) {
+    for (const found of vscodeInputNames(raw[field])) if (!hard.includes(found)) hard.push(found)
+  }
+  if (hard.length) {
+    for (const field of ['args', 'env', 'headers']) {
+      for (const value of field === 'args' && Array.isArray(raw.args) ? raw.args : Object.values(isObject(raw[field]) ? raw[field] : {})) {
+        for (const found of vscodeInputNames(value)) if (!hard.includes(found)) hard.push(found)
+      }
+    }
+    return { blocked: hard, raw: null, warnings: [] }
+  }
+  const warnings = []
+  const soft = []
+  const clean = { ...raw }
+  const args = stripFromArgs(name, raw.args, soft, warnings)
+  if (args === undefined) delete clean.args
+  else clean.args = args
+  for (const field of ['env', 'headers']) {
+    // 不是对象就原样留给下游报错：这里静默删掉会把"env 写错了"变成"没有 env"。
+    if (!isObject(raw[field])) continue
+    const table = stripFromMap(name, field, raw[field], soft, warnings)
+    // 整个字段被剔空时删掉它，别让下游把 `env: {}` 当成"用户写了空表"。
+    if (table === undefined) delete clean[field]
+    else setOwn(clean, field, table)
+  }
+  return { blocked: [], raw: clean, warnings, names: soft }
+}
+
+/**
+ * args 里带 `${input:...}` 的元素剔除。剔除后可能剩一个空数组——那就把字段删掉，
+ * 别让下游把 `args: []` 当成"用户显式写了空参数表"。
+ */
+function stripFromArgs(name, args, soft, warnings) {
+  // `args` 写成单个字符串时下游会原样当成一个参数：它带 input 就同样不可用。
+  if (typeof args === 'string') {
+    const found = vscodeInputNames(args)
+    if (!found.length) return args
+    for (const inputName of found) if (!soft.includes(inputName)) soft.push(inputName)
+    warnings.push(`${name}.args 里的 ${showInputs(found)} 需要交互取值，已跳过这个参数`)
+    return undefined
+  }
+  if (!Array.isArray(args)) return args
+  const kept = []
+  for (const item of args) {
+    const found = vscodeInputNames(item)
+    if (!found.length) {
+      kept.push(item)
+      continue
+    }
+    for (const inputName of found) if (!soft.includes(inputName)) soft.push(inputName)
+    warnings.push(`${name}.args 里的 ${showInputs(found)} 需要交互取值，已跳过这个参数`)
+  }
+  return kept.length || args.length === 0 ? kept : undefined
+}
+
+/** env / headers 里值带 `${input:...}` 的项剔除。整表剔空时删掉字段。 */
+function stripFromMap(name, field, table, soft, warnings) {
+  if (!isObject(table)) return undefined
+  const kept = {}
+  let dropped = 0
+  for (const [key, value] of Object.entries(table)) {
+    const found = vscodeInputNames(value)
+    if (!found.length) {
+      setOwn(kept, key, value)
+      continue
+    }
+    dropped += 1
+    for (const inputName of found) if (!soft.includes(inputName)) soft.push(inputName)
+    warnings.push(`${name}.${field}.${key} 需要交互取值（${showInputs(found)}），已跳过`)
+  }
+  return dropped && !Object.keys(kept).length ? undefined : kept
+}
+
 /**
  * 按来源解析文本并归一化成 DSH spec。逐条目容错：一条不支持不影响其余条目。
  * 返回的 `spec` 是 Host 侧内部值（含 `!!js` 表达式与字面密钥），**不得**直接发给浏览器。
@@ -541,33 +662,50 @@ export function normalizeSourceText(source, text, format = 'json') {
     parsed = parseSourceText(format, content)
   } catch (error) {
     const line = parseFailure(error, content)
-    return { entries: [], warnings: [], error: `不是合法 ${PARSE_LABEL[format] || format}${line ? `（第 ${line} 行附近）` : ''}` }
+    return { entries: [], warnings: [], unsupportedEntries: [], error: `不是合法 ${PARSE_LABEL[format] || format}${line ? `（第 ${line} 行附近）` : ''}` }
   }
-  if (!isObject(parsed)) return { entries: [], warnings: [], error: '配置根节点必须是对象' }
-  // VS Code 的 ${input:...} 需要交互取值，normalizeMcpImport 会整份拒绝；
-  // 在取段落之前就给出同样的判断，避免一条输入变量吞掉整份文件。
+  if (!isObject(parsed)) return { entries: [], warnings: [], unsupportedEntries: [], error: '配置根节点必须是对象' }
+  // OPT-17：VS Code 的 `${input:...}` 原本在这里整份拒绝，结果是一条交互变量吞掉
+  // 文件里其余 19 条能用的服务。改成逐条降级：位置可剔的（env/headers/args）剔掉后
+  // 照常导入并在 warnings 里说清楚，位置不可剔的（url/command/cwd）只把那一条记进
+  // unsupportedEntries，`error` 只留给"整份文件读不懂"。
   const warnings = []
-  if (Array.isArray(parsed.inputs) && parsed.inputs.length > 0) {
-    return { entries: [], warnings, error: 'VS Code inputs 需要交互式取值，DSH 当前不支持安全转换' }
-  }
+  const unsupportedEntries = []
+  // 声明了 `inputs` 只说明这份文件"可能"用到交互变量，不再是拒绝理由；真正的判定
+  // 落在每个条目上——没被引用的 inputs 声明不该影响任何导入，也不该冒出一条噪音提示。
   const selected = source.select(parsed, warnings)
-  if (selected === null) return { entries: [], warnings, error: '没有找到该客户端使用的 MCP 段落' }
+  if (selected === null) return { entries: [], warnings, unsupportedEntries, error: '没有找到该客户端使用的 MCP 段落' }
   const entries = []
   for (const item of selected) {
     const carried = item.warnings || []
     if (item.error) {
-      entries.push({ name: item.name, spec: null, error: item.error, warnings: carried })
+      entries.push({ name: item.name, spec: null, error: item.error, warnings: carried, unsupported: null })
+      continue
+    }
+    const split = splitVscodeInputs(item.name, item.raw)
+    const merged = [...carried, ...split.warnings]
+    // url / command / cwd 本身是交互值：这条没法安全转换。不进 `entries`（下游只认
+    // 可导入的 spec），改在 `unsupportedEntries` 里留一份可展示信息，别让它凭空消失。
+    if (split.blocked.length) {
+      unsupportedEntries.push({
+        name: item.name,
+        transport: guessTransport(item.raw),
+        reason: `地址/命令里用到 ${showInputs(split.blocked)}，需要交互取值，DSH 无法安全转换`,
+        names: split.blocked,
+      })
       continue
     }
     try {
-      const normalized = normalizeMcpImport({ mcpServers: { [item.name]: item.raw } })
-      entries.push({ name: item.name, spec: normalized.servers[0], error: null, warnings: [...carried, ...normalized.warnings] })
+      const normalized = normalizeMcpImport({ mcpServers: { [item.name]: split.raw } })
+      entries.push({ name: item.name, spec: normalized.servers[0], error: null, warnings: [...merged, ...normalized.warnings], unsupported: null })
     } catch (error) {
-      entries.push({ name: item.name, spec: null, error: String(error?.message ?? error), warnings: carried })
+      entries.push({ name: item.name, spec: null, error: String(error?.message ?? error), warnings: merged, unsupported: null })
     }
   }
-  if (!entries.length) return { entries, warnings, error: '这条配置里没有 MCP' }
-  return { entries, warnings, error: '' }
+  // 全部条目都不可用时 `error` 仍然是 null：上层要能说"3 条不支持 / 0 条可导入"，
+  // 而不是一句"失败"。只有真的一条 MCP 都没找到才落到下面的文案。
+  if (!entries.length && !unsupportedEntries.length) return { entries, warnings, unsupportedEntries, error: '这条配置里没有 MCP' }
+  return { entries, warnings, unsupportedEntries, error: '' }
 }
 
 export function hashSourceText(text) {
@@ -640,6 +778,7 @@ async function inspectImportLocation(source, location, ctx, readText) {
     error: '',
     contentHash: '',
     entries: [],
+    unsupportedEntries: [],
     warnings: [],
   }
   const picked = await pickCandidate(location, readText)
@@ -655,6 +794,7 @@ async function inspectImportLocation(source, location, ctx, readText) {
   row.contentHash = hashSourceText(picked.text)
   const normalized = normalizeSourceText(source, picked.text, picked.candidate.format)
   row.entries = normalized.entries
+  row.unsupportedEntries = normalized.unsupportedEntries
   row.warnings = normalized.warnings
   row.error = normalized.error
   return row

package/lib/tool-ledger.js

@@ -25,6 +25,31 @@ const MCP_PREFIX = "mcp__";
 /** 每处理这么多文件让出一次事件循环，避免大库扫描把宿主卡住。 */
 const YIELD_EVERY = 16;
 
+/**
+ * `zlib.zstdDecompressSync` 是 Node >= 22.15 才有的 API。缺失时**绝对不能**静默把每个帧
+ * 都当成「损坏」吞掉：那会让工具裁缝表现为「扫到了 N 个会话、读到了 N 个日志、调用数整列 0」，
+ * 而界面上看不到任何原因 —— 与「只看零调用」筛选的界面表现完全一致，无法自证清白。
+ * 所以这里探测一次，让失败有名字（OPT-01）。
+ */
+const ZSTD_SUPPORTED = typeof zlib.zstdDecompressSync === "function";
+const ZSTD_UNAVAILABLE_MESSAGE =
+	"zstd 解压不可用：当前 Node 不支持 zlib.zstdDecompressSync（需 Node >= 22.15）";
+
+/**
+ * 单个日志的**落盘体积**上限（OPT-06）。完整链路是「整块读入 → 逐帧解压 → Buffer.concat
+ * → toString(utf8) → split(换行)」，峰值内存约为压缩体积的 5~10 倍；没有上限意味着一个异常
+ * 长的会话日志就能拖垮主进程。64 MB 相对当前最大单文件（4.4 MB）有十四倍冗余，正常使用碰不到。
+ */
+const MAX_LOG_BYTES = 64 * 1024 * 1024;
+/** 解压文本缓存预算：按**字节**控制而非只按条数（见 textCache 注释）。 */
+const TEXT_CACHE_MAX_BYTES = 128 * 1024 * 1024;
+const TEXT_CACHE_MAX_ENTRIES = 32;
+
+/** 把字节数格式化成 MB 文案，只用于诊断信息。 */
+function formatMB(bytes) {
+	return `${(bytes / 1_048_576).toFixed(1)} MB`;
+}
+
 /**
  * 解压**多帧** zstd 缓冲（宽容版）。与 dsh-forget-session 的 zstdDecompressAllFrames 同思路：
  * 按 zstd magic（0x28B52FFD）切帧逐帧解压；单帧文件行为不变。
@@ -33,6 +58,9 @@ const YIELD_EVERY = 16;
  * @returns {{ text: string, frames: number, failedFrames: number }}
  */
 function zstdDecompressAllFramesLenient(buf) {
+	// 硬守卫（OPT-01）：Node 太旧时**必须**抛出一个有名字的错误，让 scanSessionLedger 的
+	// failures() 捕获并写进 failedFileSamples 上屏，而不是逐帧 try/catch 各自吞掉、静默全 0。
+	if (!ZSTD_SUPPORTED) throw new Error(ZSTD_UNAVAILABLE_MESSAGE);
 	const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
 	const starts = [];
 	let idx = buf.indexOf(MAGIC, 0);
@@ -54,6 +82,65 @@ function zstdDecompressAllFramesLenient(buf) {
 	return { text: Buffer.concat(parts).toString("utf8"), frames: starts.length, failedFrames };
 }
 
+/**
+ * 解压文本的跨调用缓存（OPT-03）。收益主体在这里：扫描耗时绝大部分花在「读盘 + 逐帧解压
+ * + utf8 解码」上，JSON 解析只占小头。
+ *
+ * 两条纪律：
+ *   1. 键是**日志绝对路径**，戳是 `size:mtimeMs`。日志是追加写，写必然同时抬升 size 与 mtime，
+ *      所以戳一变就失效，不会拿到陈旧数据；反过来，戳没变时内容按定义没有变化。
+ *   2. 淘汰按**字节预算**而不是只按条数。按报告里 32 条 × 解压后 15 MB 估算是 480 MB 峰值，
+ *      在宿主主进程里不可接受；这里 128 MB 封顶，超过就按 LRU 丢到预算以内。
+ * 只缓存 scanSessionLedger 需要的那点数据（解压文本 + 帧统计），不缓存任何调用记录。
+ */
+const textCache = new Map(); // logPath -> { stamp, bytes, text, frames, failedFrames }
+let textCacheBytes = 0;
+
+function dropCacheEntry(logPath) {
+	const entry = textCache.get(logPath);
+	if (entry) {
+		textCacheBytes -= entry.bytes;
+		textCache.delete(logPath);
+	}
+}
+
+function rememberCacheEntry(logPath, entry) {
+	dropCacheEntry(logPath);
+	textCache.set(logPath, entry);
+	textCacheBytes += entry.bytes;
+	// Map 的迭代顺序即插入顺序，队首就是最久未使用的一条。
+	while (textCache.size > TEXT_CACHE_MAX_ENTRIES || textCacheBytes > TEXT_CACHE_MAX_BYTES) {
+		const oldest = textCache.keys().next();
+		if (oldest.done) break;
+		dropCacheEntry(oldest.value);
+	}
+}
+
+/**
+ * 读取并解压一个日志文件，命中缓存则完全跳过 IO 与解压。
+ * @param {string} logPath - 日志绝对路径。
+ * @param {{ size: number, mtimeMs: number }} st - 已取到的 stat 结果（不额外产生 IO）。
+ * @returns {Promise<{ text: string, frames: number, failedFrames: number }>}
+ */
+async function readLogTextCached(logPath, st) {
+	const stamp = `${st.size}:${st.mtimeMs}`;
+	const hit = textCache.get(logPath);
+	if (hit && hit.stamp === stamp) {
+		// 触碰一次，让它在 LRU 里回到队尾。
+		textCache.delete(logPath);
+		textCache.set(logPath, hit);
+		return hit;
+	}
+	const raw = await readFile(logPath);
+	const value = logPath.endsWith(".zstd")
+		? zstdDecompressAllFramesLenient(raw)
+		: { text: raw.toString("utf8"), frames: 0, failedFrames: 0 };
+	const entry = { stamp, bytes: Buffer.byteLength(value.text, "utf8"), ...value };
+	// 单条就超出总预算的怪物不缓存（否则会把整个缓存挤空，还占着内存）。
+	if (entry.bytes <= TEXT_CACHE_MAX_BYTES) rememberCacheEntry(logPath, entry);
+	return value;
+}
+
 /**
  * DSH 数据根（`~/.dsh` 的上一级）。优先 `DSH_SKILL_MCP_BOARD_HOME`（测试隔离用，与
  * dsh-forget-session 的 `DSH_FORGET_SESSION_HOME` 同一惯用法），否则 OS 家目录。
@@ -115,6 +202,7 @@ export async function scanSessionLedger({ days, mcpServerNames, schemas, disable
 	const usage = new Map(); // toolName -> record
 	let filesRead = 0;
 	let filesSkippedStale = 0;
+	let filesSkippedOversize = 0;
 	let failedFiles = 0;
 	let failedFileSamples = [];
 	let sessionDirs = 0;
@@ -124,6 +212,16 @@ export async function scanSessionLedger({ days, mcpServerNames, schemas, disable
 	let totalErrors = 0;
 	let orphanResults = 0;
 	let failedFrames = 0;
+	// §5.4 逐日趋势：扫描时顺手按天分桶，不额外遍历日志。
+	// 桶只存「窗口内的相对天序号」（0 = 最早一天，windowDays-1 = 今天），
+	// 由界面负责渲染；返回绝对日期反而让前端多一次时区换算的机会出错。
+	const dayBuckets = new Array(windowDays).fill(0);
+	const dayIndex = (time) => {
+		if (typeof time !== "number") return null;
+		const offset = now - time;
+		const idx = windowDays - 1 - Math.floor(offset / 86_400_000);
+		return idx >= 0 && idx < windowDays ? idx : null;
+	};
 	const failures = (reason) => {
 		failedFiles += 1;
 		if (failedFileSamples.length < 20) failedFileSamples.push(reason);
@@ -160,32 +258,35 @@ export async function scanSessionLedger({ days, mcpServerNames, schemas, disable
 			}
 			for (const logName of logFiles) {
 				const logPath = join(sessDir, logName);
+				let st;
 				try {
 					// mtime 早于窗口起点 → 里面不可能有窗口内事件，整个文件跳过。
 					// 依据：日志是追加写，追加必然抬升 mtime。
-					const st = await stat(logPath);
-					if (st.mtimeMs < cutoffMs) {
-						filesSkippedStale += 1;
-						continue;
-					}
+					st = await stat(logPath);
 				} catch {
 					failures(`${logPath}: stat failed`);
 					continue;
 				}
-				let text;
+				if (st.mtimeMs < cutoffMs) {
+					filesSkippedStale += 1;
+					continue;
+				}
+				// 尺寸闸门放在读盘之前（OPT-06）：超限就降级跳过，并把原因交给 failures()
+				// 上屏，而不是先整块读进来再发现内存不够。
+				if (st.size > MAX_LOG_BYTES) {
+					filesSkippedOversize += 1;
+					failures(`${logPath}: 日志 ${formatMB(st.size)} 超过 ${formatMB(MAX_LOG_BYTES)} 上限，已跳过`);
+					continue;
+				}
+				let loaded;
 				try {
-					const raw = await readFile(logPath);
-					if (logName.endsWith(".zstd")) {
-						const out = zstdDecompressAllFramesLenient(raw);
-						text = out.text;
-						failedFrames += out.failedFrames;
-					} else {
-						text = raw.toString("utf8");
-					}
+					loaded = await readLogTextCached(logPath, st);
 				} catch (error) {
 					failures(`${logPath}: ${error instanceof Error ? error.message : String(error)}`);
 					continue;
 				}
+				const text = loaded.text;
+				failedFrames += loaded.failedFrames;
 				filesRead += 1;
 				let dirHadCall = false;
 				for (const line of text.split("\n")) {
@@ -210,6 +311,8 @@ export async function scanSessionLedger({ days, mcpServerNames, schemas, disable
 						record.calls += 1;
 						totalCalls += 1;
 						dirHadCall = true;
+						const bucket = dayIndex(time);
+						if (bucket !== null) dayBuckets[bucket] += 1;
 						if (callId) record.seenCallIds.add(callId);
 						if (time !== null) {
 							if (record.firstUsedMs === null || time < record.firstUsedMs) record.firstUsedMs = time;
@@ -314,9 +417,19 @@ export async function scanSessionLedger({ days, mcpServerNames, schemas, disable
 		sessionsWithCalls,
 		filesRead,
 		filesSkippedStale,
+		filesSkippedOversize,
 		failedFiles,
 		failedFileSamples,
 		failedFrames,
+		// OPT-01/OPT-02：把「解码能力」和「失败原因」显式交给上层，界面才有东西可显示。
+		zstdSupported: ZSTD_SUPPORTED,
+		// 界面在 zstd 降级时会提示「升级到 22.15 以上」，得能说出用户当前跑的是什么版本，
+		// 否则那句提示等于没说。取宿主进程自己的版本（不是 package.json 的 engines 声明）。
+		nodeVersion: process.versions.node,
+		// OPT-19：解压文本缓存的占用快照（见 textCacheStats）。128 MB 常驻占用此前对用户
+		// 完全不可见——报告带上它，面板才有数据展示「缓存占了多少、离上界还有多远」，并
+		// 在接近上界时引导用户手动回收（清空动作由 index.js 的 toolTailor 方法承接）。
+		textCache: textCacheStats(),
 		totalCalls,
 		totalResults,
 		totalErrors,
@@ -327,6 +440,109 @@ export async function scanSessionLedger({ days, mcpServerNames, schemas, disable
 		deadMcpCount: deadMcpTools.length,
 		taxTotalTokens,
 		deadMcpTaxTokens,
+		// §5.4 趋势数据：逐日调用量（下标 0 = 窗口最早一天）。
+		// 界面只在「确实有调用」时画 sparkline，全 0 从这里就能看出来，不必前端猜。
+		dailyCalls: dayBuckets,
 		tools,
 	};
 }
+
+// OPT-19：解压文本缓存（OPT-03）的**可观测性**与**手动回收**。128 MB 上界在长时间运行的
+// 宿主里是笔实实在在的常驻占用，但本模块此前只导出 scanSessionLedger，条数/字节数/新鲜度全
+// 关在模块私有作用域里：用户既看不到占用，也没有任何回收手段，出问题只能重启宿主。下面两个
+// 导出只读写模块私有状态——不读盘、不解压、不新增 RPC 契约（接线到宿主由 index.js 另行负责）。
+
+/** utilization 的量化倍数：10^4，即保留 4 位小数（0.0001 精度），避免浮点长尾进入面板文案。 */
+const UTILIZATION_SCALE = 10_000;
+
+/**
+ * 从缓存条目的戳（`size:mtimeMs`）里取出**毫秒时间戳**。
+ *
+ * 戳是复合串：它同时编码落盘体积与 mtime，用来判「内容是否变化」（见 readLogTextCached）。
+ * 但对外契约要的是 number ——「这条缓存有多久没动」是个时间点，复合串既不是数字、也不能
+ * 直接按字典序比较大小（`"9:..."` > `"10:..."`），所以这里只取后段的 mtimeMs。解析不出来
+ * （历史遗留条目或将来改了格式）时返回 null，由调用方跳过该条，绝不让 NaN 污染最值聚合。
+ * @param {{ stamp?: unknown }} entry - 缓存条目。
+ * @returns {number|null} 毫秒时间戳，无法解析时为 null。
+ */
+function stampTimeMs(entry) {
+	if (typeof entry?.stamp !== "string") return null;
+	const sep = entry.stamp.lastIndexOf(":");
+	if (sep === -1) return null;
+	const ms = Number(entry.stamp.slice(sep + 1));
+	return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * 解压文本缓存的只读快照。**纯数据、无副作用**：不读盘、不解压、不改变 LRU 顺序，可以在
+ * 面板渲染时顺手取一次而不用担心干扰扫描。
+ *
+ * `utilization` 取「字节占用率」与「条数占用率」的**较大者**：rememberCacheEntry 的收缩条件
+ * 是 `size > maxEntries || bytes > maxBytes`，任一维度逼近上界都会触发淘汰；只看字节会漏掉
+ * 「32 条小文件把条数打满、字节却很低」这种同样会开始丢缓存的情况。
+ * @returns {{
+ *   entries: number,
+ *   bytes: number,
+ *   maxEntries: number,
+ *   maxBytes: number,
+ *   utilization: number,
+ *   oldestStamp: number|null,
+ *   newestStamp: number|null
+ * }} 缓存占用快照；空缓存时 entries/bytes/utilization 全为 0，两个戳为 null。
+ */
+export function textCacheStats() {
+	let oldestStamp = null;
+	let newestStamp = null;
+	for (const entry of textCache.values()) {
+		const stamp = stampTimeMs(entry);
+		if (stamp === null) continue;
+		if (oldestStamp === null || stamp < oldestStamp) oldestStamp = stamp;
+		if (newestStamp === null || stamp > newestStamp) newestStamp = stamp;
+	}
+	const entries = textCache.size;
+	const bytes = Number.isFinite(textCacheBytes) ? textCacheBytes : 0;
+	// 必须 clamp：淘汰是「先写入、再按预算收缩」，单条最大可到 128 MB，写后到收缩之间瞬时
+	// 会越过上界（raw 可能 > 1）；下界 0 则是防计数漂移（理论上不该为负，但负数利用率上屏
+	// 毫无意义）。四舍五入放在 clamp 之后，保证结果恒在 [0, 1] 且只保留 4 位小数。
+	const raw = Math.max(bytes / TEXT_CACHE_MAX_BYTES, entries / TEXT_CACHE_MAX_ENTRIES);
+	const utilization = Math.round(Math.min(Math.max(raw, 0), 1) * UTILIZATION_SCALE) / UTILIZATION_SCALE;
+	return {
+		entries,
+		bytes,
+		maxEntries: TEXT_CACHE_MAX_ENTRIES,
+		maxBytes: TEXT_CACHE_MAX_BYTES,
+		utilization,
+		oldestStamp,
+		newestStamp,
+	};
+}
+
+/**
+ * 清空解压文本缓存并复位计数，返回被清掉的内容概要（供面板说「已释放 x MB」）。
+ *
+ * 实现顺序是有意为之——**先取 size 快照 → 再 clear → 最后把计数显式归零**：
+ *   1. 不能先 `textCache.clear()` 再取 size / 遍历求和：那时 Map 已空，clearedEntries 与
+ *      clearedBytes 会恒为 0，面板就永远只能说「已释放 0 MB」；
+ *   2. 也不能指望 `dropCacheEntry` 顺手收拾计数——它按 logPath 逐条 `-=`，必须先于 clear
+ *      调用才有意义；clear 之后它拿不到任何条目，等于什么也没做（这正是最容易被写反的地方）；
+ *   3. 计数变量 `textCacheBytes` 是**独立**于 Map 的，`Map.clear()` 不会动它。漏掉归零就会
+ *      留下一笔幽灵占用：此后 rememberCacheEntry 的预算循环会立刻判定超限并把刚写进去的条目
+ *      淘汰掉（表现为缓存「莫名其妙永不命中」）。所以这里无条件赋 0，而不是 `-= clearedBytes`。
+ *
+ * 安全性：清空后下一次 scanSessionLedger 走的是 readLogTextCached 的未命中分支（读盘 →
+ * 解压 → 回填），完全不依赖缓存状态，只是「重新解压一遍」，不会抛错。风险点其实在反方向：
+ * 清空后若 `textCacheBytes` 没归零（留着正数），后续每一次 rememberCacheEntry 都会在预算
+ * 循环里把刚写进来的条立刻丢掉，看上去就像「缓存失效了」；归零才不会把缓存卡死。
+ * 幂等：空缓存上再调一次，返回 clearedEntries 与 clearedBytes 均为 0。
+ * @returns {{ clearedEntries: number, clearedBytes: number, entries: number, bytes: number }}
+ *   被清掉的条数/字节数；entries 与 bytes 恒为 0，表示清空后的状态。
+ */
+export function clearTextCache() {
+	const clearedEntries = textCache.size;
+	// 负值只可能来自计数漂移；对面板而言「-0.0 MB」没有任何意义，按 0 呈现。清空后的状态
+	// 则无条件归零，漂移不会被带进下一轮的预算判断。
+	const clearedBytes = Number.isFinite(textCacheBytes) ? Math.max(textCacheBytes, 0) : 0;
+	textCache.clear();
+	textCacheBytes = 0;
+	return { clearedEntries, clearedBytes, entries: 0, bytes: 0 };
+}

package/lib/typert.js

@@ -85,6 +85,8 @@ export const TYPERT = {
     // WorkBuddy 市场直连（连接器 MCP + SkillHub 技能）。payload 全部 $any：数据形状由
     // lib/wb-market.js 校验，契约层与 builtins/importJson 同一宽容度。
     mv('wbConnectorCatalog', [], 'WbCatalogResult'),
+    // 顶栏「市场」chip 常驻计数：只读磁盘缓存，零网络；无缓存返回 { total: null }。
+    mv('wbConnectorCachedCount', [], 'WbCachedCountResult'),
     mv('wbConnectorPreview', [payloadParam], 'WbPreviewResult'),
     mv('wbConnectorInstall', [payloadParam], 'NoteResult'),
     mv('wbSkillCatalog', [payloadParam], 'WbSkillListResult'),

package/lib/wb-market.js

@@ -190,6 +190,25 @@ export async function wbConnectorPreview(connectorId) {
   return { connectorId: id, mcpServers: servers };
 }
 
+/**
+ * 只读磁盘缓存的市场条目计数（供顶栏 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/whats-new.js

@@ -267,4 +267,70 @@ export const WHATS_NEW = [
       },
     ],
   },
+  {
+    version: '1.9.4',
+    items: [
+      {
+        text: '**团队型专家可以召唤了**：以前 53 个专家团（软件开发团队、内容工厂等）在列表里只显示「团队型暂只读」，现在点「召唤专家团」即可用。召唤时除了写入主理人预设，还会把每位成员的人设各自落成一份本地文件（`~/.dsh/wb-market/experts/teams/<专家>/`），送还时整体清除',
+        where: '专家 → 任一标注「专家团」的卡片',
+      },
+      {
+        text: '团队主理人会**按编制自动调度成员**：WorkBuddy 的团队人设原本依赖 `TeamCreate` 与 `Agent(name=…)` 两个 DSH 没有的工具。现在召唤时会往主理人人设末尾追加一段运行时适配，把这两类指令映射成 DSH 的 `subagent`（成员人设先 read 出来拼进 prompt），并保留「不得代写成员产出、成员之间不直连」等原始铁律',
+        where: '专家 → 专家团详情弹层（「团队编制」区块会列出每位成员与职责）',
+      },
+      {
+        text: '成员人设**不计入系统提示**：5 份人设若全塞进预设，每一轮请求都要为它们白付上下文费。现在只落盘、由主理人调度时按需读取，预设里仍然只有主理人一份人设',
+        where: '—（实现细节，影响每轮 token 成本）',
+      },
+      {
+        text: '修复「工具裁缝对所有工具的检测数量全为 0」：那其实是筛选口径造成的错觉——表格默认开着「只看死工具」，屏幕上自然整列 0。现在**默认显示全部工具与真实调用次数**，零调用的行用底色标出；按钮改成「只看零调用（N）」按需开启，顶部常驻回显「显示 N/M 个工具」，不会再被读成「检测全坏」',
+        where: '工具裁缝标签页',
+      },
+    ],
+  },
+  {
+    version: '1.10.0',
+    items: [
+      {
+        text: '**英文界面真的能用了**：`t()` 框架从 1.9.x 起就写着「将来往字典合并译文即可，无需改调用点」，但字典实参一直是空的。现在填满 **720 条键**，覆盖源码里全部 685 条中文原文；语言按 `localStorage["dsh-armory.locale"]` → `navigator.language` → `zh-CN` 三级回落，宿主是英文的用户面板自动变英文。顺带修掉 `fmtInt` / `fmtTax` 把千分位写死 `en-US` 的问题',
+        where: '—（跟随宿主语言；想强制英文可设 localStorage 的 dsh-armory.locale）',
+      },
+      {
+        text: '**「明明选过仅侧栏入口，怎么又变回弹窗」根治了**：以前 `whatsNew.seen` 只存一个版本号字符串，升级后整个键被当作过期清掉，入口偏好位跟着一起归零。现在两个偏好各自结构化落盘（`whatsNew.state` / `updateHint.state`），读写都保留下旧裸键的回落（老用户升级不丢状态），升级后只有「弹窗展示」位随版本重置',
+        where: '更新提示弹窗 + 面板头部更新提示条',
+      },
+      {
+        text: '**连接诊断卡**：Server 详情页新增分区，直接列出这台服务器的连接状态（含会话槽）、会话复用数、空闲回收倒计时、上次回收耗时（超时标红）、配置是否已改动、同名项目冲突——数据来自早就注册、却从未被面板调用过的 `projectConnections`。状态不是 ready 时，卡片底部直接给「重连这台服务器」。按需拉一次不轮询，右上角可刷新',
+        where: 'MCP → 项目作用域 → 任一服务器详情',
+      },
+      {
+        text: '**teardown 残留看得见了**：先说明白一件事——**本插件不 spawn 任何 MCP 子进程**（`lib/` 里 `SIGTERM` / `SIGKILL` / `taskkill` 零命中），所以「插件自己按进程树 kill」在架构上不成立，那是宿主 mcp-client 的职责。这个版本做的是本侧可观测：记录 teardown 的耗时与结局（超过 5s 判卡住，只留最近 64 条、10 分钟过期），经既有的 `projectConnections` 行以 `teardown` 字段流出，**没有新增 RPC**；另附上游提案 `docs/host-proposal-mcp-teardown.md`',
+        where: '—（诊断数据见连接诊断卡的「上次回收」一行）',
+      },
+      {
+        text: '**导入带 `${input:xxx}` 的 VS Code 配置不再整份失败**：以前只要有一条引用交互输入，整份文件拒绝导入。现在逐条降级——`url` / `command` / `cwd` 这类核心字段含 input 的条目进「不支持」分组并附原因（去掉等于发明一个猜的值，属静默错误），而 `env.*` / `headers.*` / `args` 元素含 input 的只剔该项并给 warning，条目仍可导入。预览弹层按「可导入 / 不支持」分组呈现',
+        where: 'MCP → 导入 → 扫描来源（VS Code 配置）',
+      },
+      {
+        text: '**工具裁缝三处改善**：① 时间窗新增「今日」档，调参后看当天效果不用再切到 7 天；② Node < 22.15 时 zstd 统计全 0 会被误读成「没有调用」，现在这些数字渲染成 `—`（数据缺失），与真实 0 区分开；③ 面板新增「缓存占用：x MB / 32 条」一行，配「清空账本缓存」按钮，清完直接用返回报告刷新、不额外扫一遍',
+        where: '工具裁缝标签页',
+      },
+      {
+        text: '**专家详情不再只给看 4000 字**：persona 截断处加「展开全文（N 字符）/ 收起」，魔法数字提为 `PERSONA_PREVIEW_MAX`（已召唤 / 市场两个弹层都覆盖）；quickPrompts 超过 3 条给「显示全部 N 条 / 收起」；卡片描述 48 字截断处补 `title`，悬停可看全文',
+        where: '专家 → 任一专家详情弹层',
+      },
+      {
+        text: '**认证方式有徽章、分页能跳页、只读看板说明白了**：① 内置 MCP 目录早就带 `auth` / `authNote` 元数据，现在按类型给色——需交互授权的（OAuth / OAuth-or-PAT）用警示色，只需填 key 的中性色，`none` 不占位；这两个字段只是展示元数据，绝不写进用户配置。② 三处分页统一改用同一个 `Pager` 组件，带首页/末页 + 页码跳转 + 「第 x / y 页 · 共 N 项」常驻计数。③ 技能看板顶部直接写明只读：宿主只提供 `listSkills` / `skillDetail`，要改内容请编辑 `SKILL.md`',
+        where: 'MCP → 内置目录 / 市场连接器 / 市场技能；技能标签页',
+      },
+      {
+        text: '**通用体验四件**：① 首屏数据未到时给轻骨架（`prefers-reduced-motion` 下停用 shimmer），不再「空白半秒像卡死」；② `FAB_SIZE` / `FAB_EDGE` 提到 CSS 之前并用插值，消除「改一处忘一处」；③ 9 处 `role="dialog"` 统一走 `useFocusTrap`——打开聚焦首个可交互元素、Tab 在框内循环、关闭时焦点还原到触发元素；④ 崩溃面板除 retry 外新增「复制错误详情」（`error.stack` + `componentStack` + 时间与 locale 组装入剪贴板），降低回报成本',
+        where: '—（面板任意位置；崩溃面板见出错时）',
+      },
+      {
+        text: '**测试从 13 个套件加到 18 个**，把「注释里承诺过、但没测试守得住」的契约都钉死：契约三处一致性、导入源降级结构、i18n 覆盖率双向差集（英文界面上冒中文正是这个缺口）、persona 阈值、裁缝默认窗口、崩溃详情可复制、teardown 残留诊断。每个套件都内置反向自测，证明断言不是恒真',
+        where: '—（开发者视角：`npm test`）',
+      },
+    ],
+  },
 ]