@cc-monitoring/proxy-core 0.3.0 → 0.4.0

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

@@ -1,5 +1,4 @@
 import { spawn } from 'node:child_process';
-import { Type } from 'typebox';
 /**
  * 统一封装 ego-browser CLI：spawn 子进程 + 写入 Node 脚本 stdin，返回 cliLog 文本。
  * 每次调用独立进程，靠 useOrCreateTaskSpace 在同一 task space 复用 tab。
@@ -80,176 +79,3 @@ export function stripCliBanners(text) {
         .filter((line) => !line.startsWith('[ego-browser:notice]'))
         .join('\n');
 }
-// ---------- 工具实现辅助 ----------
-/** 把字符串参数安全注入脚本：JSON.stringify 自动处理引号 / 反斜杠 / 换行 */
-const jsLit = (v) => JSON.stringify(v);
-/** 构造 pi AgentToolResult（content + details 字段） */
-const ok = (text) => ({
-    content: [{ type: 'text', text }],
-    details: undefined,
-});
-const navigateSchema = Type.Object({
-    url: Type.String({ description: '目标 URL，必须是 http(s) 完整地址' }),
-    wait: Type.Optional(Type.Boolean({ description: '是否等待页面加载完成，默认 true' })),
-});
-const snapshotSchema = Type.Object({
-    scope: Type.Optional(Type.String({
-        description: "snapshotText 的 scope：'full_page'（默认）或 'only_within_viewport'",
-    })),
-});
-const screenshotSchema = Type.Object({});
-const clickSchema = Type.Object({
-    target: Type.String({
-        description: "点击目标：@N / CSS / 'xpath=...' / 'loc=...'，或 [x,y] 视口坐标数组",
-    }),
-    label: Type.Optional(Type.String({ description: '可选 3-6 字动作描述，用于高亮' })),
-});
-const typeSchema = Type.Object({
-    target: Type.String({ description: '输入框定位：@N / CSS / xpath=... / loc=...' }),
-    text: Type.String({ description: '要填入的文本内容' }),
-    submit: Type.Optional(Type.Boolean({ description: 'true 则填完后按 Enter，默认 false' })),
-});
-const scrollSchema = Type.Object({
-    direction: Type.String({
-        enum: ['down', 'up', 'bottom'],
-        description: "滚动方向：'down' / 'up' / 'bottom'（滚到底并触发懒加载）",
-    }),
-    amount: Type.Optional(Type.Number({ description: 'down/up 时的滚动像素量，默认 900' })),
-});
-const evaluateSchema = Type.Object({
-    expression: Type.String({
-        description: '页面内 JS 字符串。复杂逻辑用 IIFE：(() => { ... })()',
-    }),
-});
-const fetchSchema = Type.Object({
-    url: Type.String({ description: '要抓取的 URL' }),
-});
-const pressKeySchema = Type.Object({
-    key: Type.String({ description: "CDP 键名，如 'Enter' / 'Escape' / 'ArrowDown'" }),
-});
-export const browserTools = [
-    {
-        name: 'browser_navigate',
-        label: 'browser_navigate',
-        description: '在 ego-browser 的 knowledge-learn task space 中打开或复用 tab 到给定 URL。wait=true（默认）会等页面加载，timeout 20s。',
-        parameters: navigateSchema,
-        async execute(_id, params, signal) {
-            const url = jsLit(params.url);
-            const wait = params.wait ?? true;
-            const body = `
-await openOrReuseTab(${url}, { wait: ${wait}, timeout: 20 })
-const info = await pageInfo()
-cliLog(JSON.stringify(info))
-`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_snapshot',
-        label: 'browser_snapshot',
-        description: '获取当前页面的可访问性语义树（含 @N / loc= 引用），是后续 click/fillInput 定位元素的依据。默认 scope=full_page 覆盖整页。',
-        parameters: snapshotSchema,
-        async execute(_id, params, signal) {
-            const scope = params.scope ?? 'full_page';
-            const body = `cliLog(await snapshotText({ scope: ${jsLit(scope)} }))`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_screenshot',
-        label: 'browser_screenshot',
-        description: '对当前页面视口截图。返回 ego 输出的图片说明 / 路径文本。',
-        parameters: screenshotSchema,
-        async execute(_id, _params, signal) {
-            return ok(await runEgoBrowser('cliLog(await captureScreenshot())', { signal }));
-        },
-    },
-    {
-        name: 'browser_click',
-        label: 'browser_click',
-        description: '点击元素。target 支持 @N（来自最近一次 snapshotText）、CSS 选择器、xpath=...、loc=...（推荐长期稳定引用）。label 是 3-6 字动作描述，会触发高亮动画。',
-        parameters: clickSchema,
-        async execute(_id, params, signal) {
-            const target = jsLit(params.target);
-            const label = params.label ? `, { label: ${jsLit(params.label)} }` : '';
-            const body = `await click(${target}${label})\ncliLog('clicked: ${params.target}')`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_type',
-        label: 'browser_type',
-        description: '向输入框填充文本。target 同 browser_click（@N / CSS / xpath / loc）。submit=true 时填完后按 Enter（常用于搜索框）。',
-        parameters: typeSchema,
-        async execute(_id, params, signal) {
-            const target = jsLit(params.target);
-            const text = jsLit(params.text);
-            const submitBlock = params.submit ? `\nawait pressKey('Enter')` : '';
-            const body = `
-await fillInput(${target}, ${text})${submitBlock}
-cliLog('filled: ${params.target}')
-`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_scroll',
-        label: 'browser_scroll',
-        description: '滚动页面。direction=down/up 按 amount 像素滚动；direction=bottom 自动滚到底并尝试触发懒加载（最多 20 步）。',
-        parameters: scrollSchema,
-        async execute(_id, params, signal) {
-            let body;
-            if (params.direction === 'bottom') {
-                body = `
-await scrollToBottomUntil(
-  async () => false,
-  { step: 900, wait: 1, maxSteps: 20 }
-)
-cliLog('scrolled to bottom')
-`;
-            }
-            else {
-                const amount = params.amount ?? 900;
-                const signed = params.direction === 'down' ? amount : -amount;
-                body = `
-await scrollBy(${signed})
-cliLog('scrolled ${params.direction} ${amount}px')
-`;
-            }
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_evaluate',
-        label: 'browser_evaluate',
-        description: '在页面上下文执行 JS 字符串（等价于 Runtime.evaluate），返回序列化结果。多步逻辑请包成 IIFE：(() => { ... })()。不要把它当 Puppeteer page.evaluate(fn, ...args) 用。',
-        parameters: evaluateSchema,
-        async execute(_id, params, signal) {
-            const expr = jsLit(params.expression);
-            const body = `cliLog(JSON.stringify(await js(${expr})))`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_fetch',
-        label: 'browser_fetch',
-        description: '在当前浏览器页面上下文发起 fetch（复用登录态 / Cookie），返回响应正文文本。适合抓取需要鉴权的页面 JSON 或 HTML。',
-        parameters: fetchSchema,
-        async execute(_id, params, signal) {
-            const url = jsLit(params.url);
-            const body = `cliLog(await browserFetch(${url}))`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-    {
-        name: 'browser_press_key',
-        label: 'browser_press_key',
-        description: '在当前焦点元素按下键盘按键。key 用 CDP 键名，如 "Enter" / "Escape" / "Tab" / "ArrowDown" / "Control+A"。',
-        parameters: pressKeySchema,
-        async execute(_id, params, signal) {
-            const key = jsLit(params.key);
-            const body = `await pressKey(${key})\ncliLog('pressed: ${params.key}')`;
-            return ok(await runEgoBrowser(body, { signal }));
-        },
-    },
-];

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

@@ -25,6 +25,7 @@ export declare class CrawlGuard {
     private readonly maxPages;
     private readonly maxDepth;
     private readonly navigate;
+    private readonly vault;
     private entry;
     private readonly seen;
     private readonly depthByUrl;
@@ -58,5 +59,5 @@ export declare class CrawlGuard {
      */
     close(): Promise<void>;
 }
-export declare function createCrawlTools(guard: CrawlGuard): ToolDefinition[];
+export declare function createCrawlTools(guard: CrawlGuard, signal: AbortSignal): ToolDefinition[];
 export {};

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

@@ -3,11 +3,10 @@
 //   saveSource 落盘到 <slug>/sources/source-NNN.md
 // - createCrawlTools：挂给 pi session 的 4 个工具（crawl_open/crawl_visit/
 //   save_source/crawl_finish），错误以文本返回，LLM 可读可恢复
-import fs from 'node:fs';
-import path from 'node:path';
 import { Type } from 'typebox';
 import { runEgoBrowser } from './pi-browser-tools.js';
 import { CRAWL_MAX_PAGES, CRAWL_MAX_DEPTH, isSameSite, normalizeCandidate } from './web-crawler.js';
+import { createVault } from './vault.js';
 /** 单页浏览器脚本：task space 取 tab → goto → networkidle 缓冲 → 稳定性轮询 → 提取标题/正文/链接 */
 function buildCrawlScript(url) {
     return `const pages = await task.pages()
@@ -65,6 +64,12 @@ export class CrawlGuard {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "vault", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "entry", {
             enumerable: true,
             configurable: true,
@@ -108,6 +113,7 @@ export class CrawlGuard {
             writable: true,
             value: 0
         });
+        this.vault = createVault(opts.docsDir);
         this.maxPages = opts.maxPages ?? CRAWL_MAX_PAGES;
         this.maxDepth = opts.maxDepth ?? CRAWL_MAX_DEPTH;
         this.navigate = opts.navigate ?? ((url, signal) => this.defaultNavigate(url, signal));
@@ -208,10 +214,7 @@ export class CrawlGuard {
         // 对齐旧 crawlSite：trim 后为空的页面判失败，不产生空原料
         if (page.text.trim() === '')
             throw new Error(`save_source reject empty page: ${key}`);
-        const sourcesDir = path.join(this.opts.docsDir, this.opts.slug, 'sources');
-        fs.mkdirSync(sourcesDir, { recursive: true });
-        const name = `source-${String(this._savedCount + 1).padStart(3, '0')}.md`;
-        fs.writeFileSync(path.join(sourcesDir, name), `Source: ${key}\n\n${page.text}`, 'utf8');
+        this.vault.writeSourceFile(this.opts.slug, this._savedCount, key, page.text);
         this.savedUrls.add(key);
         this._savedCount += 1;
         return { savedCount: this._savedCount, reused: false };
@@ -234,16 +237,18 @@ const ok = (text) => ({
     details: undefined,
 });
 const errAsText = (e) => ok(`error: ${e instanceof Error ? e.message : String(e)}`);
-export function createCrawlTools(guard) {
+export function createCrawlTools(guard, signal) {
+    // SDK 传入 tool signal 时用它（session 中止时随之中止）；否则用外部 pipeline signal
+    const pickSignal = (toolSignal) => toolSignal ?? signal;
     return [
         {
             name: 'crawl_open',
             label: 'crawl_open',
             description: '打开本次任务的入口 URL，返回标题、正文与同站链接。抓取第一步调用。',
             parameters: Type.Object({}),
-            async execute(_id, _params, signal) {
+            async execute(_id, _params, toolSignal) {
                 try {
-                    return ok(JSON.stringify(await guard.open(signal)));
+                    return ok(JSON.stringify(await guard.open(pickSignal(toolSignal))));
                 }
                 catch (e) {
                     return errAsText(e);
@@ -255,9 +260,9 @@ export function createCrawlTools(guard) {
             label: 'crawl_visit',
             description: '访问入口同站的子页面（必须是 crawl_open/上一次 crawl_visit 返回链接中的 http(s) 页面）。',
             parameters: Type.Object({ url: Type.String({ description: '要访问的同站完整 URL' }) }),
-            async execute(_id, params, signal) {
+            async execute(_id, params, toolSignal) {
                 try {
-                    return ok(JSON.stringify(await guard.visit(params.url, signal)));
+                    return ok(JSON.stringify(await guard.visit(params.url, pickSignal(toolSignal))));
                 }
                 catch (e) {
                     return errAsText(e);

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

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

package/dist/utils/pi-dedup.js

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

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

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