Bkn Rules

业务规则提取

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

做什么

从整个建模过程的输入中提取业务规则，组织为结构化的可复用 Skill 产物。 这是业务沉淀的核心环节，在 create pipeline 中为必执行步骤。

执行模式

bkn-rules 支持两种模式，由调用方指定：

| 模式 | 时机 | 输入 | 行为 | |------|------|------|------| | full（默认） | 阶段五（首次生成） | PRD + 对话 + 提取结果 + 绑定结果 | 完整提取、分组、生成 Skill 文件 | | incremental | 阶段六评审循环结束后 / 阶段七推送后 | 已有 Skill 文件 + 评审调整结果 | 读取已有 Skill，合并新增/变更的规则，更新文件 |

输入

• mode：full | incremental（默认 full）
• network_id：网络唯一标识（必填）
• network_dir：网络目录（.bkn 文件位于 {network_dir}/bkn/，Skill 文件位于 {network_dir}/skills/）
• network_name：网络名称
• prd_content：PRD / 产品文档（incremental 模式可选）
• rule_extraction_check：阶段一末尾提取的结构化规则
• network_context：网络名称、领域
• conversation_context（可选）：建模对话中的补充知识
• binding_rules（可选）：绑定过程中发现的映射规则
• review_adjustment_plan（可选，incremental 模式）：bkn-review 输出的 adjustment_plan（包含规则缺失的诊断和修复建议）

规则来源与优先级

| 来源 | 提取内容 | 冲突时 | |------|---------|--------| | PRD / 产品文档 | 需求约束、流程规则、判定条件 | 以用户对话为准 | | 用户对话 | 补充的业务知识、行业惯例 | 最高优先级 | | ruleextractioncheck | 已结构化的主键/过滤/枚举/计算/层级规则 | — | | 绑定分析 | 字段语义映射规则、数据质量约束 | — | | 评审调整（incremental） | review_adjustment_plan 中标识的规则缺失项，经调整后产生的新规则 | 以调整后为准 |

Skill 自检（生成后必执行）

Skill 文件生成后，必须执行以下自检，失败则标注警告但不阻断流程：

| 检查项 | 判定标准 | |--------|---------| | frontmatter 完整性 | 必须包含 name、description、domain、network、network_id、version、lifecycle_state | | 文件结构合法性 | 必须包含规则总览表 + 至少一组详细规则 | | 规则可追溯性 | 每条规则必须标注 source（prd / conversation / extraction / binding / adjustment） | | 规则可执行性 | 高风险规则必须包含明确的判定条件或验证要点 | | 反例覆盖 | 高风险规则至少有一条反例或验证要点 |

Skill 拆分策略

根据规则数量和复杂度决定拆分粒度：

| 规则总数 | 策略 | 说明 | |---------|------|------| | ≤ 30 | 单 Skill | 一个网络一个规则 Skill，文件名 {network_id}-rules.md | | 31–80 | 按领域分组 | 每个概念分组一个 Skill，文件名 {network_id}-{group_slug}.md | | > 80 | 按对象拆分 | 每个核心对象一个 Skill，文件名 {network_id}-{object_slug}-rules.md |

拆分策略变化时的处理（incremental 模式）：

• 规则数量跨越阈值导致需要重新拆分/合并时，所有被替换的旧文件全部移入 _archived/
• 新生成的文件按命名规范创建，版本号延续当前版本并递增
• 合并场景（如 50→20 条）：多个分组合并为单 Skill，旧文件全部归档，生成新的 {network_id}-rules.md
• 拆分场景（如 20→50 条）：单 Skill 拆分为多个，旧文件归档，生成新的 {network_id}-{group_slug}.md 系列

命名规范

• Skill 文件名统一使用 network_id 标识，不使用网络名（中文/特殊字符可能导致路径不稳定）
• 单 Skill 场景：{network_id}-rules.md
• 多 Skill 场景（按领域分组）：{network_id}-{group_slug}.md
• group_slug 为概念分组名的英文短标识（如 sales-rules、inventory-rules）
• 文件名与 skill name 保持一致（name frontmatter = 文件名去 .md）
• 每个 Skill 文件必须有 YAML frontmatter：

``yaml --- name: "{network_id}-rules" # 单 Skill # name: "{network_id}-{group_slug}" # 多 Skill 场景 description: "..." domain: "" network: "" network_id: "" version: "1.0.0" lifecycle_state: active | draft | archived --- ``

版本规则：

• full 模式首次生成：version: "1.0.0"，lifecycle_state: active
• incremental 模式：读取当前版本的 version，递增 minor（如 1.0.0 → 1.1.0）
• 语义版本：major.minor.patch，minor 增量更新，major 结构性大改时递增

归档机制（incremental 模式）：

• 更新前将旧版本移入 {network_dir}/skills/_archived/
• 归档命名：{原文件名}-v{旧版本号}-{YYYYMMDD-HHmmss}.md
• 例：mat-master-rules-v1.0.0-20260410-143022.md
• 写入新版本后，lifecycle_state: active
• full 模式首次生成无需归档

