create-bkn

创建 BKN

按照 v2.0.1 生成格式规范的 BKN 目录（Markdown + YAML frontmatter）。

与 kweaver-core 配合使用

create-bkn 负责创建 .bkn 目录树；文件创建完成后，kweaver-core 会运行 kweaver auth login 和 kweaver bkn push / pull。

什么是 BKN

BKN 使用 Markdown + YAML frontmatter 定义架构；每个定义对应一个文件，存放在类型化子文件夹中。详情（章节、必需表格、类型）见 references/SPECIFICATION.llm.md。

目录结构

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

工作流

1. 收集需求——对象、关系、动作、可选的概念组
2. 阅读规范——references/SPECIFICATION.llm.md（格式规则、章节、frontmatter 类型）
3. 选择模板——从 assets/templates/ 复制并调整（network_type.bkn.template、object_type.bkn.template，……）
4. 创建 network.bkn——根文件；与网络概览保持一致
5. 创建 object_types/*.bkn——每个对象一个文件，{id}.bkn
6. 创建 relation_types/*.bkn——每个关系一个文件
7. 创建 action_types/*.bkn——每个动作一个文件
8. 创建 concept_groups/*.bkn——可选
9. 更新 network.bkn——在网络概览中列出所有 ID
10. 在 BKN 目录根目录添加 SKILL.md——与 network.bkn 位于同一文件夹（这不是 create-bkn 技能文件）；为该网络编写面向 Agent 的指南（参见交付的 BKN：根目录 SKILL.md）
11. 审查（必须）——对照验证清单和业务规则的放置位置进行核对；修正 ID、交叉引用和标题
12. 验证（必须）——kweaver bkn validate <dir>（参见验证）
13. 导入（可选）——kweaver bkn push <dir>

导入（kweaver CLI）

需要使用来自 @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>）已成功验证此目录，除非你修改了 .bkn 文件，否则不要在 push 前重复验证。如果尚未验证，请先运行 validate，再执行 push。

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 技能）。

验证

kweaver bkn validate <dir>——交付或上传前必须通过验证。该命令会加载 network.bkn 及其同级 .bkn 文件。成功时会打印统计数量；失败时请修复 .bkn 文件并重新运行。

各类型参考

类型	规范（章节）	模板	示例（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。

命名约定

• ID：小写字母、数字、下划线；文件：位于匹配文件夹下的 {id}.bkn
• 标题：# 网络标题，## 类型块，### 章节，#### 逻辑属性
• Frontmatter：至少包含 type、id、name（各类型的具体要求见规范）

业务规则的放置位置

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

• 网络级——在 network.bkn 中，紧接 # {title} 之后编写说明文字（位于 ## Network Overview 等结构化章节之前）
• 类型级——在各类型文件的 ## ObjectType: / ## RelationType: / … 之后、首个 ### 之前编写说明文字；切勿放在 frontmatter 中
• 属性级——放在 Data Properties 表格的 Description 列中
• 不添加额外章节——不要在标准章节之外添加 Markdown 内容；导入时解析器可能会丢弃无法解析的内容

验证清单

• 根目录下有 network.bkn；frontmatter 符合规范
• 每个 .bkn 都有有效的 YAML frontmatter（type、id、name）
• 文件位于与 type 匹配的文件夹下（object_types/、relation_types/ 等）；文件名 = {id}.bkn
• Network Overview 列出所有定义 ID，不得遗漏或多列
• 关系/操作引用现有对象类型 ID；概念组只列出现有对象
• 参数绑定 Source ∈ property | input | const；YAML 块（例如 trigger）可正常解析
• 标题层级没有跳级
• 业务规则仅放在允许的位置（见业务规则的放置位置）

输出规则

1. 输出原始 .bkn 内容——不要用带围栏的 markdown 代码块包裹整个文件
2. 在各关系/操作中一致地复用 ID
3. ID：小写字母 + 下划线；除非另有要求，显示文本使用中文
4. 按规范保持标题顺序

示例

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

交付的 BKN：根目录 SKILL.md

构建知识网络目录 {network_dir}/ 时，在根目录（与 network.bkn 同级）添加 {network_dir}/SKILL.md。其中包含简短概述和带有文件路径的索引表（对象 | 路径 | 关系 | 路径 | 操作 | 路径），以便 Agent 无需扫描即可找到正确的 .bkn。可选内容：拓扑示意图、使用场景。示例：references/examples/k8s-network/SKILL.md。