@openbkn/bkn-sdk 0.1.0 → 0.1.1-alpha.1

package/README.md

@@ -92,13 +92,28 @@ Golden `--help` baselines and a full-depth parity test live in
 
 ## Agent skill
 
-An agent skill (`skills/openbkn-core/SKILL.md`) lets AI tools drive the CLI in
-natural language. Install it with the skills CLI:
+`skills/openbkn/` is an agent skill (for Claude Code / the [skills.sh](https://skills.sh)
+ecosystem) that lets an AI drive the `openbkn` CLI from natural language. It
+ships a `SKILL.md` (trigger intents, `allowed-tools: Bash(openbkn *)`, a
+command-group map, examples, and cautions) plus per-domain cheat sheets under
+`references/` (auth, bkn, agent, model, vega, resource, dataflow, context,
+skill, toolbox, trace, admin, call) and two how-tos (build-a-KN, troubleshooting).
+
+The skill is **not** part of the npm package — it's registered separately:
 
 ```bash
-npx skills add openbkn-ai/bkn-sdk@openbkn-core
+# Install the skill (globally), then ask in natural language:
+npx skills add openbkn-ai/bkn-sdk@openbkn -g -y
+
+#   "列出所有知识网络"  /  "list all knowledge networks"
+#   "从 Vega catalog vcat-1 建一个名为 customers 的知识网络并构建索引"
+#   "诊断会话 conv-123 的 trace，带 LLM 判定"
 ```
 
+The skill assumes the `openbkn` CLI is installed (`npm i -g @openbkn/bkn-sdk`)
+and you are logged in (`openbkn auth login`). It always defers to live
+`openbkn <group> <sub> --help` for exact flags.
+
 ## License
 
 Apache-2.0

package/dist/{chunk-4NXAIG4G.js → chunk-ADZ23DPF.js}

@@ -44,9 +44,21 @@ function formatError(err) {
     const detail = err.body ? `: ${truncate(err.body, 500)}` : "";
     return `Request failed (HTTP ${err.status} ${err.statusText})${detail}`;
   }
-  if (err instanceof Error) return err.message;
+  if (err instanceof Error) {
+    const cause = err.cause;
+    if (cause?.code && isTlsCertError(cause.code)) {
+      return `TLS certificate rejected (${cause.code}). The platform is likely self-signed \u2014 retry with \`-k\`/\`--insecure\`.`;
+    }
+    if (err.message === "fetch failed" && cause?.message) {
+      return `Request failed: ${cause.message}${cause.code ? ` (${cause.code})` : ""}`;
+    }
+    return err.message;
+  }
   return String(err);
 }
+function isTlsCertError(code) {
+  return code === "DEPTH_ZERO_SELF_SIGNED_CERT" || code === "SELF_SIGNED_CERT_IN_CHAIN" || code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE" || code === "CERT_HAS_EXPIRED" || code.includes("CERT");
+}
 function truncate(s, n) {
   return s.length > n ? `${s.slice(0, n)}\u2026` : s;
 }
@@ -2696,38 +2708,6 @@ function deleteJobs(ctx, knId, ids) {
   return request(ctx, knPath(knId, `jobs/${ids}`), { method: "DELETE" });
 }
 
-// src/utils/tar.ts
-import { spawnSync } from "child_process";
-import { resolve } from "path";
-var TAR_MISSING = "tar executable not found. On Windows, ensure tar.exe is in PATH (ships with Windows 10 1803+) or install GNU tar via Git for Windows / scoop.";
-function packDirectoryToTar(dirPath) {
-  const abs = resolve(dirPath);
-  const result = spawnSync("tar", ["cf", "-", "-C", abs, "."], {
-    maxBuffer: 1024 * 1024 * 512,
-    env: { ...process.env, COPYFILE_DISABLE: "1" }
-  });
-  if (result.error && result.error.code === "ENOENT") {
-    throw new Error(TAR_MISSING);
-  }
-  if (result.status !== 0) {
-    throw new Error(`tar pack failed: ${result.stderr?.toString() ?? result.status}`);
-  }
-  return result.stdout;
-}
-function extractTarToDirectory(tarBuffer, dirPath) {
-  const abs = resolve(dirPath);
-  const result = spawnSync("tar", ["xf", "-", "-C", abs], {
-    input: tarBuffer,
-    maxBuffer: 1024 * 1024 * 512
-  });
-  if (result.error && result.error.code === "ENOENT") {
-    throw new Error(TAR_MISSING);
-  }
-  if (result.status !== 0) {
-    throw new Error(`tar extract failed: ${result.stderr?.toString() ?? result.status}`);
-  }
-}
-
 // src/api/vega.ts
 import { z } from "zod";
 var VEGA_BASE = "/api/vega-backend/v1";
