scream-code 0.8.2 → 0.8.4

package/dist/main.mjs

@@ -6,7 +6,7 @@ const __dirname = __cjsShimDirname(__filename);
 import "./suppress-sqlite-warning-C2VB0doZ.mjs";
 //#region src/main.ts
 try {
-	(await import("./app-C4TYfyrt.mjs")).main();
+	(await import("./app-DYDC5U75.mjs")).main();
 } catch (error) {
 	process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
 	process.exit(1);

package/dist/{src-aqNCeRzD.mjs → src-CptHxtUY.mjs}

@@ -243,6 +243,22 @@ var KnowledgeStore = class {
 		return this.embeddingEngine;
 	}
 	/**
+	* Proactively load the embedding model (downloads on first call).
+	* Call before ingestion so the user gets a clear download prompt instead
+	* of a mid-ingest failure.
+	*/
+	async ensureEmbeddingReady() {
+		if (this.embeddingEngine === void 0) return {
+			ok: false,
+			reason: "engine not set"
+		};
+		const ok = await this.embeddingEngine.ensureReady();
+		return {
+			ok,
+			reason: ok ? void 0 : "fastembed init failed"
+		};
+	}
+	/**
 	* Begin a write transaction. Use commitTransaction / rollbackTransaction
 	* to close it. Used by ingest to keep chunks/events/entities/edges atomic —
 	* a mid-ingest failure leaves no partial rows.
@@ -637,6 +653,42 @@ var KnowledgeStore = class {
          JOIN knowledge_event_entities ee ON ee.entity_id = en.id
          WHERE ee.event_id = ?`).all(eventId).map(rowToEntity);
 	}
+	async listEntities(sourceId) {
+		await this.init();
+		if (this.db === void 0) return [];
+		const sql = sourceId ? `SELECT e.*, COUNT(ee.id) AS event_count
+         FROM knowledge_entities e
+         LEFT JOIN knowledge_event_entities ee ON ee.entity_id = e.id
+         WHERE e.source_id = ?
+         GROUP BY e.id
+         ORDER BY event_count DESC` : `SELECT e.*, COUNT(ee.id) AS event_count
+         FROM knowledge_entities e
+         LEFT JOIN knowledge_event_entities ee ON ee.entity_id = e.id
+         GROUP BY e.id
+         ORDER BY event_count DESC`;
+		return (sourceId ? this.db.prepare(sql).all(sourceId) : this.db.prepare(sql).all()).map((row) => ({
+			...rowToEntity(row),
+			eventCount: Number(row["event_count"] ?? 0)
+		}));
+	}
+	async listEvents(sourceId) {
+		await this.init();
+		if (this.db === void 0) return [];
+		const sql = sourceId ? "SELECT * FROM knowledge_events WHERE source_id = ? ORDER BY rank ASC" : "SELECT * FROM knowledge_events ORDER BY created_at DESC";
+		return (sourceId ? this.db.prepare(sql).all(sourceId) : this.db.prepare(sql).all()).map(rowToEvent);
+	}
+	async listEventEntities(sourceId) {
+		await this.init();
+		if (this.db === void 0) return [];
+		const sql = sourceId ? `SELECT ee.event_id, ee.entity_id
+         FROM knowledge_event_entities ee
+         JOIN knowledge_events e ON e.id = ee.event_id
+         WHERE e.source_id = ?` : "SELECT event_id, entity_id FROM knowledge_event_entities";
+		return (sourceId ? this.db.prepare(sql).all(sourceId) : this.db.prepare(sql).all()).map((row) => ({
+			eventId: asString(row["event_id"]),
+			entityId: asString(row["entity_id"])
+		}));
+	}
 	async ftsSearchChunks(query, limit = 50) {
 		await this.init();
 		if (this.db === void 0) return [];
@@ -819,6 +871,13 @@ function buildFtsQuery(search) {
 const HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
 const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
 /**
+* Soft cap on chunk token count. BGE-small-zh-v1.5 (the fastembed model used
+* here) has a 512-token sequence limit; chunks longer than that get truncated
+* at the embedding layer, hurting retrieval quality. We split at ~480 to leave
+* headroom for the heading line that gets prepended at embed time.
+*/
+const MAX_CHUNK_TOKENS = 480;
+/**
 * Split a markdown document into sections using heading_strict strategy:
 * each section begins at a heading and contains all body content until the
 * next heading. Consecutive headings collapse to the lowest-level one as the
@@ -837,18 +896,25 @@ function chunkMarkdown(content) {
 	const flush = () => {
 		const raw = buffer.join("\n").trim();
 		const heading = currentHeading;
+		const level = currentLevel;
 		buffer = [];
 		if (raw.length === 0) return;
 		const body = stripMarkdown(raw);
 		if (body.length === 0 && heading === null) return;
-		sections.push({
+		const subSections = splitLargeSection({
 			heading,
-			headingLevel: currentLevel,
+			headingLevel: level,
 			content: body,
 			rawContent: raw,
 			rank
 		});
-		rank += 1;
+		for (const section of subSections) {
+			sections.push({
+				...section,
+				rank
+			});
+			rank += 1;
+		}
 	};
 	for (const line of lines) {
 		if (CODE_FENCE_RE.exec(line)) {
@@ -882,10 +948,11 @@ function stripMarkdown(text) {
 /**
 * Split a plain text file into chunks by blank-line paragraphs.
 * Each non-empty paragraph becomes one chunk with no heading.
-* Long paragraphs are split at sentence boundaries to avoid huge chunks.
+* Long paragraphs are split at sentence boundaries to stay under the
+* embedding model's token cap (same MAX_CHUNK_TOKENS as markdown).
 */
 function chunkText(content) {
-	const MAX_PARA_TOKENS = 800;
+	const MAX_PARA_TOKENS = MAX_CHUNK_TOKENS;
 	const MAX_PARA_CHARS = MAX_PARA_TOKENS * 4;
 	const paragraphs = content.split(/\n\s*\n/).map((p) => p.trim()).filter((p) => p.length > 0);
 	const sections = [];
@@ -928,8 +995,144 @@ function chunkText(content) {
 function estimateTokens(text) {
 	return Math.ceil(text.length / 4);
 }
+/**
+* Split a section that exceeds MAX_CHUNK_TOKENS into smaller sub-sections.
+* Strategy (mirrors SAG's `splitLargeSection`):
+*   1. Split into paragraphs by blank lines.
+*   2. Greedily pack paragraphs into chunks under the token cap.
+*   3. A paragraph that alone exceeds the cap is split at sentence boundaries;
+*      a sentence that itself exceeds the cap is split by character limit.
+*
+* Sections under the cap are returned unchanged (single-element array).
+* The heading is preserved across all sub-sections; rank is reassigned by the
+* caller. rawContent is rebuilt from the sub-chunk's content paragraphs.
+*/
+function splitLargeSection(section) {
+	if (estimateTokens(section.content) <= MAX_CHUNK_TOKENS) return [section];
+	const paragraphs = section.rawContent.split(/\n{2,}/).map((p) => p.trim()).filter((p) => p.length > 0);
+	if (paragraphs.length <= 1) return splitBySentences(section, section.rawContent);
+	const result = [];
+	let buffer = [];
+	let bufferTokens = 0;
+	const flushBuffer = () => {
+		if (buffer.length === 0) return;
+		const raw = buffer.join("\n\n").trim();
+		if (raw.length === 0) {
+			buffer = [];
+			bufferTokens = 0;
+			return;
+		}
+		result.push({
+			heading: section.heading,
+			headingLevel: section.headingLevel,
+			content: stripMarkdown(raw),
+			rawContent: raw,
+			rank: 0
+		});
+		buffer = [];
+		bufferTokens = 0;
+	};
+	for (const para of paragraphs) {
+		const paraTokens = estimateTokens(para);
+		if (paraTokens > MAX_CHUNK_TOKENS) {
+			flushBuffer();
+			for (const frag of splitBySentences(section, para)) result.push(frag);
+			continue;
+		}
+		if (buffer.length > 0 && bufferTokens + paraTokens > MAX_CHUNK_TOKENS) flushBuffer();
+		buffer.push(para);
+		bufferTokens += paraTokens;
+	}
+	flushBuffer();
+	return result.length > 0 ? result : [section];
+}
+/**
+* Split a long text into sub-sections at sentence boundaries.
+* Falls back to a hard character cut when a single sentence exceeds the cap.
+*/
+function splitBySentences(section, text) {
+	const sentences = splitSentences(text);
+	const result = [];
+	let buffer = "";
+	let bufferTokens = 0;
+	const flush = () => {
+		const trimmed = buffer.trim();
+		if (trimmed.length === 0) {
+			buffer = "";
+			bufferTokens = 0;
+			return;
+		}
+		result.push({
+			heading: section.heading,
+			headingLevel: section.headingLevel,
+			content: stripMarkdown(trimmed),
+			rawContent: trimmed,
+			rank: 0
+		});
+		buffer = "";
+		bufferTokens = 0;
+	};
+	for (const sentence of sentences) {
+		const sentTokens = estimateTokens(sentence);
+		if (sentTokens > MAX_CHUNK_TOKENS) {
+			flush();
+			for (const frag of splitByCharLimit(sentence)) result.push({
+				heading: section.heading,
+				headingLevel: section.headingLevel,
+				content: stripMarkdown(frag),
+				rawContent: frag,
+				rank: 0
+			});
+			continue;
+		}
+		if (buffer.length > 0 && bufferTokens + sentTokens > MAX_CHUNK_TOKENS) flush();
+		buffer = buffer.length === 0 ? sentence : `${buffer} ${sentence}`;
+		bufferTokens += sentTokens;
+	}
+	flush();
+	return result.length > 0 ? result : [{
+		heading: section.heading,
+		headingLevel: section.headingLevel,
+		content: section.content,
+		rawContent: section.rawContent,
+		rank: 0
+	}];
+}
+/** Split text into sentences using CJK + ASCII punctuation. */
+function splitSentences(text) {
+	return text.match(/[^。！？!?.\n]+[。！？!?.\n]+|[^。！？!?.\n]+$/g) ?? [text];
+}
+/** Hard character cut for pathological single sentences longer than the cap. */
+function splitByCharLimit(text) {
+	const maxChars = MAX_CHUNK_TOKENS * 4;
+	const chunks = [];
+	let remaining = text.trim();
+	while (remaining.length > maxChars) {
+		chunks.push(remaining.slice(0, maxChars));
+		remaining = remaining.slice(maxChars).trimStart();
+	}
+	if (remaining.length > 0) chunks.push(remaining);
+	return chunks;
+}
 //#endregion
 //#region ../../packages/knowledge/src/extractor.ts
+/** Max LLM call attempts for extraction — fails fall back to a heading-derived event. */
+const EXTRACTION_MAX_ATTEMPTS = 3;
+/** Base delay (ms) for exponential backoff: 100, 200, 400. */
+const EXTRACTION_BACKOFF_BASE_MS = 100;
+function backoffDelay(attempt) {
+	return EXTRACTION_BACKOFF_BASE_MS * 2 ** Math.max(0, attempt - 1);
+}
+async function callLlmWithBackoff(llm, systemPrompt, userPrompt) {
+	let lastError;
+	for (let attempt = 1; attempt <= EXTRACTION_MAX_ATTEMPTS; attempt += 1) try {
+		return await llm.generate(systemPrompt, userPrompt);
+	} catch (error) {
+		lastError = error;
+		if (attempt < EXTRACTION_MAX_ATTEMPTS) await new Promise((resolve) => setTimeout(resolve, backoffDelay(attempt)));
+	}
+	throw lastError;
+}
 const ENTITY_TYPES = [
 	"person",
 	"organization",
@@ -1104,11 +1307,12 @@ function fallbackEvent(chunk) {
 }
 /**
 * Run extraction on a single chunk via the LLM caller.
-* Returns the parsed event (with fallback on failure).
+* Retries with exponential backoff on transient failures; falls back to a
+* heading-derived event only after all attempts fail.
 */
 async function extractEventFromChunk(llm, chunk) {
 	try {
-		return parseExtractionResponse(await llm.generate(EXTRACTION_SYSTEM_PROMPT, buildExtractionUserPrompt(chunk)), chunk);
+		return parseExtractionResponse(await callLlmWithBackoff(llm, EXTRACTION_SYSTEM_PROMPT, buildExtractionUserPrompt(chunk)), chunk);
 	} catch {
 		return fallbackEvent(chunk);
 	}
@@ -1188,7 +1392,8 @@ Only include entities that explicitly appear in the query. If no clear entities,
 }
 //#endregion
 //#region ../../packages/knowledge/src/ingest.ts
-const LLM_CONCURRENCY = 5;
+/** LLM concurrency for extraction — kept low to avoid rate-limit bursts. */
+const LLM_CONCURRENCY = 3;
 const SUPPORTED_EXTENSIONS = new Set([
 	".md",
 	".markdown",
@@ -1252,9 +1457,9 @@ async function ingestFile(store, llm, filePath, onProgress) {
 	if (engine === void 0 || !engine.available) {
 		onProgress?.({
 			stage: "error",
-			message: "embedding engine unavailable"
+			message: "向量模型未就绪"
 		});
-		throw new Error("embedding engine unavailable — knowledge base requires fastembed");
+		throw new Error("向量模型未就绪，请检查网络后重试");
 	}
 	const existing = await store.findSourceByFilePath(filePath);
 	if (existing !== void 0) {
@@ -1262,7 +1467,7 @@ async function ingestFile(store, llm, filePath, onProgress) {
 			stage: "error",
 			message: `文件已摄入：${existing.name}（source id=${existing.id}）`
 		});
-		throw new Error(`file already ingested: ${filePath} (source ${existing.id})`);
+		throw new Error(`文件已摄入过: ${filePath} (source ${existing.id})`);
 	}
 	onProgress?.({
 		stage: "chunking",
@@ -1275,7 +1480,7 @@ async function ingestFile(store, llm, filePath, onProgress) {
 			stage: "error",
 			message: "文件无有效内容"
 		});
-		throw new Error("file has no content to ingest");
+		throw new Error("文件无有效内容可摄入");
 	}
 	store.beginTransaction();
 	try {
@@ -1300,9 +1505,9 @@ async function ingestFile(store, llm, filePath, onProgress) {
 		if (chunkEmbeddings === null) {
 			onProgress?.({
 				stage: "error",
-				message: "chunk embedding failed"
+				message: "chunk 向量嵌入失败"
 			});
-			throw new Error("chunk embedding failed");
+			throw new Error("chunk 向量嵌入失败");
 		}
 		const chunks = [];
 		for (let i = 0; i < sections.length; i++) {
@@ -1351,9 +1556,9 @@ async function ingestFile(store, llm, filePath, onProgress) {
 		if (titleEmbeddings === null || contentEmbeddings === null) {
 			onProgress?.({
 				stage: "error",
-				message: "event embedding failed"
+				message: "event 向量嵌入失败"
 			});
-			throw new Error("event embedding failed");
+			throw new Error("event 向量嵌入失败");
 		}
 		const events = [];
 		for (let i = 0; i < extractedEvents.length; i++) {
@@ -1394,9 +1599,9 @@ async function ingestFile(store, llm, filePath, onProgress) {
 		if (uniqueEntities.length > 0 && entityEmbeddings === null) {
 			onProgress?.({
 				stage: "error",
-				message: "entity embedding failed"
+				message: "entity 向量嵌入失败"
 			});
-			throw new Error("entity embedding failed");
+			throw new Error("entity 向量嵌入失败");
 		}
 		const entityIdByEntityKey = /* @__PURE__ */ new Map();
 		for (let i = 0; i < uniqueEntities.length; i++) {
@@ -1431,9 +1636,9 @@ async function ingestFile(store, llm, filePath, onProgress) {
 		if (relationPairs.length > 0 && relationEmbeddings === null) {
 			onProgress?.({
 				stage: "error",
-				message: "relation embedding failed"
+				message: "relation 向量嵌入失败"
 			});
-			throw new Error("relation embedding failed");
+			throw new Error("relation 向量嵌入失败");
 		}
 		for (let i = 0; i < relationPairs.length; i++) {
 			const pair = relationPairs[i];
@@ -1479,7 +1684,7 @@ async function collectSupportedFiles(dirPath) {
 }
 async function ingestDirectory(store, llm, dirPath, onProgress) {
 	const files = await collectSupportedFiles(dirPath);
-	if (files.length === 0) throw new Error(`no supported files (.md, .markdown, .txt) found in ${dirPath}`);
+	if (files.length === 0) throw new Error(`目录下没有支持的文件 (.md, .markdown, .txt): ${dirPath}`);
 	const errors = [];
 	let succeeded = 0;
 	let totalChunks = 0;
@@ -1534,6 +1739,28 @@ const EXPANDED_EVENT_LIMIT = 100;
 const COARSE_RANK_LIMIT = 50;
 const ENTITY_VECTOR_THRESHOLD = .7;
 const TITLE_VECTOR_THRESHOLD = .4;
+async function timed(onStep, step, detail, fn, payload) {
+	const start = performance.now();
+	try {
+		const result = await fn();
+		const traceStep = {
+			step,
+			detail,
+			durationMs: Math.round((performance.now() - start) * 100) / 100,
+			...payload !== void 0 ? { payload: payload(result) } : {}
+		};
+		onStep?.(traceStep);
+		return result;
+	} catch (error) {
+		const durationMs = Math.round((performance.now() - start) * 100) / 100;
+		onStep?.({
+			step,
+			detail: `${detail} 失败：${error instanceof Error ? error.message : String(error)}`,
+			durationMs
+		});
+		throw error;
+	}
+}
 /**
 * Multi-hop retrieval:
 * 1. Vectorize query.
@@ -1545,62 +1772,155 @@ const TITLE_VECTOR_THRESHOLD = .4;
 * 6. LLM rerank — pick top-K most relevant.
 * 7. Return corresponding chunks (deduped by chunk_id) with scores and provenance.
 *    If rerank yields fewer than topK chunks, backfill by direct chunk vector search.
+*
+* Optional `onStep` callback receives a trace step at each phase — used by the
+* KnowledgeLookup tool to expose retrieval diagnostics to the agent.
 */
 async function multiSearch(store, llm, query, options = {}) {
+	return (await multiSearchWithTrace(store, llm, query, options)).results;
+}
+/** Like multiSearch but also returns the retrieval trace for diagnostics. */
+async function multiSearchWithTrace(store, llm, query, options = {}) {
 	const topK = Math.min(options.topK ?? DEFAULT_TOP_K, MAX_TOP_K);
+	const steps = [];
+	const onStep = (step) => steps.push(step);
+	const rerankedEventTitles = [];
+	let fallbackReason = null;
 	const engine = store.getEmbeddingEngine();
-	if (engine === void 0 || !engine.available) return ftsFallback(store, query, topK);
-	const queryEmbeddings = await engine.embedBatch([query]);
-	if (queryEmbeddings === null || queryEmbeddings.length === 0) return ftsFallback(store, query, topK);
+	if (engine === void 0 || !engine.available) {
+		fallbackReason = "embedding engine unavailable; used FTS5 keyword fallback";
+		return {
+			results: await ftsFallback(store, query, topK),
+			trace: {
+				steps,
+				rerankedEventTitles,
+				fallbackReason
+			}
+		};
+	}
+	const queryEmbeddings = await timed(onStep, "queryEmbedding", "把用户问题转成向量，用于召回相关事件和切片。", async () => engine.embedBatch([query]));
+	if (queryEmbeddings === null || queryEmbeddings.length === 0) {
+		fallbackReason = "query embedding returned null; used FTS5 fallback";
+		return {
+			results: await ftsFallback(store, query, topK),
+			trace: {
+				steps,
+				rerankedEventTitles,
+				fallbackReason
+			}
+		};
+	}
 	const queryVec = queryEmbeddings[0];
-	const recalledEntities = await recallEntities(store, llm, query, queryVec);
+	const recalledEntities = await timed(onStep, "entityRecall", "LLM 抽 query 实体 + 名字精确匹配 + 向量召回。", () => recallEntities(store, llm, query, queryVec), (entities) => ({ count: entities.length }));
 	const seedEventIds = /* @__PURE__ */ new Set();
 	for (const entity of recalledEntities) {
 		const events = await store.findEventsByEntity(entity.id);
 		for (const event of events) seedEventIds.add(event.id);
 	}
-	const titleMatches = await store.findEventsByTitleVector(queryVec, {
+	const titleMatches = await timed(onStep, "seedEventsByTitle", "按查询向量在事件标题向量上召回 seed events。", () => store.findEventsByTitleVector(queryVec, {
 		limit: SEED_EVENT_LIMIT,
 		threshold: TITLE_VECTOR_THRESHOLD
-	});
+	}), (matches) => ({ count: matches.length }));
 	for (const { event } of titleMatches) seedEventIds.add(event.id);
-	const expandedEventIds = new Set(seedEventIds);
-	for (const eventId of seedEventIds) {
-		const entities = await store.findEntitiesByEvent(eventId);
-		for (const entity of entities) {
-			const neighborEvents = await store.findEventsByEntity(entity.id);
-			for (const neighbor of neighborEvents) {
-				expandedEventIds.add(neighbor.id);
-				if (expandedEventIds.size >= EXPANDED_EVENT_LIMIT) break;
+	if (seedEventIds.size === 0) {
+		fallbackReason = "no seed events; used direct chunk vector search";
+		return {
+			results: await chunkVectorFallback(store, queryVec, topK),
+			trace: {
+				steps,
+				rerankedEventTitles,
+				fallbackReason
+			}
+		};
+	}
+	const expandedEventIds = await timed(onStep, "bfsExpand", "从 seed events 沿实体关系 1 跳扩展候选事件。", async () => {
+		const ids = new Set(seedEventIds);
+		let capped = false;
+		for (const eventId of seedEventIds) {
+			const entities = await store.findEntitiesByEvent(eventId);
+			for (const entity of entities) {
+				const neighborEvents = await store.findEventsByEntity(entity.id);
+				for (const neighbor of neighborEvents) {
+					ids.add(neighbor.id);
+					if (ids.size >= EXPANDED_EVENT_LIMIT) {
+						capped = true;
+						break;
+					}
+				}
+				if (ids.size >= EXPANDED_EVENT_LIMIT) break;
 			}
-			if (expandedEventIds.size >= EXPANDED_EVENT_LIMIT) break;
+			if (ids.size >= EXPANDED_EVENT_LIMIT) break;
 		}
-		if (expandedEventIds.size >= EXPANDED_EVENT_LIMIT) break;
-	}
-	const candidates = [];
-	for (const eventId of expandedEventIds) {
-		const event = await store.getEvent(eventId);
-		if (event === void 0) continue;
-		const vec = event.contentEmbedding;
-		const score = vec === null ? 0 : engine.cosineSimilarity(queryVec, vec);
-		candidates.push({
-			id: event.id,
-			title: event.title,
-			summary: event.summary ?? "",
-			score,
-			chunkId: event.chunkId
-		});
+		return {
+			ids,
+			capped
+		};
+	}, (result) => ({
+		expandedCount: result.ids.size,
+		capped: result.capped
+	}));
+	const { candidates, topCandidates } = await timed(onStep, "coarseRank", "按 content 向量相似度对候选事件排序，取前 COARSE_RANK_LIMIT 个。", async () => {
+		const cands = [];
+		for (const eventId of expandedEventIds.ids) {
+			const event = await store.getEvent(eventId);
+			if (event === void 0) continue;
+			const vec = event.contentEmbedding;
+			const score = vec === null ? 0 : engine.cosineSimilarity(queryVec, vec);
+			cands.push({
+				id: event.id,
+				title: event.title,
+				summary: event.summary ?? "",
+				score,
+				chunkId: event.chunkId
+			});
+		}
+		cands.sort((a, b) => b.score - a.score);
+		return {
+			candidates: cands,
+			topCandidates: cands.slice(0, COARSE_RANK_LIMIT)
+		};
+	}, (result) => ({
+		totalCandidates: result.candidates.length,
+		kept: result.topCandidates.length,
+		topScore: result.topCandidates[0]?.score ?? 0
+	}));
+	if (candidates.length === 0) {
+		fallbackReason = "no graph-reachable events with content; used chunk vector fallback";
+		return {
+			results: await chunkVectorFallback(store, queryVec, topK),
+			trace: {
+				steps,
+				rerankedEventTitles,
+				fallbackReason
+			}
+		};
 	}
-	if (candidates.length === 0) return chunkVectorFallback(store, queryVec, topK);
-	candidates.sort((a, b) => b.score - a.score);
-	const topCandidates = candidates.slice(0, COARSE_RANK_LIMIT);
 	let rankedIds;
-	if (options.skipRerank === true || topCandidates.length <= topK) rankedIds = topCandidates.map((c) => c.id);
-	else rankedIds = await rerankEventsWithLlm(llm, query, topCandidates.map((c) => ({
+	if (options.skipRerank === true) {
+		rankedIds = topCandidates.map((c) => c.id);
+		onStep({
+			step: "rerank",
+			detail: "跳过 LLM rerank（skipRerank=true），直接用 coarse rank 顺序。",
+			durationMs: 0,
+			payload: { count: rankedIds.length }
+		});
+	} else if (topCandidates.length <= topK) {
+		rankedIds = topCandidates.map((c) => c.id);
+		onStep({
+			step: "rerank",
+			detail: `候选数 ${topCandidates.length} ≤ topK ${topK}，无需 LLM rerank。`,
+			durationMs: 0,
+			payload: { count: rankedIds.length }
+		});
+	} else rankedIds = await timed(onStep, "rerank", `LLM 从 ${topCandidates.length} 个候选中选最相关的 ${topK} 个。`, () => rerankEventsWithLlm(llm, query, topCandidates.map((c) => ({
 		id: c.id,
 		title: c.title,
 		summary: c.summary
-	})), topK);
+	})), topK), (ids) => ({ count: ids.length }));
+	for (const id of rankedIds) {
+		const c = topCandidates.find((x) => x.id === id);
+		if (c !== void 0) rerankedEventTitles.push(c.title);
+	}
 	const seen = /* @__PURE__ */ new Set();
 	const results = [];
 	for (const eventId of rankedIds) {
@@ -1612,17 +1932,29 @@ async function multiSearch(store, llm, query, options = {}) {
 		if (result !== void 0) results.push(result);
 		if (results.length >= topK) break;
 	}
-	if (results.length < topK) for (const candidate of topCandidates) {
-		if (results.length >= topK) break;
-		if (rankedIds.includes(candidate.id)) continue;
-		if (seen.has(candidate.chunkId)) continue;
-		seen.add(candidate.chunkId);
-		const result = await store.buildSearchResult(candidate.chunkId, candidate.score, candidate.id);
-		if (result !== void 0) results.push(result);
+	if (results.length < topK) {
+		let supplemented = 0;
+		for (const candidate of topCandidates) {
+			if (results.length >= topK) break;
+			if (rankedIds.includes(candidate.id)) continue;
+			if (seen.has(candidate.chunkId)) continue;
+			seen.add(candidate.chunkId);
+			const result = await store.buildSearchResult(candidate.chunkId, candidate.score, candidate.id);
+			if (result !== void 0) {
+				results.push(result);
+				supplemented += 1;
+			}
+		}
+		if (supplemented > 0) onStep({
+			step: "supplementFromCoarse",
+			detail: `rerank 结果不足，从 coarse rank 残余补 ${supplemented} 个。`,
+			durationMs: 0,
+			payload: { supplemented }
+		});
 	}
 	if (results.length < topK) {
 		const remaining = topK - results.length;
-		const backfill = await store.searchChunksByVector(queryVec, { limit: remaining * 2 });
+		const backfill = await timed(onStep, "backfill", `rerank 结果不足，回退到 chunk 向量搜索补 ${remaining} 个。`, () => store.searchChunksByVector(queryVec, { limit: remaining * 2 }), (matches) => ({ backfillCandidates: matches.length }));
 		for (const { chunk, score } of backfill) {
 			if (results.length >= topK) break;
 			if (seen.has(chunk.id)) continue;
@@ -1631,7 +1963,14 @@ async function multiSearch(store, llm, query, options = {}) {
 			if (result !== void 0) results.push(result);
 		}
 	}
-	return results;
+	return {
+		results,
+		trace: {
+			steps,
+			rerankedEventTitles,
+			fallbackReason
+		}
+	};
 }
 /** Recall entities by name (LLM-extracted) and by vector similarity. */
 async function recallEntities(store, llm, query, queryVec) {
@@ -1671,4 +2010,4 @@ async function chunkVectorFallback(store, queryVec, topK) {
 	return results;
 }
 //#endregion
-export { parse as C, normalize as S, resolve as T, KnowledgeStore as _, ENTITY_TYPES as a, isAbsolute as b, extractEventFromChunk as c, parseExtractionResponse as d, rerankEventsWithLlm as f, stripMarkdown as g, estimateTokens as h, isSupportedFile as i, extractJsonFromText as l, chunkText as m, ingestDirectory as n, EXTRACTION_SYSTEM_PROMPT as o, chunkMarkdown as p, ingestFile as r, buildExtractionUserPrompt as s, multiSearch as t, extractQueryEntities as u, basename as v, relative as w, join as x, dirname as y };
+export { join as C, resolve as D, relative as E, isAbsolute as S, parse as T, splitLargeSection as _, isSupportedFile as a, basename as b, buildExtractionUserPrompt as c, extractQueryEntities as d, parseExtractionResponse as f, estimateTokens as g, chunkText as h, ingestFile as i, extractEventFromChunk as l, chunkMarkdown as m, multiSearchWithTrace as n, ENTITY_TYPES as o, rerankEventsWithLlm as p, ingestDirectory as r, EXTRACTION_SYSTEM_PROMPT as s, multiSearch as t, extractJsonFromText as u, stripMarkdown as v, normalize as w, dirname as x, KnowledgeStore as y };

package/dist/{src-S0QPScxL.mjs → src-DhT3eU2C.mjs}

@@ -3,5 +3,5 @@ import { fileURLToPath as __cjsShimFileURLToPath } from 'node:url';
 import { dirname as __cjsShimDirname } from 'node:path';
 const __filename = __cjsShimFileURLToPath(import.meta.url);
 const __dirname = __cjsShimDirname(__filename);
-import { t as multiSearch } from "./src-aqNCeRzD.mjs";
-export { multiSearch };
+import { n as multiSearchWithTrace } from "./src-CptHxtUY.mjs";
+export { multiSearchWithTrace };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scream-code",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "A terminal-native AI agent for builders",
   "license": "MIT",
   "author": "ScreamCli",