@ontos-ai/knowhere-claw 0.2.2 → 0.2.4

package/README.md

@@ -1,7 +1,7 @@
 # Knowhere for OpenClaw
 
 Knowhere is an OpenClaw plugin that parses documents and URLs with Knowhere,
-stores the extracted result package in OpenClaw state, and gives agents a
+stores extracted Knowhere files in OpenClaw state, and gives agents a
 browse-first toolset for grounded document work.
 
 Quick mental model:
@@ -22,7 +22,7 @@ the machine running that Gateway, then restart that Gateway.
 ## What You Get
 
 - Ingest local files or document URLs with Knowhere
-- Store parsed result packages inside OpenClaw-managed state
+- Store parsed documents inside OpenClaw-managed state
 - Preview document structure, search chunks, and inspect raw result files
 - Reuse stored documents across `session`, `agent`, or `global` scope
 - Ship bundled `knowhere` and `knowhere_memory` skills so agents prefer this
@@ -73,7 +73,7 @@ Config notes:
 - `pollIntervalMs`, `pollTimeoutMs`, `requestTimeoutMs`, `uploadTimeoutMs`:
   optional tuning for job polling, API calls, and large uploads.
 - An explicit `storageDir` such as
-  `/home/<user>/.openclaw/plugin-state/knowhere` makes stored result packages
+  `/home/<user>/.openclaw/plugin-state/knowhere` makes stored documents
   easier to inspect, back up, or clean up.
 
 ## How OpenClaw Uses It
@@ -110,13 +110,13 @@ actually call the plugin tools.
 Within each scope, the plugin keeps:
 
 - an `index.json` cache of stored document summaries
-- per-document metadata and browse indexes
-- the extracted Knowhere result package under `result/`
+- a `metadata/` directory with one JSON record per stored document
+- the extracted Knowhere result files directly inside each document directory
 
 ## Common Workflow
 
 1. Provide a file path or URL to the agent.
-2. The agent ingests it into Knowhere and waits for the parse to finish.
+2. The agent ingests it into Knowhere. By default this starts parsing asynchronously and returns a job ID; when the current turn needs the parsed result immediately, the agent can call `knowhere_ingest_document` with `blockUntilComplete: true`.
 3. Follow-up questions reuse stored results from the current scope.
 4. When needed, the agent can preview structure, search chunks, read raw result
    files, or clear stored documents.

package/dist/connect-builder.d.ts

