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

package/README.md

@@ -47,17 +47,40 @@ openbkn admin role list
 # Raw passthrough to any endpoint
 openbkn call /api/bkn-backend/v1/knowledge-networks
 
-# Global flags: --base-url, --token, --user, --json/--compact, -bd/--biz-domain, -k/--insecure,
+# Return an MCP tool result with its validated BKN Trace receipt
+openbkn --json context tool-call <kn-id> <tool-name> --args '{"k":"v"}' --receipt
+
+# Global flags: --base-url, --token, --user, --json/--compact, -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
+On a deploy with the managed lifecycle, 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.
+`--interaction-id` / `BKN_INTERACTION_ID` can be supplied on its own for
+existing scripts. The SDK follows the automatic lifecycle handshake, but does
+not forward that orphan ID as a business header once it has opened an
+authoritative context; it never invents a matching Conversation ID locally. Use
+the returned receipt to establish the authoritative business context.
+
+`context tool-call --receipt` requires `--json` or `--compact` and emits
+`{ value, bkn_receipt }` (`--compact` is the one-line form). It is opt-in; the default command output and SDK
+`context.toolCall()` remain business-value-only. The receipt is validated for this
+call, not a bearer credential; confirm access under the current identity with
+`openbkn trace receipts get <receipt-id>` when authorization evidence is required.
+Check `bkn_receipt.receipt_status`, not whether `value` is `null`: a `pending`
+receipt has no consumable value and must be read back by `receipt_id` rather
+than retried. On a 0.1.5 platform a `completed` receipt carries only
+`receipt_status`, `evidence_durability`, `observed_evidence_refs` and
+`business_refs` (plus `partial_reasons` when set); `receipt_id` and the other
+identity fields come with `pending` and terminal-replay receipts. To read the
+complete record of a completed call, find its `receipt_id` with
+`openbkn trace interactions operations <interaction-id>` and pass it to
+`openbkn trace receipts get`.
 
 Tokens are stored per platform/user under `~/.bkn/` (override: `BKN_CONFIG_DIR`).
 
@@ -101,8 +124,8 @@ where each id comes from; `--json` ships the same thing as data.
 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, model, vega, resource, context,
-skill, toolbox, function, trace, admin, call) and two how-tos
+`references/` (auth, appkey, bkn, model, vega, resource, context, mcp,
+skill, toolbox, function, osdk, trace, admin, call) and two how-tos
 (build-a-KN, troubleshooting).
 
 A second skill, `skills/create-bkn/`, guides an AI through **authoring** a BKN
@@ -112,12 +135,20 @@ format spec, templates, and a worked example under `references/`. It pairs with
 the `openbkn` skill, which then runs `openbkn bkn validate` / `push` on the
 tree it produced.
 
