dsh-thesis 2.0.2 → 2.1.1

package/lib/figure/lib/spec.js

@@ -0,0 +1,290 @@
+/**
+ * 图的「结构化规格」：模型只需描述**有什么**，不描述**放在哪**。
+ *
+ * 教学场景里的图之所以糙，多半不是因为画得少，而是因为让模型直接写坐标：
+ * 节点一多就重叠、箭头乱穿、字号忽大忽小。于是这里把输入收窄成业务语义
+ * （层与模块、步骤与分支、实体与字段、参与者与消息），坐标交给
+ * `layout.ts` 的确定性版面算法——同样的输入永远得到同一张图。
+ *
+ * 解析是**严格**的：字段缺失、引用不存在的节点、重名，全部当场报错并给出示例，
+ * 绝不让一张「少了两个模块」的图静默落盘。
+ *
+ * @module dsh-thesis/figure/spec
+ */
+/** 全部种类的取值（用于工具参数的枚举与报错提示）。 */
+export const FIGURE_KINDS = ['architecture', 'flow', 'er', 'sequence', 'custom'];
+/** 规格非法：带上**怎么改**的提示，模型据此重试。 */
+export class FigureSpecError extends Error {
+    code = 'INVALID_FIGURE_SPEC';
+    constructor(message) {
+        super(message);
+        this.name = 'FigureSpecError';
+    }
+}
+// ---------------------------------------------------------------------------
+// 校验小工具
+// ---------------------------------------------------------------------------
+function fail(message) {
+    throw new FigureSpecError(message);
+}
+function asRecord(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        fail(`${path} 必须是对象，实际是 ${value === null ? 'null' : Array.isArray(value) ? '数组' : typeof value}`);
+    }
+    return value;
+}
+function asArray(value, path) {
+    if (!Array.isArray(value))
+        fail(`${path} 必须是数组`);
+    return value;
+}
+function requiredText(value, path) {
+    if (typeof value !== 'string')
+        fail(`${path} 必须是字符串`);
+    const text = value.trim();
+    if (text === '')
+        fail(`${path} 不能为空`);
+    return text;
+}
+function optionalText(value, path) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        fail(`${path} 必须是字符串`);
+    const text = value.trim();
+    return text === '' ? undefined : text;
+}
+function optionalBool(value, path) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'boolean')
+        fail(`${path} 必须是布尔值`);
+    return value;
+}
+/** 一个引用（边/关系）的解析表：同时接受 id 与显示文本。 */
+function makeResolver(entries, path) {
+    const byId = new Map();
+    const byText = new Map();
+    for (const entry of entries) {
+        if (byId.has(entry.id))
+            fail(`${path} 里 id「${entry.id}」重复`);
+        byId.set(entry.id, entry.id);
+        byText.set(entry.text, entry.id);
+    }
+    return (name) => {
+        const id = byId.get(name) ?? byText.get(name);
+        if (id === undefined) {
+            const known = [...byId.keys()].join('、');
+            fail(`${path} 引用了不存在的节点「${name}」；可用的是：${known}`);
+        }
+        return id;
+    };
+}
+// ---------------------------------------------------------------------------
+// 各类型的解析
+// ---------------------------------------------------------------------------
+const ARCH_EXAMPLE = '{"layers":[{"name":"表现层","modules":["Vue 页面","路由与状态"]},{"name":"业务层","modules":["任务服务","用户服务"]}],"edges":[{"from":"Vue 页面","to":"任务服务","label":"HTTP/JSON"}]}';
+function parseArchitecture(raw) {
+    const record = asRecord(raw, 'architecture 的 spec');
+    const layersRaw = asArray(record.layers, 'architecture.layers（不能为空）');
+    if (layersRaw.length === 0)
+        fail(`architecture.layers 不能为空，示例：${ARCH_EXAMPLE}`);
+    const layers = layersRaw.map((layerRaw, index) => {
+        const path = `architecture.layers[${index}]`;
+        const layer = asRecord(layerRaw, path);
+        const name = requiredText(layer.name, `${path}.name`);
+        const note = optionalText(layer.note, `${path}.note`);
+        const modulesRaw = asArray(layer.modules, `${path}.modules（每层至少一个模块）`);
+        if (modulesRaw.length === 0)
+            fail(`${path}.modules 不能为空：每一层至少要有一个模块`);
+        const modules = modulesRaw.map((moduleRaw, moduleIndex) => {
+            const modulePath = `${path}.modules[${moduleIndex}]`;
+            if (typeof moduleRaw === 'string')
+                return { text: requiredText(moduleRaw, modulePath) };
+            const module = asRecord(moduleRaw, modulePath);
+            const text = requiredText(module.text, `${modulePath}.text`);
+            const moduleNote = optionalText(module.note, `${modulePath}.note`);
+            const accent = optionalBool(module.accent, `${modulePath}.accent`);
+            return { text, ...(moduleNote !== undefined ? { note: moduleNote } : {}), ...(accent === true ? { accent: true } : {}) };
+        });
+        return { name, ...(note !== undefined ? { note } : {}), modules };
+    });
+    // 模块名在全图内必须唯一：边用名字引用节点，重名就无法判断指向哪一个。
+    // 层名同理：连通向层带的默认箭头也靠名字找终点。
+    const layerNames = new Set();
+    for (const layer of layers) {
+        if (layerNames.has(layer.name))
+            fail(`architecture 里层名「${layer.name}」重复：层名用于连线引用，必须唯一。`);
+        layerNames.add(layer.name);
+    }
+    const seen = new Map();
+    for (const layer of layers) {
+        for (const module of layer.modules) {
+            const previous = seen.get(module.text);
+            if (previous !== undefined) {
+                fail(`architecture 里模块名「${module.text}」重复（分别在「${previous}」与「${layer.name}」）。边用名字引用节点，模块名必须全图唯一。`);
+            }
+            seen.set(module.text, layer.name);
+        }
+    }
+    const targets = [
+        ...layers.map(layer => ({ id: layer.name, text: layer.name })),
+        ...layers.flatMap(layer => layer.modules.map(module => ({ id: module.text, text: module.text }))),
+    ];
+    const resolve = makeResolver(targets, 'architecture.edges');
+    const edgesRaw = record.edges === undefined ? [] : asArray(record.edges, 'architecture.edges');
+    const edges = edgesRaw.map((edgeRaw, index) => {
+        const path = `architecture.edges[${index}]`;
+        const edge = asRecord(edgeRaw, path);
+        const from = resolve(requiredText(edge.from, `${path}.from`));
+        const to = resolve(requiredText(edge.to, `${path}.to`));
+        if (from === to)
+            fail(`${path} 的 from 与 to 相同（「${from}」），图里不允许自环`);
+        const label = optionalText(edge.label, `${path}.label`);
+        return { from, to, ...(label !== undefined ? { label } : {}) };
+    });
+    return { layers, edges };
+}
+const FLOW_EXAMPLE = '{"nodes":[{"id":"start","text":"提交申请","kind":"start"},{"id":"check","text":"参数合法?","kind":"decision"},{"id":"save","text":"写入数据库","kind":"process"}],"edges":[{"from":"start","to":"check"},{"from":"check","to":"save","label":"是"}]}';
+function parseFlow(raw) {
+    const record = asRecord(raw, 'flow 的 spec');
+    const nodesRaw = asArray(record.nodes, 'flow.nodes（不能为空）');
+    if (nodesRaw.length === 0)
+        fail(`flow.nodes 不能为空，示例：${FLOW_EXAMPLE}`);
+    const nodes = nodesRaw.map((nodeRaw, index) => {
+        const path = `flow.nodes[${index}]`;
+        const node = asRecord(nodeRaw, path);
+        const id = optionalText(node.id, `${path}.id`) ?? `n${index + 1}`;
+        const text = requiredText(node.text, `${path}.text`);
+        const note = optionalText(node.note, `${path}.note`);
+        const kindRaw = optionalText(node.kind, `${path}.kind`) ?? 'process';
+        if (kindRaw !== 'start' && kindRaw !== 'process' && kindRaw !== 'decision' && kindRaw !== 'end') {
+            fail(`${path}.kind 只能是 start / process / decision / end，实际是「${kindRaw}」`);
+        }
+        return { id, text, kind: kindRaw, ...(note !== undefined ? { note } : {}) };
+    });
+    if (nodes.filter(node => node.kind === 'start').length === 0) {
+        fail('flow 至少需要一个 kind="start" 的节点（流程从哪开始必须说清楚）');
+    }
+    const resolve = makeResolver(nodes.map(node => ({ id: node.id, text: node.text })), 'flow.edges');
+    const edgesRaw = asArray(record.edges, 'flow.edges（没有连线的流程无法成图）');
+    if (edgesRaw.length === 0)
+        fail('flow.edges 不能为空：至少要把起点连到下一个节点');
+    const edges = edgesRaw.map((edgeRaw, index) => {
+        const path = `flow.edges[${index}]`;
+        const edge = asRecord(edgeRaw, path);
+        const from = resolve(requiredText(edge.from, `${path}.from`));
+        const to = resolve(requiredText(edge.to, `${path}.to`));
+        if (from === to)
+            fail(`${path} 的 from 与 to 相同（「${from}」），图里不允许自环`);
+        const label = optionalText(edge.label, `${path}.label`);
+        return { from, to, ...(label !== undefined ? { label } : {}) };
+    });
+    return { nodes, edges };
+}
+const ER_EXAMPLE = '{"entities":[{"name":"用户","fields":[{"name":"id","type":"bigint","key":true},{"name":"用户名","type":"varchar(32)"}]},{"name":"任务","fields":[{"name":"id","type":"bigint","key":true},{"name":"标题","type":"varchar(64)"}]}],"relations":[{"from":"用户","to":"任务","label":"创建","cardinality":"1:N"}]}';
+function parseEr(raw) {
+    const record = asRecord(raw, 'er 的 spec');
+    const entitiesRaw = asArray(record.entities, 'er.entities（不能为空）');
+    if (entitiesRaw.length === 0)
+        fail(`er.entities 不能为空，示例：${ER_EXAMPLE}`);
+    const entities = entitiesRaw.map((entityRaw, index) => {
+        const path = `er.entities[${index}]`;
+        const entity = asRecord(entityRaw, path);
+        const name = requiredText(entity.name, `${path}.name`);
+        const fieldsRaw = asArray(entity.fields, `${path}.fields（每个实体至少一个字段）`);
+        if (fieldsRaw.length === 0)
+            fail(`${path}.fields 不能为空：实体「${name}」至少要有一个字段`);
+        const fields = fieldsRaw.map((fieldRaw, fieldIndex) => {
+            const fieldPath = `${path}.fields[${fieldIndex}]`;
+            const field = asRecord(fieldRaw, fieldPath);
+            const fieldName = requiredText(field.name, `${fieldPath}.name`);
+            const type = optionalText(field.type, `${fieldPath}.type`);
+            const key = optionalBool(field.key, `${fieldPath}.key`);
+            return { name: fieldName, ...(type !== undefined ? { type } : {}), ...(key === true ? { key: true } : {}) };
+        });
+        return { name, fields };
+    });
+    const resolve = makeResolver(entities.map(entity => ({ id: entity.name, text: entity.name })), 'er.relations');
+    const relationsRaw = record.relations === undefined ? [] : asArray(record.relations, 'er.relations');
+    const relations = relationsRaw.map((relationRaw, index) => {
+        const path = `er.relations[${index}]`;
+        const relation = asRecord(relationRaw, path);
+        const from = resolve(requiredText(relation.from, `${path}.from`));
+        const to = resolve(requiredText(relation.to, `${path}.to`));
+        if (from === to)
+            fail(`${path} 的 from 与 to 相同（「${from}」），图里不允许自环`);
+        const label = optionalText(relation.label, `${path}.label`);
+        const cardinality = optionalText(relation.cardinality, `${path}.cardinality`);
+        if (cardinality !== undefined && !/^[1NnMm]\s*[:：]\s*[1NnMm]$/.test(cardinality)) {
+            fail(`${path}.cardinality 只能写成 1:1 / 1:N / N:1 / M:N，实际是「${cardinality}」`);
+        }
+        return { from, to, ...(label !== undefined ? { label } : {}), ...(cardinality !== undefined ? { cardinality } : {}) };
+    });
+    return { entities, relations };
+}
+const SEQ_EXAMPLE = '{"participants":["浏览器","Web 服务","MySQL"],"messages":[{"from":"浏览器","to":"Web 服务","text":"POST /api/tasks"},{"from":"Web 服务","to":"MySQL","text":"INSERT"},{"from":"MySQL","to":"Web 服务","text":"ok","kind":"return"}]}';
+function parseSequence(raw) {
+    const record = asRecord(raw, 'sequence 的 spec');
+    const participantsRaw = asArray(record.participants, 'sequence.participants（不能为空）');
+    if (participantsRaw.length < 2)
+        fail(`sequence.participants 至少要有两个参与者，示例：${SEQ_EXAMPLE}`);
+    const participants = participantsRaw.map((participantRaw, index) => {
+        const path = `sequence.participants[${index}]`;
+        if (typeof participantRaw === 'string') {
+            const text = requiredText(participantRaw, path);
+            return { id: text, text };
+        }
+        const participant = asRecord(participantRaw, path);
+        const text = requiredText(participant.text, `${path}.text`);
+        const id = optionalText(participant.id, `${path}.id`) ?? text;
+        return { id, text };
+    });
+    const resolve = makeResolver(participants, 'sequence.messages');
+    const messagesRaw = asArray(record.messages, 'sequence.messages（不能为空）');
+    if (messagesRaw.length === 0)
+        fail(`sequence.messages 不能为空，示例：${SEQ_EXAMPLE}`);
+    const messages = messagesRaw.map((messageRaw, index) => {
+        const path = `sequence.messages[${index}]`;
+        const message = asRecord(messageRaw, path);
+        const from = resolve(requiredText(message.from, `${path}.from`));
+        const to = resolve(requiredText(message.to, `${path}.to`));
+        const text = requiredText(message.text, `${path}.text`);
+        const kindRaw = optionalText(message.kind, `${path}.kind`) ?? 'call';
+        if (kindRaw !== 'call' && kindRaw !== 'return')
+            fail(`${path}.kind 只能是 call / return，实际是「${kindRaw}」`);
+        return { from, to, text, kind: kindRaw };
+    });
+    return { participants, messages };
+}
+function parseCustom(raw) {
+    const record = asRecord(raw, 'custom 的 spec');
+    const xml = requiredText(record.xml, 'custom.xml（draw.io 文件全文）');
+    return { xml };
+}
+/** 解析并校验规格；成功时返回规范化模型，失败时抛 {@link FigureSpecError}。 */
+export function parseFigureModel(kind, raw) {
+    if (raw === undefined || raw === null) {
+        fail(`缺少 spec：${kind} 图需要结构化规格，另可用 thesis_figure action=create 的示例参数。`);
+    }
+    switch (kind) {
+        case 'architecture': return { kind, model: parseArchitecture(raw) };
+        case 'flow': return { kind, model: parseFlow(raw) };
+        case 'er': return { kind, model: parseEr(raw) };
+        case 'sequence': return { kind, model: parseSequence(raw) };
+        case 'custom': return { kind, model: parseCustom(raw) };
+        default:
+            fail(`未知图种类「${kind}」，可选：${FIGURE_KINDS.join(' / ')}`);
+    }
+}
+/** 一句话概括模型规模（工具返回值里给模型看，确认自己传对了）。 */
+export function describeModel(model) {
+    switch (model.kind) {
+        case 'architecture':
+            return `${model.model.layers.length} 层 / ${model.model.layers.reduce((sum, layer) => sum + layer.modules.length, 0)} 个模块 / ${model.model.edges.length} 条连线`;
+        case 'flow': return `${model.model.nodes.length} 个节点 / ${model.model.edges.length} 条连线`;
+        case 'er': return `${model.model.entities.length} 个实体 / ${model.model.relations.length} 条关系`;
+        case 'sequence': return `${model.model.participants.length} 个参与者 / ${model.model.messages.length} 条消息`;
+        case 'custom': return `手写 mxfile（${model.model.xml.length} 字符）`;
+    }
+}

