ktx-context-layer-data-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ktx Context Layer for Data Agents

面向数据Agent的ktx上下文层

Skill by ara.so — AI Agent Skills collection.
ktx is an executable context layer that teaches AI agents how to query data warehouses accurately. It automatically builds a semantic layer from your database, ingests business knowledge from wikis and tools like dbt/Looker, detects joinable columns, resolves fan/chasm traps, and exposes everything through CLI and MCP tools for agent execution.
ara.so提供的Skill——AI Agent技能集合。
ktx是一个可执行上下文层,能够教AI Agent如何精准查询数据仓库。它会自动从你的数据库构建语义层,从维基百科以及dbt/Looker等工具中提取业务知识,检测可关联列,解决扇出/裂隙陷阱,并通过CLI和MCP工具将所有内容开放给Agent执行。

Installation

安装

Install ktx globally via npm:
bash
npm install -g @kaelio/ktx
Or add to a project:
bash
npm install --save-dev @kaelio/ktx
通过npm全局安装ktx:
bash
npm install -g @kaelio/ktx
或者添加到项目中:
bash
npm install --save-dev @kaelio/ktx

Quick Setup

快速设置

Run the interactive setup wizard:
bash
ktx setup
This will:
  • Create or resume a ktx project in the current directory
  • Configure LLM provider (Anthropic API, Google Vertex AI, or Claude Agent SDK)
  • Configure embedding provider (OpenAI, Anthropic, Vertex AI)
  • Set up database connections (PostgreSQL, Snowflake, BigQuery, etc.)
  • Configure context sources (dbt, LookML, Looker, Metabase, Notion)
  • Build initial context
  • Install agent integration (Codex, Claude Code, etc.)
Check project status:
bash
ktx status
Expected output after successful setup:
text
ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (warehouse)
Context sources configured: yes (dbt_main)
ktx context built: yes
Agent integration ready: yes (codex:project)
运行交互式设置向导:
bash
ktx setup
这将:
  • 在当前目录创建或恢复ktx项目
  • 配置LLM提供商(Anthropic API、Google Vertex AI或Claude Agent SDK)
  • 配置嵌入提供商(OpenAI、Anthropic、Vertex AI)
  • 设置数据库连接(PostgreSQL、Snowflake、BigQuery等)
  • 配置上下文源(dbt、LookML、Looker、Metabase、Notion)
  • 构建初始上下文
  • 安装Agent集成(Codex、Claude Code等)
检查项目状态:
bash
ktx status
设置成功后的预期输出:
text
ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (warehouse)
Context sources configured: yes (dbt_main)
ktx context built: yes
Agent integration ready: yes (codex:project)

Project Structure

项目结构

ktx creates this structure:
text
my-project/
├── ktx.yaml                         # Project configuration
├── semantic-layer/<connection-id>/  # YAML semantic sources
├── wiki/global/                     # Shared business context
├── wiki/user/<user-id>/             # User-scoped notes
├── raw-sources/<connection-id>/     # Ingest artifacts and reports
└── .ktx/                            # Local state and secrets (git-ignored)
Commit
ktx.yaml
,
semantic-layer/
, and
wiki/
. Keep
.ktx/
local.
ktx会创建以下结构:
text
my-project/
├── ktx.yaml                         # 项目配置文件
├── semantic-layer/<connection-id>/  # YAML语义源
├── wiki/global/                     # 共享业务上下文
├── wiki/user/<user-id>/             # 用户范围的笔记
├── raw-sources/<connection-id>/     # 提取的工件和报告
└── .ktx/                            # 本地状态和密钥(Git忽略)
提交
ktx.yaml
semantic-layer/
wiki/
。将
.ktx/
保留在本地。

Configuration

配置

ktx.yaml

ktx.yaml

Example project configuration:
yaml
version: 1
project_id: analytics_project
llm_provider: anthropic
embedding_provider: openai

connections:
  - id: warehouse
    type: postgres
    config:
      host: localhost
      port: 5432
      database: analytics
      user: readonly_user
      password_env: POSTGRES_PASSWORD
      ssl: false

context_sources:
  - id: dbt_main
    type: dbt
    config:
      manifest_path: ./dbt/target/manifest.json
      catalog_path: ./dbt/target/catalog.json
  
  - id: looker_metrics
    type: looker
    config:
      base_url_env: LOOKER_BASE_URL
      client_id_env: LOOKER_CLIENT_ID
      client_secret_env: LOOKER_CLIENT_SECRET

