dsh-plugin-deck-studio 0.2.5 → 0.2.8

package/lib/citation-check.js

@@ -0,0 +1,93 @@
+/**
+ * G3 引用核查（智力升级 B6 / F-177）：一次独立小调用，角色是**校对员不是评审员**。
+ *
+ * 评审给的意见带 evidence，评审员可能「引对文、推错论」（F4）或「改写当引用」（F2）。
+ * G1（程序逐字匹配，见 buildFindings）只能杀 F1/F3；这里是第二道：
+ * 让另一个没有上下文的小模型只回答两件事——这段是否逐字存在？它是否支撑这条意见？
+ *
+ * 本模块无 IO：只拼 prompt、解析结果。调用方在 tools.js 里用 review agent 跑一次。
+ */
+
+export const CITATION_VERDICTS = new Set(["verbatim", "paraphrase", "unsupported"]);
+
+/** 引用核查的 prompt：只做校对，不给意图、不让它评稿。 */
+export function citationCheckPrompt({ items = [], script = "", deckTitle = "" }) {
+  const list = items
+    .map((item) => `- ${item.id}｜${item.page}｜证据：${JSON.stringify(item.evidence)}｜意见：${item.problem || item.fix || "（未写）"}`)
+    .join("\n");
+  return `你是校对员，不是评审员。任务是核对下面的「意见」引用的稿件原文是否真实、是否支撑这条意见。
+
+规则：
+1. 只看给你的稿件原文和意见，不要评价稿件好坏，不要提新意见，不要改写。
+2. 每条意见给两个判断：
+   - quote：证据是否逐字存在于稿件原文（忽略空白 / 标点差异）→ "verbatim" | "paraphrase" | "unsupported"
+     · verbatim：稿件里有这段原文
+     · paraphrase：原文在，但这条是改写/概括，不是逐字引用
+     · unsupported：稿件里找不到这段，也找不到对应原句
+   - supports：这条证据是否足以支撑这条意见的结论 → true | false
+3. 原文里没有的东西一律判 unsupported，不要凭常识补。
+
+只输出 JSON（不要 markdown 代码块）：
+{"checks":[{"id":"R01","quote":"verbatim|paraphrase|unsupported","supports":true|false,"note":"≤40 字"}]}
+
+deck：${deckTitle || "（未命名）"}
+稿 件 原 文：
+"""
+${script}
+"""
+
+待核对意见：
+${list}`;
+}
+
+/** 解析引用核查输出；坏行丢掉，不抛。 */
+export function parseCitationCheck(text) {
+  const raw = String(text ?? "");
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start < 0 || end <= start) return { checks: [], unparsed: true };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw.slice(start, end + 1));
+  } catch {
+    return { checks: [], unparsed: true };
+  }
+  const rows = Array.isArray(parsed.checks) ? parsed.checks : [];
+  const checks = [];
+  for (const row of rows) {
+    if (!row || typeof row !== "object") continue;
+    const id = String(row.id ?? "").trim();
+    if (!/^R\d+$/.test(id)) continue;
+    const quote = String(row.quote ?? "").trim();
+    checks.push({
+      id,
+      quote: CITATION_VERDICTS.has(quote) ? quote : "unsupported",
+      supports: row.supports === true,
+      note: String(row.note ?? "").trim().slice(0, 80),
+    });
+  }
+  return { checks, unparsed: checks.length === 0 };
+}
+
+/**
+ * 把 G3 结论并回可采纳清单（B6 置信度 A–D 的完整口径）：
+ * - verbatim + supports → A（可勾选，证据可定位）
+ * - paraphrase 或 supports=false（但原文在）→ B（可勾选，标「转述 / 支撑偏弱」）
+ * - unsupported → D（原文在但推不出结论 / 支撑不足：仍列出，只作参考，默认不勾）
+ * 没拿到结论的条目保持原置信度（G1 已过的仍是 A），不因核查失败降级——但要在返回里标 `citationChecked:false`。
+ */
+export function applyCitationChecks(findings = [], checks = []) {
+  const byId = new Map(checks.map((check) => [check.id, check]));
+  let checked = 0;
+  const next = findings.map((finding) => {
+    const check = byId.get(finding.id);
+    if (!check) return { ...finding };
+    checked += 1;
+    if (check.quote === "unsupported" || check.supports === false) {
+      return { ...finding, confidence: check.quote === "unsupported" ? "D" : "B", citation: check };
+    }
+    if (check.quote === "paraphrase") return { ...finding, confidence: "B", citation: check };
+    return { ...finding, confidence: "A", citation: check };
+  });
+  return { findings: next, checked, citationChecked: checked > 0 };
+}

