1. 项目定位与目标

ktx 是一个自改进的上下文层（self-improving context layer），用于教会 AI 智能体（agents）准确查询数据仓库。它会从已审批的指标定义、可关联的列以及业务知识中自动构建并维护上下文，从而避免智能体在每次提示时都重新编写规范 SQL。

项目的核心职责可以归纳为四点 README.md：

• 吸收多源知识：从 dbt、Looker、Metabase、Notion 等系统中读取并整合业务文档，去重并标记矛盾。
• 映射数据栈：对表进行采样、采集元数据与使用模式，检测可关联列，并对来源进行标注。
• 构建语义层：通过连接图（join graph）把原始表和高层指标组合起来，自动解决 chasm 与 fan trap。
• 服务于智能体执行：通过 CLI 与 MCP 工具暴露统一接口，提供跨 wiki 与语义层实体的全文与语义混合搜索。

[!NOTE]

ktx 完全在本地运行，发送到外部的只有用户配置 LLM 提供商时主动发出的内容。运行可以使用用户自带的 LLM API Key，也可以复用 Claude Pro/Max 订阅下的 Claude Code 会话，或通过 Codex SDK 使用本地 Codex 认证 README.md。

2. 架构总览

项目采用 pnpm + uv 混合工作区 结构，TypeScript 负责 CLI 与上下文引擎，Python 负责可移植的语义层与计算服务。

flowchart LR
    User[用户 / Agent 客户端] --> CLI[packages/cli<br/>TypeScript CLI]
    CLI -->|MCP / 命令| Engine[context 引擎<br/>packages/cli/src/context]
    Engine --> Conn[connectors<br/>仓库扫描连接器]
    Engine --> LLM[llm<br/>LLM 与 Embedding 适配]
    CLI -->|HTTP| Daemon[python/ktx-daemon<br/>可移植计算服务]
    Daemon --> SL[ktx-sl<br/>语义层规划]
    Daemon --> LookML[lookml.py<br/>LookML 解析]
    Daemon --> Gen[source_generation.py<br/>从 schema 生成 source]
    Daemon --> Tele[telemetry<br/>事件埋点]

• CLI 入口提供 ktx setup、ktx status、ktx ingest、ktx sl、ktx wiki、ktx mcp start 等命令 README.md。
• CLI 通过 serve-http 子命令与 ktx-daemon 进行 HTTP 通信，默认监听 127.0.0.1:8765，并可通过 --enable-code-execution 暴露代码执行端点 python/ktx-daemon/src/ktx_daemon/__main__.py。
• setup-commands.ts 中暴露的 ktx setup --agents 支持选择目标智能体（claude-code、codex、cursor、opencode、claude-desktop、universal）以及安装目录 packages/cli/src/commands/setup-commands.ts。

3. 仓库与目录结构

根 package.json 中声明了 Apache-2.0 许可证，仓库地址为 git+https://github.com/Kaelio/ktx.git package.json。核心路径如下 README.md：

CLI 包 packages/cli/package.json 引入了 PostgreSQL、Snowflake、BigQuery、MySQL、SQL Server、SQLite、Looker SDK、Notion SDK、MCP SDK、Codex SDK、Ink（终端 UI）等关键依赖 packages/cli/package.json。

[!IMPORTANT]

连接器（connectors）已经从早期的 packages/connector-* 独立包改为 packages/cli 内的模块，社区中正在讨论的 Athena、Redshift、MongoDB 等新连接器都将遵循此布局（参见 issue #161、#164、#305）。

4. 核心子系统

4.1 语义层（Semantic Layer）

python/ktx-daemon/src/ktx_daemon/semantic_layer.py 提供了 query_semantic_layer 入口函数，负责解析请求、加载 SourceDefinition、校验重复度量名、规划度量与连接，并返回 QueryResult python/ktx-daemon/src/ktx_daemon/semantic_layer.py。这使得智能体可以声明式地获取指标，而无需每次都重写规范 SQL。

4.2 LookML 解析

lookml.py 实现了完整的 LookML 项目解析流水线：常量提取、extends/refinements 继承、列引用解析、度量与连接构建。parse_lookml_project 会过滤掉指向被跳过视图的连接，并返回 KSL-ready 的视图、连接与告警 python/ktx-daemon/src/ktx_daemon/lookml.py。

