Ktx: 弥合 LLM Agent 与数据仓库之间的鸿沟

对于许多组织而言，“与你的数据对话”这一梦想往往会撞上现实的墙。通用型 AI Agent 虽然能够编写 SQL，但经常难以应对特定公司数据仓库的细微差别。它们往往在每次提示时都重新探索模式（schema），自行发明指标逻辑，并产生与公司官方报告相冲突的数据。

传统的语义层试图通过定义规范指标和连接（joins）来解决这个问题，但它们需要巨大的手动维护工作，且无法捕捉埋藏在 Notion 页面、维基（wikis）和团队文档中的隐性知识。Ktx 作为一个自改进的上下文层应运而生，旨在弥合这一鸿沟，通过综合技术元数据和业务知识，教导 Agent 如何准确地查询仓库。

问题所在：业务逻辑的“幻觉”

当被要求查询“月度经常性收入 (MRR)”时，Agent 本身并不知道应该连接哪些表，或者应该应用哪些过滤器来排除内部测试账户。如果没有结构化的上下文层，Agent 有两个选择：基于列名进行猜测，或者每次都向用户询问定义。

传统的语义层（如 LookML 或 dbt MetricFlow）提供了“真相”，但它们通常是孤立的。业务逻辑可能存在于 dbt 项目中，而“流失客户”的定义则存在于 Notion 文档中。Agent 通常无法同时导航这些互不连接的数据源。

Ktx 的工作原理：多维上下文层

Ktx 不仅仅是一个代理；它通过几个自动化过程构建数据环境的全面地图：

1. 自动化数据栈映射

Ktx 不要求人工映射每个关系，而是通过对表进行采样、捕获元数据并分析使用模式来检测可连接的列。这减少了通常与设置语义层相关的手动开销。

2. 知识摄取

Ktx 摄取来自维基和团队知识库的内容。它组织这些信息，去除重复项，并——至关重要的是——标记矛盾之处以供人工审核。这确保了如果维基说了一套，而 dbt 定义了另一套，这种差异会被高亮显示而不是被忽略。

3. 语义层综合

通过使用连接图（join graph）将原始表和高层级指标结合起来，Ktx 会自动解决常见的 SQL 陷阱，如“深渊陷阱 (chasm traps)”和“扇形陷阱 (fan traps)”。这使得 Agent 可以以声明式的方式获取指标，这意味着它们可以请求“收入”，而无需为每个查询从头开始重写规范的 SQL 连接逻辑。

4. 通过 MCP 进行 Agent 执行

Ktx 通过 CLI 和 Model Context Protocol (MCP) 暴露其知识。这使得 Claude Code、Cursor 或 OpenCode 等 Agent 可以将 Ktx 作为工具使用，在维基和语义层中进行全文检索和语义搜索，以找到正确的数据路径。

对比：通用 Agent vs. 传统语义层 vs. Ktx

特性	通用型 Agent	传统语义层	Ktx
仓库上下文	手动/即时	手动	自动化
连接检测	启发式/猜测	手动	自动化
指标定义	即时发明	已批准/可重用	已批准/可重用
知识吸收	无	无	维基/Notion 集成
矛盾标记	无	无	自动化
Agent 集成	部分	无	CLI + MCP

技术架构与安全性

在将 AI 引入数据仓库时，首要关注的问题之一是安全性。Ktx 通过“设计即只读”的理念来解决这个问题。它从不向数据库写入数据，从而确保了仓库的完整性。

此外，Ktx 在本地运行。它不会将模式（schema）或查询结果发送到托管服务；唯一离开本地环境的数据是发送给配置的 LLM 提供商（如 Anthropic 或 Google Vertex AI）的数据。

社区洞察：文档的 ROI

在 Hacker News 的讨论中，用户指出，随着时间的推移，此类工具的价值主张已发生变化。正如一位评论者 @lifeisstillgood 所观察到的：

"Making such docs had next to no ROI 10 years ago. But today they are the difference between success and failure."

这突显了数据工程中的一个根本转变：文档不再仅仅是为了给人类阅读；它现在是 AI Agent 与我们系统交互的主要接口。此外，讨论中还提出了 Token 管理的挑战，并建议采用分层检索——先获取高层级事实，仅在必要时才获取全文——这是在不增加 Token 成本的情况下保持 Agent 有用性的最有效方式。

开始使用 Ktx

Ktx 适用于使用 PostgreSQL、Snowflake、BigQuery、ClickHouse、MySQL、SQL Server 或 SQLite 的团队。它与 dbt、Looker 和 Metabase 等现有工具集成。

要初始化一个项目，用户可以运行：

pm install -g @kaelio/ktx
ktx setup
ktx status

这将创建一个本地项目目录，其中包含 ktx.yaml 配置、用于 YAML 源的 semantic-layer/ 目录以及用于业务上下文的 wiki/ 文件夹，允许通过 Git 进行上下文层的版本控制，同时保持密钥的本地性。