dsh-armory 1.9.2 → 1.9.4

package/lib/expert-market.js

@@ -27,9 +27,9 @@
 //   - 技能落盘目标与 SkillHub 技能同一发现范围 ~/.agents/skills/，目录名带 wbexpert__ 前缀
 //     防与其它来源撞名；本地缓存复制整树，CDN 兜底只写 SKILL.md 并如实标注。
 //   - patch 写入用 yaml 文档 API（与 mcp-config.js 同款 !!js 标量约定），保留其余条目与注释。
-import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, join, resolve, sep } from "node:path";
+import { basename, join } from "node:path";
 import { parseDocument, Scalar, YAMLMap, YAMLSeq, isMap, isSeq } from "yaml";
 
 const EXPERT_ORIGIN = "https://acc-1258344699.cos.accelerate.myqcloud.com/workbuddy/expert-marketplace";
@@ -60,6 +60,14 @@ function skillsRoot() {
 function workbuddyExpertCache() {
   return join(homedir(), ".workbuddy", "plugins", "cache", "experts");
 }
+// 团队专家：主理人 + N 个成员，每人一份人设。成员人设不塞进 preset（会白白撑大每轮
+// 系统提示），而是落盘成独立 md，由主理人调度时按需 read 进 subagent 的 prompt。
+function teamMemberDir(plugin) {
+  return join(cacheDir(), "teams", safeSegment(plugin));
+}
+function teamMemberPersonaPath(plugin, memberId) {
+  return join(teamMemberDir(plugin), `${safeSegment(memberId)}.md`);
+}
 function safeSegment(value) {
   // 目录名防穿越：只留安全字符，与 wb-market.js 的 skillTargetName 同一纪律。
   const safe = String(value).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
@@ -143,15 +151,33 @@ async function loadManifest() {
 function bi(value) {
   return value && typeof value === "object" ? String(value.zh || value.en || "") : String(value || "");
 }
+function biMember(value) {
+  return value && typeof value === "object" ? String(value.zh || value.en || "") : String(value || "");
+}
+/** 团队编制里的一行：成员 ID / 花名 / 职业 / 角色 / 人设文件名。 */
+function projectMember(member) {
+  const id = String(member?.id || "").trim();
+  if (!id) return null;
+  return {
+    id,
+    name: biMember(member.displayName || member.name),
+    profession: biMember(member.profession),
+    role: String(member.role || "member"),
+    promptFile: String(member.promptFile || ""),
+    avatar: String(member.avatar || ""),
+  };
+}
 function projectExpert(entry, categoryById) {
   const plugin = String(entry.plugin || "").trim();
   if (!plugin) return null;
   const category = categoryById.get(entry.categoryId);
+  const members = Array.isArray(entry.members) ? entry.members.map(projectMember).filter(Boolean) : [];
   return {
     id: String(entry.id || plugin),
     plugin,
     agentName: String(entry.agentName || ""),
     expertType: entry.expertType === "team" ? "team" : "agent",
+    members,
     name: bi(entry.displayName) || plugin,
     profession: bi(entry.profession),
     description: bi(entry.description),
@@ -298,6 +324,120 @@ export async function installExpertSkills(plugin, skillNames, { onLog } = {}) {
   }
   return { installed, notes };
 }
+// ── 团队专家：成员人设落盘（召唤时执行，送还时整体清除）─────────────────
+async function localMemberPersona(plugin, memberId) {
+  for (const version of await localExpertVersions(plugin)) {
+    const candidate = join(version.dir, "agents", `${memberId}.md`);
+    try {
+      const text = await readFile(candidate, "utf8");
+      if (text.trim()) return text;
+    } catch { /* 该版本没有这个成员 */ }
+  }
+  return null;
+}
+async function readMemberPersona(plugin, member) {
+  const local = await localMemberPersona(plugin, member.id);
+  if (local) return { text: local, source: "workbuddy-cache" };
+  const promptFile = String(member.promptFile || `/plugins/${plugin}/agents/${member.id}.md`).trim();
+  const text = await fetchText(EXPERT_ORIGIN + promptFile);
+  if (!text.trim()) throw new Error("人设文件为空");
+  return { text, source: "cdn" };
+}
+/**
+ * 把团队成员的独立人设写成本机 md（不进 preset：5 份人设塞进系统提示会按轮计费）。
+ * 主理人调度时先 read 出来再拼进 subagent 的 prompt，语义等同 WorkBuddy 的独立协作方。
+ * @returns {Promise<{installed: Array, notes: string[], dir: string}>}
+ */
+export async function installTeamMemberPersonas(plugin, members, { onLog } = {}) {
+  const installed = [];
+  const notes = [];
+  const dir = teamMemberDir(plugin);
+  for (const member of Array.isArray(members) ? members : []) {
+    // 主理人人设本身就是召唤预设的 persona，不需要再落一份。
+    if (member.role === "lead") continue;
+    try {
+      const { text, source } = await readMemberPersona(plugin, member);
+      await mkdir(dir, { recursive: true });
+      const path = teamMemberPersonaPath(plugin, member.id);
+      await writeFile(path, text);
+      installed.push({ id: member.id, name: member.name, profession: member.profession, path, source });
+      onLog?.(`团队成员 ${member.name || member.id}：人设已落盘（${source}）`);
+    } catch (error) {
+      notes.push(`团队成员 ${member.name || member.id} 人设获取失败：${error.message}`);
+    }
+  }
+  return { installed, notes, dir };
+}
+export async function uninstallTeamMemberPersonas(plugin) {
+  const dir = teamMemberDir(plugin);
+  try {
+    await rm(dir, { recursive: true, force: true });
+    return dir;
+  } catch {
+    return null;
+  }
+}
+/**
+ * DSH 运行时桥接段：WorkBuddy 团队人设里的 TeamCreate / Agent(name, subagent_type)
+ * 在 DSH 里不存在，这里给出等价映射。追加在主理人人设末尾，只在召唤时拼一次。
+ * @param {object} detail wbExpertDetail 的返回值
+ * @param {Map<string,string>} personaFiles 成员 ID → 已落盘的人设路径（未落盘则不传）
+ */
+// 桥接段的唯一识别标记：readExpertPresets 靠它在召唤预设的人设正文里判断
+// 「这条团队预设带没带桥接段」。旧版本召唤写入的团队预设没有这段——那种预设下的
+// 会话主理人会去调不存在的 TeamCreate / Agent，成员永远开不出来（用户实测症状）。
+export const TEAM_BRIDGE_MARKER = "## DSH 运行时适配（团队协作桥接）";
+/** 团队人设正文是否已带桥接段（用于现存召唤预设行的 stale 体检）。 */
+export function hasTeamBridge(personaText) {
+  return typeof personaText === "string" && personaText.includes(TEAM_BRIDGE_MARKER);
+}
+export function buildTeamBridge(detail, personaFiles) {
+  const members = Array.isArray(detail?.members) ? detail.members : [];
+  const others = members.filter((member) => member.role !== "lead");
+  if (!others.length) return "";
+  const rows = others.map((member) => {
+    const file = personaFiles?.get(member.id);
+    return `| \`${member.id}\` | ${member.name || "-"} | ${member.profession || "-"} | ${file ? `\`${file}\`` : "（人设未落盘，按职责执行）"} |`;
+  });
+  return [
+    "",
+    "---",
+    "",
+    "## DSH 运行时适配（团队协作桥接）",
+    "",
+    "本会话运行在 DSH 上，**没有 WorkBuddy 的 `TeamCreate` 与 `Agent` 工具**。团队编制已在召唤时固定，因此上文里「建立团队」「Agent 工具 name/subagent_type」两类指令按下面的等价方式执行；其余铁律（不得代写成员产出、成员之间不直连、一切经你中转）保持不变。",
+    "",
+    "1. **建团队 → 无需调用**：本会话即本团队，成员固定如下表，不需要创建、也不需要命名。",
+    "2. **调度成员 → `subagent` 工具**：",
+    "   - `description`：`<成员ID>：<阶段产出名>`，例如 `software-architect：系统设计与任务分解`。",
+    "   - `prompt`：先用 `read` 读出该成员的人设文件（下表最后一列），把**人设正文原文**放在 prompt 最前面，接一行 `---`，再往下写本次任务、上游产出、期望交付物与验收标准。",
+    "   - 顺序 SOP（PRD → 架构 → 实现 → QA）**必须**传 `run_in_background: false`，当场等它返回再往下走；只有互不依赖的并行任务才留默认后台模式。",
+    "3. **成员产出**：子代理的最终回复就是该成员的专业产出，原文转交下一阶段，不要改写、不要替它编。",
+    "4. **续聊追问**：需要同一成员接着干活时，用 `send_message` 继续它的会话 id，不要重新 spawn 一个同名成员。",
+    "5. **上下文继承**：`subagent` 是干净上下文（更接近 WorkBuddy 的独立协作方）；只有确实需要它继承你当前会话上下文时才用 `subagent_fork`。",
+    "",
+    "### 团队编制",
+    "",
+    "| 成员 ID | 花名 | 职责 | 人设文件 |",
+    "| --- | --- | --- | --- |",
+    ...rows,
+    "",
+  ].join("\n");
+}
+/**
+ * 把「详情」变成真正可用的会话人设：单人专家原样返回，团队专家先落成员人设、
+ * 再在末尾追加 DSH 桥接段。召唤预设与会话级挂载走同一条路径，保证两个入口一致。
+ * @returns {Promise<{personaText: string, memberResult: object|null}>}
+ */
+export async function prepareExpertPersona(detail, { onLog, withMembers = true } = {}) {
+  if (detail?.expertType !== "team") return { personaText: detail?.persona || "", memberResult: null };
+  let memberResult = { installed: [], notes: [], dir: teamMemberDir(detail.plugin) };
+  if (withMembers) {
+    memberResult = await installTeamMemberPersonas(detail.plugin, detail.members, { onLog });
+  }
+  const files = new Map((memberResult.installed || []).map((row) => [row.id, row.path]));
+  return { personaText: `${detail.persona}${buildTeamBridge(detail, files)}`, memberResult };
+}
 export async function uninstallExpertSkills(plugin) {
   const root = skillsRoot();
   let names = [];
@@ -390,7 +530,20 @@ export function readExpertPresets(content) {
     const config = entry.get("config", true);
     const presetId = String(mapValue(config, "id") || "");
     if (!presetId.startsWith(EXPERT_PRESET_PREFIX)) continue;
-    rows.push({ presetId: String(mapValue(entry, "id")), plugin: presetId.slice(EXPERT_PRESET_PREFIX.length) });
+    // 带出人设正文（plugins[0] 的人设插件的 config.prefix），供 stale 体检：
+    // 旧版本召唤写入的团队预设没有桥接段，读出来后前端能标「需更新」。
+    let personaText = null;
+    const plugins = config.get("plugins", true);
+    if (isSeq(plugins) && plugins.items.length > 0 && isMap(plugins.items[0])) {
+      const personaConfig = plugins.items[0].get("config", true);
+      const prefix = personaConfig ? personaConfig.get("prefix", true) : null;
+      if (prefix && typeof prefix.value === "string") personaText = prefix.value;
+    }
+    rows.push({
+      presetId: String(mapValue(entry, "id")),
+      plugin: presetId.slice(EXPERT_PRESET_PREFIX.length),
+      personaText,
+    });
   }
   return rows;
 }
@@ -578,8 +731,9 @@ export function removeExpertPreset(content, plugin) {
 // 持久化在 ~/.dsh/wb-market/experts/recent.json：三类各存一份轻量记录
 // （skill: 技能名+来源目录名；mcp: serverName+作用域；expert: plugin+召唤预设名）。
 // 只在「可观察的使用动作」发生时写入：召唤/送还专家、召唤菜单里选中一项（由客户端
-// 显式上报）。上限各 8 条，新的顶到最前，去重按主键。文件损坏静默重置（纯增值数据）。
-const RECENT_LIMIT = 8;
+// 显式上报）。上限各 40 条（召唤菜单每屏 6 行 + 滚动，排序需要较深的最近记录池），
+// 新的顶到最前，去重按主键。文件损坏静默重置（纯增值数据）。
+const RECENT_LIMIT = 40;
 function recentPath() {
   return join(cacheDir(), "recent.json");
 }
@@ -596,7 +750,22 @@ async function readRecentRaw() {
 }
 async function writeRecentRaw(data) {
   await mkdir(cacheDir(), { recursive: true });
-  await writeFile(recentPath(), JSON.stringify(data, null, 1));
+  // OPT-08：原子写。直接覆盖写若中途断电/被杀，会留下截断的 JSON——readRecentRaw
+  // 虽然会静默重置（只丢「最近使用」排序、不至于崩），但没必要留着这个窗口。
+  //
+  // 这里刻意用「临时文件 + rename」而不引 @deepseek-ai/dsh-atomic-write：那是宿主提供的
+  // peer 依赖，本包 node_modules 里没有它，而 expert-market.js 会被 test/expert-manual.mjs
+  // 直接 import —— 加静态导入会让本地测试当场 ERR_MODULE_NOT_FOUND。
+  // 同目录 rename 在同一文件系统内是原子操作，足够。
+  const target = recentPath();
+  const tmp = `${target}.${process.pid}.${Date.now().toString(36)}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(data, null, 1));
+    await rename(tmp, target);
+  } catch (e) {
+    await rm(tmp, { force: true }).catch(() => {});
+    throw e;
+  }
 }
 /** 记录一次使用。row 携带菜单展示所需的最小字段；kind ∈ skill|mcp|expert。 */
 export async function recordExpertRecent(kind, row) {

package/lib/index.js

@@ -13,8 +13,8 @@ import { collectImportLocations, missingEnvNames, resolveImportLocation } from "
 import { deriveMcpPhase, formatMcpLog, sanitizeMcpLog } from "./mcp-observability.js";
 import { allMcpEntries, entriesForName, projectToolSchema, revisionOf, toolInventory } from "./mcp-registry.js";
 import { WHATS_NEW } from "./whats-new.js";
-import { wbConnectorCatalog, wbConnectorPreview, wbSkillCatalog, wbSkillDetail, wbSkillFiles, wbSkillInstall, wbSkillInstalled, wbSkillUninstall } from "./wb-market.js";
-import { installExpertSkills, listExpertRecent, listExpertSkills, readExpertPresets, recordExpertRecent, removeExpertPreset, uninstallExpertSkills, wbExpertCatalog, wbExpertDetail, writeExpertPreset } from "./expert-market.js";
+import { wbConnectorCatalog, wbConnectorPreview, wbSkillCatalog, wbSkillDetail, wbSkillInstall, wbSkillInstalled, wbSkillUninstall } from "./wb-market.js";
+import { hasTeamBridge, installExpertSkills, listExpertRecent, listExpertSkills, prepareExpertPersona, readExpertPresets, recordExpertRecent, removeExpertPreset, uninstallExpertSkills, uninstallTeamMemberPersonas, wbExpertCatalog, wbExpertDetail, writeExpertPreset } from "./expert-market.js";
 import { attachPersona, detachPersona, listPersonas, reconcilePersonas } from "./session-persona.js";
 import { scanSessionLedger } from "./tool-ledger.js";
 import { evaluateEnvExpression, jsExpressionToTemplate } from "./workspace-config.js";
@@ -1470,13 +1470,23 @@ let McpManagerGateway = (() => {
 		if (!sessionId) throw new Error("缺少 sessionId");
 		if (!plugin) throw new Error("缺少 plugin");
 		const detail = await wbExpertDetail({ plugin });
+		// 团队型：成员人设先落盘，主理人人设末尾追加 DSH 桥接段（与召唤预设同一套）。
+		const prepared = await prepareExpertPersona(detail, {
+			onLog: (message) => this.ctx.logger?.debug?.(`wb-expert: ${message}`),
+		});
 		const result = attachPersona(this.ctx, sessionId, {
 			plugin,
 			name: detail.name,
-			personaText: detail.persona,
+			personaText: prepared.personaText,
 		});
 		await recordExpertRecent("expert", { plugin, name: detail.name, profession: detail.profession, presetId: `session-${plugin}` }).catch(() => {});
-		return { ...result, profession: detail.profession };
+		return {
+			...result,
+			profession: detail.profession,
+			expertType: detail.expertType,
+			members: detail.members || [],
+			memberNotes: prepared.memberResult?.notes || [],
+		};
 	}
 	async expertDetach(payload) {
 		const sessionId = String(payload?.sessionId || "").trim();
@@ -1499,6 +1509,10 @@ let McpManagerGateway = (() => {
 		// 详情即预览：召唤写盘前拉一次真实人设与技能清单，失败则整体不动。
 		const detail = await wbExpertDetail({ plugin });
 		const withSkills = payload?.withSkills !== false && detail.skills.length > 0;
+		// 团队型：成员人设先落盘（人设不进 preset，避免每轮白付），主理人人设追加桥接段。
+		const prepared = await prepareExpertPersona(detail, {
+			onLog: (message) => this.ctx.logger?.debug?.(`wb-expert: ${message}`),
+		});
 		// 技能先落盘（失败只影响技能，不阻断召唤），预设行再走唯一写链（文件锁 + 版本校验 + 原子写）。
 		let skillResult = { installed: [], notes: [] };
 		if (withSkills) {
@@ -1513,7 +1527,7 @@ let McpManagerGateway = (() => {
 				displayName: detail.name,
 				profession: detail.profession,
 				description: detail.description,
-				personaText: detail.persona,
+				personaText: prepared.personaText,
 			});
 			if (written.content === state.content) return { mode: "unchanged", presetId: written.presetId };
 			await writePatch(state, written.content);
@@ -1521,14 +1535,26 @@ let McpManagerGateway = (() => {
 		});
 		// 召唤成功即记入最近使用（送还由 listExpertRecent 对账剔除）。记录失败不阻断召唤。
 		await recordExpertRecent("expert", { plugin, name: detail.name, profession: detail.profession, presetId: result.presetId }).catch(() => {});
+		const teamMembers = prepared.memberResult?.installed || [];
+		// upsert 后核对人设正文是否真带桥接段（团队型）；不带则提示更新结果不完整。
+		// 正常路径 prepared.personaText 已拼桥接段，这个分支只在异常数据时触发。
+		const staleBridge = detail.expertType === "team" && !hasTeamBridge(prepared.personaText);
 		return {
 			presetId: result.presetId,
 			presetMode: result.mode,
+			expertType: detail.expertType,
+			members: detail.members || [],
 			summonedSkills: skillResult.installed,
 			skillNotes: skillResult.notes,
+			summonedMembers: teamMembers,
+			memberNotes: prepared.memberResult?.notes || [],
+			staleBridge,
 			note: `已召唤「${detail.name}」：新会话选择预设「WorkBuddy 专家 · ${detail.name}」即专家人设接管`
+				+ (result.mode === "unchanged" ? "（预设已是最新，未改动）" : "")
+				+ (result.mode === "updated" ? "（旧预设行已刷新为人设最新版）" : "")
+				+ (teamMembers.length ? `；团队成员人设 ${teamMembers.length} 份已落盘，主理人按编制用 subagent 调度` : "")
 				+ (skillResult.installed.length ? `；捆绑技能 ${skillResult.installed.length} 个已装进 ~/.agents/skills/` : "")
-				+ (skillResult.notes.length ? `；注意：${skillResult.notes.join("；")}` : ""),
+				+ ([...(prepared.memberResult?.notes || []), ...skillResult.notes].length ? `；注意：${[...(prepared.memberResult?.notes || []), ...skillResult.notes].join("；")}` : ""),
 		};
 	}
 	async wbExpertDismiss(payload) {
@@ -1548,17 +1574,29 @@ let McpManagerGateway = (() => {
 		} catch (error) {
 			this.ctx.logger?.warn?.(`wb-expert: 预设已摘除，但技能清理失败：${error?.message ?? error}`);
 		}
-		if (result.mode === "absent" && !removedSkills.length) throw new Error("本机没有召唤过这个专家（profile patch 里没有对应预设行）");
+		// 团队型：成员人设目录同样按 plugin 隔离，一并清除。
+		let removedTeam = null;
+		try {
+			removedTeam = await uninstallTeamMemberPersonas(plugin);
+		} catch (error) {
+			this.ctx.logger?.warn?.(`wb-expert: 预设已摘除，但成员人设清理失败：${error?.message ?? error}`);
+		}
+		if (result.mode === "absent" && !removedSkills.length && !removedTeam) throw new Error("本机没有召唤过这个专家（profile patch 里没有对应预设行）");
 		return {
 			removedSkills,
+			removedTeam,
 			note: `已送还「${plugin}」`
 				+ (result.mode === "removed" ? "：召唤预设已从 profile patch 摘除（热加载，无需重启）" : "：本没有召唤预设")
-				+ (removedSkills.length ? `；捆绑技能已清理 ${removedSkills.length} 个目录` : ""),
+				+ (removedSkills.length ? `；捆绑技能已清理 ${removedSkills.length} 个目录` : "")
+				+ (removedTeam ? "；团队成员人设已清理" : ""),
 		};
 	}
 	async wbExpertInstalled() {
 		// 已召唤 = profile patch 里的召唤预设行；已装技能 = ~/.agents/skills 的 wbexpert__ 目录。
 		// patch 读走与 managedState 同一条解析（readPatch），但不持写锁——只读快照。
+		// 团队行做 stale 体检：人设正文缺桥接段 = 旧版本召唤写入的行，新会话选它会调
+		// 不存在的 TeamCreate/Agent（成员开不出来）。标记桥接判定放前端（需要市场目录的
+		// expertType），这里只把 personaText 原样带出去。
 		const patch = await readPatch(this.ctx);
 		return { presets: readExpertPresets(patch.content), skills: await listExpertSkills() };
 	}

package/lib/mcp-config.js

@@ -387,6 +387,10 @@ function makeEntry(doc, spec, id = `mcp-${spec.name}`) {
 function parsePatch(content) {
   const doc = parseDocument(content || '')
   if (doc.errors.length) throw new Error(`MCP patch YAML 无法解析：${doc.errors[0].message}`)
+  // 0 字节的文件、只有注释的文件，解析出来是 `contents: null` 而 errors 是 0 条——语法上
+  // 完全合法。以前这里直接报「必须是 YAML 列表」，于是 `managedState` 整块失败、MCP 面板
+  // 全白，而用户手上的文件根本没有写错。补一个空 seq 就能继续；String(doc) 会原样保留注释。
+  if (doc.contents === null) doc.contents = new YAMLSeq()
   if (!isSeq(doc.contents)) throw new Error('MCP patch 必须是 YAML 列表')
   return doc
 }

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;
@@ -160,32 +248,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")) {
@@ -314,9 +405,15 @@ 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,
 		totalCalls,
 		totalResults,
 		totalErrors,

package/lib/whats-new.js

@@ -242,4 +242,50 @@ export const WHATS_NEW = [
       },
     ],
   },
+  {
+    version: '1.9.3',
+    items: [
+      {
+        text: '召唤菜单的「技能 / MCP / 专家」子菜单升级为**全量列表 + 滚动浏览**：每屏固定显示 6 行，超出的往下滚（细滚动条跟随主题）；「管理技能/MCP/专家…」按钮固定在底部，不再被列表滚走。以前每类只列前 6 条，第 7 个技能在菜单里根本找不到',
+        where: '会话输入框工具行右侧的看板小图标',
+      },
+      {
+        text: '子菜单按**最近使用**排序：你刚用过的条目自动置顶并带「最近」标记（首屏 6 个），其余按原有顺序排在后面。最近使用记录池从 8 条加深到 40 条，排序更贴合真实使用习惯',
+        where: '召唤菜单 → 技能 / MCP / 专家',
+      },
+      {
+        text: '修复「换了专家，会话最上方还显示第一个专家」：会话头那条**预设标签**读的是会话创建时的事实、换专家不会变（宿主只读）。现在挂上专家后它会自动让位，改由一枚显示**当前真正生效**专家的徽章接管，并随换随新',
+        where: '会话标题栏（挂专家后）',
+      },
+      {
+        text: '修复专家显示的「三名不一致」：以前预设标签、输入框 chip、会话头三处各查一次状态，换完专家要等重挂才刷新。现在挂/换/摘后立即同帧同步，另有 5 秒兜底对账（覆盖从预设选择器等别的入口挂上的专家）',
+        where: '会话标题栏 + 输入框专家 chip',
+      },
+      {
+        text: '专家挂载不再走「预设通道」：那条路会在会话投影里写下一个**永不更新**的专家名，是上面那个「顶栏显示 A、实际生效 B」的根因。现在统一走会话级人设通道——随时挂/换/摘，显示与实效从此一致',
+        where: '召唤菜单 → 专家',
+      },
+    ],
+  },
+  {
+    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: '工具裁缝标签页',
+      },
+    ],
+  },
 ]

package/lib/workspace-runtime.js

@@ -1156,7 +1156,9 @@ function installAgentRuntime(ctx) {
 	};
 	// 生命周期归属先建立、再订阅事件：反过来的话，effect() 抛出（fiber 已 inactive）就会留下一个
 	// 被死插件永久持有的监听器，而且再也没有重新安装的机会。
-	const owner = ctx.effect(() => () => cleanup(), "mcp-manager.agentRuntime");
+	// 不接 ctx.effect 的返回值：cleanup 由 fiber 持有，本函数另外把同一个 cleanup 交回给
+	// 调用方（末尾 return cleanup），两个入口都幂等，没必要再存一份 disposer。
+	ctx.effect(() => () => cleanup(), "mcp-manager.agentRuntime");
 	activeGenerationByRoot.set(appRoot(ctx), generation);
 	try {
 		disposeAgentCreated = ctx.on("agent/created", async (payload) => {