@ontos-ai/knowhere-claw 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-claw",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",
@@ -18,27 +18,36 @@
     }
   },
   "scripts": {
-    "build": "rolldown -c && tsc -p tsconfig.build.json",
+    "build": "rolldown -c",
+    "changeset": "changeset",
+    "changeset:publish": "changeset publish",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "lint": "oxlint --type-aware",
     "lint:fix": "oxlint --type-aware --fix",
     "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",
+    "release:version": "node ./scripts/release-version.mjs",
     "tsgo": "tsgo --noEmit -p tsconfig.json",
     "typecheck": "pnpm tsgo",
     "check:plugin-version": "node ./scripts/release-guard.mjs plugin-version",
-    "check:beta-version": "node ./scripts/release-guard.mjs beta-version",
     "prepack": "pnpm build",
     "test": "vitest --run",
     "clean": "rm -rf dist"
   },
   "dependencies": {
     "@knowhere-ai/sdk": "^0.1.1",
-    "fflate": "^0.8.2"
+    "fflate": "^0.8.2",
+    "fs-extra": "^11.2.0",
+    "nodejieba": "^2.6.0"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
     "@tsconfig/node22": "^22.0.5",
-    "@types/node": "^25.3.5",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.4.0",
     "@typescript/native-preview": "7.0.0-dev.20260307.1",
     "oxfmt": "0.38.0",
     "oxlint": "^1.51.0",
@@ -60,4 +69,4 @@
       "./dist/index.js"
     ]
   }
-}
+}

package/skills/knowhere/SKILL.md

