dsh-thesis 1.0.0

package/lib/ppt/marp.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Marp Markdown 渲染（`thesis_slides action=outline` 的产出格式）。
+ *
+ * 输出目标：**标准 Marp 幻灯片 Markdown**，保证 `marp PPT.md --pptx` /
+ * `npx @marp-team/marp-cli PPT.md --pptx` / `pandoc PPT.md -o PPT.pptx`
+ * 可以直接消费。因此：
+ * - frontmatter 只写 `marp/theme/paginate/size/header/footer` 六个键，值全部
+ *   经过清洗（去引号、去换行、去 `---`），不可能破坏 YAML 头；
+ * - 页间分隔符是独占一行的 `---`；正文里任何以 `---` 开头的行都会被转义；
+ * - 讲稿写成 HTML 注释 `<!-- ... -->`（Marp 的演示者备注兼容形态）。
+ *
+ * @module dsh-thesis/ppt
+ */
+import { type PlanBullet, type PlannedSlide, type SlidePlan } from './outline.ts';
+/** 推荐主题名（Marp 内置主题 + 常见自定义主题）。 */
+export declare const MARP_THEMES: readonly string[];
+/** {@link renderMarp} 选项。 */
+export interface MarpOptions {
+    /** frontmatter 的 `theme:`；缺省 `default`。 */
+    readonly theme?: string;
+    /** 页脚文字；缺省 `dsh-thesis`。 */
+    readonly footer?: string;
+    /** 页眉文字；缺省用课题标题。 */
+    readonly header?: string;
+    /** 是否写 `paginate: true`，缺省 true。 */
+    readonly paginate?: boolean;
+}
+/**
+ * 清洗任意文本，使其可安全放进 Markdown 正文/HTML 注释：
+ * 去掉换行与 HTML 注释定界符，行首 `---`/`#` 会被打散，避免误触发分页或标题。
+ */
+export declare function sanitizeInline(text: string): string;
+/** 清洗 YAML 标量：单行、去引号、去 `---`，保证 frontmatter 不被破坏。 */
+export declare function sanitizeYamlScalar(text: string): string;
+/** 主题名只允许 `[A-Za-z0-9._-]`，其余替换为 `-`。 */
+export declare function sanitizeTheme(theme: string | undefined): string;
+/** 一条要点渲染为一行 Markdown 列表项（超长截断的要点带 `␣` 标记说明）。 */
+export declare function renderBullet(bullet: PlanBullet): string;
+/** 一页渲染为：标题 + 要点 + 讲稿注释。 */
+export declare function renderSlide(slide: PlannedSlide): string;
+/**
+ * 渲染整份 Marp Markdown。
+ *
+ * 返回文本以 frontmatter 开头、以换行结尾；页间以 `---` 分隔，
+ * 因此 `---` 独占行的出现次数 = 页数 - 1（frontmatter 的两条定界行不计入）。
+ */
+export declare function renderMarp(plan: SlidePlan, options?: MarpOptions): string;
+/** 从 Marp Markdown 里解析出的单页（用于质量检查）。 */
+export interface ParsedSlide {
+    readonly index: number;
+    readonly title: string;
+    readonly bullets: readonly {
+        readonly text: string;
+        readonly anchor?: string;
+        readonly truncated: boolean;
+    }[];
+    readonly note?: string;
+}
+/** Marp Markdown 的解析结果。 */
+export interface ParsedDeck {
+    readonly title: string;
+    readonly theme: string;
+    readonly paginate: boolean;
+    readonly slides: readonly ParsedSlide[];
+}
+/** 提取 frontmatter 键值（只支持 `key: value` 单行标量）。 */
+export declare function parseFrontmatter(markdown: string): {
+    readonly fields: Record<string, string>;
+    readonly body: string;
+};
+/** 解析 Marp Markdown（含 frontmatter）为可检查的结构。 */
+export declare function parseMarp(markdown: string): ParsedDeck;
+/** 检查 Marp Markdown 里是否会破坏 frontmatter/分页的字符。 */
+export declare function findUnsafeMarkdown(markdown: string): string[];

package/lib/ppt/marp.js

