在 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 的规则因明确提及列名而成功自动链接 24。
6. 实战验证与量化表现
在 disaster 数据库（10 表，54 规则）上，编译器成功生成了 64 个概念文件。随后，脚本对 LiveSQLBench 中的全部 18 个数据库进行了编译，所有生成的 bundle 均通过了一致性校验。这表明该编译器具备良好的规模化能力。相关代码已在 okf-sql-knowledge 仓库开源，为构建高性能 SQL Agent 提供了坚实的知识基础 1。
小结
构建 Agent 就绪的 OKF 知识包，核心在于"结构化"与"可导航"。通过标准化的编译器架构，我们将原本静态的数据库文档转化为动态的知识图谱。虽然当前方案在复杂嵌套 JSONB 的 SQL 命中率及纯文本规则链接上仍存在挑战（需进一步实验量化 Token 消耗与准确率的差异），但其提供的透明缺口报告机制和双向链接导航，已显著提升了 Agent 对数据库上下文的理解能力。