@cc-monitoring/proxy-core 0.2.3 → 0.3.0

package/dist/utils/__tests__/pi-runtime-json.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/pi-runtime-json.test.js

@@ -0,0 +1,11 @@
+// pi-coding-agent 为 ESM-only（无 require 导出），jest CJS 无法加载；
+// mock 掉以加载真实 pi-runtime 模块测试纯函数（同 pi-browser-tools.test.ts 的 typebox mock 做法）
+jest.mock('@earendil-works/pi-coding-agent', () => ({ createWriteToolDefinition: () => ({}) }), { virtual: true });
+import { extractJsonObject } from '../pi-runtime.js';
+test('extractJsonObject: 从含 prose/代码围栏文本取出第一个 JSON 对象', () => {
+    const raw = 'Here:\n```json\n{"a":1,"b":[2,3]}\n```\ndone';
+    expect(extractJsonObject(raw)).toEqual({ a: 1, b: [2, 3] });
+});
+test('extractJsonObject: 无 JSON → throw', () => {
+    expect(() => extractJsonObject('no json here')).toThrow(/no json object/);
+});

package/dist/utils/__tests__/web-crawler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/web-crawler.test.js

@@ -0,0 +1,69 @@
+import { slugFromUrl, slugFromLabel, isSameSite, normalizeCandidate, } from '../web-crawler.js';
+describe('slugFromUrl', () => {
+    it('bare host without path', () => {
+        expect(slugFromUrl('https://pi.dev')).toBe('pi');
+    });
+    it('drops generic docs segment', () => {
+        expect(slugFromUrl('https://pi.dev/docs/intro')).toBe('pi-intro');
+    });
+    it('strips www and keeps at most 3 path segments', () => {
+        expect(slugFromUrl('https://www.example.com/a/b/c/d')).toBe('example-a-b-c');
+    });
+    it('ignores query and hash', () => {
+        expect(slugFromUrl('https://pi.dev/x?y=1#z')).toBe('pi-x');
+    });
+    it('throws on invalid url', () => {
+        expect(() => slugFromUrl('not a url')).toThrow();
+    });
+});
+describe('slugFromLabel', () => {
+    it('strips extension from ascii filename', () => {
+        expect(slugFromLabel('react-hooks.md')).toBe('react-hooks');
+    });
+    it('keeps the ascii stem and washes non-ascii chars away', () => {
+        expect(slugFromLabel('Pi 介绍.docx')).toBe('pi');
+    });
+    it('falls back to topic when nothing ascii remains', () => {
+        expect(slugFromLabel('介绍.docx')).toBe('topic');
+    });
+    it('takes basename and cleans spaces case-insensitively', () => {
+        expect(slugFromLabel('/tmp/dir/My Note.TXT')).toBe('my-note');
+    });
+});
+describe('isSameSite', () => {
+    it('subdomain is same site', () => {
+        expect(isSameSite('blog.pi.dev', 'pi.dev')).toBe(true);
+    });
+    it('www is equivalent to bare host', () => {
+        expect(isSameSite('www.pi.dev', 'pi.dev')).toBe(true);
+    });
+    it('cross domain is not same site', () => {
+        expect(isSameSite('other.com', 'pi.dev')).toBe(false);
+    });
+    it('suffix-without-dot is not same site', () => {
+        expect(isSameSite('notpi.dev', 'pi.dev')).toBe(false);
+    });
+});
+describe('normalizeCandidate', () => {
+    const entry = new URL('https://pi.dev/');
+    it('passes a normal http(s) link', () => {
+        const u = normalizeCandidate('https://pi.dev/a', entry);
+        expect(u?.href).toBe('https://pi.dev/a');
+    });
+    it('resolves relative links against entry', () => {
+        const u = normalizeCandidate('/about', entry);
+        expect(u?.href).toBe('https://pi.dev/about');
+    });
+    it('rejects non-http protocols like mailto', () => {
+        expect(normalizeCandidate('mailto:a@b.com', entry)).toBeNull();
+    });
+    it('excludes binary/document extensions', () => {
+        expect(normalizeCandidate('https://pi.dev/file.pdf', entry)).toBeNull();
+        expect(normalizeCandidate('https://pi.dev/PIC.JPG', entry)).toBeNull();
+    });
+    it('clears the hash', () => {
+        const u = normalizeCandidate('https://pi.dev/a#section', entry);
+        expect(u?.href).toBe('https://pi.dev/a');
+        expect(u?.hash).toBe('');
+    });
+});

