@ontos-ai/knowhere-claw 0.2.0 → 0.2.2-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-claw",
-  "version": "0.2.0",
+  "version": "0.2.2-beta.1",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",
@@ -18,13 +18,14 @@
     }
   },
   "scripts": {
-    "build": "rolldown -c",
+    "build": "rolldown -c && tsc -p tsconfig.build.json",
     "changeset": "changeset",
     "changeset:publish": "changeset publish",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "lint": "oxlint --type-aware",
     "lint:fix": "oxlint --type-aware --fix",
+    "smoke:auto": "vite-node --mode smoke ./smoketest/run-tool.ts -- --auto --file-path smoketest/fixtures/sample.pdf",
     "smoke:tools": "vite-node --mode smoke ./smoketest/run-tool.ts",
     "release:beta": "node ./scripts/publish-beta-release.mjs",
     "release:publish": "node ./scripts/publish-release.mjs",

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.