@cc-monitoring/proxy-core 0.3.1 → 0.4.0

package/dist/utils/__tests__/request-writer.test.js

@@ -1,48 +1,280 @@
-import { saveRequestDB, loadRequestDB, listRequestDB, cleanOldRequestsDB } from '../request-writer.js';
-import { initDatabase, closeDatabase } from '../db.js';
-describe('request-writer-db', () => {
-    beforeAll(() => {
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import path from 'path';
+import { configureDbPath, initDatabase, closeDatabase, getDatabase } from '../db.js';
+import { createRequestRecorder, recordIteration, listRequestDB, interruptStaleRequestsOnStartup } from '../request-writer.js';
+import { pushNewRequest } from '../../server/data-push.js';
+jest.mock('../../server/data-push.js', () => ({ pushNewRequest: jest.fn() }));
+const pushMock = pushNewRequest;
+let counter = 0;
+function makeMeta(tag) {
+    counter += 1;
+    const unique = `${tag}_${counter}`;
+    return {
+        sessionId: `sess_${unique}`,
+        localRequestId: `local_${unique}`,
+        timestamp: new Date().toISOString(),
+        apiKey: 'ak',
+        proxyApiKey: 'pak',
+        baseUrl: 'https://api.example.com',
+        model: 'claude-test',
+        machineId: 'mid',
+        request: {
+            method: 'POST',
+            path: '/v1/messages',
+            headers: { 'user-agent': 'ua-test' },
+            body: { hello: 'world' }
+        }
+    };
+}
+function getRequestRow(requestId, sessionId) {
+    return getDatabase()
+        .prepare('SELECT * FROM requests WHERE request_id = ? AND session_id = ?')
+        .get(requestId, sessionId);
+}
+function getEventRows(requestId, sessionId) {
+    return getDatabase()
+        .prepare('SELECT * FROM response_events WHERE request_id = ? AND session_id = ? ORDER BY event_index ASC')
+        .all(requestId, sessionId);
+}
+describe('request-writer', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = mkdtempSync(path.join(tmpdir(), 'ccm-rw-'));
+        configureDbPath(path.join(tempDir, 'test.db'));
         initDatabase();
+        pushMock.mockClear();
     });
-    afterAll(() => {
+    afterEach(() => {
         closeDatabase();
+        rmSync(tempDir, { recursive: true, force: true });
     });
-    it('should save request data to SQLite', async () => {
-        const data = {
-            requestId: 'test-123',
-            sessionId: 'session-1',
-            timestamp: '2026-06-22T10:00:00Z',
-            apiKey: 'original-key',
-            proxyApiKey: 'proxy-key',
-            baseUrl: 'https://example.com',
-            model: 'claude-3-5-sonnet',
-            request: {
-                method: 'POST',
-                path: '/v1/messages',
-                headers: { 'content-type': 'application/json' },
-                body: { test: true }
-            },
+    it('pending() inserts a status_code=0 row and pushes pending', async () => {
+        const meta = makeMeta('pending');
+        const rec = createRequestRecorder(meta);
+        await rec.pending();
+        const row = getRequestRow(meta.localRequestId, meta.sessionId);
+        expect(row).toBeTruthy();
+        expect(row.status_code).toBe(0);
+        expect(pushMock).toHaveBeenCalledTimes(1);
+        expect(pushMock).toHaveBeenCalledWith(expect.objectContaining({
+            requestId: meta.localRequestId,
+            compositeId: `${meta.sessionId}:${meta.localRequestId}`,
+            statusCode: 0,
+            responseTime: 0
+        }), 'pending');
+    });
+    it('appendEvent flushes full batches of 10; complete flushes residual events with continuous indexes', async () => {
+        const meta = makeMeta('append');
+        const rec = createRequestRecorder(meta);
+        for (let i = 0; i < 12; i++) {
+            rec.appendEvent({ type: 'chunk', seq: i });
+        }
+        // Without complete: only the full first batch is persisted, indexes 0..9
+        let rows = getEventRows(meta.localRequestId, meta.sessionId);
+        expect(rows).toHaveLength(10);
+        expect(rows.map(r => r.event_index)).toEqual(Array.from({ length: 10 }, (_, i) => i));
+        // Residual 2 events land at complete, full sequence 0..11 continuous
+        await rec.complete({ statusCode: 200 });
+        rows = getEventRows(meta.localRequestId, meta.sessionId);
+        expect(rows).toHaveLength(12);
+        expect(rows.map(r => r.event_index)).toEqual(Array.from({ length: 12 }, (_, i) => i));
+    });
+    it('complete() with same id writes completed row, token columns and pushes completed without pendingId', async () => {
+        const meta = makeMeta('same');
+        const rec = createRequestRecorder(meta);
+        await rec.pending();
+        rec.appendEvent({ type: 'message_start' });
+        rec.appendEvent({
+            type: 'message_delta',
+            usage: {
+                input_tokens: 10,
+                output_tokens: 5,
+                cache_read_input_tokens: 2,
+                cache_creation_input_tokens: 1
+            }
+        });
+        await rec.complete({ statusCode: 200, headers: { 'x-test': '1' } });
+        const row = getRequestRow(meta.localRequestId, meta.sessionId);
+        expect(row.status_code).toBe(200);
+        expect(row.completed_at).toBeTruthy();
+        expect(row.input_tokens).toBe(10);
+        expect(row.output_tokens).toBe(5);
+        expect(row.cache_read_tokens).toBe(2);
+        expect(row.cache_creation_tokens).toBe(1);
+        const completedCalls = pushMock.mock.calls.filter(c => c[1] === 'completed');
+        expect(completedCalls).toHaveLength(1);
+        const summary = completedCalls[0][0];
+        expect(summary.statusCode).toBe(200);
+        expect(summary.usage.output_tokens).toBe(5);
+        expect(summary.pendingId).toBeUndefined();
+    });
+    it('complete() with a different cloud id moves requests row and events to cloud id and pushes pendingId', async () => {
+        const meta = makeMeta('cloud');
+        counter += 1;
+        const cloudId = `cloud_${counter}`;
+        const rec = createRequestRecorder(meta);
+        await rec.pending();
+        for (let i = 0; i < 12; i++) {
+            rec.appendEvent({ type: 'chunk', seq: i });
+        }
+        await rec.complete({ cloudRequestId: cloudId, statusCode: 200 });
+        // Local row and local events are gone
+        expect(getRequestRow(meta.localRequestId, meta.sessionId)).toBeFalsy();
+        expect(getEventRows(meta.localRequestId, meta.sessionId)).toHaveLength(0);
+        // Cloud row exists and is completed
+        const cloudRow = getRequestRow(cloudId, meta.sessionId);
+        expect(cloudRow).toBeTruthy();
+        expect(cloudRow.status_code).toBe(200);
+        // Events moved with continuous indexes
+        const cloudEvents = getEventRows(cloudId, meta.sessionId);
+        expect(cloudEvents).toHaveLength(12);
+        expect(cloudEvents.map(r => r.event_index)).toEqual(Array.from({ length: 12 }, (_, i) => i));
+        const completedCalls = pushMock.mock.calls.filter(c => c[1] === 'completed');
+        expect(completedCalls).toHaveLength(1);
+        const summary = completedCalls[0][0];
+        expect(summary.requestId).toBe(cloudId);
+        expect(summary.pendingId).toBe(`${meta.sessionId}:${meta.localRequestId}`);
+    });
+    it('fail() updates the pending row status/error/closed_at and pushes completed', async () => {
+        const meta = makeMeta('fail');
+        const rec = createRequestRecorder(meta);
+        await rec.pending();
+        rec.fail({ statusCode: 502, error: 'Target server unreachable' });
+        const row = getRequestRow(meta.localRequestId, meta.sessionId);
+        expect(row).toBeTruthy();
+        expect(row.status_code).toBe(502);
+        expect(row.error).toBe('Target server unreachable');
+        expect(row.closed_at).toBeTruthy();
+        expect(row.status_code).not.toBe(0);
+        const completedCalls = pushMock.mock.calls.filter(c => c[1] === 'completed');
+        expect(completedCalls).toHaveLength(1);
+    });
+    it('recordIteration() writes a completed row and events with no pending row', async () => {
+        const meta = makeMeta('iter');
+        await recordIteration({
+            ...meta,
             response: {
                 statusCode: 200,
-                events: [{ type: 'test' }]
+                events: [
+                    { type: 'message', content: [] },
+                    { type: 'message_delta', usage: { output_tokens: 7 } }
+                ]
             }
-        };
-        await saveRequestDB('session-1', 'test-123', data);
-        const loaded = await loadRequestDB('session-1:test-123');
-        expect(loaded.requestId).toBe('test-123');
-        expect(loaded.sessionId).toBe('session-1');
-        expect(loaded.apiKey).toBe('original-key');
-        expect(loaded.proxyApiKey).toBe('proxy-key');
-        expect(loaded.baseUrl).toBe('https://example.com');
-        expect(loaded.model).toBe('claude-3-5-sonnet');
-    });
-    it('should list requests summary', async () => {
-        const result = await listRequestDB();
-        expect(result.requests.length).toBeGreaterThan(0);
-        expect(result.requests[0].compositeId).toBeDefined();
-    });
-    it('should clean old requests', async () => {
-        await cleanOldRequestsDB(7);
-        // Should not throw
+        });
+        const row = getRequestRow(meta.localRequestId, meta.sessionId);
+        expect(row).toBeTruthy();
+        expect(row.status_code).toBe(200);
+        expect(row.completed_at).toBeTruthy();
+        expect(getEventRows(meta.localRequestId, meta.sessionId)).toHaveLength(2);
+        const pendingCount = getDatabase()
+            .prepare('SELECT COUNT(*) AS c FROM requests WHERE status_code = 0')
+            .get().c;
+        expect(pendingCount).toBe(0);
+        const completedCalls = pushMock.mock.calls.filter(c => c[1] === 'completed');
+        expect(completedCalls).toHaveLength(1);
+        expect(completedCalls[0][0].pendingId).toBeUndefined();
+    });
+    it('complete() synthesizes message_delta from OpenAI usage and persists output_tokens=42', async () => {
+        const meta = makeMeta('openai');
+        const rec = createRequestRecorder(meta);
+        await rec.pending();
+        rec.appendEvent({ type: 'chat.completion.chunk' });
+        rec.appendEvent({ type: 'chat.completion', usage: { prompt_tokens: 8, completion_tokens: 42 } });
+        await rec.complete({ statusCode: 200 });
+        const row = getRequestRow(meta.localRequestId, meta.sessionId);
+        expect(row.output_tokens).toBe(42);
+        const deltaRows = getEventRows(meta.localRequestId, meta.sessionId)
+            .filter(r => r.event_type === 'message_delta');
+        expect(deltaRows.length).toBeGreaterThan(0);
+        const parsed = JSON.parse(deltaRows[deltaRows.length - 1].event_data);
+        expect(parsed.type).toBe('message_delta');
+        expect(parsed.usage.output_tokens).toBe(42);
+    });
+    it('headers() writes real status_code while completed_at stays NULL and pushes pending', async () => {
+        const meta = makeMeta('headers');
+        const rec = createRequestRecorder(meta);
+        await rec.pending();
+        pushMock.mockClear();
+        rec.headers({ statusCode: 200, headers: { 'content-type': 'text/event-stream' } });
+        const row = getRequestRow(meta.localRequestId, meta.sessionId);
+        expect(row.status_code).toBe(200);
+        expect(row.completed_at).toBeNull();
+        expect(row.closed_at).toBeNull();
+        expect(JSON.parse(row.response_headers)['content-type']).toBe('text/event-stream');
+        expect(pushMock).toHaveBeenCalledTimes(1);
+        expect(pushMock).toHaveBeenCalledWith(expect.objectContaining({ requestId: meta.localRequestId, statusCode: 200, responseTime: 0 }), 'pending');
+    });
+    it('interrupt() flushes events and writes closed_at/error keeping passed status_code, pushes completed with closedAt', async () => {
+        const meta = makeMeta('interrupt');
+        const rec = createRequestRecorder(meta);
+        await rec.pending();
+        rec.appendEvent({ type: 'chunk', seq: 1 });
+        pushMock.mockClear();
+        rec.interrupt({ statusCode: 200, error: 'stream interrupted: socket hang up' });
+        const row = getRequestRow(meta.localRequestId, meta.sessionId);
+        expect(row.status_code).toBe(200);
+        expect(row.completed_at).toBeNull();
+        expect(row.closed_at).toBeTruthy();
+        expect(row.error).toBe('stream interrupted: socket hang up');
+        // 剩余事件在中断前已落库
+        expect(getEventRows(meta.localRequestId, meta.sessionId)).toHaveLength(1);
+        expect(pushMock).toHaveBeenCalledTimes(1);
+        expect(pushMock).toHaveBeenCalledWith(expect.objectContaining({
+            requestId: meta.localRequestId,
+            statusCode: 200,
+            closedAt: expect.any(String)
+        }), 'completed');
+    });
+    it('listRequestDB maps closed_at to closedAt only on closed rows', async () => {
+        const closedMeta = makeMeta('listclosed');
+        const closedRec = createRequestRecorder(closedMeta);
+        await closedRec.pending();
+        closedRec.interrupt({ statusCode: 200, error: 'boom' });
+        const openMeta = makeMeta('listopen');
+        const openRec = createRequestRecorder(openMeta);
+        await openRec.pending();
+        await openRec.complete({ statusCode: 200 });
+        const { requests } = await listRequestDB();
+        const closed = requests.find(r => r.requestId === closedMeta.localRequestId);
+        const open = requests.find(r => r.requestId === openMeta.localRequestId);
+        expect(closed).toBeTruthy();
+        expect(closed.closedAt).toEqual(expect.any(String));
+        expect(open).toBeTruthy();
+        expect(open.closedAt).toBeUndefined();
+    });
+    it('interruptStaleRequestsOnStartup() marks aged orphan rows and leaves fresh/completed rows untouched', async () => {
+        // 超龄无主行：已收到响应头（200），时间戳回拨到 6 分钟前
+        const oldMeta = makeMeta('staleold');
+        const oldRec = createRequestRecorder(oldMeta);
+        await oldRec.pending();
+        oldRec.headers({ statusCode: 200 });
+        getDatabase()
+            .prepare('UPDATE requests SET timestamp = ? WHERE request_id = ? AND session_id = ?')
+            .run(new Date(Date.now() - 6 * 60000).toISOString(), oldMeta.localRequestId, oldMeta.sessionId);
+        // 刚 pending 的新行，不超龄
+        const freshMeta = makeMeta('stalefresh');
+        const freshRec = createRequestRecorder(freshMeta);
+        await freshRec.pending();
+        // 超龄但已完成的行
+        const doneMeta = makeMeta('staledone');
+        const doneRec = createRequestRecorder(doneMeta);
+        await doneRec.pending();
+        await doneRec.complete({ statusCode: 200 });
+        getDatabase()
+            .prepare('UPDATE requests SET timestamp = ? WHERE request_id = ? AND session_id = ?')
+            .run(new Date(Date.now() - 6 * 60000).toISOString(), doneMeta.localRequestId, doneMeta.sessionId);
+        const count = interruptStaleRequestsOnStartup();
+        expect(count).toBe(1);
+        const oldRow = getRequestRow(oldMeta.localRequestId, oldMeta.sessionId);
+        expect(oldRow.closed_at).toBeTruthy();
+        expect(oldRow.error).toBe('interrupted: proxy restarted');
+        expect(oldRow.status_code).toBe(200);
+        expect(oldRow.completed_at).toBeNull();
+        const freshRow = getRequestRow(freshMeta.localRequestId, freshMeta.sessionId);
+        expect(freshRow.closed_at).toBeNull();
+        expect(freshRow.error).toBeNull();
+        const doneRow = getRequestRow(doneMeta.localRequestId, doneMeta.sessionId);
+        expect(doneRow.closed_at).toBeNull();
     });
 });

package/dist/utils/__tests__/sse-protocol.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/sse-protocol.test.js

@@ -0,0 +1,115 @@
+import { createSSEDecoder, createEventDecoder, encodeSSEFrame } from '../sse-protocol.js';
+// 收集分发帧的辅助
+function collectFrames() {
+    const frames = [];
+    const decoder = createSSEDecoder((frame) => frames.push(frame));
+    return { frames, decoder };
+}
+describe('sse-protocol', () => {
+    // 样例 1：单帧含 event: + data:
+    it('1. 单帧含 event 和 data', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write('event: foo\ndata: {"a":1}\n\n');
+        expect(frames).toEqual([
+            { event: 'foo', data: ['{"a":1}'], id: undefined }
+        ]);
+    });
+    // 样例 2：仅 data:（event 为 undefined）
+    it('2. 仅 data，event 缺省为 undefined', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write('data: {"b":2}\n\n');
+        expect(frames).toEqual([
+            { event: undefined, data: ['{"b":2}'], id: undefined }
+        ]);
+    });
+    // 样例 3：一个 data 行切成 3 个 chunk（残帧缓冲）
+    it('3. data 行跨 3 个 chunk 恰好得到一帧', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write('dat');
+        expect(frames).toHaveLength(0);
+        decoder.write('a: {"x');
+        expect(frames).toHaveLength(0);
+        decoder.write('":1}\n\n');
+        expect(frames).toEqual([
+            { event: undefined, data: ['{"x":1}'], id: undefined }
+        ]);
+    });
+    // 样例 4：CRLF 行尾 + 空行分帧
+    it('4. CRLF 行尾与空行分帧', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write('event: ping\r\ndata: {"y":2}\r\n\r\n');
+        expect(frames).toEqual([
+            { event: 'ping', data: ['{"y":2}'], id: undefined }
+        ]);
+    });
+    // 样例 5：同一帧内多行 data:，数组保留两行，消费 join('\n') 正确
+    it('5. 多行 data 逐行保留且 join 正确', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write('data: line1\ndata: line2\n\n');
+        expect(frames).toHaveLength(1);
+        expect(frames[0].data).toEqual(['line1', 'line2']);
+        expect(frames[0].data.join('\n')).toBe('line1\nline2');
+    });
+    // 样例 6：注释行不产生帧
+    it('6. 注释行被忽略不产生帧', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write(': ping\n\n');
+        expect(frames).toHaveLength(0);
+        // 注释与真实帧混合时仅真实帧分发
+        decoder.write(': keep-alive\ndata: {"r":1}\n\n');
+        expect(frames).toEqual([
+            { event: undefined, data: ['{"r":1}'], id: undefined }
+        ]);
+    });
+    // 样例 7：data: [DONE] → onDone 触发、onEvent 不触发
+    it('7. [DONE] 仅触发 onDone', () => {
+        const events = [];
+        let doneCount = 0;
+        const decoder = createEventDecoder((e) => events.push(e), () => { doneCount++; });
+        decoder.write('data: [DONE]\n\n');
+        expect(events).toHaveLength(0);
+        expect(doneCount).toBe(1);
+    });
+    // 样例 8：非 JSON data → onEvent 不触发、不抛错
+    it('8. 非 JSON data 静默跳过', () => {
+        const events = [];
+        const decoder = createEventDecoder((e) => events.push(e));
+        expect(() => {
+            decoder.write('data: not-json\n\n');
+        }).not.toThrow();
+        expect(events).toHaveLength(0);
+    });
+    // 样例 9：末尾帧无尾空行，write 不触发，end() 后恰好一帧
+    it('9. end() 输出末尾无空行的残留帧', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write('data: {"z":9}');
+        expect(frames).toHaveLength(0);
+        decoder.end();
+        expect(frames).toEqual([
+            { event: undefined, data: ['{"z":9}'], id: undefined }
+        ]);
+    });
+    // 样例 10：id: 行保留在帧 id 字段
+    it('10. id 字段保留在帧上', () => {
+        const { frames, decoder } = collectFrames();
+        decoder.write('id: e1\ndata: {"i":1}\n\n');
+        expect(frames).toEqual([
+            { event: undefined, data: ['{"i":1}'], id: 'e1' }
+        ]);
+    });
+    // 样例 11：encodeSSEFrame → createSSEDecoder 往返一致（有/无 event）
+    it('11. encode/decode 往返帧内容一致（有 event 和无 event）', () => {
+        const withEvent = encodeSSEFrame({ event: 'foo', data: '{"x":1}' });
+        const d1 = collectFrames();
+        d1.decoder.write(withEvent);
+        expect(d1.frames).toEqual([
+            { event: 'foo', data: ['{"x":1}'], id: undefined }
+        ]);
+        const withoutEvent = encodeSSEFrame({ data: '{"x":2}' });
+        const d2 = collectFrames();
+        d2.decoder.write(withoutEvent);
+        expect(d2.frames).toEqual([
+            { event: undefined, data: ['{"x":2}'], id: undefined }
+        ]);
+    });
+});

