# Bkn Backfill

> Bkn Backfill is an Agent Skill for documents published in the kweaver-ai/kweaver-dip repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

将绑定/映射结果写回 .bkn 文件。

- Skill name: `bkn-backfill`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/kweaver-ai/kweaver-dip/blob/HEAD/skills/bkn-creator/internal/bkn-backfill/SKILL.md
- Repository: kweaver-ai/kweaver-dip (298 GitHub stars when collected)

## SKILL.md

# BKN 回填

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

## 做什么

把 `bkn-bind` 和 `bkn-map` 的结果合并，写回 `.bkn` 文件，完成数据视图绑定闭环。

## 输入

- `binding_decision_list`：对象级绑定结果
- `property_mapping_draft`：属性级映射结果
- `relation_binding_result`：`bkn-relation-bind` 的输出（关系类型 + 中间视图）
- `relation_mapping_draft`：`bkn-map` 的关系类映射结果
- `network_dir`：网络目录（`.bkn` 文件位于 `{network_dir}/bkn/`）

## 流程

1. **属性回灌门禁**（P1-2）：
   - 读取 `{network_dir}/pipeline_state.yaml`（文件不存在时视为 `map_completed` 缺失）
   - **`map_completed == true`** → 继续
   - **`map_completed == skipped`**（`bind_mode == deferred` 场景）→ 记录 `map_status: skipped (deferred)`，继续
   - **`map_completed` 不存在或为 false**：
     - 用户明确要求跳过 → 在 `pipeline_state.yaml` 中追加 `skipped_steps: [bkn-map]`，输出警告后继续
     - 否则，**阻断并回交 pipeline 调度**，输出：
       `"bkn-backfill 需要 bkn-map 先执行完成（map_completed 未就绪）。请 pipeline 调度 bkn-map 后再调用本 skill。"`
2. 合并绑定变更 + 属性变更 + 映射状态为统一差异清单
3. **存储位置过滤**：
   - 跳过 `存储位置: local` 的对象（本地对象无需数据视图绑定，不参与回填）
   - 在输出摘要中单独列出被跳过的 local 对象
4. **对象类回填**（仅 platform 对象）：
   - Data Source 绑定值替换（名称/技术名 → 稳定 `view_id`）
   - Mapped Field 更新为数据视图真实字段名
   - 数据视图中不存在的属性：默认标注 Mapped Field 为 `-`（保留属性定义，便于后续补绑）；用户可指定删除该行
   - 不改动 Description 或其他业务语义字段
5. **级联修正**（关键改进）：
   - 构建 `rename_map`：`{object_id: {old_property_name → new_property_name}}`
     - 来源 1：`bkn-map` 的 `property_regen_summary.rename` 动作（draft 属性名 → 视图字段名）
     - 来源 2：用户手动指定的属性重命名
   - 扫描 `{network_dir}/bkn/relation_types/*.bkn` 的 Mapping Rules，将 Source Property / Target Property 中引用了已重命名属性的值替换
   - 扫描 `{network_dir}/bkn/action_types/*.bkn` 的 Parameter Binding / Pre-conditions，将 Binding 列中引用了已重命名属性的值替换
   - 级联修正只改引用名，不改语义
6. **关系类回填**（新增）：
   - 仅处理 `relation_binding_result` 中 `status: confirmed` 的关系
   - **direct 类型**：
     - 回填 Endpoint 表的 Type 列为 `direct`
     - 回填 Mapping Rules 表（Source Property → Target Property）
   - **data_view 类型**：
     - 回填 Endpoint 表的 Type 列为 `data_view`
     - 回填 Mapping View 表（Type = data_view, ID = intermediate_view_id）
     - 回填 Source Mapping 表（Source Property → View Property）
     - 回填 Target Mapping 表（View Property → Target Property）
   - **pending 关系**：
     - 仅回填 Endpoint 表（Type 列保留占位符或留空）
     - Mapping View / Source/Target Mapping 段不生成
   - 跳过 `relation_mapping_quality: blocked` 的关系（在输出中标记）
7. **推送前关系映射完整性预检**（执行 `../_shared/prepush-validation.md`）：
   - 检查所有 `relation_types` 的 Source/Target Property 是否存在于对应对象的 Data Properties
   - 检查所有 `action_types` 的 Parameter Binding 属性是否存在于绑定对象的 Data Properties
   - 检查 Concept Group 成员和 Network Overview 一致性
   - 检查 data_view 类型关系的 Mapping View ID 是否非空
   - 检查 data_view 类型关系的 Source/Target Mapping 属性是否存在于对应视图 schema
   - `local` 对象跳过属性存在性检查，但仍参与对象存在性检查
   - `pending` 关系仅 warning，不阻断
   - **预检失败 → 阻断写入，列出全部错误**，提示修复后重试
8. 执行写入（写入 `{network_dir}/bkn/` 下对应的 `.bkn` 文件）
9. 回读校验（文件存在、关键字段已替换、级联引用一致、关系类结构完整）
10. 输出精简摘要，提示用户检查

## 输出

```yaml
backfill_plan:
  binding_replacements: [{object, old_value, new_view_id}]
  property_changes: [{object, property, action, layer}]
  cascade_renames: [{file, table, old_ref, new_ref}]
  # 新增：关系类回填计划
  relation_replacements:
    - 关系ID: ""
      关系名称: ""
      关系类型: direct | data_view
      actions:
        - action: ""                  # fill_endpoint_type / fill_mapping_view / fill_source_mapping / fill_target_mapping
          target_section: ""          # Endpoint / Mapping View / Source Mapping / Target Mapping
          old_value: ""
          new_value: ""
  skipped_local_objects: [对象名]
  skipped_pending_relations: [关系名]  # pending 关系，跳过回填
  map_gate: {map_completed: true|false|skipped, user_skipped_map: true|false, blocked_for_map: true|false}
  prepush_validation: {status, errors}  # 写入前预检结果
backfill_status: success | partial | failed
verification: 
  files_checked: 0
  fields_replaced: 0
  cascade_refs_fixed: 0
  relations_filled: 0              # 新增：已回填的关系数量
  pending_relations: 0             # 新增：pending 关系数量
  issues: []
```

## 约束

- 只写 Data Source、Mapped Field 和级联引用，不改业务语义字段
- 级联修正仅限属性名引用，不修改关系方向或动作语义
- **写入前必须执行 `../_shared/prepush-validation.md` 预检，失败则阻断写入**
- **执行回填前必须确认 `map_completed == true` 或 `skipped`，否则阻断并回交 pipeline 调度**
- 写入后必须回读校验，包括级联引用一致性
- 回填失败时保留差异清单，可重试

---

Source: https://www.openparable.com/skill/documents/bkn-backfill (OpenParable). Cite the canonical URL above.