# BKN vs RESTful API：业务知识网络建模方式对比

本文对比两种“业务知识网络（BKN, Business Knowledge Network）”的建模/变更方式：

- **RESTful API 方式**：通过接口（或 UI/脚本调用接口）直接对系统中的知识网络做增删改。
- **BKN 文件方式**：通过 `.bkn`（Markdown-based）声明式描述目标形态，再导入到系统落地。

结论先行：

- **推荐组合**：BKN 作为“声明式建模入口/变更载体”，RESTful API 作为“落地执行接口（写入知识网络）”。
- 不建议把两者做成“双写双源”，否则容易出现状态漂移与治理失控。

---

## 1. 目标受众与可读性

| 维度 | RESTful API | BKN |
|------|-------------|-----|
| **业务读者（领域专家/运营/PM）可读性** | 中：API payload/字段语义偏工程 | 高：Markdown + 表格 + 业务描述更直观 |
| **工程读者（平台/后端）可读性** | 高：字段明确、类型严格 | 中高：前提是规范与模板稳定 |
| **跨角色协作** | 中：需要额外文档解释 | 高：文档即契约，review 友好 |

**经验法则**：
- 业务读者通常只关心“对象是什么、怎么连、能做什么”，BKN 更接近“业务词典/说明书”。
- 工程读者更关心“幂等、校验、失败策略、审计、权限”，这需要 BKN 配套导入工程化能力。

---

## 2. 大模型（LLM/Agent）友好度

| 维度 | RESTful API | BKN |
|------|-------------|-----|
| **生成难度** | 中：JSON/YAML 结构严格，容易缺字段/错类型 | 低中：结构更接近自然语言，生成更稳 |
| **局部编辑/增量修改** | 中：局部 patch 容易破坏结构一致性 | 高：修改单文件中的定义段落，导入器自动通过 checksum 识别变更 |
| **上下文长度（token）** | 中：大型网络需要拼大量 payload | 高：Markdown 格式紧凑，按 `##` 标题可定位具体定义 |
| **可解释性** | 中：语义分散在字段中 | 高：可用标题、段落、表格显式表达语义 |

建议的 LLM 友好策略：
- 统一模板（尤其是 ActionType），让模型的生成模式稳定可复用。
- 单文件内按 `##` 标题组织定义，LLM 可按需定位和编辑具体段落。

---

## 3. 稳定性与一致性（线上状态 vs 声明载体）

| 维度 | RESTful API | BKN |
|------|-------------|-----|
| **强校验与类型安全** | 高：接口层可强约束 | 取决于实现：需 validate/dry-run |
| **幂等与冲突处理** | 可控：由服务端保证 | 取决于导入语义：需明确 upsert 规则 |
| **状态漂移风险** | 中：多人/多工具直接写入可能漂移 | 中：若存在“线上改动但不回写 BKN”也会漂移 |
| **可回放/可对比** | 中：需额外实现 diff/审计 | 高：Git diff + 变更文件天然可回放 |

**推荐的“单一最终态”原则**：
- 系统中的**知识网络状态**作为最终态（Source of Truth）。
- BKN 作为**声明与变更输入**，通过导入器转换为 API 调用落地。

---

## 4. 工程化能力对比

| 能力 | RESTful API | BKN（建议配套） |
|------|-------------|----------------|
| **变更预演（dry-run）** | 需要服务端支持 | 导入器提供：解析→计算变更集→不落地 |
| **变更集（diff）** | 需要服务端或工具支持 | 导入器天然适合：新增/更新/删除列表 |
| **批量导入** | 可做但易出错 | 强项：目录级批量导入 |
| **校验（lint/validate）** | 强项：服务端校验 | 需要补齐：引用存在性、参数绑定、命名规范 |
| **导出（export）** | 需要单独接口 | 强烈建议：线上导出 BKN 以对齐与回滚 |
| **CI 集成** | 可做但不直观 | 强项：对 `.bkn` 做 lint/validate，阻止错误合入 |

---

## 5. 安全与治理（尤其 ActionType）

ActionType 连接执行面（tool/mcp），治理难点并不在”写法”，而在”权限/审计/安全边界”。

| 维度 | RESTful API | BKN |
|------|-------------|-----|
| **权限控制** | 强项：接口鉴权天然可做 | 必须依赖导入器与执行层的鉴权 |
| **审批与发布流程** | 需要流程系统配合 | 可用 Git PR 作为审批入口（更透明） |
| **审计追踪** | 需要统一日志 | 建议：执行日志关联到 BKN 定义版本/提交 |

**建议 ActionType 固定信息结构**（提升人类可读 + 风险可控）：
- 触发条件（何时触发）
- 影响范围（影响哪些对象/资源）
- 权限与前置条件（谁能启用/执行）
- 回滚/失败策略（失败如何处理/如何撤销）

---

## 6. 选择建议（什么时候用哪种）

- **优先用 BKN**：
  - 大规模网络（类型很多）
  - 需要跨团队协作与审计
  - 需要 Agent 参与增量建模/维护
  - 希望把“知识网络定义”当作可 review 的资产

- **优先用 API（直接调用）**：
  - 临时性小变更/试验（且你接受之后再回写到 BKN）
  - 强交互式配置（需要 UI 引导选择、实时校验与预览）

---

## 7. 推荐落地形态（BKN + RESTful API）

推荐把系统拆成四层：

1. **BKN 文件**（人类/Agent 可读写）
2. **BKN Importer**（parse + validate + dry-run + diff + apply）
3. **Knowledge Network RESTful API**（唯一写入通道）
4. **Knowledge Network Storage**（最终持久化状态）

Importer 的最小能力建议：
- `validate`：语法/命名/引用/参数绑定校验
- `dry-run`：输出变更集但不落地
- `apply`：按幂等 upsert 规则落地
- `export`：从线上导出 BKN 以对齐与回滚