package/lib/index.d.ts

@@ -12,6 +12,7 @@
  * | `intake/` | 材料到手后的逐题追问 → 意图规格（唯一真相） |
  * | `dedup/` | 原创性自查：本地相似度度量 + 改写处方 + 复测 |
  * | `ppt/` | 答辩幻灯：Marp Markdown + 外部转换器探测 |
+ * | `figure/` | 论文插图：draw.io 源文件 + 导出 PNG + 图表体检 |
  * | `memory/` | 跨会话事实：学校规范、导师要求、写作偏好（学生不必直接调用） |
  * | `codewalk/` | 代码演练：把 AI 写的系统拆成答辩讲得清的模块 |
  * | `gates/` | 闸门：写作意图闸门 + 不可逆操作闸门 + 意图规格闸门 |

package/lib/index.js

@@ -12,6 +12,7 @@
  * | `intake/` | 材料到手后的逐题追问 → 意图规格（唯一真相） |
  * | `dedup/` | 原创性自查：本地相似度度量 + 改写处方 + 复测 |
  * | `ppt/` | 答辩幻灯：Marp Markdown + 外部转换器探测 |
+ * | `figure/` | 论文插图：draw.io 源文件 + 导出 PNG + 图表体检 |
  * | `memory/` | 跨会话事实：学校规范、导师要求、写作偏好（学生不必直接调用） |
  * | `codewalk/` | 代码演练：把 AI 写的系统拆成答辩讲得清的模块 |
  * | `gates/` | 闸门：写作意图闸门 + 不可逆操作闸门 + 意图规格闸门 |
