ktx 评测：给数据智能体补上仓库上下文的一层
ktx is an executable context layer for data and analytics agents 🐙 Allow Claude Code, Codex, or other AI agents to query analytical databases accurately and with full context of your company
秒懂
- 它是什么？
- ktx 把 wiki、dbt 模型、BI 指标和数仓元数据汇总成 wiki Markdown 与语义层 YAML，再通过 CLI 和 MCP 把经过批准的指标喂给 Claude Code、Codex 这类智能体。它解决的是智能体每次重新探索数仓、自造指标口径的问题，代价是你要先有一个数仓，并接受它自建的上下文需要人工复核。
- 适合谁用？
- ktx 适合已经有 SQL 数仓、并且业务口径散落在 dbt、Looker、Metabase、Notion 与团队 wiki 里的团队，尤其是希望 Claude Code 或 Codex 直接查数而不是每次重新摸索的场景。只有单个临时查询需求的人不该引入它，README 也明确建议这类情况用 psql 或 notebook 就够了；没有 SQL 数仓的团队更不适用，ktx 是架在数仓之上的一层。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 5 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
ktx 想修的是智能体查数时的失忆与自造口径
通用智能体做数据任务时有两个反复出现的毛病。一是每次都重新探索数仓，表结构、可连接的列、字段含义都要重新猜一遍。二是自己发明指标逻辑，同一个营收数字和公司批准的口径对不上。README 把这两点写得很直白：智能体「re-explore your warehouse on every question, invent their own metric logic」。
传统语义层解决第二个问题，但代价是持续的人工维护，而且吸收不了公司里其他形态的知识。ktx 的定位是同时做这两件事，并且尽量自动。目标用户写得很清楚：手上有 SQL 数仓，业务知识散在 dbt、Looker、Metabase、Notion 和团队 wiki 里，希望 Claude Code、Codex、Cursor、OpenCode 这类客户端直接查数。README 同样列出了不该用的场景：没有 SQL 数仓，或者只需要一次临时查询，后者用 psql 或 notebook 就行。
摄取管线：从源连接器到 wiki Markdown 与语义层 YAML
从 README 给出的两张流程图看，ktx 分成摄取与服务两个阶段。摄取阶段由 source connectors、context builder、reconciliation、validation 四个环节组成，输入是数据库、BI 工具、建模代码和文档，输出是两类产物：wiki Markdown 和语义层 YAML。
具体动作包括：对表做采样，抓取元数据和使用模式，检测可连接的列，给数据源加注释；把 wiki 内容整理、去重，并把互相矛盾的地方标出来交人工复核；在原始表和高层指标之间建一张 join graph，README 称它自动处理 chasm trap 和 fan trap。这一点是语义层里最容易出错的地方，两个事实表通过一张维度表连接会让聚合翻倍，ktx 把这个解析放在图里做，而不是让智能体每次自己写 JOIN。
服务阶段走 MCP：智能体发问，ktx 在 wiki 和语义层实体上做全文加语义的混合检索，返回经过批准的指标，再编译成只读 SQL 打到数仓上。只读这一点在对比表里被单独列为一栏，意味着它不会让智能体改数据。
安装与首次运行：三条命令和一个必须先跑的 MCP 进程
README 给的快速开始只有三步：
npm install -g @kaelio/ktx ktx setup ktx status
ktx setup 会创建或恢复一个本地 ktx 项目，配置 provider 和连接，构建上下文，并安装智能体集成。ktx status 用来检查就绪状态，README 展示的输出里包含几项关键信息：LLM ready 与 Embeddings ready 是分开的两行，说明模型和向量化需要各自配好；Databases configured、Context sources configured、ktx context built 分别对应连接、来源和上下文构建；最后一行 Agent integration ready 会带上形如 codex:project 的标记。
README 里有一条重要提示：如果 ktx status 打印出 ktx mcp start --project-dir ...，需要在打开智能体客户端之前先运行它。也就是说 MCP 服务不会自己常驻，得手动起。常用命令还有 ktx ingest 为每个配置好的连接构建上下文，ktx sl "revenue" 检索语义来源，ktx wiki "refund policy" 检索本地 wiki 页面。升级方式是重跑全局安装并加 @latest 标签。
另一条路径是让智能体自己装：在项目目录里对 Claude Code、Codex、Cursor 或 OpenCode 说，运行 npx skills add Kaelio/ktx --skill ktx 并用 ktx skill 完成安装配置。README 把这条放在 TIP 里，说明它被当作推荐做法而非替代方案。
模型账单不进 ktx：自带密钥或复用本地登录
README 的 NOTE 里有一句容易被忽略但影响采购判断的话：ktx 用自己的 LLM API key 运行，或者复用本地智能体的登录态，比如通过 Claude Code 使用 Claude Pro/Max 订阅，或者使用本地 Codex 的认证，ktx 本身不产生额外计费。
这意味着成本结构取决于你已经在付什么。已经在付 Claude Pro/Max 的团队，摄取和检索的模型调用可以走订阅额度；没有订阅的团队则要准备 API key。这个设计把 ktx 和那些自带模型额度、按 token 转售的产品区分开了，但也意味着模型可用性、限流和费用完全由你自己的账号决定，ktx 不承担这部分。
支持的连接面很宽，但宽不等于深
README 列出的数仓覆盖 PostgreSQL、Snowflake、BigQuery、ClickHouse、MySQL、SQL Server、SQLite、DuckDB、Amazon Athena 和 MongoDB；集成侧覆盖 dbt、MetricFlow、LookML、Looker、Metabase、Sigma、Notion 和 Google Drive。
这个清单值得注意的地方在于它把两类东西放在一起：一类是查询引擎，一类是知识来源。MongoDB 出现在数仓列表里，而 ktx 的服务阶段是编译只读 SQL，文档没有说明非关系型来源在这一步怎么处理，这是材料里没有交代清楚的一处。同样，Notion 和 Google Drive 作为上下文来源进入摄取管线，但它们的内容如何与语义层实体对齐，README 只给了「整理、去重、标记矛盾」这一层描述，没有更细的规则。
宽覆盖对选型是好事，但接入一个来源和把这个来源的知识质量做到可用是两件事。README 没有给出各连接器的成熟度差异，实际用哪个来源，需要自己跑一遍 ktx ingest 看产物。
自建上下文的代价：矛盾要人来收尾
ktx 最核心的卖点是自动构建上下文，但 README 自己的措辞留了余地：摄取时会「flags contradictions for human review」。也就是说，当 wiki、dbt 模型和 BI 工具里的口径互相打架时，ktx 负责发现并标出来，不负责裁决。
这个边界很重要。语义层一旦被智能体当成权威来查，错误的合并比没有语义层更危险，因为智能体会带着信心输出一个错的数字。所以 ktx 的自动化程度越高，人工复核这一环的负载反而越需要提前安排。README 没有描述复核界面、复核队列或者冲突的严重性分级，只说会标记。
另一个限制在对比表里以留白的形式出现：传统语义层那一列在「Builds warehouse context automatically」和「Absorbs wiki / Notion / team knowledge」上都是空的，ktx 都是勾。但表格没有反过来列 ktx 相对传统语义层缺什么，比如手工精调指标的粒度控制、指标变更的审批流程。如果你的团队已经在 Looker 或 MetricFlow 里维护了一套严格治理的指标，ktx 是叠加在上面还是与之并行，README 没有给出答案。
和纯 MCP 数据库工具的区别在哪
一个常见的替代方案是直接用 MCP 连数据库的工具，让智能体自己看 schema、自己写 SQL。两者的差别不在连接能力，而在是否有一层经过批准的定义。
纯 MCP 工具把 schema 交给模型，模型每次都要重新推断哪些列可以连、哪个字段才是营收。ktx 把这一步前置到摄取阶段，产出 wiki 和语义层 YAML，运行时智能体拿到的不是原始 schema 而是已批准的指标，SQL 由 ktx 编译。代价是前置成本：你要先跑 ktx setup 和 ktx ingest，还要处理摄取出来的矛盾。
如果你的数仓只有几十张表、口径由一个人掌握，纯 MCP 工具更省事。当表数量和知识来源多到模型无法在单次上下文里稳定推断时，ktx 这种预构建的做法才开始划算。这个临界点取决于你的仓库规模，README 没有给建议，需要自己判断。
维护成本与许可
升级路径在 README 里只有一条：npm install -g @kaelio/ktx@latest。项目在 2026 年 6 月底到 7 月初连续发布了 v0.14.0、v0.15.0、v0.16.0 三个版本，主版本号仍是 0，说明 API 和命令行为还在快速变化，升级前值得先看 release notes。
真正的维护成本不在 npm 包，而在上下文本身。数仓加表、dbt 模型改名、指标口径调整之后，wiki 和语义层 YAML 需要重新摄取，否则智能体拿到的是过期定义。README 没有说明增量摄取的粒度，只说 ktx ingest 会为每个配置好的连接构建上下文。
许可证是 Apache-2.0，允许商用和修改，附带专利授权条款，通常要求保留版权与许可声明、标注修改。这是常见的企业友好型许可，但具体合规判断请以 LICENSE 原文和你的法务意见为准，本文不构成法律意见。
编辑结论
ktx 适合已经有 SQL 数仓、并且业务口径散落在 dbt、Looker、Metabase、Notion 与团队 wiki 里的团队，尤其是希望 Claude Code 或 Codex 直接查数而不是每次重新摸索的场景。只有单个临时查询需求的人不该引入它，README 也明确建议这类情况用 psql 或 notebook 就够了；没有 SQL 数仓的团队更不适用，ktx 是架在数仓之上的一层。上手前先确认三件事：ktx status 是否同时打印出 LLM ready 与 Embeddings ready，因为两者需要分别配置；README 提示如果 status 输出 ktx mcp start --project-dir ...，必须在打开智能体客户端之前先运行它，否则 MCP 通道不通；以及 ktx ingest 产出的 wiki 与语义层 YAML 是否与你现有的指标定义一致，README 只说明它会把矛盾标出来交人复核，并没有承诺自动消解。
社区笔记