@kweaver-ai/kweaver-sdk 0.7.1 → 0.7.2

package/README.md

@@ -31,7 +31,7 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
-With both set, API commands use that token even if you never ran `auth login`. You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/`. In env-token mode, `whoami` resolves the bound identity from EACP `/api/eacp/v1/user/get` and prints `Type` (user/app), `User ID`, `Account` and `Name`; this works for both opaque and JWT tokens. If EACP is unreachable, the CLI falls back to local JWT decode and prints a short hint when the token is opaque.
+With both set, API commands use that token even if you never ran `auth login`. The same applies to **`kweaver --base-url <url> --token <access-token> <command>`** (stateless flag mode; see [Stateless token mode](#stateless-token-mode)). You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/`. In env-token mode, `whoami` resolves the bound identity from EACP `/api/eacp/v1/user/get` and prints `Type` (user/app), `User ID`, `Account` and `Name`; this works for both opaque and JWT tokens. If EACP is unreachable, the CLI falls back to local JWT decode and prints a short hint when the token is opaque.
 
 `kweaver config list-bd` lists business domains for the current user. App (service) tokens are not bound to an end-user — when the backend rejects the call with `401 invalid user_id`, the CLI re-checks the token type via EACP and, if confirmed `type:"app"`, replaces the cryptic backend body with `This command does not support app accounts.`. Use a user token (interactive `auth login`) for user-bound endpoints.
 
@@ -188,8 +188,10 @@ kweaver bkn action-log list/get/cancel
 kweaver agent list/get/create/update/delete/chat/sessions/history/publish/unpublish
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
 kweaver vega health/stats/inspect/sql/catalog/resource/connector-type
-kweaver context-loader config set/use/list/show
-kweaver context-loader search-schema/tool-call/kn-search/query-object-instance/find-skills/...
+kweaver context-loader tools|resources|templates|prompts <kn-id>
+kweaver context-loader search-schema|tool-call|kn-search|kn-schema-search <kn-id> <query|name> [...]
+kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
+kweaver context-loader config set/use/list/show                       (deprecated; <kn-id> may be omitted to fall back to saved config)
 kweaver toolbox create/list/publish/unpublish/delete
 kweaver tool upload/list/enable/disable
 kweaver call <path> [-X METHOD] [-d BODY] [-H header] [-F key=value]
@@ -251,10 +253,33 @@ kweaver tool enable --toolbox <BOX_ID> <TOOL_ID>
 | `KWEAVER_BASE_URL` | KWeaver instance URL |
 | `KWEAVER_BUSINESS_DOMAIN` | Business domain identifier |
 | `KWEAVER_TOKEN` | Access token |
+| `KWEAVER_TOKEN_SOURCE` | Internal sentinel set by the CLI when `--token` is passed; do not set manually |
 | `KWEAVER_NO_AUTH` | Set to `1`/`true`/`yes` to use no-auth sentinel when `KWEAVER_TOKEN` is unset (with `KWEAVER_BASE_URL` or active platform) |
 | `KWEAVER_TLS_INSECURE` | Set to `1` or `true` to skip TLS certificate verification for all HTTPS in the process (dev only; prefer `kweaver auth … --insecure` which saves per platform) |
 | `NODE_TLS_REJECT_UNAUTHORIZED` | Node.js built-in TLS switch: set to `0` to skip certificate verification for HTTPS in this process. The `kweaver` CLI sets this when `KWEAVER_TLS_INSECURE` is set or the saved token has insecure TLS (same scope as above; dev only). |
 
