dsh-thesis 2.0.2 → 2.1.1

package/lib/figure/lib/check.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 图表体检：源文件、导出件、正文引用、图号四者对不上时，在这里被抓出来。
+ *
+ * 论文里最容易出错、又最丢分的一类细节是「图」：
+ *
+ * - 图改了忘导出，论文里还是旧图；
+ * - 图在 assets 里躺着，正文从没引用（或者引用了但文件路径断了）；
+ * - 图题写成「系统架构图」而不是「图 4-1 系统总体架构图」，编号直接断档；
+ * - 第 4 章的图编号成 图 3-1。
+ *
+ * 这些都是**可机器判定**的，所以不靠人肉检查：{@link checkFigures} 只吃已经准备好的
+ * 清单（不碰文件系统，方便单测），返回问题列表；{@link renderFigureReport} 渲染成
+ * `06-论文/assets/图/图表清单.md`。
+ *
+ * @module dsh-thesis/figure/check
+ */
+/** 问题等级：error 会让论文明图不成；warn 是「能过但会被老师问」。 */
+export type FigureSeverity = 'error' | 'warn';
+/** 一条问题。 */
+export interface FigureIssue {
+    readonly severity: FigureSeverity;
+    readonly code: string;
+    readonly message: string;
+}
+/** 图文件（源文件与导出件共用）。 */
+export interface FigureFileEntry {
+    /** 相对论文工作区根的路径（正斜杠）。 */
+    readonly path: string;
+    readonly mtimeMs?: number;
+    /** 导出件的像素宽（拿得到时用来判断印刷是否够清晰）。 */
+    readonly widthPx?: number;
+}
+/** 正文里的一处图片引用。 */
+export interface FigureReference {
+    readonly chapter: string;
+    readonly chapterNo: number;
+    /** 在章节文件里的行号（1 起）。 */
+    readonly line: number;
+    /** 形如 `图 4-1 系统总体架构图`；缺图题时为 alt 原文。 */
+    readonly alt: string;
+    /** 正文里写的路径（原样）。 */
+    readonly src: string;
+    /** 解析到的绝对/规范路径；解析不到时为 undefined（文件不存在）。 */
+    readonly resolvedPath?: string;
+}
+/** 体检输入。 */
+export interface FigureCheckInput {
+    readonly sources: readonly FigureFileEntry[];
+    readonly images: readonly FigureFileEntry[];
+    readonly references: readonly FigureReference[];
+    /** 章节正文（用于判断「本章第一张图是 4-3 时，4-2 到底存不存在」）。 */
+    readonly chapterTexts?: readonly {
+        readonly chapter: string;
+        readonly text: string;
+    }[];
+}
+/** 汇总里的一张图。 */
+export interface FigureEntry {
+    readonly stem: string;
+    readonly source?: string;
+    readonly image?: string;
+    readonly references: readonly string[];
+}
+/** 体检结果。 */
+export interface FigureCheckResult {
+    readonly entries: readonly FigureEntry[];
+    readonly issues: readonly FigureIssue[];
+    readonly errors: number;
+    readonly warnings: number;
+}
+/** 规范图题：`图 4-1 系统总体架构图`（章号-序号 + 空格 + 标题）。 */
+export declare const CAPTION_PATTERN: RegExp;
+/** 从图题里取出章号与序号；不是规范图题时返回 undefined。 */
+export declare function parseCaption(text: string): {
+    readonly chapter: number;
+    readonly index: number;
+} | undefined;
+/** 去掉扩展名，只留文件名主干（用于把 .drawio 与 .png 配对）。 */
+export declare function stemOf(path: string): string;
+/** 体检：纯函数，输入齐全时可以完全离线断言。 */
+export declare function checkFigures(input: FigureCheckInput): FigureCheckResult;
+/** 渲染成 `图表清单.md`（同时给模型看，也随论文提交）。 */
+export declare function renderFigureReport(result: FigureCheckResult, now?: Date): string;

package/lib/figure/lib/check.js

