dsh-thesis 2.0.2 → 2.1.1

package/lib/paper/lib/docx.js

@@ -23,6 +23,14 @@ export function parseMarkdownBlocks(markdown) {
             i += 1;
             continue;
         }
+        // 图片：独占一行的 `![图题](路径)`；路径可写成 `<...>`（构建时会改写为绝对路径）。
+        // 图题（alt）在图**下方**，与论文规范一致。
+        const image = /^!\[([^\]]*)\]\(\s*(?:<([^>]+)>|([^)\s]+))(?:\s+"[^"]*")?\s*\)$/.exec(trimmed);
+        if (image !== null) {
+            blocks.push({ kind: 'image', alt: image[1] ?? '', src: image[2] ?? image[3] ?? '' });
+            i += 1;
+            continue;
+        }
         // 表格：连续的 | 行（跳过分隔行）
         if (trimmed.startsWith('|') && trimmed.endsWith('|')) {
             const rows = [];
@@ -88,8 +96,12 @@ function parseInline(text) {
     }
     return runs;
 }
-function runsXml(runs) {
-    return runs.map(run => `<w:r><w:rPr>${run.bold ? '<w:b/>' : ''}</w:rPr><w:t xml:space="preserve">${escapeXml(run.text)}</w:t></w:r>`).join('');
+function runsXml(runs, opts) {
+    const sizeXml = opts?.size !== undefined ? `<w:sz w:val="${opts.size}"/><w:szCs w:val="${opts.size}"/>` : '';
+    return runs.map(run => {
+        const bold = opts?.bold ?? run.bold;
+        return `<w:r><w:rPr>${bold ? '<w:b/>' : ''}${sizeXml}</w:rPr><w:t xml:space="preserve">${escapeXml(run.text)}</w:t></w:r>`;
+    }).join('');
 }
 function paragraphXml(text, styleId, pageBreakBefore = false) {
     const pPr = styleId !== undefined || pageBreakBefore
@@ -97,41 +109,79 @@ function paragraphXml(text, styleId, pageBreakBefore = false) {
         : '';
     return `<w:p>${pPr}${runsXml(parseInline(text))}</w:p>`;
 }
+/** 表题行（`表 4-1 模块划分`）：走 Caption 样式居中，与图题同一套口径。 */
+export function isTableCaption(text) {
+    return /^表\s*\d+\s*[-–—]\s*\d+\s+\S/.test(text);
+}
 function blockXml(block) {
     switch (block.kind) {
         case 'h1': return paragraphXml(block.text, 'Heading1', true);
         case 'h2': return paragraphXml(block.text, 'Heading2');
         case 'h3': return paragraphXml(block.text, 'Heading3');
-        case 'p': return paragraphXml(block.text);
+        case 'p': return isTableCaption(block.text) ? paragraphXml(block.text, 'Caption') : paragraphXml(block.text);
         case 'bullet': return paragraphXml(`• ${block.text}`, 'ListBullet');
-        case 'table': {
-            const rows = block.rows.map(row => {
-                const cells = row.map(cell => `<w:tc><w:p>${runsXml(parseInline(cell))}</w:p></w:tc>`).join('');
-                return `<w:tr>${cells}</w:tr>`;
-            }).join('');
-            return `<w:tbl><w:tblPr><w:tblStyle w:val="TableGrid"/><w:tblW w:w="0" w:type="auto"/></w:tblPr>${rows}</w:tbl>`;
-        }
+        case 'table': return renderTableXml(block.rows);
     }
 }
 // ---------------------------------------------------------------------------
+// 表格：三线表（顶线 1.5pt / 栏目线 0.75pt / 底线 1.5pt，无竖线）
+// ---------------------------------------------------------------------------
+const TABLE_HALF_POINTS = 21; // 五号 10.5pt
+const NUMERIC_CELL = /^[\d\s.,%+\-–—~/×x≈]*\s*(?:ms|s|秒|个|次|%)?$/;
+function isNumericColumn(rows, column) {
+    const cells = rows.slice(1).map(row => row[column]?.trim() ?? '').filter(cell => cell !== '');
+    if (cells.length === 0)
+        return false;
+    return cells.every(cell => NUMERIC_CELL.test(cell) && /\d/.test(cell));
+}
+function tableCellXml(text, header, center) {
+    const rules = header
+        ? '<w:tcBorders><w:bottom w:val="single" w:sz="6" w:space="0" w:color="000000"/></w:tcBorders>'
+        : '';
+    const paragraph = `<w:p><w:pPr><w:jc w:val="${center ? 'center' : 'left'}"/><w:spacing w:before="30" w:after="30"/></w:pPr>` +
+        `${runsXml(parseInline(text), { size: TABLE_HALF_POINTS, bold: header })}</w:p>`;
+    return `<w:tc><w:tcPr>${rules}<w:vAlign w:val="center"/></w:tcPr>${paragraph}</w:tc>`;
+}
+/**
+ * 三线表：表格只靠三条横线成形，不画竖线、不做隔行底纹。
+ * 表头跨页重复（tblHeader），表内五号字，表头加粗居中，数字列居中。
+ */
+export function renderTableXml(rows) {
+    if (rows.length === 0)
+        return '';
+    const columns = Math.max(...rows.map(row => row.length));
+    const borders = '<w:tblBorders>' +
+        '<w:top w:val="single" w:sz="12" w:space="0" w:color="000000"/>' +
+        '<w:left w:val="none" w:sz="0" w:space="0" w:color="auto"/>' +
+        '<w:bottom w:val="single" w:sz="12" w:space="0" w:color="000000"/>' +
+        '<w:right w:val="none" w:sz="0" w:space="0" w:color="auto"/>' +
+        '<w:insideH w:val="none" w:sz="0" w:space="0" w:color="auto"/>' +
+        '<w:insideV w:val="none" w:sz="0" w:space="0" w:color="auto"/>' +
+        '</w:tblBorders>';
+    const margins = '<w:tblCellMar><w:top w:w="40" w:type="dxa"/><w:left w:w="85" w:type="dxa"/>' +
+        '<w:bottom w:w="40" w:type="dxa"/><w:right w:w="85" w:type="dxa"/></w:tblCellMar>';
+    const props = `<w:tblPr><w:tblW w:w="5000" w:type="pct"/><w:jc w:val="center"/>${borders}` +
+        `<w:tblLayout w:type="autofit"/>${margins}<w:tblLook w:val="04A0" w:firstRow="1" w:lastRow="0" w:firstColumn="0" w:lastColumn="0" w:noHBand="0" w:noVBand="1"/></w:tblPr>`;
+    const grid = `<w:tblGrid>${'<w:gridCol/>'.repeat(columns)}</w:tblGrid>`;
+    const body = rows.map((row, index) => {
+        const header = index === 0;
+        const cells = Array.from({ length: columns }, (_, column) => {
+            const text = row[column] ?? '';
+            return tableCellXml(text, header, header || isNumericColumn(rows, column));
+        }).join('');
+        const trProps = header ? '<w:trPr><w:cantSplit/><w:tblHeader/></w:trPr>' : '<w:trPr><w:cantSplit/></w:trPr>';
+        return `<w:tr>${trProps}${cells}</w:tr>`;
+    }).join('');
+    return `<w:tbl>${props}${grid}${body}</w:tbl>`;
+}
+// ---------------------------------------------------------------------------
 // 文档装配
 // ---------------------------------------------------------------------------
-const CONTENT_TYPES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
-  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
-  <Default Extension="xml" ContentType="application/xml"/>
-  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
-  <Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
-</Types>
-`;
 const ROOT_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
   <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
 </Relationships>
 `;
-const DOCUMENT_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"/>
-`;
 const STYLES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
   <w:docDefaults>
@@ -168,6 +218,11 @@ const STYLES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <w:rPr><w:rFonts w:eastAsia="黑体"/><w:b/><w:sz w:val="26"/><w:szCs w:val="26"/></w:rPr>
   </w:style>
   <w:style w:type="paragraph" w:styleId="ListBullet"><w:name w:val="List Bullet"/></w:style>
+  <w:style w:type="paragraph" w:styleId="Caption">
+    <w:name w:val="caption"/>
+    <w:pPr><w:jc w:val="center"/><w:spacing w:before="40" w:after="200"/></w:pPr>
+    <w:rPr><w:rFonts w:eastAsia="宋体"/><w:sz w:val="21"/><w:szCs w:val="21"/></w:rPr>
+  </w:style>
   <w:style w:type="table" w:styleId="TableGrid">
     <w:name w:val="Table Grid"/>
     <w:tblPr>
@@ -183,8 +238,58 @@ const STYLES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   </w:style>
 </w:styles>
 `;
+/** 1 像素按 96dpi 折算的 EMU。 */
+const EMU_PER_PIXEL = 9_525;
+/** 正文栏宽（A4、2.54cm 页边距约 15.9cm），插图最宽取 15cm。 */
+const MAX_IMAGE_WIDTH_EMU = 5_400_000;
+/** 单张图最高 20cm：再高就会把图题挤到下一页。 */
+const MAX_IMAGE_HEIGHT_EMU = 7_200_000;
+/** 按像素尺寸算出等比例缩放后的 EMU 宽高。 */
+function imageExtent(image) {
+    let cx = Math.max(1, image.width) * EMU_PER_PIXEL;
+    let cy = Math.max(1, image.height) * EMU_PER_PIXEL;
+    const widthScale = Math.min(1, MAX_IMAGE_WIDTH_EMU / cx);
+    cx = Math.round(cx * widthScale);
+    cy = Math.round(cy * widthScale);
+    if (cy > MAX_IMAGE_HEIGHT_EMU) {
+        const heightScale = MAX_IMAGE_HEIGHT_EMU / cy;
+        cx = Math.round(cx * heightScale);
+        cy = Math.round(cy * heightScale);
+    }
+    return { cx, cy };
+}
+/**
+ * 一张图的 WordprocessingML：居中段落 + inline drawing + 图题。
+ *
+ * 图题用单独的 Caption 段落（居中、五号），而不是塞进图片的替代文字里：
+ * 论文的图题必须能被选中、能被目录/交叉引用识别，也才能通过"图题在图下方"的检查。
+ */
+function imageXml(alt, part, image, index) {
+    if (part === undefined || image === undefined) {
+        const missing = alt === '' ? '图片缺失' : alt;
+        return paragraphXml(`［${missing}：图片文件未找到，请检查路径］`);
+    }
+    const { cx, cy } = imageExtent(image);
+    const drawing = `<w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0">`
+        + `<wp:extent cx="${cx}" cy="${cy}"/><wp:effectExtent l="0" t="0" r="0" b="0"/>`
+        + `<wp:docPr id="${index}" name="图片 ${index}"/><wp:cNvGraphicFramePr><a:graphicFrameLocks noChangeAspect="1"/></wp:cNvGraphicFramePr>`
+        + '<a:graphic><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:pic>'
+        + `<pic:nvPicPr><pic:cNvPr id="${index}" name="${escapeXml(part.partName)}"/><pic:cNvPicPr/></pic:nvPicPr>`
+        + `<pic:blipFill><a:blip r:embed="${part.rId}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill>`
+        + `<pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${cx}" cy="${cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr>`
+        + '</pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing>';
+    const imageParagraph = `<w:p><w:pPr><w:jc w:val="center"/><w:spacing w:before="120" w:after="60"/></w:pPr><w:r>${drawing}</w:r></w:p>`;
+    const caption = alt === ''
+        ? ''
+        : `<w:p><w:pPr><w:pStyle w:val="Caption"/><w:jc w:val="center"/></w:pPr><w:r><w:t xml:space="preserve">${escapeXml(alt)}</w:t></w:r></w:p>`;
+    return imageParagraph + caption;
+}
 /**
  * 生成完整 .docx 字节。title 渲染为封面页；markdown 为正文（章节合并内容）。
+ *
+ * 图片按 `images` 里的字节嵌入：`![图 4-1 系统总体架构图](绝对路径)` 会变成
+ * 「居中的图 + 图下方的图题」。找不到字节的图片降级成一行可读的占位文字——
+ * 缺图必须在 Word 里一眼看见，不能静默消失。
  */
 export function buildDocx(opts) {
     const blocks = parseMarkdownBlocks(opts.markdown);
@@ -192,22 +297,80 @@ export function buildDocx(opts) {
     body.push(paragraphXml(opts.title, 'TitlePage'));
     body.push(paragraphXml('本科毕业论文（设计）', 'Subtitle'));
     body.push('<w:p/>');
-    for (const block of blocks)
-        body.push(blockXml(block));
+    const parts = [];
+    const formats = new Set();
+    let imageIndex = 0;
+    for (const block of blocks) {
+        if (block.kind !== 'image') {
+            body.push(blockXml(block));
+            continue;
+        }
+        imageIndex += 1;
+        const image = opts.images?.get(block.src);
+        let part;
+        if (image !== undefined) {
+            const extension = image.format === 'png' ? 'png' : 'jpg';
+            part = {
+                rId: `rIdImg${imageIndex}`,
+                partName: `media/image${imageIndex}.${extension}`,
+                data: image.data,
+                format: image.format,
+            };
+            parts.push(part);
+            formats.add(image.format);
+        }
+        body.push(imageXml(block.alt, part, image, imageIndex));
+    }
     const document = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
   <w:body>
     ${body.join('')}
-    <w:sectPr><w:pgSz w:w="11906" w:h="16838"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/></w:sectPr>
+    <w:sectPr><w:pgSz w:w="11906" w:h="16838"/><w:pgMar w:top="1417" w:right="1417" w:bottom="1417" w:left="1701" w:header="851" w:footer="992" w:gutter="0"/></w:sectPr>
   </w:body>
 </w:document>
 `;
     const entries = [
-        { name: '[Content_Types].xml', data: encoder.encode(CONTENT_TYPES) },
+        { name: '[Content_Types].xml', data: encoder.encode(contentTypes(formats)) },
         { name: '_rels/.rels', data: encoder.encode(ROOT_RELS) },
         { name: 'word/document.xml', data: encoder.encode(document) },
         { name: 'word/styles.xml', data: encoder.encode(STYLES) },
-        { name: 'word/_rels/document.xml.rels', data: encoder.encode(DOCUMENT_RELS) },
+        { name: 'word/_rels/document.xml.rels', data: encoder.encode(documentRels(parts)) },
     ];
+    for (const part of parts) {
+        entries.push({ name: `word/${part.partName}`, data: part.data });
+    }
     return buildZip(entries);
 }
+/** `[Content_Types].xml`：基础部件 + 实际用到的图片格式。 */
+function contentTypes(formats) {
+    const defaults = [
+        ...(formats.has('png') ? ['  <Default Extension="png" ContentType="image/png"/>'] : []),
+        ...(formats.has('jpeg') ? ['  <Default Extension="jpg" ContentType="image/jpeg"/>'] : []),
+    ].join('\n');
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+${defaults === '' ? '' : `${defaults}\n`}  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+  <Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
+</Types>
+`;
+}
+/**
+ * `word/_rels/document.xml.rels`：样式部件必须在关系里**显式登记**。
+ *
+ * 这一条曾经漏过：`styles.xml` 写进了包、`[Content_Types].xml` 也声明了，但没有
+ * relationship 时 Word 不会应用任何样式（标题、图题全变成普通正文），python-docx
+ * 更是直接只看到 4 个内置样式。图片关系与样式关系都从这里出。
+ */
+function documentRels(parts) {
+    const relationships = [
+        '  <Relationship Id="rIdStyles" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>',
+        ...parts.map(part => `  <Relationship Id="${part.rId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="${part.partName}"/>`),
+    ].join('\n');
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+${relationships}
+</Relationships>
+`;
+}

package/lib/paper/lib/image.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 图片头部解析：只为拿到像素宽高，好让 Word 里的图按原比例排版、且不超出栏宽。
+ *
+ * 不引入图像库：论文插图只有 PNG（draw.io 导出、系统截图）与 JPEG（照片/手机截图），
+ * 两种格式的尺寸都在文件头前几十字节里，读几十个字节即可。解析不出来时返回 undefined，
+ * 调用方按「未知尺寸」降级（用默认宽度），绝不猜一个尺寸然后把图拉变形。
+ *
+ * @module dsh-thesis/paper/image
+ */
+/** 识别出的图片格式与像素尺寸。 */
+export interface ImageInfo {
+    readonly format: 'png' | 'jpeg';
+    readonly width: number;
+    readonly height: number;
+}
+/** 解析图片宽高；不认识或数据不完整时返回 undefined。 */
+export declare function readImageInfo(bytes: Uint8Array): ImageInfo | undefined;
+/** 从文件名推断格式（用于 Word 的 content-type）；不认识返回 undefined。 */
+export declare function imageFormatOf(path: string): 'png' | 'jpeg' | undefined;

package/lib/paper/lib/image.js

@@ -0,0 +1,82 @@
+/**
+ * 图片头部解析：只为拿到像素宽高，好让 Word 里的图按原比例排版、且不超出栏宽。
+ *
+ * 不引入图像库：论文插图只有 PNG（draw.io 导出、系统截图）与 JPEG（照片/手机截图），
+ * 两种格式的尺寸都在文件头前几十字节里，读几十个字节即可。解析不出来时返回 undefined，
+ * 调用方按「未知尺寸」降级（用默认宽度），绝不猜一个尺寸然后把图拉变形。
+ *
+ * @module dsh-thesis/paper/image
+ */
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function readU32BE(bytes, offset) {
+    return ((bytes[offset] ?? 0) << 24) | ((bytes[offset + 1] ?? 0) << 16) | ((bytes[offset + 2] ?? 0) << 8) | (bytes[offset + 3] ?? 0);
+}
+function readU16BE(bytes, offset) {
+    return ((bytes[offset] ?? 0) << 8) | (bytes[offset + 1] ?? 0);
+}
+function isPng(bytes) {
+    if (bytes.length < 24)
+        return false;
+    return PNG_SIGNATURE.every((byte, index) => bytes[index] === byte);
+}
+function isJpeg(bytes) {
+    return bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8;
+}
+/** 读 PNG 的 IHDR（宽高就在 16..23 字节）。 */
+function pngInfo(bytes) {
+    const width = readU32BE(bytes, 16);
+    const height = readU32BE(bytes, 20);
+    if (width <= 0 || height <= 0)
+        return undefined;
+    return { format: 'png', width, height };
+}
+/** 扫描 JPEG 的 SOFn 段拿宽高。 */
+function jpegInfo(bytes) {
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+        if (bytes[offset] !== 0xff) {
+            offset += 1;
+            continue;
+        }
+        const marker = bytes[offset + 1] ?? 0;
+        // 填充字节 0xFF 与无载荷标记（RSTn / SOI / EOI）直接跳过。
+        if (marker === 0xff) {
+            offset += 1;
+            continue;
+        }
+        if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) {
+            offset += 2;
+            continue;
+        }
+        const length = readU16BE(bytes, offset + 2);
+        if (length < 2)
+            return undefined;
+        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof) {
+            const height = readU16BE(bytes, offset + 5);
+            const width = readU16BE(bytes, offset + 7);
+            if (width <= 0 || height <= 0)
+                return undefined;
+            return { format: 'jpeg', width, height };
+        }
+        offset += 2 + length;
+    }
+    return undefined;
+}
+/** 解析图片宽高；不认识或数据不完整时返回 undefined。 */
+export function readImageInfo(bytes) {
+    if (isPng(bytes))
+        return pngInfo(bytes);
+    if (isJpeg(bytes))
+        return jpegInfo(bytes);
+    return undefined;
+}
+/** 从文件名推断格式（用于 Word 的 content-type）；不认识返回 undefined。 */
+export function imageFormatOf(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith('.png'))
+        return 'png';
+    if (lower.endsWith('.jpg') || lower.endsWith('.jpeg'))
+        return 'jpeg';
+    return undefined;
+}

package/lib/paper/lib/layout.js

@@ -310,7 +310,8 @@ ${HEADER_NOTE}
 
 ## 1 总体架构
 
-<架构图：可用 Mermaid（flowchart/architecture）>
+<架构图：用 thesis_figure action=create kind=architecture 生成 .drawio 与 PNG；
+图放 06-论文/assets/图/，图题写「图 4-1 系统总体架构图」，正文先引用再出图>
 
 ## 2 模块划分
 
@@ -390,6 +391,30 @@ ${HEADER_NOTE}
         });
     }
     files.push({ path: '06-论文/图表/.gitkeep', content: '' });
+    files.push({
+        path: '06-论文/assets/图/README.md',
+        content: `# 这里放论文的图
+
+${HEADER_NOTE}
+
+**源文件**：每张图一个 \`.drawio\`（draw.io 格式，随时可改）。**导出件**：同名 \`.png\`（论文用，3× 导出）或 \`.svg\`（幻灯用）。
+
+## 命名与引用
+
+- 文件名用英文小写与短横线：\`arch-overview.drawio\`、\`arch-overview.png\`。
+- 章节里的路径相对章节文件（\`06-论文/章节/\`），写成 \`../assets/图/arch-overview.png\`。
+- 图题在图片下一行，格式 \`图 4-1 系统总体架构图\`；正文先写「如图 4-1 所示」再出现图。
+
+## 出图与体检
+
+- 生成：\`thesis_figure action=create\`（kind = architecture / flow / er / sequence / custom）。
+- 导出：\`thesis_figure action=export\`（需要 draw.io 桌面版；没有时按 \`action=guide\` 的替代路径导出）。
+- 覆盖同名图时旧版本自动存进 \`历史/\`（不参与导出与体检）。
+- 体检：\`thesis_figure action=check\` → 生成本目录下的 \`图表清单.md\`，核对源文件、导出件、引用与图号。
+
+> 红线：论文里的每张图都必须能在这里找到源文件（系统截图除外，需在正文注明来自真实运行）。
+`,
+    });
     files.push({
         path: '06-论文/assets/学校模板/README.md',
         content: `# 学校模板与规范

package/lib/paper/lib/lit-refs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 候选文献解析：把 Undermind / Elicit / Consensus / Zotero / Google Scholar
+ * 导出的 `.bib`、`.ris`、`.csv` 读成统一的 `CandidateRef[]`。
+ *
+ * 只做**解析**，不做判断：解析结果一律视为「声称值」，必须再过
+ * `lit-verify.ts` 的权威库对账才能进 refs.bib。解析器不联网、不改写元数据，
+ * 解析不了的字段留空并给出警告（警告会出现在核验报告里）。
+ */
+import type { CandidateRef } from './lit-verify.ts';
+export type RefFormat = 'bibtex' | 'ris' | 'csv';
+export interface ParsedRefs {
+    readonly format: RefFormat;
+    readonly candidates: CandidateRef[];
+    readonly warnings: string[];
+}
+/** 按扩展名与内容特征判断格式；都不像时返回 null。 */
+export declare function detectRefFormat(fileName: string, text: string): RefFormat | null;
+export declare function parseRefs(fileName: string, text: string, source: string): ParsedRefs;
+/** 作者串 → 姓名数组。兼容 `A; B`、`A and B`、JSON 数组、`A, B, C`（≥3 个时的兜底）。 */
+export declare function splitAuthors(raw: string): string[];
+interface RawEntry {
+    readonly type: string;
+    readonly key: string;
+    readonly fields: Map<string, string>;
+}
+/** 扫出所有 `@type{key, body}`；用花括号配对找条目结尾，能容忍嵌套 `{}` 与多行字段。 */
+export declare function bibEntries(text: string): RawEntry[];
+/** RFC4180 风格解析：支持双引号包裹、`""` 转义、字段内换行。 */
+export declare function parseCsvRows(text: string, delimiter?: string): string[][];
+export {};