dsh-thesis 1.0.0

package/lib/paper/tools/build.js

@@ -0,0 +1,166 @@
+/**
+ * thesis_build：产出论文 docx（+ 可选 pdf）。
+ *
+ * 引擎选择：
+ * - pandoc 存在时优先（--reference-doc 使用学校模板）；
+ * - 无 pandoc 时使用内置零依赖转换器（lib/docx.ts），并在构建说明中
+ *   显式标注"内置过渡引擎，非学校模板排版"。
+ *
+ * 二进制例外（文档化）：ctx.fs 无二进制写入能力，docx/pdf 字节由本工具
+ * 通过 node:fs 直接写入论文仓库 06-论文/产出/ 目录。文本工作全部走 ctx.fs。
+ */
+import * as nodePath from 'node:path';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { describeFailure, spawnCommand } from "../../shared/spawn.js";
+import { buildDocx } from "../lib/docx.js";
+import { CHAPTER_META, isWrittenChapter } from "../lib/layout.js";
+import { parseLedger } from "../lib/ledger.js";
+import { findThesisRoot } from "../lib/project.js";
+const OUT_DIR = '06-论文/产出';
+const TEMPLATE_DIR = '06-论文/assets/学校模板';
+async function readOptional(fs, absPath, signal) {
+    try {
+        return await fs.readText(await fs.resolve(absPath, { signal }), signal);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function listOptional(fs, absPath, signal) {
+    try {
+        const entries = await fs.listDir(await fs.resolve(absPath, { signal }), signal);
+        return entries.map(e => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+function pandocAvailable() {
+    return spawnCommand('pandoc', ['--version'], { timeoutMs: PROBE_TIMEOUT_MS }).ok;
+}
+/** 引擎探测的超时（毫秒）：探测不该拖住工具调用。 */
+const PROBE_TIMEOUT_MS = 10_000;
+/** 单次 pandoc 转换的超时（毫秒）：大型论文 + 模板可能慢，但必须有上限。 */
+const CONVERT_TIMEOUT_MS = 120_000;
+export async function runBuild(fs, args, cwd, signal, writeBinary) {
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null)
+        throw new Error('未找到论文工作区。请先在论文仓库目录内操作。');
+    const format = args.format ?? 'docx';
+    if (format === 'pdf' && (args.engine ?? 'auto') === 'internal') {
+        throw new Error('内置引擎只能产出 docx。PDF 需要 pandoc（并安装 LaTeX 引擎）。');
+    }
+    // 章节收集（按模板顺序；只收录"已撰写"章节）
+    const chapterParts = [];
+    const included = [];
+    const missing = [];
+    for (const [index, meta] of CHAPTER_META.entries()) {
+        const text = await readOptional(fs, nodePath.join(root, '06-论文/章节', `${meta.file}.md`), signal);
+        if (text === undefined || !isWrittenChapter(text, index + 1, meta)) {
+            missing.push(meta.file);
+            continue;
+        }
+        included.push(meta.file);
+        chapterParts.push(text);
+    }
+    if (included.length === 0)
+        throw new Error('没有任何已撰写章节（06-论文/章节/*.md 均为空）。');
+    // 标题：台账 state.title，缺省通用
+    let title = '本科毕业论文（设计）';
+    const ledgerText = await readOptional(fs, nodePath.join(root, '00-管理/进度台账.md'), signal);
+    if (ledgerText !== undefined) {
+        const parsed = parseLedger(ledgerText);
+        if (parsed.found && parsed.state.title !== undefined && parsed.state.title !== '')
+            title = parsed.state.title;
+    }
+    const markdown = chapterParts.join('\n\n');
+    // 模板探测
+    const templateFiles = await listOptional(fs, nodePath.join(root, TEMPLATE_DIR), signal);
+    const template = templateFiles.find(f => /\.(docx?|dotx?)$/i.test(f));
+    // 引擎选择
+    const requested = args.engine ?? 'auto';
+    const hasPandoc = pandocAvailable();
+    let engine;
+    if (requested === 'pandoc') {
+        if (!hasPandoc)
+            throw new Error('请求 pandoc 引擎但本机未安装 pandoc。请安装 pandoc 或改用 internal 引擎。');
+        engine = 'pandoc';
+    }
+    else if (requested === 'internal') {
+        engine = 'internal';
+    }
+    else {
+        engine = hasPandoc ? 'pandoc' : 'internal';
+    }
+    // docx 字节
+    const docxPath = nodePath.join(root, OUT_DIR, '论文.docx');
+    let docxBytes;
+    if (engine === 'internal') {
+        docxBytes = buildDocx({ title, markdown });
+    }
+    else {
+        // pandoc：合并内容写临时文件后转换
+        const tmpMd = nodePath.join(tmpdir(), `dsh-thesis-build-${process.pid}-${Date.now()}.md`);
+        await writeFile(tmpMd, `${title}\n\n${'='.repeat(Math.max(4, title.length))}\n\n${markdown}`, 'utf8');
+        try {
+            const argv = ['-f', 'markdown', '-t', 'docx', '-o', docxPath];
+            if (template !== undefined)
+                argv.push('--reference-doc', nodePath.join(root, TEMPLATE_DIR, template));
+            argv.push(tmpMd);
+            const result = spawnCommand('pandoc', argv, { timeoutMs: CONVERT_TIMEOUT_MS });
+            if (!result.ok)
+                throw new Error(`pandoc 转换失败：${describeFailure('pandoc', result)}`);
+            docxBytes = new Uint8Array(await readFile(docxPath));
+        }
+        finally {
+            await rm(tmpMd, { force: true }).catch(() => { });
+        }
+    }
+    await writeBinary(docxPath, docxBytes);
+    // pdf（仅 pandoc）
+    let pdfPath;
+    if (format === 'pdf' || format === 'both') {
+        if (engine !== 'pandoc')
+            throw new Error('PDF 需要 pandoc。');
+        const out = nodePath.join(root, OUT_DIR, '论文.pdf');
+        const tmpMd = nodePath.join(tmpdir(), `dsh-thesis-build-${process.pid}-${Date.now()}.md`);
+        await writeFile(tmpMd, `${title}\n\n${'='.repeat(Math.max(4, title.length))}\n\n${markdown}`, 'utf8');
+        try {
+            const result = spawnCommand('pandoc', ['-f', 'markdown', '-t', 'pdf', '-o', out, tmpMd], { timeoutMs: CONVERT_TIMEOUT_MS });
+            if (!result.ok)
+                throw new Error(`PDF 转换失败（通常缺 LaTeX 引擎）：${describeFailure('pandoc', result)}`);
+            pdfPath = out;
+        }
+        finally {
+            await rm(tmpMd, { force: true }).catch(() => { });
+        }
+    }
+    // 构建说明（文本，走 ctx.fs）
+    const note = [
+        '# 构建说明',
+        '',
+        `- 时间：${new Date().toISOString()}`,
+        `- 引擎：${engine === 'pandoc' ? 'pandoc' : '内置过渡引擎（非学校模板排版）'}`,
+        `- 学校模板：${template ?? '未发现（请将学校模板放入 06-论文/assets/学校模板/ 后重建）'}`,
+        `- 收录章节：${included.join('、') || '无'}`,
+        `- 未收录章节（空或缺失）：${missing.join('、') || '无'}`,
+        `- 产物：论文.docx${pdfPath !== undefined ? '、论文.pdf' : ''}`,
+        '',
+    ].join('\n');
+    await fs.writeText(await fs.resolve(nodePath.join(root, OUT_DIR, '构建说明.md'), { signal }), note, undefined, signal);
+    return { docxPath, ...(pdfPath !== undefined ? { pdfPath } : {}), engine, template, chapters: included, missing };
+}
+export function buildSummary(outcome) {
+    const lines = [
+        `构建完成：${outcome.docxPath}`,
+        ...(outcome.pdfPath !== undefined ? [`PDF：${outcome.pdfPath}`] : []),
+        `- 引擎：${outcome.engine === 'pandoc' ? 'pandoc' : '内置过渡引擎（非学校模板排版，提交前请获取学校模板后用 pandoc 重建）'}`,
+        `- 学校模板：${outcome.template ?? '未发现'}`,
+        `- 收录章节：${outcome.chapters.join('、')}`,
+        ...(outcome.missing.length > 0 ? [`- 未收录（空/缺失）：${outcome.missing.join('、')}`] : []),
+        '',
+        '打开 论文.docx 检查排版；构建细节见 06-论文/产出/构建说明.md。',
+    ];
+    return lines.join('\n');
+}

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

@@ -0,0 +1,7 @@
+/**
+ * thesis_check：全文综合检查（五项），产出两份报告：
+ * - 08-合规/引用检查报告/检查-<date>.md（引用双向一致）
+ * - 08-合规/格式检查报告/检查-<date>.md（字数/图表/术语/模板）
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+export declare function runCheck(fs: FileSystem, cwd: string | undefined, signal?: AbortSignal): Promise<string>;

package/lib/paper/tools/check.js

@@ -0,0 +1,79 @@
+/**
+ * thesis_check：全文综合检查（五项），产出两份报告：
+ * - 08-合规/引用检查报告/检查-<date>.md（引用双向一致）
+ * - 08-合规/格式检查报告/检查-<date>.md（字数/图表/术语/模板）
+ */
+import * as nodePath from 'node:path';
+import { runGlobalCheck, renderCheckReport } from "../lib/check.js";
+import { CHAPTER_META, isWrittenChapter } from "../lib/layout.js";
+import { REFS_BIB_REL } from "../lib/lit-cache.js";
+import { findThesisRoot } from "../lib/project.js";
+export async function runCheck(fs, cwd, signal) {
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null)
+        throw new Error('未找到论文工作区。请先在论文仓库目录内操作。');
+    // 章节收集（只检查"已撰写"章节，脚手架列入未撰写清单）
+    const chapters = [];
+    const missing = [];
+    for (const [index, meta] of CHAPTER_META.entries()) {
+        let text;
+        try {
+            text = await fs.readText(await fs.resolve(nodePath.join(root, '06-论文/章节', `${meta.file}.md`), { signal }), signal);
+        }
+        catch {
+            text = undefined;
+        }
+        if (text === undefined || !isWrittenChapter(text, index + 1, meta)) {
+            missing.push(meta.file);
+            continue;
+        }
+        chapters.push({ name: meta.file, no: index + 1, text });
+    }
+    let bibText = '';
+    try {
+        bibText = await fs.readText(await fs.resolve(nodePath.join(root, REFS_BIB_REL), { signal }), signal);
+    }
+    catch {
+        // 文献库缺失：引用检查会如实报告。
+    }
+    let templateFiles = [];
+    try {
+        const entries = await fs.listDir(await fs.resolve(nodePath.join(root, '06-论文/assets/学校模板'), { signal }), signal);
+        templateFiles = entries.map(e => e.name);
+    }
+    catch {
+        // 目录缺失：模板检查会报告。
+    }
+    const report = runGlobalCheck({ chapters, bibText, templateFiles });
+    const date = new Date().toISOString().slice(0, 10);
+    // 引用检查报告
+    const citationSection = report.sections.find(s => s.id === 'citations');
+    const citationReport = [
+        `# 引用检查报告（${date}）`,
+        '',
+        '> 由 thesis_check 自动生成。检查：正文引用 ↔ refs.bib 双向一致。',
+        '',
+        `## ${citationSection.title}`,
+        '',
+        ...citationSection.lines,
+        '',
+    ].join('\n');
+    await fs.writeText(await fs.resolve(nodePath.join(root, '08-合规/引用检查报告', `检查-${date}.md`), { signal }), citationReport, undefined, signal);
+    // 格式检查报告
+    const formatSections = report.sections.filter(s => s.id !== 'citations');
+    const formatReport = [
+        `# 格式检查报告（${date}）`,
+        '',
+        '> 由 thesis_check 自动生成。检查：字数、图/表编号、术语定义顺序、学校模板。',
+        '',
+        ...(missing.length > 0 ? [`⚠ 未撰写章节：${missing.join('、')}（不计入检查）。`, ''] : []),
+        ...formatSections.flatMap(section => [`## ${section.title}`, '', ...section.lines, '']),
+    ].join('\n');
+    await fs.writeText(await fs.resolve(nodePath.join(root, '08-合规/格式检查报告', `检查-${date}.md`), { signal }), formatReport, undefined, signal);
+    return [
+        ...(missing.length > 0 ? [`⚠ 未撰写章节：${missing.join('、')}（不计入检查）。`, ''] : []),
+        renderCheckReport(report),
+        '',
+        `报告已写入：08-合规/引用检查报告/检查-${date}.md、08-合规/格式检查报告/检查-${date}.md`,
+    ].join('\n');
+}

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

@@ -0,0 +1,13 @@
+/**
+ * thesis_decide：决定日志追加（00-管理/决定日志.md）。
+ *
+ * 决定日志是答辩留痕的核心证据：每个关键决定记录内容、理由、备选。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+export interface DecisionArgs {
+    title?: string;
+    content: string;
+    reason?: string;
+    alternatives?: string;
+}
+export declare function runDecision(fs: FileSystem, args: DecisionArgs, cwd: string | undefined, signal?: AbortSignal): Promise<string>;

package/lib/paper/tools/decision.js

@@ -0,0 +1,53 @@
+/**
+ * thesis_decide：决定日志追加（00-管理/决定日志.md）。
+ *
+ * 决定日志是答辩留痕的核心证据：每个关键决定记录内容、理由、备选。
+ */
+import * as nodePath from 'node:path';
+import { describeReadFailure, isMissingError } from "../../shared/fs-errors.js";
+import { appendDecision, countDecisions } from "../lib/ledger.js";
+import { DECISION_REL, findThesisRoot } from "../lib/project.js";
+const DECISION_HEADER = `# 决定日志
+
+> 每个关键决定的留痕：内容、理由、备选。答辩时它是"我为什么这么写"的证据。
+> 由 thesis_decide 工具或 /thesis-decide 命令追加。
+
+`;
+function deriveTitle(content) {
+    const firstLine = content.split('\n')[0].trim();
+    const base = firstLine.length > 0 ? firstLine : '未命名决定';
+    return base.length > 24 ? `${base.slice(0, 24)}…` : base;
+}
+export async function runDecision(fs, args, cwd, signal) {
+    if (args.content === undefined || args.content.trim() === '') {
+        throw new Error('content 必填：决定的实际内容。');
+    }
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null) {
+        throw new Error('未找到论文工作区（向上查找 00-管理/进度台账.md 失败）。请先用 thesis_init 创建工作区，或在论文仓库目录内操作。');
+    }
+    const path = nodePath.join(root, DECISION_REL);
+    let raw;
+    try {
+        raw = await fs.readText(await fs.resolve(path, { signal }), signal);
+    }
+    catch (error) {
+        // 只有「确实还没有决定日志」才用表头开始：读失败时若继续，会把已有的决定全部覆盖掉。
+        if (!isMissingError(error)) {
+            throw new Error(describeReadFailure('决定日志（00-管理/决定日志.md）', path, error, signal));
+        }
+        raw = DECISION_HEADER;
+    }
+    if (raw.trim() === '')
+        raw = DECISION_HEADER;
+    const entry = {
+        date: new Date().toISOString().slice(0, 10),
+        title: args.title?.trim() || deriveTitle(args.content),
+        content: args.content.trim(),
+        ...(args.reason?.trim() ? { reason: args.reason.trim() } : {}),
+        ...(args.alternatives?.trim() ? { alternatives: args.alternatives.trim() } : {}),
+    };
+    const next = appendDecision(raw, entry);
+    await fs.writeText(await fs.resolve(path, { signal }), next, undefined, signal);
+    return `已记录决定 #${countDecisions(next)}「${entry.title}」（${entry.date}）。决定日志：${path}`;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * thesis_defense：提取答辩素材 + 生成预答辩问题库骨架。
+ *
+ * 产出（写入 07-答辩/）：
+ * - 答辩素材.md —— 课题/章节概览/技术选型/关键决定/测试数据/git 工作量/文献
+ * - 预答辩问题库.md —— 六类必问问题模板 + 证据锚点
+ * 具体问题生成与模拟问答由 AI（依据素材）与用户完成，流程见技能 thesis-defense。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import { type GitRunner } from '../lib/defense.ts';
+export declare function runDefensePrep(fs: FileSystem, cwd: string | undefined, signal: AbortSignal | undefined, gitRunner?: GitRunner): Promise<string>;

package/lib/paper/tools/defense.js

@@ -0,0 +1,74 @@
+/**
+ * thesis_defense：提取答辩素材 + 生成预答辩问题库骨架。
+ *
+ * 产出（写入 07-答辩/）：
+ * - 答辩素材.md —— 课题/章节概览/技术选型/关键决定/测试数据/git 工作量/文献
+ * - 预答辩问题库.md —— 六类必问问题模板 + 证据锚点
+ * 具体问题生成与模拟问答由 AI（依据素材）与用户完成，流程见技能 thesis-defense。
+ */
+import * as nodePath from 'node:path';
+import { parseBibKeysOrdered } from "../lib/bibtex.js";
+import { countTestCases, extractDecisionTitles, extractHeadings, extractTechChoices, renderDefenseMaterials, renderQuestionBank, spawnGitStats, } from "../lib/defense.js";
+import { CHAPTER_META, isWrittenChapter } from "../lib/layout.js";
+import { parseLedger } from "../lib/ledger.js";
+import { findThesisRoot } from "../lib/project.js";
+export async function runDefensePrep(fs, cwd, signal, gitRunner = spawnGitStats) {
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null)
+        throw new Error('未找到论文工作区。请先在论文仓库目录内操作。');
+    const rootDir = root;
+    async function readOptional(rel) {
+        try {
+            return await fs.readText(await fs.resolve(nodePath.join(rootDir, rel), { signal }), signal);
+        }
+        catch {
+            return '';
+        }
+    }
+    let title = '本科毕业论文（设计）';
+    const ledger = parseLedger(await readOptional('00-管理/进度台账.md'));
+    if (ledger.found && ledger.state.title !== undefined && ledger.state.title !== '')
+        title = ledger.state.title;
+    // 章节概览（只统计已撰写章节）
+    const chapters = [];
+    for (const [index, meta] of CHAPTER_META.entries()) {
+        const text = await readOptional(nodePath.join('06-论文/章节', `${meta.file}.md`));
+        if (!isWrittenChapter(text, index + 1, meta))
+            continue;
+        chapters.push({
+            name: meta.file,
+            no: index + 1,
+            title: meta.title,
+            cjk: (text.match(/[\u4e00-\u9fff]/g) ?? []).length,
+            headings: extractHeadings(text),
+            citations: (text.match(/\[\d+(?:[-,，]\d+)*\]/g) ?? []).length,
+        });
+    }
+    const techChoices = extractTechChoices(await readOptional('03-设计/技术选型论证.md'));
+    const decisions = extractDecisionTitles(await readOptional('00-管理/决定日志.md'));
+    const testCases = countTestCases(await readOptional('05-实验测试/测试计划.md'));
+    let resultFiles = [];
+    try {
+        const entries = await fs.listDir(await fs.resolve(nodePath.join(root, '05-实验测试/结果'), { signal }), signal);
+        resultFiles = entries.map(e => e.name).filter(n => !n.startsWith('.'));
+    }
+    catch {
+        // 结果目录缺失：素材里如实提示。
+    }
+    const bibCount = parseBibKeysOrdered(await readOptional('02-文献/refs.bib')).length;
+    const git = gitRunner(root);
+    const materials = renderDefenseMaterials({ title, chapters, techChoices, decisions, testCases, resultFiles, bibCount, git });
+    const questions = renderQuestionBank(title);
+    await fs.writeText(await fs.resolve(nodePath.join(root, '07-答辩/答辩素材.md'), { signal }), materials, undefined, signal);
+    await fs.writeText(await fs.resolve(nodePath.join(root, '07-答辩/预答辩问题库.md'), { signal }), questions, undefined, signal);
+    return [
+        `答辩素材与问题库已生成：`,
+        `- 07-答辩/答辩素材.md（课题"${title}"；已撰写 ${chapters.length} 章；技术选型 ${techChoices.length} 项；决定 ${decisions.length} 条；测试用例 ${testCases} 个；git ${git.ok ? `${git.commits} 次提交` : '统计不可用'}）`,
+        `- 07-答辩/预答辩问题库.md（六类 ${questions.match(/- \[ \]/g)?.length ?? 0} 个问题骨架）`,
+        '',
+        '下一步（流程见技能 thesis-defense）：',
+        '1. AI 依据《答辩素材》把问题库的 <> 占位替换为你的系统实际名称，生成 15-20 个具体问题',
+        '2. 你逐题回答，答不上的回对应材料补学；至少完整演练 2 轮，第 2 轮随机抽题',
+        '3. 演练完成后更新 07-答辩/问答演练.md，并用 thesis_progress 推进阶段 9 任务',
+    ].join('\n');
+}

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

@@ -0,0 +1,23 @@
+/**
+ * thesis_init：一键生成论文工作区（DESIGN.md §5 目录结构 + 技能包 + git 初始化）。
+ *
+ * 校验规则：
+ * - root 必须是绝对路径；
+ * - 目标目录存在且非空时拒绝（除非 force），绝不覆盖已有文件。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+export interface InitArgs {
+    root: string;
+    title?: string;
+    git?: boolean;
+    force?: boolean;
+}
+export interface InitOutcome {
+    readonly root: string;
+    readonly files: number;
+    readonly skills: number;
+    readonly git: 'ok' | 'skipped' | 'failed';
+    readonly gitDetail?: string;
+}
+export declare function runInit(fs: FileSystem, args: InitArgs, skillsDir: string, signal?: AbortSignal): Promise<InitOutcome>;
+export declare function initSummary(outcome: InitOutcome): string;

package/lib/paper/tools/init.js

@@ -0,0 +1,99 @@
+/**
+ * thesis_init：一键生成论文工作区（DESIGN.md §5 目录结构 + 技能包 + git 初始化）。
+ *
+ * 校验规则：
+ * - root 必须是绝对路径；
+ * - 目标目录存在且非空时拒绝（除非 force），绝不覆盖已有文件。
+ */
+import * as nodePath from 'node:path';
+import { readFile, readdir } from 'node:fs/promises';
+import { describeFailure, spawnCommand } from "../../shared/spawn.js";
+import { buildLayout } from "../lib/layout.js";
+async function dirEntries(fs, dir) {
+    try {
+        const target = await fs.resolve(dir);
+        const entries = await fs.listDir(target);
+        return entries.map(e => e.name);
+    }
+    catch {
+        return null;
+    }
+}
+async function copySkills(fs, skillsDir, root) {
+    let count = 0;
+    let names = [];
+    try {
+        names = await readdir(skillsDir);
+    }
+    catch {
+        return count;
+    }
+    for (const name of names) {
+        if (!/^[a-z0-9-]+$/.test(name))
+            continue;
+        try {
+            const body = await readFile(nodePath.join(skillsDir, name, 'SKILL.md'), 'utf8');
+            const target = await fs.resolve(nodePath.join(root, '.dsh', 'skills', name, 'SKILL.md'));
+            await fs.writeText(target, body);
+            count += 1;
+        }
+        catch {
+            // 该目录不是技能包，跳过。
+        }
+    }
+    return count;
+}
+function initGit(root) {
+    const init = spawnCommand('git', ['init', '-q'], { cwd: root });
+    if (!init.ok)
+        return { git: 'failed', gitDetail: describeFailure('git init', init) };
+    const add = spawnCommand('git', ['add', '-A'], { cwd: root });
+    if (!add.ok)
+        return { git: 'failed', gitDetail: describeFailure('git add', add) };
+    const commit = spawnCommand('git', ['-c', 'user.name=dsh-thesis', '-c', 'user.email=dsh-thesis@local', 'commit', '-q', '-m', 'chore: dsh-thesis 初始化论文工作区'], { cwd: root });
+    if (!commit.ok)
+        return { git: 'failed', gitDetail: describeFailure('git commit', commit) };
+    return { git: 'ok' };
+}
+export async function runInit(fs, args, skillsDir, signal) {
+    if (args.root === undefined || args.root.trim() === '') {
+        throw new Error('root 参数必填：论文工作区根目录的绝对路径。');
+    }
+    if (!nodePath.isAbsolute(args.root)) {
+        throw new Error(`root 必须是绝对路径，收到：${args.root}。`);
+    }
+    const root = nodePath.normalize(args.root);
+    const existing = await dirEntries(fs, root);
+    if (existing !== null && existing.length > 0 && args.force !== true) {
+        throw new Error(`目录 ${root} 非空（已有 ${existing.length} 项）。为避免覆盖数据，请选择空目录或新目录；确认要写入现有目录请设 force: true（不会覆盖同名文件，仍会失败于冲突）。`);
+    }
+    const now = new Date();
+    const date = now.toISOString().slice(0, 10);
+    const title = args.title?.trim() || '本科毕业设计';
+    const files = buildLayout({ title, date });
+    let written = 0;
+    for (const file of files) {
+        const target = await fs.resolve(nodePath.join(root, file.path), { signal });
+        await fs.writeText(target, file.content, undefined, signal);
+        written += 1;
+    }
+    const skills = await copySkills(fs, skillsDir, root);
+    const gitResult = args.git === false ? { git: 'skipped' } : initGit(root);
+    return { root, files: written, skills, ...gitResult };
+}
+export function initSummary(outcome) {
+    const lines = [
+        `论文工作区已创建：${outcome.root}`,
+        `- 模板文件：${outcome.files} 个（含目录结构、进度台账、决定日志、章节模板）`,
+        `- 技能包：${outcome.skills} 个（.dsh/skills/，随仓库版本化）`,
+    ];
+    if (outcome.git === 'ok')
+        lines.push('- git：已初始化并完成首次提交');
+    else if (outcome.git === 'skipped')
+        lines.push('- git：按请求跳过初始化');
+    else
+        lines.push(`- git：初始化失败（${outcome.gitDetail ?? '未知原因'}），请手动执行 git init`);
+    lines.push('');
+    lines.push('下一步：让 AI 运行"选题工作坊"（thesis-opener 技能），从阶段 1 开始。');
+    return lines.join('\n');
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 文献三工具：thesis_lit_search / thesis_lit_save / thesis_lit_note。
+ *
+ * 机制保证"零假文献"：
+ * - search 只返回真实 API 检索结果，并把结果写入检索缓存（.lit-cache.json）；
+ * - save 只接受缓存中的记录 id，元数据零转述，写 refs.bib 并留审计行；
+ * - note 基于缓存或 refs.bib 生成笔记骨架。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import { LIT_SOURCES, type FetchLike, type LitSource } from '../lib/lit-api.ts';
+export interface LitSearchArgs {
+    query: string;
+    year_from?: number;
+    limit?: number;
+    source?: LitSource;
+}
+export interface LitSaveArgs {
+    ids: string[];
+}
+export interface LitNoteArgs {
+    ref: string;
+    force?: boolean;
+}
+export declare function runLitSearch(fs: FileSystem, args: LitSearchArgs, cwd: string | undefined, signal: AbortSignal | undefined, fetchImpl: FetchLike): Promise<string>;
+export declare function runLitSave(fs: FileSystem, args: LitSaveArgs, cwd: string | undefined, signal?: AbortSignal): Promise<string>;
+export declare function runLitNote(fs: FileSystem, args: LitNoteArgs, cwd: string | undefined, signal?: AbortSignal): Promise<string>;
+export { LIT_SOURCES };