bkn-draft

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

# BKN 草案落盘

公约：`../_shared/contract.md`

## 委托技能

| 技能 | 用途 | 必须 |
|------|------|------|
| `bkn-archive` | 归档路径生成、ARCHIVE_ID/TIMESTAMP、回读校验 | 是 |
| `bkn-kweaver` | `kweaver 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`）→ 写入真实 `view_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-kweaver` 执行 `kweaver 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 解析