@@ -132,7 +132,7 @@ 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. Wait for the plugin's completion message that the document is ready before proceeding. If no completion message arrives, check with `knowhere_get_job_status`.
+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`).

package/dist/__tests__/channel-route.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/__tests__/ingest-tool.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/__tests__/read-result-file-tool.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/__tests__/tracker-progress.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/channel-delivery.d.ts

@@ -1,21 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import type { ChannelRouteRecord } from "./types";
-type DeliverySurface = "discord" | "imessage" | "line" | "signal" | "slack" | "telegram" | "whatsapp";
-type DeliveryResult = {
-    delivered: boolean;
-    surface?: DeliverySurface;
-    to?: string;
-    accountId?: string;
-};
-export declare function deliverChannelMessage(params: {
-    api: OpenClawPluginApi;
-    operationLabel: string;
-    context?: unknown;
-    sessionKey?: string;
-    messages?: unknown[];
-    channelRoute?: ChannelRouteRecord;
-    text: string;
-    mediaUrl?: string;
-    mediaLocalRoots?: readonly string[];
-}): Promise<DeliveryResult>;
-export {};

package/dist/client.d.ts

@@ -1,33 +0,0 @@
-import type { KnowhereIngestRequest, KnowhereIngestResult, KnowhereJobList, KnowhereJobListRequest, KnowhereJobResult } from "./types";
-export declare class KnowhereClient {
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly requestTimeoutMs;
-    private readonly uploadTimeoutMs;
-    private readonly pollIntervalMs;
-    private readonly pollTimeoutMs;
-    private readonly logger;
-    private readonly sdk;
-    constructor(params: {
-        apiKey: string;
-        baseUrl: string;
-        requestTimeoutMs: number;
-        uploadTimeoutMs: number;
-        pollIntervalMs: number;
-        pollTimeoutMs: number;
-        logger: {
-            debug?: (message: string) => void;
-            info: (message: string) => void;
-        };
-    });
-    ingestDocument(params: KnowhereIngestRequest): Promise<KnowhereIngestResult>;
-    private logPollProgress;
-    getJob(jobId: string): Promise<KnowhereJobResult>;
-    listJobs(options?: KnowhereJobListRequest): Promise<KnowhereJobList>;
-    getCompletedJobResult(jobId: string): Promise<KnowhereIngestResult>;
-    private downloadResultArchive;
-    private uploadFile;
-    private requestJson;
-    private requestBuffer;
-    private request;
-}

package/dist/config.d.ts

@@ -1,12 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import type { JsonSchemaObject, ResolvedKnowhereConfig } from "./types";
-export declare const DEFAULT_BASE_URL = "https://api.knowhereto.ai";
-export declare const knowherePluginConfigSchema: JsonSchemaObject;
-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";
-export declare function assertKnowhereApiKey(config: ResolvedKnowhereConfig): void;
-export declare function isPaymentRequiredError(error: unknown): boolean;
-export declare function formatPaymentRequiredMessage(): string;
-export declare function readPersistedApiKey(storageDir: string): Promise<string | null>;
-export declare function persistApiKey(storageDir: string, apiKey: string): Promise<void>;

package/dist/error-message.d.ts

@@ -1 +0,0 @@
-export declare function formatErrorMessage(error: unknown): string;

package/dist/index.d.ts

@@ -1,9 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-declare const plugin: {
-    id: string;
-    name: string;
-    description: string;
-    configSchema: import("./types").JsonSchemaObject;
-    register(api: OpenClawPluginApi): void;
-};
-export default plugin;

package/dist/parser.d.ts

@@ -1,16 +0,0 @@
-import type { KnowhereDownloadedResult, KnowhereManifest, KnowhereParseResult, KnowhereStatistics, StoredBrowseIndex, StoredChunk } from "./types";
-type KnowhereStoredResultSummary = {
-    manifest: KnowhereManifest;
-    chunkCount: number;
-    statistics: KnowhereStatistics;
-};
-export declare const STORED_BROWSE_INDEX_VERSION = 2;
-export declare function resolveResultEntryPath(rootDir: string, entryPath: string): string;
-export declare function buildStoredPathPrefixes(storedPath: string): string[];
-export declare function isStoredBrowseIndex(value: unknown): value is StoredBrowseIndex;
-export declare function buildStoredBrowseIndex(resultDir: string, manifest: KnowhereManifest, chunks: StoredChunk[]): Promise<StoredBrowseIndex>;
-export declare function extractKnowhereResultArchive(downloadedResult: KnowhereDownloadedResult, targetDir: string): Promise<void>;
-export declare function readStoredKnowhereResultSummary(resultDir: string): Promise<KnowhereStoredResultSummary>;
-export declare function readStoredKnowhereResultContent(resultDir: string): Promise<Omit<KnowhereParseResult, "browseIndex">>;
-export declare function readStoredKnowhereParseResult(resultDir: string): Promise<KnowhereParseResult>;
-export {};

package/dist/session.d.ts

@@ -1,11 +0,0 @@
-export type ParsedConversationSessionKey = {
-    agentId: string;
-    surface: string;
-    remainder: string;
-    segments: string[];
-};
-export declare function parseConversationSessionKey(sessionKey: string | undefined): ParsedConversationSessionKey | undefined;
-export declare function normalizeConversationScopeKey(sessionKey: string | undefined): string | undefined;
-export declare function resolveSharedConversationScopeKey(sessionKey: string | undefined): string | undefined;
-export declare function findConversationSegmentValue(session: ParsedConversationSessionKey | undefined, ...keys: string[]): string | undefined;
-export declare function deriveMessageContextScopeKey(context: unknown): string | undefined;

package/dist/store.d.ts

@@ -1,79 +0,0 @@
-import type { ChannelRouteRecord, KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentPayload, StoredDocumentRecord } from "./types";
-export declare class KnowhereStore {
-    private readonly rootDir;
-    private readonly scopeMode;
-    private readonly logger;
-    private readonly indexCache;
-    private readonly documentPayloadCache;
-    private readonly scopeAccessChains;
-    private readonly scopeKeyAliases;
-    private readonly sessionScopeKeysBySessionId;
-    private readonly sessionScopeKeysBySessionKey;
-    private readonly channelRoutes;
-    private routesLoaded;
-    constructor(params: {
-        rootDir: string;
-        scopeMode: ScopeMode;
-        logger: PluginLogger;
-    });
-    registerScopeAlias(context: {
-        scopeKey: string;
-        sessionKey?: string;
-        sessionId?: string;
-    }): string;
-    registerMessageScope(context: {
-        sessionKey?: string;
-        sessionId?: string;
-        messageContext: unknown;
-    }): string | undefined;
-    registerChannelRoute(params: {
-        channelId: string;
-        accountId?: string;
-        conversationId?: string;
-    }): Promise<void>;
-    resolveChannelRoute(params: {
-        channelId?: string;
-        conversationId?: string;
-        sessionKey?: string;
-    }): Promise<ChannelRouteRecord | undefined>;
-    private lookupChannelRoute;
-    inheritScopeAlias(context: {
-        childSessionKey?: string;
-        childSessionId?: string;
-        requesterSessionKey?: string;
-        requesterSessionId?: string;
-    }): string | undefined;
-    resolveScope(context?: {
-        agentId?: string;
-        sessionKey?: string;
-        sessionId?: string;
-    }): KnowhereScope;
-    listDocuments(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
-    loadDocumentPayload(scope: KnowhereScope, docId: string): Promise<StoredDocumentPayload | null>;
-    getResultFileAbsolutePath(scope: KnowhereScope, docId: string, relativePath: string): string;
-    readResultFile(scope: KnowhereScope, docId: string, relativePath: string): Promise<{
-        document: StoredDocumentRecord;
-        relativePath: string;
-        text: string | null;
-    } | null>;
-    saveDownloadedDocument(scope: KnowhereScope, payload: SaveStoredDocumentPayload, options?: {
-        overwrite?: boolean;
-    }): Promise<StoredDocumentRecord>;
-    removeDocument(scope: KnowhereScope, docId: string): Promise<StoredDocumentRecord | null>;
-    clearScope(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
-    private getIndex;
-    private persistIndex;
-    private runWithScopeAccessLock;
-    private removeDocumentArtifacts;
-    private buildDocumentPayloadCacheKey;
-    private touchDocumentPayloadCache;
-    private deleteDocumentPayloadCache;
-    private deleteScopeDocumentPayloadCaches;
-    private loadOrBuildBrowseIndex;
-    private buildRouteKey;
-    private ensureRoutesLoaded;
-    private persistRoutes;
-    private resolveCanonicalScopeKey;
-    private resolveKnownScopeKey;
-    private rebuildIndex;
-}

package/dist/text.d.ts

@@ -1,10 +0,0 @@
-export declare function normalizeWhitespace(value: unknown): string;
-export declare function truncateText(value: unknown, maxChars: number): string;
-export declare function slugify(value: unknown, fallback?: string): string;
-export declare function hashString(value: string): string;
-export declare function sanitizeStringArray(value: unknown): string[];
-export declare function toComparableText(value: unknown): string;
-export declare function stripHtmlTags(text: string): string;
-export declare function stripLatex(text: string): string;
-export declare function normalizeUnicode(text: string): string;
-export declare function normalizeForGrep(text: string): string;

package/dist/tools.d.ts

@@ -1,8 +0,0 @@
-import { type AnyAgentTool, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import { KnowhereStore } from "./store";
-import type { ResolvedKnowhereConfig, ToolRuntimeContext } from "./types";
-export declare function createKnowhereToolFactory(params: {
-    api: OpenClawPluginApi;
-    config: ResolvedKnowhereConfig;
-    store: KnowhereStore;
-}): (ctx: ToolRuntimeContext) => AnyAgentTool[];

package/dist/tracker-progress.d.ts

@@ -1,10 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import type { ChannelRouteRecord } from "./types";
-export declare function sendTrackerProgress(params: {
-    api: OpenClawPluginApi;
-    context?: unknown;
-    sessionKey?: string;
-    messages?: unknown[];
-    channelRoute?: ChannelRouteRecord;
-    text: string;
-}): Promise<boolean>;

package/dist/types.d.ts

@@ -1,248 +0,0 @@
-export type ScopeMode = "session" | "agent" | "global";
-export type StringRecord = Record<string, unknown>;
-export interface PluginLogger {
-    debug?: (message: string) => void;
-    info: (message: string) => void;
-    warn: (message: string) => void;
-    error: (message: string) => void;
-}
-export interface ToolRuntimeContext {
-    workspaceDir?: string;
-    agentId?: string;
-    accountId?: string;
-    sessionKey?: string;
-    sessionId?: string;
-}
-export interface ResolvedKnowhereConfig {
-    apiKey: string;
-    baseUrl: string;
-    storageDir: string;
-    scopeMode: ScopeMode;
-    pollIntervalMs: number;
-    pollTimeoutMs: number;
-    requestTimeoutMs: number;
-    uploadTimeoutMs: number;
-}
-export interface KnowhereStatistics {
-    total_chunks?: number;
-    text_chunks?: number;
-    image_chunks?: number;
-    table_chunks?: number;
-    total_pages?: number;
-}
-export interface KnowhereChecksum {
-    algorithm?: string;
-    value?: string;
-}
-export interface KnowhereManifest {
-    version?: string;
-    job_id?: string;
-    data_id?: string;
-    source_file_name?: string;
-    processing_date?: string;
-    checksum?: KnowhereChecksum;
-    statistics?: KnowhereStatistics;
-    files?: StringRecord;
-}
-export interface StoredChunk {
-    chunkId: string;
-    type: "text" | "image" | "table";
-    path: string | null;
-    summary: string;
-    content: string;
-    tokens: number | null;
-    keywords: string[];
-    relationships: unknown[];
-    metadata: StringRecord;
-    assetFilePath: string | null;
-    originalName: string | null;
-    tableType: string | null;
-}
-export interface StoredPathRecord {
-    path: string;
-    parentPath: string | null;
-    depth: number;
-    childPaths: string[];
-    chunkIds: string[];
-    directChunkCount: number;
-    chunkCount: number;
-    textChunkCount: number;
-    imageChunkCount: number;
-    tableChunkCount: number;
-}
-export type StoredResultFileKind = "manifest" | "chunks" | "fullMarkdown" | "kbCsv" | "hierarchy" | "hierarchyView" | "image" | "table" | "other";
-export interface StoredResultFileRecord {
-    relativePath: string;
-    kind: StoredResultFileKind;
-    chunkId: string | null;
-    format: string | null;
-    sizeBytes: number | null;
-}
-export interface StoredBrowseIndex {
-    version: number;
-    paths: StoredPathRecord[];
-    chunkOrder: string[];
-    resultFiles: StoredResultFileRecord[];
-}
-export interface KnowhereParseResult {
-    manifest: KnowhereManifest;
-    chunks: StoredChunk[];
-    fullMarkdown: string;
-    hierarchy: unknown;
-    browseIndex: StoredBrowseIndex;
-}
-export interface KnowhereDownloadedResult {
-    zipBytes: Buffer;
-    rawZipSha1: string;
-}
-export interface KnowhereJob {
-    job_id: string;
-    status: string;
-    source_type: string;
-    data_id?: string | null;
-    created_at?: string | null;
-    upload_url?: string | null;
-    upload_headers?: Record<string, string> | null;
-    expires_in?: number | null;
-}
-export interface KnowhereJobError {
-    code?: string;
-    message?: string;
-    request_id?: string;
-    details?: unknown;
-}
-export interface KnowhereJobResult {
-    job_id: string;
-    status: string;
-    source_type: string;
-    data_id?: string | null;
-    created_at?: string | null;
-    progress?: unknown;
-    error?: KnowhereJobError | null;
-    result?: StringRecord | null;
-    result_url?: string | null;
-    result_url_expires_at?: string | null;
-    file_name?: string | null;
-    file_extension?: string | null;
-    model?: string | null;
-    ocr_enabled?: boolean | null;
-    duration_seconds?: number | null;
-    credits_spent?: number | null;
-}
-export interface KnowhereJobList {
-    jobs: KnowhereJobResult[];
-    total: number;
-    page: number;
-    pageSize: number;
-    totalPages: number;
-}
-export interface KnowhereJobListRequest {
-    page?: number;
-    pageSize?: number;
-    jobStatus?: string;
-    jobType?: string;
-    recentDays?: 1 | 7 | 30;
-    startTime?: string;
-    endTime?: string;
-}
-export interface KnowhereParsingParams {
-    model?: "base" | "advanced";
-    ocr_enabled?: boolean;
-    kb_dir?: string;
-    doc_type?: string;
-    smart_title_parse?: boolean;
-    summary_image?: boolean;
-    summary_table?: boolean;
-    summary_txt?: boolean;
-    add_frag_desc?: string;
-}
-export interface KnowhereIngestRequest {
-    filePath?: string;
-    fileName?: string;
-    url?: string;
-    dataId?: string;
-    parsingParams?: KnowhereParsingParams;
-    onJobCreated?: (job: KnowhereJob) => void | Promise<void>;
-    onJobUpdated?: (jobResult: KnowhereJobResult) => void | Promise<void>;
-}
-export interface KnowhereIngestResult {
-    job: KnowhereJob;
-    jobResult: KnowhereJobResult;
-    downloadedResult: KnowhereDownloadedResult;
-}
-export interface KnowhereScope {
-    mode: ScopeMode | "global";
-    key: string;
-    label: string;
-    rootDir: string;
-    documentsDir: string;
-    indexPath: string;
-}
-export interface StoredDocumentRecord {
-    id: string;
-    title: string;
-    sourceType: "file" | "url";
-    source: string;
-    sourceLabel: string;
-    fileName: string | null;
-    originalFileName: string | null;
-    dataId: string | null;
-    jobId: string | null;
-    checksum: string | null;
-    resultUrl: string | null;
-    resultUrlExpiresAt: string | null;
-    scopeLabel: string;
-    tags: string[];
-    ingestedAt: string;
-    updatedAt: string;
-    chunkCount: number;
-    statistics: KnowhereStatistics;
-}
-export interface StoredDocumentPayload {
-    version: number;
-    document: StoredDocumentRecord;
-    manifest: KnowhereManifest;
-    jobResult: KnowhereJobResult;
-    fullMarkdown: string;
-    hierarchy: unknown;
-    browseIndex: StoredBrowseIndex;
-    rawZipSha1: string;
-    chunks: StoredChunk[];
-}
-export interface StoredDocumentMetadata {
-    version: number;
-    document: StoredDocumentRecord;
-    jobResult: KnowhereJobResult;
-    rawZipSha1: string;
-}
-export interface KnowhereIndex {
-    version: number;
-    scopeMode: string;
-    scopeKey: string;
-    updatedAt: string | null;
-    documents: StoredDocumentRecord[];
-}
-export interface SaveStoredDocumentPayload {
-    sourceType: "file" | "url";
-    source: string;
-    sourceLabel?: string;
-    fileName: string | null;
-    docId?: string;
-    title?: string;
-    dataId?: string;
-    tags: string[];
-    job: KnowhereJob;
-    jobResult: KnowhereJobResult;
-    downloadedResult: KnowhereDownloadedResult;
-}
-export interface JsonSchemaObject {
-    [key: string]: unknown;
-}
-export interface ChannelRouteRecord {
-    readonly channelId: string;
-    readonly accountId: string;
-    readonly conversationId?: string;
-    readonly updatedAt: string;
-}
-export declare function isRecord(value: unknown): value is StringRecord;
-export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;