@ontos-ai/knowhere-claw 0.2.3 → 0.2.5

package/dist/tools.js

@@ -1,13 +1,13 @@
 import { isRecord } from "./types.js";
 import { assertKnowhereApiKey, formatPaymentRequiredMessage, isPaymentRequiredError, persistApiKey } from "./config.js";
-import { normalizeForGrep, normalizeWhitespace, sanitizeStringArray, slugify } from "./text.js";
+import { resolveStoredKnowhereArtifactPath } from "./parser.js";
+import { sanitizeStringArray } from "./text.js";
 import { formatErrorMessage } from "./error-message.js";
 import { KnowhereClient } from "./client.js";
-import { deliverChannelMessage } from "./channel-delivery.js";
 import { sendTrackerProgress } from "./tracker-progress.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/core";
+import os from "node:os";
 //#region src/tools.ts
 const TERMINAL_JOB_STATUSES = new Set([
 	"cancelled",
@@ -18,19 +18,12 @@ const TERMINAL_JOB_STATUSES = new Set([
 ]);
 async function buildKnowledgeGraphAsync(params) {
 	const docDir = path.join(params.scope.documentsDir, params.docId);
-	const metadataPath = path.join(docDir, "metadata.json");
-	let payload = null;
-	try {
-		payload = await fs.readFile(metadataPath, "utf-8");
-	} catch {
-		payload = null;
-	}
-	if (!payload) {
+	const payloadData = await params.store.readDocumentMetadata(params.scope, params.docId);
+	if (!payloadData) {
 		params.api.logger.warn(`knowhere: cannot build KG, metadata not found for docId=${params.docId}`);
 		return;
 	}
-	const payloadData = JSON.parse(payload);
-	const fullMarkdownPath = path.join(docDir, "full_markdown.txt");
+	const fullMarkdownPath = await resolveStoredKnowhereArtifactPath(docDir, "full_markdown.txt");
 	let fullMarkdown = "";
 	try {
 		fullMarkdown = await fs.readFile(fullMarkdownPath, "utf-8");
@@ -44,8 +37,8 @@ async function buildKnowledgeGraphAsync(params) {
 		sourcePath: docDir,
 		keywords,
 		metadata: {
-			title: payloadData.document?.title || "Untitled",
-			sourceLabel: payloadData.document?.sourceLabel || "Unknown",
+			title: payloadData.document.title || "Untitled",
+			sourceLabel: payloadData.document.sourceLabel || "Unknown",
 			checksum: params.documentPayload.downloadedResult.rawZipSha1,
 			ingestedAt: (/* @__PURE__ */ new Date()).toISOString()
 		}
@@ -55,7 +48,6 @@ async function buildKnowledgeGraphAsync(params) {
 	});
 	params.api.logger.info(`knowhere: knowledge graph build completed kbId=${params.kbId} docId=${params.docId}`);
 }
-const PREVIEW_SUMMARY_MAX_CHARS = 120;
 const INGEST_TRACKER_LANGUAGES = new Set(["ch", "en"]);
 function textResult(text) {
 	return {
@@ -76,13 +68,6 @@ function deriveStoredDocumentDisplayName(document) {
 function deriveStoredDocumentFileLabel(document, manifestSourceFileName) {
 	return document.originalFileName || document.fileName || manifestSourceFileName || "unknown";
 }
-function formatStoredDocumentNotFound(docId, scopeLabel) {
-	return [
-		"Stored document not found.",
-		`Document ID: ${docId}`,
-		`Scope: ${scopeLabel}`
-	].join("\n");
-}
 function buildStoredDocumentSummaryLines(params) {
 	const lines = [`Stored document: "${params.document.title}" [${params.document.id}]`, `Scope: ${params.scopeLabel}`];
 	if (params.includeSource) lines.push(`Source: ${params.document.sourceLabel}`);
@@ -116,6 +101,7 @@ function startKnowledgeGraphBuild(params) {
 		docId: params.document.id,
 		documentPayload: params.ingestResult,
 		scope: params.scope,
+		store: params.store,
 		ctx: params.ctx,
 		api: params.api,
 		channelRoute: params.channelRoute,
@@ -146,6 +132,7 @@ async function persistIngestedDocument(params) {
 		ingestResult: params.ingestResult,
 		kgService: params.kgService,
 		scope: params.scope,
+		store: params.store,
 		sessionKey: params.sessionKey
 	});
 	return storedDocument;
@@ -160,7 +147,7 @@ function formatCompletedIngestResult(params) {
 			includeSource: true
 		}),
 		`Source type: ${params.sourceType}`,
-		"Next: use knowhere_preview_document for a structural overview or knowhere_grep to search the parsed content."
+		"Next: use knowhere_kg_query to search the knowledge graph for related content."
 	].join("\n");
 }
 function readString(value) {
@@ -284,22 +271,6 @@ function normalizeParsingParams(rawParsing) {
 	}
 	return Object.keys(result).length > 0 ? result : void 0;
 }
-function formatDocumentList(documents, scopeLabel) {
-	if (documents.length === 0) return `No stored documents in scope ${scopeLabel}.`;
-	return documents.map((document, index) => {
-		const displayTitle = deriveStoredDocumentDisplayName(document);
-		const lines = [
-			`${index + 1}. ${displayTitle} [${document.id}]`,
-			`Source: ${document.sourceLabel}`,
-			`Chunks: ${document.chunkCount}`,
-			`Updated: ${document.updatedAt || document.ingestedAt}`
-		];
-		if (document.title && document.title !== displayTitle) lines.push(`Title: ${document.title}`);
-		if (document.tags.length > 0) lines.push(`Tags: ${document.tags.join(", ")}`);
-		if (document.resultUrl) lines.push(`Result URL: ${document.resultUrl}`);
-		return lines.join("\n");
-	}).join("\n\n");
-}
 function formatJobList(params) {
 	if (params.jobList.jobs.length === 0) return `No Knowhere jobs on page ${params.jobList.page}.`;
 	const lines = [`Knowhere jobs ${params.jobList.page}/${params.jobList.totalPages || 1} (${params.jobList.total} total).`, ""];
@@ -334,239 +305,6 @@ function buildHistoryJobSourceLabel(jobId, fileName) {
 function mergeTags(tags, extras) {
 	return Array.from(new Set([...tags, ...extras]));
 }
-function formatScopeClearResult(documents, scopeLabel) {
-	if (documents.length === 0) return `Scope ${scopeLabel} is already empty.`;
-	const lines = [`Removed ${documents.length} stored document${documents.length === 1 ? "" : "s"} from scope ${scopeLabel}.`];
-	for (const [index, document] of documents.entries()) lines.push(`${index + 1}. ${deriveStoredDocumentDisplayName(document)} [${document.id}]`);
-	return lines.join("\n");
-}
-function readResultFileReadMode(value) {
-	return value === "json" || value === "csv" || value === "text" ? value : "text";
-}
-function normalizeResultFilePath(filePath) {
-	const value = normalizeWhitespace(filePath);
-	if (!value) return;
-	return path.posix.normalize(value.replace(/\\/g, "/")).replace(/^\/+/, "");
-}
-function buildChunkOrderIndex(browseIndex) {
-	return new Map(browseIndex.chunkOrder.map((chunkId, index) => [chunkId, index]));
-}
-function sortChunksByBrowseOrder(chunks, browseIndex) {
-	const orderIndex = buildChunkOrderIndex(browseIndex);
-	return [...chunks].sort((left, right) => {
-		return (orderIndex.get(left.chunkId) ?? Number.MAX_SAFE_INTEGER) - (orderIndex.get(right.chunkId) ?? Number.MAX_SAFE_INTEGER) || left.chunkId.localeCompare(right.chunkId);
-	});
-}
-function findResultFile(browseIndex, relativePath) {
-	return browseIndex.resultFiles.find((entry) => entry.relativePath === relativePath);
-}
-function isTextReadableResultFile(fileRecord) {
-	return fileRecord.kind !== "image";
-}
-const IMAGE_EXTENSION_MIME_TYPES = {
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".webp": "image/webp",
-	".svg": "image/svg+xml",
-	".bmp": "image/bmp",
-	".tiff": "image/tiff",
-	".tif": "image/tiff"
-};
-function inferImageMimeType(filePath) {
-	return IMAGE_EXTENSION_MIME_TYPES[path.extname(filePath).toLowerCase()] || "image/png";
-}
-async function buildImageToolResult(params) {
-	const mimeType = inferImageMimeType(params.absolutePath);
-	const stagedImage = await stageImageResultFileForDelivery({
-		absolutePath: params.absolutePath,
-		documentTitle: params.documentTitle,
-		relativePath: params.filePath,
-		workspaceDir: params.workspaceDir
-	});
-	const stagedImagePath = stagedImage.stagedPath;
-	const fileName = path.basename(stagedImagePath);
-	const caption = `${params.documentTitle} - ${params.filePath}`;
-	const directDelivery = await deliverChannelMessage({
-		api: params.api,
-		operationLabel: "read result image",
-		context: params.context,
-		sessionKey: params.sessionKey,
-		channelRoute: params.channelRoute,
-		text: caption,
-		mediaUrl: stagedImagePath,
-		mediaLocalRoots: [path.dirname(stagedImagePath)]
-	});
-	if (directDelivery.delivered) {
-		const payload = {
-			scope: params.scopeLabel,
-			docId: params.docId,
-			documentTitle: params.documentTitle,
-			file: params.file,
-			mode: "image_sent",
-			data: {
-				mimeType,
-				sourceRelativePath: params.filePath,
-				stagedPath: stagedImagePath,
-				fileName,
-				caption,
-				note: "Image already sent to the current channel by the plugin. Do not call read on stagedPath. Do not call the message tool or attach this file again. If you reply, send only a brief confirmation.",
-				delivery: {
-					method: "direct_runtime",
-					surface: directDelivery.surface,
-					target: directDelivery.to,
-					accountId: directDelivery.accountId
-				}
-			}
-		};
-		return {
-			content: [{
-				type: "text",
-				text: `${JSON.stringify(payload, null, 2)}\n`
-			}],
-			details: payload
-		};
-	}
-	const sendWithMessageTool = {
-		action: "send",
-		path: stagedImagePath,
-		filePath: stagedImagePath,
-		filename: fileName,
-		caption
-	};
-	const replyFallback = stagedImage.workspaceRelativePath ? {
-		instructions: "If the message tool is unavailable, send your normal user-visible reply and include this exact line on its own line to attach the image.",
-		workspaceRelativePath: stagedImage.workspaceRelativePath,
-		replyWithMediaDirective: `MEDIA:${stagedImage.workspaceRelativePath}`
-	} : void 0;
-	const note = replyFallback ? "Image bytes are not inlined. Do not call read on stagedPath. If the user wants to see this image, use the message tool with sendWithMessageTool. If the message tool is unavailable, send your user-visible reply normally and include replyFallback.replyWithMediaDirective on its own line." : "Image bytes are not inlined. Do not call read on stagedPath. If the user wants to see this image, call the message tool with sendWithMessageTool.";
-	const nextActionInstructions = replyFallback ? "Do not call read on stagedPath. Call the message tool with sendWithMessageTool to attach this image. If the message tool is unavailable, use replyFallback.replyWithMediaDirective in your normal reply instead." : "Do not call read on stagedPath. Call the message tool with sendWithMessageTool to attach this image.";
-	const payload = {
-		scope: params.scopeLabel,
-		docId: params.docId,
-		documentTitle: params.documentTitle,
-		file: params.file,
-		mode: "image_attachment",
-		data: {
-			mimeType,
-			sourceRelativePath: params.filePath,
-			stagedPath: stagedImagePath,
-			fileName,
-			caption,
-			note,
-			nextAction: {
-				tool: "message",
-				instructions: nextActionInstructions,
-				args: sendWithMessageTool
-			},
-			sendWithMessageTool,
-			...replyFallback ? { replyFallback } : {}
-		}
-	};
-	return {
-		content: [{
-			type: "text",
-			text: `${JSON.stringify(payload, null, 2)}\n`
-		}],
-		details: payload
-	};
-}
-function normalizeWorkspaceDir(workspaceDir) {
-	const trimmed = readString(workspaceDir);
-	return trimmed ? path.resolve(trimmed) : void 0;
-}
-function toWorkspaceRelativeMediaPath(params) {
-	const relativePath = path.relative(params.workspaceDir, params.stagedPath);
-	if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) return;
-	const normalizedRelativePath = relativePath.split(path.sep).join("/");
-	return normalizedRelativePath.startsWith("./") || normalizedRelativePath.startsWith("../") ? normalizedRelativePath : `./${normalizedRelativePath}`;
-}
-async function stageImageResultFileForDelivery(params) {
-	const extension = path.extname(params.relativePath) || path.extname(params.absolutePath) || ".png";
-	const imageBaseName = path.basename(params.relativePath, extension) || "image";
-	const workspaceDir = normalizeWorkspaceDir(params.workspaceDir);
-	let stagedDir;
-	if (workspaceDir) {
-		const workspaceStageRoot = path.join(workspaceDir, ".openclaw");
-		await fs.mkdir(workspaceStageRoot, { recursive: true });
-		stagedDir = await fs.mkdtemp(path.join(workspaceStageRoot, "knowhere-read-result-file-"));
-	} else stagedDir = await fs.mkdtemp(path.join(resolvePreferredOpenClawTmpDir(), "knowhere-read-result-file-"));
-	const stagedFileName = `${slugify(`${params.documentTitle}-${imageBaseName}`, "knowhere-image")}${extension.toLowerCase()}`;
-	const stagedPath = path.join(stagedDir, stagedFileName);
-	await fs.copyFile(params.absolutePath, stagedPath);
-	return {
-		stagedPath,
-		...workspaceDir ? { workspaceRelativePath: toWorkspaceRelativeMediaPath({
-			workspaceDir,
-			stagedPath
-		}) } : {}
-	};
-}
-function stripUtf8Bom(text) {
-	return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
-}
-function buildTextFilePayload(text, maxChars) {
-	return {
-		content: truncatePreview(text, maxChars),
-		lineCount: text === "" ? 0 : text.split(/\r\n|\n|\r/).length
-	};
-}
-function buildCsvFilePayload(text, maxChars) {
-	const normalized = stripUtf8Bom(text);
-	const [headerLine = ""] = normalized.split(/\r\n|\n|\r/, 1);
-	return {
-		content: truncatePreview(normalized, maxChars),
-		header: headerLine.trim() || null,
-		lineCount: normalized === "" ? 0 : normalized.split(/\r\n|\n|\r/).length
-	};
-}
-function truncatePreview(value, maxChars) {
-	if (typeof value !== "string") return "";
-	const normalized = value.replace(/\r\n/g, "\n").trim();
-	if (!normalized) return "";
-	if (normalized.length <= maxChars) return normalized;
-	return `${normalized.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
-}
-function truncateJsonValue(value, maxStringChars) {
-	if (typeof value === "string") {
-		if (value.length <= maxStringChars) return {
-			value,
-			truncated: false
-		};
-		return {
-			value: `${value.slice(0, Math.max(0, maxStringChars - 1))}…`,
-			truncated: true
-		};
-	}
-	if (Array.isArray(value)) {
-		let truncated = false;
-		return {
-			value: value.map((entry) => {
-				const result = truncateJsonValue(entry, maxStringChars);
-				truncated = truncated || result.truncated;
-				return result.value;
-			}),
-			truncated
-		};
-	}
-	if (isRecord(value)) {
-		let truncated = false;
-		const entries = Object.entries(value).map(([key, entry]) => {
-			const result = truncateJsonValue(entry, maxStringChars);
-			truncated = truncated || result.truncated;
-			return [key, result.value];
-		});
-		return {
-			value: Object.fromEntries(entries),
-			truncated
-		};
-	}
-	return {
-		value,
-		truncated: false
-	};
-}
 function formatJsonToolResult(value) {
 	return textResult(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -599,7 +337,7 @@ function createIngestTool(params) {
 	return {
 		name: "knowhere_ingest_document",
 		label: "Knowhere Ingest",
-		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. Before calling this for a document that might already be stored in the current scope, use knowhere_list_documents and reuse the existing stored document when Source, File, or Title clearly match unless the user explicitly asks for a fresh parse or overwrite. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Knowhere must be the only parser for supported files. If Knowhere returns an error, surface that exact error to the user and do not fall back to other parsing methods or fabricate a preview. By default blockUntilComplete is false, so this tool is fire-and-forget and returns a job ID while parsing continues in the background. Set blockUntilComplete to true only when the current turn explicitly needs the parsed result before continuing. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
+		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Knowhere must be the only parser for supported files. If Knowhere returns an error, surface that exact error to the user and do not fall back to other parsing methods or fabricate a preview. By default blockUntilComplete is false, so this tool is fire-and-forget and returns a job ID while parsing continues in the background. Set blockUntilComplete to true only when the current turn explicitly needs the parsed result before continuing. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -815,7 +553,7 @@ function createIngestTool(params) {
 			})]);
 			if (typeof createdJob === "symbol") {
 				params.api.logger.warn(`knowhere: knowhere_ingest_document ingest completed before job-created callback scope=${scope.label} label=${JSON.stringify(progressLabel)}`);
-				return textResult("Ingest completed synchronously. Use knowhere_list_documents to find the stored document.");
+				return textResult("Ingest completed synchronously. The document is now stored and indexed.");
 			}
 			return textResult([
 				"Ingest job created. Parsing in background.",
@@ -987,7 +725,7 @@ function createImportCompletedJobTool(params) {
 	return {
 		name: "knowhere_import_completed_job",
 		label: "Knowhere Import Completed Job",
-		description: "Import a previously completed Knowhere job into the current scope. Downloads the result package and extracts it locally, making it available for knowhere_preview_document, knowhere_grep, and knowhere_read_result_file. Use knowhere_list_jobs to find available completed jobs.",
+		description: "Import a previously completed Knowhere job into the current scope. Downloads the result package and extracts it locally. Use knowhere_list_jobs to find available completed jobs.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -1047,6 +785,24 @@ function createImportCompletedJobTool(params) {
 				downloadedResult: importResult.downloadedResult
 			}, { overwrite });
 			params.api.logger.info(`knowhere: knowhere_import_completed_job stored imported document scope=${scope.label} jobId=${importResult.jobResult.job_id} docId=${document.id}`);
+			try {
+				const importKbId = params.kgService.resolveKbId(params.ctx);
+				if (importKbId && params.kgService.isEnabled()) {
+					params.api.logger.info(`knowhere: triggering KG build after import kbId=${importKbId}`);
+					buildKnowledgeGraphAsync({
+						kgService: params.kgService,
+						kbId: importKbId,
+						docId: document.id,
+						documentPayload: { downloadedResult: importResult.downloadedResult },
+						scope,
+						store: params.store,
+						ctx: params.ctx,
+						api: params.api
+					}).catch((e) => params.api.logger.error(`knowhere: KG build after import failed: ${formatErrorMessage(e)}`));
+				}
+			} catch (kgError) {
+				params.api.logger.warn(`knowhere: import KG trigger error: ${formatErrorMessage(kgError)}`);
+			}
 			return textResult([
 				"Import complete.",
 				...buildStoredDocumentSummaryLines({
@@ -1057,551 +813,11 @@ function createImportCompletedJobTool(params) {
 				}),
 				`Imported from job: ${importResult.jobResult.job_id}`,
 				`Source type: ${importResult.jobResult.source_type}`,
-				"Next: read manifest.json with knowhere_read_result_file or preview the document with knowhere_preview_document."
-			].join("\n"));
-		}
-	};
-}
-const GREP_VALID_TARGETS = new Set([
-	"chunk.content",
-	"chunk.summary",
-	"chunk.keywords",
-	"chunk.path",
-	"chunk.type",
-	"chunk.chunkId"
-]);
-const GREP_TEXT_TARGETS = [
-	"chunk.content",
-	"chunk.summary",
-	"chunk.keywords",
-	"chunk.path"
-];
-function parseGrepConditions(raw) {
-	if (!Array.isArray(raw)) return [];
-	return raw.filter(isRecord).map((entry) => {
-		const target = readString(entry.target);
-		if (target && !GREP_VALID_TARGETS.has(target)) throw new Error(`Invalid grep target: "${target}". Valid targets: ${[...GREP_VALID_TARGETS].join(", ")}`);
-		const pattern = typeof entry.pattern === "string" ? entry.pattern : "";
-		return {
-			...target ? { target } : {},
-			pattern,
-			...typeof entry.regex === "boolean" ? { regex: entry.regex } : {},
-			...typeof entry.caseSensitive === "boolean" ? { caseSensitive: entry.caseSensitive } : {}
-		};
-	});
-}
-function resolveGrepFieldValue(chunk, target) {
-	switch (target) {
-		case "chunk.content": return chunk.content || "";
-		case "chunk.summary": return chunk.summary || "";
-		case "chunk.keywords": return chunk.keywords || [];
-		case "chunk.path": return chunk.path || "";
-		case "chunk.type": return chunk.type;
-		case "chunk.chunkId": return chunk.chunkId;
-		default: return "";
-	}
-}
-function testGrepMatch(text, pattern, useRegex, caseSensitive) {
-	if (pattern === "") return true;
-	if (useRegex) {
-		const flags = caseSensitive ? "" : "i";
-		return new RegExp(pattern, flags).test(text);
-	}
-	if (caseSensitive) return text.includes(pattern);
-	return text.toLowerCase().includes(pattern.toLowerCase());
-}
-function testGrepCondition(chunk, normalizedFields, condition, outerRegex, outerCaseSensitive) {
-	const useRegex = condition.regex ?? outerRegex;
-	const caseSensitive = condition.caseSensitive ?? outerCaseSensitive;
-	const matchedTargets = [];
-	const targets = condition.target ? [condition.target] : GREP_TEXT_TARGETS;
-	for (const target of targets) {
-		const fieldValue = target === "chunk.type" || target === "chunk.chunkId" ? resolveGrepFieldValue(chunk, target) : normalizedFields.get(target) ?? resolveGrepFieldValue(chunk, target);
-		if (Array.isArray(fieldValue)) {
-			if (fieldValue.some((entry) => testGrepMatch(entry, condition.pattern, useRegex, caseSensitive))) matchedTargets.push(target);
-		} else if (testGrepMatch(fieldValue, condition.pattern, useRegex, caseSensitive)) matchedTargets.push(target);
-	}
-	return matchedTargets;
-}
-function buildNormalizedFields(chunk) {
-	const fields = /* @__PURE__ */ new Map();
-	fields.set("chunk.content", normalizeForGrep(chunk.content || ""));
-	fields.set("chunk.summary", normalizeForGrep(chunk.summary || ""));
-	fields.set("chunk.keywords", (chunk.keywords || []).map((k) => normalizeForGrep(k)));
-	fields.set("chunk.path", normalizeForGrep(chunk.path || ""));
-	return fields;
-}
-function buildGrepHints(params) {
-	const hints = [];
-	const maxHints = 3;
-	if (params.totalMatches === 0 && params.conditionCount > 0) hints.push("No matches. Try broadening: remove a condition, use a shorter pattern, or check for typos. Call knowhere_preview_document to see the document structure first.");
-	if (hints.length < maxHints && params.totalMatches > params.returned) {
-		let hint = `Showing ${params.returned} of ${params.totalMatches} matches. Add another condition (e.g., target chunk.path to a specific section) to narrow results.`;
-		if (!params.hasPathCondition) hint += " Use knowhere_preview_document to find section paths.";
-		hints.push(hint);
-	}
-	if (hints.length < maxHints && params.truncatedStrings) if (params.returned > 3) hints.push(`Fields truncated at ${params.maxStringChars} chars. Reduce maxResults to 1-3 and increase maxStringChars to 12000-20000 for full content.`);
-	else hints.push(`Fields truncated at ${params.maxStringChars} chars. Increase maxStringChars (up to 20000) for full content.`);
-	if (hints.length < maxHints && params.totalMatches >= 1 && params.totalMatches <= 5 && !params.includeContext) hints.push("Tip: set includeContext=true to discover sibling chunks in the same section.");
-	if (hints.length < maxHints && params.totalChunks > 0 && params.totalMatches > params.totalChunks * .5 && params.conditionCount <= 1) hints.push("Pattern matches over half the document. Add a second condition to narrow.");
-	return hints;
-}
-function createGrepTool(params) {
-	return {
-		name: "knowhere_grep",
-		label: "Knowhere Grep",
-		description: "Search a stored document's chunks with composable AND conditions. Returns matching chunks with content, summary, keywords, path, and chunkId. Supports substring and regex matching with text normalization (HTML stripping, LaTeX cleanup, unicode normalization). Omit conditions to list all chunks. Omit the target field in a condition to search across all text fields (content, summary, keywords, path) — this is the recommended default. When answering questions from results, cite the chunkId and path. Tip: set maxStringChars up to 20000 when you need full untruncated content from a small number of results (e.g., maxResults=1). The default 4000 may truncate long chunks. Search strategy: (1) Start with knowhere_preview_document to see document structure. (2) Search broadly with a single short pattern, then narrow by adding conditions. (3) If zero results, broaden or try synonyms. If too many, add a path condition. (4) Once you find the right chunks, re-query with maxResults=1-3 and maxStringChars=12000-20000 to read full content.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: {
-				docId: {
-					type: "string",
-					description: "Identifier of the stored document to search."
-				},
-				conditions: {
-					type: "array",
-					items: {
-						type: "object",
-						additionalProperties: false,
-						properties: {
-							target: {
-								type: "string",
-								enum: [...GREP_VALID_TARGETS],
-								description: "Chunk field to search. Omit to search all text fields (content, summary, keywords, path) — this is the recommended default."
-							},
-							pattern: {
-								type: "string",
-								description: "Search pattern. Empty string matches all."
-							},
-							regex: {
-								type: "boolean",
-								description: "Use regex matching for this condition. Overrides outer regex default."
-							},
-							caseSensitive: {
-								type: "boolean",
-								description: "Case-sensitive matching for this condition. Overrides outer default."
-							}
-						},
-						required: ["pattern"]
-					},
-					description: "ANDed search conditions. Each condition must match for a chunk to be returned. Default [] matches all chunks (useful for browsing). Omit target in a condition to search all text fields. Use multiple conditions to narrow results (e.g., path contains 'chapter 3' AND content contains 'algorithm')."
-				},
-				regex: {
-					type: "boolean",
-					description: "Default regex mode for all conditions. Defaults to false."
-				},
-				caseSensitive: {
-					type: "boolean",
-					description: "Default case-sensitivity for all conditions. Defaults to false."
-				},
-				includeContext: {
-					type: "boolean",
-					description: "Include sibling chunk IDs sharing the same document path for each matched chunk. Useful for navigating to adjacent chunks in the same section — re-query with a condition on chunk.chunkId to fetch a specific sibling."
-				},
-				maxResults: {
-					type: "integer",
-					minimum: 1,
-					maximum: 50,
-					description: "Maximum number of matching chunks to return. Defaults to 10. Use a low value (1–3) with high maxStringChars to read specific chunks in full. Use a higher value (10–50) with lower maxStringChars to scan broadly."
-				},
-				maxStringChars: {
-					type: "integer",
-					minimum: 100,
-					maximum: 2e4,
-					description: "Maximum characters per string field before truncation. Defaults to 4000. Increase up to 20000 when retrieving full content from a small number of results (e.g., reading a single chunk in full). Reduce below 4000 when scanning many results to save tokens."
-				}
-			},
-			required: ["docId"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const paramsRecord = isRecord(rawParams) ? rawParams : {};
-			const docId = readString(paramsRecord.docId);
-			if (!docId) throw new Error("docId is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			const payload = await params.store.loadDocumentPayload(scope, docId);
-			if (!payload) {
-				params.api.logger.warn(`knowhere: knowhere_grep document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			const conditions = parseGrepConditions(paramsRecord.conditions);
-			const outerRegex = readBoolean(paramsRecord.regex, false);
-			const outerCaseSensitive = readBoolean(paramsRecord.caseSensitive, false);
-			const includeContext = readBoolean(paramsRecord.includeContext, false);
-			const maxResults = Math.min(50, Math.max(1, Math.trunc(readNumber(paramsRecord.maxResults, 10))));
-			const maxStringChars = Math.min(2e4, Math.max(100, Math.trunc(readNumber(paramsRecord.maxStringChars, 4e3))));
-			params.api.logger.info(`knowhere: knowhere_grep searching document scope=${scope.label} docId=${docId} conditions=${conditions.length} regex=${outerRegex} caseSensitive=${outerCaseSensitive} includeContext=${includeContext} maxResults=${maxResults} maxStringChars=${maxStringChars}`);
-			const pathChunkIndex = includeContext ? new Map(payload.browseIndex.paths.map((p) => [p.path, p.chunkIds])) : void 0;
-			const sortedChunks = sortChunksByBrowseOrder(payload.chunks, payload.browseIndex);
-			const results = [];
-			for (const chunk of sortedChunks) {
-				if (results.length >= maxResults) break;
-				const normalizedFields = buildNormalizedFields(chunk);
-				const allMatchedTargets = /* @__PURE__ */ new Set();
-				let allConditionsPassed = true;
-				for (const condition of conditions) {
-					const matched = testGrepCondition(chunk, normalizedFields, condition, outerRegex, outerCaseSensitive);
-					if (matched.length === 0) {
-						allConditionsPassed = false;
-						break;
-					}
-					for (const target of matched) allMatchedTargets.add(target);
-				}
-				if (!allConditionsPassed) continue;
-				const entry = {
-					chunk,
-					matchedOn: [...allMatchedTargets]
-				};
-				if (includeContext && pathChunkIndex && chunk.path) {
-					const siblings = pathChunkIndex.get(chunk.path);
-					if (siblings) entry.siblingChunkIds = siblings.filter((id) => id !== chunk.chunkId);
-				}
-				results.push(entry);
-			}
-			let totalMatches = results.length;
-			if (results.length >= maxResults) {
-				const remainingChunks = sortedChunks.slice(sortedChunks.indexOf(results[results.length - 1].chunk) + 1);
-				for (const chunk of remainingChunks) {
-					const normalizedFields = buildNormalizedFields(chunk);
-					let passed = true;
-					for (const condition of conditions) if (testGrepCondition(chunk, normalizedFields, condition, outerRegex, outerCaseSensitive).length === 0) {
-						passed = false;
-						break;
-					}
-					if (passed) totalMatches++;
-				}
-			}
-			const truncated = truncateJsonValue(results.map((entry) => {
-				const projected = {
-					chunkId: entry.chunk.chunkId,
-					type: entry.chunk.type,
-					path: entry.chunk.path,
-					content: entry.chunk.content,
-					summary: entry.chunk.summary,
-					keywords: entry.chunk.keywords,
-					tokens: entry.chunk.tokens,
-					assetFilePath: entry.chunk.assetFilePath,
-					matchedOn: entry.matchedOn
-				};
-				if (entry.siblingChunkIds) projected.siblingChunkIds = entry.siblingChunkIds;
-				return projected;
-			}), maxStringChars);
-			params.api.logger.info(`knowhere: knowhere_grep completed search scope=${scope.label} docId=${docId} returned=${results.length} totalMatches=${totalMatches} truncated=${truncated.truncated}`);
-			const hasPathCondition = conditions.some((c) => c.target === "chunk.path");
-			const hints = buildGrepHints({
-				totalMatches,
-				returned: results.length,
-				maxResults,
-				maxStringChars,
-				truncatedStrings: truncated.truncated,
-				conditionCount: conditions.length,
-				includeContext,
-				totalChunks: sortedChunks.length,
-				hasPathCondition
-			});
-			const jsonResult = formatJsonToolResult({
-				totalMatches,
-				returned: results.length,
-				results: truncated.value,
-				maxStringChars,
-				truncatedStrings: truncated.truncated
-			});
-			if (hints.length === 0) return jsonResult;
-			return textResult(`${jsonResult.content[0].text}\n---\n${hints.join("\n")}`);
-		}
-	};
-}
-function createReadResultFileTool(params) {
-	return {
-		name: "knowhere_read_result_file",
-		label: "Knowhere Read Result File",
-		description: "Read a raw result file from the stored document's extracted ZIP package. Common files: manifest.json (parsing metadata), hierarchy.json (document structure), kb.csv (knowledge base export), table HTML files (e.g., tables/table-1.html), or image assets (e.g., images/img-0.png). Image files are staged into a local attachment path and sent directly to the current channel when routing can be resolved. If direct delivery is unavailable, the tool returns a message-tool handoff and, when the run has a workspace, a workspace-relative MEDIA fallback for a normal assistant reply. When the result mode is image_attachment, do not call generic file-read tools on data.stagedPath; use data.sendWithMessageTool or data.replyFallback as returned. When the result mode is image_sent, the plugin already delivered the image. Use mode='json' for JSON files, mode='csv' for CSV files, or mode='text' (default) for everything else. Increase maxStringChars (up to 20000) for large files.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: {
-				docId: {
-					type: "string",
-					description: "Identifier of the stored document to read from."
-				},
-				filePath: {
-					type: "string",
-					description: "Relative path under the stored result directory, for example manifest.json or tables/table-1.html."
-				},
-				mode: {
-					type: "string",
-					enum: [
-						"text",
-						"json",
-						"csv"
-					],
-					description: "text returns trimmed text, json parses JSON, and csv returns a raw CSV preview. Defaults to text."
-				},
-				maxStringChars: {
-					type: "integer",
-					minimum: 100,
-					maximum: 2e4,
-					description: "Maximum characters per string field before truncation. Defaults to 4000. Increase up to 20000 for large files like hierarchy.json or kb.csv."
-				}
-			},
-			required: ["docId", "filePath"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const paramsRecord = isRecord(rawParams) ? rawParams : {};
-			const docId = readString(paramsRecord.docId);
-			const filePath = normalizeResultFilePath(paramsRecord.filePath);
-			if (!docId) throw new Error("docId is required.");
-			if (!filePath) throw new Error("filePath is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			const payload = await params.store.loadDocumentPayload(scope, docId);
-			if (!payload) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			const resultFile = findResultFile(payload.browseIndex, filePath);
-			if (!resultFile) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file result file not found scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return textResult([
-					"Result file not found.",
-					`File path: ${filePath}`,
-					`Document ID: ${docId}`,
-					`Scope: ${scope.label}`
-				].join("\n"));
-			}
-			if (resultFile.kind === "image") {
-				const absolutePath = params.store.getResultFileAbsolutePath(scope, docId, filePath);
-				const channelRoute = await params.store.resolveChannelRoute({ sessionKey: params.ctx.sessionKey });
-				params.api.logger.info(`knowhere: knowhere_read_result_file staging image asset scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return await buildImageToolResult({
-					api: params.api,
-					absolutePath,
-					channelRoute,
-					context: params.ctx,
-					docId: payload.document.id,
-					documentTitle: payload.document.title,
-					filePath,
-					file: resultFile,
-					sessionKey: params.ctx.sessionKey,
-					scopeLabel: scope.label,
-					workspaceDir: params.ctx.workspaceDir
-				});
-			}
-			if (!isTextReadableResultFile(resultFile)) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file unreadable result kind scope=${scope.label} docId=${docId} filePath=${filePath} kind=${resultFile.kind}`);
-				return textResult([
-					"Result file is not readable as text through this tool.",
-					`File path: ${filePath}`,
-					`Kind: ${resultFile.kind}`,
-					`Document ID: ${docId}`,
-					`Scope: ${scope.label}`
-				].join("\n"));
-			}
-			const storedFile = await params.store.readResultFile(scope, docId, filePath);
-			if (!storedFile) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file payload disappeared scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			if (storedFile.text === null) {
-				params.api.logger.warn(`knowhere: knowhere_read_result_file text content missing scope=${scope.label} docId=${docId} filePath=${filePath}`);
-				return textResult([
-					"Result file not found.",
-					`File path: ${filePath}`,
-					`Document ID: ${docId}`,
-					`Scope: ${scope.label}`
-				].join("\n"));
-			}
-			const mode = readResultFileReadMode(paramsRecord.mode);
-			const maxStringChars = Math.min(2e4, Math.max(100, Math.trunc(readNumber(paramsRecord.maxStringChars, 4e3))));
-			const normalizedText = stripUtf8Bom(storedFile.text);
-			params.api.logger.info(`knowhere: knowhere_read_result_file reading file scope=${scope.label} docId=${docId} filePath=${filePath} kind=${resultFile.kind} mode=${mode} maxStringChars=${maxStringChars}`);
-			if (mode === "json") {
-				let parsedJson;
-				try {
-					parsedJson = JSON.parse(normalizedText);
-				} catch (error) {
-					params.api.logger.warn(`knowhere: knowhere_read_result_file invalid json scope=${scope.label} docId=${docId} filePath=${filePath} error=${formatErrorMessage(error)}`);
-					throw new Error(`Result file ${filePath} is not valid JSON. ${formatErrorMessage(error)}`, { cause: error });
-				}
-				const truncatedJson = truncateJsonValue(parsedJson, maxStringChars);
-				params.api.logger.info(`knowhere: knowhere_read_result_file parsed json scope=${scope.label} docId=${docId} filePath=${filePath} truncated=${truncatedJson.truncated}`);
-				return formatJsonToolResult({
-					scope: scope.label,
-					docId: payload.document.id,
-					documentTitle: payload.document.title,
-					file: resultFile,
-					mode,
-					maxStringChars,
-					truncatedStrings: truncatedJson.truncated,
-					data: truncatedJson.value
-				});
-			}
-			const data = mode === "csv" ? buildCsvFilePayload(normalizedText, maxStringChars) : buildTextFilePayload(normalizedText, maxStringChars);
-			params.api.logger.info(`knowhere: knowhere_read_result_file prepared text payload scope=${scope.label} docId=${docId} filePath=${filePath} lineCount=${data.lineCount}`);
-			return formatJsonToolResult({
-				scope: scope.label,
-				docId: payload.document.id,
-				documentTitle: payload.document.title,
-				file: resultFile,
-				mode,
-				maxStringChars,
-				data
-			});
-		}
-	};
-}
-function createPreviewDocumentTool(params) {
-	return {
-		name: "knowhere_preview_document",
-		label: "Knowhere Preview Document",
-		description: "Get a structural overview of a stored Knowhere document. Returns the document metadata and a hierarchical table of contents showing sections, subsections, and chunk counts per path (text, image, table). Use this as the first step after identifying a docId to understand the document's structure before searching with knowhere_grep.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: { docId: {
-				type: "string",
-				description: "Identifier of the stored document to preview."
-			} },
-			required: ["docId"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const docId = readString((isRecord(rawParams) ? rawParams : {}).docId);
-			if (!docId) throw new Error("docId is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			const payload = await params.store.loadDocumentPayload(scope, docId);
-			if (!payload) {
-				params.api.logger.warn(`knowhere: knowhere_preview_document document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			const { document } = payload;
-			const pathSummaryMap = /* @__PURE__ */ new Map();
-			for (const chunk of payload.chunks) {
-				if (!chunk.path || pathSummaryMap.has(chunk.path)) continue;
-				const raw = (chunk.summary || chunk.content || "").trim();
-				if (raw) {
-					const oneLine = raw.replace(/\n+/g, " ").slice(0, PREVIEW_SUMMARY_MAX_CHARS);
-					pathSummaryMap.set(chunk.path, oneLine + (raw.length > PREVIEW_SUMMARY_MAX_CHARS ? "..." : ""));
-				}
-			}
-			const lines = [
-				`"${document.title}" [${document.id}]`,
-				`Scope: ${scope.label}`,
-				`Source: ${document.sourceLabel}`,
-				`Chunks: ${document.chunkCount}`
-			];
-			const pathByName = /* @__PURE__ */ new Map();
-			for (const p of payload.browseIndex.paths) pathByName.set(p.path, p);
-			const roots = payload.browseIndex.paths.filter((p) => p.depth === 1);
-			params.api.logger.info(`knowhere: knowhere_preview_document building preview scope=${scope.label} docId=${docId} paths=${payload.browseIndex.paths.length} roots=${roots.length} chunks=${payload.chunks.length}`);
-			if (roots.length > 0) {
-				lines.push("");
-				lines.push("## Table of Contents");
-				lines.push("");
-				const renderTree = (pathRecord, indent) => {
-					const prefix = "  ".repeat(indent);
-					const segments = pathRecord.path.split(/\/|-->/);
-					const label = segments[segments.length - 1] || pathRecord.path;
-					const counts = [];
-					if (pathRecord.textChunkCount > 0) counts.push(`${pathRecord.textChunkCount} text`);
-					if (pathRecord.imageChunkCount > 0) counts.push(`${pathRecord.imageChunkCount} img`);
-					if (pathRecord.tableChunkCount > 0) counts.push(`${pathRecord.tableChunkCount} tbl`);
-					const countStr = counts.length > 0 ? ` (${counts.join(", ")})` : "";
-					const summary = pathSummaryMap.get(pathRecord.path);
-					const summaryStr = summary ? ` — ${summary}` : "";
-					lines.push(`${prefix}- ${label}${countStr}${summaryStr}`);
-					for (const childPath of pathRecord.childPaths) {
-						const child = pathByName.get(childPath);
-						if (child) renderTree(child, indent + 1);
-					}
-				};
-				for (const root of roots) renderTree(root, 0);
-			} else {
-				lines.push("");
-				lines.push("No structural paths available for this document.");
-				params.api.logger.warn(`knowhere: knowhere_preview_document no structural paths scope=${scope.label} docId=${docId}`);
-			}
-			return textResult(lines.join("\n"));
-		}
-	};
-}
-function createListTool(params) {
-	return {
-		name: "knowhere_list_documents",
-		label: "Knowhere List",
-		description: "List all Knowhere documents stored in the current scope. Returns each document's ID, title, source, chunk count, tags, and last-updated timestamp. Use this first to discover available documents, check whether a file or URL is already stored, and find the right docId before calling other tools.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: {}
-		},
-		execute: async () => {
-			const scope = params.store.resolveScope(params.ctx);
-			const documents = await params.store.listDocuments(scope);
-			params.api.logger.info(`knowhere: knowhere_list_documents listed documents scope=${scope.label} count=${documents.length}`);
-			return textResult(formatDocumentList(documents, scope.label));
-		}
-	};
-}
-function createRemoveTool(params) {
-	return {
-		name: "knowhere_remove_document",
-		label: "Knowhere Remove",
-		description: "Remove a stored Knowhere document and all its extracted data from the current scope. This is irreversible — the document must be re-ingested or re-imported to restore it.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: { docId: {
-				type: "string",
-				description: "Identifier of the stored document to remove."
-			} },
-			required: ["docId"]
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const docId = readString((isRecord(rawParams) ? rawParams : {}).docId);
-			if (!docId) throw new Error("docId is required.");
-			const scope = params.store.resolveScope(params.ctx);
-			params.api.logger.info(`knowhere: knowhere_remove_document removing document scope=${scope.label} docId=${docId}`);
-			const removed = await params.store.removeDocument(scope, docId);
-			if (!removed) {
-				params.api.logger.warn(`knowhere: knowhere_remove_document document not found scope=${scope.label} docId=${docId}`);
-				return textResult(formatStoredDocumentNotFound(docId, scope.label));
-			}
-			params.api.logger.info(`knowhere: knowhere_remove_document removed document scope=${scope.label} docId=${removed.id}`);
-			return textResult([
-				"Removed stored document.",
-				`Document ID: ${removed.id}`,
-				`Title: ${removed.title}`,
-				`Scope: ${scope.label}`
+				"Document imported successfully. Use knowhere_kg_query to search its content."
 			].join("\n"));
 		}
 	};
 }
-function createClearScopeTool(params) {
-	return {
-		name: "knowhere_clear_scope",
-		label: "Knowhere Clear Scope",
-		description: "Remove all stored Knowhere documents from the current scope. This is irreversible and affects every document in the scope. Set confirm=true to execute.",
-		parameters: {
-			type: "object",
-			additionalProperties: false,
-			properties: { confirm: {
-				type: "boolean",
-				description: "Must be true to clear the current scope."
-			} }
-		},
-		execute: async (_toolCallId, rawParams) => {
-			const paramsRecord = isRecord(rawParams) ? rawParams : {};
-			const scope = params.store.resolveScope(params.ctx);
-			if (!readBoolean(paramsRecord.confirm, false)) {
-				params.api.logger.warn(`knowhere: knowhere_clear_scope skipped without confirm scope=${scope.label}`);
-				return textResult(`Set confirm=true to clear scope ${scope.label}.`);
-			}
-			params.api.logger.info(`knowhere: knowhere_clear_scope clearing scope scope=${scope.label}`);
-			const removedDocuments = await params.store.clearScope(scope);
-			params.api.logger.info(`knowhere: knowhere_clear_scope cleared scope scope=${scope.label} removed=${removedDocuments.length}`);
-			return textResult(formatScopeClearResult(removedDocuments, scope.label));
-		}
-	};
-}
 function createSetApiKeyTool(params) {
 	return {
 		name: "knowhere_set_api_key",
@@ -1717,6 +933,380 @@ function createKgQueryTool(params) {
 		}
 	};
 }
+const T2_KNOWHERE_HOME = path.join(os.homedir(), ".knowhere");
+async function t2FindDocDir(kbDir, docName) {
+	const exactPath = path.join(kbDir, docName);
+	try {
+		await fs.access(exactPath);
+		return exactPath;
+	} catch {}
+	let entries;
+	try {
+		entries = await fs.readdir(kbDir, { withFileTypes: true });
+	} catch {
+		return null;
+	}
+	for (const e of entries) if (e.isDirectory() && String(e.name).includes(docName)) return path.join(kbDir, String(e.name));
+	return null;
+}
+async function t2LoadChunks(docDir) {
+	for (const fname of ["chunks_slim.json", "chunks.json"]) try {
+		const raw = await fs.readFile(path.join(docDir, fname), "utf-8");
+		const data = JSON.parse(raw);
+		let chunks;
+		if (Array.isArray(data)) chunks = data;
+		else if (isRecord(data) && Array.isArray(data.chunks)) chunks = data.chunks;
+		else continue;
+		if (fname === "chunks.json") return chunks.map((c) => ({
+			type: c.type || "text",
+			path: c.path || "",
+			content: c.content || "",
+			summary: c.metadata?.summary || c.summary || ""
+		}));
+		return chunks;
+	} catch {
+		continue;
+	}
+	return [];
+}
+async function t2LoadRawChunks(docDir) {
+	try {
+		const raw = await fs.readFile(path.join(docDir, "chunks.json"), "utf-8");
+		const data = JSON.parse(raw);
+		if (Array.isArray(data)) return data;
+		if (isRecord(data) && Array.isArray(data.chunks)) return data.chunks;
+		return [];
+	} catch {
+		return [];
+	}
+}
+function t2ComputeTfIdfKeywords(rawChunks, topK = 10) {
+	const df = {};
+	const tf = {};
+	const totalDocs = rawChunks.length || 1;
+	for (const c of rawChunks) {
+		const tokens = Array.isArray(c.metadata?.tokens) ? c.metadata.tokens : [];
+		const keywords = Array.isArray(c.metadata?.keywords) ? c.metadata.keywords : [];
+		const allTerms = [...tokens, ...keywords];
+		const seen = /* @__PURE__ */ new Set();
+		for (const t of allTerms) {
+			if (!t || t.length <= 1) continue;
+			if (/^\d+[.,%]*$/.test(t)) continue;
+			const lower = t.toLowerCase();
+			tf[lower] = (tf[lower] || 0) + 1;
+			if (!seen.has(lower)) {
+				df[lower] = (df[lower] || 0) + 1;
+				seen.add(lower);
+			}
+		}
+	}
+	const scored = Object.entries(tf).map(([term, freq]) => {
+		return {
+			term,
+			score: freq * (Math.log(totalDocs / (df[term] || 1)) + 1)
+		};
+	});
+	scored.sort((a, b) => b.score - a.score);
+	return scored.slice(0, topK).map((s) => s.term);
+}
+function t2KeywordsNeedRepair(keywords) {
+	if (!Array.isArray(keywords) || keywords.length === 0) return true;
+	let bad = 0;
+	for (const kw of keywords) if (!kw || typeof kw === "string" && (kw.length <= 1 || /^\d+[.,%]*$/.test(kw) || /^[a-z]{1,2}$/i.test(kw))) bad++;
+	return bad >= keywords.length * .5;
+}
+function t2JsonResult(data) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data, null, 2)
+		}],
+		details: {}
+	};
+}
+async function t2ListDocDirs(kbRoot) {
+	let entries;
+	try {
+		entries = await fs.readdir(kbRoot, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const docs = [];
+	for (const e of entries) {
+		if (!e.isDirectory()) continue;
+		try {
+			await fs.access(path.join(kbRoot, String(e.name), "chunks.json"));
+			docs.push(String(e.name));
+		} catch {
+			continue;
+		}
+	}
+	return docs;
+}
+function createGetMapTool(_params) {
+	return {
+		name: "knowhere_get_map",
+		label: "Knowhere Get Map",
+		description: "获取知识库全局概览。查询知识时必须先调此工具，了解有哪些文档、关键词、重要性和跨文件关联。然后用 knowhere_get_structure 查看具体文档的章节目录。",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: { kbId: {
+				type: "string",
+				description: "Optional: specific KB ID. Leave empty to scan all."
+			} }
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const kbId = readString((isRecord(rawParams) ? rawParams : {}).kbId) || "";
+			try {
+				await fs.access(T2_KNOWHERE_HOME);
+			} catch {
+				return textResult(`未找到知识库目录 ${T2_KNOWHERE_HOME}`);
+			}
+			const entries = await fs.readdir(T2_KNOWHERE_HOME, { withFileTypes: true });
+			const kbs = [];
+			for (const e of entries) {
+				if (!e.isDirectory()) continue;
+				if (kbId && e.name !== kbId) continue;
+				const kbRoot = path.join(T2_KNOWHERE_HOME, e.name);
+				const kgPath = path.join(kbRoot, "knowledge_graph.json");
+				try {
+					const g = JSON.parse(await fs.readFile(kgPath, "utf-8"));
+					let kgDirty = false;
+					const files = g.files || {};
+					for (const [docName, info] of Object.entries(files)) if (t2KeywordsNeedRepair(info.top_keywords)) {
+						const rawChunks = await t2LoadRawChunks(path.join(kbRoot, docName));
+						if (rawChunks.length > 0) {
+							const repaired = t2ComputeTfIdfKeywords(rawChunks);
+							if (repaired.length > 0) {
+								info.top_keywords = repaired;
+								const types = {};
+								for (const c of rawChunks) {
+									const t = c.type || "text";
+									types[t] = (types[t] || 0) + 1;
+								}
+								info.types = types;
+								info.chunks_count = rawChunks.length;
+								kgDirty = true;
+							}
+						}
+					}
+					if (kgDirty) {
+						g.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+						try {
+							await fs.writeFile(kgPath, JSON.stringify(g, null, 2), "utf-8");
+						} catch {}
+					}
+					kbs.push({
+						kb_id: e.name,
+						version: g.version || "1.0",
+						updated_at: g.updated_at || "",
+						stats: g.stats || {},
+						files: g.files || {},
+						edges: g.edges || []
+					});
+				} catch {
+					const docs = await t2ListDocDirs(kbRoot);
+					if (docs.length > 0) kbs.push({
+						kb_id: e.name,
+						version: "pending",
+						files: Object.fromEntries(docs.map((d) => [d, {}])),
+						edges: []
+					});
+				}
+			}
+			if (kbs.length === 0) return textResult("未找到知识库。");
+			return t2JsonResult({
+				status: "ok",
+				knowledge_bases: kbs
+			});
+		}
+	};
+}
+function createGetStructureTool(_params) {
+	return {
+		name: "knowhere_get_structure",
+		label: "Knowhere Get Structure",
+		description: "获取文档章节目录。先调 knowhere_get_map 确定 kbId 和文档名后，用此工具查看章节结构，然后用 knowhere_read_chunks 读取内容。",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				kbId: {
+					type: "string",
+					description: "Knowledge base ID (from knowhere_get_map result)"
+				},
+				docName: {
+					type: "string",
+					description: "Document name (supports fuzzy match)"
+				}
+			},
+			required: ["kbId", "docName"]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const paramsRecord = isRecord(rawParams) ? rawParams : {};
+			const kbId = readString(paramsRecord.kbId);
+			const docName = readString(paramsRecord.docName);
+			if (!kbId || !docName) throw new Error("kbId and docName are required.");
+			const docDir = await t2FindDocDir(path.join(T2_KNOWHERE_HOME, kbId), docName);
+			if (!docDir) return textResult(`文档 '${docName}' 在 kb=${kbId} 中不存在`);
+			try {
+				const h = JSON.parse(await fs.readFile(path.join(docDir, "hierarchy.json"), "utf-8"));
+				return t2JsonResult({
+					status: "ok",
+					kb_id: kbId,
+					doc_name: path.basename(docDir),
+					hierarchy: h
+				});
+			} catch {
+				const chunks = await t2LoadChunks(docDir);
+				const paths = [...new Set(chunks.map((c) => c.path).filter(Boolean))].sort();
+				return t2JsonResult({
+					status: "ok",
+					kb_id: kbId,
+					doc_name: path.basename(docDir),
+					hierarchy: null,
+					chunk_paths: paths,
+					hint: "无 hierarchy.json，已返回 chunk 路径列表"
+				});
+			}
+		}
+	};
+}
+function createReadChunksTool(_params) {
+	return {
+		name: "knowhere_read_chunks",
+		label: "Knowhere Read Chunks",
+		description: "读取文档内容。先调 knowhere_get_structure 确定章节后，用此工具读取具体内容。可通过 sectionPath 过滤特定章节，减少 token 消耗。",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				kbId: {
+					type: "string",
+					description: "Knowledge base ID"
+				},
+				docName: {
+					type: "string",
+					description: "Document name"
+				},
+				sectionPath: {
+					type: "string",
+					description: "Optional: section path prefix to filter (e.g. '一、工程概况')"
+				},
+				maxChunks: {
+					type: "number",
+					description: "Max chunks to return (default 50)"
+				}
+			},
+			required: ["kbId", "docName"]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const paramsRecord = isRecord(rawParams) ? rawParams : {};
+			const kbId = readString(paramsRecord.kbId);
+			const docName = readString(paramsRecord.docName);
+			const sectionPath = readString(paramsRecord.sectionPath);
+			const maxChunks = readNumber(paramsRecord.maxChunks, 50);
+			if (!kbId || !docName) throw new Error("kbId and docName are required.");
+			const docDir = await t2FindDocDir(path.join(T2_KNOWHERE_HOME, kbId), docName);
+			if (!docDir) return textResult(`文档 '${docName}' 不存在`);
+			let chunks = await t2LoadChunks(docDir);
+			if (sectionPath) chunks = chunks.filter((c) => c.path.includes(sectionPath));
+			const total = chunks.length;
+			const limit = maxChunks || 50;
+			chunks = chunks.slice(0, limit);
+			try {
+				const kgPath = path.join(T2_KNOWHERE_HOME, kbId, "knowledge_graph.json");
+				const g = JSON.parse(await fs.readFile(kgPath, "utf-8"));
+				const dn = path.basename(docDir);
+				if (g.files?.[dn]) {
+					g.files[dn].hit_count = (g.files[dn].hit_count || 0) + 1;
+					g.files[dn].last_hit = (/* @__PURE__ */ new Date()).toISOString();
+					g.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+					await fs.writeFile(kgPath, JSON.stringify(g, null, 2), "utf-8");
+				}
+			} catch {}
+			return t2JsonResult({
+				status: "ok",
+				kb_id: kbId,
+				doc_name: path.basename(docDir),
+				section_path: sectionPath || null,
+				total_chunks: total,
+				returned: chunks.length,
+				truncated: total > limit,
+				chunks
+			});
+		}
+	};
+}
+function createDiscoverFilesTool(_params) {
+	return {
+		name: "knowhere_discover_files",
+		label: "Knowhere Discover Files",
+		description: "在所有知识库文档中搜索关键词，返回命中文件和次数。用于和 knowhere_get_map 做并集，避免遗漏相关文件。只返回文件名，不返回内容。",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				query: {
+					type: "string",
+					description: "Search keywords"
+				},
+				kbId: {
+					type: "string",
+					description: "Optional: limit to specific KB"
+				}
+			},
+			required: ["query"]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const paramsRecord = isRecord(rawParams) ? rawParams : {};
+			const query = readString(paramsRecord.query);
+			const kbId = readString(paramsRecord.kbId);
+			if (!query) throw new Error("query is required.");
+			const terms = query.split(/[\s,;，；。！？、\-/]+/).filter((t) => t.length > 1);
+			if (terms.length === 0) return textResult("查询词为空");
+			try {
+				await fs.access(T2_KNOWHERE_HOME);
+			} catch {
+				return textResult("未找到知识库。");
+			}
+			const results = [];
+			const kbEntries = await fs.readdir(T2_KNOWHERE_HOME, { withFileTypes: true });
+			for (const kbE of kbEntries) {
+				if (!kbE.isDirectory()) continue;
+				if (kbId && kbE.name !== kbId) continue;
+				let docEntries;
+				try {
+					docEntries = await fs.readdir(path.join(T2_KNOWHERE_HOME, String(kbE.name)), { withFileTypes: true });
+				} catch {
+					continue;
+				}
+				for (const docE of docEntries) {
+					if (!docE.isDirectory()) continue;
+					const chunks = await t2LoadChunks(path.join(T2_KNOWHERE_HOME, String(kbE.name), String(docE.name)));
+					let hits = 0;
+					for (const c of chunks) {
+						const text = `${c.content} ${c.summary}`;
+						for (const t of terms) if (text.includes(t)) hits++;
+					}
+					if (hits > 0) results.push({
+						kb_id: String(kbE.name),
+						doc_name: String(docE.name),
+						hit_count: hits
+					});
+				}
+			}
+			results.sort((a, b) => b.hit_count - a.hit_count);
+			return t2JsonResult({
+				status: "ok",
+				query,
+				terms,
+				discovered_files: results
+			});
+		}
+	};
+}
 function createKnowhereToolFactory(params) {
 	return (ctx) => [
 		createIngestTool({
@@ -1742,36 +1332,7 @@ function createKnowhereToolFactory(params) {
 			api: params.api,
 			config: params.config,
 			store: params.store,
-			ctx
-		}),
-		createGrepTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createReadResultFileTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createPreviewDocumentTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createListTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createRemoveTool({
-			api: params.api,
-			store: params.store,
-			ctx
-		}),
-		createClearScopeTool({
-			api: params.api,
-			store: params.store,
+			kgService: params.kgService,
 			ctx
 		}),
 		createSetApiKeyTool({
@@ -1787,7 +1348,11 @@ function createKnowhereToolFactory(params) {
 			api: params.api,
 			kgService: params.kgService,
 			ctx
-		})
+		}),
+		createGetMapTool({ api: params.api }),
+		createGetStructureTool({ api: params.api }),
+		createReadChunksTool({ api: params.api }),
+		createDiscoverFilesTool({ api: params.api })
 	];
 }
 //#endregion