4.3 Source 自动生成

source_generation.py 根据数据库 schema 扫描结果生成 ktx-sl YAML 源定义，通过列名与类型正则（int/numeric/timestamp/bool/_id）自动识别主键、时间列与布尔列，并基于外键关系生成 JoinDeclaration python/ktx-daemon/src/ktx_daemon/source_generation.py。

4.4 遥测（Telemetry）

遥测事件在 events.schema.json 中以 JSON Schema 形式声明，并在 events.py 中通过 _schema_catalog 动态校验白名单字段。daemon 端的事件集合包括 daemon_started、daemon_stopped、sl_plan_completed、sql_gen_completed 等，且所有事件都附带 cliVersion、nodeVersion、osPlatform、osRelease、arch、runtime、isCi 等通用信封字段 python/ktx-daemon/src/ktx_daemon/telemetry/events.py python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json。

5. 快速开始

# 全局安装
npm install -g @kaelio/ktx

# 初始化项目、配置提供商与连接、构建上下文、安装智能体集成
ktx setup

# 检查项目就绪状态
ktx status

# 为已配置的连接构建上下文
ktx ingest

成功执行 ktx status 后会输出类似 Project ready: yes、LLM ready: yes (claude-sonnet-4-6)、Embeddings ready: yes (text-embedding-3-small)、Databases configured: yes、Context sources configured: yes、ktx context built: yes、Agent integration ready: yes 的状态行 README.md。

本地开发则使用 pnpm run setup:dev 与 pnpm run link:dev 链接本地 CLI，再通过 ktx-dev --help 验证；常用检查脚本包括 pnpm run type-check、pnpm run test、pnpm run dead-code 与 uv run pytest -q README.md。

6. 典型项目目录

一个使用 ktx 管理的项目目录结构如下 README.md：

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

需要提交到版本库的是 ktx.yaml、semantic-layer/ 与 wiki/，而 .ktx/ 应保持本地。项目解析顺序为 KTX_PROJECT_DIR → 最近祖先目录的 ktx.yaml → 当前目录，脚本化调用时可使用 --project-dir <path> 显式指定 README.md。

7. 适用场景

ktx 适合以下用户：

• 希望 Claude Code、Codex、Cursor、OpenCode 等智能体能够通过已审批指标查询仓库。
• 业务知识分散在 dbt、Looker、Metabase、Notion 与团队 wiki 中，需要统一吸收。
• 希望智能体复用规范 SQL，避免每次提示时重新生成。

如果还没有 SQL 仓库（ktx 是其上层）或仅需一次临时查询（psql 或 Notebook 即可），则不建议使用 ktx。当前支持的数据库与集成包括 PostgreSQL、Snowflake、BigQuery、ClickHouse、MySQL、SQL Server、SQLite、dbt、MetricFlow、LookML、Looker、Metabase 与 Notion README.md。

8. See Also

• Building Context 指南
• Semantic Layer 上下文层
• CLI Reference
• Community & Support
• Telemetry 说明

概览

ktx 是一个 pnpm + uv 混合工作区（monorepo），其源码被拆分为两大 src 树：TypeScript 端的 packages/cli/src/ 与 Python 端的 python/ktx-daemon/src/ktx_daemon/。两棵树通过 CLI 进程调用 Python 子进程或 HTTP 守护进程进行协作，前者负责本地控制平面与 MCP 服务器，后者负责重型可移植计算（LookML 解析、源生成、语义层规划、嵌入计算等）。README.md 在 “Project Layout” 章节中明确列出了 packages/cli/src/context、packages/cli/src/llm、packages/cli/src/connectors 三个 TypeScript 子模块，以及 python/ktx-sl、python/ktx-daemon 两个 Python 包。资料来源：README.md:60-78

主仓库 package.json 以 Apache-2.0 协议发布，依赖矩阵中包含 @kaelio/ktx 共享的语义化发布工具链（semantic-release、conventional-changelog-conventionalcommits）以及 pg、better-sqlite3 等驱动绑定。资料来源：package.json:1-30