@@ -0,0 +1,214 @@
+/**
+ * 图表体检：源文件、导出件、正文引用、图号四者对不上时，在这里被抓出来。
+ *
+ * 论文里最容易出错、又最丢分的一类细节是「图」：
+ *
+ * - 图改了忘导出，论文里还是旧图；
+ * - 图在 assets 里躺着，正文从没引用（或者引用了但文件路径断了）；
+ * - 图题写成「系统架构图」而不是「图 4-1 系统总体架构图」，编号直接断档；
+ * - 第 4 章的图编号成 图 3-1。
+ *
+ * 这些都是**可机器判定**的，所以不靠人肉检查：{@link checkFigures} 只吃已经准备好的
+ * 清单（不碰文件系统，方便单测），返回问题列表；{@link renderFigureReport} 渲染成
+ * `06-论文/assets/图/图表清单.md`。
+ *
+ * @module dsh-thesis/figure/check
+ */
+/** 规范图题：`图 4-1 系统总体架构图`（章号-序号 + 空格 + 标题）。 */
+export const CAPTION_PATTERN = /^图\s*(\d+)\s*[-－—–]\s*(\d+)\s+\S/;
+/** 从图题里取出章号与序号；不是规范图题时返回 undefined。 */
+export function parseCaption(text) {
+    const match = CAPTION_PATTERN.exec(text.trim());
+    if (match === null)
+        return undefined;
+    return { chapter: Number(match[1]), index: Number(match[2]) };
+}
+/** 去掉扩展名，只留文件名主干（用于把 .drawio 与 .png 配对）。 */
+export function stemOf(path) {
+    const base = path.replace(/\\/g, '/').split('/').pop() ?? path;
+    const dot = base.lastIndexOf('.');
+    return dot <= 0 ? base : base.slice(0, dot);
+}
+function dirOf(path) {
+    const normalized = path.replace(/\\/g, '/');
+    const slash = normalized.lastIndexOf('/');
+    return slash < 0 ? '' : normalized.slice(0, slash);
+}
+/** 体检：纯函数，输入齐全时可以完全离线断言。 */
+export function checkFigures(input) {
+    const issues = [];
+    const push = (severity, code, message) => {
+        issues.push({ severity, code, message });
+    };
+    const imagesByPath = new Map(input.images.map(image => [image.path.replace(/\\/g, '/'), image]));
+    const sourcesByStem = new Map();
+    for (const source of input.sources) {
+        const key = `${dirOf(source.path)}/${stemOf(source.path)}`;
+        const bucket = sourcesByStem.get(key) ?? [];
+        bucket.push(source);
+        sourcesByStem.set(key, bucket);
+    }
+    // 1. 每个 .drawio 都要有同名的 png/svg 导出件。
+    for (const source of input.sources) {
+        const dir = dirOf(source.path);
+        const stem = stemOf(source.path);
+        const candidates = [`${dir}/${stem}.png`, `${dir}/${stem}.svg`].map(p => p.replace(/^\/+/, ''));
+        const exported = candidates.map(path => imagesByPath.get(path)).find(image => image !== undefined);
+        if (exported === undefined) {
+            push('error', 'missing-export', `源文件 ${source.path} 没有导出件（同目录缺 ${stem}.png 或 ${stem}.svg）。运行 thesis_figure action=export 导出后再写正文引用。`);
+            continue;
+        }
+        if (source.mtimeMs !== undefined && exported.mtimeMs !== undefined && exported.mtimeMs < source.mtimeMs) {
+            push('warn', 'stale-export', `${exported.path} 比源文件 ${source.path} 旧：图改过但没重新导出，论文里会显示旧图。重跑 thesis_figure action=export。`);
+        }
+    }
+    // 1.5 导出件分辨率：按论文 15cm 栏宽折算 dpi，低于 200 dpi 印刷会发虚。
+    for (const image of input.images) {
+        if (image.widthPx === undefined || image.widthPx >= 1200)
+            continue;
+        const dpi = Math.round(image.widthPx / 5.9);
+        push('warn', 'low-resolution', `${image.path} 只有 ${image.widthPx}px 宽：按 15cm 栏宽排进论文约 ${dpi} dpi，印刷会发虚。用 thesis_figure action=export（3×）重新导出，或换更高分辨率截图。`);
+    }
+    // 2. 正文引用必须能落到真实文件；alt 必须是规范图题。
+    const referenced = new Map();
+    const byChapter = new Map();
+    for (const reference of input.references) {
+        const key = reference.resolvedPath === undefined ? undefined : reference.resolvedPath.replace(/\\/g, '/');
+        if (reference.resolvedPath === undefined || !imagesByPath.has(key ?? '')) {
+            push('error', 'missing-image', `${reference.chapter}:${reference.line} 引用的图片不存在：${reference.src}。路径相对当前章节文件解析；论文仓库里的图通常写成 ../assets/图/<名字>.png。`);
+        }
+        else {
+            const bucket = referenced.get(key) ?? [];
+            bucket.push(reference.chapter);
+            referenced.set(key, bucket);
+        }
+        const caption = parseCaption(reference.alt);
+        if (caption === undefined) {
+            push('error', 'missing-caption', `${reference.chapter}:${reference.line} 的图片缺少规范图题：现在是「${reference.alt === '' ? '（空）' : reference.alt}」，应写成「图 ${reference.chapterNo}-<序号> <图名>」——图题在图下方、编号带章号。`);
+        }
+        else if (caption.chapter !== reference.chapterNo) {
+            push('error', 'caption-chapter', `${reference.chapter}:${reference.line} 的图题章号是 ${caption.chapter}，但它在第 ${reference.chapterNo} 章：应为「图 ${reference.chapterNo}-${caption.index} …」。`);
+        }
+        else {
+            const bucket = byChapter.get(reference.chapter) ?? [];
+            bucket.push({ line: reference.line, caption: reference.alt, chapterNo: reference.chapterNo });
+            byChapter.set(reference.chapter, bucket);
+        }
+    }
+    // 3. 每章图片的图号必须唯一、按出现顺序递增、且相邻（跳号说明中间那张图丢了）。
+    //    若本章第一张图不是 4-1，只有正文里确实提到过 4-(n-1) 才放行——
+    //    那说明前面还有一张图（例如截图单独放在别处），不算断档。
+    const chapterText = new Map((input.chapterTexts ?? []).map(item => [item.chapter, item.text]));
+    for (const [chapter, list] of byChapter) {
+        const sorted = [...list].sort((a, b) => a.line - b.line);
+        const parsed = sorted
+            .map(item => ({ item, caption: parseCaption(item.caption) }))
+            .filter(entry => entry.caption !== undefined);
+        const seen = new Map();
+        for (const { item, caption } of parsed) {
+            const previous = seen.get(caption.index);
+            if (previous !== undefined) {
+                push('error', 'caption-duplicate', `${chapter}:${item.line} 与第 ${previous} 行都是「图 ${caption.chapter}-${caption.index}」：同一章图号不能重复。`);
+                continue;
+            }
+            seen.set(caption.index, item.line);
+        }
+        for (let i = 1; i < parsed.length; i += 1) {
+            const previous = parsed[i - 1].caption;
+            const current = parsed[i].caption;
+            if (current.index === previous.index)
+                continue; // 重复已在上面报过，不重复计一次跳号
+            if (current.index !== previous.index + 1) {
+                push('error', 'caption-sequence', `${chapter}:${parsed[i].item.line} 的图号是 ${current.chapter}-${current.index}，上一张是 ${previous.chapter}-${previous.index}：每章图号应连续递增（中间缺 ${current.chapter}-${previous.index + 1}）。`);
+            }
+        }
+        const first = parsed[0]?.caption;
+        if (first !== undefined && first.index > 1) {
+            const text = chapterText.get(chapter) ?? '';
+            const previousIndex = first.index - 1;
+            const mentioned = new RegExp(`图\\s*${first.chapter}\\s*[-－—–]\\s*${previousIndex}`).test(text);
+            if (!mentioned) {
+                push('error', 'caption-start', `${chapter} 的图片从 图 ${first.chapter}-${first.index} 开始，缺 图 ${first.chapter}-${previousIndex}：本章第一张图应从 -1 开始，或把那张图补回来。`);
+            }
+        }
+    }
+    // 4. assets 里的图有没有人用；纯截图（无 .drawio 源）只提示不报错。
+    for (const image of input.images) {
+        const key = image.path.replace(/\\/g, '/');
+        if ([...referenced.keys()].some(used => used === key))
+            continue;
+        const stemKey = `${dirOf(image.path)}/${stemOf(image.path)}`;
+        if (sourcesByStem.has(stemKey)) {
+            push('warn', 'unused-figure', `${image.path} 没有被任何章节引用：要么在正文补一句「如图 X-Y 所示」并放图，要么删掉这张图。`);
+        }
+    }
+    // 5. 汇总条目（按源文件优先，其次图片）。
+    const entries = [];
+    const seen = new Set();
+    const addEntry = (stem, source, image) => {
+        const key = `${stem}|${source ?? ''}|${image ?? ''}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const refs = [...(image === undefined ? [] : referenced.get(image.replace(/\\/g, '/')) ?? [])];
+        entries.push({ stem, ...(source !== undefined ? { source } : {}), ...(image !== undefined ? { image } : {}), references: refs });
+    };
+    for (const source of input.sources) {
+        const dir = dirOf(source.path);
+        const stem = stemOf(source.path);
+        const candidates = [`${dir}/${stem}.png`, `${dir}/${stem}.svg`].map(p => p.replace(/^\/+/, ''));
+        const image = candidates.map(path => imagesByPath.get(path)).find(item => item !== undefined);
+        addEntry(stem, source.path, image?.path);
+    }
+    for (const image of input.images) {
+        const stems = [...sourcesByStem.keys()].filter(key => key === `${dirOf(image.path)}/${stemOf(image.path)}`);
+        if (stems.length > 0)
+            continue;
+        addEntry(stemOf(image.path), undefined, image.path);
+    }
+    entries.sort((a, b) => a.stem.localeCompare(b.stem, 'zh-Hans-CN'));
+    return {
+        entries,
+        issues,
+        errors: issues.filter(issue => issue.severity === 'error').length,
+        warnings: issues.filter(issue => issue.severity === 'warn').length,
+    };
+}
+/** 渲染成 `图表清单.md`（同时给模型看，也随论文提交）。 */
+export function renderFigureReport(result, now = new Date()) {
+    const lines = [];
+    lines.push('# 图表清单');
+    lines.push('');
+    lines.push(`> 由 thesis_figure action=check 生成；时间：${now.toISOString()}`);
+    lines.push('> 源文件（.drawio）是可编辑真相，导出件（.png/.svg）供论文与幻灯使用。');
+    lines.push('');
+    lines.push('## 一、图的清单');
+    lines.push('');
+    if (result.entries.length === 0) {
+        lines.push('（还没有图。用 thesis_figure action=create 生成第一张。）');
+    }
+    else {
+        lines.push('| 图 | 源文件 | 导出件 | 引用的章节 |');
+        lines.push('|---|---|---|---|');
+        for (const entry of result.entries) {
+            lines.push(`| ${entry.stem} | ${entry.source ?? '（无，截图/外部图）'} | ${entry.image ?? '（未导出）'} | ${entry.references.length === 0 ? '—' : entry.references.join('、')} |`);
+        }
+    }
+    lines.push('');
+    lines.push('## 二、检查结论');
+    lines.push('');
+    if (result.issues.length === 0) {
+        lines.push('✓ 源文件、导出件、正文引用、图号四者一致。');
+    }
+    else {
+        for (const issue of result.issues) {
+            lines.push(`- ${issue.severity === 'error' ? '✗' : '⚠'} ${issue.message}`);
+        }
+    }
+    lines.push('');
+    lines.push(`合计：${result.errors} 个必须修的问题、${result.warnings} 个提示。`);
+    lines.push('');
+    lines.push('修完重跑 `thesis_figure action=check`；导出用 `thesis_figure action=export`。');
+    lines.push('');
+    return lines.join('\n');
+}

package/lib/figure/lib/drawio.d.ts

@@ -0,0 +1,123 @@
+/**
+ * draw.io（`.drawio` / mxfile）渲染：把版面模型写成 draw.io 能打开、学生能继续手工编辑的 XML。
+ *
+ * 为什么不用 Mermaid：Mermaid 是「文本进、自动布局出」，论文里的架构图、ER 图往往被
+ * 排成一张挤在一起的网，字号、配色、线型也由渲染器决定。draw.io 的源文件是**显式坐标**
+ * 的矢量图，可以精确控制版面、统一风格、导出高分辨率 PNG，并且改动仍可在 draw.io 里完成。
+ * 本模块只做两件事：给出一套论文用的风格常量，把 {@link FigureCell} 渲染成 mxfile。
+ *
+ * 约束（与仓库其它模块一致）：
+ * - 零依赖、确定性输出（同样的输入 + 同样的时间，字节完全一致）；
+ * - 正文里出现的一切用户文本都要转义，标签里的换行以 `<br>` 表达（draw.io 的 html=1）；
+ * - `custom` 图接受模型手写的 mxfile，但必须过 {@link validateMxfile}，不允许脚本与 DOCTYPE。
+ *
+ * @module dsh-thesis/figure/drawio
+ */
+/** 平面坐标（draw.io 单位：1 单位 ≈ 0.01 英寸，A4 纵向页宽 827）。 */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** 矩形几何。 */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** 一条要落进 mxGraphModel 的图元。 */
+export type FigureCell = {
+    readonly kind: 'vertex';
+    readonly id: string;
+    readonly value: string;
+    readonly style: string;
+    readonly rect: Rect;
+} | {
+    readonly kind: 'edge';
+    readonly id: string;
+    readonly value: string;
+    readonly style: string;
+    readonly source: string;
+    readonly target: string;
+    /** 手工折点（缺省交给 draw.io 的正交路由）。 */
+    readonly points?: readonly Point[];
+};
+/**
+ * 统一的插图风格。
+ *
+ * 取色原则：低饱和的蓝灰主色 + 大面积留白，黑白打印仍然分得清层次；
+ * 中文用宋体、层名用黑体，与论文正文的字体习惯一致（字体缺失时 draw.io 会回退，
+ * 不会影响图的可读性）。
+ */
+export declare const STYLE: {
+    /** 分层容器的底色（虚线框，不抢内容的注意力）。 */
+    readonly layerBand: "rounded=0;whiteSpace=wrap;html=1;fillColor=#F7F9FC;strokeColor=#C3CEDC;dashed=1;dashPattern=6 4;";
+    /** 分层名（左侧竖条）。 */
+    readonly layerLabel: "rounded=0;whiteSpace=wrap;html=1;fillColor=#E9EFF7;strokeColor=#C3CEDC;fontFamily=SimHei;fontSize=12;fontStyle=1;";
+    /** 普通模块。 */
+    readonly module: "rounded=1;arcSize=10;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#6E8FB5;fontFamily=SimSun;fontSize=12;";
+    /** 强调模块（系统的核心 / 答辩要讲的那一块）。 */
+    readonly moduleAccent: "rounded=1;arcSize=10;whiteSpace=wrap;html=1;fillColor=#DCE8F6;strokeColor=#3F6D9E;fontFamily=SimSun;fontSize=12;fontStyle=1;";
+    /** 流程起点。 */
+    readonly start: "rounded=1;arcSize=50;whiteSpace=wrap;html=1;fillColor=#E4F1DC;strokeColor=#6B9E5A;fontFamily=SimSun;fontSize=12;fontStyle=1;";
+    /** 流程终点。 */
+    readonly end: "rounded=1;arcSize=50;whiteSpace=wrap;html=1;fillColor=#F6E4E4;strokeColor=#B06A6A;fontFamily=SimSun;fontSize=12;fontStyle=1;";
+    /** 判断节点（菱形）。 */
+    readonly decision: "rhombus;whiteSpace=wrap;html=1;fillColor=#FFF6E0;strokeColor=#C9A24A;fontFamily=SimSun;fontSize=12;";
+    /** ER 实体标题栏。 */
+    readonly entityTitle: "rounded=0;whiteSpace=wrap;html=1;fillColor=#DCE8F6;strokeColor=#3F6D9E;fontFamily=SimHei;fontSize=12;fontStyle=1;";
+    /** ER 实体字段行。 */
+    readonly entityRow: "rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=8;fillColor=#FFFFFF;strokeColor=#9FB3C8;fontFamily=SimSun;fontSize=11;";
+    /** 时序图参与者（draw.io 自带生命线形状）。 */
+    readonly lifeline: "shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=0;collapsible=0;recursiveResize=0;outlineConnect=0;fontFamily=SimSun;fontSize=12;";
+    /** 实线箭头（调用 / 依赖）。标签加白底，压在线上也读得清。 */
+    readonly edge: "edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;endFill=1;strokeColor=#5F7F9F;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;";
+    /** 虚线箭头（返回 / 弱依赖）。 */
+    readonly edgeDashed: "edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=open;endFill=0;dashed=1;strokeColor=#5F7F9F;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;";
+    /** 时序图消息（水平箭头，无正交折线）。 */
+    readonly message: "html=1;verticalAlign=bottom;endArrow=block;endFill=1;rounded=0;strokeColor=#3F6D9E;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;";
+    /** 时序图返回消息。 */
+    readonly messageReturn: "html=1;verticalAlign=bottom;endArrow=open;endFill=0;dashed=1;rounded=0;strokeColor=#5F7F9F;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;";
+};
+/** XML 属性值转义（顺序有关：`&` 必须先转）。 */
+export declare function escapeXmlAttr(text: string): string;
+/** draw.io 标签：逐行转义后用 `<br>` 连接（html=1 时渲染成换行）。 */
+export declare function labelValue(text: string): string;
+/** mxfile 渲染参数。 */
+export interface MxFileOptions {
+    /** 图名（写进 `<diagram name>`，也是 draw.io 里的页签标题）。 */
+    readonly name: string;
+    readonly cells: readonly FigureCell[];
+    /** 页面宽（缺省 A4 纵向 827）。导出时 `--border` 会在内容外留白，页码本身不参与裁剪。 */
+    readonly pageWidth?: number;
+    /** 页面高（缺省按内容推算，最小 A4 纵向 1169）。 */
+    readonly pageHeight?: number;
+    /** 渲染时间（测试注入固定值；缺省当前时间）。 */
+    readonly now?: Date;
+}
+/** A4 纵向页宽（draw.io 单位）。 */
+export declare const DEFAULT_PAGE_WIDTH = 827;
+/** A4 纵向页高。 */
+export declare const DEFAULT_PAGE_HEIGHT = 1169;
+/**
+ * 渲染完整的 `.drawio` 文本。
+ *
+ * 顶层版本号写死为 `24.0.0`：draw.io 对高版本文件会走兼容分支，低版本号最稳；
+ * `host/agent` 标成 dsh-thesis，便于学生一眼看出这张图是谁生成的。
+ */
+export declare function renderMxfile(options: MxFileOptions): string;
+/** 自定义 mxfile 的校验结论。 */
+export type MxfileCheck = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * 校验 `custom` 图的手写 XML。
+ *
+ * 只做结构性检查（足够挡住「贴错内容」「贴成 SVG」这类事故），不做完整 XML 解析：
+ * 真解析需要额外依赖，而 draw.io 自己会在打开时报语法错。拒绝 `<!DOCTYPE` 与 `<script`
+ * 是安全底线：mxfile 可以内嵌 HTML 标签，脚本一旦被执行就是宿主风险。
+ */
+export declare function validateMxfile(xml: string): MxfileCheck;

package/lib/figure/lib/drawio.js

@@ -0,0 +1,156 @@
+/**
+ * draw.io（`.drawio` / mxfile）渲染：把版面模型写成 draw.io 能打开、学生能继续手工编辑的 XML。
+ *
+ * 为什么不用 Mermaid：Mermaid 是「文本进、自动布局出」，论文里的架构图、ER 图往往被
+ * 排成一张挤在一起的网，字号、配色、线型也由渲染器决定。draw.io 的源文件是**显式坐标**
+ * 的矢量图，可以精确控制版面、统一风格、导出高分辨率 PNG，并且改动仍可在 draw.io 里完成。
+ * 本模块只做两件事：给出一套论文用的风格常量，把 {@link FigureCell} 渲染成 mxfile。
+ *
+ * 约束（与仓库其它模块一致）：
+ * - 零依赖、确定性输出（同样的输入 + 同样的时间，字节完全一致）；
+ * - 正文里出现的一切用户文本都要转义，标签里的换行以 `<br>` 表达（draw.io 的 html=1）；
+ * - `custom` 图接受模型手写的 mxfile，但必须过 {@link validateMxfile}，不允许脚本与 DOCTYPE。
+ *
+ * @module dsh-thesis/figure/drawio
+ */
+// ---------------------------------------------------------------------------
+// 风格：论文插图用的统一预设
+// ---------------------------------------------------------------------------
+/**
+ * 统一的插图风格。
+ *
+ * 取色原则：低饱和的蓝灰主色 + 大面积留白，黑白打印仍然分得清层次；
+ * 中文用宋体、层名用黑体，与论文正文的字体习惯一致（字体缺失时 draw.io 会回退，
+ * 不会影响图的可读性）。
+ */
+export const STYLE = {
+    /** 分层容器的底色（虚线框，不抢内容的注意力）。 */
+    layerBand: 'rounded=0;whiteSpace=wrap;html=1;fillColor=#F7F9FC;strokeColor=#C3CEDC;dashed=1;dashPattern=6 4;',
+    /** 分层名（左侧竖条）。 */
+    layerLabel: 'rounded=0;whiteSpace=wrap;html=1;fillColor=#E9EFF7;strokeColor=#C3CEDC;fontFamily=SimHei;fontSize=12;fontStyle=1;',
+    /** 普通模块。 */
+    module: 'rounded=1;arcSize=10;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#6E8FB5;fontFamily=SimSun;fontSize=12;',
+    /** 强调模块（系统的核心 / 答辩要讲的那一块）。 */
+    moduleAccent: 'rounded=1;arcSize=10;whiteSpace=wrap;html=1;fillColor=#DCE8F6;strokeColor=#3F6D9E;fontFamily=SimSun;fontSize=12;fontStyle=1;',
+    /** 流程起点。 */
+    start: 'rounded=1;arcSize=50;whiteSpace=wrap;html=1;fillColor=#E4F1DC;strokeColor=#6B9E5A;fontFamily=SimSun;fontSize=12;fontStyle=1;',
+    /** 流程终点。 */
+    end: 'rounded=1;arcSize=50;whiteSpace=wrap;html=1;fillColor=#F6E4E4;strokeColor=#B06A6A;fontFamily=SimSun;fontSize=12;fontStyle=1;',
+    /** 判断节点（菱形）。 */
+    decision: 'rhombus;whiteSpace=wrap;html=1;fillColor=#FFF6E0;strokeColor=#C9A24A;fontFamily=SimSun;fontSize=12;',
+    /** ER 实体标题栏。 */
+    entityTitle: 'rounded=0;whiteSpace=wrap;html=1;fillColor=#DCE8F6;strokeColor=#3F6D9E;fontFamily=SimHei;fontSize=12;fontStyle=1;',
+    /** ER 实体字段行。 */
+    entityRow: 'rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=8;fillColor=#FFFFFF;strokeColor=#9FB3C8;fontFamily=SimSun;fontSize=11;',
+    /** 时序图参与者（draw.io 自带生命线形状）。 */
+    lifeline: 'shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=0;collapsible=0;recursiveResize=0;outlineConnect=0;fontFamily=SimSun;fontSize=12;',
+    /** 实线箭头（调用 / 依赖）。标签加白底，压在线上也读得清。 */
+    edge: 'edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;endFill=1;strokeColor=#5F7F9F;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;',
+    /** 虚线箭头（返回 / 弱依赖）。 */
+    edgeDashed: 'edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=open;endFill=0;dashed=1;strokeColor=#5F7F9F;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;',
+    /** 时序图消息（水平箭头，无正交折线）。 */
+    message: 'html=1;verticalAlign=bottom;endArrow=block;endFill=1;rounded=0;strokeColor=#3F6D9E;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;',
+    /** 时序图返回消息。 */
+    messageReturn: 'html=1;verticalAlign=bottom;endArrow=open;endFill=0;dashed=1;rounded=0;strokeColor=#5F7F9F;labelBackgroundColor=#FFFFFF;fontFamily=SimSun;fontSize=11;',
+};
+// ---------------------------------------------------------------------------
+// 转义与渲染
+// ---------------------------------------------------------------------------
+/** XML 属性值转义（顺序有关：`&` 必须先转）。 */
+export function escapeXmlAttr(text) {
+    return text
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+/** draw.io 标签：逐行转义后用 `&lt;br&gt;` 连接（html=1 时渲染成换行）。 */
+export function labelValue(text) {
+    return text
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map(line => escapeXmlAttr(line.trimEnd()))
+        .join('&lt;br&gt;');
+}
+/** 数字统一保留两位小数，避免浮点尾巴让 diff 噪音变大。 */
+function num(value) {
+    const rounded = Math.round(value * 100) / 100;
+    return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(2);
+}
+function renderGeometry(cell) {
+    const { x, y, width, height } = cell.rect;
+    return `<mxGeometry x="${num(x)}" y="${num(y)}" width="${num(width)}" height="${num(height)}" as="geometry" />`;
+}
+function renderEdgeGeometry(cell) {
+    const points = cell.points ?? [];
+    if (points.length === 0)
+        return '<mxGeometry relative="1" as="geometry" />';
+    const rendered = points.map(p => `<mxPoint x="${num(p.x)}" y="${num(p.y)}" />`).join('');
+    return `<mxGeometry relative="1" as="geometry"><Array as="points">${rendered}</Array></mxGeometry>`;
+}
+function renderCell(cell) {
+    if (cell.kind === 'vertex') {
+        // 所有图元都挂在根层、用**绝对坐标**：mxGraph 里子图元的 geometry 是相对父图元的，
+        // 把模块嵌进层带（parent=band）会让坐标整体再偏移一次，图直接错位。
+        // 层带与模块的包含关系靠视觉位置表达，不靠 cell 嵌套。
+        // 标签走 labelValue：换行转成 `&lt;br&gt;`（html=1 时 draw.io 才认多行）。
+        return `<mxCell id="${escapeXmlAttr(cell.id)}" value="${labelValue(cell.value)}" style="${escapeXmlAttr(cell.style)}" vertex="1" parent="1">${renderGeometry(cell)}</mxCell>`;
+    }
+    return `<mxCell id="${escapeXmlAttr(cell.id)}" value="${labelValue(cell.value)}" style="${escapeXmlAttr(cell.style)}" edge="1" parent="1" source="${escapeXmlAttr(cell.source)}" target="${escapeXmlAttr(cell.target)}">${renderEdgeGeometry(cell)}</mxCell>`;
+}
+/** A4 纵向页宽（draw.io 单位）。 */
+export const DEFAULT_PAGE_WIDTH = 827;
+/** A4 纵向页高。 */
+export const DEFAULT_PAGE_HEIGHT = 1169;
+/**
+ * 渲染完整的 `.drawio` 文本。
+ *
+ * 顶层版本号写死为 `24.0.0`：draw.io 对高版本文件会走兼容分支，低版本号最稳；
+ * `host/agent` 标成 dsh-thesis，便于学生一眼看出这张图是谁生成的。
+ */
+export function renderMxfile(options) {
+    const now = options.now ?? new Date();
+    const pageWidth = options.pageWidth ?? DEFAULT_PAGE_WIDTH;
+    const pageHeight = options.pageHeight ?? DEFAULT_PAGE_HEIGHT;
+    const cells = options.cells.map(renderCell).join('');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<mxfile host="dsh-thesis" modified="${now.toISOString()}" agent="dsh-thesis" version="24.0.0" type="device">`,
+        `  <diagram id="dsh-thesis-figure" name="${escapeXmlAttr(options.name)}">`,
+        `    <mxGraphModel dx="${pageWidth}" dy="${pageHeight}" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="${pageWidth}" pageHeight="${pageHeight}" math="0" shadow="0">`,
+        '      <root>',
+        '        <mxCell id="0" />',
+        '        <mxCell id="1" parent="0" />',
+        `        ${cells}`,
+        '      </root>',
+        '    </mxGraphModel>',
+        '  </diagram>',
+        '</mxfile>',
+        '',
+    ].join('\n');
+}
+/**
+ * 校验 `custom` 图的手写 XML。
+ *
+ * 只做结构性检查（足够挡住「贴错内容」「贴成 SVG」这类事故），不做完整 XML 解析：
+ * 真解析需要额外依赖，而 draw.io 自己会在打开时报语法错。拒绝 `<!DOCTYPE` 与 `<script`
+ * 是安全底线：mxfile 可以内嵌 HTML 标签，脚本一旦被执行就是宿主风险。
+ */
+export function validateMxfile(xml) {
+    const text = xml.trim();
+    if (text === '')
+        return { ok: false, reason: 'custom 图的 xml 为空' };
+    if (/<!DOCTYPE/i.test(text))
+        return { ok: false, reason: 'custom 图的 xml 不允许 <!DOCTYPE（draw.io 也不需要）' };
+    if (/<script[\s>]/i.test(text))
+        return { ok: false, reason: 'custom 图的 xml 不允许 <script>' };
+    if (!/^<\?xml[^>]*\?>\s*<mxfile[\s>]/i.test(text) && !/^<mxfile[\s>]/i.test(text)) {
+        return { ok: false, reason: 'custom 图必须以 <mxfile> 开头（draw.io 的「文件 → 另存为 .drawio」就是这种格式）' };
+    }
+    if (!/<mxGraphModel[\s>]/i.test(text))
+        return { ok: false, reason: 'custom 图缺少 <mxGraphModel>（不是有效的 draw.io 图）' };
+    if (!/<root[\s>]/i.test(text))
+        return { ok: false, reason: 'custom 图缺少 <root>（mxGraphModel 里必须有一个根层）' };
+    return { ok: true };
+}