dsh-thesis 1.0.0

package/lib/dedup/index.js

@@ -0,0 +1,331 @@
+/**
+ * dsh-thesis 降重模块的门面与工具装配。
+ *
+ * 三层结构：
+ * - `normalize.ts`  文本归一化 + 段落切分（带原文偏移映射）
+ * - `similarity.ts` shingle 指纹、倒排索引、包含率/杰卡德/最长公共子串
+ * - `rewrite.ts` / `report.ts` 改写处方与报告渲染
+ *
+ * 本文件只做两件事：把正文段落与参考语料装进扫描器；注册 `thesis_originality` 工具
+ * 并把报告落到 `08-合规/降重报告.md`（verify 另写 `08-合规/降重报告-复测.md`）。
+ *
+ * **边界**：不做知网/维普等收费系统的接入（无授权，也不应接入）。
+ * 本地相似度只是字符串重合度估算，权威口径是学校检测结果，可回填到报告里。
+ *
+ * @module dsh-thesis/dedup
+ */
+import * as nodePath from 'node:path';
+import { bulletList, definePaperTool, sessionCwd, textOutput } from "../shared/index.js";
+import { CHAPTER_META, isWrittenChapter } from "../paper/lib/layout.js";
+import { findThesisRoot } from "../paper/lib/project.js";
+import { dedupCommand } from "./commands.js";
+import { segmentsFromText } from "./normalize.js";
+import { scan } from "./similarity.js";
+import { buildReport, parseBaseline, renderReport, renderVerifyReport, verifyDelta, weightedRateOf, } from "./report.js";
+export const REPORT_REL = '08-合规/降重报告.md';
+export const VERIFY_REPORT_REL = '08-合规/降重报告-复测.md';
+export const CHAPTERS_REL = '06-论文/章节';
+/** 缺省参考语料目录（相对论文工作区根）。 */
+export const DEFAULT_CORPUS_DIRS = [
+    '02-文献/笔记',
+    '05-实验测试/结果',
+    '00-管理/材料',
+];
+/** 参与比对的文件扩展名。 */
+const CORPUS_EXTENSIONS = ['.md', '.txt', '.tex', '.csv'];
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+function scanOptionsFor(similarity) {
+    return { shingle: similarity.shingle, threshold: similarity.threshold };
+}
+/**
+ * 读取目录下（不递归子目录）参与比对的文本文件；目录不存在返回空数组。
+ */
+async function readDirFiles(fs, root, relDir, signal) {
+    const entries = await listDirSafe(fs, nodePath.join(root, relDir), signal);
+    const files = [];
+    const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of sorted) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const rel = `${relDir}/${entry.name}`;
+        if (entry.isDirectory) {
+            const nested = await readDirFiles(fs, root, rel, signal);
+            for (const file of nested)
+                files.push(file);
+            continue;
+        }
+        if (!CORPUS_EXTENSIONS.some(ext => entry.name.toLowerCase().endsWith(ext)))
+            continue;
+        const text = await readTextSafe(fs, nodePath.join(root, rel), signal);
+        if (text === null)
+            continue;
+        files.push({ file: rel, label: rel, text });
+    }
+    return files;
+}
+async function listDirSafe(fs, abs, signal) {
+    try {
+        return await fs.listDir(await fs.resolve(abs, { signal }), signal);
+    }
+    catch {
+        return [];
+    }
+}
+async function readTextSafe(fs, abs, signal) {
+    try {
+        return await fs.readText(await fs.resolve(abs, { signal }), signal);
+    }
+    catch {
+        return null;
+    }
+}
+/** 收集参考语料：显式路径优先，否则用缺省目录 + 各章正文（互查）。 */
+export async function collectCorpus(fs, root, corpusArg, excludeFiles, wholeChapters, signal) {
+    const exclude = new Set(excludeFiles.map(toPosix));
+    const found = [];
+    const push = (file) => {
+        if (exclude.has(toPosix(file.file)))
+            return;
+        if (found.some(existing => existing.file === file.file))
+            return;
+        found.push(file);
+    };
+    if (corpusArg !== undefined && corpusArg.trim() !== '') {
+        for (const raw of corpusArg.split(/[;,]/)) {
+            const entry = raw.trim();
+            if (entry === '')
+                continue;
+            const abs = nodePath.isAbsolute(entry) ? entry : nodePath.join(root, entry);
+            const text = await readTextSafe(fs, abs, signal);
+            if (text !== null) {
+                const rel = toPosix(nodePath.isAbsolute(entry) ? nodePath.basename(entry) : entry);
+                push({ file: rel, label: rel, text });
+                continue;
+            }
+            const relDir = toPosix(nodePath.isAbsolute(entry) ? nodePath.basename(entry) : entry);
+            const files = await readDirFiles(fs, root, relDir, signal);
+            for (const file of files)
+                push(file);
+        }
+        return found;
+    }
+    for (const dir of DEFAULT_CORPUS_DIRS) {
+        const files = await readDirFiles(fs, root, dir, signal);
+        for (const file of files)
+            push(file);
+    }
+    // 正文互查：其他章整章作为语料（本段所在章由 excludeFiles/自比屏蔽排除）。
+    if (wholeChapters) {
+        for (const meta of CHAPTER_META) {
+            const rel = `${CHAPTERS_REL}/${meta.file}.md`;
+            if (exclude.has(rel))
+                continue;
+            const text = await readTextSafe(fs, nodePath.join(root, rel), signal);
+            if (text === null)
+                continue;
+            push({ file: rel, label: `${meta.file}（正文互查）`, text });
+        }
+    }
+    return found;
+}
+/** 读取正文段落（按章切分；chapter 为空则全部已撰写章）。 */
+export async function loadChapterSegments(fs, root, chapter, minChars, signal) {
+    const wanted = chapter === undefined ? undefined : (chapter.endsWith('.md') ? chapter.slice(0, -3) : chapter);
+    const segments = [];
+    const missing = [];
+    const corpusCandidates = [];
+    for (const [index, meta] of CHAPTER_META.entries()) {
+        if (wanted !== undefined && meta.file !== wanted)
+            continue;
+        const rel = `${CHAPTERS_REL}/${meta.file}.md`;
+        const text = await readTextSafe(fs, nodePath.join(root, rel), signal);
+        if (text === null || !isWrittenChapter(text, index + 1, meta)) {
+            missing.push(meta.file);
+            continue;
+        }
+        corpusCandidates.push({ file: rel, label: `${meta.file}（正文互查）`, text });
+        const split = segmentsFromText(text, { file: rel, chapter: meta.file, minChars });
+        for (const segment of split.segments)
+            segments.push(segment);
+    }
+    return { segments, missing, corpusCandidates };
+}
+async function runScan(fs, root, args, similarity, now, detected, signal) {
+    const loaded = await loadChapterSegments(fs, root, args.chapter, similarity.minChars, signal);
+    const explicitCorpus = args.corpus !== undefined && args.corpus.trim() !== '';
+    // 本次已作为正文扫描的章不再进语料：与"自己所在的那一章"比较是自比，不是重复。
+    const corpusFiles = await collectCorpus(fs, root, args.corpus, loaded.corpusCandidates.map(file => file.file), !explicitCorpus, signal);
+    const scanResult = scan({
+        segments: loaded.segments,
+        corpus: corpusFiles.map(file => ({ id: file.file, label: file.label, text: file.text })),
+        options: scanOptionsFor(similarity),
+    });
+    const options = {
+        threshold: similarity.threshold,
+        shingle: similarity.shingle,
+        minChars: similarity.minChars,
+        now,
+        corpusLabels: corpusFiles.length === 0 ? ['（无语料，仅统计段落）'] : corpusFiles.map(file => file.file),
+        ...(detected !== undefined ? { detected } : {}),
+    };
+    const report = buildReport(scanResult, options);
+    return {
+        scanResult,
+        report,
+        markdown: renderReport(report, options),
+        options,
+        missing: loaded.missing,
+        corpusLabels: options.corpusLabels ?? [],
+    };
+}
+function summaryLines(outcome, target, extra) {
+    const { scanResult, report } = outcome;
+    const top = report.risks.slice(0, 5);
+    const lines = [];
+    lines.push(`文件数：${new Set(outcome.scanResult.items.map(item => item.segment.file)).size} 个正文文件（正文段落 ${scanResult.paragraphCount} 段，语料 ${scanResult.corpusCount} 份）`);
+    lines.push(`分级：high ${scanResult.high} 段 | medium ${scanResult.medium} 段 | low ${scanResult.low} 段（有命中 ${scanResult.matchedCount} 段）`);
+    lines.push(`全文加权重复率估算：${(weightedRateOf(scanResult) * 100).toFixed(1)}%（口径见报告第 0 节；非学校检测结果）`);
+    lines.push('');
+    lines.push('Top 5 高风险段落：');
+    if (top.length === 0) {
+        lines.push('- 无中/高风险段落');
+    }
+    else {
+        lines.push(bulletList(top.map((risk, index) => `${index + 1}. ${risk.chapter} 第 ${risk.lineStart}-${risk.lineEnd} 行：${(risk.score * 100).toFixed(1)}% ← ${risk.source}`)));
+    }
+    lines.push('');
+    lines.push('下一步建议：');
+    lines.push(bulletList([
+        '先改高风险段落：按处方换结构（拆句/换语序/主被动），必须保留数字、单位、引用标记与代码标识符',
+        '命中来源是文献笔记时，改为直接引用 + [n] 标注，不要改写成自己的话',
+        '改写完成后执行 thesis_originality action=verify（baseline 传本次报告路径）复测降幅',
+        '送检后把真实重复率回填：thesis_originality action=report detected_rate=<百分比>',
+    ], '- '));
+    if (extra.length > 0) {
+        lines.push('');
+        for (const line of extra)
+            lines.push(line);
+    }
+    lines.push('');
+    lines.push(`报告已写入：${target}（每次覆盖，含时间戳与算法参数）`);
+    return lines;
+}
+async function writeReport(fs, root, rel, content, signal) {
+    await fs.writeText(await fs.resolve(nodePath.join(root, rel), { signal }), content, undefined, signal);
+}
+/** 执行 thesis_originality 的全部动作；返回有界文本摘要。 */
+export async function runDedup(fs, cwd, args, similarity, signal) {
+    // action 必填：缺省/空串**不静默当成 scan**——那会在用户只想看报告时意外跑一次全量扫描并覆盖报告。
+    const action = (args.action ?? '').trim();
+    if (action === '') {
+        throw new Error('action 必填：scan（首次扫描并落盘）| verify（对 baseline 复测降幅）| report（生成/回填检测结果）。');
+    }
+    if (!['scan', 'verify', 'report'].includes(action)) {
+        throw new Error(`未知 action：${action}（只支持 scan | verify | report）。`);
+    }
+    const root = await findThesisRoot(fs, cwd, signal);
+    if (root === null)
+        throw new Error('未找到论文工作区。请先在论文仓库目录内操作。');
+    const now = new Date();
+    const detected = detectedFrom(args);
+    const missingNote = (missing) => missing.length === 0 ? [] : [`⚠ 未撰写/缺失章节未计入：${missing.join('、')}`];
+    if (action === 'verify') {
+        const current = await runScan(fs, root, args, similarity, now, detected, signal);
+        const baselineRel = args.baseline !== undefined && args.baseline.trim() !== '' ? args.baseline.trim() : REPORT_REL;
+        const baselineText = await readTextSafe(fs, nodePath.isAbsolute(baselineRel) ? baselineRel : nodePath.join(root, baselineRel), signal);
+        if (baselineText === null) {
+            throw new Error(`未找到 baseline 报告：${baselineRel}。请先执行 thesis_originality action=scan 生成 ${REPORT_REL}。`);
+        }
+        const baseline = parseBaseline(baselineText);
+        if (baseline === null) {
+            throw new Error(`baseline 报告无法解析（${baselineRel}）。baseline 必须是 thesis_originality scan 生成的降重报告。`);
+        }
+        const currentSnapshot = {
+            paragraphCount: current.scanResult.paragraphCount,
+            matchedCount: current.scanResult.matchedCount,
+            high: current.scanResult.high,
+            medium: current.scanResult.medium,
+            weightedRate: weightedRateOf(current.scanResult),
+        };
+        const delta = verifyDelta(baseline, currentSnapshot);
+        await writeReport(fs, root, REPORT_REL, current.markdown, signal);
+        await writeReport(fs, root, VERIFY_REPORT_REL, renderVerifyReport(delta, current.options, current.report), signal);
+        const head = [
+            `复测完成：加权重复率估算 ${(delta.baseline.weightedRate * 100).toFixed(1)}% → ${(delta.current.weightedRate * 100).toFixed(1)}%`,
+            `降幅：${(delta.rateDrop * 100).toFixed(1)} 个百分点（相对 ${(delta.rateDropRatio * 100).toFixed(1)}%）`,
+            `高风险 ${delta.baseline.high} → ${delta.current.high} 段；中风险 ${delta.baseline.medium} → ${delta.current.medium} 段`,
+            `结论：${delta.verdict}`,
+            '',
+        ];
+        return [
+            ...head,
+            ...summaryLines(current, `${VERIFY_REPORT_REL}（并覆盖 ${REPORT_REL}）`, missingNote(current.missing)),
+        ].join('\n');
+    }
+    if (action !== 'scan' && action !== 'report') {
+        throw new Error(`未知 action：${action}（只支持 scan | verify | report）`);
+    }
+    const outcome = await runScan(fs, root, args, similarity, now, detected, signal);
+    await writeReport(fs, root, REPORT_REL, outcome.markdown, signal);
+    const head = [];
+    if (outcome.scanResult.paragraphCount === 0) {
+        head.push('⚠ 没有可比对的正文段落：章节未撰写或全部段落短于 minChars。');
+        head.push('');
+    }
+    if (outcome.scanResult.corpusCount === 0) {
+        head.push('⚠ 参考语料为空：请把可能的来源文本放进 02-文献/笔记、05-实验测试/结果 或 00-管理/材料，或用 corpus 参数显式指定。');
+        head.push('');
+    }
+    return [
+        ...head,
+        ...summaryLines(outcome, REPORT_REL, missingNote(outcome.missing)),
+    ].join('\n');
+}
+function detectedFrom(args) {
+    const rate = args.detected_rate;
+    if (rate === undefined || !Number.isFinite(rate))
+        return undefined;
+    const detected = { rate: rate > 1 ? rate / 100 : rate };
+    const withSystem = args.detected_system === undefined ? detected : { ...detected, system: args.detected_system };
+    return withSystem;
+}
+/**
+ * 注册 `thesis_originality`：本地相似度扫描 / 复测 / 报告回填。
+ *
+ * 参数：`action`（scan | verify | report）、`corpus`（参考语料路径，文件或目录）、
+ * `chapter`（只处理某一章）、`baseline`（verify 的上次报告路径）、
+ * `detected_rate`（report 回填的学校检测重复率）、`detected_system`。
+ * 落盘：`08-合规/降重报告.md`；verify 另写 `08-合规/降重报告-复测.md`。
+ */
+export function registerDedup(ctx, options) {
+    ctx.tools.register(definePaperTool({
+        name: 'thesis_originality',
+        description: '原创性自查（本地、确定性、零依赖、不联网）：把正文段落与参考语料做 shingle 指纹比对，'
+            + '给出每段的包含率得分、命中来源、命中片段（行号与原文）、结构化改写处方与全文加权重复率估算，'
+            + '报告写入 08-合规/降重报告.md。'
+            + 'action=scan 首次扫描；verify 用 baseline 报告复测降幅（另写 08-合规/降重报告-复测.md）；'
+            + 'report 把用户自行送检得到的重复率回填进报告。'
+            + '缺省语料为 02-文献/笔记、05-实验测试/结果、00-管理/材料 + 正文各章互查；corpus 可显式指定文件或目录。'
+            + '**本工具不接入知网/维普等收费查重系统**：本地结果是字符串重合度估算，权威口径是学校检测结果。',
+        parameters: {
+            action: { type: 'string', required: true, description: 'scan（扫描并落盘）| verify（对 baseline 复测降幅）| report（生成/回填学校检测结果）' },
+            corpus: { type: 'string', description: '参考语料路径（文件或目录，可多个用逗号分隔）；缺省用 02-文献/笔记、05-实验测试/结果、00-管理/材料 + 正文各章互查' },
+            chapter: { type: 'string', description: '只处理某一章，如 01-绪论（可带 .md）' },
+            baseline: { type: 'string', description: 'verify 用：上一次 scan 落盘的报告路径，缺省 08-合规/降重报告.md' },
+            detected_rate: { type: 'number', description: 'report 用：用户自行送检得到的重复率（0.12 或 12 均可，>1 视为百分数）' },
+            detected_system: { type: 'string', description: 'report 用：检测系统名称，如「知网 PMLC」' },
+        },
+        output: textOutput(),
+        async execute(rawArgs, exec) {
+            return await runDedup(ctx.fs, sessionCwd(exec), rawArgs, options.similarity, exec.signal);
+        },
+    }));
+    // `/thesis-originality [scan|verify|report] [语料路径] [--chapter 01-绪论]`：与工具同一执行层，
+    // 命令只是给人用的快捷入口（命令名只允许 [a-z][a-z0-9_-]*）。
+    if (ctx.commands !== undefined) {
+        ctx.commands.register(dedupCommand(ctx.fs, options.similarity));
+    }
+}
+export { segmentsFromText, scan, buildReport, renderReport, weightedRateOf };