@@ -12,6 +12,8 @@ export interface ChunkData {
     chunk_id: string;
     path: string;
     content: string;
+    /** Document directory name (e.g. "report.pdf"). Injected by kg-service at load time. */
+    fileKey: string;
     metadata: {
         keywords?: string[];
         tokens?: string[];

package/dist/connect-builder.js

@@ -8,15 +8,14 @@ function normalizeKeyword(keyword) {
 	return keyword.toLowerCase().trim();
 }
 /**
-* Extract file key from a chunk path
-* Equivalent to Python: _extract_file_key
-*
-* Example: "Default_Root/report.docx/Chapter 1" -> "report.docx"
+* Extract file key from a chunk.
+* Prefers the explicit fileKey field; falls back to path-based extraction for backward compatibility.
 */
-function extractFileKey(path) {
-	const parts = path.split("/");
+function getFileKey(chunk) {
+	if (chunk.fileKey) return chunk.fileKey;
+	const parts = chunk.path.replace(/-->/g, "/").split("/");
 	if (parts.length >= 2) return parts[1];
-	return path;
+	return chunk.path;
 }
 /**
 * Build inverted keyword index: keyword -> [chunk_ids]
@@ -97,7 +96,7 @@ function buildConnections(chunks, config, logger) {
 	for (const chunk of chunks) chunkById.set(chunk.chunk_id, chunk);
 	const chunksByFile = /* @__PURE__ */ new Map();
 	for (const chunk of chunks) {
-		const fileKey = extractFileKey(chunk.path);
+		const fileKey = getFileKey(chunk);
 		if (!chunksByFile.has(fileKey)) chunksByFile.set(fileKey, /* @__PURE__ */ new Set());
 		chunksByFile.get(fileKey).add(chunk.chunk_id);
 	}
@@ -120,14 +119,14 @@ function buildConnections(chunks, config, logger) {
 		const sourceChunk = chunkById.get(sourceId);
 		if (!sourceChunk) continue;
 		const sourceKeywords = getKeywords(sourceChunk);
-		const sourceFileKey = extractFileKey(sourceChunk.path);
+		const sourceFileKey = getFileKey(sourceChunk);
 		for (const targetId of targetIds) {
 			const targetChunk = chunkById.get(targetId);
 			if (!targetChunk) continue;
 			const pairKey = sourceId < targetId ? `${sourceId}::${targetId}` : `${targetId}::${sourceId}`;
 			if (seenPairs.has(pairKey)) continue;
 			seenPairs.add(pairKey);
-			const targetFileKey = extractFileKey(targetChunk.path);
+			const targetFileKey = getFileKey(targetChunk);
 			if (config.crossFileOnly && sourceFileKey === targetFileKey) continue;
 			const contentRatio = sequenceMatcherRatio(sourceChunk.content.slice(0, 500), targetChunk.content.slice(0, 500));
 			if (contentRatio >= config.maxContentOverlap) {

package/dist/graph-builder.d.ts

@@ -32,12 +32,15 @@ interface FileMetadata {
     top_keywords: string[];
     top_summary: string;
     importance: number;
+    created_at: string;
 }
 /**
  * Complete knowledge graph structure
  */
 export interface KnowledgeGraph {
     version: string;
+    updated_at: string;
+    kb_id: string;
     stats: {
         total_files: number;
         total_chunks: number;
@@ -59,7 +62,7 @@ export interface ChunkStats {
  * Main function to build knowledge graph
  * Equivalent to Python: build_knowledge_graph
  */
-export declare function buildKnowledgeGraph(chunks: ChunkData[], connections: Connection[], chunkStats: ChunkStats, jiebaInitialized: boolean, logger?: PluginLogger): KnowledgeGraph;
+export declare function buildKnowledgeGraph(chunks: ChunkData[], connections: Connection[], chunkStats: ChunkStats, jiebaInitialized: boolean, logger?: PluginLogger, kbId?: string): KnowledgeGraph;
 /**
  * Incremental update: match new chunks against existing chunks
  * Equivalent to Python: _incremental_connections

package/dist/graph-builder.js

@@ -7,12 +7,14 @@ import * as nodejieba from "nodejieba";
 * Builds file-level knowledge graphs from chunk connections with TF-IDF and importance scoring.
 */
 /**
-* Extract file key from chunk path
+* Extract file key from a chunk.
+* Prefers the explicit fileKey field; falls back to path-based extraction for backward compatibility.
 */
-function extractFileKey(path) {
-	const parts = path.split("/");
+function getFileKey(chunk) {
+	if (chunk.fileKey) return chunk.fileKey;
+	const parts = chunk.path.replace(/-->/g, "/").split("/");
 	if (parts.length >= 2) return parts[1];
-	return path;
+	return chunk.path;
 }
 /**
 * Extract label from chunk path (last segment)
@@ -107,7 +109,7 @@ function computeFileImportance(fileKey, fileChunks, allChunks, chunkStats, decay
 function getAllChunkCountsByFile(chunks) {
 	const countsByFile = /* @__PURE__ */ new Map();
 	for (const chunk of chunks) {
-		const fileKey = extractFileKey(chunk.path);
+		const fileKey = getFileKey(chunk);
 		countsByFile.set(fileKey, (countsByFile.get(fileKey) || 0) + 1);
 	}
 	return Array.from(countsByFile.values());
@@ -122,8 +124,8 @@ function aggregateFileLevelEdges(connections, chunkById, topN = 5) {
 		const sourceChunk = chunkById.get(conn.source);
 		const targetChunk = chunkById.get(conn.target);
 		if (!sourceChunk || !targetChunk) continue;
-		const sourceFile = extractFileKey(sourceChunk.path);
-		const targetFile = extractFileKey(targetChunk.path);
+		const sourceFile = getFileKey(sourceChunk);
+		const targetFile = getFileKey(targetChunk);
 		if (sourceFile === targetFile) continue;
 		const pairKey = sourceFile < targetFile ? `${sourceFile}::${targetFile}` : `${targetFile}::${sourceFile}`;
 		if (!filePairs.has(pairKey)) filePairs.set(pairKey, []);
@@ -159,13 +161,13 @@ function aggregateFileLevelEdges(connections, chunkById, topN = 5) {
 * Main function to build knowledge graph
 * Equivalent to Python: build_knowledge_graph
 */
-function buildKnowledgeGraph(chunks, connections, chunkStats, jiebaInitialized, logger) {
+function buildKnowledgeGraph(chunks, connections, chunkStats, jiebaInitialized, logger, kbId) {
 	logger?.info(`Building knowledge graph from ${chunks.length} chunks and ${connections.length} connections`);
 	const chunkById = /* @__PURE__ */ new Map();
 	for (const chunk of chunks) chunkById.set(chunk.chunk_id, chunk);
 	const chunksByFile = /* @__PURE__ */ new Map();
 	for (const chunk of chunks) {
-		const fileKey = extractFileKey(chunk.path);
+		const fileKey = getFileKey(chunk);
 		if (!chunksByFile.has(fileKey)) chunksByFile.set(fileKey, []);
 		chunksByFile.get(fileKey).push(chunk);
 	}
@@ -188,13 +190,16 @@ function buildKnowledgeGraph(chunks, connections, chunkStats, jiebaInitialized,
 			types: typeCount,
 			top_keywords: topKeywords,
 			top_summary: topSummary,
-			importance
+			importance,
+			created_at: (/* @__PURE__ */ new Date()).toISOString()
 		};
 	}
 	const fileEdges = aggregateFileLevelEdges(connections, chunkById, 5);
 	logger?.info(`Created graph with ${Object.keys(filesMetadata).length} files and ${fileEdges.length} edges`);
 	return {
 		version: "2.0",
+		updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+		kb_id: kbId || "",
 		stats: {
 			total_files: Object.keys(filesMetadata).length,
 			total_chunks: chunks.length,

package/dist/index.js

@@ -6,7 +6,7 @@ import { KnowledgeGraphService } from "./kg-service.js";
 const plugin = {
 	id: "knowhere-claw",
 	name: "Knowhere",
-	description: "Knowhere document ingestion and direct stored-result access for OpenClaw.",
+	description: "Knowhere document ingestion, job management, and knowledge graph tools for OpenClaw.",
 	configSchema: knowherePluginConfigSchema,
 	register(api) {
 		const config = resolveKnowhereConfig(api);
@@ -41,12 +41,6 @@ const plugin = {
 			"knowhere_list_jobs",
 			"knowhere_get_job_status",
 			"knowhere_import_completed_job",
-			"knowhere_grep",
-			"knowhere_read_result_file",
-			"knowhere_preview_document",
-			"knowhere_list_documents",
-			"knowhere_remove_document",
-			"knowhere_clear_scope",
 			"knowhere_set_api_key",
 			"knowhere_kg_list",
 			"knowhere_kg_query"

package/dist/kg-service.js

@@ -1,3 +1,4 @@
+import { resolveStoredKnowhereResultRoot } from "./parser.js";
 import { buildConnections, init_connect_builder } from "./connect-builder.js";
 import { buildKnowledgeGraph } from "./graph-builder.js";
 import path from "node:path";
@@ -143,7 +144,8 @@ var KnowledgeGraphService = class {
 		const kbPath = await this.ensureKbDirectory(params.kbId);
 		const docDir = path.join(kbPath, params.docId);
 		await fs.ensureDir(docDir);
-		await fs.copy(params.sourcePath, docDir, { overwrite: true });
+		const sourceResultRoot = await resolveStoredKnowhereResultRoot(params.sourcePath);
+		await fs.copy(sourceResultRoot, docDir, { overwrite: true });
 		const keywordsPath = path.join(docDir, "keywords.json");
 		await fs.writeJSON(keywordsPath, params.keywords, { spaces: 2 });
 		const metadataPath = path.join(docDir, "metadata.json");
@@ -185,7 +187,10 @@ var KnowledgeGraphService = class {
 				const chunksPath = path.join(kbPath, docDir, "chunks.json");
 				if (await fs.pathExists(chunksPath)) {
 					const chunksData = await fs.readJSON(chunksPath);
-					if (chunksData.chunks && Array.isArray(chunksData.chunks)) allChunks.push(...chunksData.chunks);
+					if (chunksData.chunks && Array.isArray(chunksData.chunks)) allChunks.push(...chunksData.chunks.map((c) => ({
+						...c,
+						fileKey: docDir
+					})));
 				}
 			}
 			if (allChunks.length === 0) {
@@ -198,7 +203,7 @@ var KnowledgeGraphService = class {
 			const chunkStatsPath = path.join(kbPath, "chunk_stats.json");
 			let chunkStats = {};
 			if (await fs.pathExists(chunkStatsPath)) chunkStats = await fs.readJSON(chunkStatsPath);
-			const knowledgeGraph = buildKnowledgeGraph(allChunks, connections, chunkStats, this.jiebaInitialized, this.logger);
+			const knowledgeGraph = buildKnowledgeGraph(allChunks, connections, chunkStats, this.jiebaInitialized, this.logger, kbId);
 			const graphFile = path.join(kbPath, "knowledge_graph.json");
 			await fs.writeJSON(graphFile, knowledgeGraph, { spaces: 2 });
 			this.logger.info(`Knowledge graph saved to ${graphFile}`);

package/dist/parser.d.ts

@@ -1,16 +1,12 @@
-import type { KnowhereDownloadedResult, KnowhereManifest, KnowhereParseResult, KnowhereStatistics, StoredBrowseIndex, StoredChunk } from "./types";
+import type { KnowhereDownloadedResult, KnowhereManifest, KnowhereStatistics } from "./types";
 type KnowhereStoredResultSummary = {
     manifest: KnowhereManifest;
     chunkCount: number;
     statistics: KnowhereStatistics;
 };
-export declare const STORED_BROWSE_INDEX_VERSION = 2;
 export declare function resolveResultEntryPath(rootDir: string, entryPath: string): string;
-export declare function buildStoredPathPrefixes(storedPath: string): string[];
-export declare function isStoredBrowseIndex(value: unknown): value is StoredBrowseIndex;
-export declare function buildStoredBrowseIndex(resultDir: string, manifest: KnowhereManifest, chunks: StoredChunk[]): Promise<StoredBrowseIndex>;
 export declare function extractKnowhereResultArchive(downloadedResult: KnowhereDownloadedResult, targetDir: string): Promise<void>;
-export declare function readStoredKnowhereResultSummary(resultDir: string): Promise<KnowhereStoredResultSummary>;
-export declare function readStoredKnowhereResultContent(resultDir: string): Promise<Omit<KnowhereParseResult, "browseIndex">>;
-export declare function readStoredKnowhereParseResult(resultDir: string): Promise<KnowhereParseResult>;
+export declare function resolveStoredKnowhereResultRoot(documentDir: string): Promise<string>;
+export declare function resolveStoredKnowhereArtifactPath(documentDir: string, entryPath: string): Promise<string>;
+export declare function readStoredKnowhereResultSummary(documentDir: string): Promise<KnowhereStoredResultSummary>;
 export {};

package/dist/parser.js

@@ -3,11 +3,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { strFromU8, unzipSync } from "fflate";
+//#region src/parser.ts
 const CHUNKS_FILE_NAME = "chunks.json";
-const FULL_MARKDOWN_FILE_NAME = "full.md";
-const HIERARCHY_FILE_NAME = "hierarchy.json";
-const HIERARCHY_VIEW_FILE_NAME = "hierarchy_view.html";
-const KB_CSV_FILE_NAME = "kb.csv";
+const LEGACY_RESULT_DIRECTORY_NAME = "result";
 const MANIFEST_FILE_NAME = "manifest.json";
 function readZipText(entries, fileName) {
 	const entry = entries[fileName];
@@ -16,6 +14,15 @@ function readZipText(entries, fileName) {
 async function ensureDir(targetPath) {
 	await fs.mkdir(targetPath, { recursive: true });
 }
+async function pathExists(targetPath) {
+	try {
+		await fs.access(targetPath);
+		return true;
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
 async function readTextFile(targetPath) {
 	try {
 		return await fs.readFile(targetPath, "utf-8");
@@ -39,36 +46,6 @@ function resolveResultEntryPath(rootDir, entryPath) {
 function normalizeRelativePath(value) {
 	return value.replace(/\\/g, "/").replace(/^\/+/, "");
 }
-function normalizeStoredPath(value) {
-	if (typeof value !== "string") return null;
-	return value.trim() || null;
-}
-function readChunkNumber(rawChunk, metadata, key) {
-	const metadataValue = metadata[key];
-	if (typeof metadataValue === "number" && Number.isFinite(metadataValue)) return metadataValue;
-	const rawValue = rawChunk[key];
-	if (typeof rawValue === "number" && Number.isFinite(rawValue)) return rawValue;
-	return null;
-}
-function readChunkStringArray(rawChunk, metadata, key) {
-	const metadataValue = metadata[key];
-	if (Array.isArray(metadataValue)) return metadataValue.filter((entry) => typeof entry === "string");
-	const rawValue = rawChunk[key];
-	if (Array.isArray(rawValue)) return rawValue.filter((entry) => typeof entry === "string");
-	return [];
-}
-function readChunkArray(rawChunk, metadata, key) {
-	const metadataValue = metadata[key];
-	if (Array.isArray(metadataValue)) return metadataValue;
-	const rawValue = rawChunk[key];
-	if (Array.isArray(rawValue)) return rawValue;
-	return [];
-}
-function extractAssetFilePath(rawChunk, metadata) {
-	const candidates = [rawChunk.file_path, metadata.file_path];
-	for (const candidate of candidates) if (typeof candidate === "string" && candidate.trim()) return normalizeRelativePath(candidate.trim());
-	return null;
-}
 function parseRawChunks(value) {
 	if (Array.isArray(value)) return value.filter((entry) => isRecord(entry));
 	if (isRecord(value) && Array.isArray(value.chunks)) return value.chunks.filter((entry) => isRecord(entry));
@@ -77,24 +54,6 @@ function parseRawChunks(value) {
 function parseManifest(value) {
 	return isRecord(value) ? value : {};
 }
-function buildChunk(rawChunk) {
-	const metadata = isRecord(rawChunk.metadata) ? rawChunk.metadata : {};
-	const type = rawChunk.type === "image" || rawChunk.type === "table" || rawChunk.type === "text" ? rawChunk.type : "text";
-	return {
-		chunkId: typeof rawChunk.chunk_id === "string" ? rawChunk.chunk_id : "",
-		type,
-		path: normalizeStoredPath(rawChunk.path),
-		summary: typeof metadata.summary === "string" ? metadata.summary : typeof rawChunk.summary === "string" ? rawChunk.summary : "",
-		content: typeof rawChunk.content === "string" ? rawChunk.content : "",
-		tokens: readChunkNumber(rawChunk, metadata, "tokens"),
-		keywords: readChunkStringArray(rawChunk, metadata, "keywords"),
-		relationships: readChunkArray(rawChunk, metadata, "relationships"),
-		metadata,
-		assetFilePath: extractAssetFilePath(rawChunk, metadata),
-		originalName: typeof metadata.original_name === "string" ? metadata.original_name : typeof rawChunk.original_name === "string" ? rawChunk.original_name : null,
-		tableType: typeof metadata.table_type === "string" ? metadata.table_type : typeof rawChunk.table_type === "string" ? rawChunk.table_type : null
-	};
-}
 function normalizeStatistics(manifest, rawChunks) {
 	if (manifest.statistics) return manifest.statistics;
 	return {
@@ -110,185 +69,6 @@ function validateKnowhereResultChecksum(zipBuffer, manifest) {
 	if (typeof checksum !== "string" || !checksum) return;
 	if (createHash("sha256").update(zipBuffer).digest("hex") !== checksum) throw new Error("Knowhere result ZIP checksum mismatch.");
 }
-function tokenizeStoredPath(storedPath) {
-	const slashSegments = storedPath.split("/").map((segment) => segment.trim()).filter(Boolean);
-	const tokens = [];
-	for (const slashSegment of slashSegments) {
-		const arrowSegments = slashSegment.split("-->").map((segment) => segment.trim()).filter(Boolean);
-		if (arrowSegments.length === 0) continue;
-		tokens.push({
-			delimiter: tokens.length === 0 ? null : "/",
-			segment: arrowSegments[0] || ""
-		});
-		for (const arrowSegment of arrowSegments.slice(1)) tokens.push({
-			delimiter: "-->",
-			segment: arrowSegment
-		});
-	}
-	return tokens;
-}
-function buildStoredPathPrefixes(storedPath) {
-	const tokens = tokenizeStoredPath(storedPath);
-	const prefixes = [];
-	let currentPath = "";
-	for (const token of tokens) {
-		currentPath = token.delimiter ? `${currentPath}${token.delimiter}${token.segment}` : token.segment;
-		prefixes.push(currentPath);
-	}
-	return prefixes;
-}
-function ensurePathAccumulator(accumulators, pathValue, parentPath, depth) {
-	const existing = accumulators.get(pathValue);
-	if (existing) {
-		if (parentPath && !existing.parentPath) existing.parentPath = parentPath;
-		return existing;
-	}
-	const next = {
-		childPaths: /* @__PURE__ */ new Set(),
-		chunkCount: 0,
-		chunkIds: [],
-		depth,
-		directChunkCount: 0,
-		imageChunkCount: 0,
-		parentPath,
-		path: pathValue,
-		tableChunkCount: 0,
-		textChunkCount: 0
-	};
-	accumulators.set(pathValue, next);
-	return next;
-}
-function incrementPathCounters(accumulator, chunkType) {
-	accumulator.chunkCount += 1;
-	if (chunkType === "image") {
-		accumulator.imageChunkCount += 1;
-		return;
-	}
-	if (chunkType === "table") {
-		accumulator.tableChunkCount += 1;
-		return;
-	}
-	accumulator.textChunkCount += 1;
-}
-function buildPathRecords(chunks) {
-	const accumulators = /* @__PURE__ */ new Map();
-	for (const chunk of chunks) {
-		if (!chunk.path) continue;
-		const prefixes = buildStoredPathPrefixes(chunk.path);
-		for (const [index, prefix] of prefixes.entries()) {
-			const parentPath = index > 0 ? prefixes[index - 1] || null : null;
-			const accumulator = ensurePathAccumulator(accumulators, prefix, parentPath, index + 1);
-			incrementPathCounters(accumulator, chunk.type);
-			if (parentPath) ensurePathAccumulator(accumulators, parentPath, index > 1 ? prefixes[index - 2] || null : null, index).childPaths.add(prefix);
-			if (index === prefixes.length - 1) {
-				accumulator.directChunkCount += 1;
-				if (chunk.chunkId) accumulator.chunkIds.push(chunk.chunkId);
-			}
-		}
-	}
-	return [...accumulators.values()].sort((left, right) => left.depth - right.depth || left.path.localeCompare(right.path)).map((entry) => ({
-		path: entry.path,
-		parentPath: entry.parentPath,
-		depth: entry.depth,
-		childPaths: [...entry.childPaths].sort((left, right) => left.localeCompare(right)),
-		chunkIds: [...entry.chunkIds],
-		directChunkCount: entry.directChunkCount,
-		chunkCount: entry.chunkCount,
-		textChunkCount: entry.textChunkCount,
-		imageChunkCount: entry.imageChunkCount,
-		tableChunkCount: entry.tableChunkCount
-	}));
-}
-function readManifestAssetEntries(manifest, key) {
-	const rawEntries = (isRecord(manifest.files) ? manifest.files : {})[key];
-	if (!Array.isArray(rawEntries)) return [];
-	return rawEntries.filter((entry) => isRecord(entry));
-}
-function buildResultFileChunkLookup(manifest, chunks) {
-	const entries = /* @__PURE__ */ new Map();
-	for (const key of ["images", "tables"]) {
-		const assetEntries = readManifestAssetEntries(manifest, key);
-		for (const entry of assetEntries) {
-			const filePath = typeof entry.file_path === "string" && entry.file_path.trim() ? normalizeRelativePath(entry.file_path.trim()) : null;
-			if (!filePath) continue;
-			entries.set(filePath, {
-				chunkId: typeof entry.id === "string" ? entry.id : null,
-				format: typeof entry.format === "string" ? entry.format : null
-			});
-		}
-	}
-	for (const chunk of chunks) {
-		if (!chunk.assetFilePath || entries.has(chunk.assetFilePath)) continue;
-		entries.set(chunk.assetFilePath, {
-			chunkId: chunk.chunkId || null,
-			format: null
-		});
-	}
-	return entries;
-}
-function inferResultFileKind(relativePath) {
-	if (relativePath === MANIFEST_FILE_NAME) return "manifest";
-	if (relativePath === CHUNKS_FILE_NAME) return "chunks";
-	if (relativePath === FULL_MARKDOWN_FILE_NAME) return "fullMarkdown";
-	if (relativePath === KB_CSV_FILE_NAME) return "kbCsv";
-	if (relativePath === HIERARCHY_FILE_NAME) return "hierarchy";
-	if (relativePath === HIERARCHY_VIEW_FILE_NAME) return "hierarchyView";
-	if (relativePath.startsWith("images/")) return "image";
-	if (relativePath.startsWith("tables/")) return "table";
-	return "other";
-}
-function inferResultFileFormat(relativePath) {
-	return path.posix.extname(relativePath).replace(/^\./, "").trim() || null;
-}
-function isStringArray(value) {
-	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
-}
-function isStoredBrowseIndex(value) {
-	if (!isRecord(value)) return false;
-	if (value.version !== 2) return false;
-	if (!isStringArray(value.chunkOrder)) return false;
-	if (!Array.isArray(value.paths) || !Array.isArray(value.resultFiles)) return false;
-	if (!value.paths.every((entry) => isRecord(entry) && typeof entry.path === "string" && (entry.parentPath === null || typeof entry.parentPath === "string") && typeof entry.depth === "number" && Number.isFinite(entry.depth) && isStringArray(entry.childPaths) && isStringArray(entry.chunkIds) && typeof entry.directChunkCount === "number" && typeof entry.chunkCount === "number" && typeof entry.textChunkCount === "number" && typeof entry.imageChunkCount === "number" && typeof entry.tableChunkCount === "number")) return false;
-	return value.resultFiles.every((entry) => isRecord(entry) && typeof entry.relativePath === "string" && typeof entry.kind === "string" && (entry.chunkId === null || typeof entry.chunkId === "string") && (entry.format === null || typeof entry.format === "string") && (entry.sizeBytes === null || typeof entry.sizeBytes === "number" && Number.isFinite(entry.sizeBytes)));
-}
-async function listResultFiles(rootDir, currentDir = rootDir) {
-	const entries = await fs.readdir(currentDir, { withFileTypes: true });
-	const files = [];
-	for (const entry of entries) {
-		const absolutePath = path.join(currentDir, entry.name);
-		if (entry.isDirectory()) {
-			files.push(...await listResultFiles(rootDir, absolutePath));
-			continue;
-		}
-		if (!entry.isFile()) continue;
-		files.push(normalizeRelativePath(path.relative(rootDir, absolutePath)));
-	}
-	return files.sort((left, right) => left.localeCompare(right));
-}
-async function buildResultFileRecords(resultDir, manifest, chunks) {
-	const lookup = buildResultFileChunkLookup(manifest, chunks);
-	const relativePaths = await listResultFiles(resultDir);
-	return Promise.all(relativePaths.map(async (relativePath) => {
-		const absolutePath = resolveResultEntryPath(resultDir, relativePath);
-		const stats = await fs.stat(absolutePath);
-		const manifestEntry = lookup.get(relativePath);
-		return {
-			relativePath,
-			kind: inferResultFileKind(relativePath),
-			chunkId: manifestEntry?.chunkId ?? null,
-			format: manifestEntry?.format ?? inferResultFileFormat(relativePath),
-			sizeBytes: stats.isFile() ? stats.size : null
-		};
-	}));
-}
-async function buildStoredBrowseIndex(resultDir, manifest, chunks) {
-	return {
-		version: 2,
-		paths: buildPathRecords(chunks),
-		chunkOrder: chunks.map((chunk) => chunk.chunkId).filter((chunkId) => chunkId.length > 0),
-		resultFiles: await buildResultFileRecords(resultDir, manifest, chunks)
-	};
-}
 async function extractKnowhereResultArchive(downloadedResult, targetDir) {
 	const zipBuffer = Buffer.isBuffer(downloadedResult.zipBytes) ? downloadedResult.zipBytes : Buffer.from(downloadedResult.zipBytes);
 	const entries = unzipSync(new Uint8Array(zipBuffer));
@@ -302,22 +82,24 @@ async function extractKnowhereResultArchive(downloadedResult, targetDir) {
 		await fs.writeFile(outputPath, entryBytes);
 	}
 }
-async function readStoredKnowhereResultSummary(resultDir) {
-	const manifest = parseManifest(await readJsonFile(path.join(resultDir, MANIFEST_FILE_NAME)));
-	const rawChunks = parseRawChunks(await readJsonFile(path.join(resultDir, CHUNKS_FILE_NAME)));
+async function resolveStoredKnowhereResultRoot(documentDir) {
+	if (await pathExists(path.join(documentDir, MANIFEST_FILE_NAME))) return documentDir;
+	const legacyResultDir = path.join(documentDir, LEGACY_RESULT_DIRECTORY_NAME);
+	if (await pathExists(path.join(legacyResultDir, MANIFEST_FILE_NAME))) return legacyResultDir;
+	return documentDir;
+}
+async function resolveStoredKnowhereArtifactPath(documentDir, entryPath) {
+	return resolveResultEntryPath(await resolveStoredKnowhereResultRoot(documentDir), entryPath);
+}
+async function readStoredKnowhereResultSummary(documentDir) {
+	const resultRoot = await resolveStoredKnowhereResultRoot(documentDir);
+	const manifest = parseManifest(await readJsonFile(path.join(resultRoot, MANIFEST_FILE_NAME)));
+	const rawChunks = parseRawChunks(await readJsonFile(path.join(resultRoot, CHUNKS_FILE_NAME)));
 	return {
 		manifest,
 		chunkCount: rawChunks.length,
 		statistics: normalizeStatistics(manifest, rawChunks)
 	};
 }
-async function readStoredKnowhereResultContent(resultDir) {
-	return {
-		manifest: parseManifest(await readJsonFile(path.join(resultDir, MANIFEST_FILE_NAME))),
-		chunks: parseRawChunks(await readJsonFile(path.join(resultDir, CHUNKS_FILE_NAME))).map((rawChunk) => buildChunk(rawChunk)),
-		fullMarkdown: await readTextFile(path.join(resultDir, FULL_MARKDOWN_FILE_NAME)) || "",
-		hierarchy: await readJsonFile(path.join(resultDir, HIERARCHY_FILE_NAME))
-	};
-}
 //#endregion
-export { buildStoredBrowseIndex, extractKnowhereResultArchive, isStoredBrowseIndex, readStoredKnowhereResultContent, readStoredKnowhereResultSummary, resolveResultEntryPath };
+export { extractKnowhereResultArchive, readStoredKnowhereResultSummary, resolveStoredKnowhereArtifactPath, resolveStoredKnowhereResultRoot };

package/dist/store.d.ts

@@ -1,10 +1,10 @@
-import type { ChannelRouteRecord, KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentPayload, StoredDocumentRecord } from "./types";
+import type { ChannelRouteRecord, KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentMetadata, StoredDocumentRecord } from "./types";
+type StoredDocumentScopePaths = Pick<KnowhereScope, "documentsDir" | "metadataDir">;
 export declare class KnowhereStore {
     private readonly rootDir;
     private readonly scopeMode;
     private readonly logger;
     private readonly indexCache;
-    private readonly documentPayloadCache;
     private readonly scopeAccessChains;
     private readonly scopeKeyAliases;
     private readonly sessionScopeKeysBySessionId;
@@ -48,14 +48,8 @@ export declare class KnowhereStore {
         sessionKey?: string;
         sessionId?: string;
     }): KnowhereScope;
+    readDocumentMetadata(scope: StoredDocumentScopePaths, docId: string): Promise<StoredDocumentMetadata | null>;
     listDocuments(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
-    loadDocumentPayload(scope: KnowhereScope, docId: string): Promise<StoredDocumentPayload | null>;
-    getResultFileAbsolutePath(scope: KnowhereScope, docId: string, relativePath: string): string;
-    readResultFile(scope: KnowhereScope, docId: string, relativePath: string): Promise<{
-        document: StoredDocumentRecord;
-        relativePath: string;
-        text: string | null;
-    } | null>;
     saveDownloadedDocument(scope: KnowhereScope, payload: SaveStoredDocumentPayload, options?: {
         overwrite?: boolean;
     }): Promise<StoredDocumentRecord>;
@@ -65,11 +59,6 @@ export declare class KnowhereStore {
     private persistIndex;
     private runWithScopeAccessLock;
     private removeDocumentArtifacts;
-    private buildDocumentPayloadCacheKey;
-    private touchDocumentPayloadCache;
-    private deleteDocumentPayloadCache;
-    private deleteScopeDocumentPayloadCaches;
-    private loadOrBuildBrowseIndex;
     private buildRouteKey;
     private ensureRoutesLoaded;
     private persistRoutes;
@@ -77,3 +66,4 @@ export declare class KnowhereStore {
     private resolveKnownScopeKey;
     private rebuildIndex;
 }
+export {};