agent_integrations:
  - type: codex
    scope: project
示例项目配置:
yaml
version: 1
project_id: analytics_project
llm_provider: anthropic
embedding_provider: openai

connections:
  - id: warehouse
    type: postgres
    config:
      host: localhost
      port: 5432
      database: analytics
      user: readonly_user
      password_env: POSTGRES_PASSWORD
      ssl: false

context_sources:
  - id: dbt_main
    type: dbt
    config:
      manifest_path: ./dbt/target/manifest.json
      catalog_path: ./dbt/target/catalog.json
  
  - id: looker_metrics
    type: looker
    config:
      base_url_env: LOOKER_BASE_URL
      client_id_env: LOOKER_CLIENT_ID
      client_secret_env: LOOKER_CLIENT_SECRET

agent_integrations:
  - type: codex
    scope: project

Environment Variables

环境变量

Store secrets in environment variables:
bash
undefined
将密钥存储在环境变量中:
bash
undefined

LLM Provider

LLM提供商

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_API_KEY=sk-ant-...

or for Vertex AI

或针对Vertex AI

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

Embedding Provider

嵌入提供商

export OPENAI_API_KEY=sk-...
export OPENAI_API_KEY=sk-...

Database Credentials

数据库凭证

export POSTGRES_PASSWORD=yourpassword export SNOWFLAKE_PASSWORD=yourpassword
export POSTGRES_PASSWORD=yourpassword export SNOWFLAKE_PASSWORD=yourpassword

Tool Integrations

工具集成

export LOOKER_BASE_URL=https://company.looker.com export LOOKER_CLIENT_ID=your_client_id export LOOKER_CLIENT_SECRET=your_secret export NOTION_TOKEN=secret_...
undefined
export LOOKER_BASE_URL=https://company.looker.com export LOOKER_CLIENT_ID=your_client_id export LOOKER_CLIENT_SECRET=your_secret export NOTION_TOKEN=secret_...
undefined

Core Commands

核心命令

Build Context

构建上下文

Ingest from all configured connections and sources:
bash
ktx ingest
Ingest from specific connection:
bash
ktx ingest --connection warehouse
Ingest from specific context source:
bash
ktx ingest --context-source dbt_main
从所有已配置的连接和源中提取数据:
bash
ktx ingest
从特定连接提取数据:
bash
ktx ingest --connection warehouse
从特定上下文源提取数据:
bash
ktx ingest --context-source dbt_main

Search Semantic Layer

搜索语义层

Search for metrics, dimensions, and entities:
bash
ktx sl "revenue"
ktx sl "customer lifetime value"
ktx sl "monthly active users"
Example output:
text
Found 3 semantic sources matching "revenue":

1. metric.monthly_recurring_revenue
   Type: metric
   Connection: warehouse
   Description: Sum of all active subscription values in a given month
   SQL: SUM(subscriptions.monthly_value)
   
2. dimension.revenue_tier
   Type: dimension
   Entity: customer
   Description: Customer revenue bracket (low/medium/high)
   
3. entity.revenue_events
   Type: entity
   Table: prod.revenue_events
   Primary key: event_id
搜索指标、维度和实体:
bash
ktx sl "revenue"
ktx sl "customer lifetime value"
ktx sl "monthly active users"
示例输出:
text
Found 3 semantic sources matching "revenue":

1. metric.monthly_recurring_revenue
   Type: metric
   Connection: warehouse
   Description: Sum of all active subscription values in a given month
   SQL: SUM(subscriptions.monthly_value)
   
2. dimension.revenue_tier
   Type: dimension
   Entity: customer
   Description: Customer revenue bracket (low/medium/high)
   
3. entity.revenue_events
   Type: entity
   Table: prod.revenue_events
   Primary key: event_id

Search Wiki

搜索维基知识库

Search business knowledge and documentation:
bash
ktx wiki "refund policy"
ktx wiki "customer segmentation"
搜索业务知识和文档:
bash
ktx wiki "refund policy"
ktx wiki "customer segmentation"

Query Warehouse

查询数据仓库

Execute SQL queries through ktx:
bash
ktx query "SELECT customer_tier, COUNT(*) FROM customers GROUP BY customer_tier"
Query with metric resolution:
bash
ktx query --use-metrics "SELECT monthly_recurring_revenue FROM time WHERE month = '2024-01'"
通过ktx执行SQL查询:
bash
ktx query "SELECT customer_tier, COUNT(*) FROM customers GROUP BY customer_tier"
带指标解析的查询:
bash
ktx query --use-metrics "SELECT monthly_recurring_revenue FROM time WHERE month = '2024-01'"

