bkn-draft

name	bkn-draft
description	将确认后的建模清单生成 .bkn 文件。

BKN 草案落盘

公约：../_shared/contract.md

委托技能

技能	用途	必须
bkn-archive	归档路径生成、ARCHIVE_ID/TIMESTAMP、回读校验	是
bkn-openbkn	openbkn bkn validate 结构校验	是

执行前必须读取 references/SPECIFICATION.llm.md 获取规范模板，不可凭记忆生成 .bkn 格式。 落盘路径必须走 bkn-archive，确保双轨路径（根段 archives/）和回读校验。

做什么

将用户确认的对象/关系/动作清单转化为 .bkn 文件目录，落盘到归档路径。

输入

• 已确认的对象/关系/动作清单（含 存储位置 标记）
• network_context：网络名称、领域
• mode：create（新建） | patch（更新） | copy（复制）

流程

1. 读取 ../bkn-archive/SKILL.md，获取 ARCHIVE_ID + TIMESTAMP + 归档路径
2. 读取 references/SPECIFICATION.llm.md，按 BKN v2.0.1 规范生成 .bkn 文件
   • 业务规则放置：遵循 references/SPECIFICATION.llm.md 的"业务规则放置"章节
   • 输出规则：遵循 references/SPECIFICATION.llm.md 的"输出规则"章节
3. 落盘到 {network_dir}/bkn/（即 archives/{ARCHIVE_ID}/{TIMESTAMP}/{NETWORK_DIR_NAME}/bkn/）
   • network.bkn 放入 bkn/ 根
   • object_types/、relation_types/、action_types/、concept_groups/ 等子目录均在 bkn/ 下创建
4. network.bkn 的 id 使用 {network_name} 的 slug 化形式（中文转拼音或英文直用，全小写、连字符分隔，如 bu-profit-settlement），补齐 icon: icon-dip-graph、color: #0e5fc5
   • 推送后若平台返回新 kn_id，委托 bkn-backfill 回填更新 network.bkn 中的 id
   • 禁止使用空字符串 "" 作为 id，平台 validator 会拒绝
5. 对象类分配随机颜色
6. 存储位置处理：
   • platform 对象：生成完整 BKN 格式（含 Data Source、Logic Properties 等）
   • local 对象（仅用于模型内部逻辑推理，无外部数据源）：
     • 省略 ### Data Source 节
     • 省略 Mapped Field 列（Data Properties 表格中不生成此列）
     • 省略 ### Logic Properties 节
     • 省略 Incremental Key
     • 仅保留 Data Properties（定义对象的基本属性结构）
   • 注意：relation_types 和 action_types 中的关系/动作可以引用 local 对象的属性，draft 阶段照常生成对应关系/动作文件
7. Data Source 处理（仅 platform 对象）：
   • 若此时已完成资源绑定（有 binding_decision_list）→ 写入真实 resource_id
   • 若尚未绑定 → 省略整个 ### Data Source 小节，不写占位符
   • 禁止写 待绑定 或任何占位文本，平台会将其解析为 view ID 导致推送失败
8. Mapped Field 同理：无绑定时写 -，不写占位
9. Description 仅写稳定业务语义
10. 关系映射属性交叉验证（生成关系文件后必须执行）：
    • 遍历所有 relation_types/*.bkn，对每个关系文件：
      1. 解析 Endpoint 中的 Source 对象 ID 和 Target 对象 ID
      2. 解析 Mapping Rules 中的 Source Property 和 Target Property
      3. 确认 Source Property 存在于 Source 对象 object_types/{source_id}.bkn 的 Data Properties 中
      4. 确认 Target Property 存在于 Target 对象 object_types/{target_id}.bkn 的 Data Properties 中
      5. 若任一属性不存在 → 修正映射规则中的属性名使其与目标对象 Data Properties 中的实际属性名一致；若无法确定正确属性名，记录错误并提示
    • 对 action_types/*.bkn 同理：确认 Parameter Binding 中引用的属性存在于 Bound Object 的 Data Properties 中
11. 委托 bkn-openbkn 执行 openbkn bkn validate {network_dir}/bkn/
12. 对照校验清单复核
13. 用户复核

输出

• .bkn 文件目录（位于 {network_dir}/bkn/）
• validate 结果
• root SKILL.md（可选）：在 BKN 目录根添加 {network_dir}/SKILL.md（与 network.bkn 同级），包含简短概述 + 索引表（object | path | relation | path | action | path），方便 agent 定位 .bkn 文件

校验清单

生成后必须逐项检查：

• network.bkn 在根目录；frontmatter 符合规范（type: knowledge_network、id、name）
• 每个 .bkn 有有效的 YAML frontmatter（type、id、name）
• 文件放在与 type 匹配的文件夹下（object_types/、relation_types/、action_types/、concept_groups/）；文件名 = {id}.bkn
• Network Overview 列出所有定义 ID — 无遗漏/多余
• 关系/动作引用已存在的 object-type ID；概念分组只列出已存在的对象
• 关系映射属性存在性：所有 relation_types 的 Mapping Rules 中 Source/Target Property 在对应对象 Data Properties 中存在
• 动作参数属性存在性：所有 action_types 的 Parameter Binding 中引用的属性在 Bound Object 的 Data Properties 中存在
• Parameter binding 的 Source ∈ property | input | const；YAML 块（如 trigger）可解析
• 标题层级无跳跃（# → ## → ### → ####）
• 业务规则只在允许位置（见 references/SPECIFICATION.llm.md 的"业务规则放置"章节）

数据类型选型

生成 Data Properties 时，Type 必须从规范合法类型中选择：

语义	选型
数量、金额、单价	decimal
计数、序号、版本号	integer
比率、百分比	float

禁止使用 number——平台不认识此类型，推送时报 InvalidParameter。

Action Type 选型

Bound Object 表的 Action Type 列只允许三个值：

值	语义
add	新增（不可写 create，是后端保留字）
modify	修改（不可写 update，是后端保留字）
delete	删除

当前平台版本不支持 query。如有只读操作需求，暂用 modify 并在 Description 标注。

资源索引

类型	规范章节	模板	示例
Network	knowledge_network	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

完整规范：references/SPECIFICATION.llm.md。

约束

• 本 skill 不做建模决策，只做清单 → 文件的转换
• Description 不写映射猜测信息
• 不写任何占位符文本（"待绑定"/"待确认"/"TBD"等），占位值会被平台当作真实 ID 解析