+### Stateless token mode
+
+Pass an access token via `--token` for fully stateless invocations (no read or write of `~/.kweaver/` for that token):
+
+```bash
+kweaver --base-url https://platform.example.com --token "$TOK" bkn list
+```
+
+Resolution order:
+
+| Source | base-url | token |
+|--------|----------|-------|
+| flag   | `--base-url` | `--token` |
+| env    | `KWEAVER_BASE_URL` | `KWEAVER_TOKEN` |
+| disk   | active platform | OAuth session (refreshable) |
+
+When `--token` is used, write-disk commands (`auth login` / `logout` / `use` / `delete` / `switch`, `config set-bd`, the entire `context-loader config` group) error out — drop `--token` or use `kweaver auth login` for a saved session.
+
+`auth whoami` / `auth status` distinguish the two stateless modes: `Source: CLI (flag: --token)` for flag mode, `env (KWEAVER_TOKEN)` for env mode (`whoami --json` uses `"source": "flag"` vs `"source": "env"`).
+
+`kweaver context-loader` runtime subcommands accept `<kn-id>` as the first positional (e.g. `kweaver context-loader tools <kn-id>`) or via the global `--kn-id <id>` / `-k <id>` flag, so they work in stateless mode without any saved config. The `context-loader config set|use|list|remove|show` management group is deprecated, prints a warning on use, and is disabled in its entirety under `--token`.
+
 ### TLS Certificate Troubleshooting
 
 If you encounter errors like `fetch failed`, `self-signed certificate`, or `UNABLE_TO_GET_ISSUER_CERT`, the target server likely uses a self-signed certificate or Kubernetes Ingress default fake certificate. Try the following in order of preference:

package/README.zh.md

@@ -176,8 +176,10 @@ kweaver bkn action-log list/get/cancel
 kweaver agent list/get/chat/sessions/history
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
 kweaver vega health|stats|inspect|sql|catalog|resource|connector-type
-kweaver context-loader config set/use/list/show
-kweaver context-loader search-schema/tool-call/kn-search/query-object-instance/find-skills/...
+kweaver context-loader tools|resources|templates|prompts <kn-id>
+kweaver context-loader search-schema|tool-call|kn-search|kn-schema-search <kn-id> <query|name> [...]
+kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
+kweaver context-loader config set/use/list/show                       （deprecated；省略 <kn-id> 时回退到已保存配置）
 kweaver call <path> [-X METHOD] [-d BODY] [-H header]
 ```
 
@@ -218,10 +220,33 @@ kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} L
 | `KWEAVER_BASE_URL` | KWeaver 实例地址 |
 | `KWEAVER_BUSINESS_DOMAIN` | 业务域标识 |
 | `KWEAVER_TOKEN` | 访问令牌 |
+| `KWEAVER_TOKEN_SOURCE` | CLI 传入 `--token` 时由程序设置的内部标记；请勿手动设置 |
 | `KWEAVER_NO_AUTH` | 设为 `1`/`true`/`yes` 且未设置 `KWEAVER_TOKEN` 时使用 no-auth 占位（需 `KWEAVER_BASE_URL` 或已选平台） |
 | `KWEAVER_TLS_INSECURE` | 设为 `1` 或 `true` 时跳过 TLS 证书校验（仅开发；更推荐 `kweaver auth … --insecure` 以按平台持久化） |
 | `NODE_TLS_REJECT_UNAUTHORIZED` | Node.js 内置 TLS 开关：设为 `0` 时在本进程内跳过 HTTPS 证书校验。`kweaver` 在 `KWEAVER_TLS_INSECURE` 生效或已保存 token 为不安全 TLS 时会设置此项（范围同上；仅开发）。 |
 
+### Stateless token 模式
+
+通过 `--token` 传入访问令牌，该次调用对该 token 路径既不读也不写 `~/.kweaver/`：
+
+```bash
+kweaver --base-url https://platform.example.com --token "$TOK" bkn list
+```
+
+来源优先级：
+
+| 来源 | base-url | token |
+|------|----------|-------|
+| flag | `--base-url` | `--token` |
+| env  | `KWEAVER_BASE_URL` | `KWEAVER_TOKEN` |
+| 磁盘 | active platform | OAuth 会话（可 refresh） |
+
+`--token` 模式下会禁用写盘命令：`auth login` / `logout` / `use` / `delete` / `switch`、`config set-bd`、整个 `context-loader config` 子命令组 ——去掉 `--token` 或改用 `kweaver auth login`。
+
+`auth whoami` / `auth status` 通过文案区分来源：flag 模式为 `CLI (flag: --token)`，env 模式为 `env (KWEAVER_TOKEN)`（`whoami --json` 为 `"source": "flag"` 与 `"source": "env"`）。
+
+`kweaver context-loader` 运行时子命令将 `<kn-id>` 作为第一个位置参数（如 `kweaver context-loader tools <kn-id>`），也支持全局 `--kn-id <id>` / `-k <id>` flag，因此在 stateless 模式下可直接使用，无需任何持久化配置。`context-loader config set|use|list|remove|show` 管理子命令已被标记为 deprecated（每次调用打印警告），且在 `--token` 下整组被禁用。
+
 ### TLS 证书问题排查
 
 如果遇到 `fetch failed`、`self-signed certificate`、`UNABLE_TO_GET_ISSUER_CERT` 等 TLS 相关错误，通常是目标服务器使用了自签名证书或 Kubernetes Ingress 默认假证书。可按优先级尝试以下方案：

package/dist/api/skills.js

@@ -103,18 +103,20 @@ export async function updateSkillStatus(options) {
 }
 export async function registerSkillContent(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills`);