-Neither skill is part of the npm package — they're registered separately:
+A third skill, `skills/create-skill/`, guides an AI through **authoring a Skill
+package** for the execution factory — a `SKILL.md` that declares which metrics,
+functions, actions and MCP tools of one knowledge network it uses and how an
+agent should call them — and through writing a sandbox function with
+`bkn-osdk` and registering it as a tool. Templates and a worked example that
+was verified end-to-end live under `assets/` and `references/`.
+
+None of the skills is part of the npm package — they're registered separately:
 
 ```bash
 # Install a skill (globally), then ask in natural language:
-npx skills add openbkn-ai/bkn-sdk@openbkn -g -y      # operate the platform
-npx skills add openbkn-ai/bkn-sdk@create-bkn -g -y   # author .bkn files
+npx skills add openbkn-ai/bkn-sdk@openbkn -g -y        # operate the platform
+npx skills add openbkn-ai/bkn-sdk@create-bkn -g -y     # author .bkn files
+npx skills add openbkn-ai/bkn-sdk@create-skill -g -y   # author a Skill package / function tool
 
 #   "列出所有知识网络"  /  "list all knowledge networks"
 #   "从 Vega catalog vcat-1 建一个名为 customers 的知识网络并构建索引"

package/README.zh.md

@@ -41,7 +41,10 @@ openbkn admin role list
 # 任意端点的原始透传
 openbkn call /api/bkn-backend/v1/knowledge-networks
 
-# 全局参数：--base-url --token --user --json/--compact -bd/--biz-domain -k/--insecure
+# 返回 MCP 工具结果及其已校验的 BKN Trace Receipt
+openbkn --json context tool-call <kn-id> <tool-name> --args '{"k":"v"}' --receipt
+
+# 全局参数：--base-url --token --user --json/--compact -k/--insecure
 #           --conversation-id/--interaction-id（BKN Trace 关联，等价 env：BKN_CONVERSATION_ID/BKN_INTERACTION_ID）
 #           --new-conversation（这条命令不沿用记住的 conversation）
 openbkn --help        # 分组命令树
@@ -51,6 +54,19 @@ openbkn --help        # 分组命令树
 `openbkn context conversation` 显示当前生效的是哪个、来自哪一层；`--forget` 丢掉它。
 显式 `--token` / `BKN_TOKEN` 不参与（那里的身份是 token 本身，不是存下来的用户）——
 这类脚本用 `BKN_CONVERSATION_ID` 把多条命令串起来。
+既有脚本可以单独提供 `--interaction-id` / `BKN_INTERACTION_ID`。SDK 会走自动 lifecycle handshake；
+一旦建立权威上下文，孤立 ID 不会再作为业务 header 透传，也不会在本地伪造对应的 Conversation ID；以返回的
+Receipt 确认权威业务上下文。
+
+`context tool-call --receipt` 必须带 `--json` 或 `--compact`，输出 `{ value, bkn_receipt }`（
+`--compact` 即单行形式）。这是显式选择；默认命令输出和 SDK 的 `context.toolCall()` 仍只返回
+业务值。Receipt 仅证明其已通过本次调用的字段校验，不是 bearer credential；需要授权证据时，
+应在当前身份下运行 `openbkn trace receipts get <receipt-id>` 回读确认。
+不要用 `value` 是否为 `null` 判断结果是否可用；应检查 `bkn_receipt.receipt_status`。`pending` 表示
+业务值不可消费，应使用 `receipt_id` 回读，而不是重试业务工具。0.1.5 平台上 `completed` 回执只带
+`receipt_status`、`evidence_durability`、`observed_evidence_refs`、`business_refs`（有 `partial_reasons` 时一并带上），
+没有 `receipt_id`；需要回读完整记录时，用 `openbkn trace interactions operations <interaction-id>` 找到该次调用的
+`receipt_id`，再执行 `openbkn trace receipts get`。`pending` 与终态重放回执仍带身份字段。
 
 Token 按平台/用户存于 `~/.bkn/`（可用 `BKN_CONFIG_DIR` 覆盖）。
 
@@ -86,6 +102,42 @@ npm run build    # tsup → dist/（库 + openbkn bin）
 每个命令、子命令、孙命令都带分组 `--help`，列出各自的参数与位置参数，
 整棵命令树可端到端发现。`openbkn help all` 输出全深度的逐动作签名清单。
 
+## Agent 技能
+
+`skills/openbkn/` 是一个 Agent 技能（面向 Claude Code / [skills.sh](https://skills.sh)
+生态），让 AI 用自然语言驱动 `openbkn` CLI。它包含一份 `SKILL.md`（触发意图、
+`allowed-tools: Bash(openbkn *)`、命令组地图、示例与注意事项），`references/` 下
+按领域划分的速查表（auth、appkey、bkn、model、vega、resource、context、mcp、
+skill、toolbox、function、osdk、trace、admin、call），以及两篇操作指南
+（建知识网络、排障）。
+
+第二个技能 `skills/create-bkn/` 引导 AI **编写** BKN 定义目录（`network.bkn` +
+按类型分目录的 `object_types/` / `relation_types/` / `action_types/` /
+`concept_groups/` 文件，遵循 v2.0.1 规范），`references/` 下附格式规范、模板和
+完整示例。它与 `openbkn` 技能配合：产出的目录再由 `openbkn bkn validate` / `push`
+校验和导入。
+
+第三个技能 `skills/create-skill/` 引导 AI 为执行工厂**编写 Skill 包**——一份
+`SKILL.md`，声明它用到某个知识网络的哪些指标、函数、行动和 MCP 工具，以及 Agent
+该如何调用——并用 `bkn-osdk` 编写沙箱函数、注册成工具。`assets/` 与 `references/`
+下有模板和一个端到端验证过的示例。
+
+这些技能都不在 npm 包里，需要单独安装：
+
+```bash
+# 全局安装技能，然后用自然语言提问：
+npx skills add openbkn-ai/bkn-sdk@openbkn -g -y        # 操作平台
+npx skills add openbkn-ai/bkn-sdk@create-bkn -g -y     # 编写 .bkn 文件
+npx skills add openbkn-ai/bkn-sdk@create-skill -g -y   # 编写 Skill 包 / 函数工具
+
+#   "列出所有知识网络"
+#   "从 Vega catalog vcat-1 建一个名为 customers 的知识网络并构建索引"
+#   "帮我建一个描述订单域的 BKN 知识网络文件"
+```
+
+`openbkn` 技能假定已安装 `openbkn` CLI（`npm i -g @openbkn/bkn-sdk`）并已登录
+（`openbkn auth login`）。确切参数始终以实时 `openbkn <group> <sub> --help` 为准。
+
 ## 许可证
 
 BKN SDK 是 OpenBKN 项目的一部分，采用 **Apache License, Version 2.0**。