dsh-thesis 1.0.0

package/lib/paper/tools/lit.js

@@ -0,0 +1,236 @@
+/**
+ * 文献三工具：thesis_lit_search / thesis_lit_save / thesis_lit_note。
+ *
+ * 机制保证"零假文献"：
+ * - search 只返回真实 API 检索结果，并把结果写入检索缓存（.lit-cache.json）；
+ * - save 只接受缓存中的记录 id，元数据零转述，写 refs.bib 并留审计行；
+ * - note 基于缓存或 refs.bib 生成笔记骨架。
+ */
+import * as nodePath from 'node:path';
+import { describeReadFailure, isMissingError } from "../../shared/fs-errors.js";
+import { searchLiterature, LIT_SOURCES, } from "../lib/lit-api.js";
+import { appendLitRecord, loadCache, mergeRecords, NOTES_DIR_REL, REFS_BIB_REL, saveCache, saveRow, searchRow, } from "../lib/lit-cache.js";
+import { bibKeyFor, buildBibtex, dedupeKey, parseBibDois, parseBibKeys } from "../lib/bibtex.js";
+import { findThesisRoot } from "../lib/project.js";
+const BIB_HEADER = `% 文献库（BibTeX）。
+% 红线：本文件只收录真实检索到的文献（由 thesis_lit_search/save 写入）。
+% 每条必须含 DOI 或 URL。引用格式遵循 GB/T 7714-2015（顺序编码制）。
+
+`;
+async function thesisRoot(fs, cwd, signal) {
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null) {
+        throw new Error('未找到论文工作区（向上查找 00-管理/进度台账.md 失败）。请先用 thesis_init 创建工作区，或在论文仓库目录内操作。');
+    }
+    return root;
+}
+function displayAuthors(authors, max = 3) {
+    if (authors.length === 0)
+        return '（无作者信息）';
+    const head = authors.slice(0, max).join(', ');
+    return authors.length > max ? `${head} 等` : head;
+}
+function displayRecord(record) {
+    const lines = [];
+    lines.push(`【${record.id}】${record.title}`);
+    lines.push(`  作者：${displayAuthors(record.authors)}；年份：${record.year ?? '未知'}；出处：${record.venue || '未知'}`);
+    if (record.doi !== undefined)
+        lines.push(`  DOI：${record.doi}`);
+    if (record.url !== undefined)
+        lines.push(`  URL：${record.url}`);
+    if (record.citationCount !== undefined)
+        lines.push(`  被引：${record.citationCount}`);
+    if (record.abstract !== undefined)
+        lines.push(`  摘要：${record.abstract}`);
+    return lines.join('\n');
+}
+export async function runLitSearch(fs, args, cwd, signal, fetchImpl) {
+    if (args.query === undefined || args.query.trim() === '')
+        throw new Error('query 必填：检索关键词（中英文均可）。');
+    const root = await thesisRoot(fs, cwd, signal);
+    const results = await searchLiterature(fetchImpl, {
+        query: args.query.trim(),
+        ...(args.year_from !== undefined ? { yearFrom: args.year_from } : {}),
+        ...(args.limit !== undefined ? { limit: args.limit } : {}),
+        ...(args.source !== undefined ? { source: args.source } : {}),
+        signal,
+    });
+    const cache = mergeRecords(await loadCache(fs, root, signal), results);
+    await saveCache(fs, root, cache, signal);
+    const date = new Date().toISOString().slice(0, 10);
+    await appendLitRecord(fs, root, searchRow(date, results[0].source, args.query.trim(), results.length, results.map(r => r.id)), signal);
+    const lines = [];
+    lines.push(`检索「${args.query.trim()}」命中 ${results.length} 条（来源：${results[0].source}），已写入检索缓存与检索记录。`);
+    lines.push('');
+    results.slice(0, args.limit ?? 10).forEach(r => {
+        lines.push(displayRecord(r));
+        lines.push('');
+    });
+    lines.push('下一步：选定文献后用 thesis_lit_save（ids: [记录 id]）收录进 refs.bib；再用 thesis_lit_note 生成阅读笔记。');
+    return lines.join('\n');
+}
+export async function runLitSave(fs, args, cwd, signal) {
+    if (args.ids === undefined || args.ids.length === 0)
+        throw new Error('ids 必填：thesis_lit_search 返回的记录 id 列表。');
+    const root = await thesisRoot(fs, cwd, signal);
+    const cache = await loadCache(fs, root, signal);
+    let bib;
+    try {
+        bib = await fs.readText(await fs.resolve(nodePath.join(root, REFS_BIB_REL), { signal }), signal);
+    }
+    catch (error) {
+        // 只有「文献库还没建过」才从表头开始。读失败（权限/IO）时必须停下：
+        // 否则会在「假设文献库是空的」前提下写回，等于删掉学生已有的全部文献。
+        if (!isMissingError(error)) {
+            throw new Error(describeReadFailure('文献库（02-文献/refs.bib）', nodePath.join(root, REFS_BIB_REL), error, signal));
+        }
+        bib = BIB_HEADER;
+    }
+    if (bib.trim() === '')
+        bib = BIB_HEADER;
+    const keys = parseBibKeys(bib);
+    const dois = parseBibDois(bib);
+    const date = new Date().toISOString().slice(0, 10);
+    const outcomes = [];
+    let added = 0;
+    for (const id of args.ids) {
+        const record = cache.records[id];
+        if (record === undefined) {
+            outcomes.push(`✗ ${id}：不在检索缓存中。缓存只包含真实检索结果；请先用 thesis_lit_search 检索，不要手工构造元数据。`);
+            continue;
+        }
+        if (record.doi !== undefined && dois.has(record.doi.toLowerCase())) {
+            outcomes.push(`⏭ ${record.title}：DOI 已在 refs.bib 中，跳过。`);
+            continue;
+        }
+        const finalKey = dedupeKey(bibKeyFor(record), keys);
+        keys.add(finalKey);
+        if (record.doi !== undefined)
+            dois.add(record.doi.toLowerCase());
+        const { entry } = buildBibtex(record, finalKey);
+        bib += `${entry}\n\n`;
+        await appendLitRecord(fs, root, saveRow(date, record.source, record.title, finalKey, record.doi), signal);
+        outcomes.push(`✓ ${record.title} → refs.bib [${finalKey}]`);
+        added += 1;
+    }
+    await fs.writeText(await fs.resolve(nodePath.join(root, REFS_BIB_REL), { signal }), bib, undefined, signal);
+    outcomes.push('', `本次收录 ${added}/${args.ids.length} 条。`);
+    return outcomes.join('\n');
+}
+// ---------------------------------------------------------------------------
+// 笔记
+// ---------------------------------------------------------------------------
+function noteTemplate(record, bibKey) {
+    const authorText = record.authors.length === 0 ? '（无作者信息）' : displayAuthors(record.authors);
+    const meta = [`收录于 refs.bib [${bibKey}]`];
+    if (record.doi !== undefined)
+        meta.push(`DOI：${record.doi}`);
+    if (record.url !== undefined)
+        meta.push(`URL：${record.url}`);
+    if (record.citationCount !== undefined)
+        meta.push(`被引 ${record.citationCount} 次`);
+    return `# ${record.title}（${authorText}，${record.year ?? '年份未知'}，${record.venue || '出处未知'}）
+
+> ${meta.join('；')}
+> 笔记模板见技能 thesis-literature；写论文时从这里取"可用引用句"。
+
+## 这篇解决什么问题
+
+（待补）
+
+## 方法/技术要点（3-5 条，用自己的话）
+
+（待补）
+
+## 实验与结论（数据集/指标/结果）
+
+（待补）
+
+## 与我课题的关系
+
+（待补：借鉴什么 / 对比什么 / 差异在哪）
+
+## 可用引用句
+
+（待补：1-2 句，注明放哪一章）
+
+## 摘要（原始）
+
+${record.abstract ?? '（检索记录无摘要；请从原文自行摘录）'}
+`;
+}
+/** 从 refs.bib 中按 key 提取最小记录（供 note 在缓存缺失时使用）。 */
+function findRecordByBibKey(bib, key) {
+    const m = new RegExp(`^@(\\w+)\\s*\\{\\s*${key}\\s*,\\s*([\\s\\S]*?)\\n\\}`, 'm').exec(bib);
+    if (m === null)
+        return undefined;
+    const body = m[2] ?? '';
+    const field = (name) => {
+        const fm = new RegExp(`^\\s*${name}\\s*=\\s*\\{([\\s\\S]*?)\\}`, 'm').exec(body);
+        return fm?.[1]?.trim();
+    };
+    const authorRaw = field('author');
+    const authors = authorRaw === undefined ? [] : authorRaw.split(/\s+and\s+/).map(a => a.trim()).filter(a => a !== '');
+    const title = field('title') ?? '（未知标题）';
+    const yearRaw = field('year');
+    const year = yearRaw === undefined || yearRaw === '' ? null : Number.parseInt(yearRaw, 10);
+    const doi = field('doi');
+    const url = field('url');
+    const typeMap = { article: 'article', inproceedings: 'inproceedings', book: 'book', phdthesis: 'phdthesis' };
+    return {
+        id: '',
+        title,
+        authors,
+        year: Number.isNaN(year) ? null : year,
+        venue: field('journal') ?? field('booktitle') ?? field('school') ?? field('publisher') ?? field('howpublished') ?? '',
+        type: typeMap[m[1] ?? ''] ?? 'misc',
+        ...(doi !== undefined ? { doi } : {}),
+        ...(url !== undefined ? { url } : {}),
+        source: 'refs.bib',
+    };
+}
+export async function runLitNote(fs, args, cwd, signal) {
+    if (args.ref === undefined || args.ref.trim() === '')
+        throw new Error('ref 必填：缓存记录 id（thesis_lit_search 返回）或 refs.bib 条目 key。');
+    const root = await thesisRoot(fs, cwd, signal);
+    const ref = args.ref.trim();
+    let record;
+    let bibKey;
+    const cache = await loadCache(fs, root, signal);
+    if (cache.records[ref] !== undefined) {
+        record = cache.records[ref];
+        bibKey = bibKeyFor(record);
+    }
+    else {
+        let bib;
+        try {
+            bib = await fs.readText(await fs.resolve(nodePath.join(root, REFS_BIB_REL), { signal }), signal);
+        }
+        catch (error) {
+            if (!isMissingError(error)) {
+                throw new Error(describeReadFailure('文献库（02-文献/refs.bib）', nodePath.join(root, REFS_BIB_REL), error, signal));
+            }
+            throw new Error(`记录 ${ref} 既不在检索缓存、refs.bib 也不存在。请先用 thesis_lit_search 检索。`);
+        }
+        const byKey = findRecordByBibKey(bib, ref);
+        if (byKey === undefined) {
+            throw new Error(`记录 ${ref} 不在检索缓存中，refs.bib 中也没有该 key。请先用 thesis_lit_search 检索。`);
+        }
+        record = byKey;
+        bibKey = ref;
+    }
+    const notePath = nodePath.join(root, NOTES_DIR_REL, `${bibKey}.md`);
+    try {
+        await fs.readText(await fs.resolve(notePath, { signal }), signal);
+        if (args.force !== true)
+            throw new Error(`笔记已存在：${notePath}。如确需覆盖，请设 force: true。`);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('笔记已存在'))
+            throw error;
+        // 不存在：继续创建。
+    }
+    await fs.writeText(await fs.resolve(notePath, { signal }), noteTemplate(record, bibKey), undefined, signal);
+    return `笔记骨架已创建：${notePath}\n下一步：读原文，补全"方法/技术要点"与"与我课题的关系"两节（见技能 thesis-literature）。`;
+}
+export { LIT_SOURCES };