@@ -2742,14 +2722,28 @@ var CreateBuildTaskRequest = z.object({
 });
 var BuildTask = z.object({
   id: z.string(),
-  resource_id: z.string(),
-  mode: BuildMode,
+  resource_id: z.string().optional(),
+  mode: BuildMode.optional(),
+  status: z.string().optional(),
   state: z.string().optional(),
+  total_count: z.number().optional(),
   synced_count: z.number().optional(),
-  vectorized_count: z.number().optional()
-});
+  vectorized_count: z.number().optional(),
+  embedding_fields: z.string().optional(),
+  build_key_fields: z.string().optional(),
+  embedding_model: z.string().optional(),
+  model_dimensions: z.number().optional()
+}).passthrough();
 async function createBuildTask(ctx, req) {
-  const body = CreateBuildTaskRequest.parse(req);
+  const p = CreateBuildTaskRequest.parse(req);
+  const body = {
+    resource_id: p.resource_id,
+    mode: p.mode,
+    ...p.embedding_fields?.length ? { embedding_fields: p.embedding_fields.join(",") } : {},
+    ...p.build_key_fields?.length ? { build_key_fields: p.build_key_fields.join(",") } : {},
+    ...p.embedding_model ? { embedding_model: p.embedding_model } : {},
+    ...p.model_dimensions ? { model_dimensions: p.model_dimensions } : {}
+  };
   const res = await request(ctx, `${VEGA_BASE}/build-tasks`, { method: "POST", body });
   return BuildTask.parse(res);
 }
