dsh-plugin-deck-studio 0.2.5 → 0.2.8

package/lib/review-readers.js

@@ -0,0 +1,300 @@
+/**
+ * 听众评审的「人话版」报告（F-186）。
+ *
+ * 背景：`review.experts.md` 是工程口径（覆盖矩阵 / 判定表 / 证据 / P0-P1），负责人和听众都读不进去。
+ * 这里**不产生新判断**，只把已有的盲审 + 对照结果翻译成两本人能读的文档：
+ *
+ * - `docs/review.readers.md`：听众视角——读完记住什么、连贯吗、结构清楚吗、哪里不信、还想知道什么；
+ * - `docs/review.gap.md`：负责人视角——意图要什么 vs 听众读到什么、差距、先改哪三页、哪几件要拍板。
+ *
+ * 纪律：读者文档里不出现 P0/P1、置信度 A/B/C、交叉确认这类内部词——这些留在 gap 文档的「附：内部口径」。
+ * 所有句子都由输入模板拼出来（不调模型），所以同一份评审结果每次渲染一致、可复算。
+ *
+ * @module dsh-plugin-deck-studio/review-readers
+ */
+
+const s = (value) => String(value ?? "").trim();
+/** 引号内再套句号会变成「…。」。」，渲染前先削掉末尾标点。 */
+const trimTail = (value) => s(value).replace(/[。；;，,、\s]+$/u, "");
+const firstSentence = (text, limit = 40) => {
+  const clean = s(text).replace(/\s+/g, " ");
+  if (!clean) return "";
+  const cut = clean.match(/^.*?[。！？!?;；]/);
+  const body = cut ? cut[0] : clean;
+  return body.length > limit ? `${body.slice(0, limit)}…` : body;
+};
+
+const severityRank = { 否: 0, 部分: 1, 是: 2 };
+
+/** 分数可能是 number 或 {mean, n}（合并后的四维分）——渲染时统一取均值。 */
+const meanOf = (value) => {
+  if (typeof value === "number") return Number.isInteger(value) ? value : Number(value.toFixed(2));
+  if (value && typeof value === "object" && typeof value.mean === "number") {
+    return Number.isInteger(value.mean) ? value.mean : Number(value.mean.toFixed(2));
+  }
+  return "—";
+};
+
+/** 两位听众常问同一件事：按前 20 字归一化后去重，避免「还想知道」念两遍。 */
+const dedupeBySimilarity = (items = [], limit = 3) => {
+  const seen = [];
+  const out = [];
+  for (const raw of items) {
+    const text = s(raw);
+    if (!text) continue;
+    const key = text.replace(/[\s\u3000「」『』“”"'，。；！？、—…]/g, "").slice(0, 20);
+    if (seen.some((item) => item === key || item.startsWith(key) || key.startsWith(item))) continue;
+    seen.push(key);
+    out.push(text);
+    if (out.length >= limit) break;
+  }
+  return out;
+};
+
+/** 整本一句话：听众记住了什么（用第一页的复述 + 全本读者自述）。 */
+export function readerHeadline({ gaps = [], mergedBlind = [], deckGap = "" } = {}) {
+  const pages = new Map(mergedBlind.map((row) => [row.page, row.answers?.[0] ?? {}]));
+  const firstPage = [...pages.keys()].sort((a, b) => a.localeCompare(b))[0];
+  const remembered = firstSentence(pages.get(firstPage)?.restate ?? "", 60);
+  const failed = gaps.filter((gap) => gap.verdict !== "是");
+  const halfPages = failed.filter((gap) => gap.verdict === "部分").length;
+  const missed = failed.filter((gap) => gap.verdict === "否").length;
+  const worst = [...failed].sort((a, b) => (severityRank[a.verdict] ?? 3) - (severityRank[b.verdict] ?? 3))[0];
+  const whole = firstSentence(deckGap, 80);
+  const parts = [];
+  if (remembered) parts.push(`听众读完记住的是「${trimTail(remembered)}」`);
+  if (failed.length) {
+    const detail = [halfPages ? `${halfPages} 页只接住一半` : "", missed ? `${missed} 页没接住` : ""].filter(Boolean).join("、");
+    parts.push(`${gaps.length} 页里，${detail}${worst ? `，最要紧的是第 ${worst.page.replace(/^P0*/, "")} 页` : ""}`);
+  } else if (gaps.length) {
+    parts.push("每页都被接住了");
+  }
+  if (whole) parts.push(`听众自己的总结是：「${whole}」`);
+  return `${parts.join("；")}。`;
+}
+
+/** 听众读后感的五问五答（全部来自盲审 + 对照，不新增判断）。 */
+export function readerImpression({ gaps = [], mergedBlind = [], deckGap = "" } = {}) {
+  const answers = mergedBlind.flatMap((row) => (row.answers ?? []).map((answer) => ({ ...answer, from: answer.from ?? "" })));
+  const pages = mergedBlind.map((row) => row.page);
+  const relations = new Map();
+  for (const row of mergedBlind) {
+    for (const answer of row.answers ?? []) {
+      if (!relations.has(row.page)) relations.set(row.page, answer.relation);
+    }
+  }
+  const relationChain = pages.map((page) => relations.get(page)).filter(Boolean);
+  const broken = [...relations.entries()].filter(([, relation]) => /无|没有|说不清|不知道|断/.test(s(relation))).map(([page]) => page);
+  const doubts = [...new Set(answers.map((answer) => firstSentence(answer.doubt, 60)).filter(Boolean))].slice(0, 3);
+  const knownPages = mergedBlind.filter((row) => (row.answers ?? []).some((answer) => /知道|清楚/.test(s(answer.next_action)))).length;
+  const conflicts = gaps.filter((gap) => gap.verdict === "否");
+  const halfPages = gaps.filter((gap) => gap.verdict === "部分");
+
+  const learned = firstSentence([...new Set(answers.map((answer) => firstSentence(answer.restate, 50)).filter(Boolean))].join("；"), 120)
+    || "（听众没有留下复述，可能这页太抽象或太密）";
+  const coherence = broken.length
+    ? `第 ${broken.join(" / ").replace(/P0*/g, "")} 页和上一页的接不上：听众说不出这页和前面是什么关系。`
+    : relationChain.length
+      ? `页与页之间接得上（承接：${relationChain.slice(0, 6).join(" → ")}）${relationChain.length > 6 ? " …" : ""}。`
+      : "没有拿到承接信息。";
+  const structure = gaps.length
+    ? `整本 ${gaps.length} 页，${gaps.filter((gap) => gap.verdict === "是").length} 页完全接住、${halfPages.length} 页只接住一半、${conflicts.length} 页没接住；${knownPages ? `${knownPages} 页听众知道下一步做什么` : "多数页听众不知道下一步做什么"}。`
+    : "没有对照结果，无法判断结构。";
+  const contradiction = conflicts.length
+    ? `有 ${conflicts.length} 页听众没接住——读出来的重点和讲的人要的不一样（${conflicts.map((gap) => `第 ${gap.page.replace(/^P0*/, "")} 页`).join("、")}）。这不是前后矛盾，是这几页没把话说到听众能接住。`
+    : "没有发现听众读出与意图对不上的地方。";
+  const promises = dedupeBySimilarity(doubts);
+  const wishes = promises.length ? promises.map((doubt) => `「${doubt}」`).join("；") : "听众没有留下明确的追问。";
+  return { learned, coherence, structure, contradiction, wishes };
+}
+
+/** 听众视角 markdown。 */
+export function renderReaderReviewMarkdown({
+  deckTitle = "",
+  generatedAt = "",
+  audience = "",
+  gaps = [],
+  mergedBlind = [],
+  deckGap = "",
+  fixSuggestions = [],
+  pageTitles = {},
+} = {}) {
+  const headline = readerHeadline({ gaps, mergedBlind, deckGap });
+  const impression = readerImpression({ gaps, mergedBlind, deckGap });
+  const gapByPage = new Map();
+  for (const gap of gaps) {
+    if (!gapByPage.has(gap.page) || (severityRank[gap.verdict] ?? 3) < (severityRank[gapByPage.get(gap.page).verdict] ?? 3)) gapByPage.set(gap.page, gap);
+  }
+  const pageBlocks = mergedBlind.map((row) => {
+    const answers = row.answers ?? [];
+    const primary = answers[0] ?? {};
+    const others = answers.slice(1);
+    const gap = gapByPage.get(row.page);
+    const verdictLine = gap
+      ? gap.verdict === "是"
+        ? "被说服了：是"
+        : `被说服了一半：听众读出「${firstSentence(gap.x, 70)}」，你想让他们带走的是「${firstSentence(gap.y, 70)}」。`
+      : "这一页没有对照结论。";
+    const title = pageTitles[row.page] || "";
+    return [
+      `## 第 ${row.page.replace(/^P0*/, "")} 页${title ? ` · ${title}` : ""}`,
+      "",
+      `- 读者读到：${firstSentence(primary.restate, 120) || "（没有复述）"}`,
+      `- 和上一页的关系：${firstSentence(primary.relation, 30) || "（没答）"}`,
+      `- 读者想问：${firstSentence(primary.doubt, 120) || "（没有追问）"}`,
+      `- 下一步动作：${s(primary.next_action) || "（没答）"}`,
+      `- ${verdictLine}`,
+      gap?.fix ? `- 建议改法：${gap.fix}` : "",
+      others.length ? `- 另一位听众：${firstSentence(others[0].doubt || others[0].restate, 100)}` : "",
+      "",
+    ].filter((line) => line !== "" || true).join("\n");
+  });
+  const fixes = fixSuggestions.slice(0, 3);
+  return [
+    "---",
+    `title: ${deckTitle || "deck"} · 听众读后感`,
+    "status: draft",
+    "---",
+    "",
+    `# 听众读后感 · ${deckTitle || "（未命名 deck）"}`,
+    "",
+    `> 生成时间：${generatedAt || "（未记录）"}${audience ? ` · 听众：${audience}` : ""}`,
+    "> 这份文档只记录「听众读到了什么」，不改稿；改法建议在每页末尾，需要你确认后才落版。",
+    "",
+    "## 一句话",
+    "",
+    headline,
+    "",
+    "## 读完的感觉",
+    "",
+    `- **学到了什么**：${impression.learned}`,
+    `- **连贯吗**：${impression.coherence}`,
+    `- **结构清楚吗**：${impression.structure}`,
+    `- **有没有互相矛盾的地方**：${impression.contradiction}`,
+    `- **还想知道什么**：${impression.wishes}`,
+    "",
+    "## 逐页：听众读到了什么",
+    "",
+    ...pageBlocks.map((block) => block.replace(/\n{3,}/g, "\n\n")),
+    "## 听众建议先改的三处",
+    "",
+    ...(fixes.length
+      ? fixes.map((item, index) => `${index + 1}. 第 ${String(item.page ?? "").replace(/^P0*/, "")} 页：${item.fix || item.problem || "（改法未给）"}`)
+      : ["（本次没有需要改的地方）"]),
+    "",
+    "---",
+    "",
+    "> 内部口径（严重度、交叉确认、四维分）在 [review.gap.md](review.gap.md) 的「附：内部口径」，不用给听众看。",
+    "",
+  ].join("\n");
+}
+
+/** 负责人视角 markdown：意图 vs 听众的差距 + 需要拍板的事。 */
+export function renderGapReviewMarkdown({
+  deckTitle = "",
+  generatedAt = "",
+  scriptHash = "",
+  audience = "",
+  intentText = "",
+  gaps = [],
+  mergedBlind = [],
+  deckGap = "",
+  findings = [],
+  dropped = [],
+  scores = null,
+  titleChain = null,
+  fixSuggestions = [],
+} = {}) {
+  const counts = { 是: 0, 部分: 0, 否: 0 };
+  for (const gap of gaps) counts[gap.verdict] = (counts[gap.verdict] ?? 0) + 1;
+  const headline = readerHeadline({ gaps, mergedBlind, deckGap });
+  const impression = readerImpression({ gaps, mergedBlind, deckGap });
+  const gapByPage = new Map();
+  for (const gap of gaps) {
+    if (!gapByPage.has(gap.page) || (severityRank[gap.verdict] ?? 3) < (severityRank[gapByPage.get(gap.page).verdict] ?? 3)) gapByPage.set(gap.page, gap);
+  }
+  const rows = mergedBlind.map((row) => {
+    const gap = gapByPage.get(row.page);
+    const read = gap?.x || row.answers?.[0]?.restate || "";
+    const wanted = gap?.y || "";
+    const missing = gap ? (gap.verdict === "是" ? "—" : gap.verdict === "否" ? "听众读出的和意图相反或对不上" : "只讲到一半，缺「为什么/怎么做/凭什么」中的一块") : "无对照";
+    return `| ${row.page} | ${firstSentence(wanted, 60) || "（对照组没给）"} | ${firstSentence(read, 60) || "（没有复述）"} | ${missing} | ${firstSentence(gap?.fix, 60) || "—"} | ${gap ? (gap.verdict === "否" ? "P0" : gap.verdict === "部分" ? "P1" : "—") : "—"} |`;
+  });
+  const top = [...gapByPage.values()]
+    .filter((gap) => gap.verdict !== "是")
+    .sort((a, b) => (severityRank[a.verdict] ?? 3) - (severityRank[b.verdict] ?? 3))
+    .slice(0, 3);
+  const decisions = dedupeBySimilarity(
+    mergedBlind.flatMap((row) => (row.answers ?? []).map((answer) => firstSentence(answer.doubt, 70))),
+    3,
+  );
+  const scoreLine = scores?.average
+    ? `四维均分 ${meanOf(scores.average)}（表意清晰 ${meanOf(scores.dimensions?.["表意清晰"])} / 证据充分 ${meanOf(scores.dimensions?.["证据充分"])} / 结构连贯 ${meanOf(scores.dimensions?.["结构连贯"])} / 意图达成 ${meanOf(scores.dimensions?.["意图达成"])}）`
+    : "（本轮没有评分）";
+  return [
+    "---",
+    `title: ${deckTitle || "deck"} · 意图与听众差距`,
+    "status: draft",
+    "---",
+    "",
+    `# 意图 vs 听众 · 差距报告 · ${deckTitle || "（未命名 deck）"}`,
+    "",
+    `> 生成时间：${generatedAt || "（未记录）"}${scriptHash ? ` · 稿件哈希：\`${scriptHash}\`` : ""}${audience ? ` · 目标听众：${audience}` : ""}`,
+    "> 给负责人看的一页纸：你要他们带走什么、他们实际带走了什么、差在哪、先改哪几页。",
+    "",
+    "## 一、一页总结",
+    "",
+    `- **意图达成**：是 ${counts.是} 页 / 部分 ${counts.部分} 页 / 否 ${counts.否} 页。`,
+    `- **听众读后感到的差距**：${headline}`,
+    impression.wishes ? `- **还想知道什么**：${impression.wishes}` : "",
+    `- **先改哪几页**：${top.length ? top.map((gap) => `第 ${gap.page.replace(/^P0*/, "")} 页（${gap.verdict === "否" ? "听众没接住" : "只接住一半"}）`).join("、") : "本轮没有需要先改的页"}`,
+    intentText ? `- **你的意图**：${firstSentence(intentText, 100)}` : "",
+    "",
+    "## 二、逐页差距（意图要的 vs 听众读到的）",
+    "",
+    "| 页 | 意图要的 | 听众读到的 | 差距 | 建议改法 | 内部级别 |",
+    "|---|---|---|---|---|---|",
+    ...(rows.length ? rows : ["| — | （没有对照结果） | — | — | — | — |"]),
+    "",
+    "## 三、需要你拍板",
+    "",
+    ...(decisions.length ? decisions.map((item, index) => `${index + 1}. ${item}`) : ["（本轮听众没有提出需要业务决定的问题）"]),
+    "",
+    "## 四、附：内部口径（工程/下一轮看，不用给听众）",
+    "",
+    `- ${scoreLine}${scores?.compare?.line ? `；${scores.compare.line}` : ""}`,
+    `- 可采纳建议 ${findings.length} 条${findings.length ? `：${findings.map((item) => `${item.id}（${item.page}，${item.severity}，置信度 ${item.confidence}${item.crossReviewed ? "，交叉确认" : ""}）`).join("、")}` : ""}`,
+    dropped.length ? `- 无法核实 ${dropped.length} 条（C 类，禁止据此改稿）：${dropped.map((item) => `${item.id}（${item.page}）`).join("、")}` : "- 无法核实（C 类）：0 条",
+    titleChain ? `- 标题串读：${titleChain.verdict ?? "—"}${titleChain.reasons?.length ? `（${titleChain.reasons.slice(0, 2).join("；")}）` : ""}` : "",
+    fixSuggestions.length ? `- 建议清单（按页）：${fixSuggestions.slice(0, 6).map((item) => `${item.page}：${firstSentence(item.fix, 40)}`).join("；")}` : "",
+    "",
+  ]
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/\n*$/, "\n");
+}
+
+/** 工具正文用的人话摘要（3 行以内，先讲人话，再给路径）。 */
+export function plainReviewSummary({ deckTitle = "", gaps = [], mergedBlind = [], deckGap = "", readersDoc = "", gapDoc = "", missing = [] } = {}) {
+  const headline = readerHeadline({ gaps, mergedBlind, deckGap });
+  const gapByPage = new Map();
+  for (const gap of gaps) {
+    if (!gapByPage.has(gap.page) || (severityRank[gap.verdict] ?? 3) < (severityRank[gapByPage.get(gap.page).verdict] ?? 3)) gapByPage.set(gap.page, gap);
+  }
+  const top = [...gapByPage.values()]
+    .filter((gap) => gap.verdict !== "是")
+    .sort((a, b) => (severityRank[a.verdict] ?? 3) - (severityRank[b.verdict] ?? 3))
+    .slice(0, 3);
+  const lines = [`一句话：${headline}`];
+  if (!gaps.length) lines.push("没有有效的对照结果（审稿人全失败或没跑），不能据此判断稿件没有问题。");
+  if (top.length) {
+    lines.push(
+      `听众卡在哪（先改这几页）：${top
+        .map((gap) => `第 ${gap.page.replace(/^P0*/, "")} 页——听众读出「${firstSentence(gap.x, 26) || "（空）"}」，你要的是「${firstSentence(gap.y, 26) || "（空）"}」`)
+        .join("；")}`,
+    );
+  }
+  if (readersDoc) lines.push(`完整记录：听众人话版 ${readersDoc}；意图差距 + 拍板项 ${gapDoc}（内部口径在后者末尾）。`);
+  if (missing.length) lines.push(`没跑完的审稿人：${missing.join(" / ")}（结论不完整，要说明）`);
+  return lines.join("\n");
+}

package/lib/review-score.js

@@ -0,0 +1,198 @@
+/**
+ * 审稿四维评分 + 版本记录（智力升级 B3 / F-183）。
+ *
+ * 为什么要打分：审稿意见是「这页哪里不行」，分数是「这本 deck 整体在什么水平」。
+ * 只有分数落盘并带上 scriptHash / revision，两轮评审才能对照——否则「改完是不是更好了」
+ * 只能靠感觉，这正是审稿机制最容易空转的地方。
+ *
+ * 四个维度各 1–5 分（打分发生在**对照阶段之后**，评审已看过意图；盲审阶段仍然不打分，保持听众视角的干净）：
+ * - 表意清晰：读者能否一句话复述这页想让他记住什么；
+ * - 证据充分：主张有没有支撑（含「示意数据」是否讲明）；
+ * - 结构连贯：页与页的关系是否成立（承接 / 递进 / 转折）；
+ * - 意图达成：整本有没有做到 intent 的「带走」。
+ *
+ * 本模块是纯函数（prompt / 解析 / 合并 / 对照）；落盘走 `lib/review-score-store.js` 的薄封装。
+ */
+
+export const SCORE_DIMENSIONS = ["表意清晰", "证据充分", "结构连贯", "意图达成"];
+
+/** 打分 prompt：一次只出四维分 + 每维一句理由，不做新审稿（意见已由盲审 / 对照产出）。 */
+export function scoreReviewerPrompt({ reviewer, brief = {}, deckTitle = "", script = "", maxScriptChars = 60_000 }) {
+  const dimensions = SCORE_DIMENSIONS.map((dimension, index) => `${index + 1}. ${dimension}：1–5 分（5=最好）`).join("\n");
+  const intentLines = [
+    brief.audience ? `听众：${brief.audience}` : "",
+    brief.takeaway ? `要带走：${brief.takeaway}` : "",
+    brief.success ? `成功标准：${brief.success}` : "",
+  ].filter(Boolean);
+  const scriptText = String(script ?? "");
+  const clipped = scriptText.length > maxScriptChars ? `${scriptText.slice(0, maxScriptChars)}\n…（后略）` : scriptText;
+  return [
+    `你是这份分享的听众评审：${reviewer.label}`,
+    reviewer.focus,
+    "",
+    deckTitle ? `## 分享标题\n${deckTitle}` : "",
+    intentLines.length ? `## 作者意图\n${intentLines.join("\n")}` : "",
+    "",
+    "## 稿件（打分用）",
+    clipped,
+    "",
+    "## 你的任务：只打分，不写新意见",
+    "刚才你已经审过这份稿子。现在只做一件事：给这本 deck 的四维度打分。",
+    dimensions,
+    "",
+    "打分口径：",
+    "- 3 分 = 及格：能读下去，但有一两处要读者自己补；",
+    "- 5 分 = 好：不需要作者解释，听众当场能复述 / 能被说服；",
+    "- 1 分 = 明显不合格：读完不知道在说什么，或证据站不住。",
+    "- 每维必须给一句理由（≤30 字），理由要指向具体页或具体句子，不要写「整体不错」。",
+    "",
+    "## 输出契约",
+    "只输出一个 JSON 对象，不要围栏外的解释：",
+    "{",
+    '  "reviewer": "你的身份（一句话）",',
+    '  "scores": {"表意清晰": 4, "证据充分": 3, "结构连贯": 4, "意图达成": 4},',
+    '  "notes": {"表意清晰": "P05 一句话能复述", "证据充分": "P03 的 30% 没来源"}',
+    "}",
+    "规则：分数只能是 1–5 的整数；不确定就给 3 分并在理由里写「不确定」。",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+function jsonCandidate(text) {
+  const raw = String(text ?? "").trim();
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const body = fenced ? fenced[1] : raw;
+  const start = body.indexOf("{");
+  const end = body.lastIndexOf("}");
+  if (start < 0 || end <= start) return null;
+  try {
+    return JSON.parse(body.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 解析打分输出；坏输出不炸（返回 unparsed + 缺的维度）。
+ * @returns {{record:{reviewer:string,scores:Record<string,number>,notes:Record<string,string>}|null, unparsed:boolean, missing:string[]}}
+ */
+export function parseScoreOutput(text) {
+  const parsed = jsonCandidate(text);
+  if (!parsed || typeof parsed !== "object") return { record: null, unparsed: true, missing: [...SCORE_DIMENSIONS] };
+  const reviewer = String(parsed.reviewer ?? "").trim();
+  const scores = {};
+  const notes = {};
+  const missing = [];
+  for (const dimension of SCORE_DIMENSIONS) {
+    const value = Number(parsed.scores?.[dimension]);
+    if (!Number.isFinite(value) || value < 1 || value > 5) {
+      missing.push(dimension);
+      continue;
+    }
+    scores[dimension] = Math.round(value);
+    const note = String(parsed.notes?.[dimension] ?? "").trim();
+    if (note) notes[dimension] = note.slice(0, 60);
+  }
+  if (missing.length) return { record: null, unparsed: false, missing, reviewer };
+  return { record: { reviewer: reviewer || "听众", scores, notes }, unparsed: false, missing: [] };
+}
+
+/**
+ * 合并多个评审的打分：每维取均值（保留一位小数），并记下人数 / 最低最高 / 理由。
+ * @param {{reviewer:string,scores:Record<string,number>,notes?:Record<string,string>}[]} records
+ */
+export function mergeScoreRecords(records = []) {
+  const list = (Array.isArray(records) ? records : []).filter((record) => record && record.scores);
+  const dimensions = {};
+  for (const dimension of SCORE_DIMENSIONS) {
+    const values = list.map((record) => Number(record.scores[dimension])).filter((value) => Number.isFinite(value));
+    dimensions[dimension] = values.length
+      ? {
+          mean: Number((values.reduce((sum, value) => sum + value, 0) / values.length).toFixed(1)),
+          min: Math.min(...values),
+          max: Math.max(...values),
+          count: values.length,
+        }
+      : { mean: null, min: null, max: null, count: 0 };
+  }
+  const means = SCORE_DIMENSIONS.map((dimension) => dimensions[dimension].mean).filter((value) => value != null);
+  return {
+    dimensions,
+    average: means.length ? Number((means.reduce((sum, value) => sum + value, 0) / means.length).toFixed(2)) : null,
+    reviewers: list.map((record) => ({ reviewer: record.reviewer, scores: record.scores, notes: record.notes ?? {} })),
+  };
+}
+
+/**
+ * 与上一次评审对照：返回每维 delta（无上次则全 null）。
+ * @param {object|null} previous mergeScoreRecords 产物
+ * @param {object} current
+ */
+export function compareScores(previous, current) {
+  const deltas = {};
+  for (const dimension of SCORE_DIMENSIONS) {
+    const before = previous?.dimensions?.[dimension]?.mean;
+    const after = current?.dimensions?.[dimension]?.mean;
+    deltas[dimension] = before != null && after != null ? Number((after - before).toFixed(1)) : null;
+  }
+  const changed = SCORE_DIMENSIONS.filter((dimension) => deltas[dimension] != null && deltas[dimension] !== 0);
+  return {
+    available: Boolean(previous),
+    deltas,
+    changed,
+    // 一句话结论：先说变好还是变差，再点名变化最大的维度。
+    line: !previous
+      ? ""
+      : changed.length === 0
+        ? "与上次评审相比：四维分数没有变化。"
+        : (() => {
+            const biggest = [...changed].sort((left, right) => Math.abs(deltas[right]) - Math.abs(deltas[left]))[0];
+            const direction = deltas[biggest] > 0 ? "升" : "降";
+            const improved = changed.filter((dimension) => deltas[dimension] > 0).length;
+            const worsened = changed.filter((dimension) => deltas[dimension] < 0).length;
+            return `与上次评审相比：${improved} 维升、${worsened} 维降；变化最大的是「${biggest}」${direction} ${Math.abs(deltas[biggest]).toFixed(1)} 分。`;
+          })(),
+  };
+}
+
+/** 历史记录里的一条（写入 JSON 的形状）。 */
+export function scoreHistoryEntry({ at, scriptHash, revision, mean, compare }) {
+  return {
+    at,
+    scriptHash: scriptHash ?? "",
+    revision: revision ?? "",
+    scores: mean.dimensions,
+    average: mean.average,
+    reviewers: mean.reviewers,
+    compare: compare?.available ? { deltas: compare.deltas, line: compare.line } : null,
+  };
+}
+
+/** 历史记录 → markdown 表（`docs/review.scores.md`，方便前后对照与交接）。 */
+export function renderScoreHistoryMarkdown(entries = [], { deckTitle = "" } = {}) {
+  const list = Array.isArray(entries) ? entries : [];
+  const header = `| 时间 | revision | ${SCORE_DIMENSIONS.join(" | ")} | 均分 |`;
+  const divider = `|---|---|${SCORE_DIMENSIONS.map(() => "---").join("|")}|---|`;
+  const rows = list.map((entry) => {
+    const cells = SCORE_DIMENSIONS.map((dimension) => entry.scores?.[dimension]?.mean ?? "—");
+    const at = String(entry.at ?? "").replace("T", " ").slice(0, 16);
+    return `| ${at} | ${entry.revision || "—"} | ${cells.join(" | ")} | ${entry.average ?? "—"} |`;
+  });
+  const lines = [`# 审稿评分记录 · ${deckTitle || "（未命名 deck）"}`, "", header, divider, ...rows, ""];
+  const last = list[list.length - 1];
+  if (last?.compare?.line) lines.push(last.compare.line, "");
+  lines.push("打分口径：1–5；3 = 及格，5 = 听众不需要作者解释就能复述 / 被说服。分数由每轮评审的听众独立打，取均值。", "");
+  return lines.join("\n");
+}
+
+/** 给人看的一段摘要（工具输出 / review 文档都能用）。 */
+export function renderScoreSummary({ mean, compare }) {
+  const parts = SCORE_DIMENSIONS.map((dimension) => {
+    const item = mean?.dimensions?.[dimension];
+    return item?.mean == null ? `${dimension} —` : `${dimension} ${item.mean}`;
+  });
+  const lines = [`四维评分：${parts.join(" · ")}${mean?.average != null ? `（均分 ${mean.average}）` : ""}`];
+  if (compare?.line) lines.push(compare.line);
+  return lines.join("\n");
+}

package/lib/title-chain.js

@@ -0,0 +1,122 @@
+/**
+ * 标题串读测试（智力升级 A3 / F-179）：只看一串页标题，能不能推出这份 deck 的故事线。
+ *
+ * 为什么是确定性脚本：这是「结构问题」，不该花模型调用、也不该由模型嘴上说「故事线清晰」。
+ * 判据只查机器能查的东西：
+ * - 有没有占位标题（待定 / 待补 / 暂无 / TBD）——占位意味着这一页还没有观点；
+ * - 有没有重复标题——重复意味着两页在讲同一件事，或者一页是凑数；
+ * - 相邻标题有没有共同词（2 字词）——全断链说明每页各说各的，读者串不起来；
+ * - 有没有收束页（结论 / 小结 / 下一步 / 记住 / 带走 / 回扣）——没有收束，标题串读不出「然后呢」。
+ * 「标题好不好」不在这里判（那是审稿人和人的事）；这里只判「能不能串起来」。
+ */
+
+const PLACEHOLDER = /待定|待补|暂无|待填|TBD|TBA|XXX|xxx/;
+const CLOSE_MARKERS = /小结|总结|结论|收束|下一步|记住|带走|回扣|最后|所以|落地|行动|开始|三件事|清单/;
+const STOP_BIGRAMS = new Set(["怎么", "什么", "为什么", "如何", "我们", "他们", "一个", "这个", "那个", "可以", "不是", "就是"]);
+
+/** 标题的 2 字词集合（去掉常见虚词组合）。中文没有分词器，2-gram 足够做「有没有共同词」的判断。 */
+export function bigramsOf(title = "") {
+  const text = String(title ?? "").replace(/[\s\u3000]+/g, "").replace(/[，。、；：！？,.!?：:·—–\-（）()「」『』“”"']/g, "");
+  const grams = new Set();
+  for (let index = 0; index + 1 < text.length; index += 1) {
+    const gram = text.slice(index, index + 2);
+    if (!STOP_BIGRAMS.has(gram) && !/^\d+$/.test(gram)) grams.add(gram);
+  }
+  return grams;
+}
+
+function sharesBigram(left, right) {
+  for (const gram of left) if (right.has(gram)) return true;
+  return false;
+}
+
+/**
+ * 读一遍标题串，输出逐页标记 + 能不能推出来的结论。
+ * @param {{page:number,title:string,claim?:string}[]} pages
+ */
+export function analyzeTitleChain(pages = []) {
+  const rows = (Array.isArray(pages) ? pages : [])
+    .map((item, index) => ({
+      page: Number(item?.page ?? index + 1),
+      title: String(item?.title ?? "").trim(),
+      claim: String(item?.claim ?? "").trim(),
+    }))
+    .filter((item) => item.title || item.claim)
+    .sort((left, right) => left.page - right.page);
+
+  const seen = new Map();
+  const chain = rows.map((row, index) => {
+    const flags = [];
+    if (!row.title) flags.push("无标题");
+    else if (PLACEHOLDER.test(row.title)) flags.push("占位标题");
+    const key = row.title.replace(/\s+/g, "");
+    if (key && seen.has(key)) flags.push(`与 P${String(seen.get(key)).padStart(2, "0")} 重复`);
+    else if (key) seen.set(key, row.page);
+    const grams = bigramsOf(row.title);
+    const prev = index > 0 ? bigramsOf(rows[index - 1].title) : null;
+    const next = index + 1 < rows.length ? bigramsOf(rows[index + 1].title) : null;
+    const linkedPrev = !prev || sharesBigram(grams, prev);
+    const linkedNext = !next || sharesBigram(grams, next);
+    if (index > 0 && !linkedPrev) flags.push("与上一页无共同词");
+    // 单看相邻两页会误杀正常转折（「故事线怎么定」→「逐页脚本怎么改」）。真正判「串不起来」看
+    // 整体连通性：这一页和前后任意一页有共同词，就算它挂在链上。
+    const attached = linkedPrev || linkedNext;
+    return {
+      ...row,
+      flags,
+      role: index === 0 ? "开场" : CLOSE_MARKERS.test(row.title) ? "收束" : "推进",
+      linked: attached,
+    };
+  });
+
+  const placeholderCount = chain.filter((row) => row.flags.includes("占位标题") || row.flags.includes("无标题")).length;
+  const duplicateCount = chain.filter((row) => row.flags.some((flag) => flag.includes("重复"))).length;
+  const brokenLinks = chain.filter((row) => row.flags.includes("与上一页无共同词")).length;
+  const linkRate = chain.length > 1 ? Number((1 - brokenLinks / (chain.length - 1)).toFixed(2)) : 1;
+  // 连通性：至少挂在一个邻居上的页比例（比「每一对相邻页都要同词」宽，能容忍一次正常转折）。
+  const detached = chain.filter((row) => !row.linked).length;
+  const connectivity = chain.length ? Number((1 - detached / chain.length).toFixed(2)) : 1;
+  const hasClose = chain.length > 1 && (chain[chain.length - 1].role === "收束" || chain.some((row) => CLOSE_MARKERS.test(row.title)));
+
+  const reasons = [];
+  if (!chain.length) reasons.push("没有可读的页标题");
+  if (placeholderCount) reasons.push(`${placeholderCount} 页还是占位标题（待定 / 待补）——这些页没有观点，标题串读不出内容`);
+  if (duplicateCount) reasons.push(`${duplicateCount} 页标题与别的页重复——读者会以为是同一件事讲两遍`);
+  if (connectivity < 0.7) reasons.push(`有 ${detached} 页和前后页都没有共同词——标题串中间断了，读者接不上`);
+  if (chain.length > 3 && !hasClose) reasons.push("没有收束页（结论 / 小结 / 下一步）——读完标题不知道「所以呢」");
+  if (chain.length > 0 && chain.length < 4) reasons.push(`只有 ${chain.length} 页，标题串太短，推不出完整论证`);
+
+  const verdict = reasons.length ? "推不出" : "推得出";
+  return {
+    chain,
+    stats: { pages: chain.length, placeholderCount, duplicateCount, brokenLinks, linkRate, connectivity, hasClose },
+    verdict,
+    reasons,
+    // 给 Agent 的下一步：按最靠前的硬问题先修，不要一次全改。
+    next: placeholderCount
+      ? "先把占位页的标题写成「这页的主张」（不是栏目名），再回头看链"
+      : duplicateCount
+        ? "把重复的那页并掉，或改成它真正多出来的那一层"
+        : connectivity < 0.7
+          ? "让相邻标题共享一个关键词，或加一句承接（「上一页说了 X，这页说 Y」）"
+          : !hasClose
+            ? "补一页收束：结论 / 下一步 / 要记住的一句话"
+            : "",
+  };
+}
+
+/** 渲染成给人看的标题链报告。 */
+export function renderTitleChain({ deckTitle = "", analysis }) {
+  const lines = [`# 标题串读 · ${deckTitle || "（未命名 deck）"}`, ""];
+  lines.push(`结论：**${analysis.verdict}**（${analysis.stats.pages} 页 · 占位 ${analysis.stats.placeholderCount} · 重复 ${analysis.stats.duplicateCount} · 断点 ${analysis.stats.brokenLinks} · 连通 ${Math.round((analysis.stats.connectivity ?? 1) * 100)}%）`);
+  if (analysis.reasons.length) {
+    lines.push("", "为什么：");
+    for (const reason of analysis.reasons) lines.push(`- ${reason}`);
+  }
+  lines.push("", "| 页 | 标题 | 角色 | 标记 |", "|---|---|---|---|");
+  for (const row of analysis.chain) {
+    lines.push(`| P${String(row.page).padStart(2, "0")} | ${row.title || "（空）"} | ${row.role} | ${row.flags.join("；") || "—"} |`);
+  }
+  if (analysis.next) lines.push("", `下一步：${analysis.next}`);
+  return `${lines.join("\n")}\n`;
+}