@cc-monitoring/proxy-core 0.2.3 → 0.3.1

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

@@ -0,0 +1,298 @@
+// crawl 阶段工具：LLM Agent 在 outline 阶段内自己驱动渐进抓取。
+// - CrawlGuard：同站/深度/页数硬校验的有状态抓取器，抓取过的原文存内存缓存，
+//   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';
+/** 单页浏览器脚本：task space 取 tab → goto → networkidle 缓冲 → 稳定性轮询 → 提取标题/正文/链接 */
+function buildCrawlScript(url) {
+    return `const pages = await task.pages()
+const page = pages.find(p => p.label === 'p1') ?? pages[0] ?? await task.newPage()
+await page.goto(${JSON.stringify(url)}, { waitUntil: 'load', timeout: 30000 })
+try { await page.waitForLoadState('networkidle', { timeout: 5000 }) } catch {}
+// 稳定性：500ms 采一次 innerText.length，连续 2 次相同且 >0，最多 10 次
+await page.evaluate(() => new Promise((resolve) => {
+  let last = -1, same = 0, n = 0
+  const tick = () => {
+    const len = document.body ? document.body.innerText.length : 0
+    if (len > 0 && len === last) {
+      same += 1
+      if (same >= 2) return resolve()
+    } else {
+      same = 0
+    }
+    last = len
+    if (++n >= 10) return resolve()
+    setTimeout(tick, 500)
+  }
+  tick()
+}))
+const data = await page.evaluate(() => ({
+  title: document.title,
+  text: document.body ? document.body.innerText : '',
+  links: Array.from(document.querySelectorAll('a[href]')).map(a => a.href),
+}))
+cliLog(JSON.stringify(data))
+`;
+}
+export class CrawlGuard {
+    constructor(opts) {
+        Object.defineProperty(this, "opts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: opts
+        });
+        Object.defineProperty(this, "maxPages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "maxDepth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "navigate", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "entry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "seen", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "depthByUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "rawCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        // 已落盘过的 URL（防重复原料）
+        Object.defineProperty(this, "savedUrls", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "_savedCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "currentDepth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        this.maxPages = opts.maxPages ?? CRAWL_MAX_PAGES;
+        this.maxDepth = opts.maxDepth ?? CRAWL_MAX_DEPTH;
+        this.navigate = opts.navigate ?? ((url, signal) => this.defaultNavigate(url, signal));
+    }
+    /** 默认单页抓取：跑 ego 脚本，JSON parse 失败硬抛错；signal 透传中断在途进程 */
+    async defaultNavigate(url, signal) {
+        const raw = await runEgoBrowser(buildCrawlScript(url), { timeoutMs: 60000, signal });
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`crawl: failed to parse result from ${url}`);
+        }
+        return {
+            title: typeof data.title === 'string' ? data.title : '',
+            text: typeof data.text === 'string' ? data.text : '',
+            links: Array.isArray(data.links) ? data.links.filter((l) => typeof l === 'string') : [],
+        };
+    }
+    /** 打开入口页：URL 校验 + 初始状态；signal 用于中断在途抓取 */
+    async open(signal) {
+        const entry = new URL(this.opts.entryUrl);
+        entry.hash = '';
+        this.entry = entry;
+        this.seen.add(entry.href);
+        this.depthByUrl.set(entry.href, 0);
+        this.currentDepth = 0;
+        const page = await this.navigate(entry.href, signal);
+        this.rawCache.set(entry.href, page);
+        return { url: entry.href, ...page };
+    }
+    /**
+     * 解析候选页的 BFS 最短深度：扫描每个已抓来源页的 links，
+     * 凡归一后命中候选页的来源，候选深度 = 来源深度 + 1，取所有命中的最小值。
+     * 一个来源都没查到（幻觉 URL）时硬抛错，绝不放行。
+     */
+    resolveDepth(candidate) {
+        let resolved = null;
+        for (const [sourceHref, page] of this.rawCache) {
+            for (const link of page.links) {
+                const linked = normalizeCandidate(link, this.entry);
+                if (linked && linked.href === candidate.href) {
+                    const next = this.depthByUrl.get(sourceHref) + 1;
+                    if (resolved === null || next < resolved)
+                        resolved = next;
+                    break; // 本来源页已命中，不必再看它其余 links
+                }
+            }
+        }
+        if (resolved === null) {
+            throw new Error(`crawl visit reject: ${candidate.href} not linked from any crawled page`);
+        }
+        return resolved;
+    }
+    /** 访问子页：同站/seen/链接来源/深度/页数硬校验（原因 cross-site/seen/not linked/max-depth/max-pages） */
+    async visit(rawUrl, signal) {
+        const candidate = normalizeCandidate(rawUrl, this.entry);
+        if (!candidate)
+            throw new Error(`crawl visit reject: invalid or binary url: ${rawUrl}`);
+        if (!isSameSite(candidate.hostname, this.entry.hostname)) {
+            throw new Error(`crawl visit reject cross-site: ${candidate.href}`);
+        }
+        if (this.seen.has(candidate.href)) {
+            throw new Error(`crawl visit reject seen: ${candidate.href}`);
+        }
+        // BFS 最短深度（候选必须由某个已抓页链接；未链接直接 throw）
+        const nextDepth = this.resolveDepth(candidate);
+        if (nextDepth > this.maxDepth) {
+            throw new Error(`crawl visit reject max-depth: ${candidate.href}`);
+        }
+        if (this.seen.size + 1 > this.maxPages) {
+            throw new Error(`crawl visit reject max-pages: ${candidate.href}`);
+        }
+        const page = await this.navigate(candidate.href, signal);
+        this.seen.add(candidate.href);
+        this.depthByUrl.set(candidate.href, nextDepth);
+        this.currentDepth = nextDepth;
+        this.rawCache.set(candidate.href, page);
+        return { url: candidate.href, ...page };
+    }
+    /**
+     * 保存已抓取页原文到 <slug>/sources/source-NNN.md；必须先 open/visit 过该 URL。
+     * 同页重复保存不写新文件，返回已有编号 + reused=true；空正文页判失败。
+     */
+    saveSource(rawUrl) {
+        let key = rawUrl;
+        const candidate = normalizeCandidate(rawUrl, this.entry);
+        if (candidate)
+            key = candidate.href;
+        const page = this.rawCache.get(key);
+        if (!page)
+            throw new Error(`save_source reject: url not crawled: ${rawUrl}`);
+        // 已存过：不重复落盘，返回已有编号
+        if (this.savedUrls.has(key)) {
+            return { savedCount: this._savedCount, reused: true };
+        }
+        // 对齐旧 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.savedUrls.add(key);
+        this._savedCount += 1;
+        return { savedCount: this._savedCount, reused: false };
+    }
+    get savedCount() {
+        return this._savedCount;
+    }
+    /**
+     * 抓取结束清理：no-op。
+     * 不能调 task.finish()——它会关闭全部 page 并把 space 所有权交还 user，
+     * 导致下一次 learn 的 taskSpace() resume 失败；持久 space 与 tab 留给后续复用。
+     */
+    async close() { }
+}
+// ============================================================
+// ToolDefinition 构造（写法对齐 pi-runtime，ok/err 返回）
+// ============================================================
+const ok = (text) => ({
+    content: [{ type: 'text', text }],
+    details: undefined,
+});
+const errAsText = (e) => ok(`error: ${e instanceof Error ? e.message : String(e)}`);
+export function createCrawlTools(guard) {
+    return [
+        {
+            name: 'crawl_open',
+            label: 'crawl_open',
+            description: '打开本次任务的入口 URL，返回标题、正文与同站链接。抓取第一步调用。',
+            parameters: Type.Object({}),
+            async execute(_id, _params, signal) {
+                try {
+                    return ok(JSON.stringify(await guard.open(signal)));
+                }
+                catch (e) {
+                    return errAsText(e);
+                }
+            },
+        },
+        {
+            name: 'crawl_visit',
+            label: 'crawl_visit',
+            description: '访问入口同站的子页面（必须是 crawl_open/上一次 crawl_visit 返回链接中的 http(s) 页面）。',
+            parameters: Type.Object({ url: Type.String({ description: '要访问的同站完整 URL' }) }),
+            async execute(_id, params, signal) {
+                try {
+                    return ok(JSON.stringify(await guard.visit(params.url, signal)));
+                }
+                catch (e) {
+                    return errAsText(e);
+                }
+            },
+        },
+        {
+            name: 'save_source',
+            label: 'save_source',
+            description: '把当前已抓取页面的原文保存到本主题 sources/ 目录。每打开一页后调用一次；同页重复保存不写新文件。',
+            parameters: Type.Object({ url: Type.String({ description: '刚抓取的页面 URL' }) }),
+            async execute(_id, params) {
+                try {
+                    // 直接返回 { savedCount, reused }
+                    return ok(JSON.stringify(guard.saveSource(params.url)));
+                }
+                catch (e) {
+                    return errAsText(e);
+                }
+            },
+        },
+        {
+            name: 'crawl_finish',
+            label: 'crawl_finish',
+            description: '结束抓取：清理浏览器并返回已保存页数。无更多有价值链接或到达上限时调用。',
+            parameters: Type.Object({}),
+            async execute() {
+                try {
+                    await guard.close();
+                    return ok(JSON.stringify({ finished: true, savedCount: guard.savedCount }));
+                }
+                catch (e) {
+                    return errAsText(e);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,62 @@
+export interface TopicSummary {
+    slug: string;
+    title: string;
+    summary: string;
+    tags: string[];
+}
+export declare function normalizeText(s: string): string;
+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 {
+    match: boolean;
+    targetSlug?: string;
+    confidence?: number;
+    mergedTitle?: string;
+    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 reconcileTopics(opts: {
+    port: number;
+    docsDir: string;
+    candidate: {
+        slug: string;
+        title: string;
+        tags: string[];
+        items?: OutlineItem[];
+    };
+    targets?: Array<TopicSummary & {
+        chunks?: ChunkRefLike[];
+    }>;
+    wantItems: boolean;
+}): 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 mintSlug(opts: {
+    port: number;
+    title: string;
+    existing: string[];
+}): Promise<string>;
+export declare function assertNoOldDirs(docsDir: string): void;

package/dist/utils/pi-dedup.js

@@ -0,0 +1,218 @@
+// learn 主题去重：纯字符串确定性预筛（不调 LLM、无 IO）
+import { readFile } from 'fs/promises';
+import fs from 'node:fs';
+import path from 'path';
+import { runJsonPrompt } from './pi-runtime.js';
+import { slugFromLabel } from './web-crawler.js';
+// 合法 slug：小写字母数字开头，仅含小写字母数字与连字符
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+// 归一化：小写；非字母数字字符（含 -、_、! 等标点）统一替换为空格；trim 并压缩连续空白
+// 标点替换为空格而非删除，使 state-management 与 State Management 归一后一致
+export function normalizeText(s) {
+    return s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+}
+// 命中信号强度：归一 title 相等(0) > 任一归一 tag 相等(1) > title 互为子串(2)
+export function findCandidates(cand, topics) {
+    const candTitle = normalizeText(cand.title);
+    const candTags = new Set(cand.tags.map(normalizeText).filter(Boolean));
+    // slug -> 命中的 topic 及其最强信号；按 slug 去重
+    const hits = new Map();
+    for (const topic of topics) {
+        const topicTitle = normalizeText(topic.title);
+        let rank = -1;
+        if (candTitle && topicTitle === candTitle) {
+            rank = 0;
+        }
+        else if (topic.tags.some(t => candTags.has(normalizeText(t)))) {
+            rank = 1;
+        }
+        else if (candTitle && topicTitle && (topicTitle.includes(candTitle) || candTitle.includes(topicTitle))) {
+            rank = 2;
+        }
+        if (rank === -1)
+            continue;
+        const prev = hits.get(topic.slug);
+        if (!prev || rank < prev.rank)
+            hits.set(topic.slug, { topic, rank });
+    }
+    // sort 稳定，同强度保持 topics 原始顺序
+    return [...hits.values()].sort((a, b) => a.rank - b.rank).map(h => h.topic);
+}
+// 预筛无命中时允许全量送 LLM 的目标上限；超过则安全放弃
+export 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 [];
+    }
+}
+// 读单个 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;
+    }
+}
+// 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);
+    // 先走确定性预筛；无命中且目标数在上限内才全量送 LLM，超限直接放弃
+    const hits = findCandidates({ title: opts.candidate.title, tags: opts.candidate.tags }, targets);
+    let chosen;
+    if (hits.length > 0) {
+        chosen = hits;
+    }
+    else if (targets.length > 0 && targets.length <= LLM_FULL_SCAN_MAX) {
+        chosen = targets;
+    }
+    else {
+        return { match: false };
+    }
+    const instructions = [
+        '你是主题去重裁定器。判断「新主题」与候选已有主题之间是否存在实质内容重叠。',
+        '判定从宽：只要主题域/核心问题实质重合就应判为重复，宁可合并，不要因措辞或粒度不同而漏判。',
+        '存在多个可能目标时，只选最匹配的一个，把它的 slug 填入 targetSlug。',
+        '判为重复时必须给出 mergedTitle（合并后的主题标题）与 mergedSummary（合并后的摘要）。',
+        opts.wantItems
+            ? '同时给出 itemsToAdd：仅包含目标主题现有 chunks 尚未覆盖的、需要新增的大纲条目；已覆盖的条目不要放入。'
+            : '不要输出 itemsToAdd。',
+        '只返回一个 JSON 对象，不要输出任何解释或多余文本。',
+        '格式：{"match":boolean,"targetSlug":string,"confidence":number,"mergedTitle":string,"mergedSummary":string'
+            + (opts.wantItems ? ',"itemsToAdd":[{"id":string,"title":string,"oneLine":string}]' : '')
+            + '}',
+    ].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 });
+        // 正载荷必须完整，且 targetSlug 必须在实际提供的 chosen 之中，否则安全降级
+        // （同时挡住候选自身 slug 回显、../ 路径穿越及任何未提供的目标）
+        const chosenSlugs = chosen.map(t => t.slug);
+        if (result && result.match === true &&
+            typeof result.targetSlug === 'string' && chosenSlugs.includes(result.targetSlug) &&
+            typeof result.mergedTitle === 'string' &&
+            typeof result.mergedSummary === 'string' &&
+            (!opts.wantItems || Array.isArray(result.itemsToAdd))) {
+            return result;
+        }
+        return { match: false };
+    }
+    catch {
+        return { match: false };
+    }
+}
+// ---- 物理迁移：把 src 主题的 sources/chunks 统一并入 dst ----
+// 3 位补零编号，与 orchestrator 落盘约定一致
+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 旁挂目录（含点，路径直接拼接）。
+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'));
+    // 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 });
+    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));
+    });
+    // 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 });
+    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`));
+        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'));
+        if (Array.isArray(root.topics)) {
+            root.topics = root.topics.filter(t => t.slug !== srcSlug);
+            fs.writeFileSync(rootPath, JSON.stringify(root, null, 2));
+        }
+    }
+    catch {
+        // 根 index 缺失/损坏：无条目可移除，跳过
+    }
+    // 删除整个 src 目录，写回 dst index
+    fs.rmSync(srcDir, { recursive: true, force: true });
+    fs.writeFileSync(path.join(dstDir, 'index.json'), JSON.stringify(dstIndex, null, 2));
+    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;
+    }
+}
+// 据 title 让 LLM 铸一个小写连字符 slug。失败/非法/已占 → 降级 slugFromLabel(title)，
+// 仍被占则追加 -2/-3…。返回保证合法且不落在 existing 内的 slug（除非编号也耗尽，实践不会）。
+export async function mintSlug(opts) {
+    try {
+        const result = await runJsonPrompt({
+            port: opts.port,
+            instructions: 'Return ONLY JSON {"slug":"<lowercase-hyphen-slug>"} derived faithfully from the title.',
+            prompt: `Title: ${opts.title}`,
+        });
+        if (typeof result.slug === 'string' && SLUG_RE.test(result.slug) && !opts.existing.includes(result.slug)) {
+            return result.slug;
+        }
+    }
+    catch {
+        // LLM 调用/解析失败：走确定性降级
+    }
+    const base = slugFromLabel(opts.title) || 'topic';
+    if (!opts.existing.includes(base))
+        return base;
+    for (let n = 2;; n++) {
+        const candidate = `${base}-${n}`;
+        if (!opts.existing.includes(candidate))
+            return candidate;
+    }
+}
+// 阻断：docsDir 下存在任何 .old 旁挂目录时抛错，要求人工先处理。
+// docsDir 本身缺失时直接让 readdirSync 抛错（调用方本就应在已初始化的库上学习）。
+export function assertNoOldDirs(docsDir) {
+    const oldDir = fs.readdirSync(docsDir).find(name => name.endsWith('.old'));
+    if (oldDir) {
+        throw new Error(`检测到未清理的旁挂目录 ${oldDir}，请手工处理后再学习`);
+    }
+}

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

@@ -0,0 +1,44 @@
+export interface OutlineItem {
+    id: string;
+    title: string;
+    oneLine: string;
+}
+export interface LearnPipelineEvents {
+    stageStart(stage: 'outline' | 'refine' | 'tag', totalItems?: number): void;
+    stageItemStart(index: number, total: number, title: string): void;
+    stageItemEnd(index: number, chunkId: string): void;
+    stageItemFailed(index: number, title: string, reason: string): void;
+    stageEnd(stage: 'outline' | 'refine' | 'tag'): void;
+    roundStart(roundIndex: number): void;
+    roundEnd(roundIndex: number): void;
+    textDelta(delta: string): void;
+    thinkingDelta(delta: string): void;
+    toolStart(e: {
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    }): void;
+    toolEnd(e: {
+        toolCallId: string;
+        toolName: string;
+        isError: boolean;
+        durationMs: number;
+        result: string;
+    }): void;
+}
+export interface RunLearnPipelineOptions {
+    sourceType: 'url' | 'file';
+    /** url 模式=入口 URL；file 模式=上传得到的 markdown 正文 */
+    input: string;
+    /** file 模式文件名（生成 slug 用）；url 可省略 */
+    label?: string;
+    port: number;
+    events: LearnPipelineEvents;
+    /** 注入式 docsDir（测试用）；默认 ~/.cc-monitoring/docs */
+    docsDir?: string;
+}
+export declare function runLearnPipeline(opts: RunLearnPipelineOptions): Promise<{
+    slug: string;
+    chunksWritten: number;
+    itemsFailed: number;
+}>;