# https://github.com/Kaelio/ktx 项目说明书

生成时间：2026-06-27 07:45:54 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-python-ktx-daemon-src)
- [Agents 模块](#page-skills-ktx-agents)
- [Commands 模块](#page-packages-cli-src-commands)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-python-ktx-daemon-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Kaelio/ktx/blob/main/README.md)
- [package.json](https://github.com/Kaelio/ktx/blob/main/package.json)
- [packages/cli/package.json](https://github.com/Kaelio/ktx/blob/main/packages/cli/package.json)
- [packages/cli/src/commands/setup-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/setup-commands.ts)
- [python/ktx-daemon/src/ktx_daemon/__main__.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/__main__.py)
- [python/ktx-daemon/src/ktx_daemon/semantic_layer.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/semantic_layer.py)
- [python/ktx-daemon/src/ktx_daemon/lookml.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/lookml.py)
- [python/ktx-daemon/src/ktx_daemon/source_generation.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/source_generation.py)
- [python/ktx-daemon/src/ktx_daemon/telemetry/events.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/telemetry/events.py)
- [python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json)
</details>

# 项目概览

## 1. 项目定位与目标

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

项目的核心职责可以归纳为四点 [README.md](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/README.md)。

## 2. 架构总览

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

```mermaid
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](https://github.com/Kaelio/ktx/blob/main/README.md)。
- CLI 通过 `serve-http` 子命令与 `ktx-daemon` 进行 HTTP 通信，默认监听 `127.0.0.1:8765`，并可通过 `--enable-code-execution` 暴露代码执行端点 [python/ktx-daemon/src/ktx_daemon/__main__.py](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/setup-commands.ts)。

## 3. 仓库与目录结构

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

| 路径 | 用途 |
| --- | --- |
| `packages/cli` | TypeScript CLI 与已发布的 npm 包源码 |
| `packages/cli/src/context` | 核心上下文引擎 |
| `packages/cli/src/llm` | LLM 与 Embedding 提供方 |
| `packages/cli/src/connectors` | 数据库扫描连接器 |
| `python/ktx-sl` | 语义层查询规划 |
| `python/ktx-daemon` | 可移植计算服务 |

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](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/telemetry/events.py) [python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json)。

## 5. 快速开始

```bash
# 全局安装
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](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/README.md)。

## 6. 典型项目目录

一个使用 **ktx** 管理的项目目录结构如下 [README.md](https://github.com/Kaelio/ktx/blob/main/README.md)：

```text
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](https://github.com/Kaelio/ktx/blob/main/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](https://github.com/Kaelio/ktx/blob/main/README.md)。

## 8. See Also

- [Building Context 指南](https://docs.kaelio.com/ktx/docs/guides/building-context)
- [Semantic Layer 上下文层](https://docs.kaelio.com/ktx/docs/guides/semantic-layer)
- [CLI Reference](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
- [Community & Support](https://docs.kaelio.com/ktx/docs/community/support)
- [Telemetry 说明](https://docs.kaelio.com/ktx/docs/community/telemetry)

---

<a id='page-python-ktx-daemon-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Agents 模块](#page-skills-ktx-agents)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/Kaelio/ktx/blob/main/package.json)
- [README.md](https://github.com/Kaelio/ktx/blob/main/README.md)
- [packages/cli/package.json](https://github.com/Kaelio/ktx/blob/main/packages/cli/package.json)
- [python/ktx-daemon/src/ktx_daemon/__main__.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/__main__.py)
- [python/ktx-daemon/src/ktx_daemon/lookml.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/lookml.py)
- [python/ktx-daemon/src/ktx_daemon/source_generation.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/source_generation.py)
- [python/ktx-daemon/src/ktx_daemon/semantic_layer.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/semantic_layer.py)
- [python/ktx-daemon/src/ktx_daemon/telemetry/events.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/telemetry/events.py)
- [python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json)
- [packages/cli/src/commands/setup-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/setup-commands.ts)
</details>

# Src 模块

## 概览

ktx 是一个 pnpm + uv 混合工作区（monorepo），其源码被拆分为两大 `src` 树：TypeScript 端的 [`packages/cli/src/`](https://github.com/Kaelio/ktx/tree/main/packages/cli/src) 与 Python 端的 [`python/ktx-daemon/src/ktx_daemon/`](https://github.com/Kaelio/ktx/tree/main/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`](https://github.com/Kaelio/ktx/blob/main/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/`](https://github.com/Kaelio/ktx/tree/main/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` 模块的运行时分工：

```mermaid
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）](https://github.com/Kaelio/ktx#readme)
- [CLI 参考文档](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
- [LLM 配置指南](https://docs.kaelio.com/ktx/docs/guides/llm-configuration)
- [遥测事件目录](https://docs.kaelio.com/ktx/docs/community/telemetry)

---

<a id='page-skills-ktx-agents'></a>

## Agents 模块

### 相关页面

相关主题：[Src 模块](#page-python-ktx-daemon-src), [Commands 模块](#page-packages-cli-src-commands)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Kaelio/ktx/blob/main/README.md)
- [packages/cli/src/commands/setup-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/setup-commands.ts)
- [packages/cli/package.json](https://github.com/Kaelio/ktx/blob/main/packages/cli/package.json)
- [package.json](https://github.com/Kaelio/ktx/blob/main/package.json)
- [python/ktx-daemon/src/ktx_daemon/__main__.py](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/__main__.py)
- [python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json](https://github.com/Kaelio/ktx/blob/main/python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json)
</details>

# Agents 模块

## 模块概述与定位

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 接入的入口。

```mermaid
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 中严格定义：

| Target | 说明 |
| --- | --- |
| `claude-code` | 接入 Anthropic Claude Code CLI |
| `claude-desktop` | 接入 Claude Desktop 桌面应用 |
| `codex` | 接入 OpenAI Codex CLI |
| `cursor` | 接入 Cursor 编辑器 |
| `opencode` | 接入 OpenCode 编辑器 |
| `universal` | 通用安装，向所有已发现目标写入 |

资料来源：[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](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
- [AI Resources](https://docs.kaelio.com/ktx/docs/community/ai-resources)
- [Building Context](https://docs.kaelio.com/ktx/docs/guides/building-context)
- [Telemetry](https://docs.kaelio.com/ktx/docs/community/telemetry)

---

<a id='page-packages-cli-src-commands'></a>

## Commands 模块

### 相关页面

相关主题：[Agents 模块](#page-skills-ktx-agents)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli/src/commands/setup-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/setup-commands.ts)
- [packages/cli/src/commands/knowledge-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/knowledge-commands.ts)
- [packages/cli/src/commands/completion-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/completion-commands.ts)
- [packages/cli/src/commands/connection-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/connection-commands.ts)
- [packages/cli/src/commands/connection-selection.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/connection-selection.ts)
- [packages/cli/src/commands/ingest-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/ingest-commands.ts)
- [packages/cli/src/commands/mcp-commands.ts](https://github.com/Kaelio/ktx/blob/main/packages/cli/src/commands/mcp-commands.ts)
</details>

# Commands 模块

## 概述与定位

`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` 类型构造命令树,典型入口模式为:

```ts
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/` 目录下的文件按业务域划分,每个文件对应一族相关命令。下表汇总了常见的命令族及其用途:

| 文件 | 注册的命令族 | 核心职责 |
| --- | --- | --- |
| `setup-commands.ts` | `ktx setup` | 创建或恢复本地项目、配置 LLM、连接与上下文源 |
| `ingest-commands.ts` | `ktx ingest` | 拉取数据库 / BI / Wiki 来源并构建上下文 |
| `knowledge-commands.ts` | `ktx wiki` | 列出、搜索或读取本地 wiki 页面 |
| `connection-commands.ts` | `ktx connection` | 管理数据库与数据源连接 |
| `connection-selection.ts` | (内部选择器) | 在 setup / ingest 时提供连接选择 UX |
| `mcp-commands.ts` | `ktx mcp` | 启动 MCP 服务器供 Agent 客户端调用 |
| `completion-commands.ts` | `ktx completion` | 生成 Shell 自动补全脚本 |

资料来源:[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` 注入依赖,避免全局副作用。

```mermaid
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](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
- [项目上下文层](https://docs.kaelio.com/ktx/docs/guides/context-layer)
- [Building Context](https://docs.kaelio.com/ktx/docs/guides/building-context)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: Kaelio/ktx; human_manual_source: deepwiki_human_wiki -->