dsh-thesis 1.0.0

package/lib/intake/spec.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 意图规格：把追问状态渲染成给人和模型共读的 Markdown（默认 `00-管理/意图规格.md`）。
+ *
+ * 两个不可妥协的性质：
+ * 1. **幂等**：`renderSpec` 是状态的纯函数——同样状态渲染两次逐字节一致，
+ *    因此「每次回答后自动刷新规格」不会产生无意义的 diff。文档里不写渲染时间
+ *    （时间只留在 `.paper/intake.json`），只写内容哈希作为版本指纹。
+ * 2. **未知即阻塞**：必答项未答、格式不合格、被跳过的，都显式列进「阻塞项」一节。
+ *    规格里不允许出现沉默的空白——后续写作/构建/降重/答辩只能依据本文件，
+ *    所以"没写"必须等于"看得见的缺口"。
+ *
+ * 来源标注只有三种：`用户回答` / `材料推断（待确认）` / `未知（需补）`。
+ *
+ * @module dsh-thesis/intake
+ */
+import { type AnswerCheck, type IntakeContext, type IntakeQuestion } from './questions.ts';
+import { type IntakeIo, type IntakeState } from './state.ts';
+/** 来源标注：规格阅读者一眼看出这条信息可不可信。 */
+export declare const SOURCE_USER = "\u7528\u6237\u56DE\u7B54";
+/**
+ * 材料推断、但用户还没点头：字面量必须避开闸门的关键词。
+ *
+ * `intake/gate-rules.ts` 把 `待确认` 当作「规格未立稳」的标记，所以这里用
+ * 「材料推断（未确认）」——**规格收敛完成后文档里不得再出现该标记**，
+ * 否则入口闸门会永远认为规格没立稳（详见 spec 的幂等测试）。
+ */
+export declare const SOURCE_MATERIALS_PENDING = "\u6750\u6599\u63A8\u65AD\uFF08\u672A\u786E\u8BA4\uFF09";
+export declare const SOURCE_MATERIALS = "\u6750\u6599\u63A8\u65AD";
+/** 必答项没答：这是阻塞项，闸门就是靠这个字面量识别「规格没立稳」。 */
+export declare const SOURCE_UNKNOWN = "\u672A\u77E5\uFF08\u9700\u8865\uFF09";
+/** 非必答项没答：标注清楚，但不阻塞收敛（否则规格永远立不稳）。 */
+export declare const SOURCE_OPTIONAL_OPEN = "\u672A\u7B54\uFF08\u975E\u963B\u585E\uFF09";
+/** 一条状态在规格里的呈现形态。 */
+export interface SpecLine {
+    readonly question: IntakeQuestion;
+    readonly source: string;
+    readonly value: string;
+    readonly note?: string;
+}
+/** 该问题当前的来源标注与取值。 */
+export declare function specLine(state: IntakeState, q: IntakeQuestion): SpecLine;
+/** 阻塞项：必答但未齐全（未答 / 格式不合格）的问题。 */
+export declare function blockers(state: IntakeState): IntakeQuestion[];
+/** 规格内容指纹：前 12 位，用于回答「这份文档对应哪一版状态」。 */
+export declare function specFingerprint(state: IntakeState): string;
+/**
+ * 渲染意图规格全文（纯函数、幂等）。
+ *
+ * 结构：文档说明 → 进度摘要 → 阻塞项 → 六个分节（每节一张问答表 + 未答清单）
+ * → 附录（本轮已完成问答留痕）。
+ */
+export declare function renderSpec(state: IntakeState, ctx: IntakeContext): string;
+/** 规格渲染结果的摘要（工具返回值用）。 */
+export interface SpecWriteResult {
+    readonly path: string;
+    readonly absPath: string;
+    readonly blockerIds: string[];
+    readonly bytes: number;
+}
+/**
+ * 渲染并原子落盘规格。返回相对路径与阻塞项 id，便于工具直接回报「还缺什么」。
+ * 中途失败会抛错（不吞）：规格是最新真相，写不进去必须让用户知道。
+ */
+export declare function writeSpec(io: IntakeIo, root: string, state: IntakeState, ctx: IntakeContext): Promise<SpecWriteResult>;
+/** 供工具层复用的校验调用：问题没有 `validate` 时视为通过。 */
+export declare function checkAnswer(q: IntakeQuestion, answer: string): AnswerCheck;

