# ktx - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 ktx 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86
- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`packages/cli/src/skills/analytics/SKILL.md`, `packages/cli/src/skills/dbt_ingest/SKILL.md`, `packages/cli/src/skills/historic_sql_patterns/SKILL.md`, `packages/cli/src/skills/historic_sql_table_digest/SKILL.md` 等 Claim：`clm_0004` supported 0.86

## 它能做什么

- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`packages/cli/src/skills/analytics/SKILL.md`, `packages/cli/src/skills/dbt_ingest/SKILL.md`, `packages/cli/src/skills/historic_sql_patterns/SKILL.md`, `packages/cli/src/skills/historic_sql_table_digest/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86

## 怎么开始

- `npm install -g @kaelio/ktx` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86
- `npm install -g @kaelio/ktx@latest` 证据：`README.md` Claim：`clm_0006` supported 0.86
- `git clone https://github.com/kaelio/ktx.git` 证据：`README.md` Claim：`clm_0007` supported 0.86

## 继续前判断卡

- **当前建议**：先做研究框架试用
- **为什么**：这个项目面向研究工作流，核心风险是资料可信度和输出质量；先用 Prompt Preview 验证研究框架，再在隔离环境试装。

### 30 秒判断

- **现在怎么做**：先做研究框架试用
- **最小安全下一步**：先用 Prompt Preview 验证研究框架；满意后再隔离试装
- **先别相信**：研究结论、引用和实验结果不能在安装前相信。
- **继续会触碰**：研究判断、命令执行、宿主 AI 配置

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86
- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`packages/cli/src/skills/analytics/SKILL.md`, `packages/cli/src/skills/dbt_ingest/SKILL.md`, `packages/cli/src/skills/historic_sql_patterns/SKILL.md`, `packages/cli/src/skills/historic_sql_table_digest/SKILL.md` 等 Claim：`clm_0004` supported 0.86
- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`packages/cli/src/skills/analytics/SKILL.md`, `packages/cli/src/skills/dbt_ingest/SKILL.md`, `packages/cli/src/skills/historic_sql_patterns/SKILL.md`, `packages/cli/src/skills/historic_sql_table_digest/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86

### 现在还不能相信

- **研究结论、引用和实验结果不能在安装前相信。**（unverified）：研究 Skill 可以组织问题和路径，但不能替代真实资料检索、论文核验和实验复现。
- **是否适合你的具体研究领域不能直接相信。**（unverified）：Skill 覆盖很多研究主题，不代表对你的领域、资料要求和可信度标准足够。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`, `packages/cli/src/skills/analytics/SKILL.md`, `packages/cli/src/skills/dbt_ingest/SKILL.md`, `packages/cli/src/skills/historic_sql_patterns/SKILL.md` 等
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。

### 继续会触碰什么

