create-bkn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create BKN

创建BKN

Generate well-formed BKN directories (Markdown + YAML frontmatter) per v2.0.1.

按照v2.0.1规范生成格式规范的BKN目录（Markdown + YAML前置元数据）。

Works with kweaver-core

与kweaver-core配合使用

create-bkn authors the

.bkn

tree; kweaver-core runs

kweaver auth login

and

kweaver bkn push

pull

after files exist.

create-bkn负责生成

.bkn

目录树；kweaver-core在文件创建完成后运行

kweaver auth login

以及

kweaver bkn push

pull

命令。

What is BKN

什么是BKN

BKN is Markdown + YAML frontmatter for schema; one file per definition under typed subfolders. Details (sections, required tables, types) live in references/SPECIFICATION.llm.md.

BKN是用于定义 schema 的Markdown + YAML前置元数据格式，每个定义对应一个文件，存放在对应类型的子文件夹下。详细信息（章节、必填表格、类型）请参考references/SPECIFICATION.llm.md。

Directory layout

目录结构

{network_dir}/
├── SKILL.md
├── network.bkn
├── CHECKSUM                 # optional; SDK may generate
├── object_types/
├── relation_types/
├── action_types/
├── concept_groups/
└── data/                    # optional CSV instance data

{network_dir}/
├── SKILL.md
├── network.bkn
├── CHECKSUM                 # 可选；SDK可能自动生成
├── object_types/
├── relation_types/
├── action_types/
├── concept_groups/
└── data/                    # 可选的CSV实例数据

Workflow

工作流程