package/dist/utils/knowledge-store.d.ts

@@ -8,6 +8,7 @@ export interface ChunkRef {
     id: string;
     title: string;
     summary: string;
+    tags: string[];
 }
 export interface TopicDetail {
     title: string;
@@ -36,6 +37,7 @@ export interface KnowledgeStore {
         chunkId: string;
         title: string;
         summary: string;
+        tags: string[];
     }): Promise<void>;
 }
 export declare function createKnowledgeStore(root: string): KnowledgeStore;

package/dist/utils/knowledge-store.js

@@ -53,7 +53,14 @@ export function createKnowledgeStore(root) {
             title: meta.title || topic,
             tags: Array.isArray(meta.tags) ? meta.tags : [],
             sources: [],
-            chunks: Array.isArray(meta.chunks) ? meta.chunks : [],
+            chunks: Array.isArray(meta.chunks)
+                ? meta.chunks.map(c => ({
+                    id: c.id,
+                    title: c.title,
+                    summary: c.summary,
+                    tags: Array.isArray(c.tags) ? c.tags : [],
+                }))
+                : [],
         };
     }
     async function upsertTopic(input) {
@@ -90,7 +97,7 @@ export function createKnowledgeStore(root) {
     async function upsertChunkRef(input) {
         assertTopic(input.topic);
         assertChunkId(input.chunkId);
-        const { topic, chunkId, title, summary } = input;
+        const { topic, chunkId, title, summary, tags } = input;
         const topicPath = path.join(root, topic, 'index.json');
         let topicIdx;
         try {
@@ -109,9 +116,10 @@ export function createKnowledgeStore(root) {
         if (existing) {
             existing.title = title;
             existing.summary = summary;
+            existing.tags = tags;
         }
         else {
-            topicIdx.chunks.push({ id: chunkId, title, summary });
+            topicIdx.chunks.push({ id: chunkId, title, summary, tags });
         }
         await fs.writeFile(topicPath, JSON.stringify(topicIdx, null, 2), 'utf8');
     }
@@ -120,6 +128,8 @@ export function createKnowledgeStore(root) {
             return [];
         const hits = [];
         const q = query.toLowerCase();
+        // topic index 本函数作用域缓存，避免每个 chunk 重复读
+        const topicIndexCache = new Map();
         let entries;
         try {
             entries = await fs.readdir(root);
@@ -130,6 +140,14 @@ export function createKnowledgeStore(root) {
         for (const topic of entries) {
             if (!TOPIC_RE.test(topic))
                 continue;
+            if (!topicIndexCache.has(topic)) {
+                const idx = await readJsonOr(path.join(root, topic, 'index.json'), null);
+                topicIndexCache.set(topic, idx);
+            }
+            const topicIdx = topicIndexCache.get(topic) ?? null;
+            const topicTags = topicIdx && Array.isArray(topicIdx.tags) ? topicIdx.tags : [];
+            const chunkRefs = topicIdx && Array.isArray(topicIdx.chunks) ? topicIdx.chunks : [];
+            const topicTagHit = topicTags.some(t => t.toLowerCase().includes(q));
             const chunksDir = path.join(root, topic, 'chunks');
             let files;
             try {
@@ -139,11 +157,19 @@ export function createKnowledgeStore(root) {
                 continue;
             }
             for (const file of files) {
-                if (!CHUNK_RE.test(file.replace(/\.md$/, '')))
+                const chunkId = file.replace(/\.md$/, '');
+                if (!CHUNK_RE.test(chunkId))
                     continue;
                 const text = await fs.readFile(path.join(chunksDir, file), 'utf8');
-                if (text.toLowerCase().includes(q)) {
-                    hits.push({ topic, chunkId: file.replace(/\.md$/, ''), title: parseChunkTitle(text) });
+                const ref = chunkRefs.find(c => c.id === chunkId);
+                const refTags = ref && Array.isArray(ref.tags) ? ref.tags : [];
+                const hit = text.toLowerCase().includes(q) ||
+                    (ref?.title ?? '').toLowerCase().includes(q) ||
+                    (ref?.summary ?? '').toLowerCase().includes(q) ||
+                    topicTagHit ||
+                    refTags.some(t => t.toLowerCase().includes(q));
+                if (hit) {
+                    hits.push({ topic, chunkId, title: parseChunkTitle(text) });
                 }
             }
         }

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

@@ -7,4 +7,6 @@ export declare function runEgoBrowser(scriptBody: string, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;
 }): Promise<string>;
+/** 过滤 ego-browser 自身打到输出流的横幅行（如升级 notice），保留脚本 cliLog 的真实输出 */
+export declare function stripCliBanners(text: string): string;
 export declare const browserTools: ToolDefinition[];

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

@@ -8,7 +8,7 @@ export function runEgoBrowser(scriptBody, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 30000;
     return new Promise((resolve, reject) => {
         // 头部自动注入 task space 复用调用
-        const script = `const task = await useOrCreateTaskSpace('knowledge-learn')\n${scriptBody}`;
+        const script = `const task = await taskSpace('knowledge-learn')\n${scriptBody}`;
         const child = spawn('ego-browser', ['nodejs'], {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -61,7 +61,7 @@ export function runEgoBrowser(scriptBody, opts = {}) {
                 return;
             if (code === 0) {
                 // 新版 ego cliLog 走 stderr；stdout 非空用 stdout，否则回退 stderr（新旧兼容）
-                const out = stdout.trim() ? stdout : stderr;
+                const out = stripCliBanners(stdout.trim() ? stdout : stderr);
                 finish(null, out);
             }
             else {
@@ -73,6 +73,13 @@ export function runEgoBrowser(scriptBody, opts = {}) {
         child.stdin.end(script, 'utf-8');
     });
 }
+/** 过滤 ego-browser 自身打到输出流的横幅行（如升级 notice），保留脚本 cliLog 的真实输出 */
+export function stripCliBanners(text) {
+    return text
+        .split('\n')
+        .filter((line) => !line.startsWith('[ego-browser:notice]'))
+        .join('\n');
+}
 // ---------- 工具实现辅助 ----------
 /** 把字符串参数安全注入脚本：JSON.stringify 自动处理引号 / 反斜杠 / 换行 */
 const jsLit = (v) => JSON.stringify(v);

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

@@ -0,0 +1,62 @@
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+export interface NavigatedPage {
+    title: string;
+    text: string;
+    links: string[];
+}
+interface PageData extends NavigatedPage {
+    url: string;
+}
+export interface CrawlGuardOptions {
+    entryUrl: string;
+    docsDir: string;
+    slug: string;
+    maxPages?: number;
+    maxDepth?: number;
+    /** 可注入的单页抓取（测试用）；默认调 runEgoBrowser；signal 用于中断在途抓取 */
+    navigate?: (url: string, signal?: AbortSignal) => Promise<NavigatedPage>;
+}
+export interface SaveSourceResult {
+    savedCount: number;
+    reused: boolean;
+}
+export declare class CrawlGuard {
+    private readonly opts;
+    private readonly maxPages;
+    private readonly maxDepth;
+    private readonly navigate;
+    private entry;
+    private readonly seen;
+    private readonly depthByUrl;
+    private readonly rawCache;
+    private readonly savedUrls;
+    private _savedCount;
+    private currentDepth;
+    constructor(opts: CrawlGuardOptions);
+    /** 默认单页抓取：跑 ego 脚本，JSON parse 失败硬抛错；signal 透传中断在途进程 */
+    private defaultNavigate;
+    /** 打开入口页：URL 校验 + 初始状态；signal 用于中断在途抓取 */
+    open(signal?: AbortSignal): Promise<PageData>;
+    /**
+     * 解析候选页的 BFS 最短深度：扫描每个已抓来源页的 links，
+     * 凡归一后命中候选页的来源，候选深度 = 来源深度 + 1，取所有命中的最小值。
+     * 一个来源都没查到（幻觉 URL）时硬抛错，绝不放行。
+     */
+    private resolveDepth;
+    /** 访问子页：同站/seen/链接来源/深度/页数硬校验（原因 cross-site/seen/not linked/max-depth/max-pages） */
+    visit(rawUrl: string, signal?: AbortSignal): Promise<PageData>;
+    /**
+     * 保存已抓取页原文到 <slug>/sources/source-NNN.md；必须先 open/visit 过该 URL。
+     * 同页重复保存不写新文件，返回已有编号 + reused=true；空正文页判失败。
+     */
+    saveSource(rawUrl: string): SaveSourceResult;
+    get savedCount(): number;
+    /**
+     * 抓取结束清理：no-op。
+     * 不能调 task.finish()——它会关闭全部 page 并把 space 所有权交还 user，
+     * 导致下一次 learn 的 taskSpace() resume 失败；持久 space 与 tab 留给后续复用。
+     */
+    close(): Promise<void>;
+}
+export declare function createCrawlTools(guard: CrawlGuard): ToolDefinition[];
+export {};

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;