openbkn · diff
git:20260917.2bcf0e9 to git:20260918.d7f989a
10 added, 9 removed. Audit A to A.
---
name: openbkn
description: >-
操作 BKN（Business Knowledge Network）平台的统一 CLI `openbkn` —— 知识网络
构建/查询（Schema：对象/关系/行动类型、指标、概念组；实例与语义搜索；
- push/pull/validate；从 Vega Catalog 或 CSV 建网）、资源、Vega Catalog 与
+ push/pull/validate；从 Vega Catalog 建网）、资源、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 / api / OpenAPI 工具 / 函数工具 / function /
sandbox / 沙箱 / 沙箱函数 / 生成函数代码 /
trace / 证据链 / diagnose /
eval-set / Vega / Catalog / 数据源 / 组织 / 用户 / 角色 / 审计 audit /
- AppKey / api-key / bak_ 凭据 / 签发 key / 撤销 key 等意图时使用。
+ AppKey / api-key / bak_ 凭据 / 签发 key / 撤销 key / MCP Server / mcp /
+ Cypher / 挂载能力 / capability attach / Context Loader / 检索 / vega sql /
+ 重试 / --no-retry 等意图时使用。
allowed-tools: Bash(openbkn *), Bash(npx openbkn *)
argument-hint: [自然语言指令]
---
# 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+。也可用 `npx @openbkn/bkn-sdk` 临时运行。
+ 需 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` 看确切参数。**不要猜参数**。
## 认证（凭据按平台/用户分层存于 `~/.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` | MCP 检索 | 业务对话通过 MCP 工具 `bkn_start_interaction` / `bkn_finish_interaction` 管理；CLI 沿用 `tool-call` 透传，不另设生命周期命令 |
+ | `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`；读类命令带 `--raw`（要正文而非对象存储 URL）与 `--draft`（读草稿版而非已发布版） |
+ | `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`、`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 的写入、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；`trace` 的 business-provenance 摘要（requests/interactions）自 foundry 0.1.4 起
- 只在企业版注册，社区版部署上会 404。
+ 保存索引配置，再由 `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/audit） | [admin.md](references/admin.md) |
| 通用 API 透传 | [call.md](references/call.md) |
## 操作指南
| 场景 | 参考 |
|------|------|
- | 从 Catalog / CSV 端到端建知识网络 | [build-kn.md](references/build-kn.md) |
+ | 从 Vega Catalog 端到端建知识网络（CSV 需先载入数据源） | [build-kn.md](references/build-kn.md) |
| 一次问答里反复取数 / 沙箱代码要读知识网络 | [osdk.md](references/osdk.md) —— 换 Python，业务问答仍挂在本轮 turn 上 |
- | 排障速查（401 / 空列表 / 403 / EACP / trace 索引） | [troubleshooting.md](references/troubleshooting.md) |
+ | 排障速查（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 时自动降级为纯符号。
- 宽表查询(`object-type query` / `context query-object-instance`)务必限制 `limit`、用分页与 `condition` 过滤，避免 JSON 截断。