<< All versions

Skill v1.0.1

Automated scan100/100
openbkn-ai/bkn-sdk/openbkn

+18 new

──Details
PublishedAugust 30, 2026 at 08:38 AM
Content Hashsha256:71f3249640825f65...
Git SHA21ccd9c91dce
Bump Typepatch
Compare with v1.0.0
──Files
Files (1 file, 11.7 KB)
SKILL.md11.7 KBactive
SKILL.md · 163 lines · 11.7 KB

version: "1.0.1" name: openbkn description: >- 操作 BKN（Business Knowledge Network）平台的统一 CLI openbkn —— 知识网络 构建/查询（Schema：对象/关系/行动类型、指标、概念组；实例与语义搜索； push/pull/validate；从 Vega Catalog 或 CSV 建网）、资源、Vega Catalog 与 索引构建任务、Context Loader（MCP 检索）、模型工厂（大模型/小模型 CRUD、OpenAI 兼容对话/embedding/ rerank）、Skill 注册（zip 注册/下载/安装 + 生命周期）、Toolbox/Tool（上传、 导入导出、调用）、BKN Trace（第三方 Agent 受管 Conversation / Interaction / Operation、拉取 spans、用符号 规则 + LLM rubric 判定诊断一条 trace、scan、eval-set 构建、schema 校验）、 以及运营面（openbkn admin：组织/用户/角色 CRUD、审计、模型管理）与认证 （token + OAuth 密码/浏览器）。 当用户提到：知识网络 / 知识图谱 / 对象类 / 关系 / 行动 / 指标 metric / 语义搜索 / 建索引 / create-from-catalog / 大模型 / 小模型 / embedding / rerank / Skill / 技能包 / toolbox / 工具箱 / tool / 沙箱函数 / function / trace / 证据链 / diagnose / eval-set / Vega / Catalog / 数据源 / 组织 / 用户 / 角色 / 审计 audit / AppKey / api-key / bak_ 凭据 / 签发 key / 撤销 key 等意图时使用。 allowed-tools: Bash(openbkn ), Bash(npx openbkn ) argument-hint: [自然语言指令]

openbkn CLI

BKN 平台的统一命令行工具 —— 一个二进制，运维面收进 openbkn admin 子命令。 纯后端，无 Web UI。

第三方 Agent 业务问答硬门禁

  • 业务问答必须受管：每轮先调用 bkn_start_interaction；首轮可声明 agent_name，后续轮次复用上一轮返回的 conversation_id 且不得变更名称。
  • 只用权威 ID：业务工具逐字使用 start 返回的 conversation_id 和 interaction_id，不得虚构、猜测或沿用示例值。
  • 业务调用保持受管：只通过携带上述 ID 的 Context Loader 工具访问 OpenBKN，Operation、重试和证据闭包由平台管理。
  • 提交本轮结果：回答生成后调用 bkn_finish_interaction；它只提交当前 Interaction 的结果，不关闭 Conversation。
  • 错误即停止：返回原始错误并遵循 required_action，不得降级到 CLI、Vega、ontology-query 或无受管上下文的调用。

详细合同见 context.md。

安装

bash
npm install -g @openbkn/bkn-sdk      # 提供 `openbkn` 命令

需 Node.js 22+。也可用 npx @openbkn/bkn-sdk 临时运行。

使用方式

bash
openbkn [--base-url <url>] [--token <tok>] [--user <id|name>] \
        [--json | --compact] [-bd|--biz-domain <d>] [-k|--insecure] <group> <sub> [options]
  • 默认输出为人类可读表格；--json（或 --compact）输出可被脚本解析的精确 JSON。
  • -k/--insecure 关闭 TLS 校验（自签名平台）。auth login -k 会按平台记住，之后该平台的命令无需再带；免校验只作用于该平台的请求，不碰进程全局，无需 NODE_TLS_REJECT_UNAUTHORIZED。
  • -bd <domain> 覆盖 x-business-domain（默认 bd_public）。
  • 以实时 `--help` 为准。 openbkn --help 看分组命令地图，openbkn <group> <sub> --help 看确切参数。不要猜参数。