- **研究判断**：问题拆解、资料路径、实验路径、结论结构和可信度判断。 原因：研究型 Skill 可能让输出看起来更专业，但不能替代真实证据核验。
- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `packages/cli/src/skills/analytics/SKILL.md`, `packages/cli/src/skills/dbt_ingest/SKILL.md`, `packages/cli/src/skills/historic_sql_patterns/SKILL.md` 等
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：先验证它能否正确界定研究问题和证据边界，不要先相信研究输出。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。
- **保留资料和结论核验清单**：如果后续发现引用或实验路径不可靠，可以回到证据边界阶段重新校验。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`packages/cli/src/skills/analytics/SKILL.md`, `packages/cli/src/skills/dbt_ingest/SKILL.md`, `packages/cli/src/skills/historic_sql_patterns/SKILL.md`, `packages/cli/src/skills/historic_sql_table_digest/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86

### 上下文规模

- 文件总数：1530
- 重要文件覆盖：40/1530
- 证据索引条目：79
- 角色 / Skill 条目：15

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 ktx 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 ktx 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 ktx 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 15 个角色 / Skill / 项目文档条目。

- **ktx-analytics**（skill）：Use when answering a question that needs data from a ktx-connected database - investigating, analyzing, "how many", "show me", "what's the breakdown of", finding records by value, exploring tables, comparing periods, explaining metrics, or any data-analysis request. Triggers even when the user does not say "analytics"; if the answer requires querying a configured ktx connection, this skill applies. 激活提示：当用户任务与“ktx-analytics”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/analytics/SKILL.md`
- **dbt_ingest**（skill）：Map dbt schema.yml / properties.yml models and sources into ktx semantic-layer overlays and column notes. Covers sources: vs models: , column data tests not null, unique, accepted values, relationships , and how bundle-time writes complement manifest backfill from git sync. Load when the WorkUnit's skillNames includes dbt ingest or when raw files are dbt YAML under models/ / sources/ . 激活提示：当用户任务与“dbt_ingest”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/dbt_ingest/SKILL.md`
- **historic_sql_patterns**（skill）：Identify recurring cross-table historic-SQL analytical intents from a bounded pattern shard and emit typed pattern evidence for deterministic wiki projection. 激活提示：当用户任务与“historic_sql_patterns”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/historic_sql_patterns/SKILL.md`
- **historic_sql_table_digest**（skill）：Convert one changed historic-SQL table usage bucket into typed table usage evidence for deterministic schema projection. 激活提示：当用户任务与“historic_sql_table_digest”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/historic_sql_table_digest/SKILL.md`
- **ingest_triage**（skill）：Classify and resolve conflicts detected during bundle ingest structural duplicates, definitional contradictions, near-duplicate clusters, re-ingest changes, evictions . 激活提示：当用户任务与“ingest_triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/ingest_triage/SKILL.md`
- **live_database_ingest**（skill）：Capture semantic-layer and knowledge updates from a live database schema snapshot. 激活提示：当用户任务与“live_database_ingest”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/live_database_ingest/SKILL.md`
- **looker_ingest**（skill）：Extract durable ktx knowledge and semantic-layer contribution proposals from staged Looker runtime dashboard, Look, and explore JSON. Load for WorkUnits whose raw files are under explores/, dashboards/, or looks/. 激活提示：当用户任务与“looker_ingest”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/looker_ingest/SKILL.md`
- **lookml_ingest**（skill）：Map a LookML view/model/explore into ktx semantic layer sources. Covers the LookML to ktx primitive table, provenance tagging, and three worked examples overlay, standalone from derived table, standalone with sql always where . Load when the turn contains .lkml content. 激活提示：当用户任务与“lookml_ingest”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/lookml_ingest/SKILL.md`
- **metabase_ingest**（skill）：Convert Metabase questions, models, and metrics into ktx Semantic Layer source definitions. Covers result-metadata to KSL column type mapping, FK/PK detection, near-duplicate deduplication, pre-aggregation decomposition, join-graph connectivity, and how to react to priorProvenance from earlier ingest syncs. Load when the WorkUnit contains cards/ .json files under a Metabase bundle. 激活提示：当用户任务与“metabase_ingest”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/metabase_ingest/SKILL.md`
- **metricflow_ingest**（skill）：Map a MetricFlow semantic model or metric into ktx semantic layer sources. Covers the MetricFlow to ktx primitive table, extends: inheritance flattening, metric-type handling simple / derived / ratio / cumulative / conversion , model: ref 'x' resolution, and four worked examples. Load when the turn contains .yml / .yaml files with top-level semantic models: or metrics: . 激活提示：当用户任务与“metricflow_ingest”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/metricflow_ingest/SKILL.md`
- **notion_synthesize**（skill）：Synthesize durable ktx wiki pages and semantic-layer sources from staged Notion pages, databases, data-source rows, and clustered Notion evidence. Load when a WorkUnit contains Notion raw files or Notion evidence chunks. 激活提示：当用户任务与“notion_synthesize”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/notion_synthesize/SKILL.md`
- **sl**（skill）：ktx's semantic layer - a structured catalog of sources tables/views , measures, joins, and segments expressed as YAML. Covers the schema and how to query it via sl query . Use when the task involves querying pre-defined metrics ARR, churn, retention, LTV, MAU or reading SL source YAML to understand the catalog. Capture is handled by the sl capture skill memory-agent only . 激活提示：当用户任务与“sl”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/sl/SKILL.md`
- **sl_capture**（skill）：How to capture new reusable patterns into ktx's semantic layer - when a measure, segment, or join belongs in the catalog and how to write it generically so it stays small and useful over time. Loaded by the post-turn memory-agent only. The research agent does not write to the SL. 激活提示：当用户任务与“sl_capture”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/sl_capture/SKILL.md`
- **wiki_capture**（skill）：ktx's knowledge base - wiki pages for durable, reusable business knowledge. Covers capture workflow for user preferences, metric definitions, organizational conventions, and cross-references between wiki pages and semantic-layer sources. Loaded by the post-turn memory-agent only. The research agent reads wiki via wiki read / wiki search but does not write it. 激活提示：当用户任务与“wiki_capture”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/skills/wiki_capture/SKILL.md`
- **ktx**（skill）：Installs and configures ktx, the open-source context layer for data agents — runs ktx setup non-interactively with hidden CLI flags, configures database connections and embeddings, installs agent integration, and verifies readiness. Use when the user asks an agent to add ktx to a project, connect data sources, install agent rules, ingest schema, or troubleshoot a local ktx install. 激活提示：当用户任务与“ktx”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/ktx/SKILL.md`

## 证据索引

- 共索引 79 条证据。

- **Why ktx**（documentation）：Quickstart · CLI Reference · Agent Setup · Slack 证据：`README.md`
- **ktx examples**（documentation）：local-warehouse/ is a contributor fixture for local CLI smoke tests. It uses the internal fake ingest adapter so tests can exercise memory-flow behavior without a live database or external service. 证据：`examples/README.md`
- **local-warehouse fixture**（documentation）：This directory is a contributor fixture for ktx CLI smoke tests. It uses the internal fake ingest adapter so tests can run without a live database or external service. 证据：`examples/local-warehouse/README.md`
- **Orbit-style relationship discovery verification**（documentation）：Orbit-style relationship discovery verification 证据：`examples/orbit-relationship-verification/README.md`
- **Package artifact smoke checks**（documentation）：The package artifact smoke checks create temporary projects instead of storing sample projects in this directory. Run the checks from ktx/ : 证据：`examples/package-artifacts/README.md`
- **ktx-daemon**（documentation）：ktx-daemon is the portable Python compute package for ktx . 证据：`python/ktx-daemon/README.md`
- **Package**（package_manifest）：{ "name": "ktx-docs", "version": "0.0.0", "private": true, "type": "module", "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "test": "node --test tests/ .test.mjs" }, "dependencies": { "@xyflow/react": "^12.10.2", "fumadocs-core": "16.8.10", "fumadocs-mdx": "15.0.7", "fumadocs-ui": "16.8.10", "html-to-image": "1.11.11", "next": "^16", "react": "19.2.6", "react-dom": "19.2.6" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^25.9.1", "@types/react": "^19", "@types/react-dom": "^19", "tailwindcss": "^4", "typescript": "^6.0" } } 证据：`docs-site/package.json`
- **Package**（package_manifest）：{ "name": "ktx-workspace", "version": "0.13.1", "description": "Workspace root for ktx packages", "private": true, "type": "module", "packageManager": "pnpm@11.4.0", "engines": { "node": " =22.0.0", "pnpm": " =10.20.0" }, "scripts": { "artifacts:build": "node scripts/package-artifacts.mjs build", "artifacts:build-runtime": "node scripts/package-artifacts.mjs build-runtime", "artifacts:check": "node scripts/package-artifacts.mjs check", "artifacts:live-db-smoke": "node scripts/installed-live-database-smoke.mjs", "artifacts:verify": "node scripts/package-artifacts.mjs verify", "artifacts:verify-demo": "node scripts/package-artifacts.mjs verify-demo", "artifacts:verify-manifest": "node scripts… 证据：`package.json`
- **Package**（package_manifest）：{ "name": "@kaelio/ktx", "version": "0.13.1", "description": "Standalone ktx context layer for data agents", "author": { "name": "Kaelio", "url": "https://www.kaelio.com" }, "type": "module", "engines": { "node": " =22.0.0" }, "bin": { "ktx": "./dist/bin.js" }, "main": "dist/index.js", "types": "dist/index.d.ts", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "default": "./dist/index.js" }, "./package.json": "./package.json" }, "files": "dist", "assets" , "publishConfig": { "access": "public", "provenance": true }, "scripts": { "assets:demo": "node scripts/build-demo-assets.mjs", "build": "tsc -p tsconfig.json && node dist/telemetry/schema-writer.js src/telem… 证据：`packages/cli/package.json`
- **ktx Development Notes**（documentation）：ktx is a standalone open-source context layer for data agents. These instructions apply to all agents working in this repository Codex, Claude, Gemini, and similar tools . Do not assume an external app server, frontend, database migrations, ORPC contracts, or python-service/ layout exist here. 证据：`AGENTS.md`
- **Semantic Layer Engine**（documentation）：Python semantic layer that generates SQL from structured JSON queries. No from clause - sources are inferred from fully-qualified field names source.column . 证据：`python/ktx-sl/AGENTS.md`
- **Contributing to ktx**（documentation）：Thanks for your interest in ktx . This page covers how to contribute and the contributor rewards program . For development setup, repository layout, and verification commands, see the Contributing guide in the docs https://docs.kaelio.com/ktx/docs/community/contributing . 证据：`CONTRIBUTING.md`
- **ktx Analytics Workflow**（skill_instruction）：You have access to ktx MCP tools for data discovery, semantic-layer analysis, raw read-only SQL, wiki context, and memory ingest. Follow this workflow. 证据：`packages/cli/src/skills/analytics/SKILL.md`
- **dbt → ktx bundle ingest**（skill_instruction）：Use this skill for uploaded dbt projects dbt project.yml at stage root, models/ , sources/ , schema.yml . There is no fetch in v1 - scheduled dbt parse / manifest.json pulls are out of scope; host-provided dbt sync may still backfill structured test metadata into schema on the next sync. 证据：`packages/cli/src/skills/dbt_ingest/SKILL.md`
- **Historic SQL Patterns**（skill_instruction）：Use this skill when the WorkUnit raw file is a patterns-input/part-0001.json style shard from the historic-sql adapter. Older staged bundles may still provide root patterns-input.json ; when that is the WorkUnit raw file, read it the same way. 证据：`packages/cli/src/skills/historic_sql_patterns/SKILL.md`
- **Historic SQL Table Digest**（skill_instruction）：Use this skill when the WorkUnit raw file is one tables/ . .json file from the historic-sql adapter. 证据：`packages/cli/src/skills/historic_sql_table_digest/SKILL.md`
- **Ingest Triage - conflict classification and resolution**（skill_instruction）：Ingest Triage - conflict classification and resolution 证据：`packages/cli/src/skills/ingest_triage/SKILL.md`
- **Live Database Ingest**（skill_instruction）：Use this skill when the ingest work unit contains raw files under raw-sources/ /live-database/ / . 证据：`packages/cli/src/skills/live_database_ingest/SKILL.md`
- **Looker Runtime Ingest**（skill_instruction）：Looker runtime ingest turns API-staged dashboards, Looks, and explores into durable ktx memory. Runtime entities are evidence. They are not themselves the final knowledge shape. 证据：`packages/cli/src/skills/looker_ingest/SKILL.md`
- **LookML to ktx Semantic Layer**（skill_instruction）：LookML views map to SL sources, measure: to measures, explore: { join: } to the join graph. This skill lays out the mapping and the three capture shapes. 证据：`packages/cli/src/skills/lookml_ingest/SKILL.md`
- **Metabase to ktx Semantic Layer**（skill_instruction）：Each WorkUnit represents one Metabase collection's cards for one Metabase database mapped to exactly one ktx connection . Every cards/ .json file carries the resolved SQL, result metadata, card type, collection path, and referenced-card ids. The WU's sync-config.json tells you which sync mode is active and which selections apply. databases/ .json tells you the target ktx connection. 证据：`packages/cli/src/skills/metabase_ingest/SKILL.md`
- **MetricFlow to ktx Semantic Layer**（skill_instruction）：A MetricFlow semantic model maps to an SL source; MetricFlow measures map to ktx measures; MetricFlow entities map to ktx joins ; MetricFlow metrics top-level map to ktx measures OR to cross-model derived measures. Files in one WorkUnit are ALWAYS part of the same logical entity a connected component, possibly spanning extends: + cross-model metric refs . Flatten inheritance and cross-file references at write time. 证据：`packages/cli/src/skills/metricflow_ingest/SKILL.md`
- **Notion Cluster Synthesis**（skill_instruction）：Use this skill when a WorkUnit contains staged Notion content from pages/ , databases/ , data-sources/ , or clustered Notion evidence. 证据：`packages/cli/src/skills/notion_synthesize/SKILL.md`
- **Semantic Layer**（skill_instruction）：ktx's semantic layer SL is a structured catalog. Each source represents a table, a SQL view, or an overlay that enriches a manifest-backed table with measures, computed columns, joins, and named segments. The catalog is the single source of truth for reusable business metrics. 证据：`packages/cli/src/skills/sl/SKILL.md`
- **Semantic Layer - Capture**（skill_instruction）：This skill covers when and how to capture new patterns into the semantic layer. For schema reference and query grammar, load the sl skill first. 证据：`packages/cli/src/skills/sl_capture/SKILL.md`
- **Wiki Capture**（skill_instruction）：The knowledge base stores durable, reusable business knowledge for an analytics assistant. Each page is a self-contained rule, definition, or convention that answers "how should this concept be handled in this organization?" - written once and reused across chats. 证据：`packages/cli/src/skills/wiki_capture/SKILL.md`
- **ktx**（skill_instruction）：Install and configure ktx , the open-source context layer for data agents. Use this skill when a user wants an agent to add ktx to a project, connect data sources, build initial context, install agent integration, or troubleshoot a local ktx setup. 证据：`skills/ktx/SKILL.md`
- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`
- **ktx Code-Design Principles**（documentation）：Principles agents must apply when writing or changing behavior in this repository. These rules carry the same weight as the MUST / MUST NOT rules in AGENTS.md . 证据：`docs/code-design.md`
- **ktx release runbook**（documentation）：This runbook covers the maintainer workflow for publishing @kaelio/ktx to npm through GitHub Actions. The workflow uses semantic-release to choose the next version, update release metadata in the CI workspace, publish the package, and create the GitHub release. No files are ever committed back to the repository — the git tag and the published npm artifact are the source of truth for any released version. 证据：`docs/release.md`
- **ktx Terminology Rules**（documentation）：Canonical vocabulary for coding agents working on this repository. Applies to docs prose, code comments, identifiers, CLI strings, error messages, log lines, and example output. 证据：`docs/terminology.md`
- **Events.Schema**（structured_config）：{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ktx telemetry events", "type": "object", "additionalProperties": false, "x-ktx-common-fields": "cliVersion", "nodeVersion", "osPlatform", "osRelease", "arch", "runtime", "isCi" , "x-ktx-catalog": { "name": "install first run", "description": "Emitted once when ~/.ktx/telemetry.json is created.", "fields": }, { "name": "command", "description": "Emitted once for each Commander action that reaches preAction.", "fields": "commandPath", "durationMs", "outcome", "errorClass", "errorDetail", "flagsPresent", "hasProject", "projectGroupAttached" }, { "name": "setup step", "description": "Emitted after an interactive setup step c… 证据：`packages/cli/src/telemetry/events.schema.json`
- **Events.Schema**（structured_config）：{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ktx telemetry events", "type": "object", "additionalProperties": false, "x-ktx-common-fields": "cliVersion", "nodeVersion", "osPlatform", "osRelease", "arch", "runtime", "isCi" , "x-ktx-catalog": { "name": "install first run", "description": "Emitted once when ~/.ktx/telemetry.json is created.", "fields": }, { "name": "command", "description": "Emitted once for each Commander action that reaches preAction.", "fields": "commandPath", "durationMs", "outcome", "errorClass", "errorDetail", "flagsPresent", "hasProject", "projectGroupAttached" }, { "name": "setup step", "description": "Emitted after an interactive setup step c… 证据：`python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json`
- **Completion Commands**（source_file）：import { Argument, type Command } from '@commander-js/extra-typings'; import type { KtxCliCommandContext } from '../cli-program.js'; import { computeCompletions } from '../completion/complete-engine.js'; import { completionScript } from '../completion/completion-scripts.js'; import { createProjectCompletionProviders } from '../completion/dynamic-candidates.js'; import { profileMark } from '../startup-profile.js'; ⋮---- export function registerCompletionCommands program: Command, context: KtxCliCommandContext : void 证据：`packages/cli/src/commands/completion-commands.ts`
- **Connection Commands**（source_file）：import { type Command } from '@commander-js/extra-typings'; import { type KtxCliCommandContext, resolveCommandProjectDir } from '../cli-program.js'; import type { KtxConnectionArgs } from '../connection.js'; import { profileMark } from '../startup-profile.js'; import { resolveConnectionSelection } from './connection-selection.js'; ⋮---- async function runConnectionArgs context: KtxCliCommandContext, args: KtxConnectionArgs : Promise export function registerConnectionCommands program: Command, context: KtxCliCommandContext, commandName = 'connection' : void 证据：`packages/cli/src/commands/connection-commands.ts`
- **Connection Selection**（source_file）：export type ConnectionSelection = { kind: 'all' } { kind: 'single'; connectionId: string }; export interface ResolveConnectionSelectionInput { connectionId?: string undefined; all: boolean; } export function resolveConnectionSelection input: ResolveConnectionSelectionInput : ConnectionSelection 证据：`packages/cli/src/commands/connection-selection.ts`
- **Ingest Commands**（source_file）：import { type Command, Option } from '@commander-js/extra-typings'; import { collectOption, type KtxCliCommandContext, parsePositiveIntegerOption, resolveCommandProjectDir, } from '../cli-program.js'; import type { KtxCliDeps, KtxCliIo } from '../index.js'; import { runtimeInstallPolicyFromFlags } from '../managed-python-command.js'; import type { KtxPublicIngestArgs } from '../public-ingest.js'; import { profileMark } from '../startup-profile.js'; import type { KtxTextIngestArgs } from '../text-ingest.js'; import { resolveConnectionSelection } from './connection-selection.js'; ⋮---- interface IngestCommandOptions { runTextIngest: args: KtxTextIngestArgs, io: KtxCliIo, deps: KtxCliDeps = Pr… 证据：`packages/cli/src/commands/ingest-commands.ts`
- **Knowledge Commands**（source_file）：import { type Command, Option } from '@commander-js/extra-typings'; import { type CommandWithGlobalOptions, type KtxCliCommandContext, parsePositiveIntegerOption, resolveCommandProjectDir, } from '../cli-program.js'; import type { KtxKnowledgeArgs } from '../knowledge.js'; import { profileMark } from '../startup-profile.js'; ⋮---- async function runKnowledgeArgs context: KtxCliCommandContext, args: KtxKnowledgeArgs : Promise function isDebugEnabled command: CommandWithGlobalOptions : boolean export function registerWikiCommands program: Command, context: KtxCliCommandContext : void 证据：`packages/cli/src/commands/knowledge-commands.ts`
- **Mcp Commands**（source_file）：import { spawn } from 'node:child process'; import { readFile } from 'node:fs/promises'; import { fileURLToPath } from 'node:url'; import { Command } from '@commander-js/extra-typings'; import type { KtxCliCommandContext } from '../cli-program.js'; import { collectOption, parsePositiveIntegerOption, resolveCommandProjectDir, } from '../cli-program.js'; import { mcpDaemonLayout, readKtxMcpDaemonStatus, startKtxMcpDaemon, stopKtxMcpDaemon, } from '../managed-mcp-daemon.js'; import { buildMcpSecurityConfig, runKtxMcpHttpServer } from '../mcp-http-server.js'; import { runKtxMcpStdioServer } from '../mcp-stdio-server.js'; function tokenFromOption value: string undefined : string undefined functi… 证据：`packages/cli/src/commands/mcp-commands.ts`
- **Setup Commands**（source_file）：import { type Command, InvalidArgumentError, Option } from '@commander-js/extra-typings'; import type { KtxCliCommandContext } from '../cli-program.js'; import { resolveCommandProjectDir } from '../cli-program.js'; import type { KtxSetupDatabaseDriver } from '../setup-databases.js'; import { isKtxSetupLlmBackend, type KtxSetupLlmBackend } from '../setup-models.js'; import type { KtxSetupSourceType } from '../setup-sources.js'; async function runSetupArgs context: KtxCliCommandContext, args: Parameters 0 , function positiveInteger value: string : number function embeddingBackend value: string : 'openai' 'sentence-transformers' function llmBackend value: string : KtxSetupLlmBackend function d… 证据：`packages/cli/src/commands/setup-commands.ts`
- **Main**（source_file）：def build parser - argparse.ArgumentParser ⋮---- parser = argparse.ArgumentParser prog="ktx-daemon" subcommands = parser.add subparsers dest="command", required=True ⋮---- serve http = subcommands.add parser ⋮---- def read stdin json - dict str, Any ⋮---- raw = sys.stdin.read parsed = json.loads raw ⋮---- def install serve http exception hooks started at: float - Callable , None ⋮---- original hook = sys.excepthook ⋮---- def dispose - None ⋮---- def report serve http crash error: BaseException, , started at: float - None ⋮---- started at = time.perf counter dispose hooks = install serve http exception hooks started at ⋮---- def main argv: list str None = None - int ⋮---- parser = build pars… 证据：`python/ktx-daemon/src/ktx_daemon/__main__.py`
- **Determine source type**（source_file）：logger = logging.getLogger name CONSTANT RE = re.compile r"@\{ \w+ \}" TABLE REF RE = re.compile r"^\s \$\{TABLE\}\. \w+ \s $" FIELD REF RE = re.compile r"\$\{ \w+ \}" VIEW FIELD REF RE = re.compile r"\$\{ \w+ \. \w+ \}" LIQUID RE = re.compile r"\{%. ?%\}" AGGREGATE FUNC RE = re.compile LOOKML TYPE MAP: dict str, str = { MEASURE TYPE MAP: dict str, str = { class LookMLFileInput BaseModel ⋮---- path: str content: str class ParseLookMLRequest BaseModel ⋮---- files: list LookMLFileInput constant overrides: dict str, str None = None dialect: str = "postgres" class SkippedItem BaseModel ⋮---- name: str item type: str reason: str class ParsedColumn BaseModel ⋮---- lookml name: str type: str role:… 证据：`python/ktx-daemon/src/ktx_daemon/lookml.py`
- **Semantic Layer**（source_file）：class SemanticLayerQueryRequest BaseModel ⋮---- model config = ConfigDict extra="forbid" sources: list dict str, Any query: dict str, Any dialect: str = "postgres" project id: str None = Field default=None, alias="projectId" class SemanticLayerQueryResponse BaseModel ⋮---- sql: str dialect: str columns: list dict str, Any plan: dict str, Any class ValidateSourcesRequest BaseModel ⋮---- recently touched: list str None = None class ValidateSourcesResponse BaseModel ⋮---- valid: bool errors: list str = Field default factory=list warnings: list str = Field default factory=list per source warnings: dict str, list str = Field default factory=dict def load sources raw sources: list dict str, Any -… 证据：`python/ktx-daemon/src/ktx_daemon/semantic_layer.py`
- **Source Generation**（source_file）：logger = logging.getLogger name NUMBER PATTERN = re.compile TIME PATTERN = re.compile BOOLEAN PATTERN = re.compile r"bool boolean bit", re.IGNORECASE ID PATTERN = re.compile RELATIONSHIP MAP = { RELATIONSHIP INVERSE = { class ColumnInput BaseModel ⋮---- name: str type: str primary key: bool = False nullable: bool = True comment: str None = None class TableInput BaseModel ⋮---- catalog: str None = None db: str None = None ⋮---- columns: list ColumnInput class LinkInput BaseModel ⋮---- from table: str from column: str to table: str to column: str relationship type: str class GenerateSourcesRequest BaseModel ⋮---- tables: list TableInput links: list LinkInput dialect: str = "postgres" class Ge… 证据：`python/ktx-daemon/src/ktx_daemon/source_generation.py`
- **Events**（source_file）：SCHEMA PATH = Path file .with name "events.schema.json" COMMON FIELDS = { DAEMON EVENTS = { def schema catalog - dict str, set str ⋮---- raw = json.loads SCHEMA PATH.read text encoding="utf-8" ⋮---- EVENT FIELDS = schema catalog def common envelope - dict str, Any def build telemetry event name: str, fields: dict str, Any - dict str, Any ⋮---- allowed = EVENT FIELDS.get name ⋮---- extra = set fields - allowed ⋮---- missing = { 证据：`python/ktx-daemon/src/ktx_daemon/telemetry/events.py`
- **Main**（source_file）：def dump schema - None 证据：`python/ktx-sl/semantic_layer/__main__.py`
- **Security Policy**（documentation）：If you believe you've found a security vulnerability in ktx , please report it privately through GitHub Security Advisories: 证据：`SECURITY.md`
- **Test Lookml**（source_file）：ORDER VIEW = """ USER VIEW = """ ORDER MODEL = """ DERIVED VIEW = """ def test parse lookml project returns views and joins - None ⋮---- response = parse lookml project views = {view.name: view for view in response.views} ⋮---- def test parse lookml project extracts derived table columns - None ⋮---- view = response.views 0 证据：`python/ktx-daemon/tests/test_lookml.py`
- **Test Semantic Layer**（source_file）：ORDERS SOURCE = { def test query semantic layer generates sql and plan - None ⋮---- response = query semantic layer ⋮---- identity path = tmp path / ".ktx" / "telemetry.json" ⋮---- captured = capsys.readouterr ⋮---- def test query semantic layer reports exception monkeypatch - None ⋮---- reports: list dict str, object = def fake report exception: BaseException, kwargs: object - None ⋮---- def test semantic layer request rejects project id field name - None def test validate semantic layer reports duplicate measure names - None ⋮---- invalid source = { response = validate semantic layer 证据：`python/ktx-daemon/tests/test_semantic_layer.py`
- **Test Source Generation**（source_file）：def test generate sources maps tables columns measures and joins - None ⋮---- response = generate sources response ⋮---- sources = {source "name" : source for source in response.sources} ⋮---- def test generate sources aliases multiple joins to same table - None ⋮---- sources = generate sources orders = next source for source in sources if source "name" == "orders" 证据：`python/ktx-daemon/tests/test_source_generation.py`
- **Revenue**（documentation）：Revenue is paid order amount after refund adjustments. 证据：`examples/local-warehouse/wiki/global/revenue.md`
- **Activation Policy Decision Record**（documentation）：Policy Change Anchor: notion://notion page activation policy decision policy-change 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/activation-policy-decision-record.md`
- **Analyst Onboarding**（documentation）：Operating Context Anchor: notion://notion page analyst onboarding analyst-onboarding 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/analyst-onboarding.md`
- **ARR and Contract Reporting Notes**（documentation）：ARR Contract First Anchor: notion://notion page arr contract reporting arr-contract-first 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/arr-and-contract-reporting-notes.md`
- **Customer Health Playbook**（documentation）：Risk Definition Anchor: notion://notion page customer health playbook risk-definition 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/customer-health-playbook.md`
- **Retention and NRR Definition Notes**（documentation）：NRR Definition Anchor: notion://notion page retention policy current nrr-definition 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/retention-and-nrr-definition-notes.md`
- **Revenue Reporting Policy**（documentation）：Gross Revenue Anchor: notion://notion page revenue reporting policy gross-revenue 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/revenue-reporting-policy.md`
- **Sales Ops Segmentation Guide**（documentation）：Growth Plan Normalization Anchor: notion://notion page sales ops segmentation growth-plan-normalization 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/sales-ops-segmentation-guide.md`
- **Support Escalation Runbook**（documentation）：Operating Context Anchor: notion://notion page support escalation runbook support-escalation-runbook 证据：`packages/cli/assets/demo/orbit/raw-sources/notion/support-escalation-runbook.md`
- **Customer Update Communication Standard**（documentation）：Customer Update Communication Standard 证据：`packages/cli/assets/demo/orbit/wiki/global/customer-communication-policy.md`
- 其余 19 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `examples/README.md`, `examples/local-warehouse/README.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `examples/README.md`, `examples/local-warehouse/README.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概览**：importance `high`
  - source_paths: README.md, package.json, packages/cli/package.json, pnpm-workspace.yaml, pyproject.toml
- **Src 模块**：importance `high`
  - source_paths: python/ktx-daemon/src/ktx_daemon/__init__.py, python/ktx-daemon/src/ktx_daemon/__main__.py, python/ktx-daemon/src/ktx_daemon/app.py, python/ktx-daemon/src/ktx_daemon/code_execution.py, python/ktx-daemon/src/ktx_daemon/database_introspection.py
- **Agents 模块**：importance `high`
  - source_paths: skills/ktx/agents/openai.yaml
- **Commands 模块**：importance `high`
  - source_paths: packages/cli/src/commands/completion-commands.ts, packages/cli/src/commands/connection-commands.ts, packages/cli/src/commands/connection-selection.ts, packages/cli/src/commands/ingest-commands.ts, packages/cli/src/commands/knowledge-commands.ts

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `89f25435d5c3ddfe650b6d8b39c3ae4c472cb0dd`
- inspected_files: `README.md`, `package.json`, `pnpm-lock.yaml`, `pyproject.toml`, `uv.lock`, `docs/code-design.md`, `docs/release.md`, `docs/terminology.md`, `examples/README.md`, `examples/local-warehouse/README.md`, `examples/local-warehouse/ktx.yaml`, `examples/local-warehouse/semantic-layer/warehouse/orders.yaml`, `examples/local-warehouse/source/orders/orders.json`, `examples/local-warehouse/wiki/global/revenue.md`, `examples/orbit-relationship-verification/README.md`, `examples/orbit-relationship-verification/ktx.yaml`, `examples/package-artifacts/README.md`, `examples/postgres-historic/README.md`, `examples/postgres-historic/docker-compose.yml`, `packages/cli/assets/demo/orbit/links/provenance.json`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 来源证据：Add MongoDB connector

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add MongoDB connector
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | https://github.com/Kaelio/ktx/issues/305 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 失败模式：security_permissions: Add Sigma context source

- Trigger: Developers should check this security_permissions risk before relying on the project: Add Sigma context source
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Add Sigma context source. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may expose sensitive permissions or credentials: Add Sigma context source
- Evidence: failure_mode_cluster:github_issue | https://github.com/Kaelio/ktx/issues/168 | Add Sigma context source
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 来源证据：Add Amazon Redshift connector

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Amazon Redshift connector
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | https://github.com/Kaelio/ktx/issues/161 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 来源证据：Add Confluence context source

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Confluence context source
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | https://github.com/Kaelio/ktx/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 来源证据：Add Jira context source

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Jira context source
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | https://github.com/Kaelio/ktx/issues/174 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 来源证据：Add Sigma context source

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Sigma context source
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | https://github.com/Kaelio/ktx/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 失败模式：installation: v0.12.0

- Trigger: Developers should check this installation risk before relying on the project: v0.12.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.12.0. Context: Observed when using python
- Why it matters: Upgrade or migration may change expected behavior: v0.12.0
- Evidence: failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.12.0 | v0.12.0
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 失败模式：installation: v0.13.0

- Trigger: Developers should check this installation risk before relying on the project: v0.13.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.13.0. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v0.13.0
- Evidence: failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.13.0 | v0.13.0
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 失败模式：installation: v0.6.0

- Trigger: Developers should check this installation risk before relying on the project: v0.6.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.0. Context: Observed when using node, windows
- Why it matters: Upgrade or migration may change expected behavior: v0.6.0
- Evidence: failure_mode_cluster:github_release | https://github.com/Kaelio/ktx/releases/tag/v0.6.0 | v0.6.0
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 可能修改宿主 AI 配置

- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Evidence: capability.host_targets | https://github.com/Kaelio/ktx | host_targets=claude_code, claude, mcp_host
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。