dsh-thesis 1.0.0

package/lib/ingest/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * 材料摄取模块门面：类型判定 → 各格式抽取 → 统一的 `thesis_ingest` 工具。
+ *
+ * 设计要点：
+ * - `extractDocument` 是**纯函数**（字节 + 类型 + 选项 → 结果），不碰磁盘；
+ * - `extractText` 是统一入口（按文件名判定类型），供其它模块编程调用；
+ * - `thesis_ingest` 负责磁盘/工作区落盘：读文件（二进制走 `node:fs` 例外）、
+ *   递归枚举目录、把摘要写到 `00-管理/材料/`，**绝不覆盖已存在的摘要**；
+ * - I/O 通过 {@link IngestIO} 注入，便于测试注入自定义读取器与假文件系统。
+ *
+ * @module dsh-thesis/ingest
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { IngestOptions } from '../config.ts';
+import { type CodeFileSummary, type CodeLanguage } from './code.ts';
+/** 摄取类型：可抽取的文档格式 + 源码结构摘要 + 不支持。 */
+export type IngestKind = 'docx' | 'xlsx' | 'pptx' | 'pdf' | 'text' | 'code' | 'unsupported';
+/** 递归枚举时跳过的目录名（版本库/依赖/产出，避免把仓库翻个底朝天）。 */
+export declare const SKIP_DIRS: string[];
+/**
+ * 按扩展名判定摄取类型。
+ *
+ * 顺序有讲究：源码扩展名先判为 `code`（`.md/.json/.yaml/.html` 仍走 `text`，
+ * 依赖清单也走 `text`——清单原文对写"技术选型"有用）。
+ */
+export declare function detectKind(path: string): IngestKind;
+/** 不支持时的解释（`.doc`/`.xls`/`.ppt` 走专门提示）。 */
+export declare function unsupportedReason(path: string): string;
+/** 抽取结果（工具与其它模块共用的公开形状）。 */
+export interface IngestExtract {
+    /** 是否抽取成功。 */
+    readonly ok: boolean;
+    /** 判定出的类型。 */
+    readonly kind: IngestKind;
+    /** 抽取到的文本（失败时为空串）。 */
+    readonly text: string;
+    /** 文本字符数。 */
+    readonly chars: number;
+    /** 是否因 `maxChars` 截断。 */
+    readonly truncated: boolean;
+    /** 文档标题（docx/pptx 的文档属性）。 */
+    readonly title?: string;
+    /** 说明/失败原因。 */
+    readonly note?: string;
+    /** 低置信标记（文本量明显偏少）。 */
+    readonly lowConfidence?: boolean;
+}
+/**
+ * 按类型抽取字节 → 文本（纯函数）。
+ *
+ * - `unsupported` 返回 `ok: false` 与明确的另存为提示，绝不静默返回空文本；
+ * - `code` **不返回源码正文**，只给该文件的结构摘要（语言/行数/声明）。
+ */
+export declare function extractDocument(bytes: Uint8Array, kind: IngestKind, options: {
+    maxChars: number;
+}): IngestExtract;
+/** 单文件代码结构摘要（不返回源码正文）。 */
+export declare function codeFileExtract(rel: string, text: string, options: {
+    maxChars: number;
+}): IngestExtract;
+/** 统一入口：字节 + 文件名 → 结果（内部判定类型）。 */
+export declare function extractText(bytes: Uint8Array, filename: string, options: {
+    maxChars: number;
+}): IngestExtract;
+/** 一个待摄取的文件（绝对路径 + 工作区相对路径 + 判定类型）。 */
+export interface IngestFile {
+    readonly absolute: string;
+    /** 字节数；无法取得时（测试注入的 IO）缺省为 -1。 */
+    readonly size: number;
+    readonly rel: string;
+    /** 判定出的摄取类型（`code` 只做结构摘要，不返回源码正文）。 */
+    readonly kind: IngestKind;
+}
+/** 清单文件超过该字节数就不纳入技术栈指纹（只如实列出跳过）。 */
+export declare const MAX_MANIFEST_BYTES: number;
+/** 摄取所需的 I/O：真实实现走 node:fs + ctx.fs，测试可注入内存实现。 */
+export interface IngestIO {
+    /** 指定路径是文件还是目录（不存在返回 undefined）。 */
+    kind(target: string): Promise<'file' | 'dir' | undefined>;
+    /** 目录下的直接子项（不存在/无权限抛错）。 */
+    list(target: string): Promise<readonly {
+        name: string;
+        isDirectory: boolean;
+    }[]>;
+    /** 读文件字节。 */
+    read(target: string): Promise<Uint8Array>;
+}
+/** 真实磁盘 I/O（二进制读取是文档化的例外：ctx.fs 只有 readText）。 */
+export declare const diskIO: IngestIO;
+/** 一次摄取最多处理的文件数（防止把整个磁盘拖进来）。 */
+export declare const MAX_FILES = 200;
+/** 递归深度上限。 */
+export declare const MAX_DEPTH = 6;
+/** 后缀过滤：`docx,pdf,md` → 匹配集合（空 = 不过滤）。 */
+export declare function parseGlobFilter(glob: string | undefined): Set<string>;
+/** 是否跳过该目录（名称命中 SKIP_DIRS 尾段或整体相对路径）。 */
+export declare function shouldSkipDir(name: string, rel: string): boolean;
+/** 递归枚举待摄取文件（目录）或单个文件。 */
+export declare function collectFiles(io: IngestIO, target: string, filter: Set<string>): Promise<IngestFile[]>;
+/** 目录名 → 代码摘要文件名（`<目录名>-代码结构.md`）。 */
+export declare function codeSummaryFileName(target: string): string;
+/** 代码结构汇总（清单里单独一节 + 一份摘要文件）。 */
+export interface CodeStructure {
+    /** 参与摘要的源码文件数。 */
+    readonly files: number;
+    /** 总行数 / 代码行数。 */
+    readonly lines: number;
+    readonly codeLines: number;
+    /** 语言分布（语言 → 文件数/行数），按行数降序。 */
+    readonly languages: ReadonlyArray<{
+        readonly language: CodeLanguage;
+        readonly files: number;
+        readonly lines: number;
+    }>;
+    /** 技术栈（由依赖清单推断）。 */
+    readonly stack: ReadonlyArray<{
+        readonly name: string;
+        readonly evidence: string;
+    }>;
+    /** 摘要文件在工作区内的相对路径。 */
+    readonly summaryPath: string;
+    /** 未能摘要的文件（超大/读取失败），如实列出。 */
+    readonly skipped: readonly string[];
+}
+/** 汇总一组单文件摘要。 */
+export declare function buildCodeStructure(files: readonly CodeFileSummary[], manifests: Readonly<Record<string, string>>, summaryPath: string, skipped: readonly string[]): CodeStructure;
+/** 摘要目录（相对论文工作区根）。 */
+export declare const MATERIAL_DIR = "00-\u7BA1\u7406/\u6750\u6599";
+/** 清单文件（相对论文工作区根）。 */
+export declare const MANIFEST_REL = "00-\u7BA1\u7406/\u6750\u6599\u6E05\u5355.md";
+/** 文件名 → 安全的摘要文件名（去扩展名，替换非法字符）。 */
+export declare function summaryFileName(rel: string): string;
+/**
+ * 生成单个文件的摘要 Markdown。
+ * 含：原文件名、类型、字节数、字符数、是否截断/低置信、正文。
+ */
+export declare function buildSummary(rel: string, size: number, result: IngestExtract): string;
+/** 生成工作区清单文件内容。 */
+export declare function buildManifest(files: readonly IngestFile[], results: readonly IngestExtract[], written: readonly string[], skipped: readonly string[], code: CodeStructure | undefined): string;
+/** `thesis_ingest` 的参数。 */
+export interface IngestArgs {
+    /** 文件或目录的绝对路径（必填）。 */
+    path: string;
+    /** 可选后缀过滤，如 `docx,pdf,md`。 */
+    glob?: string;
+    /** 是否把摘要落到论文工作区，默认 true。 */
+    write?: boolean;
+}
+/** 摄取结果（供测试与渲染共用）。 */
+export interface IngestOutcome {
+    readonly root: string | undefined;
+    readonly files: readonly IngestFile[];
+    readonly results: readonly IngestExtract[];
+    readonly written: readonly string[];
+    readonly skipped: readonly string[];
+    readonly failed: readonly {
+        readonly rel: string;
+        readonly reason: string;
+    }[];
+    readonly truncatedCount: number;
+    readonly lowConfidence: readonly string[];
+    /** 代码结构汇总（没有源码文件时为 undefined）。 */
+    readonly code: CodeStructure | undefined;
+    readonly note: string | undefined;
+}
+/** 执行摄取（I/O 注入；工具与测试共用）。 */
+export declare function runIngest(fs: FileSystem, io: IngestIO, args: IngestArgs, cwd: string | undefined, options: IngestOptions, signal?: AbortSignal): Promise<IngestOutcome>;
+/** 按优先级给出"该带进追问的关键材料"建议。 */
+export declare function suggestNextSteps(files: readonly IngestFile[], results: readonly IngestExtract[]): string[];
+/** 渲染工具返回值（有界字符串，遵守 maxChars）。 */
+export declare function renderOutcome(outcome: IngestOutcome, maxChars: number): string;
+/** `thesis_ingest` 工具的装配参数。 */
+export interface RegisterIngestOptions {
+    /** 摄取配置（`maxBytes`/`maxChars`，来自 `src/config.ts`）。 */
+    readonly ingest: IngestOptions;
+}
+/** 注册 `thesis_ingest`（同步注册，走仓库统一的 `definePaperTool`；斜杠命令见 `commands.ts`）。 */
+export declare function registerIngest(ctx: Context, options: RegisterIngestOptions): void;