@stofone/dsh-agent-roster 0.6.2 → 0.7.0

package/lib/capabilities.js

@@ -0,0 +1,434 @@
+/**
+ * 能力要求（`capabilities.yaml`）：与档案同目录的**兄弟文件**，只写"要用到哪些能力"，
+ * 不承载任何能力本身。
+ *
+ * 为什么不在 `roster.yaml` 里加字段：档案格式是严格闭集（未知键 = 错误），
+ * 而且上游只会消费那 17 个已知字段。能力要求属于"部署侧的事实"，不是"成员是谁"，
+ * 所以另放一个文件，由本插件自己读、自己校验。
+ *
+ * 三条纪律（都是踩过的坑换来的）：
+ *
+ * 1. **只声明能核对的**。目前能核对两类：技能是否装在技能目录里（`ctx.get("skills")`），
+ *    toolPolicy id 是否在部署声明里（配置 `knownToolPolicies`）。模型路由、插件版本、
+ *    凭据指针一律不写——它们在这个上下文里没有证据源，写进来只会再造一次假绿。
+ * 2. **缺失的语义由 `onMissing` 决定，默认 `refuse`**：拒绝出参数，而不是"先建了再说"。
+ *    静默降级正是 `systemPrompt` 假绿的翻版。
+ * 3. **核对不到 ≠ 缺失**。没有证据源时状态是 `unchecked`，既不翻红也不冒充通过。
+ *
+ * @module dsh-agent-roster/capabilities
+ */
+import { diagnostic } from "./parse.js";
+
+/** 能力要求文档的格式标识。 */
+export const CAPABILITIES_KIND = "dsh-agent-roster-capabilities/v1";
+
+/** 兄弟文件的候选文件名，按优先级取第一个。 */
+export const CAPABILITIES_FILE_NAMES = ["capabilities.yaml", "capabilities.yml", "capabilities.json"];
+
+/** 能力缺失时的行为。`refuse` 是默认值：缺能力就不出参数。 */
+export const ON_MISSING = /** @type {const} */ (["refuse", "degraded"]);
+export const DEFAULT_ON_MISSING = "refuse";
+
+/** 顶层字段闭集。 */
+const ROOT_FIELDS = new Set(["kind", "roster", "onMissing", "asOf", "requires", "notes"]);
+/** `requires` 的字段闭集。 */
+const REQUIRES_FIELDS = new Set(["skills", "toolPolicies"]);
+
+export const LIMITS = { requirements: 32, nameChars: 64, reasonChars: 200, notesChars: 500 };
+
+/** 与 format.js 同一口径的 kebab-case id 模式。 */
+export const ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+/** 技能名允许大写与下划线（DSH 技能目录不强制 kebab-case）。 */
+export const SKILL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** `asOf` 只接受日期，不接受时间戳：能力清单是按天核的，写时分秒会制造假精度。 */
+const AS_OF_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * 校验一份能力要求文档（纯函数、零 IO）。
+ *
+ * @param {unknown} value 已解析的对象树
+ * @param {{ file?: string, expectedId?: string | null }} [options]
+ * @returns {{ ok: boolean, capabilities: object | null, diagnostics: object[] }}
+ */
+export function validateCapabilities(value, options = {}) {
+  const file = String(options.file ?? "");
+  const expectedId =
+    typeof options.expectedId === "string" && options.expectedId !== "" ? options.expectedId : null;
+  const diagnostics = [];
+  const report = (severity, code, path, reason) =>
+    diagnostics.push(diagnostic(severity, code, path, reason, file));
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    report("error", "capabilities-not-mapping", "", "能力要求文档顶层必须是映射（对象）");
+    return { ok: false, capabilities: null, diagnostics };
+  }
+
+  for (const key of Object.keys(value)) {
+    if (!ROOT_FIELDS.has(key)) {
+      report(
+        "error",
+        "unknown-field",
+        key,
+        `未知字段 "${key}"。能力要求只接受 ${[...ROOT_FIELDS].join(" / ")}；` +
+          "模型路由、插件版本、凭据指针没有证据源，写进来只会变成永不核对的假绿。",
+      );
+    }
+  }
+
+  if (value.kind !== CAPABILITIES_KIND) {
+    report(
+      "error",
+      "invalid-kind",
+      "kind",
+      `kind 必须是 "${CAPABILITIES_KIND}"，实际是 ${describe(value.kind)}`,
+    );
+  }
+
+  const rosterId = value.roster;
+  if (typeof rosterId !== "string" || rosterId === "") {
+    report("error", "missing-field", "roster", "缺少 roster（这份要求属于哪份档案）");
+  } else if (!ID_PATTERN.test(rosterId)) {
+    report("error", "invalid-id", "roster", `roster 必须是 kebab-case 的 2~64 字符：${rosterId}`);
+  } else if (expectedId !== null && rosterId !== expectedId) {
+    report(
+      "error",
+      "roster-id-mismatch",
+      "roster",
+      `roster 字段（${rosterId}）必须与所在目录名（${expectedId}）一致`,
+    );
+  }
+
+  let onMissing = DEFAULT_ON_MISSING;
+  if (value.onMissing !== undefined && value.onMissing !== null) {
+    if (!ON_MISSING.includes(value.onMissing)) {
+      report(
+        "error",
+        "invalid-on-missing",
+        "onMissing",
+        `onMissing 只能是 ${ON_MISSING.join(" / ")}，实际是 ${describe(value.onMissing)}`,
+      );
+    } else {
+      onMissing = value.onMissing;
+    }
+  }
+
+  let asOf = null;
+  if (value.asOf !== undefined && value.asOf !== null) {
+    if (typeof value.asOf !== "string" || !AS_OF_PATTERN.test(value.asOf)) {
+      report("error", "invalid-as-of", "asOf", `asOf 必须是 YYYY-MM-DD 日期：${describe(value.asOf)}`);
+    } else {
+      asOf = value.asOf;
+    }
+  }
+
+  const notes = optionalText(value.notes, "notes", LIMITS.notesChars, report);
+  const requires = validateRequires(value.requires, report);
+
+  return {
+    ok: diagnostics.every((item) => item.severity !== "error"),
+    capabilities: {
+      kind: CAPABILITIES_KIND,
+      roster: typeof rosterId === "string" ? rosterId : null,
+      onMissing,
+      asOf,
+      requires,
+      notes,
+    },
+    diagnostics,
+  };
+}
+
+function validateRequires(raw, report) {
+  const empty = { skills: [], toolPolicies: [] };
+  if (raw === undefined || raw === null) return empty;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    report("error", "invalid-requires", "requires", "requires 必须是映射（对象）");
+    return empty;
+  }
+  for (const key of Object.keys(raw)) {
+    if (!REQUIRES_FIELDS.has(key)) {
+      report(
+        "error",
+        "unknown-field",
+        `requires.${key}`,
+        `未知的能力类别 "requires.${key}"。目前只核对 skills 与 toolPolicies；` +
+          "其余类别没有证据源，不接收。",
+      );
+    }
+  }
+  return {
+    skills: requirementList(raw.skills, "requires.skills", SKILL_PATTERN, report),
+    toolPolicies: requirementList(raw.toolPolicies, "requires.toolPolicies", ID_PATTERN, report),
+  };
+}
+
+/**
+ * 读取一组能力要求。每一项可以写成裸字符串，也可以写成 `{name, reason}`：
+ * 裸字符串够用于 CI，带 `reason` 是给人看的——"为什么需要它"往往比"需要它"更重要。
+ */
+function requirementList(raw, path, pattern, report) {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    report("error", "invalid-requirement-list", path, `${path} 必须是数组`);
+    return [];
+  }
+  if (raw.length > LIMITS.requirements) {
+    report("error", "too-many-requirements", path, `${path} 最多 ${LIMITS.requirements} 项`);
+    return [];
+  }
+  const seen = new Map();
+  const out = [];
+  raw.forEach((item, index) => {
+    const at = `${path}[${index}]`;
+    let name;
+    let reason = null;
+    if (typeof item === "string") {
+      name = item;
+    } else if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+      for (const key of Object.keys(item)) {
+        if (key !== "name" && key !== "reason") {
+          report("error", "unknown-field", `${at}.${key}`, `未知字段 "${key}"，只接受 name / reason`);
+        }
+      }
+      name = item.name;
+      if (item.reason !== undefined && item.reason !== null) {
+        reason = optionalText(item.reason, `${at}.reason`, LIMITS.reasonChars, report);
+      }
+    } else {
+      report("error", "invalid-requirement", at, `${at} 必须是字符串或 {name, reason} 对象`);
+      return;
+    }
+    if (typeof name !== "string" || name === "") {
+      report("error", "missing-field", `${at}.name`, `${at} 缺少 name`);
+      return;
+    }
+    if (name.length > LIMITS.nameChars) {
+      report("error", "name-too-long", `${at}.name`, `${at}.name 最长 ${LIMITS.nameChars} 字符`);
+      return;
+    }
+    if (!pattern.test(name)) {
+      report("error", "invalid-requirement-name", `${at}.name`, `${at}.name 不合格式：${name}`);
+      return;
+    }
+    if (seen.has(name)) {
+      report(
+        "error",
+        "duplicate-requirement",
+        `${at}.name`,
+        `${name} 重复声明（已出现在 ${seen.get(name)}）；重复不会让要求更强，只会让人以为写了两条。`,
+      );
+      return;
+    }
+    seen.set(name, at);
+    out.push({ name, reason });
+  });
+  return out;
+}
+
+function optionalText(value, path, limit, report) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string") {
+    report("error", "invalid-type", path, `${path} 必须是字符串`);
+    return null;
+  }
+  const text = value.trim();
+  if (text === "") return null;
+  if (text.length > limit) {
+    report("error", "too-long", path, `${path} 最长 ${limit} 字符，实际 ${text.length}`);
+    return null;
+  }
+  if (/[\r\n]/.test(text)) {
+    report("error", "multiline-text", path, `${path} 必须是单行文本`);
+    return null;
+  }
+  return text;
+}
+
+function describe(value) {
+  if (value === null) return "null";
+  if (value === undefined) return "（缺失）";
+  if (typeof value === "string") return `"${value}"`;
+  if (Array.isArray(value)) return "数组";
+  return typeof value === "object" ? "对象" : String(value);
+}
+
+/**
+ * 把能力要求摊平成一串待核对项。
+ *
+ * @param {object | null} capabilities
+ * @returns {{ kind: "skill" | "toolPolicy", name: string, reason: string | null }[]}
+ */
+export function capabilityRequirements(capabilities) {
+  if (capabilities === null || capabilities === undefined) return [];
+  const requires = capabilities.requires ?? {};
+  return [
+    ...(requires.skills ?? []).map((item) => ({ kind: "skill", name: item.name, reason: item.reason })),
+    ...(requires.toolPolicies ?? []).map((item) => ({
+      kind: "toolPolicy",
+      name: item.name,
+      reason: item.reason,
+    })),
+  ];
+}
+
+/**
+ * 核对能力要求。
+ *
+ * 三种结果，**互不冒充**：
+ * - `present`：证据源说它在；
+ * - `missing`：证据源说它不在（这是唯一会让 `refuse` 生效的状态）；
+ * - `unknown`：没有证据源（技能服务没挂、`knownToolPolicies` 没配），既不算过也不算错。
+ *
+ * @param {object[]} rosters 已通过校验的档案
+ * @param {Record<string, object>} capabilitiesById 档案 id → 能力要求对象
+ * @param {{ knownSkills?: string[] | null, knownToolPolicies?: string[] | null }} [evidence]
+ * @returns {{ entries: object[], summary: object }}
+ */
+export function checkCapabilities(rosters, capabilitiesById, evidence = {}) {
+  const knownSkills =
+    Array.isArray(evidence.knownSkills) && evidence.knownSkills.length > 0
+      ? new Set(evidence.knownSkills.filter((name) => typeof name === "string" && name !== ""))
+      : null;
+  const knownPolicies =
+    Array.isArray(evidence.knownToolPolicies) && evidence.knownToolPolicies.length > 0
+      ? new Set(evidence.knownToolPolicies.filter((id) => typeof id === "string" && id !== ""))
+      : null;
+
+  const entries = [];
+  const summary = { declared: 0, present: 0, missing: 0, unknown: 0, blocked: 0, degraded: 0 };
+
+  for (const roster of rosters) {
+    const capabilities = capabilitiesById?.[roster.id] ?? null;
+    const requirements = capabilityRequirements(capabilities);
+    if (requirements.length === 0 && capabilities === null) continue;
+
+    const missing = [];
+    const unknown = [];
+    const present = [];
+    for (const requirement of requirements) {
+      const evidenceSet = requirement.kind === "skill" ? knownSkills : knownPolicies;
+      if (evidenceSet === null) {
+        unknown.push(requirement);
+      } else if (evidenceSet.has(requirement.name)) {
+        present.push(requirement);
+      } else {
+        missing.push(requirement);
+      }
+    }
+
+    const onMissing = capabilities?.onMissing ?? DEFAULT_ON_MISSING;
+    // 只有"确实缺"才触发策略；核对不到不许当成缺，否则配不上证据源的机器会全红。
+    const blocked = onMissing === "refuse" && missing.length > 0;
+    summary.declared += requirements.length;
+    summary.present += present.length;
+    summary.missing += missing.length;
+    summary.unknown += unknown.length;
+    if (blocked) summary.blocked += 1;
+    else if (onMissing === "degraded" && missing.length > 0) summary.degraded += 1;
+
+    entries.push({
+      rosterId: roster.id,
+      version: roster.version,
+      onMissing,
+      asOf: capabilities?.asOf ?? null,
+      requires: requirements.length,
+      present,
+      missing,
+      unknown,
+      blocked,
+      status: blocked ? "blocked" : missing.length > 0 ? "degraded" : unknown.length > 0 ? "unchecked" : "ok",
+    });
+  }
+
+  return { entries, summary };
+}
+
+/** 能力类别的人话名与"该装到哪"——拒绝时直接告诉人怎么修。 */
+export const CAPABILITY_HINTS = {
+  skill: {
+    label: "技能",
+    install:
+      "把技能目录放进仓库的 .dsh/skills/ 或全局 ~/.dsh/skills/（由 dsh-skill-filesystem 监听，拷进去即生效）",
+  },
+  toolPolicy: {
+    label: "工具策略",
+    install: "在本插件配置的 knownToolPolicies 里声明该 id，并在 profile 的 toolPolicies 中定义它",
+  },
+};
+
+/**
+ * 面板层的能力诊断：把"能同步判定的部分"变成诊断条目。
+ *
+ * 为什么只判工具策略：面板快照是同步的，而技能目录只能通过宿主的技能服务异步列出来。
+ * 与其在面板里编一个"看起来通过"的结论，不如把技能要求标成"面板不核对"——
+ * 这与 `checkCapabilities` 的 `unknown` 是同一个态度：没有证据源就说没有，不冒充通过。
+ *
+ * @param {Record<string, object>} capabilitiesById 档案 id → 能力要求
+ * @param {Record<string, string>} capabilityFiles 档案 id → 能力文件相对路径
+ * @param {string[] | null} knownToolPolicies 部署已声明的策略 id
+ * @returns {object[]} 与 `scanRosterLibrary` 同形状的诊断
+ */
+export function capabilityDiagnostics(capabilitiesById, capabilityFiles, knownToolPolicies) {
+  const ids = Object.keys(capabilitiesById ?? {}).sort();
+  if (ids.length === 0) return [];
+
+  const policies = Array.isArray(knownToolPolicies) ? knownToolPolicies : null;
+  const diagnostics = [];
+  const skipped = [];
+
+  for (const id of ids) {
+    const capabilities = capabilitiesById[id];
+    const file = capabilityFiles?.[id] ?? `${id}/capabilities.yaml`;
+    const base = { path: "", file };
+
+    const declaredPolicies = (capabilities.requires?.toolPolicies ?? []).map((item) => item.name);
+    const declaredSkills = (capabilities.requires?.skills ?? []).map((item) => item.name);
+
+    if (declaredPolicies.length > 0) {
+      if (policies === null) {
+        // 证据源缺席：逐份档案刷"无法核对"只会变成噪音，汇总成一条。
+        skipped.push(id);
+      } else {
+        const missing = declaredPolicies.filter((name) => !policies.includes(name));
+        if (missing.length > 0) {
+          const refuse = (capabilities.onMissing ?? DEFAULT_ON_MISSING) === "refuse";
+          diagnostics.push({
+            ...base,
+            severity: refuse ? "error" : "warn",
+            code: "capability-policy-missing",
+            reason: refuse
+              ? `档案 "${id}" 要求工具策略 ${missing.join("、")}，但部署的 knownToolPolicies 里没有；` +
+                "onMissing: refuse，建队会被拒绝。"
+              : `档案 "${id}" 要求工具策略 ${missing.join("、")}，但部署的 knownToolPolicies 里没有；` +
+                "onMissing: degraded，建队照常，但每次核对都会记为 degraded。",
+          });
+        }
+      }
+    }
+
+    if (declaredSkills.length > 0) {
+      diagnostics.push({
+        ...base,
+        severity: "info",
+        code: "capability-skills-unverified",
+        reason:
+          `档案 "${id}" 声明了技能要求 ${declaredSkills.join("、")}；` +
+          "面板不列技能目录，因此这里不判定——用 roster_verify 核对（技能服务在场时才会给出缺/不缺）。",
+      });
+    }
+  }
+
+  if (skipped.length > 0) {
+    diagnostics.push({
+      severity: "info",
+      code: "capability-cross-check-skipped",
+      path: "",
+      file: null,
+      reason:
+        `未配置 knownToolPolicies：${skipped.join("、")} 的 toolPolicies 要求只做格式校验，不与部署交叉核对。` +
+        "把部署里存在的策略 id 列进该配置即可启用核对。",
+    });
+  }
+
+  return diagnostics;
+}