@@ -0,0 +1,165 @@
+/**
+ * Marp Markdown 渲染（`thesis_slides action=outline` 的产出格式）。
+ *
+ * 输出目标：**标准 Marp 幻灯片 Markdown**，保证 `marp PPT.md --pptx` /
+ * `npx @marp-team/marp-cli PPT.md --pptx` / `pandoc PPT.md -o PPT.pptx`
+ * 可以直接消费。因此：
+ * - frontmatter 只写 `marp/theme/paginate/size/header/footer` 六个键，值全部
+ *   经过清洗（去引号、去换行、去 `---`），不可能破坏 YAML 头；
+ * - 页间分隔符是独占一行的 `---`；正文里任何以 `---` 开头的行都会被转义；
+ * - 讲稿写成 HTML 注释 `<!-- ... -->`（Marp 的演示者备注兼容形态）。
+ *
+ * @module dsh-thesis/ppt
+ */
+import { MAX_BULLETS_PER_SLIDE } from "./outline.js";
+/** 推荐主题名（Marp 内置主题 + 常见自定义主题）。 */
+export const MARP_THEMES = ['default', 'gaia', 'uncover', 'academic', 'dsh-thesis'];
+/**
+ * 清洗任意文本，使其可安全放进 Markdown 正文/HTML 注释：
+ * 去掉换行与 HTML 注释定界符，行首 `---`/`#` 会被打散，避免误触发分页或标题。
+ */
+export function sanitizeInline(text) {
+    const flat = text.replace(/[\r\n]+/g, ' ').replace(/<!--|-->/g, ' ').replace(/\s+/g, ' ').trim();
+    return flat.replace(/^---+/, '- —').replace(/^#{1,6}\s*/, '');
+}
+/** 清洗 YAML 标量：单行、去引号、去 `---`，保证 frontmatter 不被破坏。 */
+export function sanitizeYamlScalar(text) {
+    const flat = sanitizeInline(text).replace(/["'`]/g, '').replace(/:/g, '：');
+    return flat === '' ? 'untitled' : flat;
+}
+/** 主题名只允许 `[A-Za-z0-9._-]`，其余替换为 `-`。 */
+export function sanitizeTheme(theme) {
+    const raw = (theme ?? 'default').trim();
+    const safe = raw.replace(/[^A-Za-z0-9._-]/g, '-');
+    return safe === '' ? 'default' : safe;
+}
+function frontmatter(plan, options) {
+    return [
+        '---',
+        'marp: true',
+        `theme: ${sanitizeTheme(options.theme)}`,
+        `paginate: ${options.paginate === false ? 'false' : 'true'}`,
+        'size: 16:9',
+        `header: ${sanitizeYamlScalar(options.header ?? plan.title)}`,
+        `footer: ${sanitizeYamlScalar(options.footer ?? 'dsh-thesis')}`,
+        '---',
+    ];
+}
+/** 一条要点渲染为一行 Markdown 列表项（超长截断的要点带 `␣` 标记说明）。 */
+export function renderBullet(bullet) {
+    const text = sanitizeInline(bullet.text);
+    const anchor = bullet.anchor !== undefined ? sanitizeInline(bullet.anchor) : '';
+    const suffix = anchor !== '' ? ` <!-- 锚点: ${anchor} -->` : '';
+    const mark = bullet.truncated ? '（已截断）' : '';
+    return `- ${text}${mark}${suffix}`;
+}
+/** 一页渲染为：标题 + 要点 + 讲稿注释。 */
+export function renderSlide(slide) {
+    const lines = [];
+    lines.push(`## ${sanitizeInline(slide.title)}`);
+    lines.push('');
+    for (const bullet of slide.bullets.slice(0, MAX_BULLETS_PER_SLIDE))
+        lines.push(renderBullet(bullet));
+    lines.push('');
+    lines.push(`<!-- 讲稿：${sanitizeInline(slide.note)} -->`);
+    return lines.join('\n');
+}
+/**
+ * 渲染整份 Marp Markdown。
+ *
+ * 返回文本以 frontmatter 开头、以换行结尾；页间以 `---` 分隔，
+ * 因此 `---` 独占行的出现次数 = 页数 - 1（frontmatter 的两条定界行不计入）。
+ */
+export function renderMarp(plan, options = {}) {
+    const blocks = [];
+    blocks.push(...frontmatter(plan, options));
+    blocks.push('');
+    const body = plan.slides.map(renderSlide).join('\n\n---\n\n');
+    blocks.push(body);
+    blocks.push('');
+    return blocks.join('\n');
+}
+/** 提取 frontmatter 键值（只支持 `key: value` 单行标量）。 */
+export function parseFrontmatter(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return { fields: {}, body: markdown };
+    let end = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i]?.trim() === '---') {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return { fields: {}, body: markdown };
+    const fields = {};
+    for (const raw of lines.slice(1, end)) {
+        const matched = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(raw.trim());
+        if (matched?.[1] !== undefined)
+            fields[matched[1]] = (matched[2] ?? '').trim();
+    }
+    return { fields, body: lines.slice(end + 1).join('\n') };
+}
+/** 解析 Marp Markdown（含 frontmatter）为可检查的结构。 */
+export function parseMarp(markdown) {
+    const { fields, body } = parseFrontmatter(markdown);
+    const blocks = [[]];
+    for (const line of body.split(/\r?\n/)) {
+        if (line.trim() === '---') {
+            blocks.push([]);
+            continue;
+        }
+        blocks[blocks.length - 1].push(line);
+    }
+    const slides = [];
+    for (const block of blocks) {
+        const title = block.map(l => /^##\s+(.+)$/.exec(l.trim())?.[1]).find(v => v !== undefined);
+        if (title === undefined)
+            continue;
+        const bullets = [];
+        let note;
+        for (const line of block) {
+            const trimmed = line.trim();
+            const noteMatched = /^<!--\s*讲稿[:：]\s*(.*?)\s*-->$/.exec(trimmed);
+            if (noteMatched?.[1] !== undefined) {
+                note = noteMatched[1];
+                continue;
+            }
+            if (!trimmed.startsWith('- '))
+                continue;
+            const anchorMatched = /<!--\s*锚点[:：]\s*(.*?)\s*-->/.exec(trimmed);
+            const withoutAnchor = trimmed.replace(/<!--.*?-->/g, '').trim();
+            const truncated = /（已截断）$/.test(withoutAnchor);
+            const text = withoutAnchor.replace(/^-\s+/, '').replace(/（已截断）$/, '').trim();
+            bullets.push({ text, ...(anchorMatched?.[1] !== undefined ? { anchor: anchorMatched[1] } : {}), truncated });
+        }
+        slides.push({
+            index: slides.length + 1,
+            title,
+            bullets,
+            ...(note !== undefined ? { note } : {}),
+        });
+    }
+    return {
+        title: fields.title ?? '',
+        theme: fields.theme ?? '',
+        paginate: (fields.paginate ?? 'true') !== 'false',
+        slides,
+    };
+}
+/** 检查 Marp Markdown 里是否会破坏 frontmatter/分页的字符。 */
+export function findUnsafeMarkdown(markdown) {
+    const problems = [];
+    const { body } = parseFrontmatter(markdown);
+    const lines = body.split(/\r?\n/);
+    for (const [i, line] of lines.entries()) {
+        if (/^\s*---/.test(line) && line.trim() !== '---')
+            problems.push(`第 ${i + 1} 行：以 --- 开头的正文行会被误判为分页`);
+        if (line.includes('<!-- 讲稿') && !/^<!--\s*讲稿[:：].*-->$/.test(line.trim()))
+            problems.push(`第 ${i + 1} 行：讲稿注释形态不合法`);
+    }
+    if (!/^---\r?\nmarp:\s*true\s*$/m.test(markdown))
+        problems.push('frontmatter 首行必须是 marp: true');
+    return problems;
+}

package/lib/ppt/outline.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 答辩幻灯计划（`thesis_slides action=outline` 的核心）。
+ *
+ * 产品决策：**不自研 pptx 生成器**。本模块把真实素材变成结构化的《幻灯片计划》
+ * （SlidePlan），由 `marp.ts` 渲染为标准 Marp Markdown，再交给外部转换器
+ * （marp-cli / pandoc）成稿。计划里的每一条要点都带**证据锚点**，指向工作区里
+ * 真实存在的文件/章节/数据——这是"零编造"红线在答辩环节的落地。
+ *
+ * 两条输入路径：
+ * 1. `07-答辩/答辩素材.md`（由 `thesis_defense` 生成）——优先；
+ * 2. 素材不存在时回退到 `06-论文/章节/*.md` 的标题与要点，并在结果里标注
+ *    "素材未生成，建议先跑 thesis_defense"，**不编造系统细节**。
+ *
+ * @module dsh-thesis/ppt
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+/** 幻灯页的语义类型（渲染与检查共用）。 */
+export type SlideKind = 'cover' | 'toc' | 'background' | 'status' | 'content' | 'route' | 'design' | 'impl' | 'test' | 'conclusion' | 'innovation' | 'thanks';
+/** 听众档位：本科（默认）/ 硕士。影响详略与时长估算。 */
+export type Audience = 'undergrad' | 'master';
+/** 单条要点的硬上限（字符）：超出自动截断并标记。 */
+export declare const MAX_BULLET_CHARS = 30;
+/** 单页标题的硬上限（字符）。 */
+export declare const MAX_TITLE_CHARS = 20;
+/** 单页要点条数区间。 */
+export declare const MIN_BULLETS_PER_SLIDE = 3;
+export declare const MAX_BULLETS_PER_SLIDE = 6;
+/** 每页预计讲述秒数区间（本科）。 */
+export declare const SECONDS_PER_SLIDE_MIN = 40;
+export declare const SECONDS_PER_SLIDE_MAX = 60;
+/** 系统实现页的证据锚点根目录（真实代码位置）。 */
+export declare const CODE_ROOT = "04-\u5B9E\u73B0";
+/** 实验结果的证据锚点根目录。 */
+export declare const RESULT_ROOT = "05-\u5B9E\u9A8C\u6D4B\u8BD5/\u7ED3\u679C";
+/** 要点模板：正文 + 证据锚点。 */
+export interface BulletSpec {
+    readonly text: string;
+    readonly anchor?: string;
+}
+/** 页面模板（解析素材后的呈现结构）。 */
+export interface SlideSpec {
+    readonly kind: SlideKind;
+    readonly title: string;
+    readonly bullets: readonly BulletSpec[];
+    /** 讲稿要点（渲染为 HTML 注释，Marp 演示者备注兼容）。 */
+    readonly note: string;
+}
+/** 解析后的单条要点。 */
+export interface PlanBullet {
+    readonly text: string;
+    /** 超长被自动截断（原文另见 `original`）。 */
+    readonly truncated: boolean;
+    /** 被截断前的原文（仅在 truncated=true 时出现）。 */
+    readonly original?: string;
+    /** 证据锚点：相对工作区根的文件/章节/数据位置。 */
+    readonly anchor?: string;
+}
+/** 计划中的一页。 */
+export interface PlannedSlide {
+    readonly index: number;
+    readonly kind: SlideKind;
+    readonly title: string;
+    readonly bullets: readonly PlanBullet[];
+    readonly note: string;
+}
+/** 素材来源模式。 */
+export type MaterialSource = 'defense-materials' | 'chapters';
+/** 章节解析结果。 */
+export interface ChapterDigest {
+    readonly file: string;
+    readonly title: string;
+    readonly headings: readonly string[];
+}
+/** 技术选型条目。 */
+export interface TechChoiceEntry {
+    readonly item: string;
+    readonly choice: string;
+    readonly reason: string;
+    readonly alternative: string;
+}
+/** 从答辩素材里解析出的结构化事实。 */
+export interface DefenseMaterials {
+    readonly title: string;
+    readonly chapters: readonly ChapterDigest[];
+    readonly techChoices: readonly TechChoiceEntry[];
+    readonly decisions: readonly string[];
+    readonly testCases: number;
+    readonly resultFiles: readonly string[];
+    readonly gitCommits?: number;
+    readonly bibCount?: number;
+}
+/** 时长估算。 */
+export interface PlanEstimate {
+    /** 页数下限（每页秒数上限换算成分钟）。 */
+    readonly minMinutes: number;
+    /** 页数上限（每页秒数下限换算成分钟）。 */
+    readonly maxMinutes: number;
+    readonly secondsPerSlideMin: number;
+    readonly secondsPerSlideMax: number;
+    readonly advice: string;
+}
+/** 幻灯片计划（纯函数产物，可直接序列化）。 */
+export interface SlidePlan {
+    readonly title: string;
+    readonly audience: Audience;
+    readonly pages: number;
+    readonly slides: readonly PlannedSlide[];
+    readonly estimate: PlanEstimate;
+    /** 入参页码被夹到骨架允许的区间时给出说明。 */
+    readonly pageAdjustment?: string;
+    /** 素材来源模式。 */
+    readonly source: MaterialSource;
+    /** 素材缺失标注（无则为 undefined）。 */
+    readonly note?: string;
+    /** 其它需要用户注意的事项。 */
+    readonly warnings: readonly string[];
+}
+/** 去掉 Markdown 修饰（粗体、行内代码、列表符号），得到纯文本。 */
+export declare function stripMarkdownInline(text: string): string;
+/** 中文字符数（用于判断素材章节是否"已撰写"）。 */
+export declare function cjkCount(text: string): number;
+/**
+ * 截断单条要点：`limit` 字以内原样返回；超出则截到 `limit - 1` 并补省略号，
+ * 保证总长不超过 limit，并把 `truncated` 标记为 true（原文保留在 `original`）。
+ */
+export declare function truncateBullet(text: string, limit?: number): {
+    text: string;
+    truncated: boolean;
+    original?: string;
+};
+/** 标题超长同样截断（20 字硬上限）。 */
+export declare function truncateTitle(title: string, limit?: number): string;
+/**
+ * 解析 `07-答辩/答辩素材.md`（thesis_defense 的产物）。
+ *
+ * 容错原则：任何一段缺失都只是"该段没有事实"，绝不用默认值伪造内容。
+ */
+export declare function parseDefenseMaterials(markdown: string): DefenseMaterials;
+/**
+ * 回退解析：从 `06-论文/章节/*.md` 提取章节标题与该章二三级小节标题。
+ *
+ * 这是"素材未生成"时的降级路径——只搬运论文章节里**已经写好**的标题，
+ * 不推断、不补全任何系统细节。
+ */
+export declare function parseChapterFallback(files: readonly {
+    readonly name: string;
+    readonly text: string;
+}[]): ChapterDigest[];
+/** 展开顺序的候选段落（含页面模板与素材填充规则）。 */
+type SegmentId = 'background' | 'status' | 'route' | 'design' | 'impl' | 'test' | 'conclusion';
+/** 段落页数分配结果。 */
+export interface Composition {
+    readonly ids: readonly SegmentId[];
+    readonly parts: Readonly<Record<SegmentId, number>>;
+}
+/**
+ * 按目标页数分配各段落页数：固定头（封面、目录）与固定尾（创新点、致谢）各 1 页，
+ * 中间的 7 个段落至少各 1 页，多出来的页数按可展开顺序补 2 页以上的段落。
+ */
+export declare function composeSlides(targetPages: number): Composition;
+/** 听众档位对应的时长与页数参数。 */
+export declare function audienceProfile(audience: Audience): {
+    readonly label: string;
+    readonly secondsMin: number;
+    readonly secondsMax: number;
+    readonly pages: readonly [number, number];
+    readonly defaultPages: number;
+    readonly advice: string;
+};
+/** {@link buildSlidePlan} 的输入。 */
+export interface BuildSlidePlanInput {
+    /** 课题标题（通常来自进度台账）。 */
+    readonly title: string;
+    readonly audience: Audience;
+    /** 目标页数（会被夹到骨架允许的区间，并在结果里报告）。 */
+    readonly targetPages: number;
+    /** `07-答辩/答辩素材.md` 原文；缺失时传 undefined。 */
+    readonly defenseMaterials?: string;
+    /** 素材缺失时的回退章节（真实文件内容）。 */
+    readonly chapterFiles?: readonly {
+        readonly name: string;
+        readonly text: string;
+    }[];
+}
+/**
+ * 生成幻灯片计划（纯函数；不读磁盘、不编造素材）。
+ *
+ * 步骤：解析素材 → 取骨架 → 按目标页数补齐段落 → 填素材 → 截断要点 → 估时。
+ */
+export declare function buildSlidePlan(input: BuildSlidePlanInput): SlidePlan;
+/** 读盘结果：台账标题、素材原文、回退章节。 */
+export interface OutlineInputs {
+    readonly ledgerTitle: string;
+    readonly defenseMaterials?: string;
+    readonly chapterFiles: readonly {
+        readonly name: string;
+        readonly text: string;
+    }[];
+}
+/** 从进度台账提取课题标题（与 thesis_build/thesis_defense 的口径一致）。 */
+export declare function titleFromLedger(ledger: string | undefined): string;
+/** 装载生成幻灯计划所需的全部输入（素材 → 回退章节 → 台账标题）。 */
+export declare function loadOutlineInputs(fs: FileSystem, root: string, signal?: AbortSignal): Promise<OutlineInputs>;
+/** 计划的人类可读摘要（工具返回值用，有界）。 */
+export declare function summarizePlan(plan: SlidePlan): string[];
+export {};