ktx-context-layer-data-agents
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesektx 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/ktxOr 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/ktxQuick Setup
快速设置
Run the interactive setup wizard:
bash
ktx setupThis 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 statusExpected 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 , , and . Keep local.
ktx.yamlsemantic-layer/wiki/.ktx/ktx会创建以下结构:
text
my-project/
├── ktx.yaml # 项目配置文件
├── semantic-layer/<connection-id>/ # YAML语义源
├── wiki/global/ # 共享业务上下文
├── wiki/user/<user-id>/ # 用户范围的笔记
├── raw-sources/<connection-id>/ # 提取的工件和报告
└── .ktx/ # 本地状态和密钥(Git忽略)提交、和。将保留在本地。
ktx.yamlsemantic-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: projectEnvironment Variables
环境变量
Store secrets in environment variables:
bash
undefined将密钥存储在环境变量中:
bash
undefinedLLM 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_...
undefinedexport LOOKER_BASE_URL=https://company.looker.com
export LOOKER_CLIENT_ID=your_client_id
export LOOKER_CLIENT_SECRET=your_secret
export NOTION_TOKEN=secret_...
undefinedCore Commands
核心命令
Build Context
构建上下文
Ingest from all configured connections and sources:
bash
ktx ingestIngest from specific connection:
bash
ktx ingest --connection warehouseIngest 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_mainSearch 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_idSearch 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 startSpecify project directory:
bash
ktx mcp start --project-dir /path/to/projectThe MCP server exposes these tools to agents:
- - Search metrics and dimensions
ktx_search_semantic_layer - - Search business knowledge
ktx_search_wiki - - Execute SQL queries
ktx_query - - Retrieve table schemas
ktx_get_schema - - Get canonical metric SQL
ktx_get_metric_definition
启动Model Context Protocol服务器以实现Agent集成:
bash
ktx mcp start指定项目目录:
bash
ktx mcp start --project-dir /path/to/projectMCP服务器向Agent开放以下工具:
- - 搜索指标和维度
ktx_search_semantic_layer - - 搜索业务知识
ktx_search_wiki - - 执行SQL查询
ktx_query - - 获取表结构
ktx_get_schema - - 获取标准指标SQL
ktx_get_metric_definition
Working with Semantic Sources
语义源使用
ktx automatically generates semantic sources during ingestion. You can also define them manually.
ktx会在提取过程中自动生成语义源,你也可以手动定义它们。
Metric Definition
指标定义
yaml
undefinedyaml
undefinedsemantic-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
undefinedname: 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
undefinedEntity Definition
实体定义
yaml
undefinedyaml
undefinedsemantic-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
undefinedname: 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
undefinedJoin Configuration
关联配置
ktx auto-detects joins, but you can override:
yaml
undefinedktx会自动检测关联,但你可以手动覆盖:
yaml
undefinedsemantic-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
undefinedfrom_entity: customer
to_entity: subscription
type: one_to_many
join_sql: customers.customer_id = subscriptions.customer_id
undefinedCommon Patterns
常见模式
Pattern 1: Setup New Project
模式1:新建项目设置
bash
undefinedbash
undefinedNavigate 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
undefinedktx ingest
undefinedPattern 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
undefinedCreate 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
undefinedktx ingest
undefinedPattern 4: Integrate dbt Metrics
模式4:集成dbt指标
bash
undefinedbash
undefinedEnsure 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"
undefinedktx sl "customers"
undefinedPattern 5: Agent Integration
模式5:Agent集成
For Codex:
bash
undefined针对Codex:
bash
undefinedInstall 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:
```bashnpx skills add Kaelio/ktx --skill ktx
针对Claude Code:
```bashktx 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
undefinedCheck 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
undefinedtail -f ~/.ktx/logs/mcp.log
undefinedIngestion Failures
提取失败
Symptom: fails with connection errors
ktx ingestSolution:
bash
undefined症状:因连接错误失败
ktx ingest解决方案:
bash
undefinedTest 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
undefinedktx ingest --verbose
undefinedMissing Metrics
指标缺失
Symptom: returns no results
ktx sl "metric_name"Solution:
bash
undefined症状:无结果返回
ktx sl "metric_name"解决方案:
bash
undefinedRe-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
undefinedktx ingest
undefinedLLM Provider Issues
LLM提供商问题
Symptom: Context building fails with API errors
Solution:
bash
undefined症状:上下文构建因API错误失败
解决方案:
bash
undefinedVerify 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
检查速率限制和配额
Anthropic: https://console.anthropic.com
Anthropic: https://console.anthropic.com
undefinedundefinedPermission Errors
权限错误
Symptom: Can't write to project directory
Solution:
bash
undefined症状:无法写入项目目录
解决方案:
bash
undefinedCheck 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
undefinedktx setup --project-dir ~/my-ktx-project
undefinedSemantic Layer Contradictions
语义层矛盾
Symptom: ktx flags conflicting metric definitions
Solution:
bash
undefined症状:ktx标记冲突的指标定义
解决方案:
bash
undefinedReview 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
undefinedktx ingest --force
undefinedAdvanced Configuration
高级配置
Custom Sampling Strategy
自定义采样策略
Control how ktx samples tables during ingestion:
yaml
undefined控制ktx在提取过程中如何采样表:
yaml
undefinedktx.yaml
ktx.yaml
connections:
- id: warehouse type: postgres config: host: localhost database: analytics sample_strategy: adaptive max_sample_rows: 10000 min_sample_rows: 100
undefinedconnections:
- id: warehouse type: postgres config: host: localhost database: analytics sample_strategy: adaptive max_sample_rows: 10000 min_sample_rows: 100
undefinedJoin Detection Tuning
关联检测调优
Adjust automatic join detection:
yaml
undefined调整自动关联检测:
yaml
undefinedktx.yaml
ktx.yaml
semantic_layer:
join_detection:
min_confidence: 0.8
sample_size: 1000
detect_fan_traps: true
detect_chasm_traps: true
undefinedsemantic_layer:
join_detection:
min_confidence: 0.8
sample_size: 1000
detect_fan_traps: true
detect_chasm_traps: true
undefinedWiki 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.mdBest Practices
最佳实践
- Use read-only database credentials - ktx never writes, but enforce it at the DB level
- Commit semantic layer and wiki - Share context across team
- Keep .ktx/ local - Contains secrets and local state
- Re-ingest after schema changes - after dbt runs or migrations
ktx ingest - Document metrics in wiki - Add business context beyond SQL definitions
- Use environment variables for secrets - Never commit credentials
- Test queries before agents use them - validates SQL
ktx query - Review contradiction reports - Resolve conflicting definitions promptly
- 使用只读数据库凭证 - ktx从不写入数据,但在数据库层面强制执行只读权限
- 提交语义层和维基知识库 - 在团队间共享上下文
- 将.ktx/保留在本地 - 包含密钥和本地状态
- 模式变更后重新提取 - dbt运行或迁移后执行
ktx ingest - 在维基知识库中记录指标 - 添加SQL定义之外的业务上下文
- 使用环境变量存储密钥 - 绝不提交凭证
- Agent使用前测试查询 - 可验证SQL
ktx query - 查看矛盾报告 - 及时解决冲突定义
Project Resolution
项目解析顺序
ktx finds projects in this order:
- flag
--project-dir - environment variable
KTX_PROJECT_DIR - Nearest in parent directories
ktx.yaml - Current working directory
For scripting, always use explicit project dir:
bash
ktx ingest --project-dir /opt/analytics
ktx mcp start --project-dir /opt/analyticsDocumentation: https://docs.kaelio.com/ktx
GitHub: https://github.com/Kaelio/ktx
Slack Community: https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ
GitHub: https://github.com/Kaelio/ktx
Slack Community: https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ
ktx按以下顺序查找项目:
- 参数
--project-dir - 环境变量
KTX_PROJECT_DIR - 父目录中最近的
ktx.yaml - 当前工作目录
脚本中请始终使用明确的项目目录:
bash
ktx ingest --project-dir /opt/analytics
ktx mcp start --project-dir /opt/analytics