package/lib/diff.js

@@ -0,0 +1,216 @@
+/**
+ * 档案 ↔ 档案的差异：换班时第一个要回答的问题就是"新一代改了什么"。
+ *
+ * 已有的核对都是"档案 ↔ 运行态"（`roster_verify`），它回答不了这个问题：
+ * 同一个团队换成新一代档案后，运行态与**新**档案一致，旧档案与新档案的差别却没人记得。
+ * 所以这里只做纯函数比较，不读文件、不碰团队状态——载入与解析由调用方负责。
+ *
+ * 三条判读纪律：
+ * 1. **成员按 `name` 对齐**，`aliases` 只作提示不自动合并——否则"改名"会被静默吞成"没变"。
+ * 2. **比较的是有效值**（`defaults` 已合进成员），并标注这个值是成员自己写的还是继承来的；
+ *    档案里把 `model` 从成员搬到 `defaults`、值不变，不算变更。
+ * 3. **人设不进差异正文**，只给长度与内容哈希——8000 字人设并排贴在终端里没人读得下去，
+ *    而"长度变了 / 哈希变了"足够回答"改没改"。
+ *
+ * @module dsh-agent-roster/diff
+ */
+import { sha256Hex, shortSha } from "./digest.js";
+
+/** 参与逐一比较的成员字段（顺序即输出顺序）。 */
+const MEMBER_FIELDS = ["role", "provider", "model", "reasoningEffort", "toolPolicy", "toolScope", "maxTokens"];
+
+/** 档案顶层参与比较的字段。 */
+const ROSTER_FIELDS = ["version", "title", "description", "license"];
+
+/**
+ * 比较两份已校验档案。
+ *
+ * @param {object} from 旧档案
+ * @param {object} to 新档案
+ * @returns {{ rosters: object[], members: object, skills: object[], counts: object }}
+ */
+export function diffRosters(from, to) {
+  const members = diffMembers(from, to);
+  return {
+    rosters: diffRosterFields(from, to),
+    members,
+    skills: diffSkills(from, to),
+    counts: { added: members.added.length, removed: members.removed.length, changed: members.changed.length },
+  };
+}
+
+/**
+ * 档案顶层字段。
+ *
+ * @param {object} from
+ * @param {object} to
+ * @returns {{ field: string, from: string, to: string }[]}
+ */
+function diffRosterFields(from, to) {
+  const changes = [];
+  for (const field of ROSTER_FIELDS) {
+    const before = textOf(from?.[field]);
+    const after = textOf(to?.[field]);
+    if (before !== after) changes.push({ field, from: before, to: after });
+  }
+  for (const field of ["provider", "model", "reasoningEffort"]) {
+    const before = textOf(from?.defaults?.[field]);
+    const after = textOf(to?.defaults?.[field]);
+    if (before !== after) changes.push({ field: `defaults.${field}`, from: before, to: after });
+  }
+  return changes;
+}
+
+/**
+ * 成员层面的增删改。
+ *
+ * @param {object} from
+ * @param {object} to
+ * @returns {{ added: string[], removed: string[], changed: object[] }}
+ */
+function diffMembers(from, to) {
+  const before = membersByName(from);
+  const after = membersByName(to);
+  const added = [...after.keys()].filter((name) => !before.has(name));
+  const removed = [...before.keys()].filter((name) => !after.has(name));
+  const changed = [];
+  for (const [name, newMember] of after) {
+    const oldMember = before.get(name);
+    if (oldMember === undefined) continue;
+    const fields = [];
+    for (const field of MEMBER_FIELDS) {
+      const left = textOf(oldMember[field]);
+      const right = textOf(newMember[field]);
+      if (left === right) continue;
+      fields.push({
+        field,
+        from: left,
+        to: right,
+        origin: originOf(oldMember, newMember, field),
+      });
+    }
+    const persona = diffPersona(oldMember.systemPrompt, newMember.systemPrompt);
+    if (persona !== null) fields.push(persona);
+    const aliases = diffList(oldMember.aliases, newMember.aliases, "aliases");
+    if (aliases !== null) fields.push(aliases);
+    if (fields.length > 0) changed.push({ name, fields });
+  }
+  return { added, removed, changed };
+}
+
+/**
+ * 人设只比长度与哈希。两段文字一模一样时连这一行都不出现。
+ *
+ * @param {unknown} before
+ * @param {unknown} after
+ * @returns {{ field: string, from: string, to: string } | null}
+ */
+function diffPersona(before, after) {
+  const left = typeof before === "string" ? before : "";
+  const right = typeof after === "string" ? after : "";
+  if (left === right) return null;
+  return { field: "systemPrompt", from: fingerprintOf(left), to: fingerprintOf(right) };
+}
+
+/**
+ * 列表字段（aliases / skills）按集合比较，顺序变化不算变更。
+ *
+ * @param {unknown} before
+ * @param {unknown} after
+ * @param {string} field
+ * @returns {{ field: string, from: string, to: string } | null}
+ */
+function diffList(before, after, field) {
+  const left = listOf(before);
+  const right = listOf(after);
+  if (left.join("\u0000") === right.join("\u0000")) return null;
+  return { field, from: left.join(", "), to: right.join(", ") };
+}
+
+/**
+ * 技能按成员逐条比增减——换班时最常问的是"新加的成员要装什么技能"。
+ *
+ * @param {object} from
+ * @param {object} to
+ * @returns {{ member: string, added: string[], removed: string[] }[]}
+ */
+function diffSkills(from, to) {
+  const before = membersByName(from);
+  const after = membersByName(to);
+  const changes = [];
+  for (const [name, newMember] of after) {
+    const oldMember = before.get(name);
+    if (oldMember === undefined) continue;
+    const left = new Set(listOf(oldMember.skills));
+    const right = new Set(listOf(newMember.skills));
+    const added = [...right].filter((item) => !left.has(item));
+    const removed = [...left].filter((item) => !right.has(item));
+    if (added.length > 0 || removed.length > 0) changes.push({ member: name, added, removed });
+  }
+  return changes;
+}
+
+/**
+ * 成员名 → 成员，跳过没有名字的记录（校验层已拦，这里只防崩）。
+ *
+ * @param {object} roster
+ * @returns {Map<string, object>}
+ */
+function membersByName(roster) {
+  const map = new Map();
+  for (const member of Array.isArray(roster?.members) ? roster.members : []) {
+    if (member !== null && typeof member === "object" && typeof member.name === "string" && member.name !== "") {
+      map.set(member.name, member);
+    }
+  }
+  return map;
+}
+
+/**
+ * 这个字段的差别来自哪里：成员自己改的，还是从 `defaults` 继承来的。
+ *
+ * @param {object} before
+ * @param {object} after
+ * @param {string} field
+ * @returns {string}
+ */
+function originOf(before, after, field) {
+  const left = before.inherited?.includes(field) ? "defaults" : "member";
+  const right = after.inherited?.includes(field) ? "defaults" : "member";
+  if (left === right) return right;
+  return `${left} → ${right}`;
+}
+
+/**
+ * 人读指纹：`1234 字符 #ab12cd34`。
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function fingerprintOf(text) {
+  if (text === "") return "（空）";
+  return `${text.length} 字符 #${shortSha(sha256Hex(text))}`;
+}
+
+/**
+ * 标量转文本：缺省显示成 `（未声明）`，避免 `undefined` 混进差异表。
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function textOf(value) {
+  if (value === undefined || value === null) return "（未声明）";
+  if (typeof value === "string") return value === "" ? "（空）" : value;
+  return String(value);
+}
+
+/**
+ * 字符串数组规范化：去空、排序、去重。
+ *
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function listOf(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item) => typeof item === "string" && item !== ""))].sort();
+}