package/lib/config.js

@@ -55,6 +55,19 @@ export const DEFAULT_RENDER = {
   default: "",
 };
 
+/**
+ * 图片评审（F-178 / 智力升级 C 层）用的视觉模型通道：OpenAI 兼容 chat/completions。
+ * 默认全空——**仓库不携带节点地址 / 模型名 / key**；用 profile 的 deckStudio.imageReview 或 env 配。
+ */
+export const DEFAULT_IMAGE_REVIEW = {
+  baseURL: "",
+  model: "",
+  apiKeyEnv: "WOCHENG_API_KEY",
+  apiKeyFile: "",
+  timeoutMs: 180_000,
+  maxTokens: 3000,
+};
+
 /** 默认视觉 preset（写进每页 prompt 头部；可在 profile 里用 styleBrief 覆盖）。 */
 export const DEFAULT_STYLE_BRIEF =
   "品牌信息图风格：深青 #06363B 主色、米白纸张底、暖金点缀，纸张纹理背景；" +
@@ -124,6 +137,18 @@ export function mergeConfig(raw, options = {}) {
     timeoutMs: positive(renderInput.timeoutMs, DEFAULT_RENDER.timeoutMs),
   };
 
+  const reviewInput = input.imageReview && typeof input.imageReview === "object" ? input.imageReview : {};
+  const imageReview = {
+    ...DEFAULT_IMAGE_REVIEW,
+    ...reviewInput,
+    baseURL: reviewInput.baseURL || env.DSH_DECK_VISION_BASE_URL || DEFAULT_IMAGE_REVIEW.baseURL,
+    model: reviewInput.model || env.DSH_DECK_VISION_MODEL || DEFAULT_IMAGE_REVIEW.model,
+    apiKeyEnv: reviewInput.apiKeyEnv || env.DSH_DECK_VISION_API_KEY_ENV || DEFAULT_IMAGE_REVIEW.apiKeyEnv,
+    apiKeyFile: expandHome(reviewInput.apiKeyFile || env.DSH_DECK_VISION_API_KEY_FILE || DEFAULT_IMAGE_REVIEW.apiKeyFile, env),
+    timeoutMs: positive(reviewInput.timeoutMs, DEFAULT_IMAGE_REVIEW.timeoutMs),
+    maxTokens: positive(reviewInput.maxTokens, DEFAULT_IMAGE_REVIEW.maxTokens),
+  };
+
   const decksRaw = Array.isArray(input.decks) ? input.decks : [];
   const decks = decksRaw.map((deck) => normalizeDeck(deck, env)).filter(Boolean);
 
