dsh-convert-core 0.1.0-alpha.1

package/lib/media/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * media-to-md 的公开契约。
+ *
+ * 这个包只做一件事:把一个**本地**音视频/图片文件变成「知识就绪 Markdown + 本地图片」。
+ * 它刻意不认识任何宿主(转换内核、CLI、未来的桌面端),宿主拿到的就是一个纯函数:
+ *
+ *   convertMedia(options) → { markdown, assets[], meta, transcript, warnings, … }
+ *
+ * 全程本地:不调用云端 API、不调用大模型。用到的两个**专用小模型**(语音识别 whisper、
+ * 画面文字 OCR)都是可选档位,且是否允许下载由调用方显式给出(`allowModelDownload`)。
+ */
+export type MediaSourceFormat = 'video' | 'audio' | 'image' | 'pdf';
+/** 解析档位。`auto` = 有字幕用字幕,没有才考虑转写(且必须允许下载模型)。 */
+export type MediaMode = 'auto' | 'subtitle-only' | 'transcribe' | 'frames-only';
+export interface MediaAsrOptions {
+    /** whisper 模型名(tiny/base/small/medium/large-v3/large-v3-turbo)。 */
+    model?: string;
+    /** 语言代码(zh/en…);省略则自动检测。 */
+    language?: string;
+    /** faster-whisper 设备与量化,默认 cpu/int8。 */
+    device?: string;
+    computeType?: string;
+    beamSize?: number;
+    /**
+     * 是否允许下载模型。默认 **false**:
+     * 无字幕又没有本地模型时会抛 `ASR_MODEL_REQUIRED`,把「要下多大」摊在调用方面前。
+     */
+    allowModelDownload?: boolean;
+}
+export interface MediaFrameOptions {
+    /** 均匀采样帧数(保证任何视频都有基础覆盖)。 */
+    samples?: number;
+    /** 关键帧上限。 */
+    maxFrames?: number;
+    /** 场景切换阈值(0–1);硬切/翻页会额外抽帧。 */
+    sceneThreshold?: number;
+}
+export interface MediaToolOptions {
+    /** uvx 可执行文件;默认 `uvx`。 */
+    uvxPath?: string;
+    /** uvx 使用的 Python 版本;默认 `3.12`。 */
+    pythonVersion?: string;
+}
+export interface MediaToMarkdownOptions {
+    /** 本地文件绝对路径。 */
+    file: string;
+    /** 产物标题;默认取文件名(去扩展名)。 */
+    title?: string;
+    mode?: MediaMode;
+    asr?: MediaAsrOptions;
+    frames?: MediaFrameOptions;
+    tools?: MediaToolOptions;
+    /** 对**图片**输入开启本地 OCR;默认 false(issue 0013:图片直接收录、靠多模态召回)。 */
+    imageOcr?: boolean;
+    /** 对视频**关键帧**做画面文字 OCR;默认 false。 */
+    ocrFrames?: boolean;
+    /** 保留中间目录(排障用)。 */
+    keepScratch?: boolean;
+    /** 取消信号。 */
+    signal?: AbortSignal;
+    onProgress?: (progress: MediaToMarkdownProgress) => void;
+}
+/**
+ * 轻量扫描档:纯图片页 PDF → 逐页本地 OCR。
+ *
+ * 刻意**不引入 docling / PaddlePaddle 框架**:它只解决"扫描件里的字读不出来",
+ * 版面顺序与表格结构不在这一档的承诺范围内(见 issues/0017 的可选高质量档)。
+ */
+export interface ScannedPdfOptions {
+    file: string;
+    title?: string;
+    /** 最多渲染并识别的页数(默认 50);超出会写 warning,不静默截断。 */
+    maxPages?: number;
+    /** 渲染 DPI(默认 150);越高越准,也越慢越大。 */
+    dpi?: number;
+    /** 是否把逐页图片作为 assets 落地(默认 true;false 时只保留文字)。 */
+    pageImages?: boolean;
+    tools?: MediaToolOptions;
+    keepScratch?: boolean;
+    signal?: AbortSignal;
+    onProgress?: (progress: MediaToMarkdownProgress) => void;
+}
+/** 扫描档的页级结果。 */
+export interface ScannedPage {
+    index: number;
+    /** 该页图片在产物里的相对路径(未落地图片时为 `page-NNNN.png` 的约定名)。 */
+    rel: string;
+    width?: number;
+    height?: number;
+    text: string;
+    ocrLines: number;
+}
+export interface MediaToMarkdownProgress {
+    stage: 'probing' | 'frames' | 'subtitles' | 'transcribing' | 'ocr' | 'assembling';
+    /** 0–1,未知时为 null。 */
+    progress: number | null;
+    message?: string;
+}
+export interface MediaAsset {
+    /** 相对产物根的路径,**含 `assets/` 前缀**,可直接写进 Markdown。 */
+    rel: string;
+    data: Buffer;
+    contentType?: string;
+}
+export interface MediaCue {
+    seconds: number;
+    /** 结束时间(字幕/SRT 有;自动转写也有)。缺失时按下一条的开始时间处理。 */
+    endSeconds?: number;
+    text: string;
+}
+export interface MediaMeta {
+    sourceFormat: MediaSourceFormat;
+    /** 容器/图片扩展名(不含点),例如 `mp4`、`png` —— 宿主用它拼 parser 标识。 */
+    containerExtension?: string;
+    durationSeconds: number;
+    sizeBytes: number;
+    width?: number;
+    height?: number;
+    fps?: number;
+    videoCodec?: string;
+    audioCodec?: string;
+    hasVideo: boolean;
+    hasAudio: boolean;
+    hasSubtitleTrack: boolean;
+    /** 实际用到的字幕来源。 */
+    transcriptSource: 'subtitle' | 'transcription' | 'none';
+}
+export interface MediaWarning {
+    code: string;
+    message: string;
+}
+export interface MediaToMarkdownResult {
+    title: string;
+    /** Markdown 正文;**不含 front matter**(front matter 是宿主的契约)。 */
+    markdown: string;
+    assets: MediaAsset[];
+    meta: MediaMeta;
+    transcript: {
+        source: MediaMeta['transcriptSource'];
+        cues: MediaCue[];
+    };
+    warnings: MediaWarning[];
+    dependencyVersions: Record<string, string>;
+    /** 文件内容 hash(sha256:…),给宿主做幂等。 */
+    externalId: string;
+    /** 扫描档才有:逐页文本与图片。 */
+    pages?: ScannedPage[];
+}
+/** 带可操作建议的错误:宿主(内核/CLI)应当原样展示 `code` 与 `suggestion`。 */ export declare class MediaToMarkdownError extends Error {
+    readonly code: string;
+    readonly suggestion?: string;
+    constructor(code: string, message: string, suggestion?: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/media/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/media/types.ts"],"names":[],"mappings":"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"}

package/lib/media/types.js

@@ -0,0 +1,23 @@
+/**
+ * media-to-md 的公开契约。
+ *
+ * 这个包只做一件事:把一个**本地**音视频/图片文件变成「知识就绪 Markdown + 本地图片」。
+ * 它刻意不认识任何宿主(转换内核、CLI、未来的桌面端),宿主拿到的就是一个纯函数:
+ *
+ *   convertMedia(options) → { markdown, assets[], meta, transcript, warnings, … }
+ *
+ * 全程本地:不调用云端 API、不调用大模型。用到的两个**专用小模型**(语音识别 whisper、
+ * 画面文字 OCR)都是可选档位,且是否允许下载由调用方显式给出(`allowModelDownload`)。
+ */
+/** 带可操作建议的错误:宿主(内核/CLI)应当原样展示 `code` 与 `suggestion`。 */ export class MediaToMarkdownError extends Error {
+    code;
+    suggestion;
+    constructor(code, message, suggestion) {
+        super(message);
+        this.name = 'MediaToMarkdownError';
+        this.code = code;
+        if (suggestion !== undefined)
+            this.suggestion = suggestion;
+    }
+}
+//# sourceMappingURL=types.js.map

package/lib/media/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/media/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsJH,wDAAwD,CAAA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC5F,IAAI,CAAQ;IACZ,UAAU,CAAS;IAE5B,YAAY,IAAY,EAAE,OAAe,EAAE,UAAmB;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC5D,CAAC;CACF"}

package/lib/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Public entry point of the conversion kernel.
+ *
+ * Two integration shapes, one implementation:
+ *   const service = await createConvertService({ rootDir })
+ *   const server  = await startConvertServer({ port: 8787 })      // standalone
+ *   const handler = createRequestHandler({ service, basePath })    // embedded
+ */
+import { type Server } from 'node:http';
+import { ConvertService, type ConvertServiceOptions } from './service.js';
+export * from './contract.js';
+export * from './service.js';
+export * from './delivery.js';
+export * from './adapters/index.js';
+export * from './adapters/types.js';
+export { createRequestHandler, type HandlerOptions } from './http.js';
+export interface CreateServiceOptions extends ConvertServiceOptions {
+}
+export declare function createConvertService(options?: CreateServiceOptions): Promise<ConvertService>;
+export interface StartServerOptions extends CreateServiceOptions {
+    port?: number;
+    host?: string;
+    basePath?: string;
+    webRoot?: string;
+    apiKey?: string;
+}
+export interface RunningConvertServer {
+    service: ConvertService;
+    server: Server;
+    url: string;
+    close: () => Promise<void>;
+}
+/** Start the kernel standalone — the console is at `url`, the API under `url/api`. */
+export declare function startConvertServer(options?: StartServerOptions): Promise<RunningConvertServer>;
+//# sourceMappingURL=server.d.ts.map

package/lib/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAA;AAErD,OAAO,EAAE,cAAc,EAAsB,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAE7F,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;AAErE,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;CAAG;AAEtE,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC,CAItG;AAED,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,cAAc,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,sFAAsF;AACtF,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAwCxG"}

package/lib/server.js

@@ -0,0 +1,64 @@
+/**
+ * Public entry point of the conversion kernel.
+ *
+ * Two integration shapes, one implementation:
+ *   const service = await createConvertService({ rootDir })
+ *   const server  = await startConvertServer({ port: 8787 })      // standalone
+ *   const handler = createRequestHandler({ service, basePath })    // embedded
+ */
+import { createServer } from 'node:http';
+import { createRequestHandler } from './http.js';
+import { ConvertService, defaultConvertRoot } from './service.js';
+export * from './contract.js';
+export * from './service.js';
+export * from './delivery.js';
+export * from './adapters/index.js';
+export * from './adapters/types.js';
+export { createRequestHandler } from './http.js';
+export async function createConvertService(options = {}) {
+    const service = new ConvertService({ rootDir: options.rootDir ?? defaultConvertRoot(), ...options });
+    await service.start();
+    return service;
+}
+/** Start the kernel standalone — the console is at `url`, the API under `url/api`. */
+export async function startConvertServer(options = {}) {
+    const service = await createConvertService(options);
+    const handlerOptions = {
+        service,
+        basePath: options.basePath ?? '',
+        ...(options.webRoot ? { webRoot: options.webRoot } : {}),
+        ...(options.apiKey ? { apiKey: options.apiKey } : {}),
+    };
+    const handler = createRequestHandler(handlerOptions);
+    const server = createServer((req, res) => {
+        void handler(req, res).catch(() => {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+            }
+            res.end(JSON.stringify({ ok: false, error: { code: 'INTERNAL_ERROR', message: '未捕获的服务端错误' } }));
+        });
+    });
+    const port = options.port ?? 8787;
+    const host = options.host ?? '127.0.0.1';
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const actualPort = typeof address === 'object' && address ? address.port : port;
+    const basePath = (options.basePath ?? '').replace(/\/+$/, '');
+    return {
+        service,
+        server,
+        url: `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${actualPort}${basePath}`,
+        close: async () => {
+            await service.close();
+            await new Promise(resolve => server.close(() => resolve()));
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/lib/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/lib/service.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The conversion service: queue, lifecycle, delivery, observability.
+ *
+ * It owns no transport. `http.ts` mounts it on `node:http`, the DSH plugin
+ * mounts the same handler on the host web server, and `bin/tita-convert.mjs`
+ * runs it standalone — the "kernel first, wrapper second" split.
+ */
+import { type CapabilityReport } from './adapters/index.js';
+import type { ConvertRequest, ConvertTask, IngestPayload, TaskState } from './contract.js';
+export interface ConvertServiceOptions {
+    /** Root for task state (`tasks.json`). Defaults to `~/.tita-data-agent`. */
+    rootDir?: string;
+    /**
+     * Root the **deliveries** are written under. Defaults to `<rootDir>/convert-out`.
+     *
+     * 与 `bucketByDay` 配合决定形状：不分桶是 `<outRoot>/<taskId>/`，分桶是
+     * `<outRoot>/<YYYY-MM-DD>/<taskId>/`。任务目录始终是原子的交付单位。
+     */
+    outRoot?: string;
+    /**
+     * Root the per-task **working** directories live under. Defaults to
+     * `<rootDir>/work`. 形状与 `outRoot` 一致。
+     */
+    workRoot?: string;
+    /**
+     * 交付与工作区是否按日期分桶（0029）。
+     *
+     * **默认 false，是刻意的**：这是内核，独立运行（`bin/tita-convert.mjs`）与既有
+     * 调用方都不该因为插件侧的目录结构调整而换位置。TitaAgent 插件显式传 `true`，
+     * 因为它的根路径契约里 `output/` 与 `tmp/` 的二级就是日期。
+     *
+     * 分桶的理由：这两处是「按时间堆积」的东西，不分桶的话一个月后就是一个几百条
+     * 平铺的目录，`ls` 出来读不出「上周那份报表在哪」。
+     */
+    bucketByDay?: boolean;
+    maxConcurrent?: number;
+    maxInputBytes?: number;
+    /** Keep at most this many finished tasks in the store. */
+    maxTasks?: number;
+    /** Delete deliveries older than this on start. 0 disables cleanup. */
+    retentionDays?: number;
+    /**
+     * How long a capability report stays valid. Defaults to
+     * {@link DEFAULT_CAPABILITY_TTL_MS}; 0 disables caching.
+     *
+     * See {@link ConvertService.capabilities} for why this exists: building the
+     * report spawns external binaries, and the console polls it on a timer.
+     */
+    capabilityTtlMs?: number;
+}
+/**
+ * Default lifetime of a capability report: 30 seconds.
+ *
+ * Long enough that a polling panel costs one probe per half minute instead of one
+ * per poll; short enough that installing ffmpeg and reopening the panel shows it
+ * without restarting anything.
+ */
+export declare const DEFAULT_CAPABILITY_TTL_MS = 30000;
+export interface SubmitInput {
+    filename?: string;
+    /** Raw bytes for file / video uploads. */
+    data?: Buffer;
+}
+export type ConvertListener = (task: ConvertTask) => void;
+export declare const DEFAULT_ROOT: string;
+export declare function defaultConvertRoot(): string;
+export declare class ConvertService {
+    readonly rootDir: string;
+    /** 交付物根。每个任务的具体交付目录见 `deliveryDirOf()`。 */
+    readonly outRoot: string;
+    /** 工作区根。每个任务的具体工作目录见 `workDirOf()`。 */
+    readonly workRoot: string;
+    /** 交付与工作区是否按日期分桶。见 `ConvertServiceOptions.bucketByDay`。 */
+    readonly bucketByDay: boolean;
+    private readonly options;
+    private readonly tasks;
+    private readonly controllers;
+    private readonly listeners;
+    private readonly queue;
+    private running;
+    private closed;
+    private persistTimer;
+    private persistTail;
+    /** Last capability report and when it was built. See {@link capabilities}. */
+    private capabilityCache;
+    constructor(options?: ConvertServiceOptions);
+    /**
+     * @deprecated 0029：`outDir` 现在是 `outRoot` 的别名。保留这个名字只为兼容
+     * 既有的能力报告（`host.ts` 会回显它）；新代码用 `outRoot` + `deliveryDirOf()`。
+     */
+    get outDir(): string;
+    /** @deprecated 0029：同上，用 `workRoot` + `workDirOf()`。 */
+    get workDir(): string;
+    /**
+     * 一个任务的交付目录。
+     *
+     * 分桶时 `<outRoot>/<日期>/<taskId>`，否则 `<outRoot>/<taskId>`。**按任务的
+     * `createdAt` 算而不是按「现在」**：重试一个昨天的任务不该把它换到今天来，
+     * 否则同一个交付会因为一次重试而换位置。
+     */
+    deliveryDirOf(task: Pick<ConvertTask, 'id' | 'createdAt'>): string;
+    /** 一个任务的工作目录。形状与交付目录一致。 */
+    workDirOf(task: Pick<ConvertTask, 'id' | 'createdAt'>): string;
+    private taskDir;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    subscribe(listener: ConvertListener): () => void;
+    private emit;
+    get(id: string): ConvertTask | undefined;
+    list(): ConvertTask[];
+    /**
+     * Report which adapters can run and which external binaries exist.
+     *
+     * **Cached, because building this is not free.** `capabilityReport()` probes
+     * every adapter, and the media adapter's probe runs `ffprobe -version`,
+     * `ffmpeg -version` and `uvx --version` — three child processes per call, which
+     * measured ~60ms of server time. The conversion console polls this endpoint
+     * every four seconds while its tab is visible, so an uncached report cost about
+     * 45 processes and a second of CPU per minute. That lands on the same
+     * single-threaded process that serves the GUI's HTTP and event stream, which is
+     * how a status panel becomes everyone's latency.
+     *
+     * Nothing it reports changes second to second: an installed binary stays
+     * installed. {@link ConvertServiceOptions.capabilityTtlMs} bounds the staleness.
+     *
+     * @param options - `force` bypasses the cache, for a caller that just changed
+     *   the environment (or a test that must not read another test's report).
+     * @returns the capability report.
+     */
+    capabilities(options?: {
+        force?: boolean;
+    }): Promise<CapabilityReport>;
+    submit(request: ConvertRequest, input?: SubmitInput): Promise<ConvertTask>;
+    cancel(id: string): ConvertTask;
+    retry(id: string): Promise<ConvertTask>;
+    private patch;
+    private pump;
+    private execute;
+    /** Resolve a path inside a delivery directory, refusing traversal. */
+    resolveDeliveryFile(id: string, relative: string): string | undefined;
+    readDeliveryFile(id: string, relative: string): Promise<{
+        data: Buffer;
+        contentType: string;
+    } | undefined>;
+    ingestPlan(id: string): Promise<IngestPayload>;
+    listDeliveries(): Array<{
+        taskId: string;
+        title: string;
+        deliveryDir: string;
+        state: TaskState;
+        assets: number;
+    }>;
+    private schedulePersist;
+    private persist;
+    private load;
+    /**
+     * 按保留期清理交付物。
+     *
+     * `outRoot` 下面那一层**要么是日期桶、要么是任务目录**，取决于 `bucketByDay`；
+     * 两种情况下它都是「一个可整体丢弃的单位」，所以清理规则只有一条：这一层的
+     * mtime 早于截止就整块删。分桶时不必再往下一层逐个判 —— 桶内任务通常是同一天
+     * 建的，逐个判既白判又会留下一个空壳日期目录。
+     */
+    private cleanup;
+}
+export declare function safeFilename(value: string): string;
+/** Slug used when the DSH layer files a delivery as a knowledge source. */
+export declare function knowledgeSlugFor(taskId: string, title: string): string;
+export declare function contentTypeOf(path: string): string;
+//# sourceMappingURL=service.d.ts.map

package/lib/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}