@cc-monitoring/proxy-core 0.3.1 → 0.4.1

package/dist/utils/inject-loop.js

@@ -1,22 +1,4 @@
 import { findEnabledTool } from '../tools/index.js';
-/** 解析上游 SSE 全文 -> 事件数组（收集 data: 行的 JSON） */
-export function parseSSEText(text) {
-    const events = [];
-    for (const line of text.split('\n')) {
-        if (line.startsWith('data:')) {
-            const d = line.slice(5).trim();
-            if (d && d !== '[DONE]') {
-                try {
-                    events.push(JSON.parse(d));
-                }
-                catch {
-                    // 非 JSON 行跳过
-                }
-            }
-        }
-    }
-    return events;
-}
 /** 从事件数组重建有序内容块 + stop_reason + usage */
 export function parseUpstreamEvents(events) {
     const blocks = new Map();
@@ -82,42 +64,6 @@ function blocksToAssistantContent(blocks) {
     }
     return content;
 }
-function collectText(parsed) {
-    return parsed.blocks
-        .filter((b) => b.type === 'text' && b.text)
-        .map((b) => b.text)
-        .join('');
-}
-/**
- * SSE 内部循环：命中已启用 tool -> 执行 exec -> 追加对话 -> 再调上游 -> 直到 end_turn。
- * opts.body 会被原地追加 messages。
- *
- * @param opts.events 首次上游响应事件（已确认命中注入 tool）
- * @param opts.callUpstream 用给定 body 再次调上游，返回事件数组
- * @param opts.maxIterations 死循环护栏（tool 描述可能诱导模型反复调用）
- */
-export async function runInjectLoop(opts) {
-    const maxIterations = opts.maxIterations ?? 3;
-    let parsed = parseUpstreamEvents(opts.events);
-    let iterations = 0;
-    while (iterations < maxIterations) {
-        const call = findInjectedCall(parsed);
-        if (!call || parsed.stopReason !== 'tool_use') {
-            return { text: collectText(parsed), iterations, stoppedByLimit: false };
-        }
-        const tool = findEnabledTool(call.name);
-        const result = await tool.exec(call.input);
-        opts.body.messages.push({ role: 'assistant', content: blocksToAssistantContent(parsed.blocks) });
-        opts.body.messages.push({
-            role: 'user',
-            content: [{ type: 'tool_result', tool_use_id: call.id, content: result }]
-        });
-        const nextEvents = await opts.callUpstream(opts.body);
-        parsed = parseUpstreamEvents(nextEvents);
-        iterations++;
-    }
-    return { text: collectText(parsed) || '(内部循环达到最大轮次)', iterations, stoppedByLimit: true };
-}
 export async function runStreamingInjectLoop(opts) {
     const maxIterations = opts.maxIterations ?? 3;
     let parsed = opts.initialParsed;
@@ -144,8 +90,9 @@ export async function runStreamingInjectLoop(opts) {
         const { processor, statusCode } = await opts.streamAndParse(response);
         // 保存这次迭代到 DB
         await opts.saveIterationDB(requestId, processor, statusCode, opts.body);
-        parsed = processor.getParsedUpstream();
+        // 先收尾残帧再取解析结果，保证最后一帧参与解析
         processor.flushLeftover();
+        parsed = processor.getParsedUpstream();
         iterations++;
     }
     const stoppedByLimit = iterations >= (opts.maxIterations ?? 3) &&
@@ -155,7 +102,6 @@ export async function runStreamingInjectLoop(opts) {
 }
 /**
  * JSON 内部循环：非流式请求中命中 MCP tool -> 执行 exec -> 追加对话 -> 再调上游 -> 直到 end_turn。
- * 与 SSE 版 runInjectLoop 对称，但处理 parsed JSON response body 而非 SSE event 数组。
  *
  * @param opts.initialBody 首次上游 JSON 响应（已确认命中 MCP tool）
  * @param opts.requestBody 请求体（messages 会被原地追加）

package/dist/utils/learn-tasks-db.d.ts

@@ -0,0 +1,15 @@
+import Database from 'better-sqlite3';
+export interface InsertRunningArgs {
+    slug: string;
+    sourceType: 'url' | 'file';
+    label: string;
+}
+/** 落 running 行；撞同 slug 唯一约束时错误原样抛出（SQLITE_CONSTRAINT_UNIQUE） */
+export declare function insertRunning(db: Database.Database, args: InsertRunningArgs): {
+    taskId: string;
+};
+export declare function markCompleted(db: Database.Database, taskId: string): void;
+export declare function markFailed(db: Database.Database, taskId: string, error: string): void;
+export declare function markAborted(db: Database.Database, taskId: string): void;
+/** 回收无主 running 行为 crashed（服务启动时调用），返回回收行数 */
+export declare function recoverCrashedTasks(db: Database.Database): number;

package/dist/utils/learn-tasks-db.js

@@ -0,0 +1,35 @@
+// learn_tasks 数据层：learn 流水线状态机落库
+// running → completed / failed / aborted；启动回收的无主 running → crashed。
+// 同 slug 并发运行由 partial unique index idx_learn_tasks_running_slug 硬守。
+import { randomUUID } from 'node:crypto';
+/** 落 running 行；撞同 slug 唯一约束时错误原样抛出（SQLITE_CONSTRAINT_UNIQUE） */
+export function insertRunning(db, args) {
+    const taskId = randomUUID();
+    db.prepare(`
+    INSERT INTO learn_tasks (task_id, slug, source_type, label, status)
+    VALUES (?, ?, ?, ?, 'running')
+  `).run(taskId, args.slug, args.sourceType, args.label);
+    return { taskId };
+}
+export function markCompleted(db, taskId) {
+    db.prepare(`
+    UPDATE learn_tasks SET status = 'completed', ended_at = ? WHERE task_id = ?
+  `).run(new Date().toISOString(), taskId);
+}
+export function markFailed(db, taskId, error) {
+    db.prepare(`
+    UPDATE learn_tasks SET status = 'failed', error = ?, ended_at = ? WHERE task_id = ?
+  `).run(error, new Date().toISOString(), taskId);
+}
+export function markAborted(db, taskId) {
+    db.prepare(`
+    UPDATE learn_tasks SET status = 'aborted', ended_at = ? WHERE task_id = ?
+  `).run(new Date().toISOString(), taskId);
+}
+/** 回收无主 running 行为 crashed（服务启动时调用），返回回收行数 */
+export function recoverCrashedTasks(db) {
+    const info = db.prepare(`
+    UPDATE learn_tasks SET status = 'crashed', ended_at = ? WHERE status = 'running'
+  `).run(new Date().toISOString());
+    return info.changes;
+}

package/dist/utils/openai-converter.js

@@ -1,4 +1,5 @@
 import { Transform } from 'stream';
+import { createSSEDecoder, encodeSSEFrame } from './sse-protocol.js';
 /**
  * Recursively cleans a JSON Schema for OpenAI API compatibility.
  * Removes '$schema' and 'additionalProperties'.
@@ -175,12 +176,16 @@ export function buildOpenAIHeaders(apiKey) {
  */
 export function createStreamTransformer(model) {
     let initialized = false;
-    let buffer = '';
     const messageId = `msg_${Math.random().toString(36).substr(2, 9)}`;
     const toolCalls = {};
     let contentBlockIndex = 0;
+    // 上一帧的原始 data 字符串（帧驱动下对应原 lines[length-2] 的数据来源）
+    let lastDataRaw = '';
+    let decoder = null;
+    // [DONE] 已在 decoder 回调内收尾，transform 末尾不再重复 callback
+    let doneHandled = false;
     const sendEvent = (event, data) => {
-        return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        return encodeSSEFrame({ event, data: JSON.stringify(data) });
     };
     return new Transform({
         transform(chunk, _encoding, callback) {
@@ -204,89 +209,94 @@ export function createStreamTransformer(model) {
                 }));
                 initialized = true;
             }
-            buffer += chunk.toString();
-            const lines = buffer.split('\n');
-            buffer = lines.pop() || '';
-            for (const line of lines) {
-                if (!line.startsWith('data: '))
-                    continue;
-                const data = line.substring(6);
-                if (data.trim() === '[DONE]') {
-                    // Send closing events
-                    this.push(sendEvent('content_block_stop', { type: 'content_block_stop', index: 0 }));
-                    Object.values(toolCalls).forEach(tc => {
-                        if (tc.started) {
-                            this.push(sendEvent('content_block_stop', { type: 'content_block_stop', index: tc.claudeIndex }));
+            if (!decoder) {
+                decoder = createSSEDecoder((frame) => {
+                    const data = frame.data.join('\n');
+                    if (data.trim() === '[DONE]') {
+                        // Send closing events
+                        this.push(sendEvent('content_block_stop', { type: 'content_block_stop', index: 0 }));
+                        Object.values(toolCalls).forEach(tc => {
+                            if (tc.started) {
+                                this.push(sendEvent('content_block_stop', { type: 'content_block_stop', index: tc.claudeIndex }));
+                            }
+                        });
+                        let finalStopReason = 'end_turn';
+                        try {
+                            const lastChunk = JSON.parse(lastDataRaw);
+                            const finishReason = lastChunk.choices[0].finish_reason;
+                            if (finishReason === 'tool_calls')
+                                finalStopReason = 'tool_use';
+                            if (finishReason === 'length')
+                                finalStopReason = 'max_tokens';
                         }
-                    });
-                    let finalStopReason = 'end_turn';
-                    try {
-                        const lastChunk = JSON.parse(lines[lines.length - 2].substring(6));
-                        const finishReason = lastChunk.choices[0].finish_reason;
-                        if (finishReason === 'tool_calls')
-                            finalStopReason = 'tool_use';
-                        if (finishReason === 'length')
-                            finalStopReason = 'max_tokens';
-                    }
-                    catch { }
-                    this.push(sendEvent('message_delta', {
-                        type: 'message_delta',
-                        delta: { stop_reason: finalStopReason, stop_sequence: null },
-                        usage: { output_tokens: 0 }
-                    }));
-                    this.push(sendEvent('message_stop', { type: 'message_stop' }));
-                    callback();
-                    this.destroy();
-                    return;
-                }
-                try {
-                    const openaiChunk = JSON.parse(data);
-                    const delta = openaiChunk.choices[0]?.delta;
-                    if (!delta)
-                        continue;
-                    if (delta.content) {
-                        this.push(sendEvent('content_block_delta', {
-                            type: 'content_block_delta',
-                            index: 0,
-                            delta: { type: 'text_delta', text: delta.content }
+                        catch { }
+                        this.push(sendEvent('message_delta', {
+                            type: 'message_delta',
+                            delta: { stop_reason: finalStopReason, stop_sequence: null },
+                            usage: { output_tokens: 0 }
                         }));
+                        this.push(sendEvent('message_stop', { type: 'message_stop' }));
+                        doneHandled = true;
+                        callback();
+                        this.destroy();
+                        return;
                     }
-                    if (delta.tool_calls) {
-                        for (const tc_delta of delta.tool_calls) {
-                            const index = tc_delta.index;
-                            if (!toolCalls[index]) {
-                                toolCalls[index] = { id: '', name: '', args: '', claudeIndex: 0, started: false };
-                            }
-                            if (tc_delta.id)
-                                toolCalls[index].id = tc_delta.id;
-                            if (tc_delta.function?.name)
-                                toolCalls[index].name = tc_delta.function.name;
-                            if (tc_delta.function?.arguments)
-                                toolCalls[index].args += tc_delta.function.arguments;
-                            if (toolCalls[index].id && toolCalls[index].name && !toolCalls[index].started) {
-                                contentBlockIndex++;
-                                toolCalls[index].claudeIndex = contentBlockIndex;
-                                toolCalls[index].started = true;
-                                this.push(sendEvent('content_block_start', {
-                                    type: 'content_block_start',
-                                    index: contentBlockIndex,
-                                    content_block: { type: 'tool_use', id: toolCalls[index].id, name: toolCalls[index].name, input: {} }
-                                }));
-                            }
-                            if (toolCalls[index].started && tc_delta.function?.arguments) {
-                                this.push(sendEvent('content_block_delta', {
-                                    type: 'content_block_delta',
-                                    index: toolCalls[index].claudeIndex,
-                                    delta: { type: 'input_json_delta', partial_json: tc_delta.function.arguments }
-                                }));
+                    lastDataRaw = data;
+                    try {
+                        const openaiChunk = JSON.parse(data);
+                        const delta = openaiChunk.choices[0]?.delta;
+                        if (!delta)
+                            return;
+                        if (delta.content) {
+                            this.push(sendEvent('content_block_delta', {
+                                type: 'content_block_delta',
+                                index: 0,
+                                delta: { type: 'text_delta', text: delta.content }
+                            }));
+                        }
+                        if (delta.tool_calls) {
+                            for (const tc_delta of delta.tool_calls) {
+                                const index = tc_delta.index;
+                                if (!toolCalls[index]) {
+                                    toolCalls[index] = { id: '', name: '', args: '', claudeIndex: 0, started: false };
+                                }
+                                if (tc_delta.id)
+                                    toolCalls[index].id = tc_delta.id;
+                                if (tc_delta.function?.name)
+                                    toolCalls[index].name = tc_delta.function.name;
+                                if (tc_delta.function?.arguments)
+                                    toolCalls[index].args += tc_delta.function.arguments;
+                                if (toolCalls[index].id && toolCalls[index].name && !toolCalls[index].started) {
+                                    contentBlockIndex++;
+                                    toolCalls[index].claudeIndex = contentBlockIndex;
+                                    toolCalls[index].started = true;
+                                    this.push(sendEvent('content_block_start', {
+                                        type: 'content_block_start',
+                                        index: contentBlockIndex,
+                                        content_block: { type: 'tool_use', id: toolCalls[index].id, name: toolCalls[index].name, input: {} }
+                                    }));
+                                }
+                                if (toolCalls[index].started && tc_delta.function?.arguments) {
+                                    this.push(sendEvent('content_block_delta', {
+                                        type: 'content_block_delta',
+                                        index: toolCalls[index].claudeIndex,
+                                        delta: { type: 'input_json_delta', partial_json: tc_delta.function.arguments }
+                                    }));
+                                }
                             }
                         }
                     }
-                }
-                catch {
-                    // Ignore JSON parse errors in SSE chunks
-                }
+                    catch {
+                        // Ignore JSON parse errors in SSE chunks
+                    }
+                });
             }
+            decoder.write(chunk);
+            if (!doneHandled)
+                callback();
+        },
+        flush(callback) {
+            decoder?.end();
             callback();
         }
     });

package/dist/utils/pi-browser-tools.d.ts

@@ -1,4 +1,3 @@
-import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
 /**
  * 统一封装 ego-browser CLI：spawn 子进程 + 写入 Node 脚本 stdin，返回 cliLog 文本。
  * 每次调用独立进程，靠 useOrCreateTaskSpace 在同一 task space 复用 tab。
@@ -9,4 +8,3 @@ export declare function runEgoBrowser(scriptBody: string, opts?: {
 }): Promise<string>;
 /** 过滤 ego-browser 自身打到输出流的横幅行（如升级 notice），保留脚本 cliLog 的真实输出 */
 export declare function stripCliBanners(text: string): string;
-export declare const browserTools: ToolDefinition[];

package/dist/utils/pi-browser-tools.js

@@ -1,5 +1,4 @@
 import { spawn } from 'node:child_process';
-import { Type } from 'typebox';
 /**
  * 统一封装 ego-browser CLI：spawn 子进程 + 写入 Node 脚本 stdin，返回 cliLog 文本。
  * 每次调用独立进程，靠 useOrCreateTaskSpace 在同一 task space 复用 tab。
@@ -80,176 +79,3 @@ export function stripCliBanners(text) {
         .filter((line) => !line.startsWith('[ego-browser:notice]'))
         .join('\n');
 }
-// ---------- 工具实现辅助 ----------
-/** 把字符串参数安全注入脚本：JSON.stringify 自动处理引号 / 反斜杠 / 换行 */
-const jsLit = (v) => JSON.stringify(v);
-/** 构造 pi AgentToolResult（content + details 字段） */
-const ok = (text) => ({
-    content: [{ type: 'text', text }],
-    details: undefined,
-});
-const navigateSchema = Type.Object({
-    url: Type.String({ description: '目标 URL，必须是 http(s) 完整地址' }),
-    wait: Type.Optional(Type.Boolean({ description: '是否等待页面加载完成，默认 true' })),
-});
-const snapshotSchema = Type.Object({
-    scope: Type.Optional(Type.String({
-        description: "snapshotText 的 scope：'full_page'（默认）或 'only_within_viewport'",
-    })),
-});
-const screenshotSchema = Type.Object({});
-const clickSchema = Type.Object({
-    target: Type.String({
-        description: "点击目标：@N / CSS / 'xpath=...' / 'loc=...'，或 [x,y] 视口坐标数组",
-    }),
-    label: Type.Optional(Type.String({ description: '可选 3-6 字动作描述，用于高亮' })),
-});
-const typeSchema = Type.Object({
-    target: Type.String({ description: '输入框定位：@N / CSS / xpath=... / loc=...' }),
-    text: Type.String({ description: '要填入的文本内容' }),
-    submit: Type.Optional(Type.Boolean({ description: 'true 则填完后按 Enter，默认 false' })),
-});
-const scrollSchema = Type.Object({
-    direction: Type.String({
-        enum: ['down', 'up', 'bottom'],
-        description: "滚动方向：'down' / 'up' / 'bottom'（滚到底并触发懒加载）",
-    }),
-    amount: Type.Optional(Type.Number({ description: 'down/up 时的滚动像素量，默认 900' })),
-});
-const evaluateSchema = Type.Object({
-    expression: Type.String({
-        description: '页面内 JS 字符串。复杂逻辑用 IIFE：(() => { ... })()',
-    }),
-});
-const fetchSchema = Type.Object({
-    url: Type.String({ description: '要抓取的 URL' }),
-});
-const pressKeySchema = Type.Object({
-    key: Type.String({ description: "CDP 键名，如 'Enter' / 'Escape' / 'ArrowDown'" }),
-});
-export const browserTools = [
-    {
-        name: 'browser_navigate',
-        label: 'browser_navigate',
-        description: '在 ego-browser 的 knowledge-learn task space 中打开或复用 tab 到给定 URL。wait=true（默认）会等页面加载，timeout 20s。',
-        parameters: navigateSchema,
-        async execute(_id, params, signal) {
-            const url = jsLit(params.url);
-            const wait = params.wait ?? true;
-            const body = `
-await openOrReuseTab(${url}, { wait: ${wait}, timeout: 20 })
-const info = await pageInfo()
-cliLog(JSON.stringify(info))
-`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_snapshot',
-        label: 'browser_snapshot',
-        description: '获取当前页面的可访问性语义树（含 @N / loc= 引用），是后续 click/fillInput 定位元素的依据。默认 scope=full_page 覆盖整页。',
-        parameters: snapshotSchema,
-        async execute(_id, params, signal) {
-            const scope = params.scope ?? 'full_page';
-            const body = `cliLog(await snapshotText({ scope: ${jsLit(scope)} }))`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_screenshot',
-        label: 'browser_screenshot',
-        description: '对当前页面视口截图。返回 ego 输出的图片说明 / 路径文本。',
-        parameters: screenshotSchema,
-        async execute(_id, _params, signal) {
-            return ok(await runEgoBrowser('cliLog(await captureScreenshot())', { signal }));
-        },
-    },
-    {
-        name: 'browser_click',
-        label: 'browser_click',
-        description: '点击元素。target 支持 @N（来自最近一次 snapshotText）、CSS 选择器、xpath=...、loc=...（推荐长期稳定引用）。label 是 3-6 字动作描述，会触发高亮动画。',
-        parameters: clickSchema,
-        async execute(_id, params, signal) {
-            const target = jsLit(params.target);
-            const label = params.label ? `, { label: ${jsLit(params.label)} }` : '';
-            const body = `await click(${target}${label})\ncliLog('clicked: ${params.target}')`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_type',
-        label: 'browser_type',
-        description: '向输入框填充文本。target 同 browser_click（@N / CSS / xpath / loc）。submit=true 时填完后按 Enter（常用于搜索框）。',
-        parameters: typeSchema,
-        async execute(_id, params, signal) {
-            const target = jsLit(params.target);
-            const text = jsLit(params.text);
-            const submitBlock = params.submit ? `\nawait pressKey('Enter')` : '';
-            const body = `
-await fillInput(${target}, ${text})${submitBlock}
-cliLog('filled: ${params.target}')
-`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_scroll',
-        label: 'browser_scroll',
-        description: '滚动页面。direction=down/up 按 amount 像素滚动；direction=bottom 自动滚到底并尝试触发懒加载（最多 20 步）。',
-        parameters: scrollSchema,
-        async execute(_id, params, signal) {
-            let body;
-            if (params.direction === 'bottom') {
-                body = `
-await scrollToBottomUntil(
-  async () => false,
-  { step: 900, wait: 1, maxSteps: 20 }
-)
-cliLog('scrolled to bottom')
-`;
-            }
-            else {
-                const amount = params.amount ?? 900;
-                const signed = params.direction === 'down' ? amount : -amount;
-                body = `
-await scrollBy(${signed})
-cliLog('scrolled ${params.direction} ${amount}px')
-`;
-            }
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_evaluate',
-        label: 'browser_evaluate',
-        description: '在页面上下文执行 JS 字符串（等价于 Runtime.evaluate），返回序列化结果。多步逻辑请包成 IIFE：(() => { ... })()。不要把它当 Puppeteer page.evaluate(fn, ...args) 用。',
-        parameters: evaluateSchema,
-        async execute(_id, params, signal) {
-            const expr = jsLit(params.expression);
-            const body = `cliLog(JSON.stringify(await js(${expr})))`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_fetch',
-        label: 'browser_fetch',
-        description: '在当前浏览器页面上下文发起 fetch（复用登录态 / Cookie），返回响应正文文本。适合抓取需要鉴权的页面 JSON 或 HTML。',
-        parameters: fetchSchema,
-        async execute(_id, params, signal) {
-            const url = jsLit(params.url);
-            const body = `cliLog(await browserFetch(${url}))`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_press_key',
-        label: 'browser_press_key',
-        description: '在当前焦点元素按下键盘按键。key 用 CDP 键名，如 "Enter" / "Escape" / "Tab" / "ArrowDown" / "Control+A"。',
-        parameters: pressKeySchema,
-        async execute(_id, params, signal) {
-            const key = jsLit(params.key);
-            const body = `await pressKey(${key})\ncliLog('pressed: ${params.key}')`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-];

package/dist/utils/pi-crawl-tools.d.ts

@@ -25,6 +25,7 @@ export declare class CrawlGuard {
     private readonly maxPages;
     private readonly maxDepth;
     private readonly navigate;
+    private readonly vault;
     private entry;
     private readonly seen;
     private readonly depthByUrl;
@@ -58,5 +59,5 @@ export declare class CrawlGuard {
      */
     close(): Promise<void>;
 }
-export declare function createCrawlTools(guard: CrawlGuard): ToolDefinition[];
+export declare function createCrawlTools(guard: CrawlGuard, signal: AbortSignal): ToolDefinition[];
 export {};

package/dist/utils/pi-crawl-tools.js

@@ -3,11 +3,10 @@
 //   saveSource 落盘到 <slug>/sources/source-NNN.md
 // - createCrawlTools：挂给 pi session 的 4 个工具（crawl_open/crawl_visit/
 //   save_source/crawl_finish），错误以文本返回，LLM 可读可恢复
-import fs from 'node:fs';
-import path from 'node:path';
 import { Type } from 'typebox';
 import { runEgoBrowser } from './pi-browser-tools.js';
 import { CRAWL_MAX_PAGES, CRAWL_MAX_DEPTH, isSameSite, normalizeCandidate } from './web-crawler.js';
+import { createVault } from './vault.js';
 /** 单页浏览器脚本：task space 取 tab → goto → networkidle 缓冲 → 稳定性轮询 → 提取标题/正文/链接 */
 function buildCrawlScript(url) {
     return `const pages = await task.pages()
@@ -65,6 +64,12 @@ export class CrawlGuard {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "vault", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "entry", {
             enumerable: true,
             configurable: true,
@@ -108,6 +113,7 @@ export class CrawlGuard {
             writable: true,
             value: 0
         });
+        this.vault = createVault(opts.docsDir);
         this.maxPages = opts.maxPages ?? CRAWL_MAX_PAGES;
         this.maxDepth = opts.maxDepth ?? CRAWL_MAX_DEPTH;
         this.navigate = opts.navigate ?? ((url, signal) => this.defaultNavigate(url, signal));
@@ -208,10 +214,7 @@ export class CrawlGuard {
         // 对齐旧 crawlSite：trim 后为空的页面判失败，不产生空原料
         if (page.text.trim() === '')
             throw new Error(`save_source reject empty page: ${key}`);
-        const sourcesDir = path.join(this.opts.docsDir, this.opts.slug, 'sources');
-        fs.mkdirSync(sourcesDir, { recursive: true });
-        const name = `source-${String(this._savedCount + 1).padStart(3, '0')}.md`;
-        fs.writeFileSync(path.join(sourcesDir, name), `Source: ${key}\n\n${page.text}`, 'utf8');
+        this.vault.writeSourceFile(this.opts.slug, this._savedCount, key, page.text);
         this.savedUrls.add(key);
         this._savedCount += 1;
         return { savedCount: this._savedCount, reused: false };
@@ -234,16 +237,18 @@ const ok = (text) => ({
     details: undefined,
 });
 const errAsText = (e) => ok(`error: ${e instanceof Error ? e.message : String(e)}`);
-export function createCrawlTools(guard) {
+export function createCrawlTools(guard, signal) {
+    // SDK 传入 tool signal 时用它（session 中止时随之中止）；否则用外部 pipeline signal
+    const pickSignal = (toolSignal) => toolSignal ?? signal;
     return [
         {
             name: 'crawl_open',
             label: 'crawl_open',
             description: '打开本次任务的入口 URL，返回标题、正文与同站链接。抓取第一步调用。',
             parameters: Type.Object({}),
-            async execute(_id, _params, signal) {
+            async execute(_id, _params, toolSignal) {
                 try {
-                    return ok(JSON.stringify(await guard.open(signal)));
+                    return ok(JSON.stringify(await guard.open(pickSignal(toolSignal))));
                 }
                 catch (e) {
                     return errAsText(e);
@@ -255,9 +260,9 @@ export function createCrawlTools(guard) {
             label: 'crawl_visit',
             description: '访问入口同站的子页面（必须是 crawl_open/上一次 crawl_visit 返回链接中的 http(s) 页面）。',
             parameters: Type.Object({ url: Type.String({ description: '要访问的同站完整 URL' }) }),
-            async execute(_id, params, signal) {
+            async execute(_id, params, toolSignal) {
                 try {
-                    return ok(JSON.stringify(await guard.visit(params.url, signal)));
+                    return ok(JSON.stringify(await guard.visit(params.url, pickSignal(toolSignal))));
                 }
                 catch (e) {
                     return errAsText(e);