MCP Server

MCP服务器

Start the Model Context Protocol server for agent integration:
bash
ktx mcp start
Specify project directory:
bash
ktx mcp start --project-dir /path/to/project
The MCP server exposes these tools to agents:
  • ktx_search_semantic_layer
    - Search metrics and dimensions
  • ktx_search_wiki
    - Search business knowledge
  • ktx_query
    - Execute SQL queries
  • ktx_get_schema
    - Retrieve table schemas
  • ktx_get_metric_definition
    - Get canonical metric SQL
启动Model Context Protocol服务器以实现Agent集成:
bash
ktx mcp start
指定项目目录:
bash
ktx mcp start --project-dir /path/to/project
MCP服务器向Agent开放以下工具:
  • ktx_search_semantic_layer
    - 搜索指标和维度
  • ktx_search_wiki
    - 搜索业务知识
  • ktx_query
    - 执行SQL查询
  • ktx_get_schema
    - 获取表结构
  • ktx_get_metric_definition
    - 获取标准指标SQL

Working with Semantic Sources

语义源使用

ktx automatically generates semantic sources during ingestion. You can also define them manually.
ktx会在提取过程中自动生成语义源,你也可以手动定义它们。

Metric Definition

指标定义

yaml
undefined
yaml
undefined

semantic-layer/warehouse/metrics/mrr.yaml

semantic-layer/warehouse/metrics/mrr.yaml

name: monthly_recurring_revenue type: metric description: Sum of all active subscription values in a given month entity: subscription sql: SUM(subscriptions.monthly_value) filters:
  • sql: subscriptions.status = 'active' dimensions:
  • customer_tier
  • plan_type time_dimension: subscription_start_date
undefined
name: monthly_recurring_revenue type: metric description: Sum of all active subscription values in a given month entity: subscription sql: SUM(subscriptions.monthly_value) filters:
  • sql: subscriptions.status = 'active' dimensions:
  • customer_tier
  • plan_type time_dimension: subscription_start_date
undefined

Entity Definition

实体定义

yaml
undefined
yaml
undefined

semantic-layer/warehouse/entities/customer.yaml

semantic-layer/warehouse/entities/customer.yaml

name: customer type: entity table: prod.customers primary_key: customer_id description: Customer master table dimensions:
  • name: customer_tier type: categorical sql: tier
  • name: signup_date type: time sql: created_at
undefined
name: customer type: entity table: prod.customers primary_key: customer_id description: Customer master table dimensions:
  • name: customer_tier type: categorical sql: tier
  • name: signup_date type: time sql: created_at
undefined

Join Configuration

关联配置

ktx auto-detects joins, but you can override:
yaml
undefined
ktx会自动检测关联,但你可以手动覆盖:
yaml
undefined

semantic-layer/warehouse/joins/customer_subscription.yaml

semantic-layer/warehouse/joins/customer_subscription.yaml

from_entity: customer to_entity: subscription type: one_to_many join_sql: customers.customer_id = subscriptions.customer_id
undefined
from_entity: customer to_entity: subscription type: one_to_many join_sql: customers.customer_id = subscriptions.customer_id
undefined

Common Patterns

常见模式

Pattern 1: Setup New Project

模式1:新建项目设置

bash
undefined
bash
undefined

Navigate to analytics directory

导航到分析目录

cd ~/analytics
cd ~/analytics

Initialize ktx

初始化ktx

ktx setup
ktx setup

Follow prompts to configure:

按照提示配置:

- LLM provider (Anthropic API recommended)

- LLM提供商(推荐Anthropic API)

- Embedding provider (OpenAI recommended)

- 嵌入提供商(推荐OpenAI)

- Database connection (read-only credentials)

- 数据库连接(只读凭证)

- dbt integration (point to manifest.json)

- dbt集成(指向manifest.json)

Verify setup

验证设置

ktx status
ktx status

Build initial context

构建初始上下文

ktx ingest
undefined
ktx ingest
undefined

Pattern 2: Query with Agent Context

模式2:借助Agent上下文查询

From Claude Code, Cursor, Codex, or OpenCode:
text
User: What was our MRR in January 2024?