package/dist/utils/__tests__/vault.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/{knowledge-store.test.js → vault.test.js}

@@ -1,7 +1,7 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { createKnowledgeStore } from '../knowledge-store.js';
+import { createVault } from '../vault.js';
 async function makeTmpDocs() {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-test-'));
     // 根 index.json
@@ -22,10 +22,10 @@ async function makeTmpDocs() {
     await fs.writeFile(path.join(dir, 'react-hooks', 'chunks', 'chunk-001.md'), '# 状态管理：useState\n\nuseState 用于组件状态。', 'utf8');
     return dir;
 }
-describe('knowledge-store', () => {
+describe('vault', () => {
     it('listTopics 解析根 index.json', async () => {
         const root = await makeTmpDocs();
-        const store = createKnowledgeStore(root);
+        const store = createVault(root);
         const topics = await store.listTopics();
         expect(topics).toEqual([
             { slug: 'react-hooks', title: 'React Hooks 参考', summary: 'React hooks 用法', tags: ['react', 'hooks'] },
@@ -33,12 +33,12 @@ describe('knowledge-store', () => {
     });
     it('listTopics 根 index.json 不存在返回空数组', async () => {
         const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-empty-'));
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         expect(await store.listTopics()).toEqual([]);
     });
     it('getTopic 返回元数据 + 片段清单', async () => {
         const root = await makeTmpDocs();
-        const store = createKnowledgeStore(root);
+        const store = createVault(root);
         const detail = await store.getTopic('react-hooks');
         expect(detail.title).toBe('React Hooks 参考');
         expect(detail.tags).toEqual(['react', 'hooks']);
@@ -46,25 +46,25 @@ describe('knowledge-store', () => {
     });
     it('readChunk 返回单片正文', async () => {
         const root = await makeTmpDocs();
-        const store = createKnowledgeStore(root);
+        const store = createVault(root);
         const text = await store.readChunk('react-hooks', 'chunk-001');
         expect(text).toContain('useState 用于组件状态');
     });
     it('readChunk 拒绝路径穿越', async () => {
         const root = await makeTmpDocs();
-        const store = createKnowledgeStore(root);
+        const store = createVault(root);
         await expect(store.readChunk('..', 'chunk-001')).rejects.toThrow();
         await expect(store.readChunk('react-hooks', '../chunk-001')).rejects.toThrow();
     });
     it('searchChunks 关键词命中返回清单', async () => {
         const root = await makeTmpDocs();
-        const store = createKnowledgeStore(root);
+        const store = createVault(root);
         const hits = await store.searchChunks('useState');
         expect(hits).toEqual([{ topic: 'react-hooks', chunkId: 'chunk-001', title: '状态管理：useState' }]);
     });
     it('upsertTopic 两次不同 slug → listTopics 返回 2 条，不覆盖', async () => {
         const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-upsert-'));
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         await store.upsertTopic({ slug: 'topic-a', title: 'A', summary: 'sa', tags: [] });
         await store.upsertTopic({ slug: 'topic-b', title: 'B', summary: 'sb', tags: ['x'] });
         const topics = await store.listTopics();
@@ -73,7 +73,7 @@ describe('knowledge-store', () => {
     });
     it('upsertTopic 同 slug 再调更新 summary，chunks 数组不变，listTopics 仍 1 条', async () => {
         const root = await makeTmpDocs();
-        const store = createKnowledgeStore(root);
+        const store = createVault(root);
         // 先登记一个额外 chunk ref
         await store.upsertChunkRef({ topic: 'react-hooks', chunkId: 'chunk-002', title: 'T2', summary: 'S2', tags: [] });
         await store.upsertTopic({
@@ -92,7 +92,7 @@ describe('knowledge-store', () => {
     });
     it('upsertChunkRef 同 topic 两次不同 chunk_id → getTopic 返回 2 chunks', async () => {
         const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-chunk-'));
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         await store.upsertTopic({ slug: 't1', title: 'T1', summary: 's', tags: [] });
         await store.upsertChunkRef({ topic: 't1', chunkId: 'chunk-001', title: 'c1', summary: 's1', tags: [] });
         await store.upsertChunkRef({ topic: 't1', chunkId: 'chunk-002', title: 'c2', summary: 's2', tags: [] });
@@ -102,12 +102,12 @@ describe('knowledge-store', () => {
     });
     it('upsertChunkRef topic 不存在 → rejects', async () => {
         const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-no-topic-'));
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         await expect(store.upsertChunkRef({ topic: 'ghost', chunkId: 'chunk-001', title: 'c', summary: 's', tags: [] })).rejects.toThrow(/topic not found: ghost/);
     });
     it('tags: upsertChunkRef 落盘 tags，重复调用覆写 tags', async () => {
         const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-tags-'));
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         await store.upsertTopic({ slug: 't1', title: 'T1', summary: 's', tags: [] });
         await store.upsertChunkRef({ topic: 't1', chunkId: 'chunk-001', title: 'c1', summary: 's1', tags: ['redis', '缓存'] });
         // 落盘验证
@@ -128,7 +128,7 @@ describe('knowledge-store', () => {
             slug: 'old', title: 'Old', summary: 'so', tags: [],
             chunks: [{ id: 'chunk-001', title: 'oc', summary: 'os' }],
         }), 'utf8');
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         const detail = await store.getTopic('old');
         expect(detail.chunks[0].tags).toEqual([]);
     });
@@ -144,7 +144,7 @@ describe('knowledge-store', () => {
         }), 'utf8');
         await fs.writeFile(path.join(dir, 'redis', 'chunks', 'chunk-001.md'), '# 缓存详解\n\n正文讲缓存。', 'utf8');
         await fs.writeFile(path.join(dir, 'redis', 'chunks', 'chunk-002.md'), '# 故障转移\n\n正文讲哨兵。', 'utf8');
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         // body
         expect(await store.searchChunks('缓存')).toEqual([
             { topic: 'redis', chunkId: 'chunk-001', title: '缓存详解' },
@@ -177,7 +177,7 @@ describe('knowledge-store', () => {
             chunks: [{ id: 'chunk-001', title: '缓存详解', summary: '缓存摘要' }],
         }), 'utf8');
         await fs.writeFile(path.join(dir, 'redis', 'chunks', 'chunk-001.md'), '# 缓存详解\n\n正文讲缓存。', 'utf8');
-        const store = createKnowledgeStore(dir);
+        const store = createVault(dir);
         expect(await store.searchChunks('缓存')).toEqual([
             { topic: 'redis', chunkId: 'chunk-001', title: '缓存详解' },
         ]);

package/dist/utils/abort-signals.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage } from 'node:http';
+/**
+ * 监听 Node IncomingMessage，客户端在响应结束前中止连接时 abort 返回的 signal。
+ * close 时以 req.aborted 区分：true=客户端侧中止；正常响应结束后的 close 为 false。
+ */
+export declare function createClientAbortSignal(req: IncomingMessage): AbortSignal;
+/** 合成：固定超时 + 外部取消，任意触发即 abort */
+export declare function createTimeoutSignal(ms: number, external?: AbortSignal): AbortSignal;
+/**
+ * 把 source signal 接到 abortFn：source 已 abort 立即调，否则将来 abort 时调一次。
+ * abortFn 异步拒绝不外泄（由调用方保证幂等）。
+ */
+export declare function bindAbort(source: AbortSignal, abortFn: () => Promise<void>): void;

package/dist/utils/abort-signals.js

@@ -0,0 +1,33 @@
+/**
+ * 监听 Node IncomingMessage，客户端在响应结束前中止连接时 abort 返回的 signal。
+ * close 时以 req.aborted 区分：true=客户端侧中止；正常响应结束后的 close 为 false。
+ */
+export function createClientAbortSignal(req) {
+    const controller = new AbortController();
+    // 传入时已 aborted（或已 close 过）：立即 abort，不再依赖 close 事件
+    if (req.aborted) {
+        controller.abort();
+        return controller.signal;
+    }
+    req.on('close', () => {
+        if (req.aborted)
+            controller.abort();
+    });
+    return controller.signal;
+}
+/** 合成：固定超时 + 外部取消，任意触发即 abort */
+export function createTimeoutSignal(ms, external) {
+    return AbortSignal.any([AbortSignal.timeout(ms), ...(external ? [external] : [])]);
+}
+/**
+ * 把 source signal 接到 abortFn：source 已 abort 立即调，否则将来 abort 时调一次。
+ * abortFn 异步拒绝不外泄（由调用方保证幂等）。
+ */
+export function bindAbort(source, abortFn) {
+    if (source.aborted) {
+        abortFn().catch(() => { });
+    }
+    else {
+        source.addEventListener('abort', () => abortFn().catch(() => { }), { once: true });
+    }
+}

package/dist/utils/db.d.ts

@@ -10,5 +10,6 @@ export declare function applySchemaV7(db: Database.Database): void;
 export declare function applySchemaV8(db: Database.Database): void;
 export declare function applySchemaV9(db: Database.Database): void;
 export declare function applySchemaV10(db: Database.Database): void;
+export declare function applySchemaV11(db: Database.Database): void;
 export declare function closeDatabase(): void;
 export declare function getDatabase(): Database.Database;

package/dist/utils/db.js

@@ -72,6 +72,10 @@ export function initDatabase() {
         applySchemaV10(db);
         db.prepare('INSERT OR REPLACE INTO schema_version (version) VALUES (10)').run();
     }
+    if (currentVersion < 11) {
+        applySchemaV11(db);
+        db.prepare('INSERT OR REPLACE INTO schema_version (version) VALUES (11)').run();
+    }
     return db;
 }
 export function applySchemaV2(db) {
@@ -280,6 +284,26 @@ export function applySchemaV10(db) {
     WHERE user_agent IS NULL AND request_headers IS NOT NULL
   `).run();
 }
+export function applySchemaV11(db) {
+    // learn 流水线状态机落库：文件操作前插 running，结束转 completed/failed/aborted；
+    // 服务启动时无主 running 回收为 crashed。partial unique index 硬守同 slug 并发运行。
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS learn_tasks (
+      task_id TEXT PRIMARY KEY,
+      slug TEXT NOT NULL,
+      source_type TEXT NOT NULL,
+      label TEXT NOT NULL,
+      status TEXT NOT NULL,
+      error TEXT,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      ended_at TEXT
+    )
+  `);
+    db.exec(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_learn_tasks_running_slug
+      ON learn_tasks(slug) WHERE status = 'running'
+  `);
+}
 export function closeDatabase() {
     if (db) {
         db.close();