@@ -2765,6 +2759,22 @@ async function listCatalogs(ctx, opts = {}) {
 function getCatalog(ctx, id) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}`);
 }
+function createCatalog(ctx, req) {
+  return request(ctx, `${VEGA_BASE}/catalogs`, {
+    method: "POST",
+    body: {
+      name: req.name,
+      connector_type: req.connectorType,
+      connector_config: req.connectorConfig,
+      ...req.tags ? { tags: req.tags } : {},
+      ...req.description ? { description: req.description } : {},
+      ...req.enabled !== void 0 ? { enabled: req.enabled } : {}
+    }
+  });
+}
+function enableCatalog(ctx, id) {
+  return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/enable`, { method: "POST" });
+}
 function discoverCatalog(ctx, id, wait = true) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/discover`, {
     method: "POST",
@@ -2773,8 +2783,8 @@ function discoverCatalog(ctx, id, wait = true) {
   });
 }
 function listCatalogResources(ctx, id, category) {
-  return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/resources`, {
-    query: { category: category || void 0 }
+  return request(ctx, `${VEGA_BASE}/resources`, {
+    query: { catalog_id: id, category: category || void 0 }
   });
 }
 function catalogHealthStatus(ctx, ids) {
@@ -2790,8 +2800,180 @@ function getConnectorType(ctx, type) {
   return request(ctx, `${VEGA_BASE}/connector-types/${encodeURIComponent(type)}`);
 }
 
+// src/utils/bkn-index.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync as readdirSync2, statSync } from "fs";
+import { join as join2 } from "path";
+function rowCells(line) {
+  const t = line.trim();
+  if (!t.startsWith("|")) return null;
+  return t.replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+}
+function isDivider(cells) {
+  return cells.length > 0 && cells.every((c) => /^:?-{2,}:?$/.test(c) || c === "");
+}
+function section(text, headingRe) {
+  const lines = text.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (headingRe.test(lines[i] ?? "")) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start; i < lines.length; i += 1) {
+    if (/^#{1,6}\s/.test(lines[i] ?? "")) break;
+    out.push(lines[i] ?? "");
+  }
+  return out.join("\n");
+}
+function colIndex(header, aliases) {
+  return header.findIndex((h) => aliases.test(h));
+}
+function resourceBinding(text) {
+  const sec = section(text, /^#{2,3}\s*(data\s*source|数据来源)/i);
+  if (!sec) return void 0;
+  let header = null;
+  for (const line of sec.split("\n")) {
+    const cells = rowCells(line);
+    if (!cells || isDivider(cells)) continue;
+    if (!header) {
+      header = cells;
+      continue;
+    }
+    const typeIdx = Math.max(0, colIndex(header, /type|类型/i));
+    const idIdx = colIndex(header, /\bid\b/i);
+    const type = (cells[typeIdx] ?? "").toLowerCase();
+    const id = (cells[idIdx >= 0 ? idIdx : 1] ?? "").trim();
+    if (type === "resource" && id) return id;
+  }
+  return void 0;
+}
+function mappedFields(text) {
+  const map = /* @__PURE__ */ new Map();
+  const sec = section(text, /^#{2,3}\s*(data\s*propert|数据属性)/i);
+  if (!sec) return map;
+  let header = null;
+  for (const line of sec.split("\n")) {
+    const cells = rowCells(line);
+    if (!cells || isDivider(cells)) continue;
+    if (!header) {
+      header = cells;
+      continue;
+    }
+    const nameIdx = Math.max(0, colIndex(header, /^\s*(name|属性名|属性)\s*$/i));
+    const mapIdx = colIndex(header, /mapped\s*field|映射字段|映射/i);
+    const name = cells[nameIdx] ?? "";
+    if (!name) continue;
+    map.set(name, (mapIdx >= 0 ? cells[mapIdx] : void 0) || name);
+  }
+  return map;
+}
+function vectorProps(text) {
+  const names = /* @__PURE__ */ new Set();
+  let model;
+  const scan = (sec) => {
+    if (!sec) return;
+    let header = null;
+    for (const line of sec.split("\n")) {
+      const cells = rowCells(line);
+      if (!cells || isDivider(cells)) continue;
+      if (!header) {
+        header = cells;
+        continue;
+      }
+      const nameIdx = Math.max(0, colIndex(header, /^\s*(name|属性名|属性)\s*$/i));
+      const idxCol = colIndex(header, /索引配置|索引|index\s*config|index/i);
+      const cfg = idxCol >= 0 ? cells[idxCol] ?? "" : "";
+      if (/vector/i.test(cfg)) {
+        const name = cells[nameIdx] ?? "";
+        if (name) names.add(name);
+        const m = cfg.match(/vector\s*\(\s*([^)]+?)\s*\)/i);
+        if (m?.[1]) model = m[1];
+      }
+    }
+  };
+  scan(section(text, /^#{2,3}\s*(property\s*overrides|属性覆盖)/i));
+  scan(section(text, /^#{2,3}\s*(data\s*propert|数据属性)/i));
+  return { names: [...names], ...model ? { model } : {} };
+}
+function buildKey(text) {
+  const clean = (v) => v.replace(/`/g, "").split(/[,，]/)[0]?.trim() || void 0;
+  const incr = text.match(/Incremental[ \t]*Key[ \t]*[:：][ \t]*([^\n]+)/i);
+  if (incr?.[1]?.trim()) return clean(incr[1]);
+  const pk = text.match(/Primary[ \t]*Keys?[ \t]*[:：][ \t]*([^\n]+)/i) || text.match(/\*\*[ \t]*主键[ \t]*\*\*[ \t]*[:：][ \t]*([^|\n]+)/);
+  if (pk?.[1]?.trim()) return clean(pk[1]);
+  return void 0;
+}
+function frontmatterId(text) {
+  if (!text.startsWith("---")) return void 0;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return void 0;
+  const m = text.slice(3, end).match(/^\s*id\s*:\s*(.+?)\s*$/m);
+  return m?.[1]?.replace(/^["']|["']$/g, "");
+}
+function parseObjectTypeIndex(text, fallbackName = "") {
+  const resourceId = resourceBinding(text);
+  if (!resourceId || resourceId.includes("{{")) return null;
+  const { names, model } = vectorProps(text);
+  if (names.length === 0) return null;
+  const mapped = mappedFields(text);
+  const embeddingFields = names.map((n) => mapped.get(n) ?? n);
+  return {
+    objectType: frontmatterId(text) ?? fallbackName,
+    resourceId,
+    embeddingFields,
+    ...buildKey(text) ? { buildKey: buildKey(text) } : {},
+    ...model ? { embeddingModel: model } : {}
+  };
+}
+function collectIndexTargets(dir) {
+  const otDir = join2(dir, "object_types");
+  if (!existsSync2(otDir) || !statSync(otDir).isDirectory()) return [];
+  const targets = [];
+  for (const f of readdirSync2(otDir).filter((x) => x.endsWith(".bkn"))) {
+    const stem = f.replace(/\.bkn$/, "");
+    const target = parseObjectTypeIndex(readFileSync2(join2(otDir, f), "utf8"), stem);
+    if (target) targets.push(target);
+  }
+  return targets;
+}
+
+// src/utils/tar.ts
+import { spawnSync } from "child_process";
+import { resolve } from "path";
+var TAR_MISSING = "tar executable not found. On Windows, ensure tar.exe is in PATH (ships with Windows 10 1803+) or install GNU tar via Git for Windows / scoop.";
+function packDirectoryToTar(dirPath) {
+  const abs = resolve(dirPath);
+  const result = spawnSync("tar", ["cf", "-", "-C", abs, "."], {
+    maxBuffer: 1024 * 1024 * 512,
+    env: { ...process.env, COPYFILE_DISABLE: "1" }
+  });
+  if (result.error && result.error.code === "ENOENT") {
+    throw new Error(TAR_MISSING);
+  }
+  if (result.status !== 0) {
+    throw new Error(`tar pack failed: ${result.stderr?.toString() ?? result.status}`);
+  }
+  return result.stdout;
+}
+function extractTarToDirectory(tarBuffer, dirPath) {
+  const abs = resolve(dirPath);
+  const result = spawnSync("tar", ["xf", "-", "-C", abs], {
+    input: tarBuffer,
+    maxBuffer: 1024 * 1024 * 512
+  });
+  if (result.error && result.error.code === "ENOENT") {
+    throw new Error(TAR_MISSING);
+  }
+  if (result.status !== 0) {
+    throw new Error(`tar extract failed: ${result.stderr?.toString() ?? result.status}`);
+  }
+}
+
 // src/utils/csv-import.ts
-import { statSync } from "fs";
+import { statSync as statSync2 } from "fs";
 import { glob, readFile } from "fs/promises";
 import { basename, resolve as resolve2 } from "path";
 import { parse } from "csv-parse/sync";
@@ -2866,7 +3048,7 @@ async function resolveFiles(pattern) {
         if (/\.csv$/i.test(p)) out.push(resolve2(p));
       }
     } else {
-      statSync(resolve2(part));
+      statSync2(resolve2(part));
       out.push(resolve2(part));
     }
   }
@@ -2925,6 +3107,20 @@ function parsePkMap(input) {
   }
   return out;
 }
+function parseEmbeddingFields(input) {
+  const out = {};
+  for (const pair of input.split(",").map((s) => s.trim()).filter(Boolean)) {
+    const idx = pair.indexOf(":");
+    if (idx <= 0 || idx >= pair.length - 1) {
+      throw new Error(
+        `Invalid --embedding-fields entry '${pair}'. Expected '<table>:<col>[+<col>...][,...]'`
+      );
+    }
+    const cols = pair.slice(idx + 1).split("+").map((c) => c.trim()).filter(Boolean);
+    if (cols.length > 0) out[pair.slice(0, idx).trim()] = cols;
+  }
+  return out;
+}
 function formatPkDetectionError(tableName, result) {
   const lines = [`Cannot auto-detect a primary key for table '${tableName}'.`];
   if (result.sampleSize === 0) {
@@ -3083,10 +3279,13 @@ async function createFromCatalog(ctx, opts) {
     if (opts.build) {
       log("Submitting build tasks...");
       for (const t of targets) {
+        const embedding = opts.embeddingFields?.[t.name];
         const task = await createBuildTask(ctx, {
           resource_id: viewMap[t.name],
           mode: "batch",
-          build_key_fields: [tablePk[t.name]]
+          build_key_fields: [tablePk[t.name]],
+          ...embedding && embedding.length > 0 ? { embedding_fields: embedding } : {},
+          ...opts.embeddingModel ? { embedding_model: opts.embeddingModel } : {}
         });
         builds.push({ table: t.name, taskId: String(task.id ?? "") });
       }
@@ -3179,6 +3378,8 @@ async function createFromCsv(ctx, opts) {
     tables: opts.tables && opts.tables.length > 0 ? opts.tables : imported.tables,
     pkMap: opts.pkMap,
     build: opts.build,
+    embeddingFields: opts.embeddingFields,
+    embeddingModel: opts.embeddingModel,
     noRollback: opts.noRollback,
     sampleRows: imported.sampleRows,
     onProgress: log
@@ -3251,8 +3452,32 @@ function kn(ctx) {
     bknResources: () => listBknResources(ctx),
     createFromCatalog: (opts) => createFromCatalog(ctx, opts),
     createFromCsv: (opts) => createFromCsv(ctx, opts),
-    /** Pack a local BKN directory and upload it as a knowledge network. */
-    push: (dir, opts) => uploadBkn(ctx, packDirectoryToTar(dir), opts),
+    /**
+     * Pack a local BKN directory and upload it as a knowledge network. With
+     * `build`, also submit one Vega BuildTask per object type that declares a
+     * `vector` index — the platform does not auto-build these on import.
+     */
+    push: async (dir, opts) => {
+      const upload = await uploadBkn(ctx, packDirectoryToTar(dir), { branch: opts?.branch });
+      if (!opts?.build) return upload;
+      const targets = collectIndexTargets(dir);
+      const buildTasks = [];
+      for (const t of targets) {
+        const task = await createBuildTask(ctx, {
+          resource_id: t.resourceId,
+          mode: "batch",
+          embedding_fields: t.embeddingFields,
+          ...t.buildKey ? { build_key_fields: [t.buildKey] } : {},
+          ...t.embeddingModel ?? opts.embeddingModel ? { embedding_model: t.embeddingModel ?? opts.embeddingModel } : {}
+        });
+        buildTasks.push({
+          objectType: t.objectType,
+          resourceId: t.resourceId,
+          taskId: String(task.id ?? "")
+        });
+      }
+      return { ...upload, build_tasks: buildTasks };
+    },
     /** Download a knowledge network and extract it into a local directory. */
     pull: async (knId, dir, opts) => {
       const tar = await downloadBkn(ctx, knId, opts);
@@ -3505,26 +3730,26 @@ function setSkillStatus(ctx, skillId, status2) {
 }
 
 // src/utils/skill-archive.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync2, readdirSync as readdirSync2, statSync as statSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname, join as join2, relative, resolve as resolve4, sep } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, readdirSync as readdirSync3, statSync as statSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, join as join3, relative, resolve as resolve4, sep } from "path";
 import JSZip from "jszip";
 function walk(dir, base, files) {
-  for (const entry of readdirSync2(dir)) {
-    const full = join2(dir, entry);
-    const st = statSync2(full);
+  for (const entry of readdirSync3(dir)) {
+    const full = join3(dir, entry);
+    const st = statSync3(full);
     if (st.isDirectory()) walk(full, base, files);
     else files.push(full);
   }
 }
 async function zipDirectory(dir) {
   const abs = resolve4(dir);
-  if (!existsSync2(abs)) throw new Error(`directory not found: ${abs}`);
+  if (!existsSync3(abs)) throw new Error(`directory not found: ${abs}`);
   const zip = new JSZip();
   const files = [];
   walk(abs, abs, files);
   for (const file of files) {
     const rel = relative(abs, file).split(sep).join("/");
-    zip.file(rel, readFileSync2(file));
+    zip.file(rel, readFileSync3(file));
   }
   return new Uint8Array(await zip.generateAsync({ type: "uint8array", compression: "DEFLATE" }));
 }
@@ -3536,7 +3761,7 @@ async function unzipToDirectory(bytes, dir) {
   const entries = Object.values(zip.files);
   for (const entry of entries) {
     if (entry.dir) continue;
-    const out = join2(abs, entry.name);
+    const out = join3(abs, entry.name);
     mkdirSync3(dirname(out), { recursive: true });
     writeFileSync2(out, await entry.async("nodebuffer"));
     written.push(out);
@@ -4525,11 +4750,14 @@ function trace(ctx) {
 }
 
 // src/resources/vega.ts
-var TERMINAL_STATES = /* @__PURE__ */ new Set(["completed", "success", "failed"]);
+var TERMINAL_STATES = /* @__PURE__ */ new Set(["completed", "success", "failed", "stopped", "error"]);
 function vega(ctx) {
   return {
     catalogs: (opts) => listCatalogs(ctx, opts),
     getCatalog: (id) => getCatalog(ctx, id),
+    createCatalog: (req) => createCatalog(ctx, req),
+    enableCatalog: (id) => enableCatalog(ctx, id),
+    discoverCatalog: (id, wait = false) => discoverCatalog(ctx, id, wait),
     catalogResources: (id, category) => listCatalogResources(ctx, id, category),
     catalogHealth: (ids) => catalogHealthStatus(ctx, ids),
     connectorTypes: () => listConnectorTypes(ctx),
@@ -4545,8 +4773,9 @@ function vega(ctx) {
 }
 async function pollBuildTask(ctx, taskId, timeoutMs, intervalMs) {
   const deadline = Date.now() + timeoutMs;
+  const terminal = (t) => TERMINAL_STATES.has((t.status ?? t.state ?? "").toLowerCase());
   let last = await getBuildTask(ctx, taskId);
-  while (!TERMINAL_STATES.has((last.state ?? "").toLowerCase()) && Date.now() < deadline) {
+  while (!terminal(last) && Date.now() < deadline) {
     await sleep(intervalMs);
     last = await getBuildTask(ctx, taskId);
   }
@@ -4557,7 +4786,7 @@ function sleep(ms) {
 }
 
 // src/api/call.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 function parseHeader(raw) {
   const idx = raw.indexOf(":");
   if (idx <= 0) return null;
@@ -4587,7 +4816,7 @@ async function rawCall(ctx, path, opts = {}) {
     const fd = new FormData();
     for (const field of opts.form) {
       const [key, value, isFile] = parseFormField(field);
-      if (isFile) fd.append(key, new Blob([readFileSync3(value)]), value.split("/").pop());
+      if (isFile) fd.append(key, new Blob([readFileSync4(value)]), value.split("/").pop());
       else fd.append(key, value);
     }
     body = fd;
@@ -4780,6 +5009,7 @@ export {
   context,
   dataflows,
   parsePkMap,
+  parseEmbeddingFields,
   kn,
   models,
   resources,
@@ -4802,4 +5032,4 @@ export {
   exportCreds,
   auth_exports
 };
-//# sourceMappingURL=chunk-4NXAIG4G.js.map
+//# sourceMappingURL=chunk-ADZ23DPF.js.map