package/lib/dedup/normalize.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 降重模块的文本归一化与切分（确定性，无第三方依赖）。
+ *
+ * 两件事：
+ * 1. **归一化**：全角/半角统一（NFKC 的常用子集）、去 Markdown 标记与空白标点、
+ *    中文按字切分、拉丁按词切分（统一小写）。归一化后每个字符都带一条
+ *    「原文偏移」记录，使任何命中都能回到原始行号与原文片段。
+ * 2. **段落切分**：按空行与 Markdown 结构切段，标题行/代码块/公式行/
+ *    参考文献条目/表格行/引用块不算正文重复；短于 `minChars` 的段落跳过。
+ *
+ * 归一化与偏移必须一一对应：{@link NormalizedText.chars} 的第 i 个字符来自
+ * {@link NormalizedText.tokens} 中某个 token 的第 j 个字符，而该 token 记录了
+ * 它在**原文**中的起止偏移（`[start, end)`）。
+ *
+ * @module dsh-thesis/dedup
+ */
+/** 单个词元：`text` 是归一化后的小写形式，`[start, end)` 是它在原文中的区间。 */
+export interface NormalizedToken {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** 归一化后的单个字符及其原文偏移（token 边界会打断连续区间）。 */
+export interface NormalizedChar {
+    readonly ch: string;
+    readonly offset: number;
+    /** 该字符是否是新 token 的第一个字符（用于按词重建，而不是按字）。 */
+    readonly tokenStart: boolean;
+    readonly breakBefore: boolean;
+}
+export interface NormalizedText {
+    readonly text: string;
+    readonly tokens: readonly NormalizedToken[];
+    readonly chars: readonly NormalizedChar[];
+}
+/** 正文段落：归一化结果 + 它在原文件里的位置与原文。 */
+export interface Segment {
+    /** 来源文件（相对论文工作区根，POSIX 分隔符）。 */
+    readonly file: string;
+    /** 章名（文件基名去掉 .md）；非章节语料等于 file。 */
+    readonly chapter: string;
+    /** 段落起始行（1 基，闭区间）。 */
+    readonly lineStart: number;
+    /** 段落结束行（1 基，闭区间）。 */
+    readonly lineEnd: number;
+    /**
+     * 段落原文（全文行拼接，保留 Markdown 标记与全角标点，用于展示与处方）。
+     * 只做换行统一，字符偏移与原文一致。
+     */
+    readonly raw: string;
+    /** 归一化输入（全角→半角之后的整篇文本）；所有偏移相对它计算。 */
+    readonly text: string;
+    /** 归一化结果。 */
+    readonly doc: NormalizedText;
+}
+export interface SegmentOptions {
+    /** 参与比对的最短段落长度（归一化字符数）。 */
+    readonly minChars: number;
+}
+/**
+ * 全角 → 半角、常见中文标点 → ASCII、统一大小写与换行符。
+ * 除 BOM（丢弃）与 CRLF（合并为一个 `\n`）外逐字符等长替换，
+ * 因此行号与原文字符偏移都保持可对应。
+ */
+export declare function toHalfWidth(input: string): string;
+/** 标题行：`# 标题`。 */
+export declare function isHeadingLine(line: string): boolean;
+/** 围栏代码块：``` 或 ~~~（≥3 个）。 */
+export declare function isCodeFence(line: string): boolean;
+/** 缩进代码块（4 空格 / 1 个制表符开头）。 */
+export declare function isIndentedCode(line: string): boolean;
+/** 独立公式行：`$$...$$`、`\begin{...}` 环境，或整行基本由数学符号构成。 */
+export declare function isFormulaLine(line: string): boolean;
+/** 图片行、水平分割线、HTML 注释行。 */
+export declare function isStructuralLine(line: string): boolean;
+/** 表格行。 */
+export declare function isTableLine(line: string): boolean;
+/** 引用块行（以 `>` 开头的说明性文字）。 */
+export declare function isQuoteLine(line: string): boolean;
+/** 列表项行（提纲/清单，不是连续论述）。 */
+export declare function isListItemLine(line: string): boolean;
+/** 参考文献标题（`## 参考文献` / `# References` 等）。 */
+export declare function isReferenceHeading(line: string): boolean;
+/** 参考文献条目行：`[1] 作者. 题名. 期刊, 年.` */
+export declare function isReferenceEntry(line: string): boolean;
+/** 模板脚手架提示行（`（写作要求：...）`、`（待补）` 等）。 */
+export declare function isPlaceholderLine(line: string): boolean;
+/** 该行是否属于「不构成正文重复」的结构行（不含空行判断）。 */
+export declare function isSkippedLine(line: string): boolean;
+/**
+ * 归一化一段文本，并记录每个归一化字符的原文偏移。
+ *
+ * 保留中文、拉丁词（含数字与下划线）与独立数字；标点、空白、Markdown 标记
+ * 全部丢弃 —— 字符级过滤不会破坏偏移映射（字符是逐个追加的）。
+ */
+export declare function normalizeText(text: string): NormalizedText;
+/**
+ * 把归一化字符区间 `[from, to)` 映射回**原文**的字符区间。
+ * 返回闭开区间 `{ start, end }`；空区间返回 `null`。
+ */
+export declare function offsetsFor(doc: NormalizedText, from: number, to: number): {
+    start: number;
+    end: number;
+} | null;
+/** 原文区间 `[start, end)` 的文本（越界自动截断）。 */
+export declare function sliceRaw(raw: string, start: number, end: number): string;
+/** 原始文本中某个字符偏移对应的 1 基行号。 */
+export declare function lineAt(raw: string, offset: number): number;
+/**
+ * 按空行与 Markdown 结构切段。
+ *
+ * 规则（全部确定性）：
+ * - 围栏代码块（``` 之间）、标题行、公式行、表格行、引用块、列表项行、
+ *   参考文献条目/文献区、模板占位行，一律**不参与**比对；
+ * - 连续的非跳过行合并为一个段落，段落边界在空行或跳过行处断开；
+ * - 归一化后不足 `minChars` 个字符的段落跳过（返回 `skipped` 便于解释原因）。
+ */
+export declare function segmentsFromText(text: string, options: {
+    file: string;
+    chapter?: string;
+    minChars: number;
+}): {
+    segments: Segment[];
+    skippedShort: number;
+};