TypeScript CLI 端（packages/cli/src）

packages/cli/src 是已发布 npm 包 @kaelio/ktx 的源码根目录，由 commander 14.x 驱动。其依赖矩阵见 packages/cli/package.json，涵盖 @modelcontextprotocol/sdk、@notionhq/client、@looker/sdk-rtl、lookml-parser、snowflake-sdk、mssql、mysql2、pg、better-sqlite3、openai、@openai/codex-sdk、ink 等核心库。资料来源：packages/cli/package.json:4-39

源码按职责划分为以下子目录：

• context/：核心上下文引擎，负责组合 wiki 与语义层、生成代理可消费的上下文；自 v0.8.0 起 ktx ingest 始终构建增强型上下文，旧版 “fast mode” 已移除（KLO-721）。社区正在跟踪的新适配器（如 Sigma [#168]、Confluence [#169]）也将以 packages/context/src/ingest/adapters/<source>/ 的形式落地于此树。资料来源：packages/cli/package.json:4-39
• llm/：LLM 与 embedding 提供方（Anthropic、Vertex AI、AI Gateway、Claude Agent SDK、Codex SDK）的适配层；v0.9.0 起新增 Codex LLM 后端用于 ktx 运行时工作。资料来源：packages/cli/package.json:4-39
• connectors/：数据库扫描连接器（PostgreSQL、Snowflake、BigQuery、ClickHouse、MySQL、SQL Server、SQLite）的实现。社区在 [#161]、[#164]、[#305] 中分别提出了 Amazon Redshift、Athena、MongoDB 等只读连接器的扩展位置统一为该目录下的模块。资料来源：packages/cli/package.json:4-39
• commands/：以 commander 注册的子命令。setup-commands.ts 的 registerSetupCommands 暴露了 ktx setup --agents、--install-dir（v0.13.0 引入 [#298]）、--skip-agents、--target（claude-code / claude-desktop / codex / cursor / opencode / universal）、--global、--local、--yes 等选项，并在 optionWasSpecified 检测中显式忽略 source* 与 skipSources 等上下文源选项。资料来源：packages/cli/src/commands/setup-commands.ts:1-60

Python 守护进程端（python/ktx-daemon/src/ktx_daemon）

Python 端的 src 树根为 python/ktx-daemon/src/ktx_daemon/，入口由 __main__.py 暴露为 CLI 与 HTTP 守护进程。__main__.py 注册了 semantic-generate-sources、database-introspect、lookml-parse、embedding-compute、embedding-compute-bulk、code-execute、serve-http 等子命令，其中 serve-http 默认监听 127.0.0.1:8765，并通过 --enable-code-execution 暴露 POST /code/execute；CLI 还支持 --log-level（critical / error / warning / info / debug / trace）。资料来源：python/ktx-daemon/src/ktx_daemon/__main__.py:1-60

主要模块职责如下：

• lookml.py：解析 LookML 项目，按 manifest.lkml 收集常量（_collect_constants）、替换 @{...} 与 Liquid 变量、解析 extends/refinements 与 ${view.field} 引用，并构建 KSL-ready 的视图与 join 列表；主入口 parse_lookml_project 返回 ParseLookMLResponse，并过滤掉引用了被跳过视图的 join。资料来源：python/ktx-daemon/src/ktx_daemon/lookml.py:1-30
• source_generation.py：将数据库 schema 扫描数据转换为 ktx-sl YAML 源定义；按 _NUMBER_PATTERN、_TIME_PATTERN、_BOOLEAN_PATTERN、_ID_PATTERN 推断列类型与角色，自动生成 SourceColumn、JoinDeclaration、MeasureDefinition，并在 many_to_one / one_to_many 之间通过 _RELATIONSHIP_INVERSE 双向补全。资料来源：python/ktx-daemon/src/ktx_daemon/source_generation.py:1-40
• semantic_layer.py：语义层查询执行入口 query_semantic_layer，负责加载源、校验重名度量（_validate_duplicate_measure_names）、按 provenance 重命名返回列（_response_columns），并按 time.perf_counter() 统计阶段耗时，为 sl_plan_completed 遥测提供数据。资料来源：python/ktx-daemon/src/ktx_daemon/semantic_layer.py:1-30
• telemetry/：遥测事件模块；events.py 读取 events.schema.json 中的 x-ktx-catalog 字段并构建 EVENT_FIELDS 白名单，仅允许白名单字段出现在最终上报中；build_telemetry_event 在写入前会剔除额外字段并按 DAEMON_EVENTS（daemon_started、daemon_stopped、sl_plan_completed、sql_gen_completed）进行过滤。资料来源：python/ktx-daemon/src/ktx_daemon/telemetry/events.py:1-30

端到端协作流程

CLI 在执行 ktx ingest 或代理通过 MCP 调用重型任务时，会通过子进程或 HTTP 调用 ktx-daemon，由其完成 LookML 解析、源生成、语义层规划、嵌入计算等长任务，再将结构化结果回传给 TypeScript 端写入 wiki 与 semantic-layer。下图展示了 src 模块的运行时分工：

flowchart LR
  A[packages/cli/src/commands] --> B[packages/cli/src/context]
  A --> C[packages/cli/src/llm]
  A --> D[packages/cli/src/connectors]
  B -->|HTTP or stdin JSON| E[python/ktx-daemon/src/ktx_daemon/__main__]
  E --> F[lookml.py]
  E --> G[source_generation.py]
  E --> H[semantic_layer.py]
  E --> I[embeddings.py]
  E --> J[telemetry/events.py]
  D -->|scan| K[Warehouse]
  H -->|read-only SQL| K

失败模式与注意事项

• 守护进程端口冲突：serve-http 固定默认 127.0.0.1:8765，若已被占用需显式指定 --port。资料来源：python/ktx-daemon/src/ktx_daemon/__main__.py:30-45
• 遥测字段越界：build_telemetry_event 严格按 events.schema.json 中的 x-ktx-catalog 白名单校验传入字段，多余字段会被丢弃并触发 ValueError。资料来源：python/ktx-daemon/src/ktx_daemon/telemetry/events.py:20-30
• LookML 常量覆盖：未在 constant_overrides 中提供的常量将回退到 manifest.lkml 的定义，缺常量会导致字段引用保持为 @{name} 占位符并被加入 skipped_views / warnings。资料来源：python/ktx-daemon/src/ktx_daemon/lookml.py:60-80
• 源名称重复：semantic_layer.py 中 _load_sources 显式拒绝重名 SourceDefinition，需先在 CLI 端去重后再下发。资料来源：python/ktx-daemon/src/ktx_daemon/semantic_layer.py:10-20

另请参阅

• ktx 仓库总览（README）
• CLI 参考文档
• LLM 配置指南
• 遥测事件目录

模块概述与定位

Agents 模块是 ktx 把"已构建好的上下文"与外部编码/对话 Agent（Claude Code、Codex、Cursor、OpenCode、Claude Desktop 等）连接起来的桥梁层。它位于 CLI 之上，负责把 ktx 项目内的 ktx.yaml、semantic-layer/、wiki/ 与本地 MCP（Model Context Protocol）服务注册到目标 Agent 客户端，使 Agent 能够通过受控接口调用语义层查询、Wiki 检索与数据库连接。

资料来源：README.md:1-40

模块的核心职责集中在 CLI 的 setup 子命令与 mcp start 子命令上。ktx setup 负责配置 Agent 集成，ktx mcp start 启动 MCP 服务端供 Agent 客户端连接。两者共同构成 Agent 接入的入口。

flowchart LR
    A[ktx setup --agents] --> B[写入 Agent 客户端配置]
    B --> C1[Claude Code]
    B --> C2[Codex]
    B --> C3[Cursor]
    B --> C4[OpenCode]
    B --> C5[Claude Desktop]
    B --> C6[universal]
    A --> D[ktx mcp start]
    D --> E[stdio MCP Server]
    E --> F[wiki / sl / db tools]

支持的 Agent 目标

setup 命令通过 --target 选项显式指定要接入的 Agent 类型，选项枚举在 CLI 中严格定义：

资料来源：packages/cli/src/commands/setup-commands.ts:31-41

--global 与 --local 两个互斥开关控制 Agent 配置的写入作用域：--global 写入 Agent 的全局配置目录，--local（仅 Claude Code 路径）把 MCP 配置写入项目级的 ~/.claude.json 私有作用域，避免污染团队共享仓库。

资料来源：packages/cli/src/commands/setup-commands.ts:42-45

安装流程与命令行选项

ktx setup --agents 是 Agents 模块最常用的入口。--agents 选项将 setup 限制在"仅安装 Agent 集成"模式，跳过数据库与上下文源配置。--install-dir <path> 选项允许用户自定义 Agent 配置的安装目录，默认值为 ktx 项目目录本身，这一行为在 v0.13.0 中引入。

资料来源：packages/cli/src/commands/setup-commands.ts:36-52, README.md:108-120

--skip-agents 选项是反向开关，允许在完整 setup 流程中跳过 Agent 安装步骤，便于在 CI 或无头环境中完成项目初始化。--yes 选项则让 setup 在所有确认点上接受默认行为，便于脚本化部署。

ktx status 会在 Agent 集成完成后输出 Agent integration ready: yes (<target>:<scope>)，其中 <scope> 反映 project 或 global 安装位置。

资料来源：README.md:74-83

LLM 后端与 MCP 协议

Agent 在调用 ktx 时实际运行模型推理，所需 LLM 后端通过独立的运行时配置指定。README 文档化的后端集合包括：

• Anthropic API
• Google Vertex AI
• AI Gateway
• Claude Agent SDK（复用本地 Claude Code 会话）
• Codex SDK（复用本地 Codex 鉴权）

资料来源：README.md:120-128

其中 Codex SDK 后端在 v0.9.0 中作为 codex LLM backend 加入 ktx 运行时，使 Agent 在没有独立 API Key 时也能通过本地会话完成上下文构建工作。

资料来源：README.md:152-156

ktx mcp start 启动一个 stdio MCP 服务，对外暴露 wiki 与 sl 等工具集。CLI 包依赖 @modelcontextprotocol/sdk@^1.29.0 提供协议实现。

资料来源：packages/cli/package.json:9-12

遥测与排障

Agent 触发的 MCP 请求会被采样上报。遥测事件 mcp_request_completed 记录工具名、执行结果、耗时、错误分类以及客户端名称与版本，用于定位 Agent 集成中的失败链路。该事件在 schema 中显式声明字段约束，并在发出前按 schema 校验字段集合。

资料来源：python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json:1-40

daemon 自身的启停则通过 daemon_started / daemon_stopped 两个事件独立追踪，记录 daemonVersion、pythonVersion、runtimeVersion 与启动耗时，便于 Agent 调用栈中区分 Node CLI 与 Python daemon 的边界。

资料来源：python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json:40-60

社区关注点

社区目前关注的方向主要集中在三方面：（1）通过 ktx setup --agents 让 Agent 接入更轻量，v0.13.0 引入的 --install-dir 正是回应这一点；（2）将更多 Agent 类型纳入统一安装，例如 universal 目标；（3）在不破坏既有 MCP 工具集的前提下扩展上下文源（如 Sigma、Confluence、MongoDB），以丰富 Agent 可检索的内容面。

资料来源：README.md:108-128, packages/cli/src/commands/setup-commands.ts:31-52

See Also

• CLI Reference
• AI Resources
• Building Context
• Telemetry

概述与定位

Commands 模块是 ktx 命令行工具的核心注册层,负责把所有用户面 (user-facing) 的子命令挂载到根 program 上,并将每个子命令对应的参数解析、上下文准备与执行器 (runner) 连接起来。该模块位于 packages/cli/src/commands/ 目录,采用"每个子命令一个文件"的组织方式,与 Commander.js 的 Command 抽象一一对应。资料来源:packages/cli/src/commands/setup-commands.ts:1-40

整个 ktx CLI 通过 @commander-js/extra-typings 的 Command 类型构造命令树,典型入口模式为:

export function registerXxxCommands(program: Command, context: KtxCliCommandContext): void {
  const xxx = program.command('xxx').description('...');
  xxx.option(...);
  xxx.action(async (...args) => { ... });
}

资料来源:packages/cli/src/commands/knowledge-commands.ts:1-30

每个注册函数接收共享的 KtxCliCommandContext,它包含依赖注入容器 (deps)、IO 抽象 (io) 以及退出码设置函数 (setExitCode),从而实现测试可注入与统一退出语义。

主要子命令组织

commands/ 目录下的文件按业务域划分,每个文件对应一族相关命令。下表汇总了常见的命令族及其用途:

资料来源:packages/cli/src/commands/setup-commands.ts:30-60、packages/cli/src/commands/knowledge-commands.ts:1-15

setup-commands:项目初始化

setup 是用户首次接触 ktx 的入口,负责初始化 ktx.yaml、安装 Python 运行时、配置 LLM 后端以及选择上下文源。它接受诸如 --project-dir、--agents、--target、--global、--local、--install-dir、--yes、--skip-agents 等选项,并通过 commandWasSpecified 工具函数判断用户在 setup 过程中是否提供了特定来源相关的参数,例如 sourceAuthTokenRef、sourceApiKeyRef、metabaseDatabaseId、notionCrawlMode 等。资料来源:packages/cli/src/commands/setup-commands.ts:1-30

--target 选项限定了 Agent 集成目标,合法值包括 claude-code、claude-desktop、codex、cursor、opencode 与 universal。这种"目标枚举"的设计使得 setup 阶段能够针对不同 Agent 的 MCP 配置格式生成对应的项目级或全局级配置文件。

knowledge-commands:本地知识库访问

ktx wiki 子命令族由 registerWikiCommands 注册,支持三种模式:

• 不带参数:列出所有页面
• 带查询词:执行搜索
• --output 选项:控制输出格式为 pretty(默认,在 TTY 下)、plain(TSV) 或 json

此外,--user-id 用于切换本地用户作用域(local 为默认值),--limit 限定搜索结果条数。所有选项在注册时即通过 Option(...).choices([...]) 显式声明合法值,保证解析期就捕获非法输入。资料来源:packages/cli/src/commands/knowledge-commands.ts:1-25

其他命令族

connection-commands 暴露数据库连接生命周期操作(创建、列出、测试、删除),connection-selection 则在交互式 setup / ingest 阶段复用 clack 风格的树形选择器(参考 v0.6.0 发布的"skip-context-sources menu + clack-style tree picker UX")。mcp-commands 启动一个长期运行的 MCP HTTP/SSE 服务,供 Claude Code、Codex、Cursor 等 Agent 通过 stdio 或 HTTP 调用 ktx 的查询能力。completion-commands 则根据当前 shell 类型输出对应的补全脚本片段。资料来源:packages/cli/src/commands/mcp-commands.ts、packages/cli/src/commands/completion-commands.ts

执行器与共享上下文

每个 registerXxxCommands 函数不直接执行业务逻辑,而是构造 Command 树并通过 xxx.action(async (...args) => {...}) 将参数转发给一个独立的 runner 模块(例如 runKtxKnowledge)。这种"注册/执行"分离的模式使得:

1. 注册层保持轻量,只关心 Commander 的 API;
2. Runner 可独立测试,不依赖 Commander 的命令对象;
3. 通过 KtxCliCommandContext 注入依赖,避免全局副作用。

flowchart LR
  User[用户输入 ktx ...] --> Parser[Commander 解析]
  Parser --> Registry[registerXxxCommands]
  Registry --> Action[Command.action 回调]
  Action --> Context[KtxCliCommandContext]
  Context --> Deps[deps.* 业务模块]
  Context --> IO[io 抽象]
  Deps --> Runner[runKtxXxx]
  Runner --> Output[stdout / stderr]

资料来源:packages/cli/src/commands/knowledge-commands.ts:10-30

常见失败模式与设计取舍

1. 选项拼写错误:所有选项在 Option(...).choices([...]) 处收紧,非法值会被 Commander 立即拒绝,避免静默回退到默认值。
2. 缺失上下文:当命令需要项目上下文但未找到 ktx.yaml 时,通过 resolveCommandProjectDir 解析 KTX_PROJECT_DIR 环境变量,再退回到当前目录;脚本化场景下建议显式传入 --project-dir <path>。
3. setup 阶段跳过的来源:setup-commands.ts 维护了一份"来源相关选项"白名单,通过 commandWasSpecified 统一判断,避免散落在多个 if 分支。
4. Agent 集成目录漂移:v0.13.0 引入 --install-dir 后,setup 默认安装目录跟随 ktx 项目根目录,但 --global / --local 标志仍可覆盖作用域。

资料来源:packages/cli/src/commands/setup-commands.ts:1-60

See Also

• CLI Reference
• 项目上下文层
• Building Context

Pitfall Log / 踩坑日志

项目：Kaelio/ktx

摘要：发现 27 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：Add MongoDB connector。

1. 配置坑 · 来源证据：Add MongoDB connector

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add MongoDB connector
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Kaelio/ktx/issues/305 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安全/权限坑 · 失败模式：security_permissions: Add Sigma context source

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Add Sigma context source
• 对用户的影响：Developers may expose sensitive permissions or credentials: Add Sigma context source
• 证据：failure_mode_cluster:github_issue | https://github.com/Kaelio/ktx/issues/168 | Add Sigma context source

3. 安全/权限坑 · 来源证据：Add Amazon Redshift connector

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Amazon Redshift connector
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Kaelio/ktx/issues/161 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安全/权限坑 · 来源证据：Add Confluence context source

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Confluence context source
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Kaelio/ktx/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安全/权限坑 · 来源证据：Add Jira context source

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Jira context source
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Kaelio/ktx/issues/174 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

6. 安全/权限坑 · 来源证据：Add Sigma context source

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Sigma context source
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Kaelio/ktx/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安装坑 · 失败模式：installation: v0.12.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.12.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.12.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.12.0 | v0.12.0

8. 安装坑 · 失败模式：installation: v0.13.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.13.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.13.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.13.0 | v0.13.0

9. 安装坑 · 失败模式：installation: v0.6.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.6.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.6.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.6.0 | v0.6.0

10. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Kaelio/ktx | host_targets=claude_code, claude, mcp_host

11. 配置坑 · 失败模式：configuration: Add Amazon Redshift connector

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Add Amazon Redshift connector
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add Amazon Redshift connector
• 证据：failure_mode_cluster:github_issue | https://github.com/Kaelio/ktx/issues/161 | Add Amazon Redshift connector

12. 配置坑 · 失败模式：configuration: Add Confluence context source

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Add Confluence context source
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add Confluence context source
• 证据：failure_mode_cluster:github_issue | https://github.com/Kaelio/ktx/issues/169 | Add Confluence context source

13. 配置坑 · 失败模式：configuration: Add MongoDB connector

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Add MongoDB connector
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add MongoDB connector
• 证据：failure_mode_cluster:github_issue | https://github.com/Kaelio/ktx/issues/305 | Add MongoDB connector

14. 配置坑 · 失败模式：configuration: v0.5.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.5.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.5.0 | v0.5.0

15. 配置坑 · 失败模式：configuration: v0.8.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.8.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.8.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.8.0 | v0.8.0

16. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Kaelio/ktx | README/documentation is current enough for a first validation pass.

17. 运行坑 · 失败模式：runtime: v0.10.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.10.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.10.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.10.0 | v0.10.0

18. 运行坑 · 失败模式：runtime: v0.11.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.11.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.11.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.11.0 | v0.11.0

19. 运行坑 · 失败模式：runtime: v0.9.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.9.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.9.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.9.0 | v0.9.0

20. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/Kaelio/ktx | matched external service / cloud / webhook / database keyword

21. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Kaelio/ktx | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Kaelio/ktx | no_demo; severity=medium

23. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Kaelio/ktx | no_demo; severity=medium

24. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Kaelio/ktx | issue_or_pr_quality=unknown

25. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Kaelio/ktx | release_recency=unknown

26. 维护坑 · 失败模式：maintenance: v0.13.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.13.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.13.1
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.13.1 | v0.13.1

27. 维护坑 · 失败模式：maintenance: v0.7.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.7.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0
• 证据：failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.7.0 | v0.7.0