Agent uses ktx:
1. ktx sl "monthly recurring revenue" → finds metric definition
2. ktx query --use-metrics "SELECT monthly_recurring_revenue FROM time WHERE month = '2024-01'"
3. Returns accurate result using canonical metric logic
在Claude Code、Cursor、Codex或OpenCode中:
text
用户:我们2024年1月的MRR是多少?

Agent使用ktx:
1. ktx sl "monthly recurring revenue" → 找到指标定义
2. ktx query --use-metrics "SELECT monthly_recurring_revenue FROM time WHERE month = '2024-01'"
3. 使用标准指标逻辑返回准确结果

Pattern 3: Add Business Context

模式3:添加业务上下文

Create wiki pages for business knowledge:
bash
undefined
创建维基页面存储业务知识:
bash
undefined

Create global wiki page

创建全局维基页面

mkdir -p wiki/global cat > wiki/global/refund-policy.md << 'EOF'
mkdir -p wiki/global cat > wiki/global/refund-policy.md << 'EOF'

Refund Policy

退款政策

Customers can request refunds within 30 days of purchase.
客户可在购买后30天内申请退款。

Refund Eligibility

退款资格

  • Full refund if < 7 days
  • Prorated refund if 7-30 days
  • No refund if > 30 days
  • 购买7天内可全额退款
  • 7-30天内可按比例退款
  • 超过30天不予退款

Accounting Treatment

会计处理

Refunds are recorded as negative revenue in the month issued, not the original purchase month. EOF
退款记录为退款当月的负收入,而非原始购买月份。 EOF

Ingest wiki content

提取维基内容

ktx ingest
undefined
ktx ingest
undefined

Pattern 4: Integrate dbt Metrics

模式4:集成dbt指标

bash
undefined
bash
undefined

Ensure dbt artifacts exist

确保dbt工件存在

cd dbt-project dbt compile dbt docs generate
cd dbt-project dbt compile dbt docs generate

Configure in ktx.yaml

在ktx.yaml中配置

cat >> ktx.yaml << 'EOF' context_sources:
  • id: dbt_main type: dbt config: manifest_path: ./dbt-project/target/manifest.json catalog_path: ./dbt-project/target/catalog.json EOF
cat >> ktx.yaml << 'EOF' context_sources:
  • id: dbt_main type: dbt config: manifest_path: ./dbt-project/target/manifest.json catalog_path: ./dbt-project/target/catalog.json EOF

Ingest dbt metrics

提取dbt指标

ktx ingest --context-source dbt_main
ktx ingest --context-source dbt_main

Search for dbt metrics

搜索dbt指标

ktx sl "customers"
undefined
ktx sl "customers"
undefined

Pattern 5: Agent Integration

模式5:Agent集成

For Codex:
bash
undefined
针对Codex:
bash
undefined

Install during setup or manually

在设置过程中安装,或手动安装

ktx setup
ktx setup

Select "codex" when prompted for agent integration

当提示选择Agent集成时选择“codex”

Or install explicitly

或显式安装

npx skills add Kaelio/ktx --skill ktx

For Claude Code:

```bash
npx skills add Kaelio/ktx --skill ktx

针对Claude Code:

```bash

ktx setup handles this automatically

ktx setup会自动处理

Adds MCP server config to Claude Code settings

将MCP服务器配置添加到Claude Code设置中


Manual MCP configuration for Claude Desktop:

```json
{
  "mcpServers": {
    "ktx": {
      "command": "ktx",
      "args": ["mcp", "start", "--project-dir", "/path/to/project"]
    }
  }
}

Claude Desktop的手动MCP配置:

```json
{
  "mcpServers": {
    "ktx": {
      "command": "ktx",
      "args": ["mcp", "start", "--project-dir", "/path/to/project"]
    }
  }
}

TypeScript API (Programmatic Usage)

TypeScript API(程序化使用)

While ktx is primarily a CLI tool, you can use it programmatically:
typescript
import { KtxProject } from '@kaelio/ktx';

// Load existing project
const project = await KtxProject.load('/path/to/project');

// Search semantic layer
const results = await project.searchSemanticLayer('revenue');
console.log(results);

// Search wiki
const wikiResults = await project.searchWiki('refund policy');
console.log(wikiResults);

// Execute query
const queryResult = await project.query(
  'warehouse',
  'SELECT * FROM customers LIMIT 10'
);
console.log(queryResult.rows);

