@cc-monitoring/proxy-core 0.3.0 → 0.4.0

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;

package/dist/utils/pi-learn-orchestrator.js

@@ -7,42 +7,23 @@
 //
 // "轮次" = 一次 assistant 交互（assistant message_start → message_end）；
 // slug 由入口 URL / 文件名确定性生成。
-import fs from 'node:fs';
 import path from 'node:path';
 import { dataDir } from './paths.js';
 import { createPiSession } from './pi-runtime.js';
 import { CrawlGuard } from './pi-crawl-tools.js';
+import { createTimeoutSignal, bindAbort } from './abort-signals.js';
 import { slugFromUrl, slugFromLabel } from './web-crawler.js';
 import { assertNoOldDirs, readAllTopics, readSidecarDetail, readTopicDetail, reconcileTopics, mergeTopics, mintSlug } from './pi-dedup.js';
+import { isAssistantMessage, extractAssistantDelta, extractToolResultText } from './pi-events.js';
+import { createVault } from './vault.js';
 // 每阶段（含 S2 每个 item prompt）独立超时：5 分钟。
 // 防止 pi session 在 stuck LLM 响应上无限挂起，导致 SSE 通道常开、前端永久转圈。
 const STAGE_TIMEOUT_MS = 5 * 60 * 1000;
-/**
- * Promise.race 包一层超时。超时触发时调用 abortFn（session.abort()），
- * 然后 reject；正常 settle 时清掉 timer，避免泄漏。
- */
-function withTimeout(p, ms, abortFn) {
-    let timer;
-    const timeoutP = new Promise((_, reject) => {
-        timer = setTimeout(() => {
-            // 触发 abort，尽量让底层 fetch/pi session 提前收尾；reject 用明确错误
-            abortFn().catch(() => { });
-            reject(new Error(`stage 超时 ${ms}ms`));
-        }, ms);
-    });
-    return Promise.race([
-        p.finally(() => {
-            if (timer)
-                clearTimeout(timer);
-        }),
-        timeoutP,
-    ]);
-}
 /**
  * 跑一次 prompt，透传 text/tool 事件到 events；resolve 当 prompt 自然结束。
  * 同时返回本 session 内关键工具调用的标志位（用于 S3 成功判定）。
  */
