@ontos-ai/knowhere-claw 0.2.2 → 0.2.3

package/README.md

@@ -116,7 +116,7 @@ Within each scope, the plugin keeps:
 ## 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/tools.js

@@ -9,6 +9,13 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/core";
 //#region src/tools.ts
+const TERMINAL_JOB_STATUSES = new Set([
+	"cancelled",
+	"canceled",
+	"done",
+	"error",
+	"failed"
+]);
 async function buildKnowledgeGraphAsync(params) {
 	const docDir = path.join(params.scope.documentsDir, params.docId);
 	const metadataPath = path.join(docDir, "metadata.json");
@@ -95,6 +102,67 @@ function buildStoredDocumentSummaryLines(params) {
 	if (params.includeUpdatedAt) lines.push(`Updated: ${params.document.updatedAt}`);
 	return lines;
 }
+function isTerminalJobStatus(status, hasError) {
+	return TERMINAL_JOB_STATUSES.has(status.trim().toLowerCase()) || hasError;
+}
+function startKnowledgeGraphBuild(params) {
+	if (!params.kgService.isEnabled()) return;
+	const kbId = params.kgService.resolveKbId(params.ctx);
+	if (!kbId) return;
+	params.api.logger.info(`knowhere: initiating knowledge graph build kbId=${kbId} docId=${params.document.id}`);
+	buildKnowledgeGraphAsync({
+		kgService: params.kgService,
+		kbId,
+		docId: params.document.id,
+		documentPayload: params.ingestResult,
+		scope: params.scope,
+		ctx: params.ctx,
+		api: params.api,
+		channelRoute: params.channelRoute,
+		sessionKey: params.sessionKey
+	}).catch((kgError) => {
+		params.api.logger.error(`knowhere: knowledge graph build failed kbId=${kbId} docId=${params.document.id}: ${formatErrorMessage(kgError)}`);
+	});
+}
+async function persistIngestedDocument(params) {
+	const storedDocument = await params.store.saveDownloadedDocument(params.scope, {
+		sourceType: params.sourceType,
+		source: params.source,
+		fileName: params.fileName,
+		docId: params.docId,
+		title: params.title,
+		dataId: params.dataId,
+		tags: params.tags,
+		job: params.ingestResult.job,
+		jobResult: params.ingestResult.jobResult,
+		downloadedResult: params.ingestResult.downloadedResult
+	}, { overwrite: params.overwrite });
+	params.api.logger.info(`knowhere: knowhere_ingest_document stored document scope=${params.scope.label} jobId=${params.ingestResult.job.job_id} docId=${storedDocument.id}`);
+	startKnowledgeGraphBuild({
+		api: params.api,
+		channelRoute: params.channelRoute,
+		ctx: params.ctx,
+		document: storedDocument,
+		ingestResult: params.ingestResult,
+		kgService: params.kgService,
+		scope: params.scope,
+		sessionKey: params.sessionKey
+	});
+	return storedDocument;
+}
+function formatCompletedIngestResult(params) {
+	return [
+		"Ingest complete.",
+		...buildStoredDocumentSummaryLines({
+			document: params.document,
+			scopeLabel: params.scopeLabel,
+			includeJobId: true,
+			includeSource: true
+		}),
+		`Source type: ${params.sourceType}`,
+		"Next: use knowhere_preview_document for a structural overview or knowhere_grep to search the parsed content."
+	].join("\n");
+}
 function readString(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
@@ -531,7 +599,7 @@ function createIngestTool(params) {
 	return {
 		name: "knowhere_ingest_document",
 		label: "Knowhere Ingest",
-		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. Before calling this for a document that might already be stored in the current scope, use knowhere_list_documents and reuse the existing stored document when Source, File, or Title clearly match unless the user explicitly asks for a fresh parse or overwrite. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Returns immediately with a job ID while parsing continues in the background. Use knowhere_get_job_status only when the current turn needs the parsed result. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
+		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. Before calling this for a document that might already be stored in the current scope, use knowhere_list_documents and reuse the existing stored document when Source, File, or Title clearly match unless the user explicitly asks for a fresh parse or overwrite. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Knowhere must be the only parser for supported files. If Knowhere returns an error, surface that exact error to the user and do not fall back to other parsing methods or fabricate a preview. By default blockUntilComplete is false, so this tool is fire-and-forget and returns a job ID while parsing continues in the background. Set blockUntilComplete to true only when the current turn explicitly needs the parsed result before continuing. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -573,6 +641,10 @@ function createIngestTool(params) {
 					type: "boolean",
 					description: "Replace an existing stored document with the same docId."
 				},
+				blockUntilComplete: {
+					type: "boolean",
+					description: "When true, wait for Knowhere to finish parsing, store the result, and return a ready-to-use stored-document summary. Defaults to false, which returns immediately with a job ID and continues parsing in the background."
+				},
 				lang: {
 					type: "string",
 					description: "Language for any user-facing background status update sent after parsing completes or fails. Supports en and ch; unsupported values fall back to en."
@@ -628,13 +700,14 @@ function createIngestTool(params) {
 				filePath: resolvedFilePath,
 				url: urlParam
 			});
+			const blockUntilComplete = readBoolean(paramsRecord.blockUntilComplete, false);
 			const tags = sanitizeStringArray(paramsRecord.tags);
 			const overwrite = readBoolean(paramsRecord.overwrite, false);
 			const trackerLanguage = readIngestTrackerLanguage(paramsRecord.lang);
 			const sessionKey = params.ctx.sessionKey;
 			const sourceType = urlParam ? "url" : "file";
 			const channelRoute = await params.store.resolveChannelRoute({ sessionKey });
-			params.api.logger.info(`knowhere: knowhere_ingest_document starting background ingest scope=${scope.label} sourceType=${sourceType} label=${JSON.stringify(progressLabel)} overwrite=${overwrite} docId=${docId ?? "auto"} dataId=${dataId ?? "none"} lang=${trackerLanguage} routeState=${channelRoute ? "resolved" : "missing"} routeAccountId=${channelRoute?.accountId ?? "none"}`);
+			params.api.logger.info(`knowhere: knowhere_ingest_document starting ingest scope=${scope.label} sourceType=${sourceType} label=${JSON.stringify(progressLabel)} mode=${blockUntilComplete ? "blocking" : "background"} overwrite=${overwrite} docId=${docId ?? "auto"} dataId=${dataId ?? "none"} lang=${trackerLanguage} routeState=${channelRoute ? "resolved" : "missing"} routeAccountId=${channelRoute?.accountId ?? "none"}`);
 			let resolveJobCreated;
 			const jobCreatedPromise = new Promise((resolve) => {
 				resolveJobCreated = resolve;
@@ -653,40 +726,52 @@ function createIngestTool(params) {
 					resolveJobCreated(job);
 				}
 			});
+			if (blockUntilComplete) {
+				const ingestResult = await ingestPromise.catch(rethrowWithPaymentHint);
+				params.api.logger.info(`knowhere: knowhere_ingest_document download completed scope=${scope.label} jobId=${ingestResult.job.job_id}; storing extracted result`);
+				return textResult(formatCompletedIngestResult({
+					document: await persistIngestedDocument({
+						api: params.api,
+						channelRoute,
+						ctx: params.ctx,
+						dataId,
+						docId,
+						fileName,
+						ingestResult,
+						kgService: params.kgService,
+						overwrite,
+						scope,
+						sessionKey,
+						source: urlParam || resolvedFilePath || "",
+						sourceType,
+						store: params.store,
+						tags,
+						title
+					}),
+					scopeLabel: scope.label,
+					sourceType
+				}));
+			}
 			ingestPromise.then(async (ingestResult) => {
 				params.api.logger.info(`knowhere: knowhere_ingest_document download completed scope=${scope.label} jobId=${ingestResult.job.job_id}; storing extracted result`);
-				const storedDocument = await params.store.saveDownloadedDocument(scope, {
-					sourceType,
-					source: urlParam || resolvedFilePath || "",
-					fileName,
-					docId,
-					title,
+				const storedDocument = await persistIngestedDocument({
+					api: params.api,
+					channelRoute,
+					ctx: params.ctx,
 					dataId,
+					docId,
+					fileName,
+					ingestResult,
+					kgService: params.kgService,
+					overwrite,
+					scope,
+					sessionKey,
+					source: urlParam || resolvedFilePath || "",
+					sourceType,
+					store: params.store,
 					tags,
-					job: ingestResult.job,
-					jobResult: ingestResult.jobResult,
-					downloadedResult: ingestResult.downloadedResult
-				}, { overwrite });
-				params.api.logger.info(`knowhere: knowhere_ingest_document stored document scope=${scope.label} jobId=${ingestResult.job.job_id} docId=${storedDocument.id} label=${JSON.stringify(progressLabel)}`);
-				if (params.kgService.isEnabled()) {
-					const kbId = params.kgService.resolveKbId(params.ctx);
-					if (kbId) {
-						params.api.logger.info(`knowhere: initiating knowledge graph build kbId=${kbId} docId=${storedDocument.id}`);
-						buildKnowledgeGraphAsync({
-							kgService: params.kgService,
-							kbId,
-							docId: storedDocument.id,
-							documentPayload: ingestResult,
-							scope,
-							ctx: params.ctx,
-							api: params.api,
-							channelRoute,
-							sessionKey
-						}).catch((kgError) => {
-							params.api.logger.error(`knowhere: knowledge graph build failed kbId=${kbId} docId=${storedDocument.id}: ${formatErrorMessage(kgError)}`);
-						});
-					}
-				}
+					title
+				});
 				await notifyBackgroundIngestOutcome({
 					api: params.api,
 					context: params.ctx,
@@ -737,7 +822,7 @@ function createIngestTool(params) {
 				`Job ID: ${createdJob.job_id}`,
 				`File: ${progressLabel}`,
 				`Scope: ${scope.label}`,
-				"Use knowhere_get_job_status only if this turn needs the parsed result."
+				"This call does not include parsed content yet."
 			].join("\n"));
 		}
 	};
@@ -746,7 +831,7 @@ function createJobStatusTool(params) {
 	return {
 		name: "knowhere_get_job_status",
 		label: "Knowhere Job Status",
-		description: "Check the status of a Knowhere parsing job by job ID. Returns job status, progress, duration, credits spent, and whether the result is already stored locally. Use this to monitor a running job or inspect a past job before importing it with knowhere_import_completed_job.",
+		description: "Check the status of a Knowhere parsing job by job ID. Returns job status, progress, duration, credits spent, and whether the result is already stored locally. Use this to monitor a running job or inspect a past job before importing it with knowhere_import_completed_job. Do not assume a running job is stuck just because progress is unchanged or slow. Only treat the job as failed or stuck when Knowhere returns an explicit failure status or error code.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -798,6 +883,10 @@ function createJobStatusTool(params) {
 				lines.push(`Result URL: ${job.result_url}`);
 				if (job.result_url_expires_at) lines.push(`Result URL expires: ${job.result_url_expires_at}`);
 			}
+			const hasExplicitError = Boolean(job.error?.code || job.error?.message);
+			if (job.status.trim().toLowerCase() === "done") lines.push("Interpretation: completed.");
+			else if (isTerminalJobStatus(job.status, hasExplicitError)) lines.push("Interpretation: Knowhere reported an explicit failure. Surface this error to the user and do not fall back to other parsing methods.");
+			else lines.push("Interpretation: still running. Do not describe this job as stuck or failed unless a later Knowhere API response returns an explicit failure status or error code.");
 			if (matchingDocuments.length === 0) lines.push("Stored docs in scope: none");
 			else {
 				lines.push("Stored docs in scope:");

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.2",
+  "version": "0.2.3",
   "uiHints": {
     "apiKey": {
       "label": "Knowhere API Key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-claw",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",

package/skills/knowhere/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: knowhere
-description: First-class document reader. Use Knowhere tools whenever the task involves reading, understanding, searching, or reasoning over document files (PDF, DOCX, XLSX, PPTX, images, TXT, MD) or URLs — even if the user does not mention "Knowhere" by name. Prefer Knowhere over generic file reads for all supported formats. Covers ingestion, structured browsing, chunk search, result file inspection, job management, and scope cleanup.
+description: First-class document reader. Use Knowhere tools whenever the task involves reading, understanding, searching, or reasoning over document files (PDF, DOCX, XLSX, PPTX, images, TXT, MD and more) or URLs — even if the user does not mention "Knowhere" by name. Prefer Knowhere over generic file reads for all supported formats. Covers ingestion, structured browsing, chunk search, result file inspection, job management, and scope cleanup.
 user-invocable: false
 ---
 
 # Knowhere Skill
 
-Knowhere is the first-class way to read, understand, and answer questions about document files. When a task involves reading or reasoning over a supported file (`.pdf`, `.docx`, `.xlsx`, `.pptx`, `.txt`, `.md`, `.jpg`, `.jpeg`, `.png`), always prefer Knowhere tools over generic file-reading approaches. Knowhere parses documents into structured chunks with hierarchy, summaries, tables, and images — far richer than raw text extraction.
+Knowhere is the first-class way to read, understand, and answer questions about document files. When a task involves reading or reasoning over a supported file (`.pdf`, `.docx`, `.xlsx`, `.pptx`, `.txt`, `.md`, `.jpg`, `.jpeg`, `.png` and others), always prefer Knowhere tools over generic file-reading approaches. Knowhere parses documents into structured chunks with hierarchy, summaries, tables, and images — far richer than raw text extraction.
 
 Use the `knowhere_*` tools for explicit document ingestion and browse-first stored-result workflows. Before starting a new ingest, prefer checking whether the current scope already has the same document stored.
 
@@ -21,7 +21,9 @@ Reach for Knowhere tools first whenever:
 
 Do not attempt to read supported document files (especially PDFs, DOCX, XLSX, PPTX) with generic file-read tools or shell commands. These formats are binary or semi-structured and will produce garbled or incomplete output. Knowhere handles them properly.
 
-For plain text files (`.txt`, `.md`), Knowhere still adds value through chunking, hierarchy extraction, and search — but direct reads are acceptable for quick one-off checks.
+If Knowhere returns a parsing error, status error, or explicit failure status, report that exact error to the user and stop. Do not fall back to other parsing methods, do not guess from partial binary reads, and do not fabricate a preview or summary.
+
+For plain text files (`.txt`, `.md`), Knowhere still adds value through chunking, hierarchy extraction, and search. Direct reads are acceptable only for quick workspace sanity checks that do not replace a requested parse, preview, or document-grounded answer.
 
 ## Terminology
 
@@ -132,17 +134,20 @@ After ingesting a document, use the returned document or job identifiers for fol
 ## Recommended workflow
 
 1. If the document may already exist in the current scope, call `knowhere_list_documents` first and compare `Source`, `File`, and `Title` to find an existing match.
-2. Ingest or import the document only if it is not already in the store, or if the user explicitly wants a fresh parse. After calling `knowhere_ingest_document`, you receive a job ID immediately while parsing continues in the background. If the current turn needs the parsed document, check with `knowhere_get_job_status`; otherwise stop and wait for the user to continue later.
-3. Call `knowhere_list_documents` again if you need to confirm the right `docId`.
-4. Call `knowhere_preview_document` to get a structural overview (table of contents with summaries).
-5. When you know what to search for, call `knowhere_grep` with `conditions: [{ pattern: "your query" }]` — this searches all text fields (content, summary, keywords, path) in one call. Add more conditions to narrow results (e.g. filter by `chunk.type` or `chunk.path`).
-6. Call `knowhere_grep` with a path condition to narrow results to a specific branch when browsing by structure.
-7. Call `knowhere_read_result_file` for `hierarchy.json`, `kb.csv`, table HTML, or image assets when the answer depends on parser rows, rich table structure, or visual content.
+2. Ingest or import the document only if it is not already in the store, or if the user explicitly wants a fresh parse. `knowhere_ingest_document` defaults to fire-and-forget (`blockUntilComplete: false`) and returns a job ID immediately while parsing continues in the background.
+3. Set `blockUntilComplete: true` on `knowhere_ingest_document` when the current turn explicitly needs the parsed result before continuing, such as "wait until it is parsed" or "show me a preview now".
+4. If a job was already started asynchronously and the current turn now depends on the parsed result, use `knowhere_get_job_status` until Knowhere reports `done` or an explicit failure. Do not infer "stuck" from unchanged progress alone.
+5. Call `knowhere_list_documents` again if you need to confirm the right `docId`.
+6. Call `knowhere_preview_document` to get a structural overview (table of contents with summaries).
+7. When you know what to search for, call `knowhere_grep` with `conditions: [{ pattern: "your query" }]` — this searches all text fields (content, summary, keywords, path) in one call. Add more conditions to narrow results (e.g. filter by `chunk.type` or `chunk.path`).
+8. Call `knowhere_grep` with a path condition to narrow results to a specific branch when browsing by structure.
+9. Call `knowhere_read_result_file` for `hierarchy.json`, `kb.csv`, table HTML, or image assets when the answer depends on parser rows, rich table structure, or visual content.
 
 ## Reasoning rules
 
 - Prefer `knowhere_grep` for all text search. It supports composable AND conditions, regex, and normalizes HTML/LaTeX/unicode before matching. Use `knowhere_preview_document` when you need a quick overview and structural browsing by path.
 - Use `knowhere_preview_document` before broad reads when the document is large or the relevant branch is unclear.
+- Use Knowhere as the only parser for document read. If Knowhere fails, surface the real error to the user instead of switching to another parsing approach.
 - Keep `path` in your reasoning and in your answer when possible. It restores section position and improves grounding.
 - Use `chunkId` and `path` internally for your own reasoning and tool calls, but do not expose them to the user. When citing sources, use human-readable section names derived from the path (e.g., "第7章 维护、保养" instead of `Default_Root/f339a970...-->7 维护、保养`). Never show raw `docId`, `chunkId`, or internal file paths in user-facing replies.
 - For image or table questions, inspect matching `image` or `table` chunks and the related manifest asset entries before answering. Use `knowhere_read_result_file` with the chunk's `assetFilePath` to prepare image assets for delivery, then use the returned `message` tool handoff when the user wants to see the image. Do not call `read` on the staged image path because it may live outside the agent sandbox.