认证（凭据按平台/用户分层存于 ~/.bkn/，可用 BKN_CONFIG_DIR 覆盖）

优先级：

  1. 全局 --token + --base-url（或环境 BKN_BASE_URL / 活跃平台）→ 一次性 stateless，不读写 ~/.bkn/。
  2. 环境 BKN_TOKEN + BKN_BASE_URL → 静态 token。
  3. ~/.bkn/ 凭据（openbkn auth login 写入）→ 推荐；多用户分层。
  4. 全局 --user <id|name>（或 BKN_USER）→ 在该平台已存的多个用户里指定本次用哪个；仅本次生效，不改活跃用户。BKN_PROFILE → 切换整个配置档。
bash
openbkn auth login <url> --token "$TOKEN"      # 附加已有 token（CI/headless）
openbkn auth login <url> -u <user> -p <pwd>    # headless 凭据登录（device-code，无浏览器）
openbkn auth login <url>                        # 打开浏览器批准 device code
openbkn auth login <url> --device               # 只打印 URL+code，在任意机器批准
openbkn auth status | whoami | token | list | use <url> | switch <url> <user> | logout

命令组总览

命令组说明常用命令
auth认证 / 会话 / 多用户login（--token / -u -p / 浏览器 / --device，均走 device-code）、status/whoami/token/list/use/switch/users/export、change-password
config平台 CLI 配置config show / config set <key> <value>
appkey用户自助签发的 AppKey（bak_ 长期凭据，仅 Context Loader 可用）list、`create --name <s> [--expire-days <n> \--expires-at <rfc3339> \--never-expire]（明文 key **只返回一次**）、regenerate <id>（轮换：同 id 出新 key，旧 key 立即失效）、revoke <id>、admin list [--owner-id]/admin revoke <id>`
bkn知识网络 + Schema + 查询 + 本地包list/get/search/stats/export、object-type/relation-type/action-type list/get/create/update/delete、action-type query/execute、metric …、concept-group …、action-log/action-schedule …、subgraph、relation-type-paths、resources、push <dir>/pull <kn> [dir]、validate <dir>、create-from-catalog <catalog> --name …（--build、--pk-map t:col）
resourceVega-backend 资源list/get/find --name/query/delete
vegaCatalog + 索引构建 + SQLcatalog list/get、catalog resources、connector-types、sql --query "<sql>"（直连 MySQL/PG/OpenSearch，SQL 用 {{resource-id}} 占位）、build（索引 BuildTask）+ 状态
contextMCP 检索业务对话通过 MCP 工具 bkn_start_interaction / bkn_finish_interaction 管理；CLI 沿用 tool-call 透传，不另设生命周期命令
model模型工厂llm/small list/get/add/edit/delete/test、`llm chat <name\id> -m "…" [--stream]（id 自动解析成 name）、small embeddings/rerank <name>（只收 name，填数字 id 会 400；与 chat 不同，暂不解析 id）、llm set-default/unset-default <id>、small set-default/unset-default <id>、small get-default [--type embedding\reranker]`
skillSkill 注册/市场/生命周期/沙箱执行list/market/get/names <id...>/content/read-file/files [path] [--tree]/history/set-status、execute <id> --entry '<shell>'、register <dir>/download/install、update-metadata/update-package、republish/publish-history；读类命令带 --raw（要正文而非对象存储 URL）与 --draft（读草稿版而非已发布版）
toolbox / tool工具箱与工具toolbox `list/create [--type openapi\function]/publish/delete/export/import；tool create <file> --toolbox <id>（函数工具唯一入口）/get/update/delete/upload <spec>、enable/disable、execute/debug（结果在 body.result`）
function沙箱函数（执行工厂）run <file> --event '<json>' [--pass-token]、infer-schema、deps、versions、template。入口函数必须叫 handler；成败看 exit_code 不是 HTTP 码；留下来就用 tool create --toolbox
traceBKN Traceget、search、diagnose <conv> [--llm]（符号规则 + LLM rubric + synthesizer）、scan <conv,…>、eval-set build <queries>、schema validate <file>
admin运营org/user/role … CRUD + reset-password、license show/import/receipt/activate/remove/fingerprint（集群授权）、audit list、llm/small-model …、auth …、config、call
call（别名 curl）通用 API 透传call <url> [-X POST] [-d '<json>']

