为数据代理构建可执行上下文层：ktx 的跨会话状态持久化与工具链编排

通用 AI 代理在对接企业数据仓库时面临一个结构性困境：每次提问都重新探索 schema，自行发明指标计算逻辑，最终返回的数字与业务认可的定义不符。传统语义层（如 dbt Semantic Layer、MetricFlow）虽然提供了治理机制，却需要持续的人工维护，且无法吸收散落在 wiki、Notion 和团队文档中的业务知识。

ktx 作为 Y Combinator P25 孵化的开源项目，提出了一种「可执行上下文层」（Executable Context Layer）的架构思路，通过自动化摄取、语义建模和 MCP 工具暴露三层机制，让数据代理能够基于经认可的指标定义和完整的业务上下文进行查询，而非在原始表上反复试错。

问题背景：代理在数据任务中的系统性失效

当 Claude Code、Codex 或 Cursor 直接对接数据仓库时，典型的失败模式包括：

• 重复探索：每次提问都重新扫描表结构，无法复用前序会话中对业务口径的理解
• 指标漂移：代理自行编写 SQL 计算「收入」「活跃用户」等核心指标，结果与财务或运营部门认可的定义产生偏差
• 上下文割裂：dbt 中的模型定义、Metabase 中的常用查询、Notion 中的业务规则分散在不同系统，代理无法建立统一的知识图谱

传统解决方案要么完全依赖人工维护语义层（成本高昂），要么让代理直接读取原始数据（风险不可控）。ktx 的切入点是将「上下文」本身视为可执行的基础设施，通过自动化手段持续构建、验证和暴露。

三层架构：从原始数据到可执行上下文

ktx 的核心架构可分为摄取层、语义层和执行层，每层都有明确的职责边界和自动化机制。

摄取层负责从多源异构系统中提取原始上下文。它支持 PostgreSQL、Snowflake、BigQuery、ClickHouse、MySQL、SQL Server 和 SQLite 等主流数据仓库，同时集成 dbt、MetricFlow、Looker、Metabase 和 Notion 等工具。摄取过程不仅拉取元数据，还会对表进行采样、捕获使用模式、检测可连接的列，并标注数据来源。对于 wiki 和文档类内容，ktx 会执行去重、聚类，并标记潜在的矛盾点供人工审核。

语义层是 ktx 的核心创新。它基于摄取的元数据自动构建 join graph，能够识别并解决 fan trap（多对多关系导致的重复计数）和 chasm trap（缺失匹配导致的空值遗漏）等经典数据建模问题。与手动维护的语义层不同，ktx 通过分析实际查询模式和表间关系，自动生成可复用的指标定义和连接路径。这意味着当代理请求「上季度各渠道收入」时，ktx 能够直接返回经过验证的语义实体，而非让代理自行拼接原始表。

执行层通过 CLI 和 MCP（Model Context Protocol）服务器将上下文暴露给代理。ktx mcp start 启动的本地守护进程将语义层和 wiki 内容通过标准化协议提供给 Claude Code、Codex、Cursor 或 OpenCode。代理可以通过统一的搜索接口同时查询语义实体（ktx sl "revenue"）和业务知识（ktx wiki "refund policy"），实现数据口径与业务规则的无缝对齐。

跨会话状态持久化与项目结构

ktx 将上下文视为可版本化的项目，而非临时的内存状态。这种设计确保了跨会话的持久化和团队协作能力。

典型项目结构如下：

my-project/
├── ktx.yaml                         # 项目配置
├── semantic-layer/<connection-id>/  # YAML 语义源
├── wiki/global/                     # 共享业务上下文
├── wiki/user/<user-id>/             # 用户级笔记
├── raw-sources/<connection-id>/     # 摄取产物和报告
└── .ktx/                            # 本地状态和 secrets，git-ignored

其中 ktx.yaml、语义层和 wiki 内容可提交到版本控制，而 .ktx/ 目录包含本地状态和敏感信息（如数据库连接凭证），默认被 git 忽略。这种分离设计既保证了配置的可复现性，又确保了凭证的安全隔离。

ktx setup 命令支持项目的创建、恢复和更新。当团队成员克隆仓库并运行 ktx setup 时，ktx 会基于 ktx.yaml 重建完整的上下文环境，包括重新验证数据库连接、重建语义层索引、恢复 wiki 内容。这种「配置即代码」的理念使得上下文层能够在不同开发者和代理会话之间保持一致。

MCP 工具链编排与代理集成

ktx 通过 MCP 协议实现了与主流 AI 代理的无缝集成。MCP 作为标准化的客户端 - 服务器协议，定义了工具发现、查询执行和 schema 获取的操作规范，将 AI 模型与数据源解耦。

集成流程简洁：开发者在项目目录运行 ktx mcp start，ktx 启动本地 MCP 服务器并暴露语义搜索、wiki 查询、指标解析等工具。代理客户端（如 Claude Code）通过 MCP 协议发现可用工具，随后可以在对话中直接调用 ktx_sl_search 或 ktx_wiki_query 等接口获取上下文。

这种架构的优势在于：

• 只读安全：ktx 明确设计为只读模式，所有数据库连接均通过只读权限执行，杜绝了代理意外修改生产数据的风险
• 本地优先：除调用 LLM API 进行语义理解外，所有数据（schema、查询结果、wiki 内容）均保留在本地，满足企业的数据驻留要求
• 动态发现：代理在运行时动态发现可用的语义实体和工具，无需硬编码表名或指标定义

对于已在使用 AI 代理的团队，ktx 提供了零配置的集成路径：直接在代理对话中请求运行 npx skills add Kaelio/ktx --skill ktx，代理会自动完成安装和项目配置。

适用场景与部署建议

ktx 特别适合以下场景：

• 团队使用 Claude Code、Codex、Cursor 或 OpenCode 进行数据分析，但受困于代理自行发明的 SQL 逻辑
• 业务知识分散在 dbt、Looker、Metabase、Notion 和团队 wiki 中，缺乏统一查询入口
• 需要代理复用经认可的指标定义，而非每次重新计算

暂不建议在以下场景使用：

• 无 SQL 数据仓库的环境（ktx 作为上层工具依赖底层仓库）
• 仅需执行单次即席查询（直接使用 psql 或 notebook 更简单）

部署时的关键参数包括：

• LLM 配置：支持 Anthropic API、Google Vertex AI、AI Gateway 和本地 Claude Code 会话。生产环境建议配置专用的 API key 并设置用量上限
• 连接池管理：针对 Snowflake、BigQuery 等云仓库，建议配置连接池大小和超时参数，避免采样阶段占用过多资源
• wiki 更新频率：根据业务知识变更速度设置 ktx ingest 的定时任务，建议每日或每周执行一次全量摄取
• 矛盾审核流程：ktx 会自动标记 wiki 和语义层之间的定义冲突，建议建立人工审核工作流，将审核结果反馈到 wiki/global/ 目录

资料来源

• ktx GitHub 仓库：https://github.com/kaelio/ktx
• ktx 官方文档：https://docs.kaelio.com/ktx/docs/

ai-systems