ktx 評測：把倉儲知識編譯成 agent 可查的語意層
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
秒懂
- 它是什麼？
- Kaelio 的 ktx 是一套安裝在本地專案目錄的 context layer，用 CLI 與 MCP 把資料庫結構、dbt／Looker／Notion 等來源整理成 wiki 與 semantic-layer YAML，讓 Claude Code、Codex 之類的 agent 用受核准的指標定義查詢倉儲。它的價值取決於你願不願意維護一份本地專案狀態，以及你的倉儲是否值得被反覆查詢。
- 適合誰用？
- ktx 適合已經有 SQL 倉儲、而且業務知識散落在 dbt、Looker、Metabase、Notion 與團隊 wiki 的團隊，尤其是已經在用 Claude Code 或 Codex 且不想另外付 LLM 費用的情況。只有一個 ad-hoc 查詢需求、或根本沒有倉儲的人不該引入它，README 自己就寫明這種情境用 psql 或 notebook 即可。
- 可以商用嗎？
- 可以。Apache-2.0 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 5 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
ktx 要解的是 agent 每次重猜指標口徑的問題
通用型 agent 在資料任務上的失敗模式很固定。README 的描述是：它們會「re-explore your warehouse on every question」，自己發明指標邏輯，最後吐出的數字跟公司核准的定義對不上。問題不在模型能力，而在 agent 每次拿到的是空白地圖。
傳統 semantic layer 有核准定義，但 README 直指它「demand constant manual upkeep」，而且不會吸收公司其他地方的知識。ktx 的定位就是把這兩件事接起來：一邊自動建立倉儲脈絡，一邊把 wiki、Notion、dbt、BI 工具裡的知識吃進來。
目標使用者寫得很明確：想讓 Claude Code、Codex、Cursor、OpenCode 用受核准定義查倉儲的人；知識散落在多個工具的人；需要 agent 重用既有 SQL 而不是每次重寫的人。反過來，沒有 SQL 倉儲的人不適用，只需要一次 ad-hoc 查詢的人也不適用。這個自我設限比多數專案誠實。
兩段式架構：ingestion 產出檔案，serving 只讀查詢
從 README 的兩張流程圖可以看出 ktx 分成兩個階段。Ingestion 階段由 source connectors、context builder、reconciliation、validation 四個環節組成，把資料庫、BI 工具、modeling code 與文件收進來，輸出兩種東西：wiki Markdown 與 semantic-layer YAML。這個階段的產物是檔案，落在本地專案目錄裡。
Serving 階段走 MCP。agent 發出查詢，ktx 同時搜尋 wiki 與語意層實體，回傳受核准的指標，再把它編譯成 read-only SQL 送到倉儲執行。搜尋是 full-text 與 semantic 混合，不是單純關鍵字比對。
值得注意的是語意層的 join graph 設計。README 說它「automatically resolves chasm and fan traps」，也就是 agent 用宣告式方式取指標，不必自己重寫 canonical SQL。fan trap 與 chasm trap 是維度建模裡典型的聚合錯誤來源，把它放在 join graph 層處理，等於把最容易出錯的部分從 agent 手上拿走。這是 ktx 相對通用 agent 最實質的差異，也是它相對傳統 semantic layer 唯一沒有靠人工的地方。
reconciliation 環節負責去重與標記矛盾，README 的說法是「flags contradictions for human review」。注意這裡的動詞是 flag，不是 resolve。矛盾不會被自動解決，只會被挑出來等人決定。
安裝與第一次啟動的實際指令
安裝是全域 npm 套件，README 給的是：
npm install -g @kaelio/ktx ktx setup ktx status
ktx setup 會建立或接續一個本地 ktx 專案，設定 provider 與連線，建構脈絡，並安裝 agent 整合。它同時具備 create、resume、update 三種行為，所以中斷後重跑是安全的。
ktx status 是驗收點。README 給的範例輸出包含這幾行：Project ready、LLM ready（範例顯示 claude-sonnet-4-6）、Embeddings ready（範例顯示 text-embedding-3-small）、Databases configured、Context sources configured、ktx context built、Agent integration ready（範例顯示 codex:project）。這七項要全過，agent 才拿得到完整脈絡。
README 有一則重要提醒：如果 ktx status 印出 ktx mcp start --project-dir ...，必須先跑它再開 agent client。這表示 MCP server 不會自動常駐，是手動啟動的。
日常查詢用 ktx sl "revenue" 搜語意來源、ktx wiki "refund policy" 搜本地 wiki 頁、ktx ingest 重建所有已設定連線的脈絡。升級則是 npm install -g @kaelio/ktx@latest。
LLM 金鑰方面，README 說明可以用自己的 API key，或走 Claude Pro/Max 訂閱的 Claude Code 登入、或本地 Codex 認證，並強調 ktx 不另外計費。這對已經訂閱的人是好消息，但也意味著你的 agent 額度與 ktx 的 ingestion 共用。
read-only 是設計約束，不是功能列表上的一項
README 的比較表把 read-only 列為 ktx 的屬性，並在 serving 流程圖裡寫明編譯出的 SQL 是 read-only 執行。這個約束的意義比表面大。
Agent 直接連倉儲時，你能給的權限只有兩種：要嘛給唯讀帳號，要嘛祈禱它不寫。ktx 選擇在中間插一層編譯，讓 agent 送出的是指標請求而非任意 SQL，由 ktx 產生查詢語句。這同時解掉兩個問題：一是寫入風險，二是 agent 繞過語意層自己拼 SQL 導致口徑不一致。
代價是表達能力受限。如果你的問題需要 agent 自由探索 schema、寫複雜的 window function、或做語意層沒定義的臨時聚合，這層編譯就是障礙。ktx 的適用範圍是「已定義指標的取用」，不是「探索式分析」。README 在 Skip ktx if 段落把它講成「只需要一次 ad-hoc 查詢」的情況，但實際上受限的範圍更廣：任何語意層沒覆蓋到的分析角度，都得先回到 ingestion 補定義。
矛盾要靠人裁決，這是維護成本的主要來源
README 說 ktx 會 ingest wiki 內容、整理、去重、並把矛盾標出來給人審查。這裡沒有任何自動解決的承諾，而這正是長期成本所在。
一個已經運作幾年的資料團隊，指標定義幾乎不可能只有一份。dbt 裡有一版 revenue，Looker 裡有一版，某份 Notion 文件裡還有一版寫著「暫定」。ktx 會把這些全部收進來，然後把衝突列出來。裁決這些衝突需要的是懂業務的人，不是工程時間。專案裝好那天很順，三個月後倉儲改了 schema、BI 換了欄位名、wiki 又被改寫，ktx context built 這一項就會開始需要重新處理。
ktx ingest 可以重跑，但重跑不會幫你決定哪個定義才對。README 沒有描述任何自動衝突解決機制，也沒有描述語意層的版本控制或審核流程，只有 Project Layout 顯示產出落在專案目錄。這意味著語意層檔案可以進 git，但怎麼 review、誰有權核准，得由團隊自己定。這是 ktx 留給使用者的空白，也是它與成熟商業 semantic layer 最大的落差。
與傳統 semantic layer 的差異在誰寫定義
把 ktx 跟 dbt 加 MetricFlow 這條路線放在一起看最清楚。MetricFlow 的模型寫在 dbt 專案裡，指標定義是手寫的 YAML，join 關係由 semantic model 明示，版本控制與 CI 都沿用 dbt 既有流程。優點是定義精確、可審核、與轉換層同源；缺點是每一條指標、每一個 join 都要人寫，而且它不會吸收 dbt 以外的知識。
ktx 走反方向：定義由 ingestion 從多個來源推導出來，人只負責裁決矛盾。這換來覆蓋速度，代價是定義的來源變得分散，而且正確性依賴 reconciliation 的品質。README 沒有說明推導出的語意層精確度如何驗證，只有 validation 這個環節名稱。
如果你的團隊已經把 dbt 的 semantic layer 維護得很好，ktx 的推導反而可能產生一份與既有定義競爭的第二來源。反過來，如果 dbt 裡只有轉換沒有指標定義，而真正的口徑散在 Looker 與 Notion 裡，ktx 的 ingestion 就是在補一塊本來沒人管的空缺。選擇的關鍵不是哪個工具強，而是你的定義現在寫在哪裡。
採用前該確認的三個具體事實
第一，跑完 ktx setup 後執行 ktx status，逐項確認七個 ready 狀態。範例輸出裡 LLM 與 Embeddings 是分開的兩項，代表你需要兩種能力：一個對話模型與一個 embedding 模型。若 Embeddings ready 是 no，混合搜尋會退化成什麼行為，README 沒有說明。
第二，確認 ktx status 有沒有印出 ktx mcp start --project-dir ...。這行代表 MCP server 需要手動啟動，agent client 才連得上。把它寫進你的啟動流程，否則 agent 會找不到工具。
第三，盤點要餵進去的來源。README 列出的整合有 dbt、MetricFlow、LookML、Looker、Metabase、Sigma、Notion、Google Drive，倉儲支援 PostgreSQL、Snowflake、BigQuery、ClickHouse、MySQL、SQL Server、SQLite、DuckDB、Amazon Athena、MongoDB。清單很長，但每一項都是 ingestion 的輸入，也就都是潛在的矛盾來源。先從一個倉儲加一個 BI 工具開始，比一次接八個來源容易收拾。
授權是 Apache-2.0，README 連到 LICENSE 檔。這對商業使用與修改都寬鬆，但授權不涵蓋你餵進去的公司資料，也不涵蓋你使用的 LLM provider 條款。Ingestion 會把 wiki 內容與 schema metadata 送進模型，這部分的資料治理要由你自己判斷，本文不提供法律意見。
維護節奏上，README 的升級方式只有重跑 npm install -g @kaelio/ktx@latest 一行。最近的版本是 v0.16.0，前一版 v0.15.0 與 v0.14.0 都落在 2026 年 6 月底到 7 月初，發佈間隔短，代表介面仍在變動。0.x 版號搭配這種頻率，意味著 CLI 參數與專案檔格式有調整的可能，升級前值得先看 release notes。
編輯結論
ktx 適合已經有 SQL 倉儲、而且業務知識散落在 dbt、Looker、Metabase、Notion 與團隊 wiki 的團隊，尤其是已經在用 Claude Code 或 Codex 且不想另外付 LLM 費用的情況。只有一個 ad-hoc 查詢需求、或根本沒有倉儲的人不該引入它，README 自己就寫明這種情境用 psql 或 notebook 即可。採用前先確認三件事：ktx status 是否全部顯示 ready（特別是 mcp start 那一行）、你打算餵進去的來源裡有多少互相矛盾的定義需要人工裁決、以及團隊是否接受語意層檔案進版控後要隨 schema 變更同步更新。這三項沒過，context layer 只會把錯誤的定義傳得更快。
社群筆記