@kweaver-ai/kweaver-sdk 0.7.1 → 0.7.3

package/dist/commands/ds.js

@@ -3,7 +3,7 @@ import { statSync } from "node:fs";
 import { glob } from "node:fs/promises";
 import { resolve as resolvePath } from "node:path";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
-import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTablesWithColumns, } from "../api/datasources.js";
+import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTablesWithColumns, scanMetadata, } from "../api/datasources.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { parseCsvFile, buildTableName, splitBatches, buildFieldMappings, buildDagBody, } from "./import-csv.js";
@@ -37,7 +37,10 @@ Subcommands:
   delete <id> [-y]                  Delete a datasource
   tables <id> [--keyword X]         List tables with columns
   connect <db_type> <host> <port> <database> --account X --password Y [--schema Z] [--name N]
+                                              [--reuse-existing|--force-new]
     Test connectivity, register datasource, and discover tables.
+    By default reuses an existing ds with the same (type, host, port, database, account)
+    instead of creating a duplicate. --force-new always creates a new entry.
   import-csv <ds-id> --files <glob_or_list> [--table-prefix X] [--batch-size N]
     Import CSV files into datasource tables via dataflow API.`);
         return 0;
@@ -206,6 +209,52 @@ async function runDsTablesCommand(args) {
     console.log(formatCallOutput(body, pretty));
     return 0;
 }
+export function findExistingDatasource(listBody, sig) {
+    const parsed = JSON.parse(listBody);
+    const entries = Array.isArray(parsed) ? parsed : (parsed.entries ?? []);
+    const tupleMatch = entries.find((e) => e.id &&
+        e.type === sig.type &&
+        e.bin_data?.host === sig.host &&
+        Number(e.bin_data?.port) === Number(sig.port) &&
+        e.bin_data?.database_name === sig.database &&
+        e.bin_data?.account === sig.account);
+    if (tupleMatch) {
+        return {
+            id: String(tupleMatch.id),
+            name: String(tupleMatch.name ?? ""),
+            matchedByName: tupleMatch.name === sig.name,
+            matchedByTuple: true,
+        };
+    }
+    if (sig.name) {
+        const nameMatch = entries.find((e) => e.id && e.name === sig.name);
+        if (nameMatch) {
+            return {
+                id: String(nameMatch.id),
+                name: String(nameMatch.name),
+                matchedByName: true,
+                matchedByTuple: false,
+            };
+        }
+    }
+    return undefined;
+}
+export function findDatasourceIdByName(listBody, name) {
+    const parsed = JSON.parse(listBody);
+    const entries = Array.isArray(parsed) ? parsed : (parsed.entries ?? []);
+    const hit = entries.find((e) => e.id && e.name === name);
+    return hit?.id ? String(hit.id) : undefined;
+}
+function isDuplicateNameError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    // HttpError.message is just "HTTP 400 ..."; the description lives in body.
+    const status = "status" in err ? Number(err.status) : NaN;
+    const body = "body" in err ? String(err.body) : "";
+    if (status !== 400)
+        return false;
+    return /数据源名称已存在|datasource name.*exist|already exists/i.test(body);
+}
 async function runDsConnectCommand(args) {
     let dbType = "";
     let host = "";
@@ -215,6 +264,7 @@ async function runDsConnectCommand(args) {
     let password = "";
     let schema;
     let name;
+    let forceNew = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--account" && args[i + 1]) {
@@ -233,6 +283,14 @@ async function runDsConnectCommand(args) {
             name = args[++i];
             continue;
         }
+        if (arg === "--force-new") {
+            forceNew = true;
+            continue;
+        }
+        if (arg === "--reuse-existing") {
+            forceNew = false;
+            continue;
+        }
         if (!arg.startsWith("-")) {
             if (!dbType)
                 dbType = arg;
@@ -245,7 +303,7 @@ async function runDsConnectCommand(args) {
         }
     }
     if (!dbType || !host || !database || !account || !password) {
-        console.error("Usage: kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema Z] [--name N]");
+        console.error("Usage: kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema Z] [--name N] [--reuse-existing|--force-new]");
         return 1;
     }
     if (Number.isNaN(port) || port < 1) {
@@ -254,6 +312,28 @@ async function runDsConnectCommand(args) {
     }
     const token = await ensureValidToken();
     const base = { baseUrl: token.baseUrl, accessToken: token.accessToken };
+    const dsName = name ?? database;
+    // Pre-flight dedup: connection-tuple match is the silent-orphan vector.
+    // Backend already rejects duplicate names with 400, but won't notice
+    // tuple collisions, so we own that check.
+    if (!forceNew) {
+        const listBody = await listDatasources({ ...base });
+        const hit = findExistingDatasource(listBody, {
+            type: dbType,
+            host,
+            port,
+            database,
+            account,
+            name: dsName,
+        });
+        if (hit) {
+            const why = hit.matchedByTuple
+                ? "matched by (type,host,port,database,account)"
+                : "matched by --name";
+            console.error(`Reusing existing datasource ${hit.id} (${hit.name}); ${why}. Use --force-new to override.`);
+            return printDsConnectOutput(base, hit.id);
+        }
+    }
     console.error("Testing connectivity ...");
     await testDatasource({
         ...base,
@@ -265,27 +345,45 @@ async function runDsConnectCommand(args) {
         password,
         schema,
     });
-    const dsName = name ?? database;
-    const createBody = await createDatasource({
-        ...base,
-        name: dsName,
-        type: dbType,
-        host,
-        port,
-        database,
-        account,
-        password,
-        schema,
-    });
-    const dsId = extractDatasourceId(createBody);
+    let dsId = "";
+    try {
+        const createBody = await createDatasource({
+            ...base,
+            name: dsName,
+            type: dbType,
+            host,
+            port,
+            database,
+            account,
+            password,
+            schema,
+        });
+        dsId = extractDatasourceId(createBody);
+    }
+    catch (err) {
+        // Backend checks name uniqueness but not tuple. If we raced another caller
+        // (or tuple match got disabled by --force-new and the name still collides),
+        // turn the raw 400 into a useful pointer to the existing id.
+        if (isDuplicateNameError(err)) {
+            // Backend rejected the name; look it up specifically (not by tuple —
+            // sibling ds sharing the same connection would mislead the pointer).
+            const listBody = await listDatasources({ ...base });
+            const existingId = findDatasourceIdByName(listBody, dsName);
+            if (existingId) {
+                console.error(`Datasource name '${dsName}' already exists as ${existingId}. Re-run without --force-new to reuse it, or pick a different --name.`);
+                return 1;
+            }
+        }
+        throw err;
+    }
     if (!dsId) {
         console.error("Failed to get datasource ID from create response");
         return 1;
     }
-    const tablesBody = await listTablesWithColumns({
-        ...base,
-        id: dsId,
-    });
+    return printDsConnectOutput(base, dsId);
+}
+async function printDsConnectOutput(base, dsId) {
+    const tablesBody = await listTablesWithColumns({ ...base, id: dsId });
     const tables = JSON.parse(tablesBody);
     const output = {
         datasource_id: dsId,
@@ -306,7 +404,6 @@ Options:
   --files <s>          CSV file paths (comma-separated or glob pattern, required)
   --table-prefix <s>   Table name prefix (default: none)
   --batch-size <n>     Rows per batch (default: 500, range: 1-10000)
-  --recreate           First batch uses overwrite (drop/recreate table) then append; use when schema changed
   -bd, --biz-domain    Business domain (default: bd_public)`;
 export function parseImportCsvArgs(args) {
     let datasourceId = "";
@@ -314,7 +411,6 @@ export function parseImportCsvArgs(args) {
     let tablePrefix = "";
     let batchSize = 500;
     let businessDomain = "";
-    let recreate = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -323,10 +419,6 @@ export function parseImportCsvArgs(args) {
             files = args[++i];
             continue;
         }
-        if (arg === "--recreate") {
-            recreate = true;
-            continue;
-        }
         if (arg === "--table-prefix" && args[i + 1]) {
             tablePrefix = args[++i];
             continue;
@@ -349,7 +441,7 @@ export function parseImportCsvArgs(args) {
     }
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { datasourceId, files, tablePrefix, batchSize, businessDomain, recreate };
+    return { datasourceId, files, tablePrefix, batchSize, businessDomain };
 }
 export async function resolveFiles(pattern) {
     const parts = pattern.split(",").map((p) => p.trim()).filter(Boolean);
@@ -452,7 +544,6 @@ export async function runDsImportCsv(args) {
                 tableExist,
                 data: batch,
                 fieldMappings,
-                recreate: options.recreate,
             });
             const t0 = Date.now();
             process.stderr.write(`[${tableName}] batch ${batchLabel} (${rowCount} rows)... `);
@@ -487,6 +578,23 @@ export async function runDsImportCsv(args) {
     if (failed.length > 0) {
         console.error(`Failed tables: ${failed.join(", ")}`);
     }
+    // Refresh the platform metadata catalog so the freshly imported tables
+    // are visible to ds tables / bkn create-from-ds without manual scan.
+    // Best-effort: scan failures shouldn't mask a successful import.
+    if (succeeded.length > 0) {
+        process.stderr.write("Scanning datasource metadata ...\n");
+        try {
+            await scanMetadata({
+                ...base,
+                id: options.datasourceId,
+                dsType: datasourceType,
+                businessDomain: options.businessDomain,
+            });
+        }
+        catch (err) {
+            console.error(`Scan warning (continuing): ${formatHttpError(err)}`);
+        }
+    }
     return { code: failed.length > 0 ? 1 : 0, tables: succeeded, failed, tableColumns, sampleRows };
 }
 export async function runDsImportCsvCommand(args) {

package/dist/commands/import-csv.d.ts

@@ -19,8 +19,6 @@ export interface DagBodyOptions {
     tableExist: boolean;
     data: Array<Record<string, string | null>>;
     fieldMappings: FieldMapping[];
-    /** When true on the first batch (`tableExist` false), use "insert" to force table recreation. */
-    recreate?: boolean;
 }
 /**
  * Read a CSV file and return its headers and rows.

package/dist/commands/import-csv.js

@@ -80,11 +80,9 @@ export function buildFieldMappings(headers) {
  * The DAG has two steps: a manual trigger and the database write.
  */
 export function buildDagBody(options) {
-    const { datasourceId, datasourceType, tableName, tableExist, data, fieldMappings, recreate } = options;
+    const { datasourceId, datasourceType, tableName, tableExist, data, fieldMappings } = options;
     const ts = Date.now();
-    // "insert" creates/replaces the table; "append" adds rows to an existing table.
-    // With --recreate, use "insert" on first batch to force table recreation when schema changed.
-    const operateType = tableExist ? "append" : recreate ? "insert" : "append";
+    const operateType = "append";
     const triggerStep = {
         id: "step-trigger",
         title: "Trigger",

package/dist/commands/skill.js

@@ -1,8 +1,9 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
 import { resolveBusinessDomain } from "../config/store.js";
-import { deleteSkill, downloadSkill, fetchSkillContent, fetchSkillFile, getSkill, getSkillContentIndex, installSkillArchive, listSkillMarket, listSkills, readSkillFile, registerSkillContent, registerSkillZip, updateSkillStatus, } from "../api/skills.js";
+import { deleteSkill, downloadSkill, fetchSkillContent, fetchSkillFile, getSkill, getSkillContentIndex, installSkillArchive, listSkillMarket, listSkills, readSkillFile, registerSkillZip, updateSkillStatus, } from "../api/skills.js";
+import { bundleSkillDirectoryToZip, bundleSkillFileToZip } from "../utils/skill-bundle.js";
 function printSkillHelp(subcommand) {
     if (subcommand === "list") {
         console.log(`kweaver skill list [--name kw] [--source src] [--status status] [--create-user user]
@@ -20,7 +21,15 @@ function printSkillHelp(subcommand) {
     }
     if (subcommand === "register") {
         console.log(`kweaver skill register (--content-file <path> | --zip-file <path>)
-                       [--source src] [--extend-info json] [-bd value] [--pretty|--compact]`);
+                       [--source src] [--extend-info json] [-bd value] [--pretty|--compact]
+
+  --content-file accepts either:
+    - a single file named SKILL.md (auto-bundled into a 1-file zip)
+    - a skill directory containing SKILL.md (bundled into a zip)
+  Both paths upload as multipart zip; the backend's file_type=content
+  registration is unreliable (publish-then-read returns 404) so the CLI
+  always goes through zip.
+  --zip-file accepts a pre-built .zip with SKILL.md at the archive root.`);
         return;
     }
     if (subcommand === "set-status" || subcommand === "status") {
@@ -54,6 +63,7 @@ Subcommands:
   market [--name kw] [--source src] [--page N] [--page-size N] [-bd value]
   get <skill-id> [-bd value]
   register --content-file <path> | --zip-file <path> [--source src] [--extend-info json]
+           (--content-file accepts a file named SKILL.md or a directory; both auto-zip)
   set-status <skill-id> <unpublish|published|offline> [-bd value]
   delete <skill-id> [-y] [-bd value]
   content <skill-id> [--raw] [--output file] [-bd value]
@@ -394,13 +404,23 @@ export async function runSkillCommand(args) {
             if (subcommand === "register") {
                 const opts = parseSkillRegisterArgs(rest);
                 if (opts.contentFile) {
-                    const content = readFileSync(resolve(opts.contentFile), "utf8");
-                    const result = await registerSkillContent({
+                    // Always bundle into zip — the backend's file_type=content path
+                    // doesn't write skill_file_index, so SKILL.md is unreachable
+                    // after publish via /skills/:id/content. Going through zip
+                    // (single SKILL.md or full directory) is the only path that
+                    // produces a readable skill end-to-end.
+                    const abs = resolve(opts.contentFile);
+                    const stat = statSync(abs);
+                    const bytes = stat.isDirectory()
+                        ? await bundleSkillDirectoryToZip(abs)
+                        : await bundleSkillFileToZip(abs);
+                    const result = await registerSkillZip({
                         ...token,
                         businessDomain: opts.businessDomain,
-                        content,
                         source: opts.source,
                         extendInfo: opts.extendInfo,
+                        filename: `${basename(abs).replace(/\.zip$/i, "")}.zip`,
+                        bytes,
                     });
                     console.log(format(result, opts.pretty));
                     return 0;

package/dist/commands/tool.d.ts

@@ -19,6 +19,7 @@ export interface ToolInvokeOptions {
     toolId: string;
     header?: Record<string, unknown>;
     query?: Record<string, unknown>;
+    path?: Record<string, unknown>;
     body?: unknown;
     bodyFile?: string;
     timeout?: number;

package/dist/commands/tool.js

@@ -12,8 +12,10 @@ Subcommands:
   enable --toolbox <box-id> <tool-id>...       Enable one or more tools
   disable --toolbox <box-id> <tool-id>...      Disable one or more tools
   execute --toolbox <box-id> <tool-id> [--body '<json>'|--body-file <path>]
+                                              [--header|--query|--path '<json>']
                                               Invoke a published+enabled tool
   debug   --toolbox <box-id> <tool-id> [--body '<json>'|--body-file <path>]
+                                              [--header|--query|--path '<json>']
                                               Invoke a tool (works on draft/disabled too)
 
 Options for execute/debug:
@@ -21,6 +23,9 @@ Options for execute/debug:
                           (Authorization is auto-injected from current session
                           when --header omits it; pass {} to send none)
   --query  '<json>'       Query params map forwarded to the downstream tool
+  --path   '<json>'       Path parameter map for OpenAPI path placeholders (e.g. {id})
+                          (JSON object: quote id and UUID, e.g. key id for get_dataview_detail /
+                          query_dataview_sql)
   --timeout <seconds>     Per-call timeout (backend default applies when omitted)
 
 Common options:
@@ -241,6 +246,7 @@ export function parseToolInvokeArgs(args) {
     let pretty = true;
     let header;
     let query;
+    let path;
     let body;
     let bodyProvided = false;
     let bodyFile;
@@ -259,6 +265,10 @@ export function parseToolInvokeArgs(args) {
             query = parseJsonOption("--query", args[++i]);
             continue;
         }
+        if (a === "--path" && args[i + 1]) {
+            path = parseJsonOption("--path", args[++i]);
+            continue;
+        }
         if (a === "--body" && args[i + 1]) {
             const raw = args[++i];
             try {
@@ -312,6 +322,7 @@ export function parseToolInvokeArgs(args) {
         toolId,
         header,
         query,
+        path,
         body: bodyProvided ? body : undefined,
         bodyFile,
         timeout,
@@ -370,6 +381,7 @@ async function runToolInvoke(args, action) {
         toolId: opts.toolId,
         header,
         query: opts.query,
+        path: opts.path,
         body,
         timeout: opts.timeout,
     });

package/dist/config/stateless.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stateless token mode: user passed --token on the CLI for this invocation.
+ *
+ * In stateless mode the CLI must not mutate ~/.kweaver/ — we error out from
+ * any command that would write tokens, sessions, or per-platform config.
+ *
+ * KWEAVER_TOKEN env (without --token flag) is NOT considered stateless: the
+ * env-var path predates this feature and keeps its existing semantics for
+ * backward compatibility. The cli.ts argv parser sets KWEAVER_TOKEN_SOURCE=flag
+ * only when --token was passed explicitly.
+ */
+export declare function isStatelessTokenMode(): boolean;
+export declare function assertNotStatelessForWrite(commandName: string): void;

package/dist/config/stateless.js

@@ -0,0 +1,20 @@
+/**
+ * Stateless token mode: user passed --token on the CLI for this invocation.
+ *
+ * In stateless mode the CLI must not mutate ~/.kweaver/ — we error out from
+ * any command that would write tokens, sessions, or per-platform config.
+ *
+ * KWEAVER_TOKEN env (without --token flag) is NOT considered stateless: the
+ * env-var path predates this feature and keeps its existing semantics for
+ * backward compatibility. The cli.ts argv parser sets KWEAVER_TOKEN_SOURCE=flag
+ * only when --token was passed explicitly.
+ */
+export function isStatelessTokenMode() {
+    return process.env.KWEAVER_TOKEN_SOURCE === "flag";
+}
+export function assertNotStatelessForWrite(commandName) {
+    if (isStatelessTokenMode()) {
+        throw new Error(`Cannot run \`${commandName}\` with --token. The --token flag is for stateless invocations and ` +
+            `must not mutate ~/.kweaver/. Drop --token, or use \`kweaver auth login\` to obtain a saved session.`);
+    }
+}

package/dist/config/store.d.ts

@@ -53,6 +53,7 @@ export interface PlatformSummary {
     /** Human-readable name persisted from /oauth2/userinfo at login time. */
     displayName?: string;
 }
+export declare function getProfileName(): string | null;
 /** Extract userId from a TokenConfig (try idToken, then accessToken, fallback "default"). */
 export declare function extractUserId(token: TokenConfig): string;
 /** Get the active userId for a platform. */

package/dist/config/store.js

@@ -29,6 +29,19 @@ const MCP_PATH = "/api/agent-retrieval/v1/mcp";
 function buildMcpUrl(baseUrl) {
     return baseUrl.replace(/\/+$/, "") + MCP_PATH;
 }
+const PROFILE_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+export function getProfileName() {
+    const raw = process.env.KWEAVER_PROFILE;
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    if (!PROFILE_NAME_RE.test(trimmed)) {
+        throw new Error(`KWEAVER_PROFILE='${raw}' is invalid. Use 1-64 chars from [A-Za-z0-9_-].`);
+    }
+    return trimmed;
+}
 function getConfigDirPath() {
     return process.env.KWEAVERC_CONFIG_DIR || join(homedir(), ".kweaver");
 }
@@ -36,6 +49,10 @@ function getPlatformsDirPath() {
     return join(getConfigDirPath(), "platforms");
 }
 function getStateFilePath() {
+    const profile = getProfileName();
+    if (profile) {
+        return join(getConfigDirPath(), "profiles", profile, "state.json");
+    }
     return join(getConfigDirPath(), "state.json");
 }
 function getLegacyClientFilePath() {

package/dist/resources/toolboxes.d.ts

@@ -6,6 +6,8 @@ export interface InvokeToolArgs {
      *  send no headers. */
     header?: Record<string, unknown>;
     query?: Record<string, unknown>;
+    /** Path parameters for OpenAPI `{name}` placeholders (e.g. `{ id: "<uuid>" }`). */
+    path?: Record<string, unknown>;
     body?: unknown;
     /** Per-call timeout in seconds (backend default applies when omitted). */
     timeout?: number;

package/dist/templates/bkn/document/manifest.json

@@ -0,0 +1,12 @@
+{
+  "name": "document",
+  "type": "bkn",
+  "description": "文档知识网络",
+  "arguments": [
+    { "name": "name", "required": true, "description": "BKN 名称", "type": "string" },
+    { "name": "embedding_model_id", "required": true, "description": "向量化模型 ID", "type": "string" },
+    { "name": "content_dataset_id", "required": true, "description": "内容数据集 ID", "type": "string" },
+    { "name": "document_dataset_id", "required": true, "description": "文档数据集 ID", "type": "string" },
+    { "name": "element_dataset_id", "required": true, "description": "元素数据集 ID", "type": "string" }
+  ]
+}