Gather requirements — objects, relations, actions, optional concept groups
Read spec — references/SPECIFICATION.llm.md (format rules, sections, frontmatter types)
Pick templates — copy/adapt from assets/templates/ (
```
network_type.bkn.template
```
,
```
object_type.bkn.template
```
, …)
Create
network.bkn
— root file; align with Network Overview
Create
object_types/*.bkn
— one file per object,
```
{id}.bkn
```
Create
relation_types/*.bkn
— one file per relation
Create
action_types/*.bkn
— one file per action
Create
concept_groups/*.bkn
— optional
Update
network.bkn
— list all IDs in Network Overview
Add root
SKILL.md
in the BKN directory — same folder as
```
network.bkn
```
(this is not the create-bkn skill file); agent-facing guide for that network (see Delivered BKN: root SKILL.md)
Review (MUST) — cross-check Validation checklist and Business rules placement; fix IDs, cross-refs, headings
Validate (MUST) —
```
kweaver bkn validate <dir>
```
(see Validation)
Import (optional) —
```
kweaver bkn push <dir>
```

收集需求 — 对象、关系、动作，可选概念组
阅读规范 — references/SPECIFICATION.llm.md（格式规则、章节、前置元数据类型）
选择模板 — 从assets/templates/复制/适配模板（
```
network_type.bkn.template
```
、
```
object_type.bkn.template
```
等）
创建
network.bkn
— 根文件；与网络概述保持一致
创建
object_types/*.bkn
— 每个对象对应一个文件，命名为
```
{id}.bkn
```
创建
relation_types/*.bkn
— 每个关系对应一个文件
创建
action_types/*.bkn
— 每个动作对应一个文件
创建
concept_groups/*.bkn
— 可选
更新
network.bkn
— 在网络概述中列出所有ID
在BKN目录中添加根目录
SKILL.md
— 与
```
network.bkn
```
在同一文件夹下（不是create-bkn的skill文件）；面向Agent的该网络使用指南（参考交付的BKN：根目录SKILL.md）
审核（必须执行） — 对照验证检查清单和业务规则放置；修正ID、交叉引用、标题
验证（必须执行） — 运行
```
kweaver bkn validate <dir>
```
（参考验证）
导入（可选） — 运行
```
kweaver bkn push <dir>
```

Import (kweaver CLI)

导入（kweaver CLI）

Requires the

kweaver

CLI from

@kweaver-ai/kweaver-sdk

(

npm install -g @kweaver-ai/kweaver-sdk

; Node.js 22+).

push

uses

tar

; on macOS

COPYFILE_DISABLE=1

is set by the tool.

Platform auth — If you already have a valid token for the target platform (
```
kweaver auth status
```
), do not run
```
kweaver auth login
```
again. If not authenticated, run
```
kweaver auth login <platform-url>
```
first.
BKN validation — If workflow step 12 (
```
kweaver bkn validate <dir>
```
) already succeeded for this directory, do not repeat validate before
```
push
```
unless you changed
```
.bkn
```
files. If you have not validated yet, run
```
validate
```
before
```
push
```
.

bash

kweaver bkn push <dir> [--branch main] [-bd <business-domain>]

-bd

--biz-domain

is optional. If you omit it, the CLI resolves the business domain automatically (

KWEAVER_BUSINESS_DOMAIN

env, then saved platform config in

~/.kweaver

, otherwise

bd_public

Export:

kweaver bkn pull <kn-id> [<dir>]

. More subcommands:

kweaver bkn --help

(see kweaver-core skill if loaded).

需要来自

@kweaver-ai/kweaver-sdk

的

kweaver

CLI工具（执行

npm install -g @kweaver-ai/kweaver-sdk

；要求Node.js 22+）。

push

命令使用

tar

；在macOS系统中，工具会自动设置

COPYFILE_DISABLE=1

。

平台认证 — 如果您已拥有目标平台的有效令牌（执行
```
kweaver auth status
```
查看），请勿再次运行
```
kweaver auth login
```
。如果未认证，请先运行
```
kweaver auth login <platform-url>
```
。
BKN验证 — 如果工作流程步骤12（
```
kweaver bkn validate <dir>
```
）已针对该目录执行成功，请勿在
```
push
```
前重复验证，除非您修改了
```
.bkn
```
文件。如果尚未验证，请在
```
push
```
前运行验证命令。

bash

kweaver bkn push <dir> [--branch main] [-bd <business-domain>]

-bd

--biz-domain

为可选参数。如果省略，CLI会自动解析业务域（优先使用

KWEAVER_BUSINESS_DOMAIN

环境变量，然后是

~/.kweaver

中保存的平台配置，否则使用

bd_public

）。

导出：

kweaver bkn pull <kn-id> [<dir>]

。更多子命令：

kweaver bkn --help

（若已加载kweaver-core skill可查看）。

Validation

验证

kweaver bkn validate <dir>

— must pass before delivery or upload. It loads

network.bkn

and sibling

.bkn

files. Success prints counts; on failure fix

.bkn

files and re-run.

kweaver bkn validate <dir>

— 在交付或上传前必须通过验证。该命令会加载

network.bkn

及其同级的

.bkn

文件。验证成功会打印统计信息；若失败，请修正

.bkn

文件后重新运行。

Per-type reference

各类型参考

Kind	Spec (section)	Template	Example (k8s)
Network	`knowledge_network` in spec	assets/templates/network_type.bkn.template	references/examples/k8s-network/network.bkn
Object	`object_type`	assets/templates/object_type.bkn.template	references/examples/k8s-network/object_types/pod.bkn
Relation	`relation_type`	assets/templates/relation_type.bkn.template	references/examples/k8s-network/relation_types/pod_belongs_node.bkn
Action	`action_type`	assets/templates/action_type.bkn.template	references/examples/k8s-network/action_types/restart_pod.bkn
Concept group	`concept_group`	assets/templates/concept_group.bkn.template	references/examples/k8s-network/concept_groups/k8s.bkn

Full rules and optional sections: references/SPECIFICATION.llm.md.

类型	规范（章节）	模板	示例（k8s）
网络	规范中的 `knowledge_network`	assets/templates/network_type.bkn.template	references/examples/k8s-network/network.bkn
对象	`object_type`	assets/templates/object_type.bkn.template	references/examples/k8s-network/object_types/pod.bkn
关系	`relation_type`	assets/templates/relation_type.bkn.template	references/examples/k8s-network/relation_types/pod_belongs_node.bkn
动作	`action_type`	assets/templates/action_type.bkn.template	references/examples/k8s-network/action_types/restart_pod.bkn
概念组	`concept_group`	assets/templates/concept_group.bkn.template	references/examples/k8s-network/concept_groups/k8s.bkn

完整规则和可选章节：references/SPECIFICATION.llm.md。

Naming conventions

命名规范

ID: lowercase, digits, underscores; file:
```
{id}.bkn
```
under the matching folder
Headings:
```
#
```
network title,
```
##
```
type block,
```
###
```
section,
```
####
```
logic property
Frontmatter: at least
```
type
```
,
```
id
```
,
```
name
```
(see spec for each type)

ID：小写字母、数字、下划线；文件：对应文件夹下的
```
{id}.bkn
```
标题：
```
#
```
网络标题，
```
##
```
类型块，
```
###
```
章节，
```
####
```
逻辑属性
前置元数据：至少包含
```
type
```
、
```
id
```
、
```
name
```
（每种类型的具体要求请参考规范）

Business rules placement

业务规则放置

Rules must sit in spec-defined places so import persists them. Full wording: references/SPECIFICATION.llm.md.

Network-level — prose in
```
network.bkn
```
right after
```
# {title}
```
(before structured sections like
```
## Network Overview
```
)
Type-level — prose in each type file after
```
## ObjectType:
```
/
```
## RelationType:
```
/ … and before the first
```
###
```
; never in frontmatter
Property-level — in Data Properties table Description column
No extra sections — do not add Markdown outside the standard sections; parsers may drop unparsed content on import

规则必须放在规范定义的位置，确保导入时能保留。完整说明：references/SPECIFICATION.llm.md。

网络级别 — 放在
```
network.bkn
```
中
```
# {title}
```
之后（在
```
## Network Overview
```
等结构化章节之前）的正文部分
类型级别 — 放在各类型文件中
```
## ObjectType:
```
/
```
## RelationType:
```
/ …之后、第一个
```
###
```
之前的正文部分；切勿放在前置元数据中
属性级别 — 放在数据属性表格的描述列中
禁止额外章节 — 不要在标准章节外添加Markdown内容；导入时解析器可能会丢弃未解析的内容

Validation checklist

验证检查清单

```
network.bkn
```
at root; frontmatter matches spec
Every
```
.bkn
```
has valid YAML frontmatter (
```
type
```
,
```
id
```
,
```
name
```
)
Files live under folders matching
```
type
```
(
```
object_types/
```
,
```
relation_types/
```
, …); filename =
```
{id}.bkn
```
Network Overview lists all definition IDs — no missing/extra
Relations/actions reference existing object-type IDs; concept groups list only existing objects
Parameter binding
```
Source
```
∈
```
property
```
|
```
input
```
|
```
const
```
; YAML blocks (e.g. trigger) parse
Heading hierarchy has no skipped levels
Business rules only in allowed places (see Business rules placement)

```
network.bkn
```
位于根目录；前置元数据符合规范
每个
```
.bkn
```
文件都包含有效的YAML前置元数据（
```
type
```
、
```
id
```
、
```
name
```
）
文件存放在与
```
type
```
匹配的文件夹下（
```
object_types/
```
、
```
relation_types/
```
等）；文件名 =
```
{id}.bkn
```
网络概述中列出所有定义ID — 无遗漏或多余
关系/动作引用的对象类型ID存在；概念组仅包含已存在的对象
参数绑定
```
Source
```
∈
```
property
```
|
```
input
```
|
```
const
```
；YAML块（如trigger）可正常解析
标题层级无跳跃
业务规则仅放在允许的位置（参考业务规则放置）

Output rules

输出规则

Emit raw
```
.bkn
```
content — do not wrap the whole file in a fenced
```
markdown
```
block
Reuse IDs consistently across relations/actions
IDs: lowercase + underscores; display text Chinese unless asked otherwise
Keep heading order per spec

输出原始
```
.bkn
```
内容 — 不要将整个文件包裹在带围栏的
```
markdown
```
块中
在关系/动作中一致复用ID
ID：小写字母+下划线；显示文本默认使用中文，除非另有要求
保持标题顺序与规范一致

Examples

示例

references/examples/k8s-network/ — modular sample (objects, relations, actions, concept group)

references/examples/k8s-network/ — 模块化示例（对象、关系、动作、概念组）

Delivered BKN: root SKILL.md

交付的BKN：根目录SKILL.md

When you build a knowledge network directory

{network_dir}/

, add

{network_dir}/SKILL.md

at the root (alongside

network.bkn

.bkn

without scanning. Optional: topology sketch, usage scenarios. Example: references/examples/k8s-network/SKILL.md.

当您构建知识网络目录

{network_dir}/

时，请在根目录添加

{network_dir}/SKILL.md

（与

network.bkn

同级）。内容包含简短概述 + 带文件路径的索引表格（对象 | 路径 | 关系 | 路径 | 动作 | 路径），以便Agent无需扫描即可定位到正确的

.bkn

文件。可选内容：拓扑示意图、使用场景。示例：references/examples/k8s-network/SKILL.md。