@cc-monitoring/proxy-core 0.3.1 → 0.4.1

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;

package/dist/utils/pi-events.js

@@ -0,0 +1,98 @@
+// pi-events: pi SDK 原始事件 → 会话领域事件的映射原语。
+// learn orchestrator / chat SSE / runJsonPrompt 三处订阅共用同一套映射规则。
+//
+// "轮次" = 一次 assistant 交互（assistant message_start → message_end），
+// 轮次索引 1-based。
+/**
+ * 是否 assistant 消息边界（message_start / message_end 分支内调用）。
+ * message_start 对 user / assistant / toolResult 三种消息都会触发，
+ * 只有 assistant 对应一次 LLM 回复轮次。
+ */
+export function isAssistantMessage(ev) {
+    return ev?.message?.role === 'assistant';
+}
+/**
+ * 从 message_update 事件解包 assistant 流 delta：
+ * ae.type 为 text_delta / thinking_delta 且 delta 为 string 时返回，否则 null。
+ */
+export function extractAssistantDelta(ev) {
+    if (ev?.type !== 'message_update')
+        return null;
+    const ae = ev.assistantMessageEvent;
+    if ((ae?.type === 'text_delta' || ae?.type === 'thinking_delta') && typeof ae.delta === 'string') {
+        return { kind: ae.type === 'text_delta' ? 'text' : 'thinking', delta: ae.delta };
+    }
+    return null;
+}
+/**
+ * 提取工具结果文本：result.content 为数组时，各项 type === 'text' 取 text
+ * （非 text 项以空串占位），以 '\n' 拼接；否则 ''。
+ */
+export function extractToolResultText(result) {
+    if (!Array.isArray(result?.content))
+        return '';
+    return result.content
+        .map((c) => (c?.type === 'text' ? c.text : ''))
+        .join('\n');
+}
+/**
+ * 有状态映射器：内部维护 1-based 轮次计数（assistant message_start 先自增再发
+ * round_start，message_end 带当前值），把原始事件映射为 PiSessionEvent 交给 emit。
+ * agent_end 等终态事件不在这里处理（由调用方自行监听）。
+ *
+ * 跨连接复用语义：同一 pi session 可能被多个 SSE 连接先后复用（多次追问），
+ * 调用方应通过 initialIndex 传入上次累计的轮次、并在 onIndexChange 中持久化新值，
+ * 否则每个连接的 roundIndex 都会从 1 重来，导致前端按 roundIndex 去重时串轮。
+ */
+export function createPiEventEmitter(emit, options) {
+    let roundIndex = options?.initialIndex ?? 0;
+    return {
+        write(rawEvent) {
+            try {
+                const ev = rawEvent;
+                if (ev.type === 'message_start') {
+                    if (isAssistantMessage(ev)) {
+                        roundIndex += 1;
+                        options?.onIndexChange?.(roundIndex);
+                        emit({ type: 'round_start', roundIndex });
+                    }
+                }
+                else if (ev.type === 'message_end') {
+                    if (isAssistantMessage(ev)) {
+                        emit({ type: 'round_end', roundIndex });
+                    }
+                }
+                else if (ev.type === 'message_update') {
+                    const d = extractAssistantDelta(ev);
+                    if (d) {
+                        emit(d.kind === 'text'
+                            ? { type: 'text_delta', content: d.delta }
+                            : { type: 'thinking_delta', content: d.delta });
+                    }
+                }
+                else if (ev.type === 'tool_execution_start') {
+                    emit({
+                        type: 'tool_start',
+                        toolCallId: ev.toolCallId,
+                        toolName: ev.toolName,
+                        args: ev.args,
+                    });
+                }
+                else if (ev.type === 'tool_execution_end') {
+                    emit({
+                        type: 'tool_end',
+                        toolCallId: ev.toolCallId,
+                        toolName: ev.toolName,
+                        isError: !!ev.isError,
+                        durationMs: ev.durationMs ?? 0,
+                        result: extractToolResultText(ev.result),
+                    });
+                }
+                // 其他事件（agent_end / 未知类型）忽略
+            }
+            catch {
+                // 映射或 emit 抛错不影响 SDK 事件分发（参照 orchestrator 既有约定）
+            }
+        },
+    };
+}

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

@@ -1,8 +1,5 @@
-export interface OutlineItem {
-    id: string;
-    title: string;
-    oneLine: string;
-}
+import type { OutlineItem } from './vault.js';
+export type { OutlineItem };
 export interface LearnPipelineEvents {
     stageStart(stage: 'outline' | 'refine' | 'tag', totalItems?: number): void;
     stageItemStart(index: number, total: number, title: string): void;
@@ -34,8 +31,12 @@ export interface RunLearnPipelineOptions {
     label?: string;
     port: number;
     events: LearnPipelineEvents;
+    /** 外部取消信号：客户端断开（关窗）时 abort，流水线各阶段随之中止 */
+    signal: AbortSignal;
     /** 注入式 docsDir（测试用）；默认 ~/.cc-monitoring/docs */
     docsDir?: string;
+    /** slug 算出后、任何文件改动前同步调用（落 running 行用）；抛错直接传播 */
+    onStart?: (slug: string) => void;
 }
 export declare function runLearnPipeline(opts: RunLearnPipelineOptions): Promise<{
     slug: string;