@ontos-ai/knowhere-claw 0.2.5 → 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/index.js

@@ -1,3 +1,4 @@
+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";
@@ -10,7 +11,9 @@ const plugin = {
 	configSchema: knowherePluginConfigSchema,
 	register(api) {
 		const config = resolveKnowhereConfig(api);
-		const kgConfig = resolveKnowledgeGraphConfig(resolveEffectivePluginConfig(api));
+		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/tools.js

@@ -4,9 +4,11 @@ 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([
@@ -969,6 +971,10 @@ async function t2LoadChunks(docDir) {
 	}
 	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");
@@ -980,6 +986,114 @@ async function t2LoadRawChunks(docDir) {
 		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 = {};
@@ -1043,11 +1157,78 @@ async function t2ListDocDirs(kbRoot) {
 	}
 	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 查看具体文档的章节目录。",
+		description: "获取知识库全局概览。查询知识时必须先调此工具，了解有哪些文档、关键词、重要性和跨文件关联。然后用 knowhere_get_structure 查看具体文档的章节目录。重要：knowhere_read_chunks 已内置图片/表格自动投递功能，读取内容时会自动发送多媒体到用户频道。除非用户明确要求下载原始文件，否则请勿主动发送 .docx/.pdf 等文档。",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -1127,7 +1308,7 @@ function createGetStructureTool(_params) {
 	return {
 		name: "knowhere_get_structure",
 		label: "Knowhere Get Structure",
-		description: "获取文档章节目录。先调 knowhere_get_map 确定 kbId 和文档名后，用此工具查看章节结构，然后用 knowhere_read_chunks 读取内容。",
+		description: "获取文档章节目录。先调 knowhere_get_map 确定 kbId 和文档名后，用此工具查看章节结构，然后用 knowhere_read_chunks 读取内容。重要：knowhere_read_chunks 已内置图片/表格自动投递功能，除非用户要求下载文件，否则无需额外发送原始文档。",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -1177,7 +1358,7 @@ function createReadChunksTool(_params) {
 	return {
 		name: "knowhere_read_chunks",
 		label: "Knowhere Read Chunks",
-		description: "读取文档内容。先调 knowhere_get_structure 确定章节后，用此工具读取具体内容。可通过 sectionPath 过滤特定章节，减少 token 消耗。",
+		description: "读取文档内容。先调 knowhere_get_structure 确定章节后，用此工具读取具体内容。可通过 sectionPath 过滤特定章节，减少 token 消耗。此工具已内置图片/表格自动投递：读取时会自动将多媒体内容发送到用户频道。除非用户明确要求下载原始文件，否则无需再用 message 发送文档。",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -1211,7 +1392,36 @@ function createReadChunksTool(_params) {
 			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 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);
@@ -1226,7 +1436,20 @@ function createReadChunksTool(_params) {
 					await fs.writeFile(kgPath, JSON.stringify(g, null, 2), "utf-8");
 				}
 			} catch {}
-			return t2JsonResult({
+			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),
@@ -1235,7 +1458,79 @@ function createReadChunksTool(_params) {
 				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: {}
+			};
 		}
 	};
 }
@@ -1243,7 +1538,7 @@ function createDiscoverFilesTool(_params) {
 	return {
 		name: "knowhere_discover_files",
 		label: "Knowhere Discover Files",
-		description: "在所有知识库文档中搜索关键词，返回命中文件和次数。用于和 knowhere_get_map 做并集，避免遗漏相关文件。只返回文件名，不返回内容。",
+		description: "在所有知识库文档中搜索关键词，返回命中文件和次数。用于和 knowhere_get_map 做并集，避免遗漏相关文件。只返回文件名，不返回内容。注意：后续用 knowhere_read_chunks 读取时会自动投递图片/表格到用户频道，除非用户要求下载文件，否则无需额外发送原始文档。",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -1351,7 +1646,12 @@ function createKnowhereToolFactory(params) {
 		}),
 		createGetMapTool({ api: params.api }),
 		createGetStructureTool({ api: params.api }),
-		createReadChunksTool({ api: params.api }),
+		createReadChunksTool({
+			api: params.api,
+			store: params.store,
+			ctx
+		}),
+		createViewImageTool({ api: params.api }),
 		createDiscoverFilesTool({ api: params.api })
 	];
 }

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.5",
+  "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.5",
+  "version": "0.2.6",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",

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)