转写说明

本文基于已校验的公开原文进行结构化转写与事实梳理，非原文转载。 转写保留可核验的技术事实，并将工程建议与来源观点明确分开。

核心结论

OKF 知识包编译器将散落的数据库文档（建表语句、列字典、业务规则）转化为 Agent 可直接检索的标准化知识体系。编译产物包含独立 Markdown 文件、YAML 元数据及双向链接网络，支持从概念索引到表结构细节的层级导航。系统内置缺口报告机制，区分可自动链接与需人工处理的规则，避免 Agent 基于不完整信息生成幻觉查询。

能力机制

编译器的六个核心模块形成职责分离的流水线。Readers 支持 SQL、JSON、JSONL 多格式接入，解析为统一 Python 对象。Concept 层定义 OKF 规范的 Frontmatter 结构，确保元数据一致性。Tables 模块通过正则表达式提取 CREATE TABLE 语句生成表结构。Rules 模块从原始文档提取业务规则定义。Indexes 根据 Frontmatter 生成按类型分组的导航索引。CLI 提供命令行触发编译。

数据标准化环节采用小写匹配策略消除 PostgreSQL 大小写敏感带来的歧义。针对 JSONB 列，编译器提取嵌套路径标识（如 impactmetrics.population.affected），帮助 Agent 理解深层结构。防静默失败机制通过 add_column_meanings 函数显式报告缺失描述的列，而非自动填补。

概念生成阶段为每个表创建独立 Markdown 文件，包含 Schema 表格、字段路径及外键 Join 信息。表描述基于列名和关系自动推导，严禁引入非源文档知识。每个文件头部包含 YAML Frontmatter，标记编译器版本和生成时间，并明确标记 verified: false 强调机器生成属性。系统通过正则提取规则涉及的列名，反向定位所属表，建立 Depends on 与 Used by 双向链接。

快速开始

编译过程依赖 PostgreSQL 和 Docker 环境。准备阶段需将数据库 Schema 和业务规则文档整理为标准化格式存放于指定目录。执行编译时使用命令行工具触发单库或全量数据库处理，具体命令参考源码仓库说明。生成的 bundle 位于输出目录，包含按概念类型组织的 Markdown 文件和根目录 index.md 导航索引。使用 okf_validate 工具对 bundle 进行 OKF v0.2 规范校验，检查链接有效性并生成缺口报告。

适用边界

编译器在规则链接自动化方面存在明确边界。规则必须明确提及列名才能建立自动链接，未提及具体列名的规则无法自动关联到表。在 disaster 数据库（10 表、54 规则）测试中，50 个规则成功自动链接，另有 4 个因未提及列名产生缺口。在 news 数据库测试中，61 个业务规则中有 48 个未能自动链接。当前方案不处理纯文本规则与表结构的模糊匹配，缺口需人工介入添加链接信息。

系统适用于拥有结构化数据库 Schema 和显式业务规则的场景。对于缺乏明确列名引用的业务文档，需要额外的人工标注流程补充链接信息。

核验清单

生成知识包后应逐项确认以下要素。bundle 目录存在 index.md 导航索引文件。索引按 Calculation、Business Rule 等类型分组，每项包含单行描述。概念文件头部包含完整 YAML Frontmatter，字段包含编译器版本、生成时间、源文件标识。表文件包含 Schema 表格、外键 Join 信息及 JSONB 字段路径。业务规则文件包含规则名称、定义正文及指向关联表的链接。使用 okf_validate 通过一致性校验。无自动链接的规则存在显式的缺口报告标记。概念文件与索引内容保持同步。

来源与核验

  • 原始文章
  • 页面事实以原始来源及其引用的官方资料为准；版本、星标和模型能力会随时间变化。
  • AI Stack 不公开抓取到的全文快照，只发布独立转写与来源入口。

站内链接

相关文章