package/lib/intake/spec.js

@@ -0,0 +1,221 @@
+/**
+ * 意图规格：把追问状态渲染成给人和模型共读的 Markdown（默认 `00-管理/意图规格.md`）。
+ *
+ * 两个不可妥协的性质：
+ * 1. **幂等**：`renderSpec` 是状态的纯函数——同样状态渲染两次逐字节一致，
+ *    因此「每次回答后自动刷新规格」不会产生无意义的 diff。文档里不写渲染时间
+ *    （时间只留在 `.paper/intake.json`），只写内容哈希作为版本指纹。
+ * 2. **未知即阻塞**：必答项未答、格式不合格、被跳过的，都显式列进「阻塞项」一节。
+ *    规格里不允许出现沉默的空白——后续写作/构建/降重/答辩只能依据本文件，
+ *    所以"没写"必须等于"看得见的缺口"。
+ *
+ * 来源标注只有三种：`用户回答` / `材料推断（待确认）` / `未知（需补）`。
+ *
+ * @module dsh-thesis/intake
+ */
+import * as nodePath from 'node:path';
+import { createHash } from 'node:crypto';
+import { blockingRequired, listRequired, materialInsight, questionById, QUESTIONS, INTAKE_SECTIONS, } from "./questions.js";
+import { writeAtomic } from "./state.js";
+/** 来源标注：规格阅读者一眼看出这条信息可不可信。 */
+export const SOURCE_USER = '用户回答';
+/**
+ * 材料推断、但用户还没点头：字面量必须避开闸门的关键词。
+ *
+ * `intake/gate-rules.ts` 把 `待确认` 当作「规格未立稳」的标记，所以这里用
+ * 「材料推断（未确认）」——**规格收敛完成后文档里不得再出现该标记**，
+ * 否则入口闸门会永远认为规格没立稳（详见 spec 的幂等测试）。
+ */
+export const SOURCE_MATERIALS_PENDING = '材料推断（未确认）';
+export const SOURCE_MATERIALS = '材料推断';
+/** 必答项没答：这是阻塞项，闸门就是靠这个字面量识别「规格没立稳」。 */
+export const SOURCE_UNKNOWN = '未知（需补）';
+/** 非必答项没答：标注清楚，但不阻塞收敛（否则规格永远立不稳）。 */
+export const SOURCE_OPTIONAL_OPEN = '未答（非阻塞）';
+function isBlank(value) {
+    return value.trim() === '';
+}
+/** 该问题当前的来源标注与取值。 */
+export function specLine(state, q) {
+    const rec = state.answers[q.id];
+    if (rec === undefined) {
+        const skipped = state.skipped.includes(q.id);
+        const why = state.skipReasons[q.id];
+        return {
+            question: q,
+            // 必答项没答 = 阻塞（用闸门识别的「未知」标记）；非必答项没答不阻塞收敛。
+            source: q.required ? SOURCE_UNKNOWN : SOURCE_OPTIONAL_OPEN,
+            value: skipped ? `（已跳过：${why === undefined || why === '' ? '未给理由' : why}）` : '（尚未回答）',
+        };
+    }
+    const line = {
+        question: q,
+        source: rec.source === 'materials'
+            ? (rec.confirmed ? SOURCE_MATERIALS : SOURCE_MATERIALS_PENDING)
+            : SOURCE_USER,
+        // 值里可能出现换行：统一压成单行，保证表格/列表不会被撑破。
+        value: rec.value.replace(/\s*\n+\s*/g, '；'),
+    };
+    if (rec.note !== undefined && rec.note !== '')
+        line.note = rec.note;
+    return line;
+}
+/** 阻塞项：必答但未齐全（未答 / 格式不合格）的问题。 */
+export function blockers(state) {
+    return blockingRequired(state);
+}
+/** 规格内容指纹：前 12 位，用于回答「这份文档对应哪一版状态」。 */
+export function specFingerprint(state) {
+    const canonical = listRequired()
+        .map(q => `${q.id}=${state.answers[q.id]?.value ?? ''}`)
+        .join('\u0000');
+    const digest = createHash('sha256').update(canonical).digest('hex');
+    return digest.slice(0, 12);
+}
+function sourceOf(state, q) {
+    return specLine(state, q).source;
+}
+/**
+ * 渲染意图规格全文（纯函数、幂等）。
+ *
+ * 结构：文档说明 → 进度摘要 → 阻塞项 → 六个分节（每节一张问答表 + 未答清单）
+ * → 附录（本轮已完成问答留痕）。
+ */
+export function renderSpec(state, ctx) {
+    const insight = materialInsight(ctx.materials);
+    const pending = blockers(state);
+    const required = listRequired();
+    const answeredRequired = required.filter(q => state.answers[q.id] !== undefined && state.answers[q.id]?.valid !== false);
+    const L = [];
+    L.push('# 意图规格');
+    L.push('');
+    L.push('<!-- dsh-thesis:intake-spec');
+    L.push(`fingerprint: ${specFingerprint(state)}`);
+    L.push(`specPath: ${state.specPath}`);
+    L.push('-->');
+    L.push('');
+    L.push('> **这份文档是什么**：材料到手后，由 `thesis_intake` 逐题追问收敛出的"可证伪意图规格"。');
+    L.push('> 它把模糊的口头要求变成能被检查的条款：学校/学位、格式模板、字数、查重、AI 规定、时间线、数据真实性、引用格式、答辩形式。');
+    L.push('>');
+    L.push('> **谁维护**：`thesis_intake` 工具自动重绘——你每回答一个问题，本文件立即刷新。');
+    L.push('> 请不要手工编辑表格：手工改动会在下一次回答时被覆盖。要改答案，就用同一个问题重答一次（`thesis_intake action=answer`）。');
+    L.push('>');
+    L.push('> **怎么用**：后续写作、格式检查、降重、PPT、答辩准备**只依据本文件**。');
+    L.push('> 「来源」列告诉你每条信息的可信度：`用户回答` 是用户亲口确认的；`材料推断（未确认）` 是从材料里读出来、还没得到用户点头的；必答项没答会标成「未知」并进入下一节的阻塞项；非必答项没答标为「未答（非阻塞）」。');
+    L.push('> 「阻塞项」一节非空时不进入下一阶段：先把清单里的问题答完（非必答项可以一直留着，但规格会显示它们没定）。');
+    L.push('');
+    L.push('## 进度摘要');
+    L.push('');
+    L.push(`- 当前阶段：${ctx.stage}`);
+    L.push(`- 追问状态：${state.stage === 'done' ? '✅ 必答项已齐全，可进入下一阶段' : '⏳ 进行中'}`);
+    L.push(`- 必答项：${answeredRequired.length}/${required.length} 已答`);
+    L.push(`- 材料清单：${ctx.materials.found ? `已读取（${ctx.materials.items.length} 项）` : '未找到 00-管理/材料清单.md（未做材料感知）'}`);
+    L.push(`- 已跳过：${state.skipped.length} 项${state.skipped.length > 0 ? `（${state.skipped.join('、')}）` : ''}`);
+    L.push(`- 内容指纹：\`${specFingerprint(state)}\``);
+    L.push('');
+    L.push('## 阻塞项（未答不可进入下一阶段）');
+    L.push('');
+    if (pending.length === 0) {
+        L.push('无。全部必答项已齐全。');
+    }
+    else {
+        L.push('| 问题 id | 分节 | 缺什么 | 影响产出 |');
+        L.push('|---|---|---|---|');
+        for (const q of pending) {
+            const rec = state.answers[q.id];
+            let missing;
+            if (rec === undefined) {
+                missing = state.skipped.includes(q.id) ? `已跳过：${state.skipReasons[q.id] ?? '未给理由'}` : '尚未回答';
+            }
+            else {
+                missing = `格式待修正：${rec.note ?? '校验未通过'}`;
+            }
+            L.push(`| \`${q.id}\` | ${q.section} | ${missing} | ${q.affects.join('、')} |`);
+        }
+        L.push('');
+        L.push('> 补法：`thesis_intake` 的 `action=answer` 逐题作答；确实无法回答的用 `action=skip` 并给理由，但在 `done` 之前它们仍是阻塞项。');
+    }
+    L.push('');
+    for (const section of INTAKE_SECTIONS) {
+        const qs = QUESTIONS.filter(q => q.section === section);
+        L.push(`## ${section}`);
+        L.push('');
+        if (qs.length === 0) {
+            L.push('（本节暂无问题）');
+            L.push('');
+            continue;
+        }
+        L.push('| 问题 | 结论 | 来源 | 备注 |');
+        L.push('|---|---|---|---|');
+        for (const q of qs) {
+            const line = specLine(state, q);
+            const note = line.note !== undefined
+                ? line.note
+                : (insight.suppress.has(q.id) ? '已由材料覆盖，未重复提问' : '');
+            L.push(`| ${q.ask} | ${line.value} | ${line.source} | ${note} |`);
+        }
+        L.push('');
+        const unknown = qs.filter(q => isBlank(state.answers[q.id]?.value ?? ''));
+        if (unknown.length > 0) {
+            L.push('未答清单：');
+            for (const q of unknown) {
+                L.push(`- ${q.required ? '**[必答]** ' : ''}\`${q.id}\` ${q.ask}`);
+            }
+            L.push('');
+        }
+    }
+    L.push('## 附：本轮问答留痕');
+    L.push('');
+    const asked = state.askedIds.filter(id => questionById(id) !== undefined);
+    if (asked.length === 0) {
+        L.push('（还没有问过任何问题）');
+    }
+    else {
+        L.push('| 顺序 | 问题 id | 来源 | 时间 | 校验 |');
+        L.push('|---|---|---|---|---|');
+        asked.forEach((id, i) => {
+            const q = questionById(id);
+            if (q === undefined)
+                return;
+            const rec = state.answers[id];
+            const source = rec === undefined ? '—（未答/已跳过）' : sourceOf(state, q);
+            const at = rec?.at ?? '—';
+            const check = rec === undefined ? '—' : (rec.valid === false ? `⚠️ ${rec.note ?? '未通过'}` : '✅');
+            L.push(`| ${i + 1} | \`${id}\` | ${source} | ${at} | ${check} |`);
+        });
+    }
+    L.push('');
+    L.push('---');
+    L.push('');
+    L.push('本文件由 `dsh-thesis` 的 `thesis_intake` 工具生成并维护；机器真相在 `.paper/intake.json`。');
+    L.push('');
+    return L.join('\n');
+}
+/**
+ * 渲染并原子落盘规格。返回相对路径与阻塞项 id，便于工具直接回报「还缺什么」。
+ * 中途失败会抛错（不吞）：规格是最新真相，写不进去必须让用户知道。
+ */
+export async function writeSpec(io, root, state, ctx) {
+    const rel = state.specPath === '' ? nodePath.join('00-管理', '意图规格.md') : state.specPath;
+    const abs = nodePath.join(root, rel);
+    const md = renderSpec(state, ctx);
+    await writeAtomic(io, abs, md);
+    return {
+        path: rel,
+        absPath: abs,
+        blockerIds: blockers(state).map(q => q.id),
+        bytes: md.length,
+    };
+}
+/** 供工具层复用的校验调用：问题没有 `validate` 时视为通过。 */
+export function checkAnswer(q, answer) {
+    if (q.validate === undefined)
+        return { ok: true };
+    try {
+        return q.validate(answer);
+    }
+    catch (error) {
+        // 校验函数本身出错不应打断对话：记为"未通过"并说明原因。
+        return { ok: false, note: `校验过程出错（${error instanceof Error ? error.message : String(error)}），请人工核对。` };
+    }
+}

