@cc-monitoring/proxy-core 0.2.3 → 0.3.1

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

@@ -0,0 +1,431 @@
+// pi-learn-orchestrator: outline/refine/tag 三阶段 learn 流水线
+// - outline: url 模式先由 crawl agent 在阶段内自己驱动渐进抓取（crawl_open/crawl_visit/
+//   save_source）写 sources/，再由单次 outline session read_source + add_outline
+//   写 outline.json + seed topic；file 模式直接把上传正文写 sources/
+// - refine: 对 outline.items 逐项开新 refine session，写 chunks/chunk-NNN.md
+// - tag: 单次 tag session，读 chunks 后调 add_topic 写富 tags
+//
+// "轮次" = 一次 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 { slugFromUrl, slugFromLabel } from './web-crawler.js';
+import { assertNoOldDirs, readAllTopics, readSidecarDetail, readTopicDetail, reconcileTopics, mergeTopics, mintSlug } from './pi-dedup.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) {
+    const result = { addTopicCalled: false, readSourceOk: false };
+    // Finding 1：tool_execution_start 时只记录「即将调 add_topic 且 tags 非空」，
+    // 真正置位必须等 tool_execution_end 且 isError=false。否则工具执行失败（upsert
+    // 抛错/非法 slug/JSON 写失败）时重试循环会误判成功。
+    let pendingAddTopicWithTags = false;
+    // 当前轮次索引：message_start 时记录，message_end 透传同一个值
+    let currentRound = 0;
+    // 轮次是否在途：pi abort 时在途 assistant message 不发 message_end，
+    // finally 需据此补发 roundEnd，保证任何退出路径轮次闭合
+    let roundOpen = false;
+    const unsub = session.subscribe((ev) => {
+        try {
+            if (ev.type === 'message_start' && ev.message?.role === 'assistant') {
+                currentRound = roundCounter.index;
+                roundCounter.index += 1;
+                roundOpen = true;
+                events.roundStart(currentRound);
+            }
+            else if (ev.type === 'message_end' && ev.message?.role === 'assistant') {
+                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);
+                }
+                else if (ae?.type === 'thinking_delta' && typeof ae.delta === 'string') {
+                    events.thinkingDelta(ae.delta);
+                }
+            }
+            else if (ev.type === 'tool_execution_start') {
+                events.toolStart({
+                    toolCallId: ev.toolCallId,
+                    toolName: ev.toolName,
+                    args: ev.args,
+                });
+                if (ev.toolName === 'add_topic') {
+                    const tags = ev.args?.tags;
+                    pendingAddTopicWithTags = Array.isArray(tags) && tags.length > 0;
+                }
+            }
+            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;
+                }
+                if (ev.toolName === 'read_source' && !ev.isError) {
+                    result.readSourceOk = true;
+                }
+                events.toolEnd({
+                    toolCallId: ev.toolCallId,
+                    toolName: ev.toolName,
+                    isError: !!ev.isError,
+                    durationMs: ev.durationMs ?? 0,
+                    result: resultText,
+                });
+            }
+        }
+        catch {
+            // 事件转发失败不中断流水线
+        }
+    });
+    try {
+        // Finding 3：整个 prompt + waitForIdle 包 5 分钟超时；超时 abort 并抛错。
+        await withTimeout((async () => {
+            await session.prompt(promptText);
+            await session.waitForIdle();
+        })(), STAGE_TIMEOUT_MS, () => session.abort());
+    }
+    finally {
+        unsub();
+        // 在途轮次补闭合（abort/超时/异常导致 message_end 缺失）；回调异常不外泄
+        if (roundOpen) {
+            try {
+                events.roundEnd(currentRound);
+            }
+            catch { /* 忽略 */ }
+        }
+    }
+    return result;
+}
+// ============================================================
+// 原料准备 + 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) {
+    // 抓取必须在 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 });
+            let crawlSession = (await createPiSession({
+                port: opts.port,
+                mode: 'crawl',
+                crawlGuard: guard,
+            }));
+            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) {
+                // 替换前关闭旧 guard（close 容错），再全新 guard + session 重试一次
+                await guard.close();
+                guard = new CrawlGuard({ entryUrl: opts.input, docsDir: opts.docsDir, slug: opts.slug });
+                crawlSession = (await createPiSession({
+                    port: opts.port,
+                    mode: 'crawl',
+                    crawlGuard: guard,
+                }));
+                await runPrompt(crawlSession, crawlPrompt, events, roundCounter);
+                if (countSourceFiles(opts.docsDir, opts.slug) === 0) {
+                    throw new Error('crawl 未收集到页面');
+                }
+            }
+        }
+        else {
+            writeSourceFile(opts.docsDir, 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'));
+        // 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 };
+    }
+    finally {
+        // 兜底关闭当前 guard（crawl_finish 已关时 close 也安全）
+        await guard?.close();
+        events.stageEnd('outline');
+    }
+}
+// ============================================================
+// refine 阶段
+// ============================================================
+async function runRefineStage(opts, slug, items, events, roundCounter, 
+/** chunk id 起始偏移：合并进已有主题时从目标现有 chunk 数后续号 */
+startOffset = 0) {
+    events.stageStart('refine', items.length);
+    let chunksWritten = 0;
+    let itemsFailed = 0;
+    try {
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            const chunkId = `chunk-${String(startOffset + i + 1).padStart(3, '0')}`;
+            events.stageItemStart(i, items.length, item.title);
+            try {
+                const prompt = `主题 slug: ${slug}\n` +
+                    `概念: ${item.title}\n` +
+                    `说明: ${item.oneLine}\n` +
+                    `请读 source.md 相关段落，写 chunks/${chunkId}.md，然后调 add_chunk 带 tags`;
+                let ok = false;
+                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);
+                    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)
+                            ok = true;
+                    }
+                    catch {
+                        // 不存在 → 重试
+                    }
+                }
+                // Finding 2：chunk 文件非空不等于 add_chunk 被调。校验 index.json.chunks
+                // 里真的有这个 chunkId，否则文件是孤儿（tag 阶段从 index.json 读 chunk 列表会静默跳过）。
+                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);
+                    }
+                    catch {
+                        // index.json 读失败/JSON 坏 → 当作未注册
+                        chunkRegistered = false;
+                    }
+                    if (!chunkRegistered) {
+                        ok = false;
+                        failReason = 'add_chunk 未调用';
+                    }
+                }
+                if (ok) {
+                    chunksWritten++;
+                    events.stageItemEnd(i, chunkId);
+                }
+                else {
+                    itemsFailed++;
+                    events.stageItemFailed(i, item.title, failReason);
+                }
+            }
+            catch (e) {
+                // per-item 任意错误（createPiSession 失败、prompt 抛错等）→ 不中断整个 refine 阶段
+                itemsFailed++;
+                events.stageItemFailed(i, item.title, e?.message || String(e));
+            }
+        }
+    }
+    finally {
+        events.stageEnd('refine');
+    }
+    return { chunksWritten, itemsFailed };
+}
+// ============================================================
+// tag 阶段
+// ============================================================
+async function runTagStage(opts, slug, events, roundCounter, 
+/** 合并场景：查重门裁定的合并后 title/summary，要求 add_topic 设置为该精确值 */
+override) {
+    events.stageStart('tag');
+    try {
+        const topicIdxPath = path.join(opts.docsDir, slug, 'index.json');
+        const topicIdx = JSON.parse(fs.readFileSync(topicIdxPath, 'utf8'));
+        // 合并后重跑 tag：title/summary 取 override 精确值；否则沿用现有值
+        const title = override?.title ?? topicIdx.title;
+        const summary = override?.summary ?? topicIdx.summary;
+        const chunkListing = (topicIdx.chunks ?? [])
+            .map((c) => `- ${c.id}: ${c.title} — ${c.summary}`)
+            .join('\n');
+        const prompt = `主题 slug: ${slug}\n` +
+            `现有 title: ${title}\n` +
+            `现有 summary: ${summary}\n` +
+            `已有 chunks:\n${chunkListing}\n\n` +
+            `请用 read_chunk 读 chunks 实际内容，为该主题生成 5 类富 tags（同义/上位/触发场景/易混淆/典型提问，共 10-20 个小写连字符），` +
+            (override
+                ? `然后调 add_topic({ slug, title, summary, tags }) 覆盖主题元数据。title/summary 必须使用上面给出的精确值，不要改动。`
+                : `然后调 add_topic({ slug, title, summary, tags }) 覆盖主题元数据。title/summary 复用现有值，不要改。`);
+        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);
+            if (res.addTopicCalled) {
+                tagged = true;
+                break;
+            }
+        }
+        if (!tagged) {
+            throw new Error('add_topic 未调用');
+        }
+    }
+    finally {
+        events.stageEnd('tag');
+    }
+}
+// ============================================================
+// 主编排
+// ============================================================
+export async function runLearnPipeline(opts) {
+    const docsDir = opts.docsDir ?? path.join(dataDir, 'docs');
+    const slug = opts.sourceType === 'url' ? slugFromUrl(opts.input) : slugFromLabel(opts.label ?? 'topic');
+    // 阻断：存在未清理的 .old 旁挂目录时直接拒绝，必须在一切写入之前
+    assertNoOldDirs(docsDir);
+    // 全局轮次计数器：所有 session 共享，轮次索引全流水线单调递增
+    const roundCounter = { index: 0 };
+    // activeSlug：门0 slug 碰撞另铸后，下游各门/阶段实际操作的 slug
+    let activeSlug = slug;
+    let outline;
+    // 门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);
+        const sidecar = await readSidecarDetail(docsDir, slug);
+        const r0 = await reconcileTopics({
+            port: opts.port,
+            docsDir,
+            candidate: { slug, title: outline.title, tags: [], items: outline.items },
+            targets: sidecar ? [sidecar] : [],
+            wantItems: true,
+        });
+        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 });
+            return { slug, chunksWritten: refine.chunksWritten, itemsFailed: refine.itemsFailed };
+        }
+        // slug 真碰撞：新内容另铸 ns，旧 topic 还原
+        const ns = await mintSlug({
+            port: opts.port,
+            title: outline.title,
+            existing: (await readAllTopics(docsDir)).map((t) => t.slug),
+        });
+        // 新 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'));
+        nsIdx.slug = ns;
+        fs.writeFileSync(nsIdxPath, JSON.stringify(nsIdx, null, 2), 'utf8');
+        // 根 index：把 S1 为新内容登记的 slug 条目改挂 ns
+        const rootPath = path.join(docsDir, 'index.json');
+        const rootIdx = JSON.parse(fs.readFileSync(rootPath, 'utf8'));
+        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'));
+        const oldRoot = rootIdx.topics.find((t) => t.slug === slug);
+        if (oldRoot) {
+            oldRoot.title = oldIdx.title;
+            oldRoot.summary = oldIdx.summary;
+            oldRoot.tags = oldIdx.tags;
+        }
+        else {
+            rootIdx.topics.push({ slug, title: oldIdx.title, summary: oldIdx.summary, tags: oldIdx.tags });
+        }
+        fs.writeFileSync(rootPath, JSON.stringify(rootIdx, null, 2), 'utf8');
+        activeSlug = ns;
+    }
+    else {
+        prepareTopicDir(docsDir, slug);
+        outline = await runOutlineStage({ ...opts, docsDir, slug }, opts.events, roundCounter);
+    }
+    // 门1：outline 后、refine 前，基于大纲条目查重（命中则只要需新增的条目）
+    const r1 = await reconcileTopics({
+        port: opts.port,
+        docsDir,
+        candidate: { slug: activeSlug, title: outline.title, tags: [], items: outline.items },
+        wantItems: true,
+    });
+    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 });
+        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);
+    // 门2：tag 后基于富 tags 再查一次（不需要新增条目）
+    const detail = await readTopicDetail(docsDir, activeSlug);
+    const r2 = await reconcileTopics({
+        port: opts.port,
+        docsDir,
+        candidate: { slug: activeSlug, title: outline.title, tags: detail?.tags ?? [], items: undefined },
+        wantItems: false,
+    });
+    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 });
+        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,8 +1,30 @@
 import { type AgentSession } from '@earendil-works/pi-coding-agent';
-export type PiSessionMode = 'chat' | 'learn';
+import { type CrawlGuard } from './pi-crawl-tools.js';
+export type PiSessionMode = 'chat' | 'outline' | 'refine' | 'tag' | 'crawl' | 'reconcile';
 export interface CreatePiSessionOptions {
     cwd?: string;
     port: number;
     mode: PiSessionMode;
+    /** mode='crawl' 时必填：渐进抓取状态守卫 */
+    crawlGuard?: CrawlGuard;
 }
+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 对象。
+ * 容忍 prose / 代码围栏包裹。无 `{` 或解析失败时抛错。
+ */
+export declare function extractJsonObject<T>(raw: string): T;
+/**
+ * 建 reconcile（无工具）session，跑一次纯 JSON 调用并返回解析结果。
+ * instructions 与 prompt 合并为单条用户消息：规则在前，JSON 数据在后。
+ */
+export declare function runJsonPrompt(opts: {
+    port: number;
+    instructions: string;
+    prompt: string;
+}): Promise<unknown>;