@ontos-ai/knowhere-claw 0.2.4 → 0.2.6

package/dist/agent-hooks.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { StringRecord } from "./types";
+export declare function registerAgentHooks(api: OpenClawPluginApi, rawConfig: StringRecord): void;

package/dist/agent-hooks.js

@@ -0,0 +1,46 @@
+import { isRecord } from "./types.js";
+//#region src/agent-hooks.ts
+const KNOWHERE_PROMPT_CONTEXT = [
+	"## 🔧 Knowhere Plugin Guidance",
+	"",
+	"### File Ingestion",
+	"When the user sends a file or attachment, or asks to parse/ingest a document,",
+	"**always** use `knowhere_ingest_document` to process it.",
+	"- If a `[media attached: ...]` marker is present, the file is already on disk — use the `filePath` parameter.",
+	"- If the file is in the cloud (e.g. Feishu Drive), first obtain the download URL via the appropriate channel tool, then use the `url` parameter.",
+	"- Refer to your **knowhere_memory** skill for the complete step-by-step workflow.",
+	"",
+	"### Knowledge Retrieval",
+	"When answering questions about documents or the knowledge base:",
+	"- ✅ Use `knowhere_get_map`, `knowhere_get_structure`, `knowhere_read_chunks`, `knowhere_kg_query`",
+	"- ❌ Do NOT use `exec` or shell commands to read files inside `~/.knowhere/`"
+].join("\n");
+const KNOWHERE_DIR_PATTERN = ".knowhere";
+const BLOCK_REASON = "Do not use exec to read .knowhere/ directly. Use knowhere retrieval tools instead: knowhere_get_map, knowhere_get_structure, knowhere_read_chunks, knowhere_kg_query.";
+function resolveAgentHooksConfig(raw) {
+	const section = isRecord(raw.agentHooks) ? raw.agentHooks : {};
+	return { enabled: typeof section.enabled === "boolean" ? section.enabled : true };
+}
+function registerAgentHooks(api, rawConfig) {
+	if (!resolveAgentHooksConfig(rawConfig).enabled) {
+		api.logger.info("knowhere: agent hooks disabled via config");
+		return;
+	}
+	api.on("before_prompt_build", async () => {
+		return { prependContext: KNOWHERE_PROMPT_CONTEXT };
+	});
+	api.on("before_tool_call", async (event) => {
+		if (event.toolName !== "exec") return;
+		const params = isRecord(event.params) ? event.params : {};
+		if ((typeof params.command === "string" ? params.command : typeof params.cmd === "string" ? params.cmd : "").includes(KNOWHERE_DIR_PATTERN)) {
+			api.logger.info(`knowhere: blocked exec touching ${KNOWHERE_DIR_PATTERN}`);
+			return {
+				block: true,
+				blockReason: BLOCK_REASON
+			};
+		}
+	});
+	api.logger.info("knowhere: agent hooks registered (prompt context + tool governance)");
+}
+//#endregion
+export { registerAgentHooks };

package/dist/client.js

@@ -1,8 +1,8 @@
 import { isRecord } from "./types.js";
 import { formatErrorMessage } from "./error-message.js";