// Get metric definition
const metric = await project.getMetric('monthly_recurring_revenue');
console.log(metric.sql);
虽然ktx主要是CLI工具,但你也可以通过编程方式使用它:
typescript
import { KtxProject } from '@kaelio/ktx';

// 加载现有项目
const project = await KtxProject.load('/path/to/project');

// 搜索语义层
const results = await project.searchSemanticLayer('revenue');
console.log(results);

// 搜索维基知识库
const wikiResults = await project.searchWiki('refund policy');
console.log(wikiResults);

// 执行查询
const queryResult = await project.query(
  'warehouse',
  'SELECT * FROM customers LIMIT 10'
);
console.log(queryResult.rows);

// 获取指标定义
const metric = await project.getMetric('monthly_recurring_revenue');
console.log(metric.sql);

Troubleshooting

故障排除

MCP Server Not Starting

MCP服务器无法启动

Symptom: Agent can't connect to ktx
Solution:
bash
undefined
症状:Agent无法连接到ktx
解决方案
bash
undefined

Check status

检查状态

ktx status
ktx status

Start MCP server manually

手动启动MCP服务器

ktx mcp start --project-dir /path/to/project
ktx mcp start --project-dir /path/to/project

Check logs

查看日志

tail -f ~/.ktx/logs/mcp.log
undefined
tail -f ~/.ktx/logs/mcp.log
undefined

Ingestion Failures

提取失败

Symptom:
ktx ingest
fails with connection errors
Solution:
bash
undefined
症状
ktx ingest
因连接错误失败
解决方案
bash
undefined

Test database connection

测试数据库连接

ktx test-connection warehouse
ktx test-connection warehouse

Verify environment variables

验证环境变量

env | grep -E 'POSTGRES|SNOWFLAKE|ANTHROPIC|OPENAI'
env | grep -E 'POSTGRES|SNOWFLAKE|ANTHROPIC|OPENAI'

Check ktx.yaml syntax

检查ktx.yaml语法

ktx validate
ktx validate

Ingest with verbose logging

启用详细日志提取

ktx ingest --verbose
undefined
ktx ingest --verbose
undefined

Missing Metrics

指标缺失

Symptom:
ktx sl "metric_name"
returns no results
Solution:
bash
undefined
症状
ktx sl "metric_name"
无结果返回
解决方案
bash
undefined

Re-ingest context

重新提取上下文

ktx ingest --force
ktx ingest --force

Check semantic layer directory

检查语义层目录

ls -la semantic-layer/warehouse/metrics/
ls -la semantic-layer/warehouse/metrics/

Manually create metric if needed

如有需要手动创建指标

mkdir -p semantic-layer/warehouse/metrics cat > semantic-layer/warehouse/metrics/my_metric.yaml << 'EOF' name: my_metric type: metric description: My custom metric entity: my_entity sql: COUNT(*) EOF
mkdir -p semantic-layer/warehouse/metrics cat > semantic-layer/warehouse/metrics/my_metric.yaml << 'EOF' name: my_metric type: metric description: My custom metric entity: my_entity sql: COUNT(*) EOF

Rebuild context

重建上下文

ktx ingest
undefined
ktx ingest
undefined

LLM Provider Issues

LLM提供商问题

Symptom: Context building fails with API errors
Solution:
bash
undefined
症状:上下文构建因API错误失败
解决方案
bash
undefined

Verify API key

验证API密钥

echo $ANTHROPIC_API_KEY
echo $ANTHROPIC_API_KEY

Test LLM connection

测试LLM连接

ktx test-llm
ktx test-llm

Switch provider if needed

如有需要切换提供商

ktx setup
ktx setup

Select different LLM provider

选择不同的LLM提供商

Check rate limits and quota

检查速率限制和配额

undefined
undefined

Permission Errors

权限错误

Symptom: Can't write to project directory
Solution:
bash
undefined
症状:无法写入项目目录
解决方案
bash
undefined

Check directory permissions

检查目录权限

ls -la .
ls -la .

Fix ownership

修复所有权

sudo chown -R $USER:$USER .
sudo chown -R $USER:$USER .

Or specify writable project directory

或指定可写入的项目目录

ktx setup --project-dir ~/my-ktx-project
undefined
ktx setup --project-dir ~/my-ktx-project
undefined

Semantic Layer Contradictions

语义层矛盾

