ppt-template-reuse 0.4.0-rc.2

package/src/core/adaptive-planner.mjs

@@ -0,0 +1,1192 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  parseArgs,
+  readJson,
+  requireArg,
+  textWidthUnits,
+  writeJson,
+} from "./planner-lib.mjs";
+import { assessTemplateFit } from "./template-intelligence.mjs";
+import { auditContentPlan } from "./content-audit.mjs";
+
+const EXEMPT_FAMILIES = new Set(["cover", "agenda", "divider", "closing", "reference", "references"]);
+
+const KIND_ROLE = {
+  background: "background",
+  fact: "evidence",
+  timeline: "evidence",
+  issue: "issue",
+  rule: "analysis",
+  theory: "analysis",
+  method: "analysis",
+  evidence: "evidence",
+  data: "evidence",
+  application: "analysis",
+  analysis: "analysis",
+  counterargument: "counterargument",
+  rebuttal: "rebuttal",
+  conclusion: "conclusion",
+  recommendation: "conclusion",
+};
+
+const KIND_FUNCTIONS = {
+  background: ["background", "explain"],
+  fact: ["claim-and-evidence", "organize-evidence"],
+  timeline: ["chronology", "show-change"],
+  issue: ["problem", "analysis"],
+  rule: ["analysis", "explain"],
+  theory: ["analysis", "explain"],
+  method: ["explain-process", "analysis"],
+  evidence: ["organize-evidence", "claim-and-evidence"],
+  data: ["quantify", "show-trend"],
+  application: ["analysis", "claim-and-evidence"],
+  analysis: ["analysis", "claim-and-evidence"],
+  counterargument: ["compare", "counterargument"],
+  rebuttal: ["analysis", "rebuttal"],
+  conclusion: ["summary", "synthesize"],
+  recommendation: ["summary", "call-to-action"],
+};
+
+function stableObject(value) {
+  if (Array.isArray(value)) return value.map(stableObject);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, stableObject(value[key])]),
+    );
+  }
+  return value;
+}
+
+function fingerprint(value) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(stableObject(value)))
+    .digest("hex");
+}
+
+function text(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalized(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function nonWhitespaceChars(value) {
+  return [...String(value || "").replace(/\s+/gu, "")].length;
+}
+
+function asStrings(value) {
+  if (Array.isArray(value)) return value.map(text).filter(Boolean);
+  const result = text(value);
+  return result ? [result] : [];
+}
+
+function fragmentRecordsForUnit(unit) {
+  const records = [];
+  const add = (field, values, displayRole = "") => {
+    for (const [index, value] of asStrings(values).entries()) {
+      const normalizedText = text(value);
+      if (
+        !normalizedText ||
+        records.some((record) => record.text === normalizedText)
+      ) {
+        continue;
+      }
+      records.push({
+        fragmentId: `${unit.id}:${field}:${index + 1}`,
+        sourceUnitId: String(unit.id),
+        sourceField: field,
+        displayRole: normalized(displayRole),
+        text: normalizedText,
+      });
+    }
+  };
+  for (const [index, fragment] of (
+    Array.isArray(unit.displayFragments) ? unit.displayFragments : []
+  ).entries()) {
+    const fragmentText =
+      typeof fragment === "string" ? fragment : fragment?.text;
+    const fragmentRole =
+      typeof fragment === "string" ? "label" : fragment?.role || "label";
+    add(`displayFragments.${index + 1}`, fragmentText, fragmentRole);
+  }
+  add("summary", unit.summary);
+  add("claim", unit.claim);
+  add("evidence", unit.evidence);
+  add("whyItMatters", unit.whyItMatters);
+  add("counterargument", unit.counterargument);
+  add("rebuttal", unit.rebuttal);
+  return records;
+}
+
+function groupFragmentRecords(group) {
+  const byUnit = group.units.map(fragmentRecordsForUnit);
+  const records = [];
+  const maximum = Math.max(0, ...byUnit.map((items) => items.length));
+  for (let index = 0; index < maximum; index += 1) {
+    for (const unitRecords of byUnit) {
+      if (unitRecords[index]) records.push(unitRecords[index]);
+    }
+  }
+  return records;
+}
+
+function visibleTraceForFields(fields, records) {
+  const trace = [];
+  for (const [field, rawValue] of Object.entries(fields || {})) {
+    const values =
+      rawValue && typeof rawValue === "object" && !Array.isArray(rawValue)
+        ? [rawValue.value, rawValue.alt].filter(Boolean)
+        : Array.isArray(rawValue)
+          ? rawValue
+          : [rawValue];
+    for (const value of values.map(text).filter(Boolean)) {
+      for (const record of records.filter((item) => item.text === value)) {
+        trace.push({
+          ...record,
+          destination: `fields.${field}`,
+        });
+      }
+    }
+  }
+  return trace.filter(
+    (record, index, all) =>
+      all.findIndex(
+        (candidate) =>
+          candidate.fragmentId === record.fragmentId &&
+          candidate.destination === record.destination,
+      ) === index,
+  );
+}
+
+function allUnitsVisible(group, trace) {
+  const visible = new Set(trace.map((record) => record.sourceUnitId));
+  return group.units.every((unit) => visible.has(String(unit.id)));
+}
+
+function sourcePriority(unit) {
+  const priority = normalized(unit.priority);
+  if (["critical", "supporting", "optional"].includes(priority)) return priority;
+  return "supporting";
+}
+
+function sourceRelevance(unit) {
+  const relevance = normalized(unit.presentationRelevance);
+  if (["core", "appendix", "exclude"].includes(relevance)) return relevance;
+  return sourcePriority(unit) === "optional" ? "appendix" : "core";
+}
+
+function validateSourceMap(sourceMap) {
+  const errors = [];
+  const units = Array.isArray(sourceMap.sourceUnits) ? sourceMap.sourceUnits : [];
+  if (!units.length) errors.push("source-map.json must contain sourceUnits");
+  const ids = new Set();
+  for (const [index, unit] of units.entries()) {
+    const id = text(unit.id);
+    if (!id) errors.push(`Source unit ${index + 1} is missing id`);
+    if (ids.has(id)) errors.push(`Duplicate source unit id: ${id}`);
+    ids.add(id);
+    if (!text(unit.summary) && !text(unit.text)) {
+      errors.push(`Source unit ${id || index + 1} is missing summary or text`);
+    }
+    if (!["critical", "supporting", "optional"].includes(sourcePriority(unit))) {
+      errors.push(`Source unit ${id || index + 1} has invalid priority`);
+    }
+  }
+  if (errors.length) throw new Error(errors.join("\n"));
+}
+
+function topicKey(unit, index) {
+  return (
+    text(unit.topicId) ||
+    text(unit.clusterId) ||
+    text(unit.sectionId) ||
+    `${normalized(unit.kind || "analysis")}-${Math.floor(index / 3) + 1}`
+  );
+}
+
+function groupUnits(units) {
+  const groups = [];
+  let current = null;
+  for (const [index, unit] of units.entries()) {
+    const key = topicKey(unit, index);
+    if (!current || current.key !== key) {
+      current = {
+        key,
+        title:
+          text(unit.topicTitle) ||
+          text(unit.sectionTitle) ||
+          text(unit.claim) ||
+          text(unit.summary),
+        units: [],
+      };
+      groups.push(current);
+    }
+    current.units.push(unit);
+  }
+  return groups;
+}
+
+function primaryKind(units) {
+  const priority = [
+    "timeline",
+    "counterargument",
+    "rebuttal",
+    "issue",
+    "data",
+    "evidence",
+    "rule",
+    "application",
+    "analysis",
+    "conclusion",
+    "recommendation",
+    "fact",
+    "background",
+  ];
+  const kinds = new Set(units.map((unit) => normalized(unit.kind || "analysis")));
+  return priority.find((kind) => kinds.has(kind)) || normalized(units[0]?.kind || "analysis");
+}
+
+function groupClaim(group) {
+  return (
+    group.units.map((unit) => text(unit.claim)).find(Boolean) ||
+    text(group.title) ||
+    text(group.units[0]?.summary)
+  );
+}
+
+function groupEvidence(group) {
+  const evidence = group.units.flatMap((unit) => [
+    ...asStrings(unit.evidence),
+    ...(normalized(unit.kind) === "fact" || normalized(unit.kind) === "data"
+      ? [text(unit.summary)]
+      : []),
+  ]);
+  const unique = [...new Set(evidence.filter(Boolean))];
+  if (unique.length) return unique;
+  return group.units.map((unit) => text(unit.summary)).filter(Boolean);
+}
+
+function groupWhy(group) {
+  return (
+    group.units.map((unit) => text(unit.whyItMatters)).find(Boolean) ||
+    group.units.map((unit) => text(unit.consequence)).find(Boolean) ||
+    `这些材料共同支撑“${groupClaim(group)}”这一判断。`
+  );
+}
+
+function groupCounterargument(group) {
+  return (
+    group.units.map((unit) => text(unit.counterargument)).find(Boolean) ||
+    group.units
+      .filter((unit) => normalized(unit.kind) === "counterargument")
+      .map((unit) => text(unit.summary))
+      .find(Boolean) ||
+    ""
+  );
+}
+
+function groupRebuttal(group) {
+  return (
+    group.units.map((unit) => text(unit.rebuttal)).find(Boolean) ||
+    group.units
+      .filter((unit) => normalized(unit.kind) === "rebuttal")
+      .map((unit) => text(unit.summary))
+      .find(Boolean) ||
+    ""
+  );
+}
+
+function groupAssets(group) {
+  return group.units.flatMap((unit) =>
+    Array.isArray(unit.assets) ? unit.assets : [],
+  );
+}
+
+function candidateFunctions(kind) {
+  return KIND_FUNCTIONS[kind] || ["analysis", "explain"];
+}
+
+function candidateScore(slide, {
+  kind,
+  unitCount,
+  fragments,
+  assets,
+  previousSourceSlide,
+  previousFamily,
+}) {
+  if (slide.safetyStatus !== "automatic") return Number.NEGATIVE_INFINITY;
+  if (EXEMPT_FAMILIES.has(slide.layoutFamily)) return Number.NEGATIVE_INFINITY;
+  const requiredAssets = (slide.assetRequirements || []).filter(
+    (item) => item.required,
+  );
+  if (
+    requiredAssets.some(
+      (requirement) =>
+        !assets.some((asset) => normalized(asset.type || "image") === normalized(requirement.type)),
+    )
+  ) {
+    return Number.NEGATIVE_INFINITY;
+  }
+  const requiredSlots = (slide.slotSchema || []).filter(
+    (slot) =>
+      slot.purpose !== "pageNumber" &&
+      !["header", "footer", "sidelabel"].includes(normalized(slot.purpose)),
+  );
+  const textSlots = requiredSlots.filter((slot) => slot.type === "text");
+  const visualSlots = requiredSlots.filter((slot) => slot.type !== "text");
+  const suppliedVisuals = assets.length;
+  if (visualSlots.length > suppliedVisuals) return Number.NEGATIVE_INFINITY;
+  if (textSlots.length > fragments.length + 2) return Number.NEGATIVE_INFINITY;
+
+  const desired = candidateFunctions(kind);
+  const actual = new Set([
+    ...(slide.communicationFunctions || []),
+    ...(slide.narrativeRoles || []),
+  ]);
+  const overlap = desired.filter((item) => actual.has(item)).length;
+  const recommended = slide.contentRecipe?.recommendedSourceUnits || {};
+  let score = overlap * 28;
+  score += slide.layoutFamily === kind ? 20 : 0;
+  score += unitCount >= Number(recommended.min || 1) ? 6 : -4;
+  score += unitCount <= Number(recommended.max || 3) ? 12 : -22;
+  score += Math.min(10, Number(slide.confidence || 0) * 10);
+  score -= Math.abs(textSlots.length - Math.min(textSlots.length, fragments.length)) * 5;
+  if (slide.sourceSlide === previousSourceSlide) score -= 28;
+  if (slide.layoutFamily === previousFamily) score -= 8;
+  return score;
+}
+
+function chooseRecipe(profile, context) {
+  const rank = (candidateContext) =>
+    profile.slides
+      .map((slide) => ({
+        slide,
+        score: candidateScore(slide, candidateContext),
+      }))
+      .filter((item) => Number.isFinite(item.score))
+      .sort(
+        (left, right) =>
+          right.score - left.score ||
+          Number(left.slide.sourceSlide) - Number(right.slide.sourceSlide),
+      );
+  let ranked = rank(context);
+  if (ranked[0] && ranked[0].score < 12) {
+    ranked = rank({
+      ...context,
+      previousSourceSlide: null,
+      previousFamily: null,
+    });
+  }
+  if (ranked[0] && ranked[0].score < 12) return null;
+  if (
+    ranked[0] &&
+    ranked[1] &&
+    ranked[0].score - ranked[1].score <= 6 &&
+    Number(ranked[0].slide.sourceSlide) !==
+      Number(ranked[1].slide.sourceSlide)
+  ) {
+    const error = new Error(
+      `Template selection is ambiguous between source slides ${ranked[0].slide.sourceSlide} and ${ranked[1].slide.sourceSlide}`,
+    );
+    error.code = "TEMPLATE_SELECTION_AMBIGUOUS";
+    error.details = {
+      candidates: ranked.slice(0, 4).map((item) => ({
+        sourceSlide: item.slide.sourceSlide,
+        layoutFamily: item.slide.layoutFamily,
+        score: Number(item.score.toFixed(3)),
+      })),
+      context: {
+        kind: context.kind,
+        unitCount: context.unitCount,
+      },
+    };
+    throw error;
+  }
+  return ranked[0] || null;
+}
+
+function chooseExemptRecipe(profile, familyCandidates, previousSourceSlide = null) {
+  const wanted = new Set(familyCandidates);
+  return profile.slides
+    .filter(
+      (slide) =>
+        slide.safetyStatus === "automatic" &&
+        (wanted.has(slide.layoutFamily) ||
+          (slide.narrativeRoles || []).some((role) => wanted.has(role))),
+    )
+    .sort(
+      (left, right) =>
+        Number(left.sourceSlide === previousSourceSlide) -
+          Number(right.sourceSlide === previousSourceSlide) ||
+        Number(right.confidence || 0) - Number(left.confidence || 0) ||
+        Number(left.sourceSlide) - Number(right.sourceSlide),
+    )[0];
+}
+
+function valueFitsSlot(value, slot) {
+  if (slot.type !== "text") return true;
+  const stringValue = String(value || "");
+  const units = textWidthUnits(stringValue);
+  if (Number(slot.maxTextUnits || 0) > 0) {
+    return units <= Number(slot.maxTextUnits) + 0.01;
+  }
+  if (Number(slot.maxChars || 0) > 0) {
+    return nonWhitespaceChars(stringValue) <= Number(slot.maxChars);
+  }
+  return true;
+}
+
+function fitTextForSlot(values, slot, used) {
+  for (const value of values) {
+    if (used.has(value)) continue;
+    if (valueFitsSlot(value, slot)) {
+      used.add(value);
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function valuesForSlotPurpose(slot, fragmentRecords, fallbackValues) {
+  const purpose = normalized(slot.purpose);
+  const aliases = {
+    date: ["date", "time", "year", "period"],
+    label: ["label", "step", "item", "tag", "metric-label", "category"],
+    body: ["body", "description", "detail", "evidence", "explanation"],
+    subtitle: ["subtitle", "summary", "context"],
+    title: ["title", "claim"],
+  };
+  const wanted = new Set(aliases[purpose] || [purpose]);
+  const matched = fragmentRecords
+    .filter((record) => wanted.has(normalized(record.displayRole)))
+    .map((record) => record.text);
+  return [...new Set([...matched, ...fallbackValues])];
+}
+
+function assetForSlot(assets, slot, usedAssets) {
+  for (const [index, asset] of assets.entries()) {
+    if (usedAssets.has(index)) continue;
+    const assetType = normalized(asset.type || "image");
+    const slotType = normalized(slot.semanticType || slot.type);
+    if (
+      assetType === slotType ||
+      (assetType === "image" && ["image", "icon"].includes(slotType))
+    ) {
+      usedAssets.add(index);
+      return asset.value || asset;
+    }
+  }
+  return undefined;
+}
+
+function fillRecipeFields({
+  slide,
+  title,
+  subtitle,
+  fragments,
+  fragmentRecords = [],
+  assets,
+  brief,
+}) {
+  const fields = {};
+  const used = new Set();
+  const usedAssets = new Set();
+  const textPool = [
+    ...new Set(
+      fragments.filter(
+        (value) => value && value !== title && value !== subtitle,
+      ),
+    ),
+    subtitle,
+    title,
+  ].filter(Boolean);
+  for (const slot of slide.slotSchema || []) {
+    const purpose = normalized(slot.purpose);
+    if (purpose === "pagenumber") continue;
+    if (slot.type === "text") {
+      let value;
+      if (purpose === "title") value = title;
+      else if (purpose === "subtitle") value = subtitle || title;
+      else if (purpose === "footer") value = text(brief.footer) || text(brief.organization);
+      else if (purpose === "header") value = text(brief.header) || text(brief.title);
+      else if (purpose === "sidelabel") value = text(brief.sideLabel) || text(brief.useCase);
+      if (!value || !valueFitsSlot(value, slot)) {
+        value = fitTextForSlot(
+          valuesForSlotPurpose(slot, fragmentRecords, textPool),
+          slot,
+          used,
+        );
+      }
+      if (value === undefined) {
+        return {
+          passed: false,
+          reason: `No source-derived value fits text slot ${slot.slotId}`,
+        };
+      }
+      fields[slot.slotId] = value;
+    } else {
+      const value = assetForSlot(assets, slot, usedAssets);
+      if (value === undefined) {
+        return {
+          passed: false,
+          reason: `No supplied asset fits ${slot.type} slot ${slot.slotId}`,
+        };
+      }
+      fields[slot.slotId] = value;
+    }
+  }
+  return { passed: true, fields };
+}
+
+function composeSpeakerNotes(group, claim, evidence, whyItMatters, counterargument, rebuttal) {
+  const sourcedParagraphs = group.units.flatMap((unit) => {
+    const primary =
+      text(unit.text) ||
+      text(unit.detail) ||
+      text(unit.summary) ||
+      "";
+    const supplemental = [
+      text(unit.claim),
+      ...asStrings(unit.evidence),
+      text(unit.whyItMatters),
+      text(unit.counterargument),
+      text(unit.rebuttal),
+    ].filter((value) => value && value !== primary);
+    return [primary, ...supplemental].filter(Boolean).map((value, index) => ({
+      fragmentId: `${unit.id}:notes:${index + 1}`,
+      sourceUnitId: String(unit.id),
+      sourceField: index === 0 ? "text" : "semantic",
+      text: value,
+      destination: "speakerNotes",
+    }));
+  });
+  const spokenParagraphs = [
+    `本页结论：${claim}。`,
+    evidence.length ? `主要依据：${evidence.join("；")}。` : "",
+    `分析意义：${whyItMatters}。`,
+    counterargument ? `可能的反方意见：${counterargument}。` : "",
+    rebuttal ? `对此回应：${rebuttal}。` : "",
+  ].filter(Boolean);
+  let spokenText = [...new Set(spokenParagraphs)].join("\n");
+  if (nonWhitespaceChars(spokenText) < 150) {
+    spokenText += `\n讲解时应把结论、依据与推理之间的关系讲完整，并指出本页事实或规则为什么会改变最终判断，不能只念标题。`;
+  }
+  const sourceReferenceText = [
+    ...new Set(sourcedParagraphs.map((record) => record.text)),
+  ].join("\n");
+  const notes = [
+    spokenText,
+    sourceReferenceText
+      ? `[来源追踪，不逐字朗读]\n${sourceReferenceText}`
+      : "",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+  return {
+    text: notes,
+    spokenText,
+    trace: sourcedParagraphs.filter((record) => notes.includes(record.text)),
+  };
+}
+
+function buildContentSlide({
+  group,
+  slide,
+  outputSlide,
+  section,
+  brief,
+}) {
+  const kind = primaryKind(group.units);
+  const claim = groupClaim(group);
+  const evidence = groupEvidence(group);
+  const whyItMatters = groupWhy(group);
+  const counterargument = groupCounterargument(group);
+  const rebuttal = groupRebuttal(group);
+  const fragmentRecords = groupFragmentRecords(group);
+  const uniqueFragments = [
+    ...new Set(fragmentRecords.map((record) => record.text)),
+  ];
+  const filled = fillRecipeFields({
+    slide,
+    title: claim,
+    subtitle: text(group.units[0]?.topicTitle) || text(group.title),
+    fragments: uniqueFragments,
+    fragmentRecords,
+    assets: groupAssets(group),
+    brief,
+  });
+  if (!filled.passed) throw new Error(filled.reason);
+  const visibleTrace = visibleTraceForFields(filled.fields, fragmentRecords);
+  if (!allUnitsVisible(group, visibleTrace)) {
+    throw new Error(
+      `Template page ${slide.sourceSlide} does not visibly represent every mapped source unit`,
+    );
+  }
+  const notes = composeSpeakerNotes(
+    group,
+    claim,
+    evidence,
+    whyItMatters,
+    counterargument,
+    rebuttal,
+  );
+  const role = KIND_ROLE[kind] || "analysis";
+  return {
+    outputSlide,
+    sourceSlide: slide.sourceSlide,
+    narrativeRole: role,
+    layoutFamily: slide.layoutFamily,
+    layoutVariant: slide.layoutVariant || undefined,
+    title: claim,
+    sourceUnitIds: group.units.map((unit) => String(unit.id)),
+    claim,
+    evidence,
+    whyItMatters,
+    counterargument: counterargument || undefined,
+    rebuttal: rebuttal || undefined,
+    speakerNotes: notes.text,
+    spokenText: notes.spokenText,
+    sourceTrace: {
+      visible: visibleTrace,
+      speakerNotes: notes.trace,
+    },
+    estimatedSeconds: Math.max(
+      35,
+      Math.ceil(nonWhitespaceChars(notes.spokenText) / 4.2),
+    ),
+    section,
+    fields: filled.fields,
+    templateSelection: {
+      mode: "adaptive-template-intelligence",
+      sourceSlide: slide.sourceSlide,
+      profileConfidence: slide.confidence,
+      communicationFunctions: slide.communicationFunctions,
+    },
+  };
+}
+
+function splitGroupToFit(group, profile, state) {
+  const results = [];
+  let queue = [...group.units];
+  while (queue.length) {
+    let accepted = null;
+    for (let count = queue.length; count >= 1; count -= 1) {
+      const subset = {
+        ...group,
+        units: queue.slice(0, count),
+      };
+      const kind = primaryKind(subset.units);
+      const fragmentRecords = groupFragmentRecords(subset);
+      const fragments = [...new Set(fragmentRecords.map((record) => record.text))];
+      const candidate = chooseRecipe(profile, {
+        kind,
+        unitCount: subset.units.length,
+        fragments,
+        assets: groupAssets(subset),
+        previousSourceSlide: state.previousSourceSlide,
+        previousFamily: state.previousFamily,
+      });
+      if (!candidate) continue;
+      const filled = fillRecipeFields({
+        slide: candidate.slide,
+        title: groupClaim(subset),
+        subtitle: text(subset.units[0]?.topicTitle) || text(subset.title),
+        fragments: [...new Set(fragments)],
+        fragmentRecords,
+        assets: groupAssets(subset),
+        brief: state.brief,
+      });
+      if (!filled.passed) continue;
+      const visibleTrace = visibleTraceForFields(filled.fields, fragmentRecords);
+      if (!allUnitsVisible(subset, visibleTrace)) continue;
+      const notes = composeSpeakerNotes(
+        subset,
+        groupClaim(subset),
+        groupEvidence(subset),
+        groupWhy(subset),
+        groupCounterargument(subset),
+        groupRebuttal(subset),
+      );
+      const visibleChars = [
+        ...new Set(
+          Object.values(filled.fields)
+            .filter((value) => typeof value === "string")
+            .map(text)
+            .filter(Boolean),
+        ),
+      ].reduce((sum, value) => sum + nonWhitespaceChars(value), 0);
+      const notesChars = nonWhitespaceChars(notes.text);
+      if (visibleChars > 180 || notesChars > 600) continue;
+      accepted = { subset, slide: candidate.slide };
+      break;
+    }
+    if (!accepted) {
+      throw new Error(
+        `No approved template page can safely express source unit ${queue[0]?.id}. ` +
+          "Use a different template, supply required assets, or approve a suitable source page.",
+      );
+    }
+    results.push(accepted);
+    state.previousSourceSlide = accepted.slide.sourceSlide;
+    state.previousFamily = accepted.slide.layoutFamily;
+    queue = queue.slice(accepted.subset.units.length);
+  }
+  return results;
+}
+
+function buildExemptSlide({
+  slide,
+  outputSlide,
+  role,
+  title,
+  subtitle,
+  fragments,
+  brief,
+  estimatedSeconds,
+}) {
+  const filled = fillRecipeFields({
+    slide,
+    title,
+    subtitle,
+    fragments,
+    assets: [],
+    brief,
+  });
+  if (!filled.passed) {
+    throw new Error(
+      `Template source slide ${slide.sourceSlide} cannot be used as ${role}: ${filled.reason}`,
+    );
+  }
+  return {
+    outputSlide,
+    sourceSlide: slide.sourceSlide,
+    narrativeRole: role,
+    layoutFamily: slide.layoutFamily,
+    layoutVariant: slide.layoutVariant || undefined,
+    title,
+    subtitle,
+    sourceUnitIds: [],
+    speakerNotes: subtitle || title,
+    estimatedSeconds,
+    fields: filled.fields,
+    templateSelection: {
+      mode: "adaptive-template-intelligence",
+      sourceSlide: slide.sourceSlide,
+      profileConfidence: slide.confidence,
+      communicationFunctions: slide.communicationFunctions,
+    },
+  };
+}
+
+function durationPolicy(brief, coreSlides) {
+  const configured = brief.durationSeconds || {};
+  const minimum = Number(configured.min || 0);
+  const maximum = Number(configured.max || 0);
+  const estimated = coreSlides.reduce(
+    (sum, slide) => sum + Number(slide.estimatedSeconds || 0),
+    0,
+  );
+  const criticalSeconds = coreSlides
+    .filter((slide) => slide.critical === true)
+    .reduce((sum, slide) => sum + Number(slide.estimatedSeconds || 0), 0);
+  return {
+    requested: maximum > 0,
+    minimum,
+    maximum,
+    estimated,
+    criticalSeconds,
+    criticalConflict: maximum > 0 && criticalSeconds > maximum,
+    conflict: maximum > 0 && estimated > maximum,
+    overflowSeconds: maximum > 0 ? Math.max(0, estimated - maximum) : 0,
+  };
+}
+
+export function buildAdaptiveContentPlan(sourceMap, templateProfile, options = {}) {
+  validateSourceMap(sourceMap);
+  const brief = {
+    title: text(sourceMap.presentationBrief?.title) || "演示文稿",
+    audience: text(sourceMap.presentationBrief?.audience),
+    communicationJob: text(sourceMap.presentationBrief?.communicationJob),
+    useCase: normalized(sourceMap.presentationBrief?.useCase || "general-report"),
+    density: normalized(options.density || sourceMap.presentationBrief?.density || "rich"),
+    scope: normalized(options.scope || sourceMap.presentationBrief?.scope || "core-and-appendix"),
+    durationSeconds:
+      options.durationSeconds || sourceMap.presentationBrief?.durationSeconds || {},
+    footer: text(sourceMap.presentationBrief?.footer),
+    header: text(sourceMap.presentationBrief?.header),
+    sideLabel: text(sourceMap.presentationBrief?.sideLabel),
+    subtitle: text(sourceMap.presentationBrief?.subtitle),
+    author: text(sourceMap.presentationBrief?.author),
+    organization: text(sourceMap.presentationBrief?.organization),
+    date: text(sourceMap.presentationBrief?.date),
+    visualMode: normalized(sourceMap.presentationBrief?.visualMode),
+  };
+  const fit = assessTemplateFit(templateProfile, brief);
+  if (fit.recommendedMode === "recommend-other-template" && options.allowLowFit !== true) {
+    throw new Error(
+      `Template fit is ${fit.score}; missing capabilities: ${fit.missingCapabilities.join(", ")}. ` +
+        "Choose another template or explicitly use style-only mode.",
+    );
+  }
+
+  const allUnits = sourceMap.sourceUnits.map((unit) => ({
+    ...unit,
+    id: String(unit.id),
+    priority: sourcePriority(unit),
+    presentationRelevance: sourceRelevance(unit),
+  }));
+  const coreUnits = allUnits.filter(
+    (unit) => unit.presentationRelevance === "core",
+  );
+  const appendixUnits = allUnits.filter(
+    (unit) => unit.presentationRelevance === "appendix",
+  );
+  const excludedUnits = allUnits.filter(
+    (unit) => unit.presentationRelevance === "exclude",
+  );
+  const state = {
+    brief,
+    previousSourceSlide: null,
+    previousFamily: null,
+  };
+  const slides = [];
+
+  const cover = chooseExemptRecipe(templateProfile, ["cover", "opening"]);
+  if (!cover) throw new Error("Template has no approved cover/opening page");
+  slides.push(
+    buildExemptSlide({
+      slide: cover,
+      outputSlide: 1,
+      role: "opening",
+      title: brief.title,
+      subtitle:
+        brief.subtitle ||
+        [brief.author, brief.organization, brief.date].filter(Boolean).join(" · "),
+      fragments: [
+        brief.communicationJob,
+        brief.author,
+        brief.organization,
+        brief.date,
+      ].filter(Boolean),
+      brief,
+      estimatedSeconds: 20,
+    }),
+  );
+  state.previousSourceSlide = cover.sourceSlide;
+  state.previousFamily = cover.layoutFamily;
+
+  const coreGroups = groupUnits(coreUnits);
+  const appendixGroups = groupUnits(appendixUnits);
+  const agenda = chooseExemptRecipe(
+    templateProfile,
+    ["agenda", "roadmap"],
+    state.previousSourceSlide,
+  );
+  if (agenda && coreGroups.length >= 3) {
+    const agendaTitles = coreGroups
+      .map((group) => text(group.title))
+      .filter(Boolean)
+      .slice(0, 8);
+    slides.push(
+      buildExemptSlide({
+        slide: agenda,
+        outputSlide: slides.length + 1,
+        role: "agenda",
+        title: "内容路线",
+        subtitle: brief.communicationJob,
+        fragments: agendaTitles,
+        brief,
+        estimatedSeconds: 25,
+      }),
+    );
+    state.previousSourceSlide = agenda.sourceSlide;
+    state.previousFamily = agenda.layoutFamily;
+  }
+
+  const coreContentSlides = [];
+  for (const group of coreGroups) {
+    for (const planned of splitGroupToFit(group, templateProfile, state)) {
+      const slide = buildContentSlide({
+        group: planned.subset,
+        slide: planned.slide,
+        outputSlide: slides.length + coreContentSlides.length + 1,
+        section: "core",
+        brief,
+      });
+      slide.critical = planned.subset.units.some(
+        (unit) => unit.priority === "critical",
+      );
+      coreContentSlides.push(slide);
+    }
+  }
+  slides.push(...coreContentSlides);
+
+  const duration = durationPolicy(brief, slides);
+  if (duration.conflict) {
+    const error = new Error(
+      `Complete planned content needs about ${duration.estimated} seconds, exceeding the requested maximum ${duration.maximum}. ` +
+        "Extend the duration, narrow the scope, or split the presentation.",
+    );
+    error.code = "DURATION_CONFLICT";
+    error.details = duration;
+    throw error;
+  }
+
+  if (brief.scope !== "core-only" && appendixGroups.length) {
+    const divider = chooseExemptRecipe(
+      templateProfile,
+      ["divider", "section"],
+      state.previousSourceSlide,
+    );
+    if (divider) {
+      slides.push(
+        buildExemptSlide({
+          slide: divider,
+          outputSlide: slides.length + 1,
+          role: "section",
+          title: "补充材料",
+          subtitle: "用于课后回看与问答",
+          fragments: ["附录", "补充证据", "备用材料"],
+          brief,
+          estimatedSeconds: 10,
+        }),
+      );
+      state.previousSourceSlide = divider.sourceSlide;
+      state.previousFamily = divider.layoutFamily;
+    }
+    for (const group of appendixGroups) {
+      for (const planned of splitGroupToFit(group, templateProfile, state)) {
+        slides.push(
+          buildContentSlide({
+            group: planned.subset,
+            slide: planned.slide,
+            outputSlide: slides.length + 1,
+            section: "appendix",
+            brief,
+          }),
+        );
+      }
+    }
+  }
+
+  const closing = chooseExemptRecipe(
+    templateProfile,
+    ["closing"],
+    state.previousSourceSlide,
+  );
+  if (closing) {
+    const conclusion =
+      allUnits
+        .filter((unit) =>
+          ["conclusion", "recommendation"].includes(normalized(unit.kind)),
+        )
+        .map((unit) => text(unit.summary))
+        .find(Boolean) || brief.communicationJob || brief.title;
+    slides.push(
+      buildExemptSlide({
+        slide: closing,
+        outputSlide: slides.length + 1,
+        role: "closing",
+        title: conclusion,
+        subtitle: "谢谢",
+        fragments: [conclusion, "Q&A", "谢谢"],
+        brief,
+        estimatedSeconds: 20,
+      }),
+    );
+  }
+
+  slides.forEach((slide, index) => {
+    slide.outputSlide = index + 1;
+    delete slide.critical;
+  });
+  const plan = {
+    schemaVersion: 2,
+    title: brief.title,
+    audience: brief.audience,
+    communicationJob: brief.communicationJob,
+    presentationBrief: brief,
+    templateFit: fit,
+    deckPolicy: {
+      strictMode: true,
+      fidelityMode:
+        templateProfile.templateKind === "flattened-deck"
+          ? "hybrid-locked"
+          : "exact-native",
+      adaptiveContent: true,
+      templateMode:
+        options.templateMode || fit.recommendedMode || "inherit-narrative",
+      candidateLimit: 24,
+      beamWidth: 192,
+      ambiguityThreshold: 6,
+      localAmbiguityThreshold: 6,
+      contentAudit: {
+        adaptiveTotals: true,
+        requireTraceableCoverage: true,
+        criticalCoverageMin: 1,
+        weightedCoverageMin: 0.95,
+        criticalVisibleCoverageMin: 1,
+        weightedVisibleCoverageMin: 0.9,
+        sourceTextCoverageMin: 1,
+        visibleCharsPerContentSlide: {
+          min: 55,
+          max: 180,
+          enforce: true,
+        },
+        speakerNotesCharsPerContentSlide: {
+          min: 150,
+          max: 600,
+          enforce: true,
+        },
+        durationScope: "core-only",
+        durationSeconds: brief.durationSeconds,
+        exemptNarrativeRoles: [
+          "opening",
+          "agenda",
+          "roadmap",
+          "section",
+          "reference",
+          "references",
+          "closing",
+        ],
+      },
+    },
+    sourceUnits: allUnits,
+    excludedSourceUnits: excludedUnits.map((unit) => ({
+      id: unit.id,
+      reason: text(unit.exclusionReason) || "Marked out of presentation scope",
+    })),
+    slides,
+    planningSummary: {
+      sourceUnitCount: allUnits.length,
+      sourceCharacterCount: allUnits.reduce(
+        (sum, unit) =>
+          sum + nonWhitespaceChars(text(unit.detail) || text(unit.text)),
+        0,
+      ),
+      argumentNodeCount: allUnits.reduce(
+        (sum, unit) =>
+          sum +
+          [
+            unit.claim,
+            ...(Array.isArray(unit.evidence) ? unit.evidence : [unit.evidence]),
+            unit.whyItMatters,
+            unit.counterargument,
+            unit.rebuttal,
+          ].filter((value) => text(value)).length,
+        0,
+      ),
+      coreSourceUnitCount: coreUnits.length,
+      appendixSourceUnitCount: appendixUnits.length,
+      excludedSourceUnitCount: excludedUnits.length,
+      coreSlideCount: slides.filter((slide) => slide.section !== "appendix").length,
+      appendixSlideCount: slides.filter((slide) => slide.section === "appendix").length,
+      outputSlideCount: slides.length,
+      estimatedCoreSeconds: slides
+        .filter((slide) => slide.section !== "appendix")
+        .reduce((sum, slide) => sum + Number(slide.estimatedSeconds || 0), 0),
+      estimatedTotalSeconds: slides.reduce(
+        (sum, slide) => sum + Number(slide.estimatedSeconds || 0),
+        0,
+      ),
+      durationPolicy: duration,
+      templateProfileFingerprint: templateProfile.profileFingerprint,
+    },
+  };
+  plan.planningFingerprint = fingerprint({
+    sourceMapFingerprint: fingerprint(sourceMap),
+    templateProfileFingerprint: templateProfile.profileFingerprint,
+    brief,
+    slides,
+  });
+  return plan;
+}
+
+function parseDuration(value) {
+  const stringValue = text(value);
+  if (!stringValue) return undefined;
+  const range = stringValue.match(/^(\d+)(?:\s*-\s*(\d+))?$/);
+  if (!range) {
+    throw new Error("--duration must be minutes such as 12 or 12-15");
+  }
+  const minMinutes = Number(range[1]);
+  const maxMinutes = Number(range[2] || range[1]);
+  return {
+    min: minMinutes * 60,
+    max: maxMinutes * 60,
+  };
+}
+
+function usage() {
+  return [
+    "Usage:",
+    "  node plan-adaptive-content.mjs --source-map <source-map.json>",
+    "       --template-profile <template-profile-v2.json> --out <content-plan.json>",
+    "       [--duration 12-15] [--density rich] [--scope core-and-appendix]",
+    "       [--template-mode style-only] [--allow-low-fit]",
+  ].join("\n");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+  const sourceMapPath = path.resolve(requireArg(args, "source-map"));
+  const profilePath = path.resolve(requireArg(args, "template-profile"));
+  const outPath = path.resolve(requireArg(args, "out"));
+  const sourceMap = await readJson(sourceMapPath);
+  const templateProfile = await readJson(profilePath);
+  const plan = buildAdaptiveContentPlan(sourceMap, templateProfile, {
+    durationSeconds: parseDuration(args.duration),
+    density: args.density,
+    scope: args.scope,
+    templateMode: args["template-mode"],
+    allowLowFit: args["allow-low-fit"] === true,
+  });
+  const audit = auditContentPlan(plan, { planPath: outPath });
+  if (!audit.passed) {
+    throw new Error(
+      `Adaptive content audit failed:\n- ${audit.errors.join("\n- ")}`,
+    );
+  }
+  await writeJson(outPath, plan);
+  console.log(
+    JSON.stringify(
+      {
+        out: outPath,
+        sourceUnits: plan.planningSummary.sourceUnitCount,
+        outputSlides: plan.planningSummary.outputSlideCount,
+        coreSlides: plan.planningSummary.coreSlideCount,
+        appendixSlides: plan.planningSummary.appendixSlideCount,
+        estimatedCoreSeconds: plan.planningSummary.estimatedCoreSeconds,
+        templateFit: plan.templateFit,
+        planningFingerprint: plan.planningFingerprint,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+const isMain =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) {
+  main().catch((error) => {
+    console.error(error.stack || error.message || String(error));
+    if (error.details) console.error(JSON.stringify(error.details, null, 2));
+    console.error(usage());
+    process.exit(error.code === "DURATION_CONFLICT" ? 2 : 1);
+  });
+}