Skill 文件结构

每个 Skill 文件遵循标准 SKILL.md 结构：

1. Frontmatter（name, description, domain, network, networkid, version, lifecyclestate）
2. 规则总览表（rule_id / 规则名 / 类型 / 关联对象）
3. 分组详细规则
4. 依赖关系图

流程

1. 确认执行模式（full 或 incremental）
2. full 模式：
3. 收集所有规则来源
4. 提取规则（每条标注 source）
5. 去重归并（同规则多来源合并，保留最完整版本）
6. 按领域/对象分组
7. 决定拆分策略（按上表）
8. 高优先级规则补反例 + 验证要点
9. 分析规则间依赖
10. incremental 模式：
11. 读取 {network_dir}/skills/ 下已有规则 Skill 文件（排除 _archived/ 目录）
12. 降级判定：若未找到任何已有 Skill 文件，降级为 full 模式执行，后续步骤按 full 模式处理
13. 结合 review_adjustment_plan 中标识的规则缺失项和当前建模状态（对象/关系/动作草案），识别新增/变更/废弃的规则
14. 归档旧版本：将已有 Skill 文件移入 {network_dir}/skills/_archived/，重命名为 {原文件名}-v{旧版本号}-{YYYYMMDD-HHmmss}.md。确保 _archived/ 目录存在（不存在则创建）
15. 合并到已有 Skill 文件中（保留原有 source 标注，新增标注 source: adjustment），递增版本号
16. 重新执行拆分策略判定（规则数量变化可能导致需要重新拆分/合并，见上方拆分策略变化处理规则）
17. 生成 Skill 产物，落盘到 {network_dir}/skills/
18. Skill 自检（见上方自检表），结果输出到 skill_self_check
19. 锚定与分发：

• full 模式：每个 Skill 对应一个 bkn-anchor 锚定对象，后续由 pipeline 委托 bkn-distribute 分发
• incremental 模式：仅新增 Skill 需要锚定，已有 Skill 原地更新
• create pipeline 场景（阶段六评审后/阶段七推送后）：不触发重新分发（避免覆盖用户手动修改），仅输出差异清单供 pipeline 决定是否重新分发
• feedback pipeline 场景：修复完成后 pipeline 会显式委托 bkn-distribute 覆盖各平台副本

输出

business_rules_skill:
  skill_name: "{network_id}-rules"
  mode: full | incremental
  domain: ""
  version: "1.0.0"
  lifecycle_state: active
  rules_summary: {total, by_type, added, modified, removed}
  archived_files: []  # incremental 模式：被归档的旧版本路径列表
  rule_groups:
    - group_name: ""
      rules:
        - rule_id: BR-001
          rule_name: ""
          rule_type: 主键规则 | 过滤规则 | 枚举规则 | 计算规则 | 层级规则 | 约束规则 | 映射规则
          description: ""
          source: prd | conversation | extraction | binding | adjustment
          related_objects: []
          validation_points: []
          counterexample: ""
  dependency_graph: {}
skill_self_check: {frontmatter: pass|fail, structure: pass|fail, traceability: pass|fail, executability: pass|fail, counterexamples: pass|fail, warnings: []}
skill_artifact_path: ""

规则存储边界

业务规则存在两个落地位置，职责不同：

| 位置 | 内容 | 写入方 | 消费方 | |------|------|--------|--------| | .bkn 文件 Description 列 | 属性级的简短语义说明（≤ 30 字） | bkn-draft | 平台 schema 展示、语义搜索命中 | | skills/{network_id}-rules.md | 完整规则定义（条件、公式、反例、依赖） | bkn-rules（本 skill） | Agent 推理、Q&A 验证、业务沉淀 | | skills/_archived/ | 旧版本 Skill 归档（incremental 模式生成） | bkn-rules | 版本回滚、变更追溯 |

原则：

• Description 是"标签"——告诉平台这个字段大概什么意思
• Skill 是"手册"——告诉 Agent 完整的业务逻辑
• 两者的内容可以重叠，但 Skill 必须是 Description 的超集
• BKN 规范明确禁止在 .bkn 文件中添加规范外的额外 section，所以复杂规则只能放 Skill

验证方式：

• qa_verify 路径 B（语义搜索）验证的是 Description 的可达性
• qa_verify 路径 C（Decision Agent）验证的是 Skill 的推理完整性
• 两个路径都通过，才说明"规则可用"

约束

• 所有规则必须有来源标注，不编造不存在的规则
• 未提取到的规则标注 TBD，不伪造
• 冲突表述以用户对话确认为准，标注冲突
• Description 列只写精炼语义，完整规则写 Skill 文件

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kweaver-ai
• Source: kweaver-ai/kweaver-dip
• License: Apache-2.0
• Homepage: https://kweaver.ai

Install and usage instructions live in the source repository linked above.