-    const payload = {
-        file_type: "content",
-        file: options.content,
-    };
+    const form = new FormData();
+    form.set("file_type", "content");
+    // Backend's gin form-binder rejects plain string field for `file`
+    // (typed json.RawMessage); needs an actual multipart file part with
+    // filename. See utils/gin.go GetBindMultipartFormRaw.
+    form.set("file", new Blob([options.content], { type: "text/markdown" }), "SKILL.md");
     if (options.source)
-        payload.source = options.source;
+        form.set("source", options.source);
     if (options.extendInfo)
-        payload.extend_info = options.extendInfo;
+        form.set("extend_info", JSON.stringify(options.extendInfo));
     const { body } = await fetchTextOrThrow(url, {
         method: "POST",
-        headers: { ...baseHeaders(options), "content-type": "application/json" },
-        body: JSON.stringify(payload),
+        headers: baseHeaders(options),
+        body: form,
     });
     return normalizeSkillId(unwrapEnvelope(body));
 }

package/dist/cli.js

@@ -19,7 +19,7 @@ function printHelp() {
     console.log(`kweaver
 
 Usage:
-  kweaver [--user <userId|username>] <command> [options]
+  kweaver [--base-url <url>] [--token <access-token>] [--user <userId|username>] <command> [options]
   kweaver --version | -V
   kweaver --help | -h
 
@@ -60,6 +60,7 @@ Usage:
   kweaver ds delete <id> [-y]
   kweaver ds tables <id> [--keyword X]
   kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema S] [--name N]
+                     [--reuse-existing|--force-new]
 
   kweaver dataflow list [-bd value]
   kweaver dataflow run <dagId> (--file <path> | --url <remote-url> --name <filename>) [-bd value]
@@ -123,18 +124,21 @@ Usage:
   kweaver vega query execute|sql [options]
   kweaver vega connector-type list|get [options]
 
-  kweaver context-loader config set|use|list|remove|show [options]
-  kweaver context-loader tools|resources|templates|prompts [--cursor]
-  kweaver context-loader resource <uri>
-  kweaver context-loader prompt <name> [--args json]
-  kweaver context-loader search-schema <query> [--scope object,relation,action,metric] [--max N]
-  kweaver context-loader tool-call <name> --args '<json>'
-  kweaver context-loader kn-search <query> [--only-schema]      (compat HTTP)
-  kweaver context-loader kn-schema-search <query> [--max N]     (compat HTTP)
-  kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills ...
+  kweaver context-loader config set|use|list|remove|show [options]                (deprecated; not supported with --token)
+  kweaver context-loader tools|resources|templates|prompts <kn-id> [--cursor]
+  kweaver context-loader resource <kn-id> <uri>
+  kweaver context-loader prompt <kn-id> <name> [--args json]
+  kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--max N]
+  kweaver context-loader tool-call <kn-id> <name> --args '<json>'
+  kweaver context-loader kn-search <kn-id> <query> [--only-schema]                 (compat HTTP)
+  kweaver context-loader kn-schema-search <kn-id> <query> [--max N]                (compat HTTP)
+  kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
+                                                          (omit <kn-id> to fall back to deprecated saved config)
   (alias: kweaver context ...)
 
 Global options:
+  --base-url <url>  Override platform base URL for this command (env: KWEAVER_BASE_URL)
+  --token <value>   Override access token for this command (env: KWEAVER_TOKEN; disables write-to-disk commands)
   --user <id|name>  Use a specific user's credentials for this command (env: KWEAVER_USER)
   --pretty / --compact
                     Toggle pretty-printed JSON output. Supported by every
@@ -165,12 +169,40 @@ export async function run(argv) {
         !process.env.KWEAVER_TOKEN) {
         process.env.KWEAVER_TOKEN = NO_AUTH_TOKEN;
     }
-    // Global --user flag: override active user for this invocation
-    const userIdx = argv.indexOf("--user");
+    // Global flags consumed before subcommand dispatch.
+    // Pattern follows --user (legacy): each flag, if present, is removed from argv
+    // and projected into a process.env value that downstream resolvers already read.
     let filteredArgv = argv;
-    if (userIdx !== -1 && userIdx + 1 < argv.length) {
-        process.env.KWEAVER_USER = argv[userIdx + 1];
-        filteredArgv = [...argv.slice(0, userIdx), ...argv.slice(userIdx + 2)];
+    function consumeFlag(flag) {
+        const idx = filteredArgv.indexOf(flag);
+        if (idx === -1 || idx + 1 >= filteredArgv.length)
+            return undefined;
+        const value = filteredArgv[idx + 1];
+        filteredArgv = [...filteredArgv.slice(0, idx), ...filteredArgv.slice(idx + 2)];
+        return value;
+    }
+    const userVal = consumeFlag("--user");
+    if (userVal)
+        process.env.KWEAVER_USER = userVal;
+    const tokenVal = consumeFlag("--token");
+    const baseUrlVal = consumeFlag("--base-url");
+    if (tokenVal) {
+        process.env.KWEAVER_TOKEN = tokenVal;
+        process.env.KWEAVER_TOKEN_SOURCE = "flag";
+    }
+    if (baseUrlVal) {
+        process.env.KWEAVER_BASE_URL = baseUrlVal;
+    }
+    // --token requires a base URL from somewhere; fail fast with guidance.
+    if (tokenVal && !process.env.KWEAVER_BASE_URL) {
+        const { getCurrentPlatform } = await import("./config/store.js");
+        if (!getCurrentPlatform()) {
+            console.error("--token requires a base URL. Provide one of:\n" +
+                "  --base-url <url>\n" +
+                "  export KWEAVER_BASE_URL=<url>\n" +
+                "  kweaver auth login <url>   (save once, reuse later)");
+            return 1;
+        }
     }
     const [command, ...rest] = filteredArgv;
     if (command === "--version" || command === "-V" || command === "version") {

package/dist/commands/auth.js

@@ -1,4 +1,5 @@
 import { isNoAuth } from "../config/no-auth.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
 import { autoSelectBusinessDomain, clearPlatformSession, deletePlatform, deleteUser, getActiveUser, getConfigDir, getCurrentPlatform, getPlatformAlias, hasPlatform, listPlatforms, listUserProfiles, loadClientConfig, loadTokenConfig, loadUserTokenConfig, resolveBusinessDomain, resolvePlatformIdentifier, resolveUserId, saveNoAuthPlatform, setActiveUser, setCurrentPlatform, setPlatformAlias, } from "../config/store.js";
 import { decodeJwtPayload } from "../config/jwt.js";
 import { eacpModifyPassword } from "../auth/eacp-modify-password.js";
@@ -71,6 +72,13 @@ Login options:
     const LOGIN_SUBCOMMANDS = new Set(["status", "list", "use", "delete", "logout", "export", "whoami", "users", "switch"]);
     if (target && !LOGIN_SUBCOMMANDS.has(target)) {
         try {
+            try {
+                assertNotStatelessForWrite("auth login");
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                return 1;
+            }
             const normalizedTarget = normalizeBaseUrl(target);
             const alias = readOption(args, "--alias");
             let username = readOption(args, "--username") ?? readOption(args, "-u");
@@ -268,7 +276,8 @@ Login options:
             }
             console.log(`Config directory: ${getConfigDir()}`);
             console.log(`Platform:         ${active.url} (KWEAVER_BASE_URL)`);
-            console.log(`Token present:    yes (KWEAVER_TOKEN)`);
+            const tokenProvenance = process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "CLI (flag: --token)" : "KWEAVER_TOKEN";
+            console.log(`Token present:    yes (${tokenProvenance})`);
             console.log(`Refresh token:    n/a (env)`);
             return 0;
         }
@@ -358,6 +367,13 @@ Login options:
             console.error(`No saved token for ${useTarget}. Run \`kweaver auth login ${useTarget}\` first.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth use");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         setCurrentPlatform(useTarget);
         console.log(`Current platform: ${useTarget}`);
         return 0;
@@ -375,6 +391,13 @@ Login options:
             console.error(`No saved token for ${deleteTarget}.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth delete");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         if (deleteUserArg) {
             const deleteUserId = resolveUserId(deleteTarget, deleteUserArg) ?? deleteUserArg;
             deleteUser(deleteTarget, deleteUserId);
@@ -404,6 +427,13 @@ Login options:
             console.error(`No saved token for ${logoutTarget}.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth logout");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         const logoutUserId = logoutUserArg ? resolveUserId(logoutTarget, logoutUserArg) ?? logoutUserArg : undefined;
         clearPlatformSession(logoutTarget, logoutUserId);
         const userHint = logoutUserId ? ` (user: ${logoutUserId})` : "";
@@ -487,6 +517,13 @@ You can specify either the userId (sub claim) or the username (preferred_usernam
         }
         return 1;
     }
+    try {
+        assertNotStatelessForWrite("auth switch");
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
     setActiveUser(platform, resolvedId);
     const profiles = listUserProfiles(platform);
     const profile = profiles.find((p) => p.userId === resolvedId);
@@ -535,7 +572,10 @@ Options:
         // complete picture without forcing them to pick a mode.
         const jwtPayload = decodeJwtPayload(accessToken);
         if (jsonOutput) {
-            const out = { platform: envUrl, source: "env" };
+            const out = {
+                platform: envUrl,
+                source: process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "flag" : "env",
+            };
             if (userInfo)
                 out.userInfo = userInfo;
             if (jwtPayload)
@@ -544,7 +584,7 @@ Options:
             return 0;
         }
         console.log(`Platform: ${envUrl}`);
-        console.log(`Source:   env (KWEAVER_TOKEN)`);
+        console.log(`Source:   ${process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "CLI (flag: --token)" : "env (KWEAVER_TOKEN)"}`);
         if (userInfo) {
             console.log(`Type:     ${userInfo.type}`);
             console.log(`User ID:  ${userInfo.id}`);

package/dist/commands/bkn-ops.d.ts

@@ -1,4 +1,6 @@
 import { type BknEncodingImportOptions } from "../utils/bkn-encoding.js";
+export declare const BKN_OBJECT_NAME_MAX_LENGTH = 40;
+export declare function assertValidBknObjectNames(names: string[], context: string): void;
 export declare function parseKnBuildArgs(args: string[]): {
     knId: string;
     wait: boolean;
@@ -34,6 +36,7 @@ export declare function parseKnCreateFromDsArgs(args: string[]): {
     timeout: number;
     businessDomain: string;
     pretty: boolean;
+    noRollback: boolean;
 };
 /** Generate a BKN ObjectType YAML markdown file for a table. */
 export declare function generateObjectTypeBkn(tableName: string, dvId: string, pk: string, dk: string, columns: Array<{
@@ -52,6 +55,7 @@ export declare function parseKnCreateFromCsvArgs(args: string[]): {
     recreate: boolean;
     timeout: number;
     businessDomain: string;
+    noRollback: boolean;
 };
 export declare function runKnCreateFromCsvCommand(args: string[]): Promise<number>;
 export interface ActionScheduleParsed {