package/lib/intake/state.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 追问状态的落盘与读取：`.paper/intake.json`（相对论文工作区根）。
+ *
+ * 三条硬规则：
+ * 1. **原子写**：先写同目录临时文件，再改名覆盖目标。中途断电只会留下一个
+ *    可识别的临时文件，绝不会把状态写成半截 JSON。改名走可注入的
+ *    {@link IntakeIo.rename} 接口——真机上是 `node:fs/promises` 的 rename，
+ *    测试里是内存实现，两条路径都必须走通。
+ * 2. **损坏时报错，不静默重置**：JSON 解析失败、版本不符、结构不对，一律抛出
+ *    带文件路径与修复建议的中文错误。悄悄重置会丢掉用户已经答过的每一个问题，
+ *    这比报错严重得多。
+ * 3. **断点续问**：状态是唯一的真相来源，新会话读回它就能从正确的问题继续。
+ *
+ * @module dsh-thesis/intake
+ */
+import type { MaterialSummary } from './questions.ts';
+/** 状态文件相对论文工作区根的路径。 */
+export declare const STATE_REL = ".paper/intake.json";
+/** 状态 schema 版本；结构不兼容变更时必须递增（旧状态将明确报错而非被猜读）。 */
+export declare const STATE_VERSION = 1;
+/** 追问阶段：`asking` 进行中；`done` 必答项已齐、可进入下一阶段。 */
+export type IntakeStage = 'asking' | 'done';
+/** 合法阶段集合（状态迁移校验用）。 */
+export declare const INTAKE_STAGES: readonly IntakeStage[];
+/** 一条答案的来源：用户亲口答的，还是材料推断出来的。 */
+export type AnswerSource = 'user' | 'materials';
+/** 一条已记录的答案。 */
+export interface IntakeAnswer {
+    value: string;
+    /** 记录时刻（ISO 字符串）。 */
+    at: string;
+    source: AnswerSource;
+    /** 材料推断的答案必须经用户确认才计入必答项。 */
+    confirmed: boolean;
+    /** 轻校验是否通过（缺省视为通过）。 */
+    valid?: boolean;
+    /** 校验提示：格式不对时的具体说明。 */
+    note?: string;
+}
+/** 追问状态：`.paper/intake.json` 的全部内容。 */
+export interface IntakeState {
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    stage: IntakeStage;
+    /**
+     * 本轮追问已经问过的问题 id（含被跳过的）。
+     * 这是 `maxQuestions` 上限的计分依据，也是断点续问的进度标记。
+     */
+    askedIds: string[];
+    answers: Record<string, IntakeAnswer>;
+    skipped: string[];
+    /** 跳过理由：`id → 理由`（`skip` 必须给理由）。 */
+    skipReasons: Record<string, string>;
+    specPath: string;
+}
+/** 建一份全新状态。 */
+export declare function defaultState(now?: Date, specPath?: string): IntakeState;
+/** 稳定序列化：键序固定、2 空格缩进、结尾换行（同样的状态 → 同样的字节）。 */
+export declare function serializeState(state: IntakeState): string;
+/** 状态损坏：带路径与修复建议的可读错误。 */
+export declare class IntakeStateError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+/**
+ * 解析状态文本。任何结构性问题都抛出 {@link IntakeStateError}，
+ * 绝不返回「看起来能用」的默认状态。
+ */
+export declare function parseState(raw: string, path?: string): IntakeState;
+/** 迁移检查结果。 */
+export interface TransitionCheck {
+    readonly ok: boolean;
+    readonly reason: string;
+}
+/**
+ * 校验「把阶段推进到 to」是否被允许。
+ *
+ * 规则：`asking → done` 只能由 `done` 动作在必答项齐全后触发（由调用方保证）；
+ * 已经 `done` 的状态允许重答问题，但不会被自动退回 `asking`——回退必须显式
+ * 重答一个必答项（见 {@link applyAnswer}），避免状态在两次读取间莫名倒退。
+ */
+export declare function canTransition(state: IntakeState, to: IntakeStage): TransitionCheck;
+/** 校验通过后写入阶段；不通过时返回原状态（调用方负责提示原因）。 */
+export declare function setStage(state: IntakeState, to: IntakeStage, now?: Date): TransitionCheck;
+/** 记录一次「已提问」（幂等：重复记同一个 id 不改变状态）。 */
+export declare function markAsked(state: IntakeState, id: string, now?: Date): boolean;
+/**
+ * 写入一条答案。**幂等**：`value` 与原值完全一致时不改动 `at`/`updatedAt`，
+ * 返回 `changed:false`——重复提交同一个答案不会污染历史。
+ */
+export declare function applyAnswer(state: IntakeState, id: string, value: string, opts?: {
+    source?: AnswerSource;
+    confirmed?: boolean;
+    valid?: boolean;
+    note?: string;
+    now?: Date;
+}): {
+    changed: boolean;
+    record: IntakeAnswer;
+};
+/** 记录一次跳过（必须带理由；跳过必答项会让 `done` 拒绝）。 */
+export declare function applySkip(state: IntakeState, id: string, reason: string, now?: Date): void;
+/** 宿主文件系统的最小面（`ctx.fs` 在运行期满足它）。 */
+export interface FileSystemLike {
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        displayPath: string;
+    }>;
+    readText(target: {
+        displayPath: string;
+    }, signal?: AbortSignal): Promise<string>;
+    writeText(target: {
+        displayPath: string;
+    }, content: string, expected?: unknown, signal?: AbortSignal): Promise<unknown>;
+    stat(target: {
+        displayPath: string;
+    }, signal?: AbortSignal): Promise<{
+        isDirectory: boolean;
+        size: number;
+    } | undefined>;
+    listDir(target: {
+        displayPath: string;
+    }, signal?: AbortSignal): Promise<Array<{
+        name: string;
+        isDirectory: boolean;
+    }>>;
+}
+/**
+ * 追问模块用的窄 I/O 接口。
+ *
+ * `rename` 单独抽出来，是为了让「临时文件 + 改名」的原子写在假 fs 下也能走通：
+ * 真机实现用 `node:fs/promises`，测试可注入内存实现或干脆省略（走兜底复制路径）。
+ */
+export interface IntakeIo {
+    read(path: string): Promise<string | undefined>;
+    write(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    listDir(path: string): Promise<string[]>;
+    /** 原子改名的注入点；省略时 {@link writeAtomic} 退化为「写临时文件 → 复制 → 删临时文件」。 */
+    rename?(from: string, to: string): Promise<void>;
+    /** 可选：删掉临时文件；省略时临时文件会留下（不影响正确性）。 */
+    remove?(path: string): Promise<void>;
+}
+/**
+ * 用 `ctx.fs` 拼一个 I/O；默认改名走 `node:fs/promises`（真机路径）。
+ *
+ * **`read` 只把「确认不存在」折叠成 `undefined`**：权限与 IO 错误一律上抛。
+ * 否则调用方会以为状态还没建过，用默认态覆盖掉用户已答的每一个问题
+ * （详见 `shared/fs-errors.ts`）。
+ */
+export declare function fsIo(fs: FileSystemLike, signal?: AbortSignal, rename?: (from: string, to: string) => Promise<void>): IntakeIo;
+/** 真机改名：`node:fs/promises` 的 readFile + writeFile（同一目录内的替换）。 */
+export declare const nodeRename: (from: string, to: string) => Promise<void>;
+/**
+ * 原子写：先写临时文件，再改名覆盖目标。
+ *
+ * 有 `io.rename` 时是真改名；没有时退化为「写临时 → 写目标 → 清临时」。
+ * 任何一步失败都会尽力清掉临时文件，并把错误原样抛给调用方（不吞）。
+ */
+export declare function writeAtomic(io: IntakeIo, path: string, content: string): Promise<void>;
+/** 读取状态；文件不存在返回 `undefined`（由调用方决定是否初始化）。 */
+export declare function loadState(io: IntakeIo, root: string): Promise<IntakeState | undefined>;
+/** 原子落盘状态。 */
+export declare function saveState(io: IntakeIo, root: string, state: IntakeState, now?: Date): Promise<void>;
+/** `thesis_ingest` 的材料清单相对路径。 */
+export declare const MATERIALS_REL = "00-\u7BA1\u7406/\u6750\u6599\u6E05\u5355.md";
+/** 台账相对路径（复用 paper 模块的约定，但不 import 它，避免模块间耦合成环）。 */
+declare const LEDGER_REL = "00-\u7BA1\u7406/\u8FDB\u5EA6\u53F0\u8D26.md";
+/**
+ * 宽容解析材料清单 Markdown。
+ *
+ * 只认「一行的表格里有 `.扩展名` 的单元格」：取该行第一个（剥掉反引号/星号后）
+ * 含扩展名的单元格为路径，其余单元格里第一个非空、非数字的当类型。
+ * 表头、分隔行、段落一律跳过。
+ * 解析不出任何条目时返回空清单——宁可多问一个，也不要凭猜免问。
+ */
+export declare function parseMaterials(md: string): MaterialSummary;
+/** 读材料清单；缺失或为空返回 `{ found:false, items:[] }`。 */
+export declare function loadMaterials(io: IntakeIo, root: string): Promise<MaterialSummary>;
+/**
+ * 从进度台账推断当前阶段名。
+ *
+ * 台账的机器真相是 `<!-- thesis:state ... -->` 里的 `currentStage`（数字），
+ * 这里只做「读到就用、读不到就按开题前」的宽容推断，绝不因为台账异常而中断追问。
+ */
+export declare function stageFromLedger(md: string | undefined): string | undefined;
+/** 读台账并推断阶段（读不到返回 undefined，由 {@link makeContext} 落到默认值）。 */
+export declare function loadStage(io: IntakeIo, root: string): Promise<string | undefined>;
+export { LEDGER_REL };