@openbkn/bkn-sdk 0.1.3 → 0.1.5-rc.1

package/README.md

@@ -20,7 +20,7 @@ npm install -g @openbkn/bkn-sdk   # CLI: `openbkn`
 npm install @openbkn/bkn-sdk
 ```
 
-Requires Node ≥ 22.19.
+Requires Node ≥ 22.19.0.
 
 ## CLI
 
@@ -38,25 +38,27 @@ openbkn bkn object-type list <kn-id>
 # Data platform
 openbkn resource list --type table
 openbkn vega catalog list
-openbkn dataflow list
 openbkn model llm list
 
-# Agents
-openbkn agent list
-openbkn agent sessions <agent-key>
-
 # Operator (nested)
 openbkn admin org list
 openbkn admin role list
 
 # Raw passthrough to any endpoint
-openbkn call /api/ontology-manager/v1/knowledge-networks
+openbkn call /api/bkn-backend/v1/knowledge-networks
 
 # Global flags: --base-url, --token, --user, --json/--compact, -bd/--biz-domain, -k/--insecure,
 #               --conversation-id/--interaction-id (BKN Trace correlation; also BKN_CONVERSATION_ID/BKN_INTERACTION_ID)
+#               --new-conversation (ignore the remembered conversation for this command)
 openbkn --help        # grouped command map
 ```
 
+On a `managed-v2` deploy, commands continue the conversation the previous one
+opened, so work spanning several commands lands in one thread. `openbkn context conversation` shows which
+is in force and where it came from; `--forget` drops it. An explicit `--token` /
+`BKN_TOKEN` opts out (identity there is the token, not the stored user) — use
+`BKN_CONVERSATION_ID` to thread such a script's commands together.
+
 Tokens are stored per platform/user under `~/.bkn/` (override: `BKN_CONFIG_DIR`).
 
 ## SDK
@@ -73,6 +75,10 @@ const raw = await bkn.call("/api/...", { method: "GET" });
 
 Importing the package has no side effects; `createClient` resolves config explicitly.
 
+Dynamic-data responses (including Vega and ontology queries) may contain native
+`bigint` values for integers outside JavaScript's safe range. Serialize such a result with the exported
+`stringifyBigIntJSON()` helper instead of native `JSON.stringify()`.
+
 ## Develop
 
 ```bash
@@ -86,7 +92,8 @@ npm run build    # tsup → dist/ (library + `openbkn` bin)
 
 Every command, subcommand, and sub-subcommand ships a grouped `--help` that
 lists its flags and arguments, so the tree is discoverable end to end.
-`openbkn help all` dumps the full per-action signature list.
+`openbkn describe` prints the whole tree at once — sections, arguments, and
+where each id comes from; `--json` ships the same thing as data.
 
 ## Agent skill
 
@@ -94,8 +101,9 @@ lists its flags and arguments, so the tree is discoverable end to end.
 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).
+`references/` (auth, bkn, model, vega, resource, context,
+skill, toolbox, function, trace, admin, call) and two how-tos
+(build-a-KN, troubleshooting).
 
 A second skill, `skills/create-bkn/`, guides an AI through **authoring** a BKN
 definition tree (`network.bkn` + typed `object_types/` / `relation_types/` /

package/README.zh.md

@@ -15,7 +15,7 @@ npm install -g @openbkn/bkn-sdk   # CLI：openbkn
 npm install @openbkn/bkn-sdk
 ```
 
-需要 Node ≥ 22.19。
+需要 Node ≥ 22.19.0。
 
 ## CLI
 
@@ -32,25 +32,26 @@ openbkn bkn object-type list <kn-id>
 # 数据平台
 openbkn resource list --type table
 openbkn vega catalog list
-openbkn dataflow list
 openbkn model llm list
 
-# 智能体
-openbkn agent list
-openbkn agent sessions <agent-key>
-
 # 运维（嵌套）
 openbkn admin org list
 openbkn admin role list
 
 # 任意端点的原始透传
-openbkn call /api/ontology-manager/v1/knowledge-networks
+openbkn call /api/bkn-backend/v1/knowledge-networks
 
 # 全局参数：--base-url --token --user --json/--compact -bd/--biz-domain -k/--insecure
 #           --conversation-id/--interaction-id（BKN Trace 关联，等价 env：BKN_CONVERSATION_ID/BKN_INTERACTION_ID）
+#           --new-conversation（这条命令不沿用记住的 conversation）
 openbkn --help        # 分组命令树
 ```
 
+`managed-v2` 部署上，命令会接着上一条开的 conversation，跨命令的一件事因此落在同一个线程里。
+`openbkn context conversation` 显示当前生效的是哪个、来自哪一层；`--forget` 丢掉它。
+显式 `--token` / `BKN_TOKEN` 不参与（那里的身份是 token 本身，不是存下来的用户）——
+这类脚本用 `BKN_CONVERSATION_ID` 把多条命令串起来。
+
 Token 按平台/用户存于 `~/.bkn/`（可用 `BKN_CONFIG_DIR` 覆盖）。
 
 ## SDK
@@ -67,6 +68,10 @@ const raw = await bkn.call("/api/...", { method: "GET" });
 
 import 本包无副作用；`createClient` 显式解析配置。
 
+Vega 和本体查询等动态数据响应中，超出 JavaScript 安全整数范围的值可能是原生 `bigint`。
+序列化这类结果时，请使用导出的 `stringifyBigIntJSON()`，不要使用原生
+`JSON.stringify()`。
+
 ## 开发
 
 ```bash