在 AI Agent 自主编写 SQL 的场景中，仅仅提供数据库 Schema 往往是不够的。Agent 还需要理解业务术语（如指标定义、风险条件）才能生成准确的查询。然而，原始文档（如建表语句、列字典、业务规则）通常散落在各处，格式不一，难以被 Agent 有效检索。本文旨在通过构建一个基于 OKF（Open 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 对数据库上下文的理解能力。
