dsh-thesis 1.0.0

package/lib/paper/lib/lit-api.js

@@ -0,0 +1,296 @@
+/**
+ * 真实学术文献检索：四个免费来源 + 失败降级链。
+ *
+ * 来源（均无需 API key）：
+ * 1. Semantic Scholar Graph API  https://api.semanticscholar.org/graph/v1/paper/search
+ * 2. DBLP                         https://dblp.org/search/publ/api
+ * 3. arXiv                        https://export.arxiv.org/api/query（Atom XML）
+ * 4. Crossref                     https://api.crossref.org/works
+ *
+ * 红线（DESIGN 最高标准之一）：论文引用只能来自这里的真实检索结果。
+ * 本模块不产出任何"凭记忆生成"的文献记录。
+ */
+import { createHash } from 'node:crypto';
+import { isAbortError } from "../../shared/fs-errors.js";
+const DEFAULT_FETCH = (url, init) => fetch(url, init);
+const MAX_RESULTS = 20;
+const REQUEST_TIMEOUT_MS = 15000;
+function timedFetch(fetchImpl, url, outerSignal) {
+    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    const signal = outerSignal === undefined ? timeout : AbortSignal.any([outerSignal, timeout]);
+    return fetchImpl(url, { signal });
+}
+async function json(fetchImpl, url, outerSignal) {
+    const res = await timedFetch(fetchImpl, url, outerSignal);
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+}
+// ---------------------------------------------------------------------------
+// 通用小工具
+// ---------------------------------------------------------------------------
+function decodeEntities(text) {
+    return text
+        .replaceAll('&', '&')
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&quot;', '"')
+        .replaceAll('&#39;', "'")
+        .replaceAll('&apos;', "'")
+        .replace(/&#(\d+);/g, (_m, d) => String.fromCodePoint(Number(d)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_m, h) => String.fromCodePoint(Number.parseInt(h, 16)));
+}
+function stripTags(text) {
+    // 先解码实体（&lt;em&gt; → <em>），再剥标签，最后再解码一次（处理剥标签后残留的实体）。
+    const decoded = decodeEntities(text);
+    return decodeEntities(decoded.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim());
+}
+function classifyVenue(venue, hasArxivId) {
+    const v = venue.toLowerCase();
+    if (/journal|transactions|review|letters|magazine|quarterly|acta|annals/.test(v))
+        return 'article';
+    if (/conference|symposium|workshop|proceedings|meeting|congress/.test(v))
+        return 'inproceedings';
+    if (hasArxivId)
+        return 'misc';
+    return 'article';
+}
+function cleanAbstract(raw, max = 600) {
+    if (raw === undefined)
+        return undefined;
+    const text = stripTags(raw).trim();
+    if (text === '')
+        return undefined;
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+function normalizeTitle(raw) {
+    return stripTags(raw ?? '').replace(/\s+/g, ' ').trim();
+}
+async function searchSemanticScholar(fetchImpl, opts) {
+    const limit = Math.min(opts.limit ?? 10, MAX_RESULTS);
+    const params = new URLSearchParams({ query: opts.query, limit: String(limit), fields: 'title,authors,year,venue,abstract,url,citationCount,externalIds' });
+    if (opts.yearFrom !== undefined)
+        params.set('year', `${opts.yearFrom}-`);
+    const body = await json(fetchImpl, `https://api.semanticscholar.org/graph/v1/paper/search?${params}`, opts.signal);
+    return (body.data ?? []).flatMap(item => {
+        const hasArxiv = item.externalIds?.ArXiv !== undefined;
+        const title = normalizeTitle(item.title);
+        if (title === '')
+            return [];
+        const abstract = cleanAbstract(item.abstract ?? undefined);
+        return [{
+                id: makeId(item.externalIds?.DOI, item.url ?? (hasArxiv ? `https://arxiv.org/abs/${item.externalIds.ArXiv}` : undefined), title),
+                title,
+                authors: (item.authors ?? []).map(a => a.name).filter((n) => n !== undefined && n !== ''),
+                year: item.year ?? null,
+                venue: item.venue ?? '',
+                type: classifyVenue(item.venue ?? '', hasArxiv),
+                ...(item.externalIds?.DOI !== undefined ? { doi: item.externalIds.DOI } : {}),
+                ...(item.url !== undefined ? { url: item.url } : {}),
+                ...(abstract !== undefined ? { abstract } : {}),
+                ...(item.citationCount !== undefined ? { citationCount: item.citationCount } : {}),
+                source: 'semantic-scholar',
+            }];
+    });
+}
+function dblpAuthors(raw) {
+    if (raw === undefined)
+        return [];
+    const list = Array.isArray(raw) ? raw : [raw];
+    return list.map(a => {
+        if (typeof a === 'string')
+            return a;
+        if (a !== null && typeof a === 'object' && 'text' in a && typeof a.text === 'string') {
+            return a.text;
+        }
+        return '';
+    }).filter(n => n !== '' && !/^\d{4}(-\d{4}){0,3}$/.test(n.trim()));
+}
+async function searchDblp(fetchImpl, opts) {
+    const limit = Math.min(opts.limit ?? 10, MAX_RESULTS);
+    const params = new URLSearchParams({ q: opts.query, format: 'json', h: String(limit) });
+    const body = await json(fetchImpl, `https://dblp.org/search/publ/api?${params}`, opts.signal);
+    const hits = body.result?.hits?.hit;
+    const list = hits === undefined ? [] : Array.isArray(hits) ? hits : [hits];
+    return list.map(hit => {
+        const info = hit.info ?? {};
+        const title = normalizeTitle(info.title);
+        const year = typeof info.year === 'number' ? info.year : (info.year !== undefined ? Number.parseInt(String(info.year), 10) : Number.NaN);
+        const venue = info.venue ?? '';
+        // CoRR / arXiv 是预印本，即使 DBLP 按期刊条目收录也标为 misc。
+        const isPreprint = /coRR|arxiv/i.test(venue);
+        const typeMap = {
+            'Conference and Workshop Papers': 'inproceedings',
+            'Journal Articles': 'article',
+            'Books and Theses': 'book',
+        };
+        const type = isPreprint ? 'misc' : (typeMap[info.type ?? ''] ?? (info.doi !== undefined ? 'article' : 'inproceedings'));
+        const url = info.ee ?? info.url;
+        return {
+            id: makeId(info.doi, url, title),
+            title,
+            authors: dblpAuthors(info.authors?.author),
+            year: Number.isNaN(year) ? null : year,
+            venue,
+            type,
+            ...(info.doi !== undefined ? { doi: info.doi } : {}),
+            ...(url !== undefined ? { url } : {}),
+            source: 'dblp',
+        };
+    }).filter(r => r.title !== '');
+}
+// ---------------------------------------------------------------------------
+// 3. arXiv（Atom XML，最小解析器 + fixtures 测试）
+// ---------------------------------------------------------------------------
+function parseArxivAtom(xml) {
+    const entries = [];
+    const entryBlocks = xml.split('<entry').slice(1);
+    for (const block of entryBlocks) {
+        const grab = (tag) => {
+            const m = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`).exec(block);
+            return m?.[1] === undefined ? undefined : decodeEntities(stripTags(m[1]));
+        };
+        const title = grab('title');
+        if (title === undefined || title === '')
+            continue;
+        const idText = grab('id');
+        const arxivId = idText?.split('/abs/').pop()?.replace(/v\d+$/, '') ?? '';
+        const doiText = grab('doi');
+        const published = grab('published') ?? '';
+        const names = [...block.matchAll(/<name>([\s\S]*?)<\/name>/g)].map(m => decodeEntities(m[1]?.trim() ?? ''))
+            .filter(n => n !== '');
+        entries.push({
+            title,
+            summary: grab('summary') ?? '',
+            authors: names,
+            arxivId,
+            ...(doiText !== undefined && doiText !== '' ? { doi: doiText } : {}),
+            published,
+        });
+    }
+    return entries;
+}
+async function searchArxiv(fetchImpl, opts) {
+    const limit = Math.min(opts.limit ?? 10, MAX_RESULTS);
+    const query = `all:${encodeURIComponent(opts.query)}`;
+    const url = `https://export.arxiv.org/api/query?search_query=${query}&start=0&max_results=${limit}`;
+    const res = await timedFetch(fetchImpl, url, opts.signal);
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    const xml = await res.text();
+    return parseArxivAtom(xml).flatMap(entry => {
+        const yearRaw = Number.parseInt(entry.published.slice(0, 4), 10);
+        const year = Number.isNaN(yearRaw) ? null : yearRaw;
+        if (opts.yearFrom !== undefined && year !== null && year < opts.yearFrom)
+            return [];
+        const absUrl = `https://arxiv.org/abs/${entry.arxivId}`;
+        const abstract = cleanAbstract(entry.summary);
+        return [{
+                id: makeId(entry.doi, absUrl, entry.title),
+                title: entry.title,
+                authors: entry.authors,
+                year,
+                venue: 'arXiv preprint',
+                type: 'misc',
+                ...(entry.doi !== undefined ? { doi: entry.doi } : {}),
+                url: absUrl,
+                ...(abstract !== undefined ? { abstract } : {}),
+                source: 'arxiv',
+            }];
+    });
+}
+async function searchCrossref(fetchImpl, opts) {
+    const limit = Math.min(opts.limit ?? 10, MAX_RESULTS);
+    const params = new URLSearchParams({ query: opts.query, rows: String(limit), select: 'DOI,title,author,issued,container-title,type,abstract,URL' });
+    const body = await json(fetchImpl, `https://api.crossref.org/works?${params}`, opts.signal);
+    const items = body.message?.items ?? [];
+    const typeMap = {
+        'journal-article': 'article',
+        'proceedings-article': 'inproceedings',
+        book: 'book',
+        monograph: 'book',
+        dissertation: 'phdthesis',
+        'posted-content': 'misc',
+    };
+    return items.flatMap(item => {
+        const doi = item.DOI;
+        if (doi === undefined)
+            return [];
+        const title = normalizeTitle(item.title?.[0]);
+        const year = item.issued?.['date-parts']?.[0]?.[0] ?? null;
+        if (opts.yearFrom !== undefined && year !== null && year < opts.yearFrom)
+            return [];
+        return [{
+                id: makeId(doi, item.URL, title),
+                title,
+                authors: (item.author ?? []).map(a => a.name ?? [a.given, a.family].filter(Boolean).join(' ').trim()).filter(n => n !== ''),
+                year,
+                venue: item['container-title']?.[0] ?? '',
+                type: typeMap[item.type ?? ''] ?? 'article',
+                doi,
+                ...(item.URL !== undefined ? { url: item.URL } : {}),
+                ...cleanAbstract(item.abstract) !== undefined ? { abstract: cleanAbstract(item.abstract) } : {},
+                source: 'crossref',
+            }];
+    });
+}
+// ---------------------------------------------------------------------------
+// 组合检索（降级链）
+// ---------------------------------------------------------------------------
+export function makeId(doi, url, title) {
+    const basis = (doi ?? url ?? title).trim().toLowerCase();
+    return createHash('sha1').update(basis).digest('hex').slice(0, 16);
+}
+const SOURCE_ORDER = ['semantic-scholar', 'dblp', 'arxiv', 'crossref'];
+const SEARCHERS = {
+    'semantic-scholar': searchSemanticScholar,
+    dblp: searchDblp,
+    arxiv: searchArxiv,
+    crossref: searchCrossref,
+};
+export const LIT_SOURCES = ['semantic-scholar', 'dblp', 'arxiv', 'crossref'];
+/**
+ * 检索文献。source=auto 时按 Semantic Scholar → DBLP → arXiv → Crossref 顺序
+ * 降级：某源失败（网络/限流/超时）则尝试下一源；首个返回 ≥1 条结果的源胜出。
+ * 返回按年被引/年份排序后的去重列表（重复判定：id 相同）。
+ *
+ * **取消不是失败**：调用方取消时立刻把 `AbortError` 抛出去，不去试下一个源——
+ * 否则用户按了停止，工具会继续打四个学术 API（最多 60 秒），最后报一句
+ * 「所有检索源均未返回结果」，把取消误导成网络问题。
+ */
+export async function searchLiterature(fetchImpl, opts) {
+    const forced = opts.source !== undefined && opts.source !== 'auto' ? opts.source : undefined;
+    if (forced !== undefined && SEARCHERS[forced] === undefined) {
+        throw new Error(`未知的检索来源「${forced}」。可用：${LIT_SOURCES.join(' | ')}，或省略 source 走降级链（auto）。`);
+    }
+    const order = forced !== undefined ? [forced] : SOURCE_ORDER;
+    const errors = [];
+    for (const source of order) {
+        try {
+            const results = await SEARCHERS[source](fetchImpl, opts);
+            if (results.length > 0) {
+                return dedupe(results)
+                    .sort((a, b) => (b.citationCount ?? b.year ?? 0) - (a.citationCount ?? a.year ?? 0));
+            }
+            errors.push(`${source}: 无结果`);
+        }
+        catch (error) {
+            if (isAbortError(error))
+                throw error;
+            errors.push(`${source}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new Error(`所有检索源均未返回结果。${errors.join('；')}`);
+}
+function dedupe(records) {
+    const seen = new Set();
+    const out = [];
+    for (const record of records) {
+        if (seen.has(record.id))
+            continue;
+        seen.add(record.id);
+        out.push(record);
+    }
+    return out;
+}
+export { parseArxivAtom };

package/lib/paper/lib/lit-cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 文献检索缓存与检索留痕（02-文献/.lit-cache.json 与 02-文献/检索记录.md）。
+ *
+ * 缓存是"零假文献"的机制保证：thesis_lit_save 只接受缓存中由真实检索
+ * 产生的记录 ID，不接受模型转述的元数据。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { LitRecord } from './lit-api.ts';
+export declare const LIT_CACHE_REL = "02-\u6587\u732E/.lit-cache.json";
+export declare const LIT_RECORD_REL = "02-\u6587\u732E/\u68C0\u7D22\u8BB0\u5F55.md";
+export declare const REFS_BIB_REL = "02-\u6587\u732E/refs.bib";
+export declare const NOTES_DIR_REL = "02-\u6587\u732E/\u7B14\u8BB0";
+export interface LitCache {
+    readonly version: 1;
+    readonly records: Record<string, LitRecord>;
+}
+export declare function emptyCache(): LitCache;
+/**
+ * 读取检索缓存。
+ *
+ * **只有「缓存文件不存在」才返回空缓存**（第一次检索的正常情况）。
+ * 其余情况一律抛错：
+ * - 读失败（权限 / IO）：抛错并说明「缓存存在但读不出来」，否则调用方会用空缓存
+ *   覆盖写回，把**全部历史检索记录**抹掉——那些记录是「零假文献」红线的审计证据；
+ * - JSON 损坏 / 版本不符：同样抛错，并提示备份后重建。
+ */
+export declare function loadCache(fs: FileSystem, root: string, signal?: AbortSignal): Promise<LitCache>;
+export declare function saveCache(fs: FileSystem, root: string, cache: LitCache, signal?: AbortSignal): Promise<void>;
+export declare function mergeRecords(cache: LitCache, records: readonly LitRecord[]): LitCache;
+export declare function appendLitRecord(fs: FileSystem, root: string, row: string, signal?: AbortSignal): Promise<void>;
+export declare function searchRow(date: string, source: string, query: string, hits: number, ids: readonly string[]): string;
+export declare function saveRow(date: string, source: string, title: string, bibKey: string, doi?: string): string;

package/lib/paper/lib/lit-cache.js

@@ -0,0 +1,91 @@
+/**
+ * 文献检索缓存与检索留痕（02-文献/.lit-cache.json 与 02-文献/检索记录.md）。
+ *
+ * 缓存是"零假文献"的机制保证：thesis_lit_save 只接受缓存中由真实检索
+ * 产生的记录 ID，不接受模型转述的元数据。
+ */
+import * as nodePath from 'node:path';
+import { describeReadFailure, isMissingError } from "../../shared/fs-errors.js";
+export const LIT_CACHE_REL = '02-文献/.lit-cache.json';
+export const LIT_RECORD_REL = '02-文献/检索记录.md';
+export const REFS_BIB_REL = '02-文献/refs.bib';
+export const NOTES_DIR_REL = '02-文献/笔记';
+export function emptyCache() {
+    return { version: 1, records: {} };
+}
+/**
+ * 读取检索缓存。
+ *
+ * **只有「缓存文件不存在」才返回空缓存**（第一次检索的正常情况）。
+ * 其余情况一律抛错：
+ * - 读失败（权限 / IO）：抛错并说明「缓存存在但读不出来」，否则调用方会用空缓存
+ *   覆盖写回，把**全部历史检索记录**抹掉——那些记录是「零假文献」红线的审计证据；
+ * - JSON 损坏 / 版本不符：同样抛错，并提示备份后重建。
+ */
+export async function loadCache(fs, root, signal) {
+    const path = nodePath.join(root, LIT_CACHE_REL);
+    let raw;
+    try {
+        raw = await fs.readText(await fs.resolve(path, { signal }), signal);
+    }
+    catch (error) {
+        if (isMissingError(error))
+            return emptyCache();
+        throw new Error(describeReadFailure('文献检索缓存', path, error, signal));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`文献检索缓存不是合法 JSON：${path}（${error instanceof Error ? error.message : String(error)}）。`
+            + '为避免把历史检索记录改成空缓存，已停止本次操作。请备份该文件后删除它，再重新检索。');
+    }
+    if (parsed === null || typeof parsed !== 'object' || parsed.version !== 1
+        || typeof parsed.records !== 'object' || parsed.records === null) {
+        throw new Error(`文献检索缓存的版本或结构不符：${path}（期望 version: 1 与 records 对象）。`
+            + '为避免覆盖历史检索记录，已停止本次操作。请备份后删除该文件，再重新检索。');
+    }
+    return parsed;
+}
+export async function saveCache(fs, root, cache, signal) {
+    await fs.writeText(await fs.resolve(nodePath.join(root, LIT_CACHE_REL), { signal }), JSON.stringify(cache, null, 2) + '\n', undefined, signal);
+}
+export function mergeRecords(cache, records) {
+    const next = { ...cache.records };
+    for (const record of records)
+        next[record.id] = record;
+    return { version: 1, records: next };
+}
+const RECORD_HEADER = `# 文献检索记录
+
+> 每次检索留痕：哪个库、什么关键词、命中多少、收录哪些。
+> 这是"零假文献"的审计证据。
+
+| 日期 | 动作 | 数据库 | 关键词/文献 | 命中 | 备注 |
+|---|---|---|---|---|---|
+`;
+export async function appendLitRecord(fs, root, row, signal) {
+    const path = nodePath.join(root, LIT_RECORD_REL);
+    let raw;
+    try {
+        raw = await fs.readText(await fs.resolve(path, { signal }), signal);
+    }
+    catch (error) {
+        // 只有「检索记录还没建过」才用表头开始；读失败必须上抛，否则会抹掉审计证据。
+        if (!isMissingError(error))
+            throw new Error(describeReadFailure('文献检索记录', path, error, signal));
+        raw = RECORD_HEADER;
+    }
+    if (raw.trim() === '')
+        raw = RECORD_HEADER;
+    await fs.writeText(await fs.resolve(path, { signal }), `${raw.trimEnd()}\n${row}\n`, undefined, signal);
+}
+export function searchRow(date, source, query, hits, ids) {
+    const note = hits > 0 ? `缓存 id：${ids.join('、')}` : '无结果';
+    return `| ${date} | 检索 | ${source} | ${query.replaceAll('|', '\\|')} | ${hits} | ${note} |`;
+}
+export function saveRow(date, source, title, bibKey, doi) {
+    const note = `收录 → refs.bib [${bibKey}]${doi !== undefined ? `（DOI: ${doi}）` : ''}`;
+    return `| ${date} | 收录 | ${source} | ${title.replaceAll('|', '\\|')} | 1 | ${note} |`;
+}

package/lib/paper/lib/project.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 论文工作区根目录定位：从当前会话 cwd 向上寻找 `00-管理/进度台账.md`，
+ * 或使用配置显式指定的工作区根。
+ *
+ * **为什么向上探测而不是记住路径**：装配发生在进程启动时，那时还没有会话，
+ * 也就没有 cwd。向上探测让「在论文仓库里任意子目录操作」都能正确定位根。
+ *
+ * @module dsh-thesis/paper/lib/project
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+export declare const LEDGER_REL = "00-\u7BA1\u7406/\u8FDB\u5EA6\u53F0\u8D26.md";
+export declare const DECISION_REL = "00-\u7BA1\u7406/\u51B3\u5B9A\u65E5\u5FD7.md";
+/** 装配时由 `src/index.ts` 调用；传 `undefined` 表示恢复「向上探测」。 */
+export declare function setWorkspaceRoot(root: string | undefined): void;
+/** 当前生效的显式工作区根（测试与诊断用）。 */
+export declare function currentWorkspaceRoot(): string | undefined;
+/** 工作区未找到时的统一错误文案（工具层直接抛）。 */
+export declare function workspaceNotFoundError(cwd: string | undefined): Error;
+/**
+ * 找到论文工作区根；确实找不到时返回 null。
+ *
+ * 三种情况严格区分：
+ * - **显式配置了 workspace**：只认它。台账不存在或读不出来 → 抛错（配置写错了要立刻知道，
+ *   绝不能悄悄退回到 cwd 探测，否则工具会写到别的目录去）。
+ * - **向上探测**：某层没有台账 → 继续往上；读失败（权限/IO）→ 抛错，
+ *   因为「读不出来」不等于「不存在」，静默跳过会让用户以为工作区不存在。
+ * - **走到头**：返回 null（调用方给可读错误）。
+ */
+export declare function findThesisRoot(fs: FileSystem, cwd: string | undefined, signal?: AbortSignal): Promise<string | null>;

package/lib/paper/lib/project.js

@@ -0,0 +1,93 @@
+/**
+ * 论文工作区根目录定位：从当前会话 cwd 向上寻找 `00-管理/进度台账.md`，
+ * 或使用配置显式指定的工作区根。
+ *
+ * **为什么向上探测而不是记住路径**：装配发生在进程启动时，那时还没有会话，
+ * 也就没有 cwd。向上探测让「在论文仓库里任意子目录操作」都能正确定位根。
+ *
+ * @module dsh-thesis/paper/lib/project
+ */
+import * as nodePath from 'node:path';
+import { isAbortError, isMissingError } from "../../shared/fs-errors.js";
+export const LEDGER_REL = '00-管理/进度台账.md';
+export const DECISION_REL = '00-管理/决定日志.md';
+/** 向上最多探测的层级数（防止在文件系统根上无意义循环）。 */
+const MAX_UP = 8;
+/**
+ * 配置显式指定的论文工作区根。
+ *
+ * 语义是**部署级**的（一个插件装载对应一个论文工作区），因此用模块级持有：
+ * 装配时由 {@link setWorkspaceRoot} 写入，工具执行时读取。这样做而不把
+ * workspace 参数穿透到十几个调用点，是因为宿主在进程启动时装配、之后才执行
+ * 工具，时序上不存在竞态；单用户单工作区是插件的目标场景。
+ */
+let configuredRoot;
+/** 装配时由 `src/index.ts` 调用；传 `undefined` 表示恢复「向上探测」。 */
+export function setWorkspaceRoot(root) {
+    configuredRoot = root === '' ? undefined : root;
+}
+/** 当前生效的显式工作区根（测试与诊断用）。 */
+export function currentWorkspaceRoot() {
+    return configuredRoot;
+}
+/** 工作区未找到时的统一错误文案（工具层直接抛）。 */
+export function workspaceNotFoundError(cwd) {
+    const where = cwd === undefined || cwd === '' ? '（本次调用没有会话工作目录）' : `（自 ${cwd} 向上查找 ${LEDGER_REL} 失败）`;
+    return new Error(`未找到论文工作区${where}。请先用 thesis_init 创建工作区后在论文目录内操作；`
+        + '若工作区在别处，可在插件配置里用 `workspace` 指定它的绝对路径。');
+}
+/**
+ * 找到论文工作区根；确实找不到时返回 null。
+ *
+ * 三种情况严格区分：
+ * - **显式配置了 workspace**：只认它。台账不存在或读不出来 → 抛错（配置写错了要立刻知道，
+ *   绝不能悄悄退回到 cwd 探测，否则工具会写到别的目录去）。
+ * - **向上探测**：某层没有台账 → 继续往上；读失败（权限/IO）→ 抛错，
+ *   因为「读不出来」不等于「不存在」，静默跳过会让用户以为工作区不存在。
+ * - **走到头**：返回 null（调用方给可读错误）。
+ */
+export async function findThesisRoot(fs, cwd, signal) {
+    if (configuredRoot !== undefined) {
+        const root = nodePath.resolve(configuredRoot);
+        const ledger = nodePath.join(root, LEDGER_REL);
+        try {
+            await fs.readText(await fs.resolve(ledger, { signal }), signal);
+            return root;
+        }
+        catch (error) {
+            if (isAbortError(error))
+                throw error;
+            if (isMissingError(error)) {
+                throw new Error(`配置的 workspace 里没有 ${LEDGER_REL}：${root}。`
+                    + '该路径不是 dsh-thesis 论文工作区（或工作区尚未创建）；请修正配置或先用 thesis_init 建库。');
+            }
+            throw new Error(`配置的 workspace 里的 ${LEDGER_REL} 存在但读不出来：${ledger}`
+                + `（${error instanceof Error ? error.message : String(error)}）。请检查文件权限后重试。`);
+        }
+    }
+    if (cwd === undefined || cwd === '')
+        return null;
+    let dir = nodePath.resolve(cwd);
+    for (let i = 0; i <= MAX_UP; i += 1) {
+        try {
+            await fs.readText(await fs.resolve(nodePath.join(dir, LEDGER_REL), { signal }), signal);
+            return dir;
+        }
+        catch (error) {
+            // 取消必须原样抛出：否则用户按了停止，探测还会继续往上走 8 层。
+            if (isAbortError(error))
+                throw error;
+            if (!isMissingError(error)) {
+                throw new Error(`读取 ${nodePath.join(dir, LEDGER_REL)} 失败`
+                    + `（${error instanceof Error ? error.message : String(error)}）。`
+                    + '这不是「工作区不存在」，而是读取本身出错；为避免写错目录，已停止本次操作。');
+            }
+            // 该层确实没有台账，继续向上。
+        }
+        const parent = nodePath.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 章节确定性评审（thesis_review 的核心）。
+ *
+ * 六个可执行检查，全部基于真实文件内容，不做任何"感觉式"判断：
+ * 1. 字数：正文 CJK 字符数 vs 该章目标区间
+ * 2. 大纲：模板要求的全部小节标题是否齐全
+ * 3. 引用：文中引用编号是否都能对应 refs.bib 中的条目（顺序编码制）
+ * 4. 图表：图/表编号章号正确、序号从 1 连续
+ * 5. 未完成标记：待补/TODO/尖括号占位等残留
+ * 6. G2 清单：章节模板内嵌验收清单的勾选状态
+ *
+ * 语义质量（论证是否充分、逻辑是否连贯）由 AI 依据 thesis-writing 技能评审，
+ * 本工具只负责"可被机器证明"的部分——报告与清单一起构成 G2 验收依据。
+ */
+import type { ChapterMeta } from './layout.ts';
+export interface ReviewFinding {
+    readonly check: string;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+export interface ReviewInput {
+    readonly chapterText: string;
+    readonly bibText: string;
+    readonly meta: ChapterMeta;
+    readonly chapterNo: number;
+}
+/** 图/表编号：第 n 章的编号必须是 n-k，k 从 1 连续，且不得出现其它章编号。 */
+export declare function checkNumberedObjects(text: string, chapterNo: number, kind: '图' | '表'): ReviewFinding;
+export interface ReviewReport {
+    readonly chapter: string;
+    readonly chapterNo: number;
+    readonly title: string;
+    readonly findings: readonly ReviewFinding[];
+    readonly allOk: boolean;
+}
+export declare function reviewChapter(input: ReviewInput): ReviewReport;
+export declare function renderReviewReport(report: ReviewReport): string;