按需深入：需要某命令的完整参数时运行 openbkn <group> <sub> --help，或读对应的速查参考。

本 CLI 暂未覆盖的平台能力（别猜命令，直接用 openbkn call 打原始接口）：

  • Agent 运行时 bkn-agent（/api/bkn-agent/v1/agents、/chat、/run、/tasks、/prompts）
  • 执行工厂的 MCP 注册面（/api/agent-operator-integration/v1/mcp）
  • Skill 索引构建任务（/api/agent-operator-integration/v1/skills/index/build）
  • openbkn call /api/<service>/v1/... [-X POST] [-d '<json>'] 会自动注入认证头
  • 接口文档在 https://openbkn-ai.github.io/bkn-foundry/ —— 按模块分组的交互式

OpenAPI（bkn-backend / context-loader / ontology-query / vega-backend / execution-factory / agent-observability / bkn-agent）。先在那里查准路径和 请求体，再 call，不要猜路径

另注：知识网络没有"整网构建"这回事，索引数据由 openbkn vega dataset build <resource-id> 的 BuildTask 产出；trace 的 business-provenance 摘要（requests/interactions）自 foundry 0.1.4 起 只在企业版注册，社区版部署上会 404。

详细参考（references/）

主题文件
认证 / 会话 / 多用户auth.md
AppKey 签发 / 撤销（bak_）appkey.md
知识网络 + Schema + 查询 + 建网bkn.md
模型工厂model.md
Vega Catalog + 索引构建vega.md
vega-backend 资源resource.md
Context Loader（MCP）context.md
Skill 注册 / 生命周期skill.md
Toolbox / Tooltoolbox.md
沙箱函数（代码→工具）function.md
BKN Trace（diagnose / eval-set）trace.md
运营（org/user/role/audit）admin.md
通用 API 透传call.md

操作指南

场景参考
从 Catalog / CSV 端到端建知识网络build-kn.md
排障速查（401 / 空列表 / 403 / EACP / trace 索引）troubleshooting.md

调用示例

text
/openbkn 列出所有知识网络
/openbkn 搜索知识网络 xxx 中关于"供应链"的内容
/openbkn 从 Vega catalog vcat-1 建一个名为 customers 的知识网络并构建索引
/openbkn 把本地 ./my-bkn 目录校验后 push 上去
/openbkn 诊断会话 conv-123 的 trace，带 LLM 判定
/openbkn 在 skill market 里找名字含 retrieval 的 skill 并安装到 ./out
/openbkn 把 ./openapi.json 上传到 toolbox 1234567890
/openbkn 列出组织结构；给用户 u-1 重置密码

注意事项

  • 不要预检：直接执行目标命令，认证由 CLI 处理(token 模式不自动续期；~/.bkn/ 凭据可用 refresh)。
  • 不要猜 business domain / 参数：用 --help；列表为空时确认 -bd。
  • 不要猜请求体字段：带 --body / --body-file 的命令，其 --body 说明里写着该去

https://openbkn-ai.github.io/bkn-foundry/ 的哪个模块查形状（改定义看 bkn-backend， 取数/执行看 ontology-query，skill/tool 看 execution-factory，受管交互看 agent-observability）。context 的 --args 例外：形状是 MCP 工具自己的 input schema， 用 context tools <kn-id> 取。

  • 破坏性操作（bkn/admin 的 delete、admin user reset-password、Action 执行）作用于线上，执行前向用户确认。
  • trace diagnose --llm、rubric/synthesizer 用本地 `claude` CLI 做判定；claude 不在 PATH 时自动降级为纯符号。
  • 宽表查询(object-type query / context query-object-instance)务必限制 limit、用分页与 condition 过滤，避免 JSON 截断。
← v1.0.0All versionsv1.0.2 →