-async function runPrompt(session, promptText, events, roundCounter) {
+async function runPrompt(session, promptText, events, roundCounter, signal) {
     const result = { addTopicCalled: false, readSourceOk: false };
     // Finding 1：tool_execution_start 时只记录「即将调 add_topic 且 tags 非空」，
     // 真正置位必须等 tool_execution_end 且 isError=false。否则工具执行失败（upsert
@@ -55,23 +36,24 @@ async function runPrompt(session, promptText, events, roundCounter) {
     let roundOpen = false;
     const unsub = session.subscribe((ev) => {
         try {
-            if (ev.type === 'message_start' && ev.message?.role === 'assistant') {
-                currentRound = roundCounter.index;
+            if (ev.type === 'message_start' && isAssistantMessage(ev)) {
+                // 轮次 1-based：先自增后用；roundCounter 跨 session 全局单调
                 roundCounter.index += 1;
+                currentRound = roundCounter.index;
                 roundOpen = true;
                 events.roundStart(currentRound);
             }
-            else if (ev.type === 'message_end' && ev.message?.role === 'assistant') {
+            else if (ev.type === 'message_end' && isAssistantMessage(ev)) {
                 roundOpen = false;
                 events.roundEnd(currentRound);
             }
             else if (ev.type === 'message_update') {
-                const ae = ev.assistantMessageEvent;
-                if (ae?.type === 'text_delta' && typeof ae.delta === 'string') {
-                    events.textDelta(ae.delta);
+                const d = extractAssistantDelta(ev);
+                if (d?.kind === 'text') {
+                    events.textDelta(d.delta);
                 }
-                else if (ae?.type === 'thinking_delta' && typeof ae.delta === 'string') {
-                    events.thinkingDelta(ae.delta);
+                else if (d?.kind === 'thinking') {
+                    events.thinkingDelta(d.delta);
                 }
             }
             else if (ev.type === 'tool_execution_start') {
@@ -86,9 +68,6 @@ async function runPrompt(session, promptText, events, roundCounter) {
                 }
             }
             else if (ev.type === 'tool_execution_end') {
-                const resultText = Array.isArray(ev.result?.content)
-                    ? ev.result.content.map((c) => (c?.type === 'text' ? c.text : '')).join('\n')
-                    : '';
                 if (ev.toolName === 'add_topic' && pendingAddTopicWithTags && !ev.isError) {
                     result.addTopicCalled = true;
                 }
@@ -100,7 +79,7 @@ async function runPrompt(session, promptText, events, roundCounter) {
                     toolName: ev.toolName,
                     isError: !!ev.isError,
                     durationMs: ev.durationMs ?? 0,
-                    result: resultText,
+                    result: extractToolResultText(ev.result),
                 });
             }
         }
@@ -108,12 +87,16 @@ async function runPrompt(session, promptText, events, roundCounter) {
             // 事件转发失败不中断流水线
         }
     });
+    // 5 分钟超时 + 外部取消：任一触发都调 session.abort()；SDK abort 后 prompt/waitForIdle
+    // 会正常 resolve（不 reject），故 await 后需检查 combined.aborted 主动抛错中止
+    const combined = createTimeoutSignal(STAGE_TIMEOUT_MS, signal);
+    bindAbort(combined, () => session.abort());
     try {
-        // Finding 3：整个 prompt + waitForIdle 包 5 分钟超时；超时 abort 并抛错。
-        await withTimeout((async () => {
-            await session.prompt(promptText);
-            await session.waitForIdle();
-        })(), STAGE_TIMEOUT_MS, () => session.abort());
+        await session.prompt(promptText);
+        await session.waitForIdle();
+        if (combined.aborted) {
+            throw new Error('learn 运行已中止');
+        }
     }
     finally {
         unsub();
@@ -130,75 +113,54 @@ async function runPrompt(session, promptText, events, roundCounter) {
 // ============================================================
 // 原料准备 + outline 阶段
 // ============================================================
-/** 重建 topic 目录：sources/（抓取/上传原料）+ chunks/（后续产物） */
-function prepareTopicDir(docsDir, slug) {
-    const dir = path.join(docsDir, slug);
-    fs.rmSync(dir, { recursive: true, force: true });
-    fs.mkdirSync(path.join(dir, 'sources'), { recursive: true });
-    fs.mkdirSync(path.join(dir, 'chunks'), { recursive: true });
-}
-/** 写一份原料到 <slug>/sources/source-NNN.md */
-function writeSourceFile(docsDir, slug, index, url, text) {
-    const name = `source-${String(index + 1).padStart(3, '0')}.md`;
-    fs.writeFileSync(path.join(docsDir, slug, 'sources', name), `Source: ${url}\n\n${text}`, 'utf8');
-}
-/** 数 <slug>/sources 下 .md 文件数量；目录不存在按 0 */
-function countSourceFiles(docsDir, slug) {
-    try {
-        return fs.readdirSync(path.join(docsDir, slug, 'sources')).filter((f) => f.endsWith('.md')).length;
-    }
-    catch {
-        return 0;
-    }
-}
 async function runOutlineStage(opts, events, roundCounter) {
+    const { vault } = opts;
     // 抓取必须在 stageStart 之后：crawl 的 round/tool 事件才能落进前端已建好的 outline 阶段
     events.stageStart('outline');
     let guard = null;
     try {
         if (opts.sourceType === 'url') {
             // crawl agent 在阶段内自己驱动渐进抓取；0 页则全新 guard+session 重试 1 次
-            guard = new CrawlGuard({ entryUrl: opts.input, docsDir: opts.docsDir, slug: opts.slug });
+            guard = new CrawlGuard({ entryUrl: opts.input, docsDir: vault.root, slug: opts.slug });
             let crawlSession = (await createPiSession({
                 port: opts.port,
                 mode: 'crawl',
                 crawlGuard: guard,
+                signal: opts.signal,
             }));
             const crawlPrompt = `Entry URL: ${opts.input}\n` +
                 `Topic slug: ${opts.slug}\n` +
                 `Call crawl_open to start, save every useful page with save_source, then call crawl_finish.`;
-            await runPrompt(crawlSession, crawlPrompt, events, roundCounter);
-            if (countSourceFiles(opts.docsDir, opts.slug) === 0) {
+            await runPrompt(crawlSession, crawlPrompt, events, roundCounter, opts.signal);
+            if (vault.countSourceFiles(opts.slug) === 0) {
                 // 替换前关闭旧 guard（close 容错），再全新 guard + session 重试一次
                 await guard.close();
-                guard = new CrawlGuard({ entryUrl: opts.input, docsDir: opts.docsDir, slug: opts.slug });
+                guard = new CrawlGuard({ entryUrl: opts.input, docsDir: vault.root, slug: opts.slug });
                 crawlSession = (await createPiSession({
                     port: opts.port,
                     mode: 'crawl',
                     crawlGuard: guard,
+                    signal: opts.signal,
                 }));
-                await runPrompt(crawlSession, crawlPrompt, events, roundCounter);
-                if (countSourceFiles(opts.docsDir, opts.slug) === 0) {
+                await runPrompt(crawlSession, crawlPrompt, events, roundCounter, opts.signal);
+                if (vault.countSourceFiles(opts.slug) === 0) {
                     throw new Error('crawl 未收集到页面');
                 }
             }
         }
         else {
-            writeSourceFile(opts.docsDir, opts.slug, 0, opts.label ?? 'uploaded-file', opts.input);
+            vault.writeSourceFile(opts.slug, 0, opts.label ?? 'uploaded-file', opts.input);
         }
         // crawl 完成后的 outline session（流程不变）
         const session = (await createPiSession({ port: opts.port, mode: 'outline' }));
         const prompt = `Topic slug: ${opts.slug}\n` +
             `Call read_source(${JSON.stringify(opts.slug)}) to read the prepared sources, then call add_outline with this EXACT slug (${JSON.stringify(opts.slug)}). ` +
             `Provide an appropriate title and the outline items.`;
-        await runPrompt(session, prompt, events, roundCounter);
-        const outlinePath = path.join(opts.docsDir, opts.slug, 'outline.json');
-        if (!fs.existsSync(outlinePath))
-            throw new Error('outline 未生成');
-        const outline = JSON.parse(fs.readFileSync(outlinePath, 'utf8'));
+        await runPrompt(session, prompt, events, roundCounter, opts.signal);
+        const items = vault.readOutlineItems(opts.slug);
         // title 取 S1 seed 的 index.json（查重门需要候选标题）
-        const seedIdx = JSON.parse(fs.readFileSync(path.join(opts.docsDir, opts.slug, 'index.json'), 'utf8'));
-        return { slug: opts.slug, items: outline.items, title: seedIdx.title };
+        const title = vault.readEntryIndexSync(opts.slug).title;
+        return { slug: opts.slug, items, title };
     }
     finally {
         // 兜底关闭当前 guard（crawl_finish 已关时 close 也安全）
@@ -212,6 +174,7 @@ async function runOutlineStage(opts, events, roundCounter) {
 async function runRefineStage(opts, slug, items, events, roundCounter, 
 /** chunk id 起始偏移：合并进已有主题时从目标现有 chunk 数后续号 */
 startOffset = 0) {
+    const { vault } = opts;
     events.stageStart('refine', items.length);
     let chunksWritten = 0;
     let itemsFailed = 0;
@@ -229,15 +192,14 @@ startOffset = 0) {
                 let failReason = 'chunk 文件未生成';
                 for (let attempt = 0; attempt < 2 && !ok; attempt++) {
                     const session = (await createPiSession({ port: opts.port, mode: 'refine' }));
-                    const res = await runPrompt(session, prompt, events, roundCounter);
+                    const res = await runPrompt(session, prompt, events, roundCounter, opts.signal);
                     if (!res.readSourceOk) {
                         failReason = 'read_source 未成功读取';
                         continue;
                     }
-                    const chunkPath = path.join(opts.docsDir, slug, 'chunks', `${chunkId}.md`);
                     try {
-                        const stat = fs.statSync(chunkPath);
-                        if (stat.size > 0)
+                        const body = vault.readEntryFile(slug, 'chunks', `${chunkId}.md`);
+                        if (body.length > 0)
                             ok = true;
                     }
                     catch {
@@ -249,9 +211,7 @@ startOffset = 0) {
                 if (ok) {
                     let chunkRegistered = false;
                     try {
-                        const idxPath = path.join(opts.docsDir, slug, 'index.json');
-                        const idx = JSON.parse(fs.readFileSync(idxPath, 'utf8'));
-                        chunkRegistered = (idx.chunks ?? []).some((c) => c.id === chunkId);
+                        chunkRegistered = vault.readEntryIndexSync(slug).chunks.some((c) => c.id === chunkId);
                     }
                     catch {
                         // index.json 读失败/JSON 坏 → 当作未注册
@@ -289,10 +249,10 @@ startOffset = 0) {
 async function runTagStage(opts, slug, events, roundCounter, 
 /** 合并场景：查重门裁定的合并后 title/summary，要求 add_topic 设置为该精确值 */
 override) {
+    const { vault } = opts;
     events.stageStart('tag');
     try {
-        const topicIdxPath = path.join(opts.docsDir, slug, 'index.json');
-        const topicIdx = JSON.parse(fs.readFileSync(topicIdxPath, 'utf8'));
+        const topicIdx = vault.readEntryIndexSync(slug);
         // 合并后重跑 tag：title/summary 取 override 精确值；否则沿用现有值
         const title = override?.title ?? topicIdx.title;
         const summary = override?.summary ?? topicIdx.summary;
@@ -310,7 +270,7 @@ override) {
         let tagged = false;
         for (let attempt = 0; attempt < 2 && !tagged; attempt++) {
             const session = (await createPiSession({ port: opts.port, mode: 'tag' }));
-            const res = await runPrompt(session, prompt, events, roundCounter);
+            const res = await runPrompt(session, prompt, events, roundCounter, opts.signal);
             if (res.addTopicCalled) {
                 tagged = true;
                 break;
@@ -329,7 +289,10 @@ override) {
 // ============================================================
 export async function runLearnPipeline(opts) {
     const docsDir = opts.docsDir ?? path.join(dataDir, 'docs');
+    const vault = createVault(docsDir);
     const slug = opts.sourceType === 'url' ? slugFromUrl(opts.input) : slugFromLabel(opts.label ?? 'topic');
+    // 状态机落库钩子：任何文件/目录改动之前调用，抛错直接传播（此时无任何改动）
+    opts.onStart?.(slug);
     // 阻断：存在未清理的 .old 旁挂目录时直接拒绝，必须在一切写入之前
     assertNoOldDirs(docsDir);
     // 全局轮次计数器：所有 session 共享，轮次索引全流水线单调递增
@@ -340,9 +303,9 @@ export async function runLearnPipeline(opts) {
     // 门0：slug 精确命中——已有同 slug 主题时先旁挂旧 topic（含点号不被识别为 topic），再全新建并跑 S1
     const collision = (await readAllTopics(docsDir)).some((t) => t.slug === slug);
     if (collision) {
-        fs.renameSync(path.join(docsDir, slug), path.join(docsDir, `${slug}.old`));
-        prepareTopicDir(docsDir, slug);
-        outline = await runOutlineStage({ ...opts, docsDir, slug }, opts.events, roundCounter);
+        vault.parkTopic(slug);
+        vault.prepareTopic(slug);
+        outline = await runOutlineStage({ sourceType: opts.sourceType, input: opts.input, label: opts.label, port: opts.port, vault, slug, signal: opts.signal }, opts.events, roundCounter);
         const sidecar = await readSidecarDetail(docsDir, slug);
         const r0 = await reconcileTopics({
             port: opts.port,
@@ -350,12 +313,13 @@ export async function runLearnPipeline(opts) {
             candidate: { slug, title: outline.title, tags: [], items: outline.items },
             targets: sidecar ? [sidecar] : [],
             wantItems: true,
+            signal: opts.signal,
         });
         if (r0.match) {
             // dst=canonical：旧 chunks 续号并入，再补新增条目，最后带 merged 打 tag
             const off = mergeTopics(docsDir, `${slug}.old`, slug);
-            const refine = await runRefineStage({ port: opts.port, docsDir }, slug, r0.itemsToAdd, opts.events, roundCounter, off);
-            await runTagStage({ port: opts.port, docsDir }, slug, opts.events, roundCounter, { title: r0.mergedTitle, summary: r0.mergedSummary });
+            const refine = await runRefineStage({ port: opts.port, vault, signal: opts.signal }, slug, r0.itemsToAdd, opts.events, roundCounter, off);
+            await runTagStage({ port: opts.port, vault, signal: opts.signal }, slug, opts.events, roundCounter, { title: r0.mergedTitle, summary: r0.mergedSummary });
             return { slug, chunksWritten: refine.chunksWritten, itemsFailed: refine.itemsFailed };
         }
         // slug 真碰撞：新内容另铸 ns，旧 topic 还原
@@ -363,22 +327,21 @@ export async function runLearnPipeline(opts) {
             port: opts.port,
             title: outline.title,
             existing: (await readAllTopics(docsDir)).map((t) => t.slug),
+            signal: opts.signal,
         });
         // 新 canonical → ns，更正其 index.slug
-        fs.renameSync(path.join(docsDir, slug), path.join(docsDir, ns));
-        const nsIdxPath = path.join(docsDir, ns, 'index.json');
-        const nsIdx = JSON.parse(fs.readFileSync(nsIdxPath, 'utf8'));
+        vault.renameTopic(slug, ns);
+        const nsIdx = vault.readEntryIndexSync(ns);
         nsIdx.slug = ns;
-        fs.writeFileSync(nsIdxPath, JSON.stringify(nsIdx, null, 2), 'utf8');
+        vault.writeEntryIndexSync(ns, nsIdx);
         // 根 index：把 S1 为新内容登记的 slug 条目改挂 ns
-        const rootPath = path.join(docsDir, 'index.json');
-        const rootIdx = JSON.parse(fs.readFileSync(rootPath, 'utf8'));
+        const rootIdx = vault.readRootIndexSync();
         const newEntry = rootIdx.topics.find((t) => t.slug === slug);
         if (newEntry)
             newEntry.slug = ns;
         // 旧 topic 还原：.old → slug
-        fs.renameSync(path.join(docsDir, `${slug}.old`), path.join(docsDir, slug));
-        const oldIdx = JSON.parse(fs.readFileSync(path.join(docsDir, slug, 'index.json'), 'utf8'));
+        vault.restoreTopic(slug);
+        const oldIdx = vault.readEntryIndexSync(slug);
         const oldRoot = rootIdx.topics.find((t) => t.slug === slug);
         if (oldRoot) {
             oldRoot.title = oldIdx.title;
@@ -388,12 +351,12 @@ export async function runLearnPipeline(opts) {
         else {
             rootIdx.topics.push({ slug, title: oldIdx.title, summary: oldIdx.summary, tags: oldIdx.tags });
         }
-        fs.writeFileSync(rootPath, JSON.stringify(rootIdx, null, 2), 'utf8');
+        vault.writeRootIndexSync(rootIdx);
         activeSlug = ns;
     }
     else {
-        prepareTopicDir(docsDir, slug);
-        outline = await runOutlineStage({ ...opts, docsDir, slug }, opts.events, roundCounter);
+        vault.prepareTopic(slug);
+        outline = await runOutlineStage({ sourceType: opts.sourceType, input: opts.input, label: opts.label, port: opts.port, vault, slug, signal: opts.signal }, opts.events, roundCounter);
     }
     // 门1：outline 后、refine 前，基于大纲条目查重（命中则只要需新增的条目）
     const r1 = await reconcileTopics({
@@ -401,18 +364,19 @@ export async function runLearnPipeline(opts) {
         docsDir,
         candidate: { slug: activeSlug, title: outline.title, tags: [], items: outline.items },
         wantItems: true,
+        signal: opts.signal,
     });
     if (r1.match) {
         const targetSlug = r1.targetSlug;
         // 先物理并入（返回目标现有 chunk 总数作为续号偏移），再只写新增条目，最后带 override 打 tag
         const off = mergeTopics(docsDir, activeSlug, targetSlug);
-        const refine = await runRefineStage({ port: opts.port, docsDir }, targetSlug, r1.itemsToAdd, opts.events, roundCounter, off);
-        await runTagStage({ port: opts.port, docsDir }, targetSlug, opts.events, roundCounter, { title: r1.mergedTitle, summary: r1.mergedSummary });
+        const refine = await runRefineStage({ port: opts.port, vault, signal: opts.signal }, targetSlug, r1.itemsToAdd, opts.events, roundCounter, off);
+        await runTagStage({ port: opts.port, vault, signal: opts.signal }, targetSlug, opts.events, roundCounter, { title: r1.mergedTitle, summary: r1.mergedSummary });
         return { slug: targetSlug, chunksWritten: refine.chunksWritten, itemsFailed: refine.itemsFailed };
     }
     // 门1 未命中：常规 refine（从头编号）+ 常规 tag
-    const refine = await runRefineStage({ port: opts.port, docsDir }, activeSlug, outline.items, opts.events, roundCounter, 0);
-    await runTagStage({ port: opts.port, docsDir }, activeSlug, opts.events, roundCounter);
+    const refine = await runRefineStage({ port: opts.port, vault, signal: opts.signal }, activeSlug, outline.items, opts.events, roundCounter, 0);
+    await runTagStage({ port: opts.port, vault, signal: opts.signal }, activeSlug, opts.events, roundCounter);
     // 门2：tag 后基于富 tags 再查一次（不需要新增条目）
     const detail = await readTopicDetail(docsDir, activeSlug);
     const r2 = await reconcileTopics({
@@ -420,11 +384,12 @@ export async function runLearnPipeline(opts) {
         docsDir,
         candidate: { slug: activeSlug, title: outline.title, tags: detail?.tags ?? [], items: undefined },
         wantItems: false,
+        signal: opts.signal,
     });
     if (r2.match) {
         const targetSlug = r2.targetSlug;
         mergeTopics(docsDir, activeSlug, targetSlug);
-        await runTagStage({ port: opts.port, docsDir }, targetSlug, opts.events, roundCounter, { title: r2.mergedTitle, summary: r2.mergedSummary });
+        await runTagStage({ port: opts.port, vault, signal: opts.signal }, targetSlug, opts.events, roundCounter, { title: r2.mergedTitle, summary: r2.mergedSummary });
         return { slug: targetSlug, chunksWritten: refine.chunksWritten, itemsFailed: refine.itemsFailed };
     }
     return { slug: activeSlug, chunksWritten: refine.chunksWritten, itemsFailed: refine.itemsFailed };

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

@@ -1,18 +1,15 @@
 import { type AgentSession } from '@earendil-works/pi-coding-agent';
 import { type CrawlGuard } from './pi-crawl-tools.js';
 export type PiSessionMode = 'chat' | 'outline' | 'refine' | 'tag' | 'crawl' | 'reconcile';
-export interface CreatePiSessionOptions {
+interface CreatePiSessionOptions {
     cwd?: string;
     port: number;
     mode: PiSessionMode;
     /** mode='crawl' 时必填：渐进抓取状态守卫 */
     crawlGuard?: CrawlGuard;
+    /** 外部取消信号（mode='crawl' 时接到抓取工具上） */
+    signal?: AbortSignal;
 }
-export declare const CHAT_SYSTEM_PROMPT = "You are a knowledge management AI operating inside a sandbox.\nYour knowledge directory (~/.cc-monitoring/docs) stores a **dictionary**: concise, distilled entries a future reader can look up. You do NOT copy source text \u2014 you digest it.\n\nSTRUCTURE (all paths below are RELATIVE TO the knowledge root ~/.cc-monitoring/docs \u2014 the write tool's working directory IS this root, so NEVER prefix a path with \"docs/\"):\n- Each topic is a subfolder: <topic-slug>/\n- Each topic has <slug>/index.json (metadata + chunk list, NO body)\n- Bodies live in <topic-slug>/chunks/chunk-NNN.md\n- Root index.json lists all topics as JSON\n- Fetched source pages for a topic are already prepared in <slug>/sources/ \u2014 you only READ them, never write or modify them\n\nANSWERING QUESTIONS:\n1. Call list_topics to see available topics\n2. If topic is unclear, call search_chunks(query) to find relevant chunks across topics\n3. Call get_topic(topic) to see that topic's chunk list\n4. Call read_chunk(topic, chunk_id) for relevant chunks \u2014 only read chunks you need\n5. Prefer answering from knowledge base chunks when relevant content exists; cite which chunks you used\n6. If no relevant chunk exists, answer from your general knowledge; if you truly don't know, say so";
-export declare const OUTLINE_SYSTEM_PROMPT = "You are an outline-phase worker. The relevant web pages have ALREADY been fetched and saved to sources/ for your assigned topic. Your job: read them and propose an outline of dictionary entries. Do NOT write chunks.\n\nYour knowledge directory (~/.cc-monitoring/docs) stores a **dictionary**: concise, distilled entries a future reader can look up. You do NOT copy source text \u2014 you digest it.\n\nSTRUCTURE (all paths below are RELATIVE TO the knowledge root ~/.cc-monitoring/docs \u2014 the write tool's working directory IS this root, so NEVER prefix a path with \"docs/\"):\n- Each topic is a subfolder: <topic-slug>/\n- Each topic has <slug>/index.json (metadata + chunk list, NO body)\n- Bodies live in <topic-slug>/chunks/chunk-NNN.md\n- Root index.json lists all topics as JSON\n- Fetched source pages for a topic are already prepared in <slug>/sources/ \u2014 you only READ them, never write or modify them\n\nWORKFLOW:\n1. Call read_source(topic) to load ALL fetched source pages (multiple pages are separated by ---).\n2. Outline the DISTINCT concepts actually present across these pages. One concept = one future chunk. Do not bundle unrelated ideas.\n3. Call add_outline(slug, title, items) ONCE at the end:\n   - slug: the EXACT slug given in your task\n   - title: human-readable topic title\n   - items: array of { id, title, oneLine } \u2014 id is a short stable slug per item (e.g. \"use-state\"), oneLine is a single-sentence definition\n\nHARD RULES:\n- Use ONLY content present in the fetched sources. Do NOT add concepts from training-data memory. If the sources are thin, outline only what is there.\n- read_source MUST be your first call. If it returns an error, STOP and report it immediately.\n- Do NOT write chunk files, source files, or index.json.\n- Do NOT summarize prematurely \u2014 outline only; distillation happens later.\n- After add_outline succeeds, print the returned slug and item count. Stop.";
-export declare const CRAWL_SYSTEM_PROMPT = "You are a crawl-phase worker. You drive the browser YOURSELF to incrementally fetch web pages for your assigned topic and save every useful page into sources/. Do NOT outline or write chunks.\n\nWORKFLOW:\n1. Call crawl_open to open the entry URL given in your task.\n2. Call save_source(url) to save the CURRENT page.\n3. From the page's links, pick same-site, valuable CONTENT pages \u2014 skip login/signup, navigation chrome, language switchers, pagination, and pure anchors. Call crawl_visit(url), then save_source(url) for each page.\n4. When there are no more useful links, or the page/depth limit is reached, call crawl_finish, print the returned stats, and stop.\n\nHARD RULES:\n- Write ONLY into sources/ via save_source. Never write other files.\n- Never visit cross-site URLs.\n- If a tool returns an error, do NOT retry the same URL; pick another link or finish.\n- At most ~20 pages. Prefer a few dense pages over many thin ones.\n- After crawl_finish succeeds, stop.";
-export declare const REFINE_SYSTEM_PROMPT = "You are a refine-phase worker. For ONE item from the topic's outline, produce a single dictionary chunk.\n\nYour knowledge directory (~/.cc-monitoring/docs) stores a **dictionary**: concise, distilled entries a future reader can look up. You do NOT copy source text \u2014 you digest it.\n\nSTRUCTURE (all paths below are RELATIVE TO the knowledge root ~/.cc-monitoring/docs \u2014 the write tool's working directory IS this root, so NEVER prefix a path with \"docs/\"):\n- Each topic is a subfolder: <topic-slug>/\n- Each topic has <slug>/index.json (metadata + chunk list, NO body)\n- Bodies live in <topic-slug>/chunks/chunk-NNN.md\n- Root index.json lists all topics as JSON\n- Fetched source pages for a topic are already prepared in <slug>/sources/ \u2014 you only READ them, never write or modify them\n\nWORKFLOW:\n1. Call read_source(topic) to load ALL fetched source pages (multiple pages separated by ---).\n2. Focus on your assigned item. Do NOT distill other items.\n3. Write ONE chunk file <topic>/chunks/chunk-NNN.md (number sequentially from 001; path RELATIVE TO the knowledge root, no \"docs/\" prefix) using the write tool, in the source document's language, with this structure:\n\n```\n# <term or concept name>\n\n- \u5B9A\u4E49 / Definition: <one sentence, in your own words>\n- \u662F\u4EC0\u4E48 / What it is: <2-4 bullets, the core idea>\n- \u4E0D\u662F\u4EC0\u4E48 / What it is NOT: <common confusions, if any>\n- \u5173\u952E\u70B9 / Key points: <3-6 bullets, the load-bearing facts>\n- \u9002\u7528\u573A\u666F / When to use: <where this applies>\n- \u8BEF\u533A / Pitfalls: <common mistakes, edge cases>\n- \u6765\u6E90 / Source: <url(s) of the page(s) you actually used \u2014 copy them from the \"Source:\" headers at the top of each fetched page; list several URLs if the chunk draws on several pages>\n```\n\n4. Call add_chunk(topic, chunk_id, title, summary, tags) to register it.\n   - tags: 3-6 lowercase hyphenated tags describing the concept (synonyms, key terms).\n\nHARD RULES:\n- read_source MUST be your first call. If it returns an error, STOP and report it immediately. Do NOT write a placeholder source.md yourself, and do NOT write the chunk from memory.\n- Every fact must come from the fetched sources. If a claim is not supported by them, omit it. Never fill gaps from memory.\n- NO large quotes. A short quote (\u22642 sentences) is allowed ONLY as evidence under a bullet you already wrote in your own words.\n- Every bullet must be YOU re-expressing the idea. If you find yourself copying sentences, stop and rephrase.\n- One concept per chunk.\n- If the material is thin on a concept, write what exists; do NOT invent content. Omit empty sections.\n- Do NOT call add_topic. Do NOT write index.json.";
-export declare const TAG_SYSTEM_PROMPT = "You are a tag-phase worker. Enrich an existing topic with rich, retrieval-friendly tags.\n\nYour knowledge directory (~/.cc-monitoring/docs) stores a **dictionary**: concise, distilled entries a future reader can look up. You do NOT copy source text \u2014 you digest it.\n\nSTRUCTURE (all paths below are RELATIVE TO the knowledge root ~/.cc-monitoring/docs \u2014 the write tool's working directory IS this root, so NEVER prefix a path with \"docs/\"):\n- Each topic is a subfolder: <topic-slug>/\n- Each topic has <slug>/index.json (metadata + chunk list, NO body)\n- Bodies live in <topic-slug>/chunks/chunk-NNN.md\n- Root index.json lists all topics as JSON\n- Fetched source pages for a topic are already prepared in <slug>/sources/ \u2014 you only READ them, never write or modify them\n\nWORKFLOW:\n1. Call get_topic(slug) to list this topic's chunks.\n2. Call read_chunk for the chunks to understand the actual content.\n3. Generate 5 categories of tags (10-20 total), all lowercase hyphenated:\n   - synonyms: alternate names / aliases\n   - hypernym: broader parent concept (e.g. \"state-management\" for redux)\n   - trigger-scenarios: situations where a reader would reach for this (e.g. \"form-validation\")\n   - confusable: things this is often mixed up with\n   - typical-questions: questions a reader might search (e.g. \"how-does-usestate-work\")\n4. Call add_topic(slug, title, summary, tags) to OVERWRITE the topic's tags + metadata. Reuse the existing title and summary from get_topic; do not change them.\n\nHARD RULES:\n- Do NOT write chunk files. Do NOT call add_chunk.\n- Do NOT invent tags the content does not support.";
 export declare function createPiSession(options: CreatePiSessionOptions): Promise<AgentSession>;
 /**
  * 从任意文本截取第一个 `{` 到最后一个 `}` 之间的子串并解析为 JSON 对象。
@@ -27,4 +24,6 @@ export declare function runJsonPrompt(opts: {
     port: number;
     instructions: string;
     prompt: string;
+    signal?: AbortSignal;
 }): Promise<unknown>;
+export {};