openbkn CLI

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

第三方 Agent 业务问答硬门禁

• 业务问答必须受管：每轮先调用 bkn_start_interaction，必传 question、agent_name（每轮同一名称）和 conversation_mode：首轮用 new 且不传 conversation_id，后续轮次用 continue 并传上一轮返回的 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。

安装

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

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

使用方式

openbkn [--base-url <url>] [--token <tok>] [--user <id|name>] \
        [--json | --compact] [-k|--insecure] <group> <sub> [options]

• 默认输出为人类可读表格；--json（或 --compact）输出可被脚本解析的精确 JSON。
• -k/--insecure 关闭 TLS 校验（自签名平台）。auth login -k 会按平台记住，之后该平台的命令无需再带；免校验只作用于该平台的请求，不碰进程全局，无需 NODE_TLS_REJECT_UNAUTHORIZED。
• 以实时 --help 为准。 openbkn --help 看分组命令地图，openbkn <group> <sub> --help 看确切参数。不要猜参数。
• 默认检查 SDK 与平台的基础版本是否一致，忽略 RC 与 build 后缀：0.2.0 可匹配 0.2.0-rc.1 或 0.2.0-rc.2。跨基础版本或平台报占位版本时，CLI 可显式加 --skip-version-check；SDK 可设 BKN_SKIP_VERSION_CHECK=1。

认证（凭据按平台/用户分层存于 ~/.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 → 切换整个配置档。

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

命令组总览

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

• 配置全文索引前，用 vega index-capabilities 查询部署支持的分析器；返回列表与检查时间，详情见 vega.md。
• bkn object-metric validate 的成败看返回的 valid；false 时 CLI 输出问题列表并以退出码 1 结束。对象类的 data_properties 可省略，读取时按无数据属性处理。详情见 bkn.md。

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

• Agent 运行时 bkn-agent（/api/bkn-agent/v1/agents、/chat、/run、/tasks、/prompts）
• 执行工厂 MCP 的写入、Market 与调用面（/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 resource update <resource-id> 保存索引配置，再由 openbkn vega resource build <resource-id> 创建 BuildTask。

详细参考（references/）

操作指南

调用示例

/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)。
• 不要猜参数：使用实时 --help；列表为空时先确认当前账号权限和目标资源是否存在。
• 不要猜请求体字段：带 --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 截断。