@stofone/dsh-agent-roster 0.6.1 → 0.7.0

package/lib/digest.js

@@ -0,0 +1,65 @@
+/**
+ * 摘要工具：把"看不见的东西"变成可以比对的一行字。
+ *
+ * 两个用途，都是 issue #2 暴露出来的盲区：
+ * - **档案文件内容**：团队状态里没有"由哪一版档案建成"的字段，只能把文件内容的 sha256
+ *   写进 `agent_teams_create` 的 description（溯源串），下次核对比的是同一份字节。
+ * - **物化后的工具策略**：`team.json` 里除了 `toolPolicy` 这个 id，还存了策略被展开成工具名
+ *   之后的 `toolFilter` {@code {deny:[…]}}。只比 id 会在"部署侧改了策略定义"时永远绿，
+ *   所以要比这一坨工具名的规范化摘要。
+ *
+ * 规范化一律按"排序 + JSON.stringify"：键序与元素顺序不同不算变化，否则每次重排都会假报漂移。
+ *
+ * @module dsh-agent-roster/digest
+ */
+import { createHash } from "node:crypto";
+
+/**
+ * 计算文本的 sha256 十六进制摘要。
+ *
+ * @param {string | Uint8Array} input
+ * @returns {string} 64 位小写十六进制
+ */
+export function sha256Hex(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * 取摘要前 8 位：打印、写进 description 时用短的，避免把一行文字撑得太长。
+ *
+ * @param {string | null | undefined} hex
+ * @returns {string}
+ */
+export function shortSha(hex) {
+  return typeof hex === "string" && hex !== "" ? hex.slice(0, 8) : "";
+}
+
+/**
+ * 把一个成员的工具过滤器折叠成"可比较的形状"。
+ *
+ * 缺失、非对象、字段类型不对时返回 `null`——读不到就是读不到，不编一个空摘要出来，
+ * 否则"没有 toolFilter"会被伪装成"toolFilter 与别人一致"。
+ *
+ * @param {unknown} toolFilter `team.json` 成员的 `toolFilter`
+ * @returns {{ deny: number, allow: number, sha: string } | null}
+ */
+export function toolFilterDigest(toolFilter) {
+  if (toolFilter === null || typeof toolFilter !== "object" || Array.isArray(toolFilter)) return null;
+  const deny = namesOf(toolFilter.deny);
+  const allow = namesOf(toolFilter.allow);
+  if (deny === null && allow === null) return null;
+  const canonical = JSON.stringify({ allow: allow ?? [], deny: deny ?? [] });
+  return { deny: (deny ?? []).length, allow: (allow ?? []).length, sha: shortSha(sha256Hex(canonical)) };
+}
+
+/**
+ * 取出字符串数组并排序去重；不是数组时返回 `null`，让调用方区分"空"与"没有这个键"。
+ *
+ * @param {unknown} value
+ * @returns {string[] | null}
+ */
+function namesOf(value) {
+  if (!Array.isArray(value)) return null;
+  const names = value.filter((item) => typeof item === "string" && item !== "");
+  return [...new Set(names)].sort();
+}

package/lib/library.js

@@ -8,6 +8,7 @@
  * @module dsh-agent-roster/library
  */
 import { displayDshHome, isGlobalDirSpec, resolveDshHome, resolveDirSpec } from "./home.js";
+import { capabilityDiagnostics } from "./capabilities.js";
 import { scanRosterLibrary } from "./registry.js";
 
 /**
@@ -46,6 +47,10 @@ export function collectLibrary(ctx, config, meta) {
         rootDir,
         knownToolPolicies: config.knownToolPolicies ?? null,
       });
+      // 能力要求的面板侧诊断：能同步判定的（策略）落到严重度上，判不了的（技能）如实标成不判定。
+      scan.diagnostics.push(
+        ...capabilityDiagnostics(scan.capabilities ?? {}, scan.capabilityFiles ?? {}, config.knownToolPolicies ?? null),
+      );
       reports.push({
         ...target,
         dirSpec,

package/lib/registry.js

@@ -24,6 +24,8 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import nodePath from "node:path";
 
+import { CAPABILITIES_FILE_NAMES, validateCapabilities } from "./capabilities.js";
+import { sha256Hex } from "./digest.js";
 import { MEMBER_FILE_NAMES } from "./format.js";
 import { parseDocumentText } from "./parse.js";
 import { validateRoster } from "./validate.js";
@@ -51,6 +53,10 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
   const diagnostics = [];
   const entries = [];
   const rosters = [];
+  /** 档案 id → 能力要求（`capabilities.yaml` 的解析结果）。 */
+  const capabilities = {};
+  /** 档案 id → 能力要求的文件名（诊断要指到具体那份文件）。 */
+  const capabilityFiles = {};
   const stats = {
     total: 0,
     ok: 0,
@@ -97,7 +103,15 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
       }
 
       stats.total += 1;
-      const entry = { id: child.name, file: found.relative, roster: null };
+      const entry = { id: child.name, file: found.relative, roster: null, capabilities: null };
+      // 能力要求与档案分开加载：档案写错了不该顺带把"缺能力"这条信息也藏起来。
+      const wanted = loadCapabilities(dirPath, child.name);
+      diagnostics.push(...wanted.diagnostics);
+      if (wanted.capabilities !== null) {
+        entry.capabilities = wanted.capabilities;
+        capabilities[child.name] = wanted.capabilities;
+        capabilityFiles[child.name] = wanted.file;
+      }
       const outcome = loadDocument(found, child.name, { knownToolPolicies });
       diagnostics.push(...outcome.diagnostics);
       if (outcome.ok) {
@@ -151,7 +165,7 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
       String(left.file ?? "").localeCompare(String(right.file ?? "")),
   );
 
-  return { rootDir, missing: childDirs === null, entries, rosters, stats, diagnostics };
+  return { rootDir, missing: childDirs === null, entries, rosters, capabilities, capabilityFiles, stats, diagnostics };
 }
 
 /**
@@ -219,10 +233,10 @@ function locateDocument(dirPath, dirName, diagnostics) {
  * @param {{ knownToolPolicies: string[] | null }} options
  * @returns {{ ok: boolean, roster: object | null, diagnostics: object[] }}
  */