@@ -140,6 +165,8 @@ export function mergeConfig(raw, options = {}) {
   }
 
   return {
+    /** 图片评审的视觉模型通道（F-178）；默认空，靠 profile / env 配。 */
+    imageReview,
     /** 只在 preset 子树挂载点为 true；根挂载只开路由与面板。 */
     tools: input.tools === true,
     /** preset 子树挂载点设 false（根挂载已注册同路径路由，避免双重注册）。 */
@@ -152,8 +179,8 @@ export function mergeConfig(raw, options = {}) {
         env,
       ) || defaultDataRoot(env),
     /**
-     * 新建 deck 项目的落盘根（2026-10-21 负责人：以后写的 deck 都放
-     * `00_company/sharing/`）。留空 = 旧的内部 `.deck/projects/<id>/source`。
+     * 新建 deck 项目的落盘根。留空 = <dataRoot>/projects/<id>/source。
+     * 与会话 workspacePath 独立；默认数据根不在插件安装目录内。
      * 配置了这个根时，新项目直接建在 `<projectsRoot>/<目录名>/`
      * （script.md / intent.md / style-reference.md / prompts/ 同层，和已有 deck 源结构一致）。
      */
@@ -205,14 +232,10 @@ export function mergeConfig(raw, options = {}) {
     bootstrap: input.bootstrap === true,
     /**
      * 听众评审（F-159）：审稿人由 intent 的「听众」动态生成，不是写死的固定 role。
-     * presetId 指向只读评审 preset（cordis.patch.yml 的 preset-deck-critic）；
+     * 审稿人使用插件内置 Sub Agent，不接受公开 preset 选择；旧 presetId 不再生效。
      * maxReviewers 是成本上限（每个审稿人 = 一次子 agent 调用），默认 3。
      */
     review: {
-      presetId:
-        typeof input.review?.presetId === "string" && input.review.presetId.trim()
-          ? input.review.presetId.trim()
-          : "deck-critic",
       maxReviewers: Math.min(
         HARD_MAX_REVIEWERS,
         positive(input.review?.maxReviewers, DEFAULT_MAX_REVIEWERS),

package/lib/deck-brief.js

@@ -10,7 +10,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-const clean = (value) => String(value ?? "").replace(/^（待补[^）]*）$/, "").trim();
+// 占位文本可能带嵌套括号（「（待补：…（只写角色，不写标题））」），所以整行匹配而不是遇到第一个右括号就停。
+const clean = (value) => String(value ?? "").replace(/^（待补[\s\S]*）$/, "").trim();
 
 /** 读 `---` front matter（只取顶层 `key: value`）。 */
 export function readFrontMatter(text) {
@@ -56,6 +57,12 @@ export function readDeckBrief(sourceRoot) {
   } catch {
     intent = {};
   }
+  const skeleton = {
+    argument: clean(intent["核心论证"]),
+    type: clean(intent["骨架类型"]),
+    order: clean(intent["页序角色"]),
+    keepThree: clean(intent["只留 3 页留哪 3 页"]),
+  };
   return {
     title: clean(scriptHead.title || intent["主题"]),
     owner: clean(scriptHead.owner),
@@ -65,10 +72,37 @@ export function readDeckBrief(sourceRoot) {
     takeaway: clean(intent["带走"]),
     success: clean(intent["成功标准"]),
     scopeOut: clean(intent["不讲的"]),
+    skeleton,
     rules: "",
   };
 }
 
+/** A0 骨架类型（plan §A0）：写页之前先选一个，或自由写一句。 */
+export const SKELETON_TYPES = ["结论先行", "故事线", "教学分解", "视觉主导", "中性简报"];
+
+/**
+ * 论证骨架体检（A0 的判据）：
+ * - 核心论证 / 骨架类型 / 页序角色 三行必填；
+ * - 「只留 3 页留哪 3 页」答不出来 → 说明论证还没想清（warn，不阻断）；
+ * - 骨架类型不在预设里也行（自由写一句），但要在文本里能看出来。
+ * @returns {{ok:boolean, missing:string[], keepThree:boolean, typeKnown:boolean, hint:string}}
+ */
+export function validateSkeleton(brief = {}) {
+  const skeleton = brief.skeleton ?? {};
+  const missing = [];
+  if (!skeleton.argument) missing.push("核心论证");
+  if (!skeleton.type) missing.push("骨架类型");
+  if (!skeleton.order) missing.push("页序角色");
+  const keepThree = Boolean(skeleton.keepThree);
+  const typeKnown = !skeleton.type || SKELETON_TYPES.some((type) => String(skeleton.type).includes(type));
+  const hint = missing.length
+    ? `论证骨架还没写全（缺：${missing.join(" / ")}）。写页之前先在 intent.md 的「论证骨架」段写三行：核心论证（因为 X，所以 Y；听众要做的是 Z）/ 骨架类型（${SKELETON_TYPES.join(" / ")}，或自由写一句）/ 页序角色（只写角色，不写标题）。连贯不是句子的产物，是骨架的产物。`
+    : !keepThree
+      ? "论证骨架有了，但「只留 3 页留哪 3 页」没答——答不出来说明论证还没想清，先想清楚再往下写。"
+      : "";
+  return { ok: missing.length === 0, missing, keepThree, typeKnown, hint };
+}
+
 /** 出图 prompt 用的上下文行：受众 / 目的（一句话）。没有就返回空数组。 */
 export function briefPromptLines(brief = {}) {
   const lines = [];

package/lib/deck-docs.js

@@ -100,8 +100,10 @@ export const DOC_SPECS = [
   {
     id: "review",
     label: "审稿",
-    purpose: "交付前问题清单：严重度 / 位置 / 证据 / 修复建议 + 是否可交付",
-    candidates: ["review.md"],
+    // F-187：评审产出按「读者 → 负责人 → 工程」排序，听众读后感放第一个（原来只有工程口径的 review.md）。
+    purpose: "听众读后感（人话）· 意图与听众差距 · 工程口径的问题清单 / 证据 / 修复建议",
+    candidates: ["review.readers.md", "review.gap.md", "review.md", "review.experts.md", "review.images.md", "review.scores.md"],
+    aliases: ["review.readers.md", "review.gap.md", "review.experts.md", "review.images.md", "review.scores.md"],
     template: "review",
   },
   {
@@ -412,13 +414,17 @@ export function buildChangeFeed({ entries = [], revisions = [], events = [] }) {
   }
   for (const revision of revisions) {
     const pageIds = revision.pageIds ?? revision.slideIds ?? (revision.page ? [revision.page] : []);
+    // F-173：首稿自动落版的 revision 要有醒目标记（徽标 + 自改摘要），否则用户看不出「这版没经过确认」。
+    const badge = String(revision.autolandBadge ?? "");
+    const autoland = revision.autoland && typeof revision.autoland === "object" ? revision.autoland : null;
     rows.push({
       date: revision.savedAt || "",
-      kind: "改脚本",
+      kind: badge || "改脚本",
       page: pageIds.join(","),
-      note: revision.note || "script 编辑",
-      actor: revision.actor || "",
+      note: revision.note || (autoland?.selfReview?.summary ? `自改摘要：${autoland.selfReview.summary}` : "script 编辑"),
+      actor: autoland ? "agent（自动落版）" : revision.actor || "",
       revision: revision.revision || "",
+      ...(autoland ? { autoland: { ...autoland, badge: badge || "首稿（自动落版，未经确认）" } } : {}),
     });
   }
   for (const event of events) {
@@ -810,7 +816,7 @@ export function resolveDeckDocs({ adapter, deckDir, render = {}, revisions = [],
  * 读取单份文档：正文 + 结构化视图，供中间区对应标签渲染。
  * @param {object} input
  */
-export function readDeckDoc({ adapter, deckDir, docId, render = {}, revisions = [], events = [] }) {
+export function readDeckDoc({ adapter, deckDir, docId, file = "", render = {}, revisions = [], events = [] }) {
   const spec = DOC_SPECS.find((item) => item.id === docId);
   if (!spec) return null;
   const { docs } = resolveDeckDocs({ adapter, deckDir, render, revisions, events });
@@ -818,7 +824,39 @@ export function readDeckDoc({ adapter, deckDir, docId, render = {}, revisions =
   const sourceRoot = adapter?.sourceRoot ?? "";
   const draftFile = draftPath(deckDir, docId);
   const sourceFile = spec.candidates.map((name) => join(sourceRoot, name)).find((file) => existsSync(file));
-  const primaryFile = sourceFile ?? (existsSync(draftFile) ? draftFile : null);
+  let primaryFile = sourceFile ?? (existsSync(draftFile) ? draftFile : null);
+  // F-187：评审产物写在 deck 工作副本的 docs/ 下（review.readers.md / review.gap.md 等），
+  // 不是源 deck 的候选文件；这里按「读者 → 负责人 → 工程」顺序找第一个存在的当作正文。
+  if (docId === "review") {
+    const preferred = spec.candidates.map((name) => join(deckDir, "docs", name)).find((file) => existsSync(file));
+    if (preferred) {
+      primaryFile = preferred;
+      doc.primary = `docs/${preferred.split(/[\\/]/).pop()}`;
+      // 人话版是散文体（没有「严重度」表格），不该被表格解析判成 partial。
+      const human = /review\.(readers|gap)\.md$/.test(preferred);
+      if (human || doc.status === "missing") {
+        doc.status = human ? "ok" : "draft";
+        doc.issues = [];
+      }
+      // 指定了相关文件（工作台点 chip）就读它；只允许本 deck docs/ 下的 review.* 文件。
+      const wanted = String(file ?? "").trim();
+      if (wanted && /^docs\/review\.[a-z]+\.(md|json)$/.test(wanted)) {
+        const target = join(deckDir, wanted);
+        if (existsSync(target) && statSync(target).isFile()) {
+          primaryFile = target;
+          doc.primary = wanted;
+          doc.status = "ok";
+          doc.issues = [];
+        }
+      }
+      // 「相关文件」按顺序列出存在的几本，工作台文档页可以逐个打开。
+      for (const name of spec.aliases ?? []) {
+        const file = join(deckDir, "docs", name);
+        if (!existsSync(file) || !statSync(file).isFile()) continue;
+        doc.files.push({ name: `docs/${name}`, exists: true, role: "相关", sizeBytes: statSync(file).size });
+      }
+    }
+  }
   const content = primaryFile ? readText(primaryFile) ?? "" : "";
   const script = adapter?.readScriptRaw?.() ?? readText(join(sourceRoot, "script.md")) ?? "";
   const pages = adapter?.storyPages?.() ?? [];

package/lib/deck-templates.js

@@ -20,7 +20,7 @@ const orPlaceholder = (value, hint) => (pad(value) ? pad(value) : `（待补：$
  * intent.md 初始内容。
  * @param {{title:string, audience?:string, topic?:string, intent?:string, references?:string, created?:string, owner?:string}} input
  */
-export function buildIntentMarkdown({ title, audience = "", topic = "", intent = "", references = "", occasion = "", success = "", scopeOut = "", created = "", owner = "" } = {}) {
+export function buildIntentMarkdown({ title, audience = "", topic = "", intent = "", references = "", occasion = "", success = "", scopeOut = "", argument = "", skeletonType = "", pageOrder = "", keepThree = "", created = "", owner = "" } = {}) {
   const heading = pad(title) || "（deck 标题）";
   return [
     "---",
@@ -39,6 +39,13 @@ export function buildIntentMarkdown({ title, audience = "", topic = "", intent =
     `- **成功标准**：${orPlaceholder(success, "怎么判断这场讲成了")}`,
     `- **不讲的**：${orPlaceholder(scopeOut, "明确排除什么，避免范围膨胀")}`,
     "",
+    "## 论证骨架（写页之前先定）",
+    "",
+    `- **核心论证**：${orPlaceholder(argument, "因为 [X]，所以 [Y]；听众要做的是 [Z]")}`,
+    `- **骨架类型**：${orPlaceholder(skeletonType, "结论先行 / 故事线 / 教学分解 / 视觉主导 / 中性简报，或自由写一句")}`,
+    `- **页序角色**：${orPlaceholder(pageOrder, "封面 → 结论 → 证据1 → 证据2 → 风险 → 请求；只写角色，不写标题")}`,
+    `- **只留 3 页留哪 3 页**：${orPlaceholder(keepThree, "答不出来说明论证还没想清——先想清楚再列页")}`,
+    "",
     "## 参考资料",
     "",
     orPlaceholder(references, "链接 / 文件路径 / 已有材料说明"),

package/lib/deck-workspace.js

@@ -8,7 +8,7 @@
  * @module dsh-plugin-deck-studio/deck-workspace
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { createLocalSourceAdapter } from "./source-adapter.js";
@@ -56,6 +56,12 @@ export const SECTION_FIELD_KEYS = {
   // F-109：正文独立成字段。以前 claim 把「正文」当别名，提案会整段覆盖正文，
   // 现在 body 走自己的字段，claim 不再误伤正文。
   body: ["正文"],
+  // F-181（I-06）：逐页契约 5 项里的可写字段；缺字段时插在标题行之后，老 deck 不受影响。
+  // 键名用中文字段名（工具 enum 直接暴露给人看），英文别名保留给内部调用。
+  角色: ["角色"],
+  受众变化: ["受众变化", "听众变化"],
+  关系: ["关系"],
+  证据: ["证据"],
 };
 
 /** 标题行（`### P04 · …`）与该页结束行（下一个 heading 之前）。 */
@@ -393,6 +399,25 @@ export function createDeckWorkspace(config) {
     return { revision, path: file };
   }
 
+  /** 已落版 script revision 列表（新的在前）；首稿判定与回滚共用。 */
+  function listScriptRevisions(deckId) {
+    const dir = join(deckDir(deckId), "script", "revisions");
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .filter((name) => /^v\d+\.md$/.test(name))
+      .sort()
+      .reverse()
+      .map((name) => {
+        const revision = name.replace(/\.md$/, "");
+        const noteFile = join(dir, `${revision}.note.txt`);
+        return {
+          revision,
+          savedAt: statSync(join(dir, name)).mtime.toISOString(),
+          note: existsSync(noteFile) ? readFileSync(noteFile, "utf8").trim() : "",
+        };
+      });
+  }
+
   /** 提案。 */
   function saveProposal(proposal) {
     const dir = join(deckDir(proposal.deckId), "proposals");
@@ -460,6 +485,7 @@ export function createDeckWorkspace(config) {
     appendScriptPages,
     scriptPageNumbers,
     saveScriptRevision,
+    listScriptRevisions,
     saveProposal,
     proposal,
     updateProposal,

package/lib/designs.js

@@ -41,6 +41,21 @@ export function normalizeAbbr(value) {
   return abbr.toUpperCase();
 }
 
+/**
+ * 从风格名称推一个可用缩写（F-186：普通对话里登记风格时不用用户想缩写）。
+ * 规则与 normalizeAbbr 一致：2–6 位、字母开头；中文名没有拉丁字母时退化成 `ST01`。
+ */
+export function suggestAbbr(name, taken = []) {
+  const used = new Set((taken ?? []).map((value) => String(value ?? "").toUpperCase()).filter(Boolean));
+  const latin = String(name ?? "").toUpperCase().replace(/[^A-Z0-9]/g, "").replace(/[0-9]/g, "");
+  const base = (latin.length >= 2 ? latin : "ST").slice(0, 4);
+  for (let index = 0; index < 500; index += 1) {
+    const candidate = index === 0 ? base : `${base.slice(0, 3)}${String(index).padStart(2, "0")}`;
+    if (candidate.length <= 6 && !used.has(candidate)) return candidate;
+  }
+  throw new Error("自动生成风格缩写失败（同名风格太多），请手动指定 abbr");
+}
+
 /**
  * @param {{dataRoot: string}} input
  */

package/lib/fact-labels.js

@@ -0,0 +1,81 @@
+/**
+ * 事实标注（智力升级 A2 / F-182）：正文里的数字，要么挂「事实 ID」（调研台账里的条目），
+ * 要么显式标「示意数据」——不能既没出处、又没说「这是我编的数」。
+ *
+ * 判据是确定性的（不花模型、不阻断出图）：
+ * 1. 从这页的 body + claim 里抽数字（排除年份、页号这类不承载事实的编号）；
+ * 2. 看这页的「证据」字段（I-06 契约里的第 5 项）写了什么：
+ *    - 事实 ID（`F-01` / `#3` / 「调研台账 C02」/「访谈 12 人」…）→ 有来源；
+ *    - 「示意数据 / 示意」→ 明确标了是示意；
+ *    - 「无需」或空 → 有数字却没来源 → 提示（不阻断）。
+ * 3. 提示只指出「哪页哪个数没来源」，不替用户改稿。
+ */
+
+// 数字 + 可选单位：42 / 3–5 分钟 / 30% / 1.5 倍 / 1200 万。
+const NUMBER_RE = /(\d+(?:\.\d+)?(?:\s*[–\-~—至]\s*\d+(?:\.\d+)?)?)\s*(%|％|万|亿|倍|分钟|小时|天|个月|月|年|人|页|个|条|次|元|块|秒)?/g;
+// 不承载事实的编号：年份、日期、页号、版本号、编号 ID 里的数字由字段自己管。
+const IGNORE_IF_YEAR = /^(19|20)\d{2}$/;
+const CITATION_RE = /(事实|台账|调研|访谈|问卷|报告|数据|统计|来源|出处|F-?\d+|#\s?\d+|C\d{2}|P\d{2})/i;
+const SCHEMATIC_RE = /示意/;
+
+/** 抽正文里的数字（去重、保序），返回 [{raw, unit, context}]。 */
+export function extractFacts(text = "") {
+  const source = String(text ?? "");
+  const found = [];
+  const seen = new Set();
+  for (const match of source.matchAll(NUMBER_RE)) {
+    const raw = match[1].replace(/\s+/g, "");
+    const unit = match[2] ?? "";
+    if (IGNORE_IF_YEAR.test(raw)) continue;
+    // 编号不是事实：v001 / F-03 / C02 / P05 / 2026-10-25 里的数字不算「正文数字」。
+    const before = source.slice(Math.max(0, (match.index ?? 0) - 1), match.index ?? 0);
+    if (/[A-Za-z0-9_#\-.]/.test(before)) continue;
+    const key = `${raw}${unit}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const index = match.index ?? 0;
+    found.push({ raw, unit, context: source.slice(Math.max(0, index - 12), index + raw.length + unit.length + 12).replace(/\s+/g, " ").trim() });
+  }
+  return found;
+}
+
+/**
+ * 单页事实标注体检。
+ * @param {{page:number, body?:string, claim?:string, evidence?:string}} input
+ * @returns {{page:number, numbers:string[], status:"no-numbers"|"cited"|"schematic"|"unannotated", hint:string}}
+ */
+export function checkFactLabels({ page = 0, body = "", claim = "", evidence = "" } = {}) {
+  const facts = extractFacts([claim, body].filter(Boolean).join("\n"));
+  const numbers = facts.map((fact) => `${fact.raw}${fact.unit}`);
+  if (!numbers.length) return { page, numbers, status: "no-numbers", hint: "" };
+  const evidenceText = String(evidence ?? "").trim();
+  if (SCHEMATIC_RE.test(evidenceText)) return { page, numbers, status: "schematic", hint: "" };
+  if (evidenceText && CITATION_RE.test(evidenceText)) return { page, numbers, status: "cited", hint: "" };
+  const shown = numbers.slice(0, 4).join(" / ") + (numbers.length > 4 ? " …" : "");
+  const hint = evidenceText
+    ? `P${String(page).padStart(2, "0")} 正文有数字（${shown}），但「证据」写的是「${evidenceText.slice(0, 20)}」——数字要么挂事实 ID（调研台账里的条目），要么写「示意数据」。`
+    : `P${String(page).padStart(2, "0")} 正文有数字（${shown}）却没写来源——在「证据」字段写事实 ID（调研台账里的条目），或写「示意数据」标明这是示意。`;
+  return { page, numbers, status: "unannotated", hint };
+}
+
+/**
+ * 整本事实标注汇总。
+ * @param {{page:number, body?:string, claim?:string, evidence?:string}[]} pages
+ */
+export function analyzeFactLabels(pages = []) {
+  const perPage = (Array.isArray(pages) ? pages : []).map((page) => checkFactLabels(page)).sort((left, right) => left.page - right.page);
+  const unannotated = perPage.filter((item) => item.status === "unannotated");
+  return {
+    perPage,
+    unannotated,
+    withNumbers: perPage.filter((item) => item.numbers.length > 0).length,
+  };
+}
+
+/** 一行摘要（没有问题时返回空串）。 */
+export function factSummaryLine(analysis) {
+  if (!analysis?.unannotated?.length) return "";
+  const pages = analysis.unannotated.slice(0, 5).map((item) => `P${String(item.page).padStart(2, "0")}（${item.numbers.slice(0, 2).join(" / ")}）`).join("；");
+  const more = analysis.unannotated.length > 5 ? ` …等 ${analysis.unannotated.length} 页` : "";
+  return `事实标注：${analysis.unannotated.length} 页正文有数字但没挂来源：${pages}${more}——在「证据」字段写事实 ID（见调研台账）或「示意数据」；不阻断出图，但别让用户以为数字有出处。`;
+}

package/lib/first-draft.js

@@ -0,0 +1,119 @@
+/**
+ * 首稿自动落版（F-173 / 智力升级 I-17）。
+ *
+ * 为什么单独一层：首稿是唯一「没有人工把关就进库」的动作，所以判定、元数据、回滚
+ * 必须由程序保证，而不是靠 Agent 记得「这次是首稿」。三道硬约束：
+ *
+ * 1. 判定：`script/revisions/` 里没有任何 vNNN.md 才允许自动落版；有历史版本一律拒绝。
+ * 2. 留痕：每条自动落版 revision 旁写 `<vNNN>.autoland.json`（自改轮次 / 依据的评审 / 摘要），
+ *    并把落版前的稿子存成 `<vNNN>.before.md`——回滚要能精确还原到落版前，不是「重来一次」。
+ * 3. 可回滚：只有「最新 revision 且是自动落版」才允许回滚；回滚本身也追加新 revision，
+ *    旧版本照常保留（copy-on-write 不放宽）。
+ *
+ * 本模块无 IO 之外的依赖，工具 / 路由 / 文档读取共用同一套判定，避免三处各写一遍。
+ *
+ * @module dsh-plugin-deck-studio/first-draft
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const AUTOLAND_SUFFIX = ".autoland.json";
+export const BEFORE_SUFFIX = ".before.md";
+
+/** script revision 目录。 */
+export function revisionsDir(workspace, deckId) {
+  return join(workspace.deckDir(deckId), "script", "revisions");
+}
+
+/** 已落版 revision 数（vNNN.md；note/sidecar 不算）。 */
+export function revisionCount(workspace, deckId) {
+  const dir = revisionsDir(workspace, deckId);
+  if (!existsSync(dir)) return 0;
+  return workspace.listScriptRevisions(deckId).length;
+}
+
+/** 首稿判定：一份稿子都还没落过。 */
+export function isFirstDraft(workspace, deckId) {
+  return revisionCount(workspace, deckId) === 0;
+}
+
+/** 读某条 revision 的自动落版记录；没有返回 null。 */
+export function autolandOf(workspace, deckId, revision) {
+  const file = join(revisionsDir(workspace, deckId), `${revision}${AUTOLAND_SUFFIX}`);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 最新一条 revision 的自动落版记录（用于「能不能回滚」判定）。
+ * @returns {{revision:string, record:object}|null}
+ */
+export function latestAutoland(workspace, deckId) {
+  const revisions = workspace.listScriptRevisions(deckId); // 新的在前
+  if (!revisions.length) return null;
+  const revision = revisions[0].revision;
+  const record = autolandOf(workspace, deckId, revision);
+  if (!record || record.rolledBack) return null;
+  return { revision, record };
+}
+
+/** 写自动落版记录 + 落版前稿子（回滚用）。 */
+export function writeAutoland(workspace, deckId, { revision, proposal, selfReview, draftRound, beforeText }) {
+  const dir = revisionsDir(workspace, deckId);
+  const beforeFile = `${revision}${BEFORE_SUFFIX}`;
+  writeFileSync(join(dir, beforeFile), String(beforeText ?? ""), "utf8");
+  const record = {
+    autoland: true,
+    at: new Date().toISOString(),
+    deckId,
+    revision,
+    proposalId: proposal?.proposalId ?? null,
+    draftRound: Number.isFinite(Number(draftRound)) ? Number(draftRound) : 1,
+    selfReview: {
+      rounds: Number.isFinite(Number(selfReview?.rounds)) ? Number(selfReview.rounds) : 0,
+      reviewId: String(selfReview?.reviewId ?? ""),
+      summary: String(selfReview?.summary ?? ""),
+    },
+    before: { revision: null, file: beforeFile, chars: String(beforeText ?? "").length },
+    rolledBack: null,
+  };
+  writeFileSync(join(dir, `${revision}${AUTOLAND_SUFFIX}`), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  return record;
+}
+
+/**
+ * 回滚首稿：把 `<vNNN>.before.md` 的内容作为**新 revision** 写回，并标记原记录已回滚。
+ * 只在「最新 revision 是自动落版且未回滚」时可用。
+ * @returns {{ok:true, revision:string, restoredFrom:string, beforeRevision:string}}
+ */
+export function rollbackFirstDraft({ workspace, deckId, note = "" }) {
+  const latest = latestAutoland(workspace, deckId);
+  if (!latest) {
+    throw new Error("没有可回滚的首稿：只支持回滚「最新一条 revision 是自动落版」的情况；正式修订请用提案流程。");
+  }
+  const dir = revisionsDir(workspace, deckId);
+  const beforeFile = join(dir, latest.record.before?.file ?? `${latest.revision}${BEFORE_SUFFIX}`);
+  if (!existsSync(beforeFile)) throw new Error(`首稿回滚缺少落版前快照：${beforeFile}`);
+  const text = readFileSync(beforeFile, "utf8");
+  const saved = workspace.saveScriptRevision(
+    deckId,
+    text,
+    `rollback autoland ${latest.revision} → 落版前内容（${note || "用户要求回滚首稿"}）`,
+  );
+  latest.record.rolledBack = { at: new Date().toISOString(), revision: saved.revision, note: String(note ?? "") };
+  writeFileSync(join(dir, `${latest.revision}${AUTOLAND_SUFFIX}`), `${JSON.stringify(latest.record, null, 2)}\n`, "utf8");
+  return { ok: true, revision: saved.revision, restoredFrom: latest.record.before?.file ?? beforeFile, beforeRevision: latest.revision };
+}
+
+/** 给 workbench / 修改日志用的一句话徽标文案。 */
+export function autolandBadge(record) {
+  if (!record || !record.autoland) return "";
+  if (record.rolledBack) return "首稿已回滚";
+  const rounds = Number(record.selfReview?.rounds ?? 0);
+  return `首稿（自动落版${rounds > 0 ? `，自改 ${rounds} 轮` : ""}，未经确认）`;
+}