openbkn

# 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](references/context.md)。 ## 安装 ```bash npm install -g @openbkn/bkn-sdk # 提供 `openbkn` 命令 ``` 需 Node.js 22.19.0+。也可用 `npx @openbkn/bkn-sdk` 临时运行。 ## 使用方式 ```bash 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` → 切换整个配置档。 ```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 …`、`capability list/attach/detach`、`action-log/action-schedule …`、`subgraph`、`relation-type-paths`、`resources`、`push <dir>`/`pull <kn> [dir]`、`validate <dir>`、`create-from-catalog <catalog> --name … --pk-map t:col` | | `resource` | Vega-backend 资源 | `list`/`get`/`find --name`/`query`/`delete` | | `vega` | Catalog + 资源 + 索引构建 + SQL | `catalog list/get/stats`、`catalog resources`、`resource create/update/delete/build`、`build-task list/get/start/stop/delete`、`connector-type list/get`、`index-capabilities`、`sql --query "<sql>"`（直连 MySQL/PG/OpenSearch，SQL 用 `{{resource-id}}` 占位） | | `context` | Context Loader（MCP 检索） | `info`/`tools <kn>`、`kn-detail`/`object-types`/`relation-types`、`search-schema <kn> "<q>"`、`query-object-instance`/`query-instance-subgraph`/`explore-subgraph`/`query-metric`/`get-logic-properties`/`get-action-info --args '<json>'`、`run-cypher --query`、`run-sql --sql`、`search-capabilities`、`tool-call <kn> <tool> --args`、`conversation [--forget]`。第三方 Agent 业务问答用 MCP `bkn_start_interaction`/`bkn_finish_interaction`；CLI 未带受管上下文时自己开一次托管会话并记住 | | `mcp` | 已注册 MCP Server | `list`/`get`/`tools` 只读发现；不含 Market、登记、发布或调用 | | `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]` | | `skill` | Skill 注册/市场/生命周期/沙箱执行 | `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`；`content`/`read-file` 带 `--raw`（要正文而非对象存储 URL）；`content`/`read-file`/`files`/`download` 带 `--draft`（读草稿版而非已发布版） | | `toolbox` | 工具箱容器 | `list`/`create --name <n> [--type openapi\|function] [--service-url <url>]`/`publish`/`unpublish`/`delete`/`export`/`import`。**`execute` 要求箱子已 `publish`**（未发布/下线返回 400 `ToolNotAvailable`），`debug` 不要求 | | `sandbox` | 临时代码（不注册任何东西） | `run <file> --event '<json>' [--timeout <s>] [--pass-token]`、`infer-schema`、`deps`、`versions`、`template`、`generate <type> [--timeout <s>]`/`prompt <type>`（平台模型生成代码/参数元数据，客户端默认等 300 秒，默认网关 60 秒即 504）。入口函数必须叫 `handler`；成败看 `exit_code` 不是 HTTP 码；长任务留在这里跑 | | `function` | 已注册的函数工具（`--type function` 箱子） | `create <file> --toolbox <id> --name <n>`/`list`/`get`/`update`/`delete`、`enable`/`disable`、`debug`/`execute`（结果在 `body.result`）。流程 create → enable → `toolbox publish` → execute；经工具箱调用约 30 秒被切断（200 + `result: null`） | | `api` | 已注册的 OpenAPI 工具（`--type openapi` 箱子） | `import <spec> --toolbox <id>`（JSON/YAML，`failure_count` 非零则非零退出）/`list`/`get`/`update`/`delete`、`enable`/`disable`、`debug`/`execute`。流程 import → enable → `toolbox publish` → execute | | `tool` | 类型无关的高级入口（兼容旧自动化） | `create <file> --toolbox <id> [--type openapi]`/`upload <spec>`/`list`/`get`/`update`/`delete`、`enable`/`disable`、`execute`/`debug`；新流程优先用 `function` / `api` | | `trace` | BKN Trace | `get`、`search`、`diagnose <conv> [--llm]`（符号规则 + LLM rubric + synthesizer）、`scan <conv,…>`、`eval-set build <queries>`、`schema validate <file>` | | `admin` | 运营 | `org/user/role …` CRUD + `reset-password`、`row-filter get/apply/delete/explain`（企业版行过滤策略）、`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`，或读对应的速查参考。 - 配置全文索引前，用 `vega index-capabilities` 查询部署支持的分析器；返回列表与检查时间，详情见 [vega.md](references/vega.md)。 - `bkn metric validate` 的成败看返回的 `valid`；`false` 时 CLI 输出结果并以退出码 1 结束。对象类的 `data_properties` 可省略，读取时按无数据属性处理。详情见 [bkn.md](references/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/） | 主题 | 文件 | |------|------| | 认证 / 会话 / 多用户 | [auth.md](references/auth.md) | | AppKey 签发 / 撤销（`bak_`） | [appkey.md](references/appkey.md) | | 知识网络 + Schema + 查询 + 建网 | [bkn.md](references/bkn.md) | | 模型工厂 | [model.md](references/model.md) | | Vega Catalog + 索引构建 | [vega.md](references/vega.md) | | vega-backend 资源 | [resource.md](references/resource.md) | | Context Loader（MCP） | [context.md](references/context.md) | | 已注册 MCP Server（只读发现） | [mcp.md](references/mcp.md) | | Skill 注册 / 生命周期 | [skill.md](references/skill.md) | | 写一个 Skill 包 / 沙箱函数（bkn-osdk） | [create-skill](../create-skill/SKILL.md) 技能 | | Toolbox / API / Tool | [toolbox.md](references/toolbox.md) | | Sandbox / Function（代码→函数工具） | [function.md](references/function.md) | | Python 里读知识网络（bkn-osdk） | [osdk.md](references/osdk.md) | | BKN Trace（diagnose / eval-set） | [trace.md](references/trace.md) | | 运营（org/user/role/row-filter/audit） | [admin.md](references/admin.md) | | 通用 API 透传 | [call.md](references/call.md) | ## 操作指南 | 场景 | 参考 | |------|------| | 从 Vega Catalog 端到端建知识网络（CSV 需先载入数据源） | [build-kn.md](references/build-kn.md) | | 一次问答里反复取数 / 沙箱代码要读知识网络 | [osdk.md](references/osdk.md) —— 换 Python，业务问答仍挂在本轮 turn 上 | | 排障速查（401 / 重试 / 空列表 / 403 / 审计权限 / trace 无数据） | [troubleshooting.md](references/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)。 - **不要猜参数**：使用实时 `--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 时自动降级为纯符号。