@@ -30,6 +31,7 @@ import { Config, resolveConfig } from "./config.js";
 import { registerDedup } from "./dedup/index.js";
 import { installDangerousGate } from "./gates/dangerous.js";
 import { installWritingGate } from "./gates/prompt.js";
+import { registerFigure } from "./figure/index.js";
 import { registerIngest } from "./ingest/index.js";
 import { installIntakeGate } from "./intake/gate.js";
 import { registerIntake } from "./intake/index.js";
@@ -57,7 +59,7 @@ export function apply(ctx, config = {}) {
     registerFacts(ctx, resolved.memoryPath);
     // 事实回灌：相关时自动把已确认的稳定事实放回上下文（不相关则完全静默）。
     installFactRecall(ctx, resolved.recall);
-    // 论文工作区：11 个工具。
+    // 论文工作区：13 个工具。
     registerPaper(ctx, { skillsDir: SKILLS_DIR });
     // 代码演练（答辩层）：3 个工具 + 进度卡注入 + code-walkthrough 技能。
     registerCodewalk(ctx, resolved.codeWalkthrough);
@@ -69,6 +71,8 @@ export function apply(ctx, config = {}) {
     registerDedup(ctx, { similarity: resolved.similarity });
     // 答辩：Markdown 幻灯 + 外部转换器探测。
     registerPpt(ctx, { ppt: resolved.ppt });
+    // 论文插图：draw.io 源文件（唯一真源）+ 导出 PNG + 图表体检。
+    registerFigure(ctx, resolved.figure);
     // 自动驾驶：论文工作区里开口就问一次意图 → 建目标自动续轮；关卡由人拍板。
     // 不提供任何斜杠命令：人只在「开头选一次」与「过关卡」两处出现。
     installAutopilot(ctx, { ...resolved.autopilot, specRel: resolved.intake.specRel });

package/lib/paper/lib/check.d.ts

@@ -27,6 +27,11 @@ export interface CheckReport {
     readonly sections: readonly CheckSection[];
     readonly allOk: boolean;
 }
+/** 统计一章里的 Markdown 表格块数与「表 x-y」表题数（用于查"有表无题"）。 */
+export declare function countTablesAndCaptions(text: string, chapterNo: number): {
+    tables: number;
+    captions: number;
+};
 export declare function runGlobalCheck(input: CheckInput): CheckReport;
 export declare function renderCheckReport(report: CheckReport): string;
 export { CHAPTER_META };

package/lib/paper/lib/check.js

@@ -104,6 +104,21 @@ function checkWordCountsGlobal(input) {
 // ---------------------------------------------------------------------------
 // 3. 图/表编号（全文逐章）
 // ---------------------------------------------------------------------------
+/** 统计一章里的 Markdown 表格块数与「表 x-y」表题数（用于查"有表无题"）。 */
+export function countTablesAndCaptions(text, chapterNo) {
+    const lines = text.split(/\r?\n/);
+    let tables = 0;
+    let inTable = false;
+    for (const line of lines) {
+        const isRow = line.trim().startsWith('|');
+        if (isRow && !inTable)
+            tables += 1;
+        inTable = isRow;
+    }
+    const pattern = new RegExp(`^表\\s*${chapterNo}\\s*[-–—]\\s*\\d+`, 'gm');
+    const captions = (text.match(pattern) ?? []).length;
+    return { tables, captions };
+}
 function checkFiguresGlobal(input) {
     const lines = [];
     let problems = 0;
@@ -115,6 +130,12 @@ function checkFiguresGlobal(input) {
                 lines.push(`✗ ${chapter.name} ${finding.detail}`);
             }
         }
+        // 表题缺失：有表格却没有「表 x-y 名称」的行。学位论文要求每张表都有表序与表名。
+        const { tables, captions } = countTablesAndCaptions(chapter.text, chapter.no);
+        if (tables > captions) {
+            problems += 1;
+            lines.push(`✗ ${chapter.name}：${tables} 张表但只有 ${captions} 个表题；每张表上方都要有「表 ${chapter.no}-x 名称」`);
+        }
     }
     if (problems === 0)
         lines.push('✓ 各章图/表编号章号正确、序号连续（无图表的章不计）。');

package/lib/paper/lib/docx.d.ts

@@ -22,14 +22,40 @@ type Block = {
 } | {
     readonly kind: 'table';
     readonly rows: readonly (readonly string[])[];
+} | {
+    readonly kind: 'image';
+    readonly alt: string;
+    readonly src: string;
 };
 export declare function parseMarkdownBlocks(markdown: string): Block[];
+/** 表题行（`表 4-1 模块划分`）：走 Caption 样式居中，与图题同一套口径。 */
+export declare function isTableCaption(text: string): boolean;
+/**
+ * 三线表：表格只靠三条横线成形，不画竖线、不做隔行底纹。
+ * 表头跨页重复（tblHeader），表内五号字，表头加粗居中，数字列居中。
+ */
+export declare function renderTableXml(rows: readonly (readonly string[])[]): string;
+/** 要嵌进 docx 的图片（由 thesis_build 从章节里的 `![](路径)` 收集）。 */
+export interface DocxImage {
+    readonly data: Uint8Array;
+    /** 像素宽（文件头解析得到）。 */
+    readonly width: number;
+    /** 像素高。 */
+    readonly height: number;
+    readonly format: 'png' | 'jpeg';
+}
 export interface DocxOptions {
     readonly title: string;
     readonly markdown: string;
+    /** 图片绝对路径 → 图片字节与像素尺寸；缺省的图片降级为一行占位文字。 */
+    readonly images?: ReadonlyMap<string, DocxImage>;
 }
 /**
  * 生成完整 .docx 字节。title 渲染为封面页；markdown 为正文（章节合并内容）。
+ *
+ * 图片按 `images` 里的字节嵌入：`![图 4-1 系统总体架构图](绝对路径)` 会变成
+ * 「居中的图 + 图下方的图题」。找不到字节的图片降级成一行可读的占位文字——
+ * 缺图必须在 Word 里一眼看见，不能静默消失。
  */
 export declare function buildDocx(opts: DocxOptions): Uint8Array;
 export {};