dsh-thesis 1.0.0

package/lib/ppt/actions.js

@@ -0,0 +1,263 @@
+/**
+ * `thesis_slides` 的四个动作实现（outline / convert / check / guide）。
+ *
+ * 与 `src/paper/tools/*.ts` 同一分层思路：**业务逻辑在这里，靠 `defineTool` 的
+ * 胶水在 `index.ts`**。本文件只依赖 Node 内置与 `FileSystem` 的**类型**（宿主在
+ * 运行期提供真实实现），因此在没有安装宿主包的离线环境里也能被单元测试直接导入。
+ *
+ * 落盘约定（全部相对论文仓库根）：
+ * - `07-答辩/PPT.md`（outline；默认不覆盖，force 时先备份为 `PPT-<时间戳>.md`）
+ * - `07-答辩/PPT.pptx`（convert 成功时，由外部转换器写出）
+ * - `07-答辩/PPT转换说明.md`（convert 无论成败都写：探测结果 + 命令 + 退出码 + 输出摘要）
+ *
+ * @module dsh-thesis/ppt
+ */
+import * as nodePath from 'node:path';
+import { existsSync } from 'node:fs';
+import { findThesisRoot } from "../paper/lib/project.js";
+import { buildSlidePlan, loadOutlineInputs, audienceProfile } from "./outline.js";
+import { renderMarp } from "./marp.js";
+import { checkDeck, renderCheckReport, verifyAnchors } from "./check.js";
+import { conversionGuide, convert, detectEngines, renderConversionNotes } from "./convert.js";
+/** PPT 工具在论文工作区里的所有落盘位置。 */
+export const PPT_RELS = {
+    /** 幻灯 Markdown（唯一真源）。 */
+    slides: '07-答辩/PPT.md',
+    /** 外部转换器产出的 pptx。 */
+    pptx: '07-答辩/PPT.pptx',
+    /** 转换说明（探测结果 + 确切命令，任何情况都写）。 */
+    notes: '07-答辩/PPT转换说明.md',
+    /** 素材（输入，由 thesis_defense 生成）。 */
+    materials: '07-答辩/答辩素材.md',
+};
+/** 目标页数的合法区间（放置非法入参）。 */
+const PAGES_MIN = 8;
+const PAGES_MAX = 20;
+function clampPages(pages) {
+    const value = pages === undefined || !Number.isFinite(pages) ? 11 : Math.round(pages);
+    return Math.min(PAGES_MAX, Math.max(PAGES_MIN, value));
+}
+function normalizeAudience(audience) {
+    return audience === 'master' ? 'master' : 'undergrad';
+}
+/** 时间戳（本地时间，文件名安全：20260912-184800）。 */
+export function timestamp(now) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+async function readOptional(fs, absPath, signal) {
+    try {
+        return await fs.readText(await fs.resolve(absPath, { signal }), signal);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeText(fs, absPath, content, signal) {
+    await fs.writeText(await fs.resolve(absPath, { signal }), content, undefined, signal);
+}
+/** 把绝对路径转成工作区内的 POSIX 相对路径（写进说明文档，跨平台可读）。 */
+function relativeForDisplay(root, absPath) {
+    return nodePath.relative(root, absPath).split(nodePath.sep).join('/') || absPath;
+}
+/** 由已装载的素材构建幻灯计划（工具与测试共用）。 */
+export function planFromInputs(inputs, audience, pages) {
+    const { ledgerTitle, ...rest } = inputs;
+    return buildSlidePlan({ title: ledgerTitle, audience, targetPages: pages, ...rest });
+}
+async function resolveDeck(fs, root, signal) {
+    const markdown = await readOptional(fs, nodePath.join(root, PPT_RELS.slides), signal);
+    if (markdown === undefined) {
+        throw new Error(`${PPT_RELS.slides} 尚未生成。请先运行 thesis_slides action=outline。`);
+    }
+    return markdown;
+}
+/** 定位论文仓库根；找不到即抛错（所有动作都要求在工作区内）。 */
+export async function requireRoot(fs, cwd, signal) {
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null)
+        throw new Error('未找到论文工作区。请先在论文仓库目录内操作（需要 00-管理/进度台账.md）。');
+    return root;
+}
+// ---------------------------------------------------------------------------
+// outline
+// ---------------------------------------------------------------------------
+/** outline 的文本摘要（有界）。 */
+export function outlineSummary(plan, slidesRel, notesRel, backupRel) {
+    const lines = [
+        `幻灯 Markdown 已生成：${slidesRel}`,
+        `- 实际页数：${plan.pages} 页（听众：${audienceProfile(plan.audience).label}）`,
+        `- 预计时长：${plan.estimate.minMinutes}-${plan.estimate.maxMinutes} 分钟（每页 ${plan.estimate.secondsPerSlideMin}-${plan.estimate.secondsPerSlideMax} 秒）`,
+        `- 素材来源：${plan.source === 'defense-materials' ? PPT_RELS.materials : '06-论文/章节/*.md（回退）'}`,
+    ];
+    if (plan.note !== undefined)
+        lines.push(`- 提示：${plan.note}`);
+    if (plan.pageAdjustment !== undefined)
+        lines.push(`- 页数调整：${plan.pageAdjustment}`);
+    for (const warning of plan.warnings)
+        lines.push(`- 注意：${warning}`);
+    if (backupRel !== undefined)
+        lines.push(`- 旧文件已备份为：${backupRel}`);
+    lines.push(`- 转换说明：${notesRel}`);
+    lines.push('');
+    lines.push('下一步：');
+    lines.push('- 复核页数/要点/讲稿后运行 thesis_slides action=convert 生成 PPT.pptx');
+    lines.push('- 或运行 thesis_slides action=guide 获取可复制执行的转换命令（本机未装 marp/pandoc 时用）');
+    return lines.join('\n');
+}
+/** `action=outline`：生成/刷新 `07-答辩/PPT.md`。 */
+export async function runOutline(fs, root, args, options, signal, deps = {}) {
+    const now = deps.now ?? (() => new Date());
+    const audience = normalizeAudience(args.audience);
+    const targetPages = clampPages(args.pages);
+    const slidesAbs = nodePath.join(root, PPT_RELS.slides);
+    const inputs = await loadOutlineInputs(fs, root, signal);
+    const plan = planFromInputs(inputs, audience, targetPages);
+    const markdown = renderMarp(plan, { theme: options.ppt.theme, footer: 'dsh-thesis · 答辩幻灯', header: plan.title });
+    const existing = await readOptional(fs, slidesAbs, signal);
+    if (existing !== undefined && existing.trim() !== '' && args.force !== true) {
+        return {
+            plan,
+            text: [
+                `${PPT_RELS.slides} 已存在，未覆盖（保护你手工改过的内容）。`,
+                `- 现有文件：${PPT_RELS.slides}`,
+                `- 本次将生成 ${plan.pages} 页（若确认覆盖，请带 force=true；旧文件会先备份为 07-答辩/PPT-<时间戳>.md）`,
+                '',
+                '建议：先 thesis_slides action=check 看现有文件的问题清单，或复制一份再重新生成。',
+            ].join('\n'),
+        };
+    }
+    let backupRel;
+    if (existing !== undefined && existing.trim() !== '') {
+        backupRel = `07-答辩/PPT-${timestamp(now())}.md`;
+        await writeText(fs, nodePath.join(root, backupRel), existing, signal);
+    }
+    await writeText(fs, slidesAbs, markdown, signal);
+    return { plan, text: outlineSummary(plan, PPT_RELS.slides, PPT_RELS.notes, backupRel) };
+}
+/** `action=check`：对已有 `07-答辩/PPT.md` 做确定性质量检查。 */
+export async function runCheckAction(fs, root, args, signal) {
+    const markdown = await resolveDeck(fs, root, signal);
+    const result = checkDeck(markdown, {
+        audience: normalizeAudience(args.audience),
+        fs,
+        root,
+        targetPages: args.pages !== undefined ? clampPages(args.pages) : undefined,
+    });
+    const anchorIssues = await verifyAnchors(markdown, fs, root);
+    const merged = {
+        ...result,
+        issues: [...result.issues, ...anchorIssues],
+        warnings: result.warnings + anchorIssues.length,
+    };
+    return { result: merged, anchorIssues, text: renderCheckReport(merged, PPT_RELS.slides) };
+}
+// ---------------------------------------------------------------------------
+// convert
+// ---------------------------------------------------------------------------
+/** convert 的文本摘要（有界）。 */
+export function convertSummary(slidesRel, pptxRel, notesRel, detection, engine, result, error) {
+    const lines = [];
+    if (result !== undefined && result.ok) {
+        lines.push(`转换成功：${pptxRel}（引擎：${result.engine}）`);
+    }
+    else {
+        lines.push(`未产出 pptx：${error ?? '未知原因'}`);
+    }
+    lines.push(`- 幻灯 Markdown：${slidesRel}`);
+    lines.push(`- 目标文件：${pptxRel}`);
+    lines.push(`- 配置引擎：${engine}`);
+    lines.push(`- 探测：marp=${detection.marp ? '可用' : '无'}；npx marp-cli=${detection.marpNpx ? '可用' : '无'}；pandoc=${detection.pandoc ? '可用' : '无'}`);
+    if (result !== undefined) {
+        for (const record of result.commands) {
+            lines.push(`- 命令：${[record.command, ...record.args].join(' ')} → 退出码 ${record.status ?? 'null'}，耗时 ${record.elapsedMs} ms`);
+        }
+    }
+    lines.push(`- 转换说明（含命令与输出摘要）：${notesRel}`);
+    if (result === undefined || !result.ok) {
+        lines.push('');
+        lines.push('下一步（可直接复制执行）：');
+        lines.push(`- npx --yes @marp-team/marp-cli "${slidesRel}" --pptx --output "${pptxRel}" --allow-local-files`);
+        lines.push('- 或运行 thesis_slides action=guide 查看完整指引（PowerShell/Unix/手工兜底/离线方案）');
+    }
+    return lines.join('\n');
+}
+/** `action=convert`：执行外部转换；失败时**先写说明再抛错**（绝不假装成功）。 */
+export async function runConvertAction(fs, root, options, signal, deps = {}) {
+    const now = deps.now ?? (() => new Date());
+    const detect = deps.detect ?? (() => detectEngines());
+    const runConvert = deps.convert ?? ((slidesPath, outPath, opts) => convert(slidesPath, outPath, { engine: opts.engine, timeoutMs: opts.timeoutMs, exists: path => existsSync(path) }));
+    const writePptx = deps.writeBinary ?? (async () => { });
+    const slidesAbs = nodePath.join(root, PPT_RELS.slides);
+    const pptxAbs = nodePath.join(root, PPT_RELS.pptx);
+    const notesAbs = nodePath.join(root, PPT_RELS.notes);
+    await resolveDeck(fs, root, signal);
+    const detection = detect();
+    let result;
+    let failure;
+    try {
+        result = runConvert(slidesAbs, pptxAbs, { engine: options.ppt.engine, timeoutMs: options.ppt.timeoutMs });
+    }
+    catch (error) {
+        failure = error instanceof Error ? error.message : String(error);
+    }
+    if (result !== undefined && result.ok && failure === undefined) {
+        // 真实转换器已经把 pptx 写在目标路径上；这里只调用落盘钩子（测试替身用），
+        // 生产环境用它保证"产出即落盘"这一契约可替换、可测。
+        await writePptx(pptxAbs, new Uint8Array(0));
+    }
+    const notes = renderConversionNotes({
+        slidesPath: relativeForDisplay(root, slidesAbs),
+        outPath: relativeForDisplay(root, pptxAbs),
+        detection,
+        engine: options.ppt.engine,
+        ...(result !== undefined ? { result } : {}),
+        ...(failure !== undefined ? { error: failure } : {}),
+        theme: options.ppt.theme,
+        now: now(),
+    });
+    await writeText(fs, notesAbs, notes, signal);
+    const text = convertSummary(PPT_RELS.slides, PPT_RELS.pptx, PPT_RELS.notes, detection, options.ppt.engine, result, failure);
+    if (failure !== undefined) {
+        return {
+            text: `${text}\n\n（转换说明已写入 ${PPT_RELS.notes}）`,
+            detection,
+            error: failure,
+        };
+    }
+    return { text, detection, ...(result !== undefined ? { conversion: result } : {}) };
+}
+// ---------------------------------------------------------------------------
+// guide
+// ---------------------------------------------------------------------------
+/** `action=guide`：只输出可复制执行的转换指引，不写盘、不执行。 */
+export function runGuideAction(deps = {}) {
+    const detect = deps.detect ?? (() => detectEngines());
+    const detection = detect();
+    return { text: conversionGuide(PPT_RELS.slides, PPT_RELS.pptx, detection), detection };
+}
+// ---------------------------------------------------------------------------
+// 动作分发
+// ---------------------------------------------------------------------------
+/**
+ * 按 action 分发。`convert` 失败时抛出的错误里**带上已经写好的说明**，
+ * 让模型看到的是一次真实失败 + 下一步命令，而不是沉默。
+ */
+export async function runPptAction(fs, cwd, args, options, signal, deps = {}) {
+    if (args.action === 'guide')
+        return runGuideAction(deps);
+    const root = await requireRoot(fs, cwd, signal);
+    if (args.action === 'outline')
+        return runOutline(fs, root, args, options, signal, deps);
+    if (args.action === 'check') {
+        const checked = await runCheckAction(fs, root, args, signal);
+        return { text: checked.text };
+    }
+    if (args.action === 'convert') {
+        const outcome = await runConvertAction(fs, root, options, signal, deps);
+        if (outcome.error !== undefined)
+            throw new Error(outcome.text);
+        return outcome;
+    }
+    throw new Error(`未知 action：${String(args.action)}。可用：outline | convert | check | guide。`);
+}

package/lib/ppt/check.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 幻灯质量检查（`thesis_slides action=check` 的核心）。
+ *
+ * 全部检查项都是**确定性**的（不调用模型）：页数区间、每页要点条数、单条要点
+ * 字数、是否有讲稿、是否每页都有证据锚点、是否出现「待补充/TODO」、预计时长
+ * 是否落在 8–12 分钟。每条问题都带页码与原文位置，便于逐条修。
+ *
+ * @module dsh-thesis/ppt
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import { type Audience } from './outline.ts';
+/** 问题级别：error = 必须修；warn = 建议修。 */
+export type IssueLevel = 'error' | 'warn';
+/** 一条检查问题。 */
+export interface SlideIssue {
+    /** 稳定的问题代号（便于测试与逐条定位）。 */
+    readonly code: string;
+    readonly level: IssueLevel;
+    /** 定位（如「第 3 页」）；全局问题为「全文」。 */
+    readonly where: string;
+    readonly message: string;
+}
+/** 质量检查结果。 */
+export interface CheckResult {
+    readonly pages: number;
+    readonly estimate: {
+        readonly minMinutes: number;
+        readonly maxMinutes: number;
+        readonly secondsPerSlideMin: number;
+        readonly secondsPerSlideMax: number;
+    };
+    readonly issues: readonly SlideIssue[];
+    readonly errors: number;
+    readonly warnings: number;
+    /** 通过（无 error）时为 true。 */
+    readonly ok: boolean;
+}
+/** 每页预计时长的允许区间（分钟）。 */
+export declare const DURATION_MIN_MINUTES = 8;
+export declare const DURATION_MAX_MINUTES = 12;
+/** 占位符/未完成标记（命中即提示）。 */
+export declare const PLACEHOLDER_PATTERNS: readonly {
+    readonly pattern: RegExp;
+    readonly label: string;
+}[];
+/**
+ * 检查幻灯 Markdown 原文（确定性检查项全集）。
+ *
+ * `pages`/`audience` 用于判定页数区间与时长；`fs`/`root` 可选——提供了就顺便
+ * 验证证据锚点指向的文件是否存在（缺失记 warn，不阻塞）。
+ */
+export declare function checkDeck(markdown: string, options: {
+    readonly audience: Audience;
+    readonly fs?: FileSystem;
+    readonly root?: string;
+    readonly targetPages?: number;
+}): CheckResult;
+/**
+ * 证据锚点落盘校验（可选）：锚点形如 `相对路径#小节`，只校验路径部分是否存在。
+ * 缺失记为 warn——素材尚未生成时会大量缺失，属于正常提示而非错误。
+ */
+export declare function verifyAnchors(markdown: string, fs: FileSystem, root: string): Promise<SlideIssue[]>;
+/** 检查结果的文本渲染（有界；工具返回值用）。 */
+export declare function renderCheckReport(result: CheckResult, deckRelPath: string): string;

package/lib/ppt/check.js

@@ -0,0 +1,185 @@
+/**
+ * 幻灯质量检查（`thesis_slides action=check` 的核心）。
+ *
+ * 全部检查项都是**确定性**的（不调用模型）：页数区间、每页要点条数、单条要点
+ * 字数、是否有讲稿、是否每页都有证据锚点、是否出现「待补充/TODO」、预计时长
+ * 是否落在 8–12 分钟。每条问题都带页码与原文位置，便于逐条修。
+ *
+ * @module dsh-thesis/ppt
+ */
+import * as nodePath from 'node:path';
+import { MAX_BULLETS_PER_SLIDE, MAX_BULLET_CHARS, MAX_TITLE_CHARS, MIN_BULLETS_PER_SLIDE, audienceProfile } from "./outline.js";
+import { parseMarp } from "./marp.js";
+/** 每页预计时长的允许区间（分钟）。 */
+export const DURATION_MIN_MINUTES = 8;
+export const DURATION_MAX_MINUTES = 12;
+/** 占位符/未完成标记（命中即提示）。 */
+export const PLACEHOLDER_PATTERNS = [
+    { pattern: /待补充/, label: '待补充' },
+    { pattern: /待补\b|待填|待定/, label: '待填占位' },
+    { pattern: /TODO|FIXME/, label: 'TODO/FIXME' },
+    { pattern: /<[^>\s]{1,20}>/, label: '<> 模板占位' },
+];
+function textLength(text) {
+    return text.replace(/\s+/g, '').length;
+}
+/**
+ * 检查幻灯 Markdown 原文（确定性检查项全集）。
+ *
+ * `pages`/`audience` 用于判定页数区间与时长；`fs`/`root` 可选——提供了就顺便
+ * 验证证据锚点指向的文件是否存在（缺失记 warn，不阻塞）。
+ */
+export function checkDeck(markdown, options) {
+    const deck = parseMarp(markdown);
+    const profile = audienceProfile(options.audience);
+    const issues = [];
+    const pages = deck.slides.length;
+    const push = (code, level, where, message) => {
+        issues.push({ code, level, where, message });
+    };
+    // 1. 页数区间
+    const [minPages, maxPages] = profile.pages;
+    if (pages === 0) {
+        push('deck-empty', 'error', '全文', '没有解析到任何幻灯片（每页需要一行 `## 标题` 与要点列表）。');
+    }
+    else if (pages < minPages) {
+        push('deck-too-few-pages', 'error', '全文', `只有 ${pages} 页，少于${profile.label}答辩骨架要求的 ${minPages}-${maxPages} 页。`);
+    }
+    else if (pages > maxPages) {
+        push('deck-too-many-pages', 'error', '全文', `共 ${pages} 页，超出${profile.label}答辩骨架的 ${minPages}-${maxPages} 页；删页而不是压缩讲述。`);
+    }
+    if (options.targetPages !== undefined && pages !== options.targetPages) {
+        push('deck-page-mismatch', 'warn', '全文', `页数 ${pages} 与目标 ${options.targetPages} 页不一致。`);
+    }
+    // 2. frontmatter
+    if (deck.theme === '')
+        push('deck-theme-missing', 'warn', '全文', 'frontmatter 缺少 `theme:`，Marp 会退回默认主题。');
+    // 3-6. 逐页
+    for (const slide of deck.slides) {
+        checkSlide(slide, push);
+    }
+    // 7. 时长
+    const minMinutes = Math.max(1, Math.round((pages * profile.secondsMin) / 60));
+    const maxMinutes = Math.max(1, Math.round((pages * profile.secondsMax) / 60));
+    if (pages > 0 && maxMinutes > DURATION_MAX_MINUTES) {
+        push('time-over', 'error', '全文', `预计时长 ${minMinutes}-${maxMinutes} 分钟，超出 ${DURATION_MIN_MINUTES}-${DURATION_MAX_MINUTES} 分钟的答辩窗口；删页或压缩每页讲述内容（每页 ${profile.secondsMin}-${profile.secondsMax} 秒）。`);
+    }
+    else if (pages > 0 && minMinutes < DURATION_MIN_MINUTES) {
+        push('time-under', 'warn', '全文', `预计时长 ${minMinutes}-${maxMinutes} 分钟，短于 ${DURATION_MIN_MINUTES} 分钟；老师一般要求讲满，建议把要点讲透或补一页实现细节。`);
+    }
+    const errors = issues.filter(i => i.level === 'error').length;
+    const warnings = issues.filter(i => i.level === 'warn').length;
+    return {
+        pages,
+        estimate: {
+            minMinutes,
+            maxMinutes,
+            secondsPerSlideMin: profile.secondsMin,
+            secondsPerSlideMax: profile.secondsMax,
+        },
+        issues,
+        errors,
+        warnings,
+        ok: errors === 0,
+    };
+}
+function checkSlide(slide, push) {
+    const where = `第 ${slide.index} 页「${slide.title}」`;
+    const titleChars = textLength(slide.title);
+    // 封面/致谢页上的姓名、日期等占位符属正常（提交前替换），其余页面的占位符是必须修的问题。
+    const placeholderTolerated = slide.index === 1 || /^(封面|致谢|致谢页|问答页|目录)$/.test(slide.title.trim());
+    if (titleChars > MAX_TITLE_CHARS) {
+        push('title-too-long', 'warn', where, `标题 ${titleChars} 字，超过 ${MAX_TITLE_CHARS} 字上限，会换行挤压版面。`);
+    }
+    if (slide.bullets.length < MIN_BULLETS_PER_SLIDE) {
+        push('too-few-bullets', 'warn', where, `只有 ${slide.bullets.length} 条要点，建议 ${MIN_BULLETS_PER_SLIDE}-${MAX_BULLETS_PER_SLIDE} 条（一页一个观点）。`);
+    }
+    if (slide.bullets.length > MAX_BULLETS_PER_SLIDE) {
+        push('too-many-bullets', 'error', where, `${slide.bullets.length} 条要点，超出每页 ${MAX_BULLETS_PER_SLIDE} 条上限。`);
+    }
+    for (const [i, bullet] of slide.bullets.entries()) {
+        if (textLength(bullet.text) > MAX_BULLET_CHARS) {
+            push('bullet-too-long', 'error', where, `第 ${i + 1} 条要点 ${textLength(bullet.text)} 字，超出 ${MAX_BULLET_CHARS} 字上限：${bullet.text.slice(0, 40)}…`);
+        }
+        if (bullet.truncated) {
+            push('bullet-truncated', 'warn', where, `第 ${i + 1} 条要点在生成时被自动截断（标记「已截断」），请人工确认语义是否完整。`);
+        }
+        for (const { pattern, label } of PLACEHOLDER_PATTERNS) {
+            if (pattern.test(bullet.text)) {
+                const informational = placeholderTolerated && (label === '待填占位' || label === '<> 模板占位');
+                push('placeholder', informational ? 'warn' : 'error', where, `第 ${i + 1} 条要点含未完成标记「${label}」：${bullet.text}${informational ? '（封面/致谢页的占位符属正常，提交前替换）' : ''}`);
+            }
+        }
+        if (bullet.anchor === undefined || bullet.anchor.trim() === '') {
+            push('missing-anchor', 'error', where, `第 ${i + 1} 条要点没有证据锚点（应指向真实文件/章节/数据，如 06-论文/章节/04-系统设计.md#架构）。`);
+        }
+        else if (/^材料|^见论文|^结论/.test(bullet.anchor.trim())) {
+            push('vague-anchor', 'warn', where, `第 ${i + 1} 条要点的锚点过于笼统：${bullet.anchor}`);
+        }
+    }
+    if (slide.note === undefined || slide.note.trim() === '') {
+        push('missing-note', 'warn', where, '缺少讲稿要点（生成时应写入 `<!-- 讲稿：… -->` 注释，Marp 演示者备注用）。');
+    }
+}
+/**
+ * 证据锚点落盘校验（可选）：锚点形如 `相对路径#小节`，只校验路径部分是否存在。
+ * 缺失记为 warn——素材尚未生成时会大量缺失，属于正常提示而非错误。
+ */
+export async function verifyAnchors(markdown, fs, root) {
+    const deck = parseMarp(markdown);
+    const issues = [];
+    const checked = new Map();
+    for (const slide of deck.slides) {
+        for (const [i, bullet] of slide.bullets.entries()) {
+            if (bullet.anchor === undefined || bullet.anchor.trim() === '')
+                continue;
+            const rel = (bullet.anchor.split('#')[0] ?? '').trim();
+            if (rel === '' || /^(git log|见论文|材料)/.test(rel))
+                continue;
+            let exists = checked.get(rel);
+            if (exists === undefined) {
+                exists = await fileExists(fs, joinPath(root, rel));
+                checked.set(rel, exists);
+            }
+            if (!exists) {
+                issues.push({
+                    code: 'anchor-file-missing',
+                    level: 'warn',
+                    where: `第 ${slide.index} 页「${slide.title}」`,
+                    message: `第 ${i + 1} 条要点的证据锚点指向的文件不存在：${rel}（素材未生成或路径已变；答辩前请补齐真实证据）`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function joinPath(root, rel) {
+    return nodePath.join(root, rel.replace(/^[\\/]+/, ''));
+}
+async function fileExists(fs, absPath) {
+    try {
+        await fs.readText(await fs.resolve(absPath), undefined);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 检查结果的文本渲染（有界；工具返回值用）。 */
+export function renderCheckReport(result, deckRelPath) {
+    const lines = [];
+    lines.push(`幻灯质量检查：${deckRelPath}`);
+    lines.push(`- 页数：${result.pages} 页`);
+    lines.push(`- 预计时长：${result.estimate.minMinutes}-${result.estimate.maxMinutes} 分钟（每页 ${result.estimate.secondsPerSlideMin}-${result.estimate.secondsPerSlideMax} 秒）`);
+    lines.push(`- 结论：${result.ok ? '通过（无 error）' : `${result.errors} 条必须修、${result.warnings} 条建议修`}`);
+    if (result.issues.length === 0) {
+        lines.push('- 未发现问题。');
+        return lines.join('\n');
+    }
+    lines.push('');
+    lines.push('问题清单（逐条定位）：');
+    for (const issue of result.issues) {
+        lines.push(`- [${issue.level === 'error' ? '必须修' : '建议修'}] ${issue.where} · ${issue.code}：${issue.message}`);
+    }
+    return lines.join('\n');
+}

package/lib/ppt/commands.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 斜杠命令 `/thesis-defense` 的**幻灯侧**输入解析。
+ *
+ * 命令名遵循 DSH 的 `[a-z][a-z0-9_-]*` 约束（kebab-case）。命令注册本身在
+ * 装配层（`src/index.ts`）完成：`/thesis-defense` 同时覆盖答辩幻灯与代码演练，
+ * 由装配层聚合两侧的处理器——这样 `ppt/` 与 `codewalk/` 之间没有反向依赖。
+ *
+ * @module dsh-thesis/ppt
+ */
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { PptOptions } from '../config.ts';
+import { type PptArgs, type PptDeps } from './actions.ts';
+/** 幻灯侧的子命令（与代码演练侧区分）。 */
+export declare const PPT_SUBCOMMANDS: readonly string[];
+/** 把 `/thesis-defense <输入>` 的幻灯侧部分解析成工具参数。 */
+export declare function parsePptCommandInput(rawInput: string): PptArgs;
+/**
+ * 幻灯侧的命令处理器（由装配层在 `/thesis-defense` 下调度）。
+ *
+ * `rawInput` 仍是命令名之后的全部输入；本函数只关心幻灯侧子命令。
+ */
+export declare function handlePptCommand(fs: FileSystem, options: {
+    ppt: PptOptions;
+}, invocation: CommandInvocation, deps?: PptDeps): Promise<CommandResult>;
+/** 命令的展示元信息（装配层注册时使用）。 */
+export declare const PPT_COMMAND_DESCRIPTION = "\u7B54\u8FA9\u5E7B\u706F\uFF1A\u751F\u6210 Marp Markdown\uFF08prepare/outline\uFF09/ \u6267\u884C\u5916\u90E8\u8F6C\u6362\uFF08convert\uFF09/ \u8D28\u91CF\u68C0\u67E5\uFF08check\uFF09/ \u8F6C\u6362\u6307\u5F15\uFF08guide\uFF09";
+export declare const PPT_COMMAND_HINT = "prepare | convert | check | guide [\u9875\u6570] [undergrad|master] [force]";

package/lib/ppt/commands.js

@@ -0,0 +1,71 @@
+/**
+ * 斜杠命令 `/thesis-defense` 的**幻灯侧**输入解析。
+ *
+ * 命令名遵循 DSH 的 `[a-z][a-z0-9_-]*` 约束（kebab-case）。命令注册本身在
+ * 装配层（`src/index.ts`）完成：`/thesis-defense` 同时覆盖答辩幻灯与代码演练，
+ * 由装配层聚合两侧的处理器——这样 `ppt/` 与 `codewalk/` 之间没有反向依赖。
+ *
+ * @module dsh-thesis/ppt
+ */
+import { runPptAction } from "./actions.js";
+async function safe(work) {
+    try {
+        return { kind: 'success', text: await work() };
+    }
+    catch (error) {
+        return { kind: 'error', text: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** 幻灯侧的子命令（与代码演练侧区分）。 */
+export const PPT_SUBCOMMANDS = ['prepare', 'convert', 'check', 'guide'];
+/** 把 `/thesis-defense <输入>` 的幻灯侧部分解析成工具参数。 */
+export function parsePptCommandInput(rawInput) {
+    const tokens = rawInput.trim().split(/\s+/).filter(t => t !== '');
+    let action = 'outline';
+    let pages;
+    let audience;
+    let force = false;
+    for (const token of tokens) {
+        const lowered = token.toLowerCase();
+        if (lowered === 'prepare' || lowered === 'outline' || lowered === 'convert' || lowered === 'check' || lowered === 'guide') {
+            action = lowered === 'prepare' ? 'outline' : lowered;
+            continue;
+        }
+        if (lowered === 'undergrad' || lowered === 'master') {
+            audience = lowered;
+            continue;
+        }
+        if (lowered === 'force' || lowered === '--force' || lowered === '-f') {
+            force = true;
+            continue;
+        }
+        const number = Number.parseInt(token, 10);
+        if (Number.isFinite(number)) {
+            pages = number;
+            continue;
+        }
+        throw new Error(`无法识别的参数「${token}」。用法：/thesis-defense prepare [页数] [undergrad|master] [force]`
+            + ' | convert | check | guide | new <原始项目路径> | status | check [里程碑]');
+    }
+    return {
+        action,
+        ...(pages !== undefined ? { pages } : {}),
+        ...(audience !== undefined ? { audience } : {}),
+        ...(force ? { force: true } : {}),
+    };
+}
+/**
+ * 幻灯侧的命令处理器（由装配层在 `/thesis-defense` 下调度）。
+ *
+ * `rawInput` 仍是命令名之后的全部输入；本函数只关心幻灯侧子命令。
+ */
+export async function handlePptCommand(fs, options, invocation, deps = {}) {
+    return await safe(async () => {
+        const args = parsePptCommandInput(invocation.rawInput);
+        const outcome = await runPptAction(fs, invocation.agent.session.header.cwd, args, options, invocation.signal, deps);
+        return outcome.text;
+    });
+}
+/** 命令的展示元信息（装配层注册时使用）。 */
+export const PPT_COMMAND_DESCRIPTION = '答辩幻灯：生成 Marp Markdown（prepare/outline）/ 执行外部转换（convert）/ 质量检查（check）/ 转换指引（guide）';
+export const PPT_COMMAND_HINT = 'prepare | convert | check | guide [页数] [undergrad|master] [force]';