@stofone/dsh-agent-roster 0.6.2 → 0.8.0

package/lib/registry.js

@@ -24,7 +24,15 @@
 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 {
+  ORGANIZATION_FILE_NAMES,
+  checkOrganization,
+  organizationDiagnostics,
+  validateOrganization,
+} from "./organization.js";
 import { parseDocumentText } from "./parse.js";
 import { validateRoster } from "./validate.js";
 
@@ -51,6 +59,13 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
   const diagnostics = [];
   const entries = [];
   const rosters = [];
+  /** 档案 id → 能力要求（`capabilities.yaml` 的解析结果）。 */
+  const capabilities = {};
+  /** 档案 id → 能力要求的文件名（诊断要指到具体那份文件）。 */
+  const capabilityFiles = {};
+  /** 组织档案（organization.yaml）与它的交叉核对结果。 */
+  let organization = null;
+  let organizationFile = null;
   const stats = {
     total: 0,
     ok: 0,
@@ -76,6 +91,8 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
       if (child.name.startsWith(".") || SKIP_DIRS.has(child.name) || child.isSymbolicLink()) continue;
 
       if (!child.isDirectory()) {
+        // 库根上的 organization.yaml 是合法的：它是这座库的目录页，不是散落的档案。
+        if (ORGANIZATION_FILE_NAMES.includes(child.name)) continue;
         // 散落的 *.yaml 曾经是另一种布局；现在只认目录，必须明确告知而不是忽略。
         diagnostics.push({
           severity: "warn",
@@ -97,7 +114,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) {
@@ -111,6 +136,17 @@ export function scanRosterLibrary({ rootDir, knownToolPolicies = null }) {
     }
   }
 
+  // 组织档案在目录扫完之后读：它的交叉核对需要知道磁盘上到底有哪些档案。
+  const wantedOrganization = loadOrganization(rootDir, nodePath.basename(rootDir));
+  organization = wantedOrganization.organization;
+  organizationFile = wantedOrganization.file;
+  diagnostics.push(...wantedOrganization.diagnostics);
+  const organizationCheck = checkOrganization(
+    organization,
+    rosters.map((item) => item.id),
+  );
+  diagnostics.push(...organizationDiagnostics(organization, organizationCheck, organizationFile ?? ORGANIZATION_FILE_NAMES[0]));
+
   if (stats.total > 0 && rosters.length === 0) {
     diagnostics.push({
       severity: "error",
@@ -151,7 +187,19 @@ 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,
+    organization,
+    organizationFile,
+    organizationCheck,
+    stats,
+    diagnostics,
+  };
 }
 
 /**
@@ -219,10 +267,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 +304,163 @@ 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 loadOrganization(rootDir, dirName) {
+  let names;
+  try {
+    names = readdirSync(rootDir);
+  } catch {
+    return { organization: null, file: null, diagnostics: [] };
+  }
+  const present = ORGANIZATION_FILE_NAMES.filter((name) => names.includes(name));
+  if (present.length === 0) return { organization: null, file: null, diagnostics: [] };
+
+  const diagnostics = [];
+  const relative = present[0];
+  if (present.length > 1) {
+    diagnostics.push({
+      severity: "warn",
+      code: "multiple-organization-files",
+      path: "",
+      file: relative,
+      reason:
+        `档案库同时存在 ${present.join("、")}，只读 ${present[0]}；` +
+        "请删掉多余文件，否则另一份永远不会生效。",
+    });
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(nodePath.join(rootDir, relative), "utf8");
+  } catch (error) {
+    diagnostics.push({
+      severity: "error",
+      code: "unreadable-file",
+      path: "",
+      file: relative,
+      reason: `文件不可读：${messageOf(error)}`,
+    });
+    return { organization: null, file: relative, diagnostics };
+  }
+
+  const format = relative.endsWith(".json") ? "json" : "yaml";
+  const parsed = parseDocumentText(raw, { file: relative, format });
+  if (!parsed.ok) return { organization: null, file: relative, diagnostics: [...diagnostics, ...parsed.diagnostics] };
+
+  const validated = validateOrganization(parsed.value, { file: relative, expectedId: dirName });
+  diagnostics.push(...validated.diagnostics);
+  if (!validated.ok) return { organization: null, file: relative, diagnostics };
+  return { organization: validated.organization, file: relative, diagnostics };
+}
+
+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}）`;
+  }
+}
 
 /**
  * 诊断列表 → 文本块。错误在前、按文件分组，超出上限时明确写出省略了多少条。
@@ -51,6 +89,21 @@ export function renderRosterList(scan) {
   const { entries, stats, rootDir } = scan;
   const lines = [];
   lines.push(`档案库  ${rootDir}`);
+  const organization = scan.organization ?? null;
+  if (organization !== null) {
+    const check = scan.organizationCheck ?? { declared: 0, present: 0, missing: [], undeclared: [], archived: [] };
+    lines.push(`组织    ${organization.id}  ${organization.title}`);
+    if (organization.description !== "") lines.push(`        ${organization.description}`);
+    const parts = [
+      `登记 ${check.declared}`,
+      `在库 ${check.present}`,
+      `缺 ${check.missing.length}`,
+      `未登记 ${check.undeclared.length}`,
+    ];
+    if (check.archived.length > 0) parts.push(`已归档 ${check.archived.length}`);
+    if (organization.maintainers.length > 0) parts.push(`维护者 ${organization.maintainers.join(", ")}`);
+    lines.push(`        ${parts.join(" · ")}`);
+  }
   if (entries.length === 0) {
     lines.push("");
     lines.push(scan.missing === true ? "（目录尚未创建：保存第一份档案时会自动建）" : "（空：没有任何 roster 目录）");
@@ -210,9 +263,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 +275,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 +288,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 +304,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 +351,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 +506,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");
+}