@fgbg/mdocs 0.8.25 → 1.1.1

package/dist/server/task-queue/TaskQueue.js

@@ -0,0 +1,258 @@
+import { TaskLogStore } from './log-store.js';
+export class TaskQueue {
+    taskTypes = new Map();
+    queue = [];
+    concurrency;
+    timeSliceMs;
+    logStore;
+    scheduling = false; // 防止 schedule 重入
+    constructor(options) {
+        this.concurrency = options.concurrency ?? 2;
+        this.timeSliceMs = options.timeSliceMs ?? 30_000;
+        this.logStore = new TaskLogStore(options.logDir);
+    }
+    /* ── 注册任务类型 ── */
+    registerTask(type, def) {
+        this.taskTypes.set(type, def);
+    }
+    /* ── 入队 ── */
+    enqueue(type, payload) {
+        const def = this.taskTypes.get(type);
+        if (!def) {
+            throw new Error(`未知任务类型：${type}`);
+        }
+        const taskId = def.makeId(payload);
+        // 检查是否已有未完成的同 ID 任务（去重）
+        const existing = this.queue.find((t) => t.id === taskId && t.state !== 'completed' && t.state !== 'failed');
+        if (existing) {
+            return {
+                taskId,
+                status: this.getPublicStatus(existing),
+                position: this.getPosition(existing),
+                deduped: true,
+            };
+        }
+        // 移除旧的 completed/failed 任务（重新生成，覆盖）
+        this.queue = this.queue.filter((t) => t.id !== taskId);
+        // 创建新任务
+        const task = {
+            id: taskId,
+            type,
+            payload,
+            state: 'queued',
+            createdAt: Date.now(),
+        };
+        this.queue.push(task);
+        // 重置日志文件（重新开始写）
+        this.logStore.reset(taskId);
+        // 触发调度
+        this.schedule();
+        return {
+            taskId,
+            status: this.getPublicStatus(task),
+            position: this.getPosition(task),
+            deduped: false,
+        };
+    }
+    /* ── 查询任务状态 ── */
+    getTask(taskId) {
+        const task = this.queue.find((t) => t.id === taskId);
+        // 从日志推断进度
+        const logs = this.logStore.readTail(taskId, 50);
+        const progress = this.extractProgress(logs);
+        const lastLog = logs[logs.length - 1];
+        // 任务在队列中
+        if (task) {
+            return {
+                id: task.id,
+                type: task.type,
+                status: this.getPublicStatus(task),
+                position: this.getPosition(task),
+                progress,
+                logs,
+                error: task.error,
+                createdAt: new Date(task.createdAt).toISOString(),
+                startedAt: task.startedAt ? new Date(task.startedAt).toISOString() : undefined,
+                finishedAt: task.finishedAt ? new Date(task.finishedAt).toISOString() : undefined,
+            };
+        }
+        // 任务不在队列中（可能重启了，或已完成很久了）
+        const mtime = this.logStore.getMtime(taskId);
+        // 日志都没有 → not_found
+        if (!mtime) {
+            return {
+                id: taskId,
+                type: '',
+                status: 'not_found',
+                position: -1,
+                logs: [],
+                createdAt: '',
+            };
+        }
+        // 从最后一条日志判断状态
+        let status = 'stale';
+        let error;
+        if (lastLog?.event === 'task.completed') {
+            status = 'completed';
+        }
+        else if (lastLog?.event === 'task.failed') {
+            status = 'failed';
+            error = lastLog.data?.error;
+        }
+        else if (Date.now() - mtime > 5 * 60 * 1000) {
+            // 超过 5 分钟没更新 → stale
+            status = 'stale';
+        }
+        else {
+            // 5 分钟内有更新，但队列里没了 → 大概率刚重启，也算 stale
+            status = 'stale';
+        }
+        return {
+            id: taskId,
+            type: '',
+            status,
+            position: -1,
+            progress,
+            logs,
+            error,
+            createdAt: '',
+            startedAt: '',
+            finishedAt: lastLog ? lastLog.ts : undefined,
+        };
+    }
+    /* ── 调度核心 ── */
+    schedule() {
+        // 防重入：同步代码中多次调用 schedule，只执行一次
+        if (this.scheduling)
+            return;
+        this.scheduling = true;
+        // 用 setImmediate 让当前同步代码先跑完，再统一调度
+        setImmediate(() => {
+            this.scheduling = false;
+            this.doSchedule();
+        });
+    }
+    doSchedule() {
+        // 1. 先清理已完成/失败的任务
+        this.queue = this.queue.filter((t) => t.state !== 'completed' && t.state !== 'failed');
+        // 2. 确保前 concurrency 个位置上的任务都在跑
+        for (let i = 0; i < this.concurrency && i < this.queue.length; i++) {
+            const task = this.queue[i];
+            if (!task)
+                continue;
+            if (task.state === 'queued') {
+                // 还没开始过 → 启动
+                this.startTask(task);
+            }
+            else if (task.state === 'suspended') {
+                // yield 挂起了 → 恢复
+                this.resumeTask(task);
+            }
+            // running 不用管，它自己在跑
+        }
+    }
+    /* ── 启动 / 恢复任务 ── */
+    startTask(task) {
+        const def = this.taskTypes.get(task.type);
+        if (!def)
+            return;
+        task.state = 'running';
+        task.startedAt = task.startedAt ?? Date.now();
+        task.lastRunAt = Date.now();
+        const ctx = this.createContext(task);
+        task.run = def.run;
+        def.run(task.payload, ctx)
+            .then(() => {
+            task.state = 'completed';
+            task.finishedAt = Date.now();
+            this.logStore.append(task.id, 'task.completed');
+            this.schedule();
+        })
+            .catch((err) => {
+            task.state = 'failed';
+            task.error = err.message;
+            task.finishedAt = Date.now();
+            // 写一条失败日志
+            this.logStore.append(task.id, 'task.failed', { error: err.message }, 'error');
+            this.schedule();
+        });
+    }
+    resumeTask(task) {
+        if (task.state !== 'suspended' || !task.resume)
+            return;
+        task.state = 'running';
+        task.lastRunAt = Date.now();
+        const resume = task.resume;
+        task.resume = undefined;
+        resume();
+    }
+    /* ── 创建上下文 ── */
+    createContext(task) {
+        const scheduler = this.createScheduler(task);
+        return {
+            taskId: task.id,
+            scheduler,
+            emit: (event, data, level) => {
+                this.logStore.append(task.id, event, data, level);
+            },
+        };
+    }
+    createScheduler(task) {
+        return {
+            shouldYield: () => {
+                // 没人排队 → 没必要让
+                if (this.queue.length <= this.concurrency)
+                    return false;
+                // 时间片还没到 → 不让
+                if (!task.lastRunAt || Date.now() - task.lastRunAt < this.timeSliceMs)
+                    return false;
+                return true;
+            },
+            yield: () => {
+                return new Promise((resolve) => {
+                    // 存 resume 回调
+                    task.resume = resolve;
+                    task.state = 'suspended';
+                    // 写一条 yielded 日志
+                    this.logStore.append(task.id, 'task.yielded', { reason: 'time-slice' });
+                    // 从当前位置移除，塞到队尾
+                    this.queue = this.queue.filter((t) => t.id !== task.id);
+                    this.queue.push(task);
+                    // 触发调度（前面空位会被顶上）
+                    this.schedule();
+                });
+            },
+        };
+    }
+    /* ── 辅助方法 ── */
+    getPublicStatus(task) {
+        if (!task)
+            return 'pending';
+        if (task.state === 'completed')
+            return 'completed';
+        if (task.state === 'failed')
+            return 'failed';
+        const index = this.queue.indexOf(task);
+        if (index < this.concurrency)
+            return 'running';
+        return 'pending';
+    }
+    getPosition(task) {
+        if (!task)
+            return -1;
+        const index = this.queue.indexOf(task);
+        if (index < this.concurrency)
+            return 0; // 0 表示正在跑
+        return index - this.concurrency + 1; // 排队位置：1 = 下一个就轮到
+    }
+    extractProgress(logs) {
+        // 从日志里找最后一条 task.progress
+        for (let i = logs.length - 1; i >= 0; i--) {
+            if (logs[i].event === 'task.progress' && logs[i].data) {
+                return { current: logs[i].data.current, total: logs[i].data.total };
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=TaskQueue.js.map

package/dist/server/task-queue/TaskQueue.js.map

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

package/dist/server/task-queue/TaskQueue.test.js

@@ -0,0 +1,136 @@
+/**
+ * TaskQueue 单元测试。
+ *
+ * 测试要点：
+ * 1. 基本入队、执行、完成
+ * 2. 并发控制（不超过 concurrency）
+ * 3. 去重
+ * 4. yield 让出 + 恢复
+ * 5. 失败处理
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { TaskQueue } from './TaskQueue.js';
+describe('TaskQueue', () => {
+    let tmpDir;
+    let queue;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'task-queue-test-'));
+        queue = new TaskQueue({ concurrency: 2, timeSliceMs: 100, logDir: tmpDir });
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    /* ── 辅助：注册一个简单的测试任务 ── */
+    function registerSimpleTask(name, work) {
+        queue.registerTask(name, {
+            makeId: (payload) => `${name}:${payload.id}`,
+            run: async (payload, ctx) => {
+                await work(ctx);
+            },
+        });
+    }
+    it('基本流程：入队 → 执行 → 完成', async () => {
+        let ran = false;
+        registerSimpleTask('test', async () => {
+            ran = true;
+        });
+        const result = queue.enqueue('test', { id: '1' });
+        expect(result.deduped).toBe(false);
+        expect(result.taskId).toBe('test:1');
+        // 等 setImmediate 里的调度执行完
+        await new Promise((r) => setTimeout(r, 10));
+        expect(ran).toBe(true);
+        const status = queue.getTask('test:1');
+        expect(status.status).toBe('completed');
+    });
+    it('并发控制：同时最多跑 concurrency 个', async () => {
+        let running = 0;
+        let maxRunning = 0;
+        const tasks = [];
+        queue.registerTask('test', {
+            makeId: (p) => `test:${p.id}`,
+            run: async () => {
+                running++;
+                maxRunning = Math.max(maxRunning, running);
+                await new Promise((r) => setTimeout(r, 50));
+                running--;
+            },
+        });
+        // 入队 5 个
+        for (let i = 0; i < 5; i++) {
+            queue.enqueue('test', { id: String(i) });
+        }
+        // 等所有任务跑完
+        await new Promise((r) => setTimeout(r, 200));
+        expect(maxRunning).toBe(2);
+    });
+    it('去重：相同 ID 不重复入队', async () => {
+        let count = 0;
+        registerSimpleTask('test', async () => {
+            count++;
+        });
+        queue.enqueue('test', { id: 'same' });
+        const result = queue.enqueue('test', { id: 'same' });
+        expect(result.deduped).toBe(true);
+        expect(result.taskId).toBe('test:same');
+        await new Promise((r) => setTimeout(r, 10));
+        expect(count).toBe(1); // 只执行了一次
+    });
+    it('yield：任务可以让出，后面的顶上', async () => {
+        // 用并发 1 来测，确保 A yield 后 B 能顶上
+        queue = new TaskQueue({ concurrency: 1, timeSliceMs: 100, logDir: tmpDir });
+        const order = [];
+        queue.registerTask('test', {
+            makeId: (p) => `test:${p.id}`,
+            run: async (payload, ctx) => {
+                order.push(`${payload.id}-start`);
+                if (payload.yield) {
+                    await ctx.scheduler.yield();
+                }
+                order.push(`${payload.id}-end`);
+            },
+        });
+        // A yield，B 不 yield
+        queue.enqueue('test', { id: 'A', yield: true });
+        queue.enqueue('test', { id: 'B', yield: false });
+        await new Promise((r) => setTimeout(r, 100));
+        // 顺序应该是：
+        // A-start → A yield → B-start → B-end → A-end
+        expect(order).toEqual(['A-start', 'B-start', 'B-end', 'A-end']);
+    });
+    it('失败：任务异常标记为 failed，不影响其他任务', async () => {
+        queue.registerTask('test', {
+            makeId: (p) => `test:${p.id}`,
+            run: async (payload) => {
+                if (payload.fail) {
+                    throw new Error('boom');
+                }
+            },
+        });
+        queue.enqueue('test', { id: 'bad', fail: true });
+        queue.enqueue('test', { id: 'good', fail: false });
+        await new Promise((r) => setTimeout(r, 50));
+        const bad = queue.getTask('test:bad');
+        const good = queue.getTask('test:good');
+        expect(bad.status).toBe('failed');
+        expect(bad.error).toBe('boom');
+        expect(good.status).toBe('completed');
+    });
+    it('shouldYield：没人排队时不让', async () => {
+        let capturedShouldYield = true;
+        queue.registerTask('test', {
+            makeId: (p) => `test:${p.id}`,
+            run: async (_payload, ctx) => {
+                capturedShouldYield = ctx.scheduler.shouldYield();
+            },
+        });
+        queue.enqueue('test', { id: '1' });
+        await new Promise((r) => setTimeout(r, 10));
+        // 只有一个任务，没人排队 → 不让
+        expect(capturedShouldYield).toBe(false);
+    });
+});
+//# sourceMappingURL=TaskQueue.test.js.map

package/dist/server/task-queue/TaskQueue.test.js.map

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

package/dist/server/task-queue/index.js

@@ -0,0 +1,18 @@
+/**
+ * 任务队列单例。
+ *
+ * 全局只有一个 TaskQueue 实例，所有任务类型共享同一个并发池。
+ */
+import path from 'node:path';
+import os from 'node:os';
+import { TaskQueue } from './TaskQueue.js';
+const dataDir = process.env.MDOCS_DATA_DIR || path.join(os.homedir(), '.mdocs');
+const logDir = path.join(dataDir, 'task-logs');
+export const taskQueue = new TaskQueue({
+    concurrency: 2,
+    timeSliceMs: 30_000,
+    logDir,
+});
+export { TaskQueue } from './TaskQueue.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/server/task-queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/task-queue/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;AAChF,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC;IACrC,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,MAAM;IACnB,MAAM;CACP,CAAC,CAAC;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,cAAc,YAAY,CAAC"}

package/dist/server/task-queue/log-store.js

@@ -0,0 +1,84 @@
+/**
+ * 任务日志存储：JSON Lines 文件，每个任务一个文件。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class TaskLogStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    filePath(taskId) {
+        // 把 / 替换成 _，避免路径穿越
+        const safeId = taskId.replace(/\//g, '_').replace(/\.\./g, '');
+        return path.join(this.dir, `${safeId}.log`);
+    }
+    /** 清空并重新开始写（任务开始时调用） */
+    reset(taskId) {
+        const file = this.filePath(taskId);
+        fs.writeFileSync(file, '');
+    }
+    /** 追加一条日志 */
+    append(taskId, event, data, level = 'info') {
+        const entry = {
+            ts: new Date().toISOString(),
+            event,
+            level,
+            data,
+        };
+        const line = JSON.stringify(entry) + '\n';
+        try {
+            fs.appendFileSync(this.filePath(taskId), line);
+        }
+        catch {
+            // 写日志失败不影响任务执行
+        }
+    }
+    /** 读取最后 N 条日志 */
+    readTail(taskId, limit = 50) {
+        const file = this.filePath(taskId);
+        if (!fs.existsSync(file))
+            return [];
+        try {
+            const content = fs.readFileSync(file, 'utf-8');
+            const lines = content.split('\n').filter(Boolean);
+            const tail = lines.slice(-limit);
+            return tail
+                .map((line) => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((e) => e !== null);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 读取最后一条日志 */
+    readLast(taskId) {
+        const entries = this.readTail(taskId, 1);
+        return entries[0] ?? null;
+    }
+    /** 获取日志文件 mtime（用于 stale 判断） */
+    getMtime(taskId) {
+        const file = this.filePath(taskId);
+        if (!fs.existsSync(file))
+            return null;
+        try {
+            return fs.statSync(file).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 日志文件是否存在 */
+    exists(taskId) {
+        return fs.existsSync(this.filePath(taskId));
+    }
+}
+//# sourceMappingURL=log-store.js.map

package/dist/server/task-queue/log-store.js.map

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

package/dist/server/task-queue/types.js

@@ -0,0 +1,5 @@
+/**
+ * 任务队列核心类型定义。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/task-queue/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/task-queue/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/shared/docPath.js

@@ -30,8 +30,9 @@ export function normaliseDocRelativePath(input) {
         throw new DocPathError("use forward slashes");
     if (raw.includes(".."))
         throw new DocPathError("path must not contain ..");
-    if (!raw.toLowerCase().endsWith(".md")) {
-        throw new DocPathError("document path must end with .md");
+    const lower = raw.toLowerCase();
+    if (!lower.endsWith(".md") && !lower.endsWith(".json")) {
+        throw new DocPathError("document path must end with .md or .json");
     }
     if (!RELATIVE_PATH_RX.test(raw)) {
         throw new DocPathError("path contains unsupported characters");

package/dist/shared/docPath.js.map

@@ -1 +1 @@
-{"version":3,"file":"docPath.js","sourceRoot":"","sources":["../../src/shared/docPath.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAEnF,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,gBAAgB,GAAG,kCAAkC,CAAC;AAE5D,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG;YAAE,SAAS;QACxC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,IAAI,KAAK,CAAC,MAAM;gBAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QAChC,CAAC;;YAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,YAAY,CAAC,2BAA2B,CAAC,CAAC;IAC9D,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,uBAAuB,CAAC,CAAC;IACzE,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,qBAAqB,CAAC,CAAC;IACtE,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,0BAA0B,CAAC,CAAC;IAC3E,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,YAAY,CAAC,iCAAiC,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,YAAY,CAAC,sCAAsC,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,YAAY,CAAC,wBAAwB,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"docPath.js","sourceRoot":"","sources":["../../src/shared/docPath.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAEnF,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,gBAAgB,GAAG,kCAAkC,CAAC;AAE5D,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG;YAAE,SAAS;QACxC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,IAAI,KAAK,CAAC,MAAM;gBAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QAChC,CAAC;;YAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,YAAY,CAAC,2BAA2B,CAAC,CAAC;IAC9D,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,uBAAuB,CAAC,CAAC;IACzE,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,qBAAqB,CAAC,CAAC;IACtE,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,0BAA0B,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,YAAY,CAAC,0CAA0C,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,YAAY,CAAC,sCAAsC,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,YAAY,CAAC,wBAAwB,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/shared/file-types.js

@@ -0,0 +1,35 @@
+/**
+ * 统一的 file_type 定义。
+ *
+ * mdocs 文档系统中，不同类型的文件/目录通过 file_type 区分：
+ * - md / dir：普通文档和目录（文档树中可见）
+ * - folder_desc：目录描述文件（___desc___.md，文档树中不可见，用于目录展示）
+ * - graph_file / graph_dir：图谱相关文件（文档树中不可见）
+ *
+ * 新增文件类型在这里统一定义，不要散落在各处。
+ */
+export const FILE_TYPE = {
+    /** 普通 Markdown 文章（文档树中可见） */
+    DOCUMENT: 'md',
+    /** 普通目录（文档树中可见） */
+    FOLDER: 'dir',
+    /** 目录描述文件 ___desc___.md（文档树中不可见，用于展示目录介绍） */
+    FOLDER_DESC: 'folder_desc',
+    /** 图谱 JSON 文件（文档树中不可见） */
+    GRAPH_FILE: 'graph_file',
+    /** 图谱缓存目录 __graph__（文档树中不可见） */
+    GRAPH_DIR: 'graph_dir',
+};
+/** 判断是否是文档树中可见的类型（普通 md 文件 + 目录） */
+export function isVisibleFileType(fileType) {
+    return fileType === FILE_TYPE.DOCUMENT || fileType === FILE_TYPE.FOLDER;
+}
+/** 判断是否是目录类型（普通目录或特殊目录） */
+export function isFolderFileType(fileType) {
+    return fileType === FILE_TYPE.FOLDER || fileType === FILE_TYPE.GRAPH_DIR;
+}
+/** 判断是否是图谱相关的文件类型 */
+export function isGraphFileType(fileType) {
+    return fileType === FILE_TYPE.GRAPH_FILE || fileType === FILE_TYPE.GRAPH_DIR;
+}
+//# sourceMappingURL=file-types.js.map

package/dist/shared/file-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-types.js","sourceRoot":"","sources":["../../src/shared/file-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,6BAA6B;IAC7B,QAAQ,EAAE,IAAI;IACd,mBAAmB;IACnB,MAAM,EAAE,KAAK;IACb,6CAA6C;IAC7C,WAAW,EAAE,aAAa;IAC1B,0BAA0B;IAC1B,UAAU,EAAE,YAAY;IACxB,gCAAgC;IAChC,SAAS,EAAE,WAAW;CACd,CAAC;AAIX,oCAAoC;AACpC,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,QAAQ,KAAK,SAAS,CAAC,QAAQ,IAAI,QAAQ,KAAK,SAAS,CAAC,MAAM,CAAC;AAC1E,CAAC;AAED,2BAA2B;AAC3B,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,QAAQ,KAAK,SAAS,CAAC,MAAM,IAAI,QAAQ,KAAK,SAAS,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,qBAAqB;AACrB,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,QAAQ,KAAK,SAAS,CAAC,UAAU,IAAI,QAAQ,KAAK,SAAS,CAAC,SAAS,CAAC;AAC/E,CAAC"}

package/dist/shared/graph-files.js

@@ -0,0 +1,31 @@
+/**
+ * 知识图谱相关的特殊文件名与工具函数。
+ *
+ * 图谱隐藏文件/目录在文档树中不可见，file_type 统一在 shared/file-types.ts 定义。
+ * 本文件只放文件名常量和路径判断函数。
+ */
+import { FILE_TYPE } from './file-types.js';
+/** 目录级图谱文件名（每个目录一个） */
+export const DIR_GRAPH_FILENAME = '___graph___.json';
+/** 文章级图谱缓存目录名（每个目录下一个） */
+export const ARTICLE_GRAPH_DIRNAME = '__graph__';
+/** 文章级图谱文件后缀 */
+export const ARTICLE_GRAPH_FILE_SUFFIX = '.graph.json';
+/** 兼容旧引用：graph_file / graph_dir 常量 */
+export const GRAPH_FILE_TYPE = {
+    FILE: FILE_TYPE.GRAPH_FILE,
+    DIR: FILE_TYPE.GRAPH_DIR,
+};
+/** 判断文件名是否是目录级图谱文件 */
+export function isDirGraphFile(name) {
+    return name.toLowerCase() === DIR_GRAPH_FILENAME.toLowerCase();
+}
+/** 判断目录名是否是文章级图谱缓存目录 */
+export function isArticleGraphDir(name) {
+    return name.toLowerCase() === ARTICLE_GRAPH_DIRNAME.toLowerCase();
+}
+/** 生成文章级图谱文件的文件名 */
+export function articleGraphFileName(documentId) {
+    return `${documentId}${ARTICLE_GRAPH_FILE_SUFFIX}`;
+}
+//# sourceMappingURL=graph-files.js.map

package/dist/shared/graph-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-files.js","sourceRoot":"","sources":["../../src/shared/graph-files.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,uBAAuB;AACvB,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAErD,0BAA0B;AAC1B,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAEjD,gBAAgB;AAChB,MAAM,CAAC,MAAM,yBAAyB,GAAG,aAAa,CAAC;AAEvD,sCAAsC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,SAAS,CAAC,UAAU;IAC1B,GAAG,EAAE,SAAS,CAAC,SAAS;CAChB,CAAC;AAIX,sBAAsB;AACtB,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,kBAAkB,CAAC,WAAW,EAAE,CAAC;AACjE,CAAC;AAED,wBAAwB;AACxB,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,qBAAqB,CAAC,WAAW,EAAE,CAAC;AACpE,CAAC;AAED,oBAAoB;AACpB,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,OAAO,GAAG,UAAU,GAAG,yBAAyB,EAAE,CAAC;AACrD,CAAC"}