在 AI Agent 自主编写 SQL 的场景中仅仅提供数据库 Schema 往往是不够的。Agent 还需要理解业务术语如指标定义、风险条件才能生成准确的查询。然而原始文档如建表语句、列字典、业务规则通常散落在各处格式不一难以被 Agent 有效检索。本文旨在通过构建一个基于 OKFOpen Knowledge Format的知识包编译器将非结构化的数据库文档转化为 Agent 可读、可导航的标准化知识体系。以下是基于 Python、PostgreSQL 和 Docker 技术栈的深度技术解析。1. 核心架构设计okf_compiler编译器的核心模块okf_compiler采用职责分离的设计模式主要包含六个子模块Readers负责多源数据接入将 SQL、JSON、JSONL 文件解析为统一的 Python 对象。Concept定义 OKF 规范中统一的 Frontmatter 结构确保生成的元数据一致性。Tables Rules分别处理表结构解析和业务规则提取。Indexes生成导航索引支持层级化检索。CLI提供命令行接口支持单库或全量数据库的一键编译 [1]。这种架构使得编译器具备高度的可扩展性能够轻松适配不同来源的数据库文档。2. 数据标准化与完整性处理在数据读取阶段系统利用正则表达式解析CREATE TABLE语句以获取基础表结构。关键在于如何处理数据不一致性大小写处理系统强制采用小写匹配策略消除 PostgreSQL 中大小写敏感带来的检索歧义。JSONB 嵌套支持针对 PostgreSQL 特有的 JSONB 列编译器专门提取嵌套字段描述生成如impactmetrics.population.affected这样的路径标识帮助 Agent 理解深层数据结构 [1]。防静默失败机制add_column_meanings函数在执行完映射后会显式报告缺失描述的列。这一设计遵循“编译器应报告缺口而非填补”的原则避免 Agent 基于幻觉进行查询 [2]。3. 概念生成与双向链接构建编译器为每个表生成独立的 Markdown 文件包含 Schema 表格、JSON 字段路径及外键 Join 信息。表描述基于列名和 Join 关系自动推导严禁引入 LLM 生成的非源文档知识以保持知识源的真实性。每个文件头部包含 YAML Frontmatter标记编译器版本、生成时间及源文件但明确标记为verified: false强调其机器生成属性 [3]。对于业务规则编译器通过正则表达式提取规则名称和定义中涉及的列名反向查找所属表并建立链接。同时系统自动构建Depends on依赖项和Used by使用者双向链接。这种图结构使得 Agent 能够从一个规则出发通过依赖关系导航至相关表显著降低检索路径长度 [1]。4. 索引导航机制为了避免 Agent 在大量文档中迷失编译器在每个知识包文件夹下生成index.md。该索引按概念类型如 Calculation, Business Rule分组列出所有概念及其单行描述。工作流程如下Agent 首先读取index.md作为“菜单”根据意图筛选相关文件仅加载必要的细节。这种分层检索策略大幅减少了 Token 消耗。索引数据仅从概念文件的 Frontmatter 中提取因此支持对手动编辑后的 bundle 重新生成索引保证了索引与内容的同步 [1]。5. 完整性校验与缺口分析编译器集成了okf_validate工具用于校验生成的 bundle 是否符合 OKF v0.2 规范重点检查链接的有效性。对于无法自动链接的情况编译器不猜测而是生成缺口报告。例如在news数据库案例中48/61 的业务规则因未提及具体列名而无法自动链接到表这些缺口被明确标记需人工介入处理。相比之下在disaster数据库中50/54 的规则因明确提及列名而成功自动链接 [2][4]。6. 实战验证与量化表现在disaster数据库10 表54 规则上编译器成功生成了 64 个概念文件。随后脚本对 LiveSQLBench 中的全部 18 个数据库进行了编译所有生成的 bundle 均通过了一致性校验。这表明该编译器具备良好的规模化能力。相关代码已在okf-sql-knowledge仓库开源为构建高性能 SQL Agent 提供了坚实的知识基础 [1]。小结构建 Agent 就绪的 OKF 知识包核心在于“结构化”与“可导航”。通过标准化的编译器架构我们将原本静态的数据库文档转化为动态的知识图谱。虽然当前方案在复杂嵌套 JSONB 的 SQL 命中率及纯文本规则链接上仍存在挑战需进一步实验量化 Token 消耗与准确率的差异但其提供的透明缺口报告机制和双向链接导航已显著提升了 Agent 对数据库上下文的理解能力。