package/lib/paper/tools/progress.d.ts

@@ -0,0 +1,18 @@
+/**
+ * thesis_progress：进度台账读写 + 人工关卡闸门（G1/G2/G3/G4）。
+ *
+ * 关卡是工具层强制，不是提示语：阶段入口关卡未通过时，该阶段任务
+ * 拒绝进入 doing/done（lib/ledger.ts canUpdateTask）。通过关卡前，
+ * 关联任务必须先 done（lib/ledger.ts applyGate）。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+export interface ProgressArgs {
+    action: 'report' | 'update' | 'gate';
+    task_id?: string;
+    status?: 'todo' | 'doing' | 'done';
+    note?: string;
+    gate?: 'G1' | 'G2' | 'G3' | 'G4';
+    pass?: boolean;
+    chapter?: string;
+}
+export declare function runProgress(fs: FileSystem, args: ProgressArgs, cwd: string | undefined, signal?: AbortSignal): Promise<string>;

package/lib/paper/tools/progress.js

@@ -0,0 +1,77 @@
+/**
+ * thesis_progress：进度台账读写 + 人工关卡闸门（G1/G2/G3/G4）。
+ *
+ * 关卡是工具层强制，不是提示语：阶段入口关卡未通过时，该阶段任务
+ * 拒绝进入 doing/done（lib/ledger.ts canUpdateTask）。通过关卡前，
+ * 关联任务必须先 done（lib/ledger.ts applyGate）。
+ */
+import * as nodePath from 'node:path';
+import { describeReadFailure, isMissingError } from "../../shared/fs-errors.js";
+import { applyGate, applyTaskUpdate, GATE_NAMES, parseLedger, renderLedger, renderReport, } from "../lib/ledger.js";
+import { findThesisRoot, LEDGER_REL } from "../lib/project.js";
+async function loadLedger(fs, cwd, signal) {
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null) {
+        throw new Error('未找到论文工作区（向上查找 00-管理/进度台账.md 失败）。请先用 thesis_init 创建工作区，或在论文仓库目录内操作。');
+    }
+    const ledgerPath = nodePath.join(root, LEDGER_REL);
+    let raw;
+    try {
+        raw = await fs.readText(await fs.resolve(ledgerPath, { signal }), signal);
+    }
+    catch (error) {
+        // 只有「台账确实不存在」才可以重建（工作区被手工删掉台账的异常情况）。
+        // 读失败（权限/IO）时重建会把 25 条真实任务状态重置为初始态，且报告看起来一切正常——
+        // 那是最坏的一种失败：学生以为进度没丢。
+        if (!isMissingError(error)) {
+            throw new Error(describeReadFailure('进度台账（00-管理/进度台账.md）', ledgerPath, error, signal));
+        }
+        const fresh = renderLedger(parseLedger('').state);
+        await fs.writeText(await fs.resolve(ledgerPath, { signal }), fresh, undefined, signal);
+        return { root, state: parseLedger(fresh).state };
+    }
+    const parsed = parseLedger(raw);
+    if (!parsed.found) {
+        throw new Error('进度台账的 `<!-- thesis:state -->` 状态块缺失或损坏。请勿手工修改该 JSON 块；如被误改，可让 AI 依据默认任务清单重建。');
+    }
+    return { root, state: parsed.state };
+}
+async function saveLedger(fs, root, state, signal) {
+    const target = await fs.resolve(nodePath.join(root, LEDGER_REL), { signal });
+    await fs.writeText(target, renderLedger(state), undefined, signal);
+}
+export async function runProgress(fs, args, cwd, signal) {
+    switch (args.action) {
+        case 'report': {
+            const { state } = await loadLedger(fs, cwd, signal);
+            return renderReport(state);
+        }
+        case 'update': {
+            if (args.task_id === undefined || args.status === undefined) {
+                throw new Error('update 需要 task_id 与 status（todo/doing/done）。');
+            }
+            const { root, state } = await loadLedger(fs, cwd, signal);
+            const result = applyTaskUpdate(state, args.task_id, args.status, args.note);
+            if (!result.ok)
+                throw new Error(result.reason);
+            await saveLedger(fs, root, state, signal);
+            return `已更新：${result.task.id} ${result.task.title} → ${args.status}。\n${renderReport(state)}`;
+        }
+        case 'gate': {
+            if (args.gate === undefined || args.pass === undefined) {
+                throw new Error('gate 需要 gate（G1/G2/G3/G4）与 pass（boolean）。');
+            }
+            const { root, state } = await loadLedger(fs, cwd, signal);
+            const result = applyGate(state, args.gate, args.pass, { chapter: args.chapter, note: args.note });
+            if (!result.ok)
+                throw new Error(result.reason);
+            await saveLedger(fs, root, state, signal);
+            const name = GATE_NAMES[args.gate] ?? args.gate;
+            const extra = args.gate === 'G2' && args.chapter !== undefined ? `（${args.chapter}）` : '';
+            return `关卡 ${args.gate} ${name}${extra} ${args.pass ? '已通过' : '已重置为未通过'}。\n${renderReport(state)}`;
+        }
+        default: {
+            throw new Error(`未知 action：${String(args.action)}。有效值：report、update、gate。`);
+        }
+    }
+}