-function loadDocument(found, expectedId, { knownToolPolicies }) {
+function loadDocument(found, expectedId, { knownToolPolicies }, rawText = null) {
   let raw;
   try {
-    raw = readFileSync(found.absolute, "utf8");
+    raw = rawText === null ? readFileSync(found.absolute, "utf8") : rawText;
   } catch (error) {
     return {
       ok: false,
@@ -256,6 +270,115 @@ function loadDocument(found, expectedId, { knownToolPolicies }) {
   };
 }
 
+/**
+ * 读取档案目录里的能力要求兄弟文件（`capabilities.yaml|yml|json`）。
+ *
+ * 文件不存在是**正常状态**：没写能力要求就是不设要求，不产生任何诊断。
+ * 文件存在但校验不过时才记 error——那时档案本身仍然是好的，缺的是"要求"这份文档。
+ *
+ * @param {string} dirPath 档案目录
+ * @param {string} dirName 目录名（同时也是期望的 `roster` 字段）
+ * @returns {{ capabilities: object | null, file: string | null, diagnostics: object[] }}
+ */
+export function loadCapabilities(dirPath, dirName) {
+  let names;
+  try {
+    names = readdirSync(dirPath);
+  } catch {
+    return { capabilities: null, file: null, diagnostics: [] };
+  }
+  const present = CAPABILITIES_FILE_NAMES.filter((name) => names.includes(name));
+  if (present.length === 0) return { capabilities: null, file: null, diagnostics: [] };
+
+  const diagnostics = [];
+  const relative = `${dirName}/${present[0]}`;
+  if (present.length > 1) {
+    diagnostics.push({
+      severity: "warn",
+      code: "multiple-capabilities-files",
+      path: "",
+      file: relative,
+      reason:
+        `目录 "${dirName}" 同时存在 ${present.join("、")}，只读 ${present[0]}；` +
+        "请删掉多余文件，否则另一份永远不会生效。",
+    });
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(nodePath.join(dirPath, present[0]), "utf8");
+  } catch (error) {
+    diagnostics.push({
+      severity: "error",
+      code: "unreadable-file",
+      path: "",
+      file: relative,
+      reason: `文件不可读：${messageOf(error)}`,
+    });
+    return { capabilities: null, file: relative, diagnostics };
+  }
+
+  const format = present[0].endsWith(".json") ? "json" : "yaml";
+  const parsed = parseDocumentText(raw, { file: relative, format });
+  if (!parsed.ok) return { capabilities: null, file: relative, diagnostics: [...diagnostics, ...parsed.diagnostics] };
+
+  const validated = validateCapabilities(parsed.value, { file: relative, expectedId: dirName });
+  diagnostics.push(...validated.diagnostics);
+  if (!validated.ok) return { capabilities: null, file: relative, diagnostics };
+  return { capabilities: validated.capabilities, file: relative, diagnostics };
+}
+
+/**
+ * 从任意目录加载**一份**档案，并带出它的文件路径与内容哈希。
+ *
+ * 两个用途共用这一个入口：
+ * - 溯源串要把"档案文件内容的 sha256"写进团队 description（`roster:<id>@<version>#<sha8>`）；
+ * - 换代对比（`roster_diff`）要能收任意目录，而不是只有 `rosterDirs[0]`。
+ *
+ * 目录布局兼容两种：目录本身就是一个档案目录（里面有 `roster.yaml|yml|json`），
+ * 或者是一个档案库目录下的 `<id>/`。`expectedId` 传 `null` 表示"目录名不必等于档案 id"。
+ *
+ * @param {string} dirPath 档案目录的绝对路径
+ * @param {{ expectedId?: string | null, knownToolPolicies?: string[] | null }} [options]
+ * @returns {{ ok: boolean, roster: object | null, diagnostics: object[], file: string | null,
+ *   relative: string | null, contentSha: string | null }}
+ */
+export function loadRosterAt(dirPath, options = {}) {
+  const diagnostics = [];
+  const expectedId =
+    typeof options.expectedId === "string" && options.expectedId !== "" ? options.expectedId : null;
+  const dirName = expectedId ?? nodePath.basename(dirPath);
+  const found = locateDocument(dirPath, dirName, diagnostics);
+  if (found === null) return { ok: false, roster: null, diagnostics, file: null, relative: null, contentSha: null };
+
+  let raw;
+  try {
+    raw = readFileSync(found.absolute, "utf8");
+  } catch (error) {
+    diagnostics.push({
+      severity: "error",
+      code: "unreadable-file",
+      path: "",
+      file: found.relative,
+      reason: `文件不可读：${messageOf(error)}`,
+    });
+    return { ok: false, roster: null, diagnostics, file: found.absolute, relative: found.relative, contentSha: null };
+  }
+
+  const outcome = loadDocument(found, expectedId, { knownToolPolicies: options.knownToolPolicies ?? null }, raw);
+  const wanted = loadCapabilities(dirPath, dirName);
+  return {
+    ok: outcome.ok,
+    roster: outcome.roster,
+    capabilities: wanted.capabilities,
+    capabilitiesFile: wanted.file,
+    diagnostics: [...diagnostics, ...wanted.diagnostics, ...outcome.diagnostics],
+    file: found.absolute,
+    relative: found.relative,
+    contentSha: sha256Hex(raw),
+  };
+}
+
 /**
  * 定位一份档案或其中某个成员。
  *

package/lib/render.js

@@ -8,6 +8,44 @@
  */
 import { BINDING_STATUS, describeField, summarizeBinding } from "./bridge.js";
 import { LIMITS } from "./format.js";
+import { memberVerdict } from "./verify.js";
+
+
+/** 核对结论的人读标签。 */
+const VERDICT_LABEL = { faithful: "一致", unverified: "未核实", drift: "降级", missing: "未部署" };
+
+/**
+ * 一行工具过滤器摘要。`null` 表示 `team.json` 里没有物化后的 deny 列表——
+ * 那不是"一致"，只是读不到，所以照实写"无法核对"。
+ *
+ * @param {{ deny: number, allow: number, sha: string } | null} digest
+ * @returns {string}
+ */
+function toolFilterLine(digest) {
+  if (digest === null) return "   toolFilter  无法核对（team.json 没有物化后的 deny 列表）";
+  return `   toolFilter  deny ${digest.deny} · allow ${digest.allow} · sha ${digest.sha}`;
+}
+
+/**
+ * 一句人读的溯源结论。
+ *
+ * @param {object} item `verifyBindings` 的 provenance 项
+ * @returns {string}
+ */
+function provenanceText(item) {
+  switch (item.status) {
+    case "absent":
+      return "description 里没有溯源串（建团队时把 roster_create 给的那一行写进 description 才有出处）";
+    case "unknown-roster":
+      return `声明 ${item.declared}，但本机没有这份档案`;
+    case "id-only":
+      return `声明 ${item.declared}，没有内容哈希，只能核对 id 与版本`;
+    case "match":
+      return `${item.declared} · 与当前档案内容一致`;
+    default:
+      return `${item.declared} · 档案文件内容已变（当前 #${item.currentSha}）`;
+  }
+}
 
 /**
  * 诊断列表 → 文本块。错误在前、按文件分组，超出上限时明确写出省略了多少条。
@@ -210,9 +248,11 @@ export function renderVerifyReport(report, options = {}) {
   }
 
   for (const [key, group] of byRoster) {
-    const faithful = group.filter((check) => check.found && check.faithful).length;
     const found = group.filter((check) => check.found).length;
-    lines.push(`roster:${key}  成员 ${group.length} · 已部署 ${found} · 一致 ${faithful}`);
+    const faithful = group.filter((check) => memberVerdict(check) === "faithful").length;
+    const unverified = group.filter((check) => memberVerdict(check) === "unverified").length;
+    const suffix = unverified === 0 ? "" : ` · 未核实 ${unverified}`;
+    lines.push(`roster:${key}  成员 ${group.length} · 已部署 ${found} · 一致 ${faithful}${suffix}`);
     for (const check of group) {
       if (!check.found) {
         lines.push("");
@@ -220,11 +260,12 @@ export function renderVerifyReport(report, options = {}) {
         continue;
       }
       lines.push("");
-      const verdict = check.faithful ? "一致" : "降级";
-      lines.push(`▸ ${check.member}  @ ${check.teamName}   ${verdict}`);
+      const verdict = memberVerdict(check);
+      lines.push(`▸ ${check.member}  @ ${check.teamName}   ${VERDICT_LABEL[verdict]}`);
       if (typeof check.matchedAs === "string" && check.matchedAs !== check.member) {
         lines.push(`   （运行时以旧名 "${check.matchedAs}" 记录，来自 aliases）`);
       }
+      lines.push(toolFilterLine(check.toolFilter));
       for (const field of check.binding.fields) {
         if (field.status === "pending") continue;
         lines.push(`   ${describeField(field)}`);
@@ -232,7 +273,7 @@ export function renderVerifyReport(report, options = {}) {
       if (!check.faithful) {
         const summary = check.summary;
         lines.push(
-          `   → 降级字段：覆盖 ${summary.counts.overridden ?? 0} · 缺失 ${summary.counts.omitted ?? 0} · 无法核对 ${summary.counts.unconfirmed ?? 0}`,
+          `   → ${verdict === "unverified" ? "无法核对" : "降级"}字段：覆盖 ${summary.counts.overridden ?? 0} · 未留痕 ${summary.counts["not-persisted"] ?? 0} · 未声明 ${summary.counts.omitted ?? 0} · 无法核对 ${summary.counts.unconfirmed ?? 0}`,
         );
       }
     }
@@ -248,10 +289,33 @@ export function renderVerifyReport(report, options = {}) {
     lines.push("");
   }
 
+  const drift = report.policyDrift ?? [];
+  if (drift.length > 0) {
+    lines.push("策略漂移（同一个 toolPolicy 被物化成了不同的 deny 列表）");
+    for (const item of drift) {
+      lines.push(`  · ${item.toolPolicy} @ ${item.teamName}：${item.variants.length} 种物化结果`);
+      for (const variant of item.variants) {
+        lines.push(`      deny ${variant.deny} · sha ${variant.sha} · ${variant.members.length} 人（${variant.members.join(", ")}）`);
+      }
+    }
+    lines.push("");
+  }
+
+  const provenance = report.provenance ?? [];
+  if (provenance.length > 0) {
+    lines.push("团队溯源（团队由哪一版档案建成；插件只读 description）");
+    for (const item of provenance) lines.push(`  · ${item.teamName}：${provenanceText(item)}`);
+    lines.push("");
+  }
+
   const summary = report.summary;
   lines.push(
-    `汇总：一致 ${summary.faithful} · 降级 ${summary.degraded} · 未部署 ${summary.missing} · 无档案 ${summary.unmanaged}`,
+    `汇总：忠实 ${summary.faithful} · 未核实 ${summary.unverified} · 降级 ${summary.drift} · 未部署 ${summary.missing} · 无档案 ${summary.unmanaged}`,
   );
+  if (summary.unverified > 0) {
+    lines.push("（未核实 = 档案声明了值、运行时却不持久化该字段，例如人设 executionPrompt；这不是降级，但也拿不到回执。）");
+  }
+  if (summary.policyDrift > 0) lines.push(`（另有 ${summary.policyDrift} 处策略漂移、${summary.provenanceDiffer} 处溯源自建档案后已变。）`);
 
   const skills = (report.skills ?? []).filter(
     (item) => rosterIds.size === 0 || rosterIds.has(item.rosterId),
@@ -272,7 +336,68 @@ export function renderVerifyReport(report, options = {}) {
 }
 
 /**
- * 队长段：说明"能声明什么、真要生效要改哪里"。
+ * 档案差异（`roster_diff`）的人读渲染。
+ *
+ * @param {object} diff `diffRosters` 的结果
+ * @param {{ from: object, to: object }} labels 两端的档案标识（`{ id, version, sha }`）
+ * @returns {string}
+ */
+export function renderRosterDiff(diff, labels) {
+  const lines = [];
+  lines.push(`档案差异  ${rosterLabel(labels.from)}  →  ${rosterLabel(labels.to)}`);
+  lines.push("（比的是有效值：defaults 已合进成员；成员按 name 对齐，aliases 不自动合并）");
+
+  if (diff.rosters.length === 0 && diff.counts.added === 0 && diff.counts.removed === 0 && diff.counts.changed === 0) {
+    lines.push("");
+    lines.push("两份档案没有语义差别。");
+  }
+
+  if (diff.rosters.length > 0) {
+    lines.push("");
+    lines.push("档案字段");
+    for (const change of diff.rosters) {
+      lines.push(`  · ${change.field}  ${change.from} → ${change.to}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(`成员  增 ${diff.counts.added} · 删 ${diff.counts.removed} · 改 ${diff.counts.changed}`);
+  for (const name of diff.members.added) lines.push(`  + ${name}  （新一代新增，旧团队里没有）`);
+  for (const name of diff.members.removed) lines.push(`  - ${name}  （新一代已移除，旧团队里还在）`);
+  for (const change of diff.members.changed) {
+    lines.push(`  · ${change.name}`);
+    for (const field of change.fields) {
+      const origin = field.origin === undefined ? "" : `   [${field.origin}]`;
+      lines.push(`      ${field.field}  ${field.from} → ${field.to}${origin}`);
+    }
+  }
+
+  if (diff.skills.length > 0) {
+    lines.push("");
+    lines.push("技能（声明层：不会因为档案写了就加载）");
+    for (const change of diff.skills) {
+      const parts = [];
+      if (change.added.length > 0) parts.push(`新增 ${change.added.join(", ")}`);
+      if (change.removed.length > 0) parts.push(`移除 ${change.removed.join(", ")}`);
+      lines.push(`  · ${change.member}  ${parts.join("；")}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * `roster:<id>@<ver>[#sha8]`。
+ *
+ * @param {{ id: string, version: string, sha: string | null }} label
+ * @returns {string}
+ */
+function rosterLabel(label) {
+  const sha = typeof label.sha === "string" && label.sha !== "" ? `#${label.sha.slice(0, 8)}` : "";
+  return `roster:${label.id}@${label.version}${sha}`;
+}
+
+/**
+ * 队长段：说明"能声明什么，真要生效要改哪里"。
  *
  * 队长不是成员——它就是创建团队的那个会话。这里绝不写成"档案已配置队长"，
  * 否则使用者会以为改档案就能换队长模型。
@@ -366,3 +491,109 @@ function firstLines(text, maxLines, maxChars) {
   const clipped = lines.length > maxChars ? `${lines.slice(0, maxChars)}…` : lines;
   return clipped === "" ? "（空）" : clipped;
 }
+
+/**
+ * 一份档案的「能力要求」声明块（`roster_show` 用）。
+ *
+ * 只陈述"要求什么、缺失时怎么办、什么时候核过"，不评价是否满足——满足与否是核对器的事，
+ * 两件事混在一段文字里，读者永远分不清哪句是声明、哪句是判定。
+ *
+ * @param {object} roster 已校验档案
+ * @param {object} capabilities `capabilities.yaml` 的解析结果
+ * @returns {string}
+ */
+export function renderCapabilityRequirements(roster, capabilities) {
+  const requires = capabilities?.requires ?? { skills: [], toolPolicies: [] };
+  const lines = [
+    `能力要求  ${roster.id}  onMissing=${capabilities?.onMissing ?? "refuse"}` +
+      `${capabilities?.asOf === null || capabilities?.asOf === undefined ? "" : `  asOf=${capabilities.asOf}`}`,
+  ];
+  const sections = [
+    ["技能", requires.skills ?? []],
+    ["工具策略", requires.toolPolicies ?? []],
+  ];
+  const total = sections.reduce((sum, [, items]) => sum + items.length, 0);
+  if (total === 0) {
+    lines.push("  （没有声明任何能力要求）");
+  } else {
+    for (const [label, items] of sections) {
+      if (items.length === 0) continue;
+      lines.push(`  ${label}  ${items.length} 项`);
+      for (const item of items) {
+        lines.push(`    · ${item.name}${item.reason === null || item.reason === undefined ? "" : ` — ${item.reason}`}`);
+      }
+    }
+  }
+  if (capabilities?.notes) lines.push(`  说明  ${capabilities.notes}`);
+  lines.push("  只声明不承载：能力本体在技能目录与策略定义里，这份文件只回答「需要什么」。");
+  return lines.join("\n");
+}
+
+/**
+ * 拒绝出参数时的说明（`roster_create` 的闸门）。
+ *
+ * 三件事必须同时说清：缺什么、缺的那项该装到哪、以及"核对不到"为什么不算缺。
+ * 只说"缺少能力"等于把问题原样丢回给调用者。
+ *
+ * @param {object} roster 已校验档案
+ * @param {object} gate `checkCapabilities().entries` 的单条结果
+ * @param {Record<string, { label: string, install: string }>} hints 类别 → 人话名与安装位置
+ * @returns {string}
+ */
+export function renderCapabilityGate(roster, gate, hints) {
+  const lines = [
+    `能力闸门  ${roster.id}  缺 ${gate.missing.length} 项，未生成建队参数（onMissing=${gate.onMissing}）`,
+  ];
+  for (const item of gate.missing) {
+    const hint = hints[item.kind] ?? { label: item.kind, install: "（无已知安装位置）" };
+    lines.push(`  ✖ ${hint.label} ${item.name}${item.reason ? ` — ${item.reason}` : ""}`);
+    lines.push(`      怎么补：${hint.install}`);
+  }
+  if (gate.unknown.length > 0) {
+    lines.push(
+      `  ? 核对不到 ${gate.unknown.length} 项（不算缺失，也不会被当成通过）：` +
+        gate.unknown.map((item) => item.name).join("、"),
+    );
+    lines.push("      原因通常是宿主没挂技能服务，或本插件没配 knownToolPolicies。");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * 多份档案的能力核对汇总（`roster_verify` 用）。
+ *
+ * @param {object[]} entries `checkCapabilities().entries`
+ * @param {Record<string, { label: string }>} hints 类别 → 人话名
+ * @returns {string}
+ */
+export function renderCapabilityReport(entries, hints) {
+  const total = { declared: 0, missing: 0, unknown: 0, blocked: 0 };
+  const lines = [];
+  for (const entry of entries) {
+    total.declared += entry.requires;
+    total.missing += entry.missing.length;
+    total.unknown += entry.unknown.length;
+    if (entry.blocked) total.blocked += 1;
+  }
+  lines.push(
+    `能力要求  要求 ${total.declared} · 缺 ${total.missing} · 核对不到 ${total.unknown} · 拦下 ${total.blocked} 份档案`,
+  );
+  for (const entry of entries) {
+    const detail =
+      entry.requires === 0
+        ? "未声明要求"
+        : entry.missing.length > 0
+          ? `缺 ${entry.missing.map((item) => `${hints[item.kind]?.label ?? item.kind}:${item.name}`).join("、")}`
+          : entry.unknown.length > 0
+            ? `核对不到 ${entry.unknown.map((item) => item.name).join("、")}`
+            : `要求 ${entry.requires} 项全部在位`;
+    lines.push(
+      `  ${entry.rosterId.padEnd(24)} ${entry.status.padEnd(9)} ${detail}` +
+        `  onMissing=${entry.onMissing}${entry.asOf === null ? "" : `  asOf=${entry.asOf}`}`,
+    );
+  }
+  if (total.unknown > 0) {
+    lines.push("  核对不到 ≠ 缺失：没有证据源时既不翻红，也不冒充通过。");
+  }
+  return lines.join("\n");
+}