dsh-thesis 1.0.0

package/lib/ingest/code.js

@@ -0,0 +1,356 @@
+/**
+ * 代码结构摘要：把源码变成「论文与答辩用得上的结构信息」，而不是原文倒出。
+ *
+ * 为什么不做成"把源码当文本读"：一个课程设计仓库动辄上万行，倒进上下文既挤爆预算、
+ * 又对写作没有帮助。真正有用的是**结构**——有哪些文件、各多少行、定义了哪些类与函数、
+ * 入口在哪、用了什么技术栈、依赖清单说了什么。这些正是：
+ * - 论文「系统实现」章的骨架；
+ * - `thesis_defense` 的「工作量」证据（文件数/代码行数）；
+ * - 答辩必问「你的系统怎么实现的」的可检索索引；
+ * - `code-walkthrough` 做代码演练时的地图。
+ *
+ * 纯函数、无宿主依赖、零第三方库：只用正则做**结构化信号提取**（不求 AST 精度），
+ * 因此结果里只报"检出"，不谎称"完整解析"。
+ *
+ * @module dsh-thesis/ingest/code
+ */
+/** 扩展名 → 语言。 */
+const LANGUAGE_BY_EXTENSION = {
+    '.ts': 'typescript', '.tsx': 'typescript', '.mts': 'typescript', '.cts': 'typescript',
+    '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.py': 'python', '.pyw': 'python',
+    '.java': 'java',
+    '.go': 'go',
+    '.rs': 'rust',
+    '.c': 'c', '.h': 'c',
+    '.cc': 'cpp', '.cpp': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp', '.hh': 'cpp',
+    '.cs': 'csharp',
+    '.php': 'php',
+    '.rb': 'ruby',
+    '.kt': 'kotlin', '.kts': 'kotlin',
+    '.swift': 'swift',
+    '.sql': 'sql',
+    '.sh': 'shell', '.bash': 'shell', '.zsh': 'shell', '.ps1': 'shell', '.bat': 'shell',
+    '.vue': 'vue',
+    '.html': 'html', '.htm': 'html',
+    '.css': 'css', '.scss': 'css', '.less': 'css',
+};
+/** 依赖/构建清单文件（用于技术栈指纹）。 */
+const MANIFEST_NAMES = [
+    'package.json', 'pnpm-lock.yaml', 'yarn.lock', 'package-lock.json',
+    'requirements.txt', 'pyproject.toml', 'pipfile', 'environment.yml',
+    'go.mod', 'cargo.toml', 'pom.xml', 'build.gradle', 'build.gradle.kts',
+    'composer.json', 'gemfile', 'dockerfile', 'docker-compose.yml', 'makefile',
+];
+/** 语言名（用于摘要文本）。 */
+export function languageLabel(language) {
+    return language;
+}
+/** 是否是受支持的源码文件；不是则返回 `undefined`。 */
+export function codeLanguageOf(path) {
+    const lower = path.toLowerCase().replace(/\\/g, '/');
+    const base = lower.slice(lower.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    return LANGUAGE_BY_EXTENSION[base.slice(dot)];
+}
+/** 是否是依赖/构建清单。 */
+export function isManifestFile(path) {
+    const lower = path.toLowerCase().replace(/\\/g, '/');
+    const base = lower.slice(lower.lastIndexOf('/') + 1);
+    return MANIFEST_NAMES.includes(base);
+}
+/** 每个文件最多索引多少条声明（防止超大生成文件把摘要撑爆）。 */
+export const MAX_DECLARATIONS_PER_FILE = 40;
+/** 单文件最多扫描多少行。 */
+export const MAX_SCAN_LINES = 20_000;
+/** 各语言的声明模式（顺序即优先级，命中即记录，同名字取首个）。 */
+const PATTERNS = {
+    typescript: [
+        { kind: 'function', regex: /^\s*export\s+(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'function', regex: /^\s*(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'class', regex: /^\s*export\s+(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'class', regex: /^\s*(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'interface', regex: /^\s*export\s+interface\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'type', regex: /^\s*export\s+type\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'enum', regex: /^\s*export\s+enum\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'const', regex: /^\s*export\s+const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\(|<)/ },
+        { kind: 'route', regex: /\.\s*(?:get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/ },
+    ],
+    javascript: [
+        { kind: 'function', regex: /^\s*export\s+(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'function', regex: /^\s*(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'class', regex: /^\s*(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'route', regex: /\.\s*(?:get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/ },
+    ],
+    python: [
+        { kind: 'class', regex: /^\s*class\s+([A-Za-z_]\w*)/ },
+        { kind: 'function', regex: /^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)/ },
+        { kind: 'route', regex: /@\w+\.(?:route|get|post|put|delete)\s*\(\s*['"]([^'"]+)['"]/ },
+    ],
+    java: [
+        { kind: 'class', regex: /^\s*(?:public|protected|private)?\s*(?:final\s+|abstract\s+)?(?:class|interface|enum)\s+([A-Za-z_]\w*)/ },
+        { kind: 'method', regex: /^\s*(?:public|protected|private)\s+(?:static\s+|final\s+|synchronized\s+)*[\w<>\[\],.\s]+\s+([A-Za-z_]\w*)\s*\(/ },
+    ],
+    go: [
+        { kind: 'function', regex: /^func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)/ },
+        { kind: 'struct', regex: /^type\s+([A-Za-z_]\w*)\s+struct/ },
+        { kind: 'interface', regex: /^type\s+([A-Za-z_]\w*)\s+interface/ },
+    ],
+    rust: [
+        { kind: 'function', regex: /^\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)/ },
+        { kind: 'struct', regex: /^\s*(?:pub\s+)?struct\s+([A-Za-z_]\w*)/ },
+        { kind: 'enum', regex: /^\s*(?:pub\s+)?enum\s+([A-Za-z_]\w*)/ },
+        { kind: 'trait', regex: /^\s*(?:pub\s+)?trait\s+([A-Za-z_]\w*)/ },
+    ],
+    c: [
+        { kind: 'struct', regex: /^\s*(?:typedef\s+)?struct\s+([A-Za-z_]\w*)/ },
+        { kind: 'function', regex: /^[A-Za-z_][\w\s*]*\s+([A-Za-z_]\w*)\s*\([^;]*\)\s*\{/ },
+    ],
+    cpp: [
+        { kind: 'class', regex: /^\s*class\s+([A-Za-z_]\w*)/ },
+        { kind: 'struct', regex: /^\s*(?:typedef\s+)?struct\s+([A-Za-z_]\w*)/ },
+        { kind: 'function', regex: /^[A-Za-z_][\w:<>*&\s]*\s+([A-Za-z_]\w*)\s*\([^;]*\)\s*\{/ },
+    ],
+    csharp: [
+        { kind: 'class', regex: /^\s*(?:public|internal|private|protected)?\s*(?:sealed\s+|abstract\s+|partial\s+)*(?:class|interface|enum|record)\s+([A-Za-z_]\w*)/ },
+        { kind: 'method', regex: /^\s*(?:public|private|protected|internal)\s+(?:static\s+|async\s+|virtual\s+|override\s+)*[\w<>\[\],.\s]+\s+([A-Za-z_]\w*)\s*\(/ },
+    ],
+    php: [
+        { kind: 'class', regex: /^\s*(?:final\s+|abstract\s+)?class\s+([A-Za-z_]\w*)/ },
+        { kind: 'function', regex: /^\s*(?:public|private|protected|static|\s)*function\s+([A-Za-z_]\w*)/ },
+    ],
+    ruby: [
+        { kind: 'class', regex: /^\s*class\s+([A-Za-z_]\w*)/ },
+        { kind: 'function', regex: /^\s*def\s+([A-Za-z_]\w*[?!=]?)/ },
+    ],
+    kotlin: [
+        { kind: 'class', regex: /^\s*(?:data\s+|sealed\s+|open\s+|abstract\s+)?class\s+([A-Za-z_]\w*)/ },
+        { kind: 'function', regex: /^\s*(?:private\s+|internal\s+|public\s+)?fun\s+([A-Za-z_]\w*)/ },
+    ],
+    swift: [
+        { kind: 'class', regex: /^\s*(?:final\s+|open\s+)?(?:class|struct|enum|protocol)\s+([A-Za-z_]\w*)/ },
+        { kind: 'function', regex: /^\s*(?:public\s+|private\s+|internal\s+)?func\s+([A-Za-z_]\w*)/ },
+    ],
+    sql: [
+        { kind: 'table', regex: /^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"[]?([A-Za-z_]\w*)/i },
+        { kind: 'view', regex: /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?VIEW\s+[`"[]?([A-Za-z_]\w*)/i },
+    ],
+    shell: [
+        { kind: 'function', regex: /^\s*(?:function\s+)?([A-Za-z_]\w*)\s*\(\s*\)\s*\{/ },
+    ],
+    vue: [
+        { kind: 'component', regex: /^\s*defineComponent\s*\(\s*\{?\s*name:\s*['"]([^'"]+)['"]/ },
+        { kind: 'function', regex: /^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/ },
+        { kind: 'const', regex: /^\s*const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:ref|reactive|computed|defineProps|defineEmits)\b/ },
+    ],
+    html: [
+        { kind: 'script', regex: /<script[^>]*src=["']([^"']+)["']/i },
+        { kind: 'link', regex: /<link[^>]*href=["']([^"']+)["']/i },
+    ],
+    css: [
+        { kind: 'selector', regex: /^([.#][A-Za-z_][\w-]*)\s*\{/ },
+    ],
+};
+/** 是否是注释行（语言无关的粗判；不求精确）。 */
+function isCommentLine(line, language) {
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return false;
+    if (language === 'python' || language === 'shell' || language === 'ruby')
+        return trimmed.startsWith('#');
+    if (language === 'sql')
+        return trimmed.startsWith('--');
+    if (language === 'html')
+        return trimmed.startsWith('<!--');
+    if (language === 'css')
+        return trimmed.startsWith('/*') || trimmed.startsWith('*');
+    return trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('*/');
+}
+/**
+ * 摘要一个源码文件。
+ *
+ * @param rel - 展示用相对路径
+ * @param text - 文件内容（已解码）
+ */
+export function summarizeSource(rel, text) {
+    const language = codeLanguageOf(rel) ?? 'typescript';
+    const allLines = text.split('\n');
+    const truncated = allLines.length > MAX_SCAN_LINES;
+    const lines = truncated ? allLines.slice(0, MAX_SCAN_LINES) : allLines;
+    let blankLines = 0;
+    let commentLines = 0;
+    const declarations = [];
+    const seen = new Set();
+    const patterns = PATTERNS[language] ?? [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.trim() === '') {
+            blankLines += 1;
+            continue;
+        }
+        if (isCommentLine(line, language)) {
+            commentLines += 1;
+            continue;
+        }
+        if (declarations.length >= MAX_DECLARATIONS_PER_FILE)
+            continue;
+        for (const pattern of patterns) {
+            const match = pattern.regex.exec(line);
+            const name = match?.[1];
+            if (name === undefined || name === '')
+                continue;
+            const key = `${pattern.kind}:${name}`;
+            if (seen.has(key))
+                break;
+            seen.add(key);
+            declarations.push({ kind: pattern.kind, name, line: index + 1 });
+            break;
+        }
+    }
+    return {
+        rel,
+        language,
+        lines: allLines.length,
+        codeLines: lines.length - blankLines - commentLines,
+        commentLines,
+        blankLines,
+        declarations,
+        truncated,
+    };
+}
+const STACK_SIGNALS = [
+    { name: 'Node.js / npm', regex: /"(?:dependencies|devDependencies)"\s*:/ },
+    { name: 'React', regex: /"react"\s*:/ },
+    { name: 'Vue', regex: /"vue"\s*:/ },
+    { name: 'Angular', regex: /"@angular\/core"\s*:/ },
+    { name: 'Express', regex: /"express"\s*:/ },
+    { name: 'Koa', regex: /"koa"\s*:/ },
+    { name: 'NestJS', regex: /"@nestjs\/core"\s*:/ },
+    { name: 'TypeScript', regex: /"typescript"\s*:/ },
+    { name: 'Vite', regex: /"vite"\s*:/ },
+    { name: 'Webpack', regex: /"webpack"\s*:/ },
+    { name: 'Next.js', regex: /"next"\s*:/ },
+    { name: 'FastAPI', regex: /fastapi/i },
+    { name: 'Flask', regex: /flask/i },
+    { name: 'Django', regex: /django/i },
+    { name: 'PyTorch', regex: /torch/i },
+    { name: 'TensorFlow', regex: /tensorflow/i },
+    { name: 'NumPy', regex: /numpy/i },
+    { name: 'Pandas', regex: /pandas/i },
+    { name: 'OpenCV', regex: /opencv/i },
+    { name: 'Spring Boot', regex: /spring-boot/i },
+    { name: 'MyBatis', regex: /mybatis/i },
+    { name: 'Maven', regex: /<groupId>/ },
+    { name: 'Gradle', regex: /plugins\s*\{|dependencies\s*\{/ },
+    { name: 'Go Modules', regex: /^module\s+\S+/m },
+    { name: 'Gin', regex: /gin-gonic\/gin/ },
+    { name: 'Cargo / Rust', regex: /^\[package\]/m },
+    { name: 'MySQL', regex: /mysql/i },
+    { name: 'PostgreSQL', regex: /postgres/i },
+    { name: 'SQLite', regex: /sqlite/i },
+    { name: 'Redis', regex: /redis/i },
+    { name: 'MongoDB', regex: /mongo/i },
+    { name: 'Docker', regex: /FROM\s+\S+|services:/i },
+    { name: 'Composer / PHP', regex: /"require"\s*:/ },
+];
+/** 从清单文件内容推断技术栈。 */
+export function detectTechStack(manifests) {
+    const entries = [];
+    const seen = new Set();
+    for (const [rel, content] of Object.entries(manifests)) {
+        for (const signal of STACK_SIGNALS) {
+            if (seen.has(signal.name))
+                continue;
+            if (signal.regex.test(content)) {
+                seen.add(signal.name);
+                entries.push({ name: signal.name, evidence: rel });
+            }
+        }
+    }
+    return entries;
+}
+/** 渲染成 Markdown（写进 `00-管理/材料/` 的摘要文件）。 */
+export function renderProjectSummary(summary) {
+    const byLanguage = new Map();
+    for (const file of summary.files) {
+        const bucket = byLanguage.get(file.language) ?? { files: 0, lines: 0 };
+        bucket.files += 1;
+        bucket.lines += file.lines;
+        byLanguage.set(file.language, bucket);
+    }
+    const totalLines = summary.files.reduce((sum, file) => sum + file.lines, 0);
+    const totalCode = summary.files.reduce((sum, file) => sum + file.codeLines, 0);
+    const lines = [];
+    lines.push(`# 代码结构摘要：${summary.root}`);
+    lines.push('');
+    lines.push('> 由 `thesis_ingest` 生成。这里只记录**结构信号**（文件、行数、声明、入口、技术栈），');
+    lines.push('> 不含源码正文——论文「系统实现」章与答辩素材应从这些结构出发，而不是粘贴代码。');
+    lines.push('');
+    lines.push('## 规模');
+    lines.push('');
+    lines.push(`- 源码文件：${summary.files.length} 个`);
+    lines.push(`- 总行数：${totalLines} 行（其中代码行 ${totalCode} 行）`);
+    lines.push('');
+    if (byLanguage.size > 0) {
+        lines.push('| 语言 | 文件数 | 行数 |');
+        lines.push('|---|---|---|');
+        for (const [language, bucket] of [...byLanguage.entries()].sort((a, b) => b[1].lines - a[1].lines)) {
+            lines.push(`| ${language} | ${bucket.files} | ${bucket.lines} |`);
+        }
+        lines.push('');
+    }
+    const stack = detectTechStack(summary.manifests);
+    lines.push('## 技术栈（由依赖清单推断，须与你的实际选型核对）');
+    lines.push('');
+    if (stack.length === 0) {
+        lines.push('- 未在依赖清单里检出可识别技术栈；若确有依赖文件，请确认它在本目录内。');
+    }
+    else {
+        for (const entry of stack)
+            lines.push(`- ${entry.name}　（证据：${entry.evidence}）`);
+    }
+    lines.push('');
+    lines.push('## 文件与主要声明');
+    lines.push('');
+    if (summary.files.length === 0) {
+        lines.push('- （未摄取到源码文件：确认 path 指向代码目录，且没有被 SKIP_DIRS 跳过）');
+        lines.push('');
+    }
+    for (const file of [...summary.files].sort((a, b) => b.lines - a.lines)) {
+        const parts = [`${file.lines} 行`];
+        if (file.commentLines > 0)
+            parts.push(`注释 ${file.commentLines}`);
+        if (file.truncated)
+            parts.push('已截断摘要');
+        lines.push(`### ${file.rel}　（${file.language}，${parts.join('，')}）`);
+        lines.push('');
+        if (file.declarations.length === 0) {
+            lines.push('- （未检出顶层声明）');
+        }
+        else {
+            for (const declaration of file.declarations) {
+                lines.push(`- \`${declaration.kind}\` **${declaration.name}**　（第 ${declaration.line} 行）`);
+            }
+        }
+        lines.push('');
+    }
+    if (summary.skipped.length > 0) {
+        lines.push('## 未纳入摘要的文件');
+        lines.push('');
+        for (const rel of summary.skipped)
+            lines.push(`- ${rel}`);
+        lines.push('');
+        lines.push('（原因通常是文件过大或读取失败——需要时请单独查看。）');
+        lines.push('');
+    }
+    lines.push('## 怎么写进论文');
+    lines.push('');
+    lines.push('1. 「系统实现」章按**模块**组织：每个主要文件/声明的职责 + 关键实现取舍（而不是贴代码）；');
+    lines.push('2. 「系统设计」章的模块划分应与这里的文件/声明结构一致，答辩时能一一指认；');
+    lines.push('3. 工作量证据用这里的文件数与代码行数，但**不要**把它们直接写进正文当论据堆砌；');
+    lines.push('4. 想让老师追问不倒你，用 `defense_code_status`/`defense_code_next` 建代码演练（配合 `code-walkthrough` 技能）。');
+    lines.push('');
+    return lines.join('\n');
+}

package/lib/ingest/commands.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 斜杠命令：`/thesis-ingest`。
+ *
+ * 命令名遵循 DSH 的 `[a-z][a-z0-9_-]*` 约束（kebab-case），与 `/thesis-check` 等同一套写法。
+ * 命令只是 `thesis_ingest` 工具的薄封装：把命令行输入解析成 `IngestArgs` 后交给 `runIngest`，
+ * 因此行为与工具**完全一致**。
+ *
+ * @module dsh-thesis/ingest
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { IngestOptions } from '../config.ts';
+import { type IngestArgs } from './index.ts';
+/**
+ * 解析 `/thesis-ingest` 的输入。
+ *
+ * 用法：`/thesis-ingest <绝对路径> [--glob docx,pdf] [--dry]`
+ * - `<绝对路径>`：文件或目录（目录递归；源码目录会产出代码结构摘要）
+ * - `--glob`：后缀过滤，逗号分隔
+ * - `--dry`：只读不落盘（不写材料清单与摘要文件）
+ */
+export declare function parseIngestCommandInput(rawInput: string): IngestArgs;
+/** 构造 `/thesis-ingest` 命令定义。 */
+export declare function ingestCommand(fs: FileSystem, options: IngestOptions): unknown;

package/lib/ingest/commands.js

@@ -0,0 +1,74 @@
+/**
+ * 斜杠命令：`/thesis-ingest`。
+ *
+ * 命令名遵循 DSH 的 `[a-z][a-z0-9_-]*` 约束（kebab-case），与 `/thesis-check` 等同一套写法。
+ * 命令只是 `thesis_ingest` 工具的薄封装：把命令行输入解析成 `IngestArgs` 后交给 `runIngest`，
+ * 因此行为与工具**完全一致**。
+ *
+ * @module dsh-thesis/ingest
+ */
+import { diskIO, renderOutcome, runIngest } from "./index.js";
+async function safe(work) {
+    try {
+        return { kind: 'success', text: await work() };
+    }
+    catch (error) {
+        return { kind: 'error', text: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * 解析 `/thesis-ingest` 的输入。
+ *
+ * 用法：`/thesis-ingest <绝对路径> [--glob docx,pdf] [--dry]`
+ * - `<绝对路径>`：文件或目录（目录递归；源码目录会产出代码结构摘要）
+ * - `--glob`：后缀过滤，逗号分隔
+ * - `--dry`：只读不落盘（不写材料清单与摘要文件）
+ */
+export function parseIngestCommandInput(rawInput) {
+    const tokens = rawInput.trim().split(/\s+/).filter(token => token !== '');
+    let path;
+    let glob;
+    let write = true;
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        const lowered = token.toLowerCase();
+        if (lowered === '--glob' || lowered === '-g') {
+            glob = tokens[++index];
+            if (glob === undefined)
+                throw new Error('--glob 后面要跟后缀列表，如 --glob docx,pdf');
+            continue;
+        }
+        if (lowered === '--dry' || lowered === '--no-write') {
+            write = false;
+            continue;
+        }
+        if (token.startsWith('-'))
+            throw new Error(`无法识别的选项「${token}」`);
+        if (path !== undefined)
+            throw new Error(`只能指定一个路径（多余的是「${token}」）`);
+        path = token;
+    }
+    if (path === undefined) {
+        throw new Error('用法：/thesis-ingest <绝对路径> [--glob docx,pdf] [--dry]');
+    }
+    return {
+        path,
+        ...(glob !== undefined ? { glob } : {}),
+        ...(write ? {} : { write: false }),
+    };
+}
+/** 构造 `/thesis-ingest` 命令定义。 */
+export function ingestCommand(fs, options) {
+    return {
+        name: 'thesis-ingest',
+        description: '摄取材料：docx/xlsx/pptx/pdf/md/csv/bib + 源码目录 → 文本与代码结构摘要，写 00-管理/材料清单.md',
+        input: { hint: '<绝对路径> [--glob docx,pdf] [--dry]' },
+        async handler(invocation) {
+            return await safe(async () => {
+                const args = parseIngestCommandInput(invocation.rawInput);
+                const outcome = await runIngest(fs, diskIO, args, invocation.agent.session.header.cwd, options, invocation.signal);
+                return renderOutcome(outcome, options.maxChars);
+            });
+        },
+    };
+}

package/lib/ingest/docx.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `.docx` 摄取：ZIP → `word/document.xml` → 段落文本。
+ *
+ * 说明：
+ * - 只读正文（`word/document.xml`），页眉/页脚/脚注/文本框暂不抽取
+ *   （文本框内容在 `w:txbxContent` 里，与正文同文档，会被一起抽到）；
+ * - 表格保留为制表符分隔的行（见 `ooxml.ts`）；
+ * - 标题取 `docProps/core.xml` 的 `dc:title`（Word 的"标题"属性），没有就留空，
+ *   不拿正文第一行冒充标题；
+ * - 若该文件其实是 xlsx/pptx（改扩展名的常见误操作），给出明确提示而不是报解析错误。
+ *
+ * @module dsh-thesis/ingest
+ */
+import { type ExtractOptions, type ExtractResult } from './types.ts';
+/** docx 正文抽取的完整结果（供测试与上层复用）。 */
+export interface DocxContent {
+    /** `dc:title`（没有则为 undefined）。 */
+    readonly title?: string;
+    /** 段落数组（表格行为 tab 分隔的单段）。 */
+    readonly paragraphs: readonly string[];
+    /** 段落用换行拼起来的正文。 */
+    readonly text: string;
+}
+/** 判定 OOXML 容器的真实类型（按内部条目，而不是扩展名）。 */
+export declare function sniffOoxmlKind(bytes: Uint8Array): 'docx' | 'xlsx' | 'pptx' | undefined;
+/** 纯抽取：ZIP 字节 → 标题 + 段落（不截断、不做结果包装）。 */
+export declare function readDocx(bytes: Uint8Array): DocxContent;
+/** 门面用入口：docx 字节 → 抽取结果（含截断/失败原因）。 */
+export declare function extractDocx(bytes: Uint8Array, options: ExtractOptions): ExtractResult;

package/lib/ingest/docx.js

@@ -0,0 +1,92 @@
+/**
+ * `.docx` 摄取：ZIP → `word/document.xml` → 段落文本。
+ *
+ * 说明：
+ * - 只读正文（`word/document.xml`），页眉/页脚/脚注/文本框暂不抽取
+ *   （文本框内容在 `w:txbxContent` 里，与正文同文档，会被一起抽到）；
+ * - 表格保留为制表符分隔的行（见 `ooxml.ts`）；
+ * - 标题取 `docProps/core.xml` 的 `dc:title`（Word 的"标题"属性），没有就留空，
+ *   不拿正文第一行冒充标题；
+ * - 若该文件其实是 xlsx/pptx（改扩展名的常见误操作），给出明确提示而不是报解析错误。
+ *
+ * @module dsh-thesis/ingest
+ */
+import { extractElementText, extractDocxParagraphs, extractRawElement } from "./ooxml.js";
+import { failureResult, successResult } from "./types.js";
+import { ZipError, decodeBytes, openZip } from "./zip.js";
+/** 判定 OOXML 容器的真实类型（按内部条目，而不是扩展名）。 */
+export function sniffOoxmlKind(bytes) {
+    try {
+        const zip = openZip(bytes);
+        if (zip.has('word/document.xml'))
+            return 'docx';
+        if (zip.has('xl/workbook.xml'))
+            return 'xlsx';
+        if (zip.has('ppt/presentation.xml'))
+            return 'pptx';
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 读取 `docProps/core.xml` 的 `dc:title`。 */
+function readCoreTitle(bytes) {
+    let core;
+    try {
+        core = decodeBytes(openZip(bytes).require('docProps/core.xml'));
+    }
+    catch {
+        return undefined;
+    }
+    const raw = extractRawElement(core, ['dc:title', 'title']);
+    if (raw === undefined)
+        return undefined;
+    const cleaned = extractElementText(`<x>${raw}</x>`, 'x', ['x']).trim();
+    return cleaned === '' ? undefined : cleaned;
+}
+/** 纯抽取：ZIP 字节 → 标题 + 段落（不截断、不做结果包装）。 */
+export function readDocx(bytes) {
+    const zip = openZip(bytes);
+    const documentBytes = zip.read('word/document.xml');
+    if (documentBytes === undefined) {
+        const actual = sniffOoxmlKind(bytes);
+        if (actual === 'xlsx') {
+            throw new ZipError('wrong-format', '这个文件内部是 Excel 工作簿（.xlsx），不是 Word 文档：请把扩展名改回 .xlsx，或先另存为 .docx。');
+        }
+        if (actual === 'pptx') {
+            throw new ZipError('wrong-format', '这个文件内部是 PowerPoint 演示文稿（.pptx），不是 Word 文档：请把扩展名改回 .pptx。');
+        }
+        throw new ZipError('missing-document', '这个 ZIP 里没有 word/document.xml：不是有效的 .docx（可能是 .odt/.zip 或已损坏）。请用 Word/WPS 另存为 .docx。');
+    }
+    const xml = decodeBytes(documentBytes);
+    const paragraphs = extractDocxParagraphs(xml);
+    const title = readCoreTitle(bytes);
+    return {
+        ...(title !== undefined ? { title } : {}),
+        paragraphs,
+        text: paragraphs.join('\n'),
+    };
+}
+/** 门面用入口：docx 字节 → 抽取结果（含截断/失败原因）。 */
+export function extractDocx(bytes, options) {
+    let content;
+    try {
+        content = readDocx(bytes);
+    }
+    catch (error) {
+        const reason = error instanceof ZipError
+            ? error.message
+            : `读取 .docx 失败：${error instanceof Error ? error.message : String(error)}`;
+        return failureResult(reason);
+    }
+    if (content.text.trim() === '') {
+        return failureResult('这个 .docx 没有任何正文文本（可能是空文档，或正文全在文本框/图片里）：请另存为含文本的文档再试。');
+    }
+    return successResult({
+        text: content.text,
+        maxChars: options.maxChars,
+        title: content.title,
+        note: `共 ${content.paragraphs.length} 段。`,
+    });
+}