@cc-monitoring/proxy-core 0.3.1 → 0.4.0

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);

package/dist/utils/pi-dedup.d.ts

@@ -1,33 +1,9 @@
-export interface TopicSummary {
-    slug: string;
-    title: string;
-    summary: string;
-    tags: string[];
-}
-export declare function normalizeText(s: string): string;
+import { type TopicSummary, type TopicIndex, type OutlineItem, type ChunkRef } from './vault.js';
 export declare function findCandidates(cand: {
     title: string;
     tags: string[];
 }, topics: TopicSummary[]): TopicSummary[];
-export interface OutlineItem {
-    id: string;
-    title: string;
-    oneLine: string;
-}
-export interface ChunkRefLike {
-    id: string;
-    title: string;
-    summary: string;
-    tags: string[];
-}
-export interface TopicIndexLike {
-    slug: string;
-    title: string;
-    summary: string;
-    tags: string[];
-    chunks: ChunkRefLike[];
-}
-export interface ReconcileResult {
+interface ReconcileResult {
     match: boolean;
     targetSlug?: string;
     confidence?: number;
@@ -35,9 +11,8 @@ export interface ReconcileResult {
     mergedSummary?: string;
     itemsToAdd?: OutlineItem[];
 }
-export declare const LLM_FULL_SCAN_MAX = 20;
 export declare function readAllTopics(docsDir: string): Promise<TopicSummary[]>;
-export declare function readTopicDetail(docsDir: string, slug: string): Promise<TopicIndexLike | null>;
+export declare function readTopicDetail(docsDir: string, slug: string): Promise<TopicIndex | null>;
 export declare function reconcileTopics(opts: {
     port: number;
     docsDir: string;
@@ -48,15 +23,18 @@ export declare function reconcileTopics(opts: {
         items?: OutlineItem[];
     };
     targets?: Array<TopicSummary & {
-        chunks?: ChunkRefLike[];
+        chunks?: ChunkRef[];
     }>;
     wantItems: boolean;
+    signal: AbortSignal;
 }): Promise<ReconcileResult>;
 export declare function mergeTopics(docsDir: string, srcSlug: string, dstSlug: string): number;
-export declare function readSidecarDetail(docsDir: string, slug: string): Promise<TopicIndexLike | null>;
+export declare function readSidecarDetail(docsDir: string, slug: string): Promise<TopicIndex | null>;
 export declare function mintSlug(opts: {
     port: number;
     title: string;
     existing: string[];
+    signal: AbortSignal;
 }): Promise<string>;
 export declare function assertNoOldDirs(docsDir: string): void;
+export {};

package/dist/utils/pi-dedup.js

@@ -1,14 +1,11 @@
-// learn 主题去重：纯字符串确定性预筛（不调 LLM、无 IO）
-import { readFile } from 'fs/promises';
-import fs from 'node:fs';
-import path from 'path';
+// learn 主题去重：纯字符串确定性预筛（不调 LLM）+ LLM 兜底裁定 + 物理迁移。
+// 文件读写、路径、类型统一经 vault（接收 docsDir，按需 createVault，刻意不导入单例）。
 import { runJsonPrompt } from './pi-runtime.js';
 import { slugFromLabel } from './web-crawler.js';
-// 合法 slug：小写字母数字开头，仅含小写字母数字与连字符
-const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+import { createVault, isValidSlug } from './vault.js';
 // 归一化：小写；非字母数字字符（含 -、_、! 等标点）统一替换为空格；trim 并压缩连续空白
 // 标点替换为空格而非删除，使 state-management 与 State Management 归一后一致
-export function normalizeText(s) {
+function normalizeText(s) {
     return s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
 }
 // 命中信号强度：归一 title 相等(0) > 任一归一 tag 相等(1) > title 互为子串(2)
@@ -39,33 +36,20 @@ export function findCandidates(cand, topics) {
     return [...hits.values()].sort((a, b) => a.rank - b.rank).map(h => h.topic);
 }
 // 预筛无命中时允许全量送 LLM 的目标上限；超过则安全放弃
-export const LLM_FULL_SCAN_MAX = 20;
+const LLM_FULL_SCAN_MAX = 20;
 // 读全部 topic 摘要；index.json 缺失/损坏等任何异常一律返回 []
 export async function readAllTopics(docsDir) {
-    try {
-        const raw = await readFile(path.join(docsDir, 'index.json'), 'utf8');
-        const data = JSON.parse(raw);
-        return Array.isArray(data.topics) ? data.topics : [];
-    }
-    catch {
-        return [];
-    }
+    return createVault(docsDir).listTopics();
 }
 // 读单个 topic 详情；缺失/异常返回 null
 export async function readTopicDetail(docsDir, slug) {
-    try {
-        const raw = await readFile(path.join(docsDir, slug, 'index.json'), 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
+    return createVault(docsDir).readTopicIndex(slug);
 }
 // LLM 兜底：在确定性预筛无法排除重复时，请模型裁定候选是否应并入某已有 topic。
 // 任何失败（IO、坏 JSON、超限）均安全降级为 { match: false }
 export async function reconcileTopics(opts) {
-    const targets = opts.targets
-        ?? (await readAllTopics(opts.docsDir)).filter(t => t.slug !== opts.candidate.slug);
+    const vault = createVault(opts.docsDir);
+    const targets = opts.targets ?? (await vault.listTopics()).filter(t => t.slug !== opts.candidate.slug);
     // 先走确定性预筛；无命中且目标数在上限内才全量送 LLM，超限直接放弃
     const hits = findCandidates({ title: opts.candidate.title, tags: opts.candidate.tags }, targets);
     let chosen;
@@ -93,7 +77,7 @@ export async function reconcileTopics(opts) {
     ].join('\n');
     const prompt = `新主题：\n${JSON.stringify(opts.candidate)}\n\n候选已有主题：\n${JSON.stringify(chosen)}`;
     try {
-        const result = await runJsonPrompt({ port: opts.port, instructions, prompt });
+        const result = await runJsonPrompt({ port: opts.port, instructions, prompt, signal: opts.signal });
         // 正载荷必须完整，且 targetSlug 必须在实际提供的 chosen 之中，否则安全降级
         // （同时挡住候选自身 slug 回显、../ 路径穿越及任何未提供的目标）
         const chosenSlugs = chosen.map(t => t.slug);
@@ -115,15 +99,6 @@ export async function reconcileTopics(opts) {
 function pad3(n) {
     return String(n).padStart(3, '0');
 }
-// 列出 dir 下的 .md 文件名（排序）；目录缺失视为空
-function listMd(dir) {
-    try {
-        return fs.readdirSync(dir).filter(f => f.endsWith('.md')).sort();
-    }
-    catch {
-        return [];
-    }
-}
 // 将 src 主题物理并入 dst：sources 续号拷贝、chunks 按 dst 现有数偏移重编号，
 // 同步更新 dst index 与根 index，最后删除整个 src 目录。返回迁移后 dst 的 chunk 总数。
 // srcSlug 可能是 x.old 旁挂目录（含点，路径直接拼接）。
@@ -131,57 +106,49 @@ export function mergeTopics(docsDir, srcSlug, dstSlug) {
     // 防护自合并：LLM 可能回显候选自身 slug；自合并会重复 refs、移除自身根注册并删目录（数据丢失）
     if (srcSlug === dstSlug)
         throw new Error('mergeTopics: src 与 dst 相同');
-    const srcDir = path.join(docsDir, srcSlug);
-    const dstDir = path.join(docsDir, dstSlug);
-    // dst index 必须存在，缺失直接抛错；src index 同样读取（路径直接拼，支持 x.old）
-    const dstIndex = JSON.parse(fs.readFileSync(path.join(dstDir, 'index.json'), 'utf8'));
-    const srcIndex = JSON.parse(fs.readFileSync(path.join(srcDir, 'index.json'), 'utf8'));
+    const vault = createVault(docsDir);
+    // dst index 必须存在，缺失直接抛错；src index 同样读取（entry 直接拼，支持 x.old）
+    const dstIndex = vault.readEntryIndexSync(dstSlug);
+    const srcIndex = vault.readEntryIndexSync(srcSlug);
     // sources：按 dst 现有数量续号，逐个读→写 dst→删 src 原件（copy→unlink，避免跨设备 rename 失败）
-    const srcSources = listMd(path.join(srcDir, 'sources'));
-    const s0 = listMd(path.join(dstDir, 'sources')).length;
-    fs.mkdirSync(path.join(dstDir, 'sources'), { recursive: true });
+    const srcSources = vault.listEntryMd(srcSlug, 'sources');
+    const s0 = vault.listEntryMd(dstSlug, 'sources').length;
+    vault.mkdirEntrySubdir(dstSlug, 'sources');
     srcSources.forEach((file, i) => {
-        const body = fs.readFileSync(path.join(srcDir, 'sources', file));
-        fs.writeFileSync(path.join(dstDir, 'sources', `source-${pad3(s0 + i + 1)}.md`), body);
-        fs.unlinkSync(path.join(srcDir, 'sources', file));
+        const body = vault.readEntryFile(srcSlug, 'sources', file);
+        vault.writeEntryFile(dstSlug, 'sources', `source-${pad3(s0 + i + 1)}.md`, body);
+        vault.unlinkEntryFile(srcSlug, 'sources', file);
     });
     // chunks：src refs 按 id 排序，按 dst 现有 chunk 数偏移重编号；正文逐字拷贝不改
     const srcRefs = [...srcIndex.chunks].sort((a, b) => a.id.localeCompare(b.id));
     const k = dstIndex.chunks.length;
-    fs.mkdirSync(path.join(dstDir, 'chunks'), { recursive: true });
+    vault.mkdirEntrySubdir(dstSlug, 'chunks');
     srcRefs.forEach((ref, i) => {
         const newId = `chunk-${pad3(k + i + 1)}`;
-        const body = fs.readFileSync(path.join(srcDir, 'chunks', `${ref.id}.md`));
-        fs.writeFileSync(path.join(dstDir, 'chunks', `${newId}.md`), body);
-        fs.unlinkSync(path.join(srcDir, 'chunks', `${ref.id}.md`));
+        const body = vault.readEntryFile(srcSlug, 'chunks', `${ref.id}.md`);
+        vault.writeEntryFile(dstSlug, 'chunks', `${newId}.md`, body);
+        vault.unlinkEntryFile(srcSlug, 'chunks', `${ref.id}.md`);
         dstIndex.chunks.push({ ...ref, id: newId });
     });
     // 根 index：移除 slug===srcSlug 的条目（srcSlug 为 x.old 时不命中即 no-op）
     try {
-        const rootPath = path.join(docsDir, 'index.json');
-        const root = JSON.parse(fs.readFileSync(rootPath, 'utf8'));
+        const root = vault.readRootIndexSync();
         if (Array.isArray(root.topics)) {
             root.topics = root.topics.filter(t => t.slug !== srcSlug);
-            fs.writeFileSync(rootPath, JSON.stringify(root, null, 2));
+            vault.writeRootIndexSync(root);
         }
     }
     catch {
         // 根 index 缺失/损坏：无条目可移除，跳过
     }
     // 删除整个 src 目录，写回 dst index
-    fs.rmSync(srcDir, { recursive: true, force: true });
-    fs.writeFileSync(path.join(dstDir, 'index.json'), JSON.stringify(dstIndex, null, 2));
+    vault.removeEntry(srcSlug);
+    vault.writeEntryIndexSync(dstSlug, dstIndex);
     return dstIndex.chunks.length;
 }
 // 读旁挂目录 <slug>.old 的 index.json；缺失/坏 → null
 export async function readSidecarDetail(docsDir, slug) {
-    try {
-        const raw = await readFile(path.join(docsDir, `${slug}.old`, 'index.json'), 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
+    return createVault(docsDir).readSidecarIndex(slug);
 }
 // 据 title 让 LLM 铸一个小写连字符 slug。失败/非法/已占 → 降级 slugFromLabel(title)，
 // 仍被占则追加 -2/-3…。返回保证合法且不落在 existing 内的 slug（除非编号也耗尽，实践不会）。
@@ -191,8 +158,9 @@ export async function mintSlug(opts) {
             port: opts.port,
             instructions: 'Return ONLY JSON {"slug":"<lowercase-hyphen-slug>"} derived faithfully from the title.',
             prompt: `Title: ${opts.title}`,
+            signal: opts.signal,
         });
-        if (typeof result.slug === 'string' && SLUG_RE.test(result.slug) && !opts.existing.includes(result.slug)) {
+        if (typeof result.slug === 'string' && isValidSlug(result.slug) && !opts.existing.includes(result.slug)) {
             return result.slug;
         }
     }
@@ -211,8 +179,5 @@ export async function mintSlug(opts) {
 // 阻断：docsDir 下存在任何 .old 旁挂目录时抛错，要求人工先处理。
 // docsDir 本身缺失时直接让 readdirSync 抛错（调用方本就应在已初始化的库上学习）。
 export function assertNoOldDirs(docsDir) {
-    const oldDir = fs.readdirSync(docsDir).find(name => name.endsWith('.old'));
-    if (oldDir) {
-        throw new Error(`检测到未清理的旁挂目录 ${oldDir}，请手工处理后再学习`);
-    }
+    createVault(docsDir).assertNoOldSidecars();
 }

package/dist/utils/pi-events.d.ts

@@ -0,0 +1,65 @@
+/** 会话领域事件：与 SSE data 帧 payload 同形（type 字符串固定） */
+export type PiSessionEvent = {
+    type: 'round_start';
+    roundIndex: number;
+} | {
+    type: 'round_end';
+    roundIndex: number;
+} | {
+    type: 'text_delta';
+    content: string;
+} | {
+    type: 'thinking_delta';
+    content: string;
+} | {
+    type: 'tool_start';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+} | {
+    type: 'tool_end';
+    toolCallId: string;
+    toolName: string;
+    isError: boolean;
+    durationMs: number;
+    result: string;
+};
+/**
+ * 是否 assistant 消息边界（message_start / message_end 分支内调用）。
+ * message_start 对 user / assistant / toolResult 三种消息都会触发，
+ * 只有 assistant 对应一次 LLM 回复轮次。
+ */
+export declare function isAssistantMessage(ev: any): boolean;
+/**
+ * 从 message_update 事件解包 assistant 流 delta：
+ * ae.type 为 text_delta / thinking_delta 且 delta 为 string 时返回，否则 null。
+ */
+export declare function extractAssistantDelta(ev: any): {
+    kind: 'text' | 'thinking';
+    delta: string;
+} | null;
+/**
+ * 提取工具结果文本：result.content 为数组时，各项 type === 'text' 取 text
+ * （非 text 项以空串占位），以 '\n' 拼接；否则 ''。
+ */
+export declare function extractToolResultText(result: any): string;
+export interface PiEventWriter {
+    /** 喂入一条 pi SDK 原始事件；映射/回调异常不外泄 */
+    write(rawEvent: unknown): void;
+}
+export interface PiEventEmitterOptions {
+    /** 初始轮次计数（复用 session 时传入上次累计值），默认 0 */
+    initialIndex?: number;
+    /** 计数递增时回调，供调用方持久化到 session */
+    onIndexChange?: (roundIndex: number) => void;
+}
+/**
+ * 有状态映射器：内部维护 1-based 轮次计数（assistant message_start 先自增再发
+ * round_start，message_end 带当前值），把原始事件映射为 PiSessionEvent 交给 emit。
+ * agent_end 等终态事件不在这里处理（由调用方自行监听）。
+ *
+ * 跨连接复用语义：同一 pi session 可能被多个 SSE 连接先后复用（多次追问），
+ * 调用方应通过 initialIndex 传入上次累计的轮次、并在 onIndexChange 中持久化新值，
+ * 否则每个连接的 roundIndex 都会从 1 重来，导致前端按 roundIndex 去重时串轮。
+ */
+export declare function createPiEventEmitter(emit: (ev: PiSessionEvent) => void, options?: PiEventEmitterOptions): PiEventWriter;

package/dist/utils/pi-events.js

@@ -0,0 +1,98 @@
+// pi-events: pi SDK 原始事件 → 会话领域事件的映射原语。
+// learn orchestrator / chat SSE / runJsonPrompt 三处订阅共用同一套映射规则。
+//
+// "轮次" = 一次 assistant 交互（assistant message_start → message_end），
+// 轮次索引 1-based。
+/**
+ * 是否 assistant 消息边界（message_start / message_end 分支内调用）。
+ * message_start 对 user / assistant / toolResult 三种消息都会触发，
+ * 只有 assistant 对应一次 LLM 回复轮次。
+ */
+export function isAssistantMessage(ev) {
+    return ev?.message?.role === 'assistant';
+}
+/**
+ * 从 message_update 事件解包 assistant 流 delta：
+ * ae.type 为 text_delta / thinking_delta 且 delta 为 string 时返回，否则 null。
+ */
+export function extractAssistantDelta(ev) {
+    if (ev?.type !== 'message_update')
+        return null;
+    const ae = ev.assistantMessageEvent;
+    if ((ae?.type === 'text_delta' || ae?.type === 'thinking_delta') && typeof ae.delta === 'string') {
+        return { kind: ae.type === 'text_delta' ? 'text' : 'thinking', delta: ae.delta };
+    }
+    return null;
+}
+/**
+ * 提取工具结果文本：result.content 为数组时，各项 type === 'text' 取 text
+ * （非 text 项以空串占位），以 '\n' 拼接；否则 ''。
+ */
+export function extractToolResultText(result) {
+    if (!Array.isArray(result?.content))
+        return '';
+    return result.content
+        .map((c) => (c?.type === 'text' ? c.text : ''))
+        .join('\n');
+}
+/**
+ * 有状态映射器：内部维护 1-based 轮次计数（assistant message_start 先自增再发
+ * round_start，message_end 带当前值），把原始事件映射为 PiSessionEvent 交给 emit。
+ * agent_end 等终态事件不在这里处理（由调用方自行监听）。
+ *
+ * 跨连接复用语义：同一 pi session 可能被多个 SSE 连接先后复用（多次追问），
+ * 调用方应通过 initialIndex 传入上次累计的轮次、并在 onIndexChange 中持久化新值，
+ * 否则每个连接的 roundIndex 都会从 1 重来，导致前端按 roundIndex 去重时串轮。
+ */
+export function createPiEventEmitter(emit, options) {
+    let roundIndex = options?.initialIndex ?? 0;
+    return {
+        write(rawEvent) {
+            try {
+                const ev = rawEvent;
+                if (ev.type === 'message_start') {
+                    if (isAssistantMessage(ev)) {
+                        roundIndex += 1;
+                        options?.onIndexChange?.(roundIndex);
+                        emit({ type: 'round_start', roundIndex });
+                    }
+                }
+                else if (ev.type === 'message_end') {
+                    if (isAssistantMessage(ev)) {
+                        emit({ type: 'round_end', roundIndex });
+                    }
+                }
+                else if (ev.type === 'message_update') {
+                    const d = extractAssistantDelta(ev);
+                    if (d) {
+                        emit(d.kind === 'text'
+                            ? { type: 'text_delta', content: d.delta }
+                            : { type: 'thinking_delta', content: d.delta });
+                    }
+                }
+                else if (ev.type === 'tool_execution_start') {
+                    emit({
+                        type: 'tool_start',
+                        toolCallId: ev.toolCallId,
+                        toolName: ev.toolName,
+                        args: ev.args,
+                    });
+                }
+                else if (ev.type === 'tool_execution_end') {
+                    emit({
+                        type: 'tool_end',
+                        toolCallId: ev.toolCallId,
+                        toolName: ev.toolName,
+                        isError: !!ev.isError,
+                        durationMs: ev.durationMs ?? 0,
+                        result: extractToolResultText(ev.result),
+                    });
+                }
+                // 其他事件（agent_end / 未知类型）忽略
+            }
+            catch {
+                // 映射或 emit 抛错不影响 SDK 事件分发（参照 orchestrator 既有约定）
+            }
+        },
+    };
+}

package/dist/utils/pi-learn-orchestrator.d.ts

@@ -1,8 +1,5 @@
-export interface OutlineItem {
-    id: string;
-    title: string;
-    oneLine: string;
-}
+import type { OutlineItem } from './vault.js';
+export type { OutlineItem };
 export interface LearnPipelineEvents {
     stageStart(stage: 'outline' | 'refine' | 'tag', totalItems?: number): void;
     stageItemStart(index: number, total: number, title: string): void;
@@ -34,8 +31,12 @@ export interface RunLearnPipelineOptions {
     label?: string;
     port: number;
     events: LearnPipelineEvents;
+    /** 外部取消信号：客户端断开（关窗）时 abort，流水线各阶段随之中止 */
+    signal: AbortSignal;
     /** 注入式 docsDir（测试用）；默认 ~/.cc-monitoring/docs */
     docsDir?: string;
+    /** slug 算出后、任何文件改动前同步调用（落 running 行用）；抛错直接传播 */
+    onStart?: (slug: string) => void;
 }
 export declare function runLearnPipeline(opts: RunLearnPipelineOptions): Promise<{
     slug: string;