Show HN: Ktx – 面向数据智能体的开源可执行上下文层

背景

通用大语言模型（LLM）智能体在处理数据任务时往往表现不佳。它们每次回答问题时都会重新探索数据仓库，自行发明指标逻辑，并返回与官方批准定义不符的数字。这种“幻觉”和缺乏上下文的问题，导致智能体难以直接用于严肃的企业数据分析场景。

传统的语义层（Semantic Layer）虽然试图解决这一问题，但通常存在两个主要缺陷：一是需要持续的人工维护，二是无法吸收公司其他部分的非结构化知识（如文档、Wiki）。

在此背景下，Ktx 作为一个开源项目应运而生。它不仅仅是一个语义层，更是一个“自我改进的上下文层”。其核心目标是教会智能体如何基于已批准的指标定义、可连接的列以及业务知识库，准确地向数据仓库发起查询。

核心内容

Ktx 通过自动化方式解决了传统方案的痛点，主要包含以下四个核心功能模块：

1. 从公司知识库中学习

Ktx 能够摄取 Wiki 内容，对其进行整理、去重，并标记出矛盾之处供人类审核。这使得智能体不仅能访问数据，还能理解数据背后的业务逻辑和上下文。

2. 映射数据栈

Ktx 会对数据表进行采样，捕获元数据和 usage patterns（使用模式），检测可连接的列，并对数据源进行标注。这些操作旨在帮助智能体编写出更优质的 SQL 查询语句。

3. 构建语义层

Ktx 将原始表与高层级指标通过一个“连接图”（Join Graph）结合起来。该图能自动解决“漏斗陷阱”（Chasm Traps）和“扇出陷阱”（Fan Traps）。这意味着智能体可以声明式地获取指标，而不需要每次都在重写规范化的 SQL。

4. 在执行时为智能体提供服务

Ktx 提供了 CLI 和 MCP（Model Context Protocol）工具，支持在 Wiki 内容和语义层实体之间进行全文搜索和语义搜索的结合，从而为智能体提供统一的查询入口。

适用场景与兼容性

适合使用 Ktx 的情况：

• 希望智能体（如 Claude Code、Codex、Cursor 或 OpenCode）使用已批准的指标定义查询数据仓库。
• 业务知识分散在 dbt、Looker、Metabase、Notion 和团队 Wiki 中。
• 需要智能体重用规范化的 SQL，而不是每次提示都重新发明。

不适合使用 Ktx 的情况：

• 没有 SQL 数据仓库（Ktx 建立在数据仓库之上）。
• 只需要执行一次临时查询（此时 psql 或笔记本即可满足需求）。

技术兼容性：

• 数据仓库支持： PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite。
• 集成支持： dbt, MetricFlow, LookML, Looker, Metabase, Notion。

快速开始与配置

安装非常简单，通过 npm 全局安装即可：

npm install -g @kaelio/ktx

主要命令包括：

• ktx setup：创建或恢复本地 Ktx 项目，配置提供者和连接，构建上下文，并安装智能体集成。
• ktx status：检查项目状态，包括 LLM、嵌入模型、数据库配置、上下文源以及智能体集成的就绪情况。

项目结构示例：

my-project/
├── ktx.yaml          # 项目配置
├── semantic-layer/   # YAML 语义源
├── wiki/             # 共享业务上下文和用户笔记
├── raw-sources/      # 摄取工件和报告
└── .ktx/             # 本地状态和密钥（git 忽略）

智能体集成提示： 如果你已经在使用智能体，可以从项目目录中运行以下命令添加 Ktx 技能：

npx skills add Kaelio/ktx --skill ktx

注意：如果 ktx status 提示需要运行 ktx mcp start --project-dir ...，请在打开智能体客户端之前运行该命令。

隐私与安全

• 本地运行： Ktx 在本地运行，不会将模式或查询结果发送到托管服务。离开你机器的唯一数据是你发送到你配置的 LLM 提供商的数据。
• 只读连接： 连接是只读的，Ktx 永远不会写入你的数据库。
• 支持的 LLM 后端： Anthropic API, Google Vertex AI, AI Gateway, 以及通过 Claude Agent SDK 进行的本地 Claude Code 会话。

开发贡献

Ktx 是一个 pnpm + uv 工作区。克隆仓库后，可以通过以下命令进行本地开发：

git clone https://github.com/kaelio/ktx.git
cd ktx
pnpm install
uv sync --all-groups
pnpm run build
pnpm run check

遥测与许可

• 遥测： Ktx 从交互式 CLI 运行中收集匿名使用遥测数据，以改进设置、命令可靠性和数据智能体工作流。不记录文件路径、主机名、SQL、模式名称、错误消息或参数。
• 许可： Apache License, Version 2.0。

关键要点

• 解决智能体数据查询痛点： 传统智能体在数据任务中容易出错，Ktx 通过提供经过验证的指标和业务知识，显著提高了查询准确性。
• 超越传统语义层： 不仅管理数据元数据，还整合了非结构化的业务文档（如 Wiki），解决了传统语义层维护成本高且知识孤岛的问题。
• 自动化上下文构建： 自动处理表采样、元数据捕获、连接检测以及指标图的构建，减少了人工配置负担。
• 本地优先与隐私安全： 核心组件在本地运行，数据连接只读，不向第三方托管服务泄露敏感数据，仅与用户指定的 LLM 提供商通信。
• 广泛的生态集成： 兼容主流数据仓库（Snowflake, BigQuery 等）和 BI/建模工具（dbt, Looker, Metabase 等），并能与主流代码智能体（Cursor, Claude Code 等）无缝集成。
• MCP 协议支持： 通过 Model Context Protocol (MCP) 为智能体提供标准化的上下文访问接口，增强了互操作性。
• 开源且可定制： 基于 Apache 2.0 许可，允许开发者自行部署、修改和贡献代码。

意义与影响

Ktx 的出现标志着 AI 智能体从“通用对话”向“专业数据操作”迈出了关键一步。在企业环境中，数据准确性至关重要，而智能体之前的“幻觉”和“自创逻辑”一直是阻碍其落地生产环境的主要障碍。

1. 填补了“语义层”与“业务上下文”之间的空白： 现有的解决方案往往要么只关注技术元数据（如 dbt），要么只关注业务定义（如 Looker），Ktx 尝试将两者结合，并引入非结构化知识，为智能体提供了一个更完整的“世界观”。
2. 降低了智能体集成的门槛： 通过标准化的 MCP 接口和 CLI 工具，使得 Cursor、Claude Code 等开发工具能够轻松接入企业数据仓库，让开发者能够利用 AI 进行更复杂的数据分析和工程任务。
3. 强调了本地化和数据主权： 在数据隐私日益受到重视的今天，Ktx 坚持本地运行和只读连接的设计，消除了企业对将数据发送给云端 AI 服务的顾虑，符合企业级安全合规要求。
4. 推动了“自我改进”的智能体工作流： Ktx 不仅是一个静态的工具，它还能通过吸收新知识并标记矛盾来“自我改进”，这为构建更智能、更适应企业特定环境的 AI 助手提供了新的范式。

总的来说，Ktx 为希望将 AI 智能体引入数据分析流程的企业提供了一个务实、安全且高效的开源解决方案，有望加速 AI 在数据工程和商业智能领域的深度融合。