Symptom: ktx flags conflicting metric definitions
Solution:
bash
undefined
症状:ktx标记冲突的指标定义
解决方案
bash
undefined

Review contradictions report

查看矛盾报告

cat raw-sources/warehouse/contradictions.json
cat raw-sources/warehouse/contradictions.json

Resolve by editing semantic sources

通过编辑语义源解决

vim semantic-layer/warehouse/metrics/revenue.yaml
vim semantic-layer/warehouse/metrics/revenue.yaml

Or update source (dbt, Looker, etc.)

或更新源(dbt、Looker等)

Then re-ingest

然后重新提取

ktx ingest --force
undefined
ktx ingest --force
undefined

Advanced Configuration

高级配置

Custom Sampling Strategy

自定义采样策略

Control how ktx samples tables during ingestion:
yaml
undefined
控制ktx在提取过程中如何采样表:
yaml
undefined

ktx.yaml

ktx.yaml

connections:
  • id: warehouse type: postgres config: host: localhost database: analytics sample_strategy: adaptive max_sample_rows: 10000 min_sample_rows: 100
undefined
connections:
  • id: warehouse type: postgres config: host: localhost database: analytics sample_strategy: adaptive max_sample_rows: 10000 min_sample_rows: 100
undefined

Join Detection Tuning

关联检测调优

Adjust automatic join detection:
yaml
undefined
调整自动关联检测:
yaml
undefined

ktx.yaml

ktx.yaml

semantic_layer: join_detection: min_confidence: 0.8 sample_size: 1000 detect_fan_traps: true detect_chasm_traps: true
undefined
semantic_layer: join_detection: min_confidence: 0.8 sample_size: 1000 detect_fan_traps: true detect_chasm_traps: true
undefined

Wiki Organization

维基知识库组织

Structure wiki for better retrieval:
bash
wiki/
├── global/
│   ├── metrics/
│   │   ├── revenue-definitions.md
│   │   └── user-engagement.md
│   ├── policies/
│   │   ├── data-retention.md
│   │   └── refund-policy.md
│   └── glossary/
│       └── business-terms.md
└── user/
    └── <user-id>/
        └── scratch.md
结构化维基知识库以优化检索:
bash
wiki/
├── global/
│   ├── metrics/
│   │   ├── revenue-definitions.md
│   │   └── user-engagement.md
│   ├── policies/
│   │   ├── data-retention.md
│   │   └── refund-policy.md
│   └── glossary/
│       └── business-terms.md
└── user/
    └── <user-id>/
        └── scratch.md

Best Practices

最佳实践

  1. Use read-only database credentials - ktx never writes, but enforce it at the DB level
  2. Commit semantic layer and wiki - Share context across team
  3. Keep .ktx/ local - Contains secrets and local state
  4. Re-ingest after schema changes -
    ktx ingest
    after dbt runs or migrations
  5. Document metrics in wiki - Add business context beyond SQL definitions
  6. Use environment variables for secrets - Never commit credentials
  7. Test queries before agents use them -
    ktx query
    validates SQL
  8. Review contradiction reports - Resolve conflicting definitions promptly
  1. 使用只读数据库凭证 - ktx从不写入数据,但在数据库层面强制执行只读权限
  2. 提交语义层和维基知识库 - 在团队间共享上下文
  3. 将.ktx/保留在本地 - 包含密钥和本地状态
  4. 模式变更后重新提取 - dbt运行或迁移后执行
    ktx ingest
  5. 在维基知识库中记录指标 - 添加SQL定义之外的业务上下文
  6. 使用环境变量存储密钥 - 绝不提交凭证
  7. Agent使用前测试查询 -
    ktx query
    可验证SQL
  8. 查看矛盾报告 - 及时解决冲突定义

Project Resolution

项目解析顺序

ktx finds projects in this order:
  1. --project-dir
    flag
  2. KTX_PROJECT_DIR
    environment variable
  3. Nearest
    ktx.yaml
    in parent directories
  4. Current working directory
For scripting, always use explicit project dir:
bash
ktx ingest --project-dir /opt/analytics
ktx mcp start --project-dir /opt/analytics

ktx按以下顺序查找项目:
  1. --project-dir
    参数
  2. KTX_PROJECT_DIR
    环境变量
  3. 父目录中最近的
    ktx.yaml
  4. 当前工作目录
脚本中请始终使用明确的项目目录:
bash
ktx ingest --project-dir /opt/analytics
ktx mcp start --project-dir /opt/analytics