@ontos-ai/knowhere-claw 0.2.3 → 0.2.4

package/skills/knowhere/SKILL.md

@@ -1,285 +0,0 @@
----
-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 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` 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.
-
-## When to prefer Knowhere
-
-Reach for Knowhere tools first whenever:
-
-- The user asks you to read, summarize, analyze, compare, or quote from a document file — even if they don't mention "Knowhere" by name.
-- The user references an attached file or a file path pointing to a supported format.
-- The user asks a question that likely requires content from a document (e.g., "what does the contract say about…", "find the table in the report…").
-- You encounter a supported file in the workspace and need to understand its content to complete a task.
-
-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.
-
-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
-
-Use these terms consistently:
-
-- `stored document`: one locally stored document identified by `docId`
-- `scope`: the current local storage scope
-- `path`: a structural path derived from Knowhere chunk paths
-- `chunk`: one stored parsed unit identified by `chunkId`
-- `asset path`: the relative path to a stored image or table asset under `result/`
-
-## Response Style
-
-Keep tool-driven replies short and labeled.
-
-- Always reply in the same language the user is using. Tool outputs are in English — translate status messages, labels, and explanations to the user's language.
-- Never expose internal identifiers (`docId`, `chunkId`, UUID-based filenames, raw paths like `Default_Root/...`) in user-facing replies. These are for your internal reasoning and tool calls only. Cite sources using human-readable section or chapter names derived from the path.
-- Reuse labels such as `Scope`, `Source`, `File`, `Chunks`, `Job ID`, and `Next` when relaying tool results.
-- Prefer one short status line plus the key fields the user needs for the next step.
-
-## When to use Knowhere
-
-Use Knowhere whenever the task involves document content — whether the user mentions "Knowhere" or not:
-
-- Read, summarize, analyze, compare, or quote from any supported file (PDF, DOCX, XLSX, PPTX, images, TXT, MD)
-- Parse a document from a URL (pass the URL directly to `knowhere_ingest_document` — no local download needed)
-- Answer questions that depend on document content ("what does section 3 say?", "find the revenue table", "compare these two reports")
-- Inspect, browse, or search previously ingested documents
-- Inspect ingest jobs or import a completed Knowhere job
-- Preview, list, remove, or clear stored documents
-- Understand what fields exist inside the stored result package
-
-When the user provides a URL to a document (e.g., a link to a PDF, web page, or online report), use `knowhere_ingest_document` with the `url` parameter. Knowhere fetches it directly — no need to download the file locally first.
-
-Before calling `knowhere_ingest_document` for a file or URL that may already be available in the current scope, call `knowhere_list_documents` and compare `Source`, `File`, and `Title`. If a matching stored document already exists, reuse it instead of ingesting again unless the user explicitly asks for a fresh parse, different parsing settings, or overwrite behavior.
-
-Do not assume an uploaded attachment was already ingested. If the user asks you to use an attached file, first check for an existing matching Knowhere result in the current scope. If no existing result clearly covers it, call `knowhere_ingest_document` yourself.
-
-## Attachment markers
-
-When a prompt contains a marker like:
-
-```text
-[media attached: /absolute/path/to/file.pdf (application/pdf) | handbook.pdf]
-```
-
-Use:
-
-- the exact absolute path as `filePath`
-- the visible filename as `fileName`
-
-This preserves the original filename when the local path is a temporary UUID-based attachment path.
-
-## Stored result model
-
-The canonical Knowhere delivery format behind `result_url` is a ZIP package.
-This plugin stores that package in extracted form on disk: lightweight local
-metadata in `metadata.json`, a plugin-local browse index in `browse-index.json`,
-and the unzipped Knowhere result files under `result/`.
-
-The important package files are:
-
-- `metadata.json`: plugin-local sidecar. It maps the local `docId`, source labels, tags, timestamps, and job metadata to the extracted Knowhere package under `result/`.
-- `browse-index.json`: plugin-local browse helper. It tracks structural paths, chunk order, and result-file inventory for fast path and file browsing.
-- `manifest.json`: package inventory. Read this first. It tells you what optional files and assets exist and carries `job_id`, `data_id`, `source_file_name`, checksum, and statistics.
-- `chunks.json`: primary retrieval dataset. It contains stable chunk IDs, chunk types, `path`, `content`, summaries, and metadata.
-- `hierarchy.json`: document tree rebuilt from parser paths. Use it when structural context matters and the raw path tree is not enough.
-- `full.md`: convenience whole-document markdown view. Good for broad skimming, but do not treat it as the only grounding source.
-- `images/` and `tables/`: raw extracted assets referenced by chunk metadata and manifest entries. The plugin stores these untouched.
-- `kb.csv`: raw parser export when present. Use it when you need parser rows, joins, or custom downstream transforms.
-
-Each stored chunk exposes these core fields through the chunk tools:
-
-- `chunkId`: stable chunk identifier
-- `type`: `text`, `image`, or `table`
-- `path`: best-effort hierarchy/path label
-- `summary`: chunk summary
-- `content`: original stored text payload
-- `contentLength`: character count of the content field (available in summary mode to help budget reads)
-- `tokens`: parser token hint when present
-- `keywords`: search hints from the parser
-- `relationships`: best-effort related chunk metadata
-- `assetFilePath`: relative path to the stored asset for image/table chunks
-
-Useful joins:
-
-- `manifest.files.images[].id == chunks[].chunkId` for image chunks
-- `manifest.files.tables[].id == chunks[].chunkId` for table chunks
-- `chunks[].assetFilePath` points to the stored asset path under `result/`
-
-## String truncation
-
-Chunk and file tools truncate string fields to `maxStringChars` (default 4000).
-When `truncatedStrings: true` appears, retry with a higher value (e.g. 12000, up to 20000) to get full content.
-
-## Tool selection
-
-- `knowhere_ingest_document` for new local files or URLs after confirming the document is not already stored in the current scope, or when the user explicitly wants a fresh parse
-- `knowhere_list_documents` to find candidate document IDs in the current scope and check whether the same document is already stored before a new ingest
-- `knowhere_read_result_file` for `manifest.json`, `hierarchy.json`, `kb.csv`, table HTML files, image assets (e.g., `images/img-0.png`), or other files under `result/`. Image files are staged into an attachment-ready local path and returned with a `message` tool handoff instead of inline image bytes. When the result mode is `image_attachment`, never call `read` or any other file-reading tool on `data.stagedPath`; immediately call `message` with `data.sendWithMessageTool`.
-- `knowhere_preview_document` for a quick overview: markdown preview plus the structural path tree (like a book index)
-- `knowhere_grep` to search chunks with composable AND conditions across fields. This is the recommended default for text search — just pass `conditions: [{ pattern: "your query" }]` with no target to search all text fields at once. Use targeted conditions only when you need to narrow by specific fields like `chunk.type` or `chunk.path`.
-- `knowhere_list_jobs`, `knowhere_get_job_status`, and `knowhere_import_completed_job` for async Knowhere jobs
-- `knowhere_remove_document` and `knowhere_clear_scope` for cleanup
-
-After ingesting a document, use the returned document or job identifiers for follow-up operations instead of guessing names.
-
-## 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. `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.
-- Do not rely on `full.md` alone if the question depends on exact section boundaries, tables, or images.
-- If the task needs raw `kb.csv`, raw HTML tables, or another stored text file under `result/`, read it directly with `knowhere_read_result_file`.
-- When a tool response contains `truncatedStrings: true`, retry with `maxStringChars: 12000` (or up to 20000) before answering from incomplete content.
-- When `knowhere_grep` returns hints after the JSON (separated by `---`), follow the suggested next steps before answering. The hints guide you to refine your search iteratively.
-- Iterate on grep: if 0 matches, broaden; if results are capped, add a path condition; if truncated, re-query fewer results with higher maxStringChars.
-
-## Tool usage examples
-
-Use a real stored `docId` returned by `knowhere_ingest_document`, `knowhere_import_completed_job`, or `knowhere_list_documents`.
-
-Ingest a local file:
-
-```json
-{
-  "filePath": "/tmp/uploads/handbook.pdf",
-  "fileName": "handbook.pdf"
-}
-```
-
-Ingest a URL:
-
-```json
-{
-  "url": "https://example.com/report-2026.pdf",
-  "title": "Q1 Report"
-}
-```
-
-Check job status:
-
-```json
-{
-  "jobId": "job_f6f12930906a"
-}
-```
-
-Import a completed job:
-
-```json
-{
-  "jobId": "job_f6f12930906a"
-}
-```
-
-Read manifest JSON:
-
-```json
-{
-  "docId": "handbook-1234",
-  "filePath": "manifest.json",
-  "mode": "json"
-}
-```
-
-Preview a document:
-
-```json
-{
-  "docId": "handbook-1234"
-}
-```
-
-Grep for text across all chunk fields (recommended default):
-
-```json
-{
-  "docId": "paper-pdf-a370ef58",
-  "conditions": [{ "pattern": "npm audit" }]
-}
-```
-
-Grep with multiple AND conditions (e.g. table chunks mentioning "precision"):
-
-```json
-{
-  "docId": "paper-pdf-a370ef58",
-  "conditions": [{ "target": "chunk.type", "pattern": "table" }, { "pattern": "precision" }]
-}
-```
-
-Grep with path filter and sibling context:
-
-```json
-{
-  "docId": "paper-pdf-a370ef58",
-  "conditions": [{ "target": "chunk.path", "pattern": "EVALUATION" }],
-  "includeContext": true
-}
-```
-
-Grep with regex:
-
-```json
-{
-  "docId": "paper-pdf-a370ef58",
-  "conditions": [{ "pattern": "\\bF1[- ]score\\b", "regex": true }]
-}
-```
-
-Read a table HTML file:
-
-```json
-{
-  "docId": "handbook-1234",
-  "filePath": "tables/table-1.html",
-  "mode": "text"
-}
-```
-
-Read an image asset:
-
-```json
-{
-  "docId": "handbook-1234",
-  "filePath": "images/img-0.png"
-}
-```
-
-If the result returns `mode: "image_attachment"`, call `message` with `data.sendWithMessageTool` exactly as returned. Do not call `read` on `data.stagedPath`.
-
-Example workflow for a question like `What does the handbook say about hotel limits?`:
-
-1. Call `knowhere_list_documents` to find the right `docId` if you do not already have it.
-2. Call `knowhere_read_result_file` with `filePath: "manifest.json"` to confirm the package layout.
-3. Call `knowhere_preview_document` with `mode: "paths"` and look for a relevant branch such as `Travel` or `Expenses`.
-4. Call `knowhere_grep` with `conditions: [{ "pattern": "hotel" }]` to find matching chunks, or add a path condition to narrow to the branch.
-5. If the answer depends on a table, read the linked `assetFilePath` with `knowhere_read_result_file`.
-6. Answer from the matched chunks and cite `chunkId` and `path`.
-
-Do not rely on prompt-loaded excerpts as the main workflow. Prefer reading the stored result directly from disk.
-
-If Knowhere returns an API error, quote the error directly in your reply.