+import { openAsBlob } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { openAsBlob } from "node:fs";
 import { Knowhere } from "@knowhere-ai/sdk";
 //#region src/client.ts
 const RETRYABLE_STATUS_CODES = new Set([

package/dist/config.d.ts

@@ -2,6 +2,14 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import type { JsonSchemaObject, ResolvedKnowhereConfig, StringRecord, KnowledgeGraphConfig } from "./types";
 export declare const DEFAULT_BASE_URL = "https://api.knowhereto.ai";
 export declare const knowherePluginConfigSchema: JsonSchemaObject;
+/**
+ * Return the effective plugin config object, merging the persisted
+ * resolved-config when the live pluginConfig is missing explicit fields
+ * (i.e. in agent subprocesses).  Both `resolveKnowhereConfig` and
+ * `resolveKnowledgeGraphConfig` should read from this merged result so
+ * that subprocess instances inherit the gateway's full configuration.
+ */
+export declare function resolveEffectivePluginConfig(api: OpenClawPluginApi): StringRecord;
 export declare function resolveKnowhereConfig(api: OpenClawPluginApi): ResolvedKnowhereConfig;
 export declare const API_KEY_URL = "https://knowhereto.ai/api-keys";
 export declare const PURCHASE_CREDITS_URL = "https://knowhereto.ai/usage?buy=true";

package/dist/config.js

@@ -1,4 +1,5 @@
 import { isRecord } from "./types.js";
+import { readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/config.ts
@@ -147,36 +148,83 @@ function readScopeMode(raw) {
 	if (value === "session" || value === "agent" || value === "global") return value;
 	return KNOWHERE_PLUGIN_DEFAULTS.scopeMode;
 }
+const RESOLVED_CONFIG_STATE_FILE = "resolved-config.json";
+function readPersistedResolvedConfigSync(stateDir) {
+	const filePath = path.join(stateDir, RESOLVED_CONFIG_STATE_FILE);
+	try {
+		const raw = readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (isRecord(parsed)) return parsed;
+		return null;
+	} catch {
+		return null;
+	}
+}
+async function persistResolvedConfig(stateDir, config) {
+	await fs.mkdir(stateDir, { recursive: true });
+	const filePath = path.join(stateDir, RESOLVED_CONFIG_STATE_FILE);
+	await fs.writeFile(filePath, JSON.stringify(config, null, 2), "utf-8");
+}
+function hasExplicitPluginConfig(raw) {
+	return Boolean(readString(raw, "scopeMode") || readString(raw, "storageDir"));
+}
+/**
+* Return the effective plugin config object, merging the persisted
+* resolved-config when the live pluginConfig is missing explicit fields
+* (i.e. in agent subprocesses).  Both `resolveKnowhereConfig` and
+* `resolveKnowledgeGraphConfig` should read from this merged result so
+* that subprocess instances inherit the gateway's full configuration.
+*/
+function resolveEffectivePluginConfig(api) {
+	const raw = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+	const stateDir = api.runtime.state.resolveStateDir();
+	if (!hasExplicitPluginConfig(raw)) {
+		const persisted = readPersistedResolvedConfigSync(stateDir);
+		if (persisted) return {
+			...persisted,
+			...raw
+		};
+	}
+	return raw;
+}
 function resolveKnowhereConfig(api) {
 	const raw = isRecord(api.pluginConfig) ? api.pluginConfig : {};
 	const stateDir = api.runtime.state.resolveStateDir();
-	const storageDirRaw = readString(raw, "storageDir");
-	return {
+	const hasExplicit = hasExplicitPluginConfig(raw);
+	const effective = resolveEffectivePluginConfig(api);
+	const storageDirRaw = readString(effective, "storageDir");
+	const config = {
 		apiKey: readString(raw, "apiKey") || process.env.KNOWHERE_API_KEY || "",
 		baseUrl: readString(raw, "baseUrl") || process.env.KNOWHERE_BASE_URL || "https://api.knowhereto.ai",
 		storageDir: storageDirRaw ? api.resolvePath(storageDirRaw) : path.join(stateDir, "plugins", api.id),
-		scopeMode: readScopeMode(raw),
-		pollIntervalMs: readNumber(raw, "pollIntervalMs", KNOWHERE_PLUGIN_DEFAULTS.pollIntervalMs, {
+		scopeMode: readScopeMode(effective),
+		pollIntervalMs: readNumber(effective, "pollIntervalMs", KNOWHERE_PLUGIN_DEFAULTS.pollIntervalMs, {
 			min: 1e3,
 			max: 6e4,
 			integer: true
 		}),
-		pollTimeoutMs: readNumber(raw, "pollTimeoutMs", KNOWHERE_PLUGIN_DEFAULTS.pollTimeoutMs, {
+		pollTimeoutMs: readNumber(effective, "pollTimeoutMs", KNOWHERE_PLUGIN_DEFAULTS.pollTimeoutMs, {
 			min: 1e4,
 			max: 72e5,
 			integer: true
 		}),
-		requestTimeoutMs: readNumber(raw, "requestTimeoutMs", KNOWHERE_PLUGIN_DEFAULTS.requestTimeoutMs, {
+		requestTimeoutMs: readNumber(effective, "requestTimeoutMs", KNOWHERE_PLUGIN_DEFAULTS.requestTimeoutMs, {
 			min: 1e3,
 			max: 3e5,
 			integer: true
 		}),
-		uploadTimeoutMs: readNumber(raw, "uploadTimeoutMs", KNOWHERE_PLUGIN_DEFAULTS.uploadTimeoutMs, {
+		uploadTimeoutMs: readNumber(effective, "uploadTimeoutMs", KNOWHERE_PLUGIN_DEFAULTS.uploadTimeoutMs, {
 			min: 1e3,
 			max: 72e5,
 			integer: true
 		})
 	};
+	if (hasExplicit) persistResolvedConfig(stateDir, {
+		scopeMode: config.scopeMode,
+		storageDir: config.storageDir,
+		knowledgeGraph: raw.knowledgeGraph
+	}).catch(() => void 0);
+	return config;
 }
 const API_KEY_URL = "https://knowhereto.ai/api-keys";
 const PURCHASE_CREDITS_URL = "https://knowhereto.ai/usage?buy=true";
@@ -257,4 +305,4 @@ function resolveKnowledgeGraphConfig(raw) {
 	};
 }
 //#endregion
-export { assertKnowhereApiKey, formatPaymentRequiredMessage, isPaymentRequiredError, knowherePluginConfigSchema, persistApiKey, readPersistedApiKey, resolveKnowhereConfig, resolveKnowledgeGraphConfig };
+export { assertKnowhereApiKey, formatPaymentRequiredMessage, isPaymentRequiredError, knowherePluginConfigSchema, persistApiKey, readPersistedApiKey, resolveEffectivePluginConfig, resolveKnowhereConfig, resolveKnowledgeGraphConfig };

package/dist/graph-builder.d.ts

@@ -62,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, kbId?: string): 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

@@ -1,12 +1,5 @@
-import * as nodejieba from "nodejieba";
 //#region src/graph-builder.ts
 /**
-* Graph Builder Module
-*
-* TypeScript implementation of knowhere-api/apps/worker/app/services/connect_builder/graph_builder.py
-* Builds file-level knowledge graphs from chunk connections with TF-IDF and importance scoring.
-*/
-/**
 * Extract file key from a chunk.
 * Prefers the explicit fileKey field; falls back to path-based extraction for backward compatibility.
 */
@@ -27,29 +20,18 @@ function extractLabel(path) {
 * Extract tokens from text using jieba
 * Equivalent to Python: _extract_tokens_from_content
 */
-function extractTokensFromContent(content, jiebaInitialized) {
-	const cleanContent = content.replace(/<[^>]*>/g, " ");
-	if (!jiebaInitialized) return cleanContent.split(/\s+/).filter((w) => w.length > 1);
-	try {
-		return nodejieba.cut(cleanContent).filter((token) => {
-			if (token.length <= 1) return false;
-			if (/^\d+$/.test(token)) return false;
-			if (/^[^\w\u4e00-\u9fa5]+$/.test(token)) return false;
-			return true;
-		});
-	} catch {
-		return cleanContent.split(/\s+/).filter((w) => w.length > 1);
-	}
+function extractTokensFromContent(content) {
+	return content.replace(/<[^>]*>/g, " ").split(/\s+/).filter((w) => w.length > 1);
 }
 /**
 * Compute TF-IDF top keywords for a file
 * Equivalent to Python: _compute_tfidf_top_keywords
 */
-function computeTfidfTopKeywords(fileChunks, allChunks, topK, jiebaInitialized) {
+function computeTfidfTopKeywords(fileChunks, allChunks, topK) {
 	if (fileChunks.length === 0) return [];
 	const fileTokens = [];
 	for (const chunk of fileChunks) {
-		const tokens = extractTokensFromContent(chunk.content, jiebaInitialized);
+		const tokens = extractTokensFromContent(chunk.content);
 		fileTokens.push(...tokens);
 	}
 	if (fileTokens.length === 0) return [];
@@ -60,7 +42,7 @@ function computeTfidfTopKeywords(fileChunks, allChunks, topK, jiebaInitialized)
 	}
 	const docFreq = /* @__PURE__ */ new Map();
 	for (const chunk of allChunks) {
-		const tokens = new Set(extractTokensFromContent(chunk.content, jiebaInitialized).map((t) => t.toLowerCase()));
+		const tokens = new Set(extractTokensFromContent(chunk.content).map((t) => t.toLowerCase()));
 		for (const token of tokens) docFreq.set(token, (docFreq.get(token) || 0) + 1);
 	}
 	const totalDocs = allChunks.length;
@@ -161,7 +143,7 @@ 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, kbId) {
+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);
@@ -178,7 +160,7 @@ function buildKnowledgeGraph(chunks, connections, chunkStats, jiebaInitialized,
 			const type = chunk.metadata.type || "text";
 			typeCount[type] = (typeCount[type] || 0) + 1;
 		}
-		const topKeywords = computeTfidfTopKeywords(fileChunks, chunks, 10, jiebaInitialized);
+		const topKeywords = computeTfidfTopKeywords(fileChunks, chunks, 10);
 		const importance = computeFileImportance(fileKey, fileChunks, chunks, chunkStats);
 		let topSummary = "";
 		for (const chunk of fileChunks) if (chunk.metadata.summary && typeof chunk.metadata.summary === "string") {

package/dist/index.js

@@ -1,4 +1,5 @@
-import { knowherePluginConfigSchema, readPersistedApiKey, resolveKnowhereConfig, resolveKnowledgeGraphConfig } from "./config.js";
+import { registerAgentHooks } from "./agent-hooks.js";
+import { knowherePluginConfigSchema, readPersistedApiKey, resolveEffectivePluginConfig, resolveKnowhereConfig, resolveKnowledgeGraphConfig } from "./config.js";
 import { KnowhereStore } from "./store.js";
 import { createKnowhereToolFactory } from "./tools.js";
 import { KnowledgeGraphService } from "./kg-service.js";
@@ -10,7 +11,9 @@ const plugin = {
 	configSchema: knowherePluginConfigSchema,
 	register(api) {
 		const config = resolveKnowhereConfig(api);
-		const kgConfig = resolveKnowledgeGraphConfig(api.pluginConfig && typeof api.pluginConfig === "object" ? api.pluginConfig : {});
+		const effectiveRaw = resolveEffectivePluginConfig(api);
+		const kgConfig = resolveKnowledgeGraphConfig(effectiveRaw);
+		registerAgentHooks(api, effectiveRaw);
 		const store = new KnowhereStore({
 			rootDir: config.storageDir,
 			scopeMode: config.scopeMode,
@@ -43,7 +46,11 @@ const plugin = {
 			"knowhere_import_completed_job",
 			"knowhere_set_api_key",
 			"knowhere_kg_list",
-			"knowhere_kg_query"
+			"knowhere_kg_query",
+			"knowhere_get_map",
+			"knowhere_get_structure",
+			"knowhere_read_chunks",
+			"knowhere_discover_files"
 		] });
 	}
 };

package/dist/kg-service.d.ts

@@ -9,11 +9,9 @@ export declare class KnowledgeGraphService {
     private readonly logger;
     private degradationMode;
     private buildQueues;
-    private jiebaInitialized;
     constructor(params: KnowledgeGraphServiceParams);
     initialize(): Promise<void>;
     private checkPythonEnvironment;
-    private initializeJieba;
     extractKeywords(text: string, topK?: number): Promise<string[]>;
     resolveKbId(context: ToolRuntimeContext): string | null;
     getKbPath(kbId: string): string;

package/dist/kg-service.js

@@ -2,10 +2,9 @@ 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";
+import os from "node:os";
 import { spawn } from "node:child_process";
 import fs from "fs-extra";
-import os from "node:os";
-import * as nodejieba from "nodejieba";
 //#region src/kg-service.ts
 init_connect_builder();
 const DEFAULT_CONNECT_CONFIG = {
@@ -26,18 +25,11 @@ const DEFAULT_KG_CONFIG = {
 function formatUnknownError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
-function extractKeywordText(item) {
-	if (typeof item === "string") return item;
-	if (typeof item === "number" || typeof item === "boolean" || typeof item === "bigint") return String(item);
-	if (typeof item === "object" && item !== null && "word" in item && typeof item.word === "string") return item.word;
-	return null;
-}
 var KnowledgeGraphService = class {
 	config;
 	logger;
 	degradationMode = "full";
 	buildQueues = /* @__PURE__ */ new Map();
-	jiebaInitialized = false;
 	constructor(params) {
 		this.config = {
 			...DEFAULT_KG_CONFIG,
@@ -58,18 +50,12 @@ var KnowledgeGraphService = class {
 		}
 		try {
 			await this.checkPythonEnvironment();
-			await this.initializeJieba();
 			this.degradationMode = "full";
 			this.logger.info("Knowledge graph service initialized in full mode");
 		} catch (error) {
 			this.logger.warn(`Knowledge graph initialization failed: ${error instanceof Error ? error.message : String(error)}`);
-			if (error.code === "PYTHON_MISSING") {
-				this.degradationMode = "disabled";
-				this.logger.warn("Python not found, knowledge graph disabled");
-			} else if (error.code === "NODEJIEBA_MISSING") {
-				this.degradationMode = "basic";
-				this.logger.warn("Nodejieba missing, using basic tokenization");
-			} else this.degradationMode = "disabled";
+			this.degradationMode = "disabled";
+			this.logger.warn("Python not found, knowledge graph disabled");
 		}
 	}
 	async checkPythonEnvironment() {
@@ -92,30 +78,8 @@ var KnowledgeGraphService = class {
 			});
 		});
 	}
-	async initializeJieba() {
-		try {
-			nodejieba.load();
-			this.jiebaInitialized = true;
-			this.logger.info("Nodejieba initialized successfully");
-		} catch {
-			const err = /* @__PURE__ */ new Error("Failed to initialize nodejieba");
-			err.code = "NODEJIEBA_MISSING";
-			throw err;
-		}
-	}
 	async extractKeywords(text, topK = 20) {
 		if (this.degradationMode === "disabled") return [];
-		if (this.degradationMode === "full" && this.jiebaInitialized) try {
-			const rawKeywords = nodejieba.extract(text, topK);
-			return (Array.isArray(rawKeywords) ? rawKeywords : []).map((item) => extractKeywordText(item)).filter((keyword) => keyword !== null).filter((kw) => {
-				if (kw.length <= 1) return false;
-				if (/^\d+$/.test(kw)) return false;
-				return true;
-			}).slice(0, topK);
-		} catch (error) {
-			this.logger.warn(`Jieba extraction failed, falling back to basic: ${formatUnknownError(error)}`);
-			this.degradationMode = "basic";
-		}
 		return text.split(/\s+/).filter((w) => w.length > 1).slice(0, topK);
 	}
 	resolveKbId(context) {
@@ -146,8 +110,6 @@ var KnowledgeGraphService = class {
 		await fs.ensureDir(docDir);
 		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");
 		await fs.writeJSON(metadataPath, params.metadata, { spaces: 2 });
 		this.logger.info(`Document saved to knowledge base: kb=${params.kbId} doc=${params.docId}`);
@@ -176,7 +138,7 @@ var KnowledgeGraphService = class {
 			const docPath = path.join(kbPath, doc);
 			if ((await fs.stat(docPath)).isDirectory() && doc !== "knowledge_graph.json" && doc !== "chunk_stats.json" && doc !== "kb_metadata.json") docDirs.push(doc);
 		}
-		if (docDirs.length < 2) {
+		if (docDirs.length < 1) {
 			this.logger.info(`Not enough documents for graph building (need >=2, have ${docDirs.length}), skipping`);
 			return;
 		}
@@ -203,7 +165,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, kbId);
+			const knowledgeGraph = buildKnowledgeGraph(allChunks, connections, chunkStats, false, 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/tools.js

@@ -4,9 +4,12 @@ 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 crypto from "node:crypto";
+import os from "node:os";
 //#region src/tools.ts
 const TERMINAL_JOB_STATUSES = new Set([
 	"cancelled",
@@ -784,6 +787,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({
@@ -914,6 +935,673 @@ 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 [];
+}
+function t2NormalizePath(s) {
+	return s.replace(/[\uFF01-\uFF5E]/g, (ch) => String.fromCharCode(ch.charCodeAt(0) - 65248)).replace(/[\s\u3000\u00A0]+/g, "").toLowerCase();
+}
+const PLACEHOLDER_RE = /(?:IMAGE|TABLE)_([a-f0-9-]+)_(?:IMAGE|TABLE)/g;
+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 [];
+	}
+}
+/**
+* Runtime-only enrichment of chunks returned to the AI:
+* 1. Replace IMAGE_uuid_IMAGE placeholders with [📷 path] in text chunks
+* 2. Replace TABLE_uuid_TABLE placeholders with actual HTML content in text chunks
+* 3. Remove standalone table chunks that were inlined via placeholders
+* 4. Strip self-referencing placeholders from image/table chunk content & summary
+*
+* Does NOT modify chunks.json on disk.
+*/
+async function t2EnrichChunks(chunks, docDir) {
+	const rawChunks = await t2LoadRawChunks(docDir);
+	const idToRaw = /* @__PURE__ */ new Map();
+	for (const rc of rawChunks) if (rc.chunk_id) idToRaw.set(rc.chunk_id, rc);
+	const manifestPaths = /* @__PURE__ */ new Map();
+	try {
+		const manifest = JSON.parse(await fs.readFile(path.join(docDir, "manifest.json"), "utf-8"));
+		if (isRecord(manifest) && isRecord(manifest.files)) {
+			const files = manifest.files;
+			for (const entry of Array.isArray(files.images) ? files.images : []) if (typeof entry.id === "string" && typeof entry.file_path === "string") manifestPaths.set(entry.id, {
+				type: "image",
+				filePath: entry.file_path
+			});
+			for (const entry of Array.isArray(files.tables) ? files.tables : []) if (typeof entry.id === "string" && typeof entry.file_path === "string") manifestPaths.set(entry.id, {
+				type: "table",
+				filePath: entry.file_path
+			});
+		}
+	} catch {}
+	const inlinedTablePaths = /* @__PURE__ */ new Set();
+	const inlinedImagePaths = /* @__PURE__ */ new Set();
+	for (const chunk of chunks) {
+		if (!chunk.content) continue;
+		PLACEHOLDER_RE.lastIndex = 0;
+		if (PLACEHOLDER_RE.test(chunk.content)) {
+			PLACEHOLDER_RE.lastIndex = 0;
+			chunk.content = await replacePlaceholders(chunk.content, idToRaw, docDir, chunk.type === "text" ? inlinedTablePaths : void 0, chunk.type === "text" ? inlinedImagePaths : void 0, manifestPaths);
+			PLACEHOLDER_RE.lastIndex = 0;
+			if (chunk.type !== "text" && chunk.path && PLACEHOLDER_RE.test(chunk.content)) {
+				if (chunk.type === "table") try {
+					const html = await fs.readFile(path.join(docDir, chunk.path), "utf-8");
+					chunk.content = chunk.content.replace(PLACEHOLDER_RE, `\n${html.slice(0, 8e3)}\n`);
+				} catch {
+					chunk.content = chunk.content.replace(PLACEHOLDER_RE, `[📊 ${chunk.path}]`);
+				}
+				else if (chunk.type === "image") chunk.content = chunk.content.replace(PLACEHOLDER_RE, `[📷 ${chunk.path}]`);
+			}
+		}
+		if (chunk.summary) {
+			PLACEHOLDER_RE.lastIndex = 0;
+			if (PLACEHOLDER_RE.test(chunk.summary)) {
+				PLACEHOLDER_RE.lastIndex = 0;
+				chunk.summary = await replacePlaceholders(chunk.summary, idToRaw, docDir, void 0, void 0, manifestPaths);
+			}
+		}
+	}
+	chunks = chunks.filter((c) => {
+		if (c.type === "table" && inlinedTablePaths.has(c.path)) return false;
+		if (c.type === "image" && inlinedImagePaths.has(c.path)) return false;
+		return true;
+	});
+	return chunks;
+}
+async function replacePlaceholders(text, idToRaw, docDir, inlinedTablePaths, inlinedImagePaths, manifestPaths) {
+	const matches = [];
+	const re = /(?:(IMAGE|TABLE))_([a-f0-9-]+)_(?:IMAGE|TABLE)/g;
+	let m;
+	while ((m = re.exec(text)) !== null) matches.push({
+		full: m[0],
+		type: m[1],
+		id: m[2],
+		start: m.index,
+		end: m.index + m[0].length
+	});
+	if (matches.length === 0) return text;
+	const replacements = [];
+	for (const match of matches) {
+		const raw = idToRaw.get(match.id);
+		let resolvedPath = raw?.path;
+		if (!resolvedPath && manifestPaths) {
+			const mEntry = manifestPaths.get(match.id);
+			if (mEntry) resolvedPath = mEntry.filePath;
+		}
+		if (!resolvedPath) {
+			replacements.push(match.full);
+			continue;
+		}
+		if (match.type === "IMAGE") {
+			replacements.push(`[📷 ${resolvedPath}]`);
+			inlinedImagePaths?.add(resolvedPath);
+		} else {
+			const htmlPath = path.join(docDir, resolvedPath);
+			try {
+				const html = await fs.readFile(htmlPath, "utf-8");
+				replacements.push(`\n${html.slice(0, 8e3)}\n`);
+				inlinedTablePaths?.add(resolvedPath);
+			} catch {
+				const tableContent = raw?.content || "";
+				if (tableContent && tableContent.includes("<")) {
+					replacements.push(`\n${tableContent}\n`);
+					inlinedTablePaths?.add(resolvedPath);
+				} else replacements.push(`[📊 ${resolvedPath}]`);
+			}
+		}
+	}
+	let result = text;
+	for (let i = matches.length - 1; i >= 0; i--) result = result.slice(0, matches[i].start) + replacements[i] + result.slice(matches[i].end);
+	return result;
+}
+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;
+}
+async function t2StageFile(srcPath, stagingDir) {
+	await fs.mkdir(stagingDir, { recursive: true });
+	const ext = path.extname(srcPath);
+	const hash = crypto.createHash("sha1").update(srcPath).digest("hex").slice(0, 12);
+	const staged = path.join(stagingDir, `knowhere-asset-${hash}${ext}`);
+	await fs.copyFile(srcPath, staged);
+	return staged;
+}
+async function t2ResolveAssets(params) {
+	const assets = [];
+	const stagingDir = path.join(os.homedir(), ".openclaw", "knowhere-assets");
+	const processedPaths = /* @__PURE__ */ new Set();
+	let channelRoute;
+	try {
+		channelRoute = await params.store.resolveChannelRoute({ sessionKey: params.ctx.sessionKey });
+	} catch {}
+	const resolveOne = async (opts) => {
+		const absolutePath = path.join(params.docDir, opts.relativePath);
+		if (processedPaths.has(absolutePath)) return;
+		processedPaths.add(absolutePath);
+		if (opts.type === "table") try {
+			const html = await fs.readFile(absolutePath, "utf-8");
+			assets.push({
+				chunk_id: opts.chunkId,
+				type: "table",
+				relative_path: opts.relativePath,
+				summary: opts.summary.slice(0, 200),
+				mode: "table_inline",
+				html_content: html.slice(0, 8e3)
+			});
+		} catch {
+			params.api.logger.debug?.(`knowhere: t2ResolveAssets table read failed: ${absolutePath}`);
+		}
+		else try {
+			await fs.access(absolutePath);
+			const stagedPath = await t2StageFile(absolutePath, stagingDir);
+			const result = await deliverChannelMessage({
+				api: params.api,
+				operationLabel: "t2-asset-image",
+				sessionKey: params.ctx.sessionKey,
+				channelRoute,
+				text: `📷 ${opts.summary.slice(0, 100)}`,
+				mediaUrl: stagedPath,
+				mediaLocalRoots: [stagingDir]
+			});
+			assets.push({
+				chunk_id: opts.chunkId,
+				type: "image",
+				relative_path: opts.relativePath,
+				summary: opts.summary.slice(0, 200),
+				mode: result.delivered ? "image_sent" : "image_failed"
+			});
+		} catch (err) {
+			params.api.logger.debug?.(`knowhere: t2ResolveAssets image delivery failed: ${absolutePath} — ${err instanceof Error ? err.message : String(err)}`);
+		}
+	};
+	for (const chunk of params.returnedChunks) if ((chunk.type === "image" || chunk.type === "table") && chunk.path) {
+		if (chunk.type === "table" && chunk.content && !/TABLE_[a-f0-9-]+_TABLE/.test(chunk.content)) continue;
+		await resolveOne({
+			chunkId: chunk.path,
+			type: chunk.type,
+			relativePath: chunk.path,
+			summary: chunk.summary || chunk.content?.slice(0, 200) || ""
+		});
+	}
+	return assets;
+}
+function createGetMapTool(_params) {
+	return {
+		name: "knowhere_get_map",
+		label: "Knowhere Get Map",
+		description: "获取知识库全局概览。查询知识时必须先调此工具，了解有哪些文档、关键词、重要性和跨文件关联。然后用 knowhere_get_structure 查看具体文档的章节目录。重要：knowhere_read_chunks 已内置图片/表格自动投递功能，读取内容时会自动发送多媒体到用户频道。除非用户明确要求下载原始文件，否则请勿主动发送 .docx/.pdf 等文档。",
+		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 读取内容。重要：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 消耗。此工具已内置图片/表格自动投递：读取时会自动将多媒体内容发送到用户频道。除非用户明确要求下载原始文件，否则无需再用 message 发送文档。",
+		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);
+			const totalAll = chunks.length;
+			if (sectionPath) {
+				let filtered = chunks.filter((c) => c.path.includes(sectionPath));
+				if (filtered.length === 0) {
+					const normQuery = t2NormalizePath(sectionPath);
+					filtered = chunks.filter((c) => t2NormalizePath(c.path).includes(normQuery));
+				}
+				if (filtered.length === 0) {
+					const sections = [...new Set(chunks.filter((c) => c.type === "text" && c.path).map((c) => {
+						const parts = c.path.split("/");
+						return parts.length > 1 ? parts.slice(-1)[0] : c.path;
+					}))].slice(0, 30);
+					return t2JsonResult({
+						status: "no_match",
+						message: `sectionPath '${sectionPath}' 未匹配到任何切片。请检查路径或从以下章节中选择：`,
+						available_sections: sections
+					});
+				}
+				chunks = filtered;
+			} else if (totalAll > 20) {
+				const sections = [...new Set(chunks.filter((c) => c.type === "text" && c.path).map((c) => {
+					const parts = c.path.split("/");
+					return parts.length > 1 ? parts.slice(-1)[0] : c.path;
+				}))].slice(0, 30);
+				return t2JsonResult({
+					status: "too_many",
+					message: `该文档共有 ${totalAll} 个切片，请先用 knowhere_get_structure 查看目录，然后用 sectionPath 参数指定章节。`,
+					available_sections: sections
+				});
+			}
+			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 {}
+			chunks = await t2EnrichChunks(chunks, docDir);
+			let resolvedAssets = [];
+			try {
+				resolvedAssets = await t2ResolveAssets({
+					api: _params.api,
+					store: _params.store,
+					ctx: _params.ctx,
+					docDir,
+					returnedChunks: chunks
+				});
+			} catch (err) {
+				_params.api.logger.debug?.(`knowhere: read_chunks asset resolution failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			const result = {
+				status: "ok",
+				kb_id: kbId,
+				doc_name: path.basename(docDir),
+				section_path: sectionPath || null,
+				total_chunks: total,
+				returned: chunks.length,
+				truncated: total > limit,
+				chunks
+			};
+			if (resolvedAssets.length > 0) {
+				result.resolved_assets = resolvedAssets;
+				const sent = resolvedAssets.filter((a) => a.mode === "image_sent").length;
+				const tables = resolvedAssets.filter((a) => a.mode === "table_inline").length;
+				const notes = [];
+				if (sent > 0) notes.push(`${sent} 张图片已自动发送到用户频道`);
+				if (tables > 0) notes.push(`${tables} 个表格已内联为 HTML`);
+				result.asset_summary = notes.join("；");
+				result._agent_note = "上述多媒体资源（图片/表格/视频）已自动投递到用户频道，用户已经可以看到。请直接用文字回答用户的问题，不要再重复发送这些图片或表格。也不要主动发送原始文档文件（.docx/.pdf），除非用户明确要求下载原始文件。如果用户要求你分析、描述或对比图片内容，请使用 knowhere_view_image 工具传入 content 中的 [📷 path] 路径来获取图片数据进行视觉分析。";
+			}
+			return t2JsonResult(result);
+		}
+	};
+}
+function createViewImageTool(_params) {
+	return {
+		name: "knowhere_view_image",
+		label: "Knowhere View Image",
+		description: "分析知识库图片的像素内容。当 knowhere_read_chunks 返回的文本中包含 [📷 path] 标记时，可用此工具传入该 path 来获取图片的 base64 数据进行视觉分析。需要提供 kbId、docName 和 imagePath（即 [📷 ...] 中的相对路径）。",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				kbId: {
+					type: "string",
+					description: "Knowledge base ID"
+				},
+				docName: {
+					type: "string",
+					description: "Document name"
+				},
+				imagePath: {
+					type: "string",
+					description: "Image relative path from [📷 ...] marker, e.g. 'images/image-9 助力手推车.jpeg'"
+				}
+			},
+			required: [
+				"kbId",
+				"docName",
+				"imagePath"
+			]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const paramsRecord = isRecord(rawParams) ? rawParams : {};
+			const kbId = readString(paramsRecord.kbId);
+			const docName = readString(paramsRecord.docName);
+			const imagePath = readString(paramsRecord.imagePath);
+			if (!kbId || !docName || !imagePath) throw new Error("kbId, docName, and imagePath are required.");
+			const docDir = await t2FindDocDir(path.join(T2_KNOWHERE_HOME, kbId), docName);
+			if (!docDir) return textResult(`文档 '${docName}' 不存在`);
+			const absolutePath = path.join(docDir, imagePath);
+			try {
+				await fs.access(absolutePath);
+			} catch {
+				return textResult(`图片文件不存在: ${imagePath}`);
+			}
+			const base64Data = (await fs.readFile(absolutePath)).toString("base64");
+			const ext = path.extname(imagePath).toLowerCase();
+			let mediaType = "image/jpeg";
+			if (ext === ".png") mediaType = "image/png";
+			else if (ext === ".gif") mediaType = "image/gif";
+			else if (ext === ".webp") mediaType = "image/webp";
+			return {
+				content: [{
+					type: "text",
+					text: `你正在查看图片: ${imagePath}。图片数据已附在下方，请直接用你的视觉能力分析图片内容，`
+				}, {
+					type: "image_url",
+					image_url: { url: `data:${mediaType};base64,${base64Data}` }
+				}],
+				details: {}
+			};
+		}
+	};
+}
+function createDiscoverFilesTool(_params) {
+	return {
+		name: "knowhere_discover_files",
+		label: "Knowhere Discover Files",
+		description: "在所有知识库文档中搜索关键词，返回命中文件和次数。用于和 knowhere_get_map 做并集，避免遗漏相关文件。只返回文件名，不返回内容。注意：后续用 knowhere_read_chunks 读取时会自动投递图片/表格到用户频道，除非用户要求下载文件，否则无需额外发送原始文档。",
+		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({
@@ -939,6 +1627,7 @@ function createKnowhereToolFactory(params) {
 			api: params.api,
 			config: params.config,
 			store: params.store,
+			kgService: params.kgService,
 			ctx
 		}),
 		createSetApiKeyTool({
@@ -954,7 +1643,16 @@ function createKnowhereToolFactory(params) {
 			api: params.api,
 			kgService: params.kgService,
 			ctx
-		})
+		}),
+		createGetMapTool({ api: params.api }),
+		createGetStructureTool({ api: params.api }),
+		createReadChunksTool({
+			api: params.api,
+			store: params.store,
+			ctx
+		}),
+		createViewImageTool({ api: params.api }),
+		createDiscoverFilesTool({ api: params.api })
 	];
 }
 //#endregion

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Knowhere",
   "description": "Parse documents with Knowhere and expose the stored result as tool-queryable document state for OpenClaw agents.",
   "skills": ["./skills"],
-  "version": "0.2.4",
+  "version": "0.2.6",
   "uiHints": {
     "apiKey": {
       "label": "Knowhere API Key",
@@ -152,6 +152,16 @@
             }
           }
         }
+      },
+      "agentHooks": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true
+          }
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-claw",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",
@@ -40,8 +40,7 @@
   "dependencies": {
     "@knowhere-ai/sdk": "^0.1.1",
     "fflate": "^0.8.2",
-    "fs-extra": "^11.2.0",
-    "nodejieba": "^2.6.0"
+    "fs-extra": "^11.2.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",

package/skills/knowhere_memory/SKILL.md

@@ -19,28 +19,46 @@ Activate this skill when:
 
 ## Part 1: Ingesting New Documents
 
-When a file is uploaded or attached (e.g. via Telegram), the agent should parse it into the knowledge base.
+When a user sends, uploads, or mentions a file, **always** use `knowhere_ingest_document` to parse it into the knowledge base. Two delivery modes exist depending on how the file arrives:
 
-### Attachment markers
+### Mode A: Local File (Telegram, Discord, Signal, …)
 
-When a prompt contains a marker like:
+When the channel downloads the file to disk, a marker appears in the prompt:
 
 ```text
 [media attached: /absolute/path/to/file.pdf (application/pdf) | handbook.pdf]
 ```
 
-Use the exact absolute path as `filePath` and the visible filename as `fileName`.
+Use the exact absolute path from the marker:
 
-### Ingestion workflow
+```
+knowhere_ingest_document(filePath: "/absolute/path/to/file.pdf", fileName: "handbook.pdf")
+```
+
+### Mode B: Cloud File (Feishu, …)
+
+When the file stays in a cloud service (no `[media attached:]` marker):
+
+1. Use the channel's file tool to locate the file and obtain a download URL
+   - Feishu: use `feishu_drive` with `action: "list"` to find the file, then get its download URL
+   - Other cloud channels: use the equivalent tool to get a direct download URL
+2. Pass the URL to knowhere:
+
+```
+knowhere_ingest_document(url: "https://download-url-from-channel-tool/...")
+```
+
+### After Ingestion
+
+The plugin handles everything automatically:
+
+- Uploads/fetches the file for parsing
+- Polls until parsing completes
+- Downloads and extracts the result package
+- Copies parsed data to `~/.knowhere/{kbId}/`
+- Builds/updates `knowledge_graph.json`
 
-1. Call `knowhere_ingest_document` with the file path
-2. The plugin handles everything automatically:
-   - Uploads the file to Knowhere API for parsing
-   - Polls until parsing completes
-   - Downloads and extracts the result package
-   - **Automatically** copies parsed data to `~/.knowhere/{kbId}/`
-   - **Automatically** builds/updates `knowledge_graph.json`
-3. After ingest completes, the new document is immediately searchable via the retrieval workflow below
+After ingest completes, the new document is immediately searchable via the retrieval workflow below.
 
 Supported formats: PDF, DOCX, XLSX, PPTX, TXT, MD, images (JPG, PNG)