package/lib/paper/tools/review.d.ts

@@ -0,0 +1,11 @@
+/**
+ * thesis_review：单章确定性评审（字数/大纲/引用/图表/未完成标记/G2 清单）。
+ *
+ * 评审的是"机器可证明"的部分；语义质量由 AI 依据 thesis-writing 技能完成，
+ * 报告结论里会提示这一点。G2 人工验收流程见技能 thesis-pipeline / thesis-writing。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+export interface ReviewArgs {
+    chapter: string;
+}
+export declare function runReview(fs: FileSystem, args: ReviewArgs, cwd: string | undefined, signal?: AbortSignal): Promise<string>;

package/lib/paper/tools/review.js

@@ -0,0 +1,41 @@
+/**
+ * thesis_review：单章确定性评审（字数/大纲/引用/图表/未完成标记/G2 清单）。
+ *
+ * 评审的是"机器可证明"的部分；语义质量由 AI 依据 thesis-writing 技能完成，
+ * 报告结论里会提示这一点。G2 人工验收流程见技能 thesis-pipeline / thesis-writing。
+ */
+import * as nodePath from 'node:path';
+import { chapterMetaFor } from "../lib/layout.js";
+import { REFS_BIB_REL } from "../lib/lit-cache.js";
+import { findThesisRoot } from "../lib/project.js";
+import { renderReviewReport, reviewChapter } from "../lib/review.js";
+export async function runReview(fs, args, cwd, signal) {
+    if (args.chapter === undefined || args.chapter.trim() === '') {
+        throw new Error('chapter 必填：章节文件名，如 01-绪论（可带 .md）。');
+    }
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null) {
+        throw new Error('未找到论文工作区（向上查找 00-管理/进度台账.md 失败）。请先在论文仓库目录内操作。');
+    }
+    const located = chapterMetaFor(args.chapter.trim());
+    if (located === undefined) {
+        throw new Error(`未知章节：${args.chapter}。有效章节：01-绪论 至 07-总结与展望。`);
+    }
+    const chapterPath = nodePath.join(root, '06-论文/章节', `${located.meta.file}.md`);
+    let chapterText;
+    try {
+        chapterText = await fs.readText(await fs.resolve(chapterPath, { signal }), signal);
+    }
+    catch {
+        throw new Error(`章节文件不存在：${chapterPath}。请先撰写该章（模板已由 thesis_init 生成，可能尚未动笔）。`);
+    }
+    let bibText = '';
+    try {
+        bibText = await fs.readText(await fs.resolve(nodePath.join(root, REFS_BIB_REL), { signal }), signal);
+    }
+    catch {
+        // 文献库尚未建立：引用检查会如实报告 0 条。
+    }
+    const report = reviewChapter({ chapterText, bibText, meta: located.meta, chapterNo: located.chapterNo });
+    return renderReviewReport(report);
+}

package/lib/ppt/actions.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `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 type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { PptOptions } from '../config.ts';
+import { type Audience, type OutlineInputs, type SlidePlan } from './outline.ts';
+import { type CheckResult, type SlideIssue } from './check.ts';
+import { type ConversionResult, type EngineDetection } from './convert.ts';
+/** `thesis_slides` 的参数。 */
+export interface PptArgs {
+    readonly action: 'outline' | 'convert' | 'check' | 'guide';
+    /** 目标页数（默认 11，会夹到骨架允许区间）。 */
+    readonly pages?: number;
+    /** 听众档位：undergrad（默认）| master。 */
+    readonly audience?: Audience;
+    /** outline：已存在 PPT.md 时是否覆盖（默认 false，覆盖前自动备份）。 */
+    readonly force?: boolean;
+}
+/** 可注入的依赖（测试用替身；生产用默认实现）。 */
+export interface PptDeps {
+    /** 引擎探测替身。 */
+    readonly detect?: () => EngineDetection;
+    /** 转换替身（测试用它模拟成功/失败）。 */
+    readonly convert?: (slidesPath: string, outPath: string, options: {
+        engine: PptOptions['engine'];
+        timeoutMs: number;
+    }) => ConversionResult;
+    /** 二进制落盘钩子（默认不做事：真实转换器已把 pptx 写在目标路径上）。 */
+    readonly writeBinary?: (absPath: string, data: Uint8Array) => Promise<void>;
+    /** 时间源（测试固定备份文件名）。 */
+    readonly now?: () => Date;
+}
+/** PPT 工具在论文工作区里的所有落盘位置。 */
+export declare const PPT_RELS: {
+    /** 幻灯 Markdown（唯一真源）。 */
+    readonly slides: "07-答辩/PPT.md";
+    /** 外部转换器产出的 pptx。 */
+    readonly pptx: "07-答辩/PPT.pptx";
+    /** 转换说明（探测结果 + 确切命令，任何情况都写）。 */
+    readonly notes: "07-答辩/PPT转换说明.md";
+    /** 素材（输入，由 thesis_defense 生成）。 */
+    readonly materials: "07-答辩/答辩素材.md";
+};
+/** 动作返回：有界文本 + 结构化关键事实（测试与上层复用）。 */
+export interface PptActionResult {
+    readonly text: string;
+    readonly plan?: SlidePlan;
+    readonly detection?: EngineDetection;
+    readonly conversion?: ConversionResult;
+    readonly error?: string;
+}
+/** 时间戳（本地时间，文件名安全：20260912-184800）。 */
+export declare function timestamp(now: Date): string;
+/** 由已装载的素材构建幻灯计划（工具与测试共用）。 */
+export declare function planFromInputs(inputs: OutlineInputs, audience: Audience, pages: number): SlidePlan;
+/** 定位论文仓库根；找不到即抛错（所有动作都要求在工作区内）。 */
+export declare function requireRoot(fs: FileSystem, cwd: string | undefined, signal?: AbortSignal): Promise<string>;
+/** outline 的文本摘要（有界）。 */
+export declare function outlineSummary(plan: SlidePlan, slidesRel: string, notesRel: string, backupRel?: string): string;
+/** `action=outline`：生成/刷新 `07-答辩/PPT.md`。 */
+export declare function runOutline(fs: FileSystem, root: string, args: PptArgs, options: {
+    ppt: PptOptions;
+}, signal?: AbortSignal, deps?: PptDeps): Promise<PptActionResult>;
+/** check 的完整结果（含锚点落盘校验）。 */
+export interface DeckCheck {
+    readonly result: CheckResult;
+    readonly anchorIssues: readonly SlideIssue[];
+    readonly text: string;
+}
+/** `action=check`：对已有 `07-答辩/PPT.md` 做确定性质量检查。 */
+export declare function runCheckAction(fs: FileSystem, root: string, args: PptArgs, signal?: AbortSignal): Promise<DeckCheck>;
+/** convert 的文本摘要（有界）。 */
+export declare function convertSummary(slidesRel: string, pptxRel: string, notesRel: string, detection: EngineDetection, engine: PptOptions['engine'], result: ConversionResult | undefined, error: string | undefined): string;
+/** `action=convert`：执行外部转换；失败时**先写说明再抛错**（绝不假装成功）。 */
+export declare function runConvertAction(fs: FileSystem, root: string, options: {
+    ppt: PptOptions;
+}, signal?: AbortSignal, deps?: PptDeps): Promise<PptActionResult>;
+/** `action=guide`：只输出可复制执行的转换指引，不写盘、不执行。 */
+export declare function runGuideAction(deps?: PptDeps): PptActionResult;
+/**
+ * 按 action 分发。`convert` 失败时抛出的错误里**带上已经写好的说明**，
+ * 让模型看到的是一次真实失败 + 下一步命令，而不是沉默。
+ */
+export declare function runPptAction(fs: FileSystem, cwd: string | undefined, args: PptArgs, options: {
+    ppt: PptOptions;
+}, signal?: AbortSignal, deps?: PptDeps): Promise<PptActionResult>;