karst

karst

了解你的更改会造成什么影响——而无需让代码离开你的设备。 karst 为任何 AI 编码工具——Cursor、Claude Desktop、自定义 Agent——提供代码库的本地映射。它会通过精确的 file:line 引用回答问题，并且遍历真实的调用／导入／继承关系图，计算更改的影响范围——也就是“如果我修改这里，还会有什么地方出问题？”——这是普通搜索和 Agent 式 grep 无法回答的问题。

它在本地运行，使用 MCP（因此可接入任何 Agent），并且不收集遥测数据：CLI 本身不会向任何地方发送任何内容。索引、搜索和影响分析都不会调用大模型。只有 karst ask 和 karst review 会调用大模型，而且仅限于你配置了大模型的情况。哪些内容会离开你的设备列出了所有情况。另外，按包检索可使每个问题的输入令牌减少 约 60%。

受监管、隔离网络或对 IP 敏感的团队？ karst 专为云端编码工具因架构限制而无法进入的环境打造——完全离线、不收集遥测数据，源代码可供审计。请从 哪些内容会离开你的设备和 合规与隔离网络工具包（证明文件、 网络出口流量表、预填的安全问卷、离线安装）开始。

uv tool install karst      # recommended — fast, and puts `karst` on PATH for you
# or
pipx install karst         # isolated install, also handles PATH
# or
pip install karst          # if `karst` isn't found after, use `python -m karst …`

uv 和 pipx 是最简单的选择，因为它们会自动将 karst 命令添加到你的 PATH。使用普通的 pip --user （尤其是 Microsoft Store Python）时，命令可能不会出现在 PATH 中——这种情况下， python -m karst … 始终可用，无需配置 PATH。

首次运行：会下载哪些内容

karst 自身的代码不会发起网络请求，但它的两个依赖项会在首次需要时获取文件。这些文件会缓存在磁盘上，因此每项只会下载一次。

1. Tree-sitter 解析器（tree-sitter-language-pack）。它的 wheel 不包含语法文件：首次使用某种语言时，会下载一个解析器包，并解压该语言的库。要获取 karst 当前会解析的六种语言，请在安装了 karst 的 Python 环境中运行一次：

   python -c "from tree_sitter_language_pack import get_parser; [get_parser(n) for n in ('python', 'javascript', 'typescript', 'go', 'rust', 'java')]"
   

   .tsx 文件使用 typescript 语法解析，因此没有单独的 tsx 条目。缓存按用户和 tree-sitter-language-pack 版本区分，而不是按虚拟环境区分，因此安装了相同版本的任何 Python 都会填充该缓存。这对 uv tool 和 pipx 安装很有帮助，因为 karst 会位于私有环境中。

2. 嵌入模型（BAAI/bge-small-en-v1.5，约 65 MB，来自 huggingface.co），会在首次运行 index、quickstart、ask、review 或 MCP search_code 时下载。在任意小型仓库中运行一次 karst quickstart 即可获取该模型，然后设置 KARST_OFFLINE=1 以禁止后续模型下载。

tree-sitter-language-pack 1.9.1（pyproject.toml 中锁定的版本）的解析器下载详情：

主机	GitHub 上 kreuzberg-dev/tree-sitter-language-pack 的 v1.9.1 版本发布页：包含一个清单、parsers.json 和一个适用于各平台的压缩包 parsers-<os>-<arch>.tar.zst（约 18-21 MB）。GitHub 会重定向到 xberg-io/tree-sitter-language-pack（该仓库的新名称），并从 release-assets.githubusercontent.com 提供压缩包。仅使用 HTTPS；支持 HTTPS_PROXY / ALL_PROXY。
完整性	压缩包的 SHA-256 会与清单中的值进行比对。不匹配时会引发 ChecksumMismatchError，且不会缓存任何内容。清单和压缩包来自同一版本发布，因此此检查可以发现下载损坏或被篡改的情况，但无法防范版本发布本身遭到入侵。不会进行签名检查，且解压后的库（原生代码，会加载到 karst 进程中）在后续运行时不会重新计算哈希值。
缓存	Linux ${XDG_CACHE_HOME:-~/.cache}/tree-sitter-language-pack/v1.9.1/libs，macOS ~/Library/Caches/tree-sitter-language-pack/v1.9.1/libs，Windows %LOCALAPPDATA%\tree-sitter-language-pack\v1.9.1\libs。运行 python -c "import tree_sitter_language_pack as t; print(t.cache_dir())" 可查看缓存路径。（Microsoft Store 版 Python 会将 Windows 文件夹保存在其自身的 LocalCache\Local 目录下。）
镜像 / 离线	TREE_SITTER_LANGUAGE_PACK_MANIFEST_URL（https:// 或 file:// URL）可替换清单 URL。对于与网络隔离的机器，请在一台操作系统和 CPU 架构相同且已联网的机器上运行上面的命令，然后将 libs 文件夹复制到相同路径。

运行过该命令一次后，analyze、graph-index 和 impact 不会发起网络请求。当某种语言的库已在缓存中时，解析器包会从磁盘加载该库，且不会连接 GitHub；六种语言的库都缓存后，即使没有清单、没有网络也能正常工作。只要该版本对应的缓存文件夹保持完整，此结论就成立：不同版本的 tree-sitter-language-pack 使用不同的缓存文件夹，因此会重新下载。

不要为此使用解析器包自身的 download([...])。在 1.9.1 中，对于解析器包已列出的语言，该方法会直接返回而不获取任何内容；实际执行获取操作的是 get_parser，karst 调用的正是它。KARST_OFFLINE=1 仅适用于嵌入模型，不适用于解析器。

解析器下载由解析器包的原生代码完成，而不是由 Python 完成。Python 层面的网络钩子（例如对 socket.socket 的 monkeypatch，或针对 socket.connect 的审计钩子）无法检测到这些请求，因此无法据此判断 karst 是否联网。请改用操作系统层面的检查方式：例如防火墙日志，或在 Linux 上使用 strace -f -e trace=network。

为什么

大多数“与代码库对话”工具会在每次提问时，向模型灌入数万个关联性模糊的令牌。你看不到加载了什么，无法限定范围，月底账单却会如期而至。karst 则反其道而行：

• 限定范围 — 按包过滤检索，读取约 200 个片段，而非 5,000 个。
• 提供引用 — 每个片段都带有准确的 file:line。核实，而非盲信。
• 预测影响 — 真实的调用／导入图可以回答“如果我改了这个，还有什么会出问题？”，单靠嵌入无法做到。

在一个真实的 246 个文件的 NestJS + Next.js 仓库上测得：已索引 906 个片段，增量重新索引耗时从 343s 降至 2.3s，使用 Sonnet 4.6 时每个问题约 $0.019（调用前显示），附加代码包后令牌减少 60%。

快速入门（CLI）

找不到 karst 命令？ 你的 Python Scripts 目录不在 PATH 中（Microsoft Store Python 用户很常见）。以下所有命令也可以通过 python -m karst … 运行，效果相同，无需设置 PATH。（或者通过 uv／pipx 安装，它们会自动将 karst 添加到 PATH。）

cd your-project

# one command: index + call/import graph + suggested packs
karst quickstart                 #  or:  python -m karst quickstart

# ask questions about the code (defaults to this folder's index)
karst ask "how does checkout charge the user?" --no-llm    # cited code, no API key
karst ask -i                     # interactive: ask many questions

# what breaks if I change a function? (run inside the project; it finds the graph itself)
karst impact --target checkout

# review a diff with severity-tagged, cited findings
karst review --staged --storage ~/.karst/indexes/<your-project>-<hash>   # the path quickstart prints

karst examples                   # a copy-paste cheatsheet of everything

karst quickstart 会打印准确的后续命令，并填入你的索引路径。设置了 ANTHROPIC_API_KEY／OPENAI_API_KEY 后，karst ask 会生成大模型回答，并将检索到的代码发送给对应服务提供商（参见哪些内容会离开你的设备）；添加 --no-llm 可获取带引用的片段，且不进行网络调用。下方的 MCP 服务也无需密钥——模型由你的 IDE 提供。

在 IDE 中使用（MCP）

karst 附带一个 MCP 服务（karst-mcp），通过标准输入／输出提供五种工具：search_code、find_impact、list_packs、index_status、index_repository。

Claude Desktop（claude_desktop_config.json）或 Cursor（.cursor/mcp.json）——选择你已有的启动方式：

{
  "mcpServers": {
    "karst": { "command": "uvx", "args": ["--from", "karst", "karst-mcp"] }
  }
}

uvx 无需预先安装任何内容——它会按需获取并运行 karst。如果已经安装，{ "command": "karst-mcp" } 也可以使用。如果完全没有 PATH，可使用 { "command": "python", "args": ["-m", "karst.mcp_server"] }。

重启宿主，然后像平常一样提问——它会在有帮助时调用 karst 的工具，并返回限定范围且带引用的上下文。完整设置说明见 docs/MCP.md。

指南

初次使用？从最适合你的指南开始：

• 为什么选择 karst？ — 用通俗易懂的语言介绍它是什么、适用于什么场景。如果你不确定它能解决什么问题，请先读这篇。
• 快速入门 — 5 分钟内从零开始提出实际问题，无需 API 密钥，并查看真实输出。
• 面向氛围编码者 — 在 Cursor／Claude Desktop 中使用 karst，无需执行 CLI 命令——只需聊天。
• 连接你的 AI 工具 — 为每种客户端复制粘贴 MCP 设置：Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Zed、JetBrains，以及网页应用。
• 自托管与隔离网络环境 — 使用本地模型，在你的设备上运行 karst 和 AI 回答。适用于代码不能上传到云端的团队。
• 实用指南 — 真实场景（新成员上手、影响范围分析、降低令牌成本、审查差异）的可复制粘贴命令。
• MCP 设置 — 将 karst 连接到任意 MCP 客户端。

工作原理

1. 索引 — tree-sitter 将每个函数、类和方法拆分为感知 AST 的代码块（Python、JS、TS、Go、Rust、Java）；代码块会嵌入本地 Qdrant 存储中。支持增量处理：SHA 清单和嵌入缓存会跳过未更改的文件。
2. 图谱 — 由 CALLS / IMPORTS / CONTAINS / IMPLEMENTS 边构成的 NetworkX 知识图谱，可用于影响分析（“哪些内容依赖于此项？”——包括哪些类实现了某个接口或继承了某个基类）。
3. 打包 — 将相关文件整理为可命名、可附加的上下文包（auth、billing）。查询只会加载对应的包。
4. 服务 — MCP 服务返回经过排序并附有 file:line 引用的代码块；宿主的模型会据此进行推理。

所有内容都在本地运行，并支持离线使用（FastEmbed/ONNX 嵌入、Qdrant 本地模式、sqlite 缓存——无需 Docker 或守护进程）。一次性下载以及所有可能连接网络的路径都列在下方。

哪些内容会离开你的设备

此 CLI 不包含遥测、分析、更新检查或回传功能，karst 自身的代码也不包含 HTTP 客户端。网络流量仅来自下方各行所列内容。它们要么是不会发送任何数据的一次性下载，要么是由你启动或配置的内容。

命令 / 标志	发送内容	发送至	发送时机
analyze、graph-index、impact、packs …、MCP find_impact / list_packs / index_status	无	—	从不。（analyze、graph-index 和 packs suggest 会解析代码，因此需要下一行所述的解析器。）
首次解析某种语言（analyze、graph-index、index、quickstart、packs suggest、MCP index_repository）	不会发送你的任何内容。只会下载 tree-sitter 解析器包，约 18-21 MB。和任何下载一样，GitHub 会看到你的 IP 地址。它由原生代码生成，因此 Python 层级的 socket 钩子无法检测到；请在操作系统层级监控。	github.com（重定向至 release-assets.githubusercontent.com）	每个解析器版本下载一次，除非已缓存。预先下载。
首次生成嵌入（index、quickstart、ask、review、MCP search_code / index_repository）	不会发送你的任何内容。会下载嵌入模型，约 65 MB。嵌入过程在本地运行。	通过 FastEmbed 和 huggingface_hub 访问 huggingface.co	下载一次，保存至 ~/.karst/models。KARST_OFFLINE=1 会阻止下载。
不带 --no-llm 的 ask	你的问题和检索到的代码块：默认取排名前 8 个，每个截取至 2,000 个字符；使用 --graph 时，还会附带最多 6 个图邻居。	Anthropic（api.anthropic.com）、OpenAI（api.openai.com）或你的本地模型服务	每次运行一次，前提是已配置提供商。如果未配置任何提供商，命令会报错并停止，不会发送任何内容。
review --staged / --base / --diff / --pr	对每个变更文件：其 diff 片段、每个片段最多 3 个包含该片段的代码块（各截取至 1,500 个字符），以及每个片段最多 3 个相似代码块（各截取至 800 个字符；--no-neighbors 会移除这些相似代码块）。	与 ask 相同的提供商规则。review 没有 --no-llm，因此始终需要大模型。	每次运行。
review --pr N	PR 编号和 --repo。会读取 PR diff。	通过你的 gh 命令行工具访问 GitHub，使用 gh 当前登录的账号	使用 --pr 时。
review --pr N --post-to-pr	一条 PR 评审，每项发现对应一条行内评论：严重程度、消息和建议的修复方案。	通过 gh api 访问 GitHub，使用你的 gh 账号。PR 上的所有人都能看到。	添加该标志时。不会出现确认提示。
karst-mcp（stdio 或 --http），任意工具	检索到的代码块和影响分析结果会返回给你的 MCP 客户端（Claude Desktop、Cursor、Claude Code 等）。karst 本身不会向外发送任何内容。	你的 MCP 客户端，通常会将工具结果转发给其自身的大模型提供商。	每次工具调用。客户端接下来会做什么由客户端决定，而非 karst。
karst-mcp --http	不会向外发送任何内容。它会向提供了 bearer token 的客户端提供已索引的代码。	默认监听 127.0.0.1:8080。如果未设置 KARST_MCP_TOKEN，它会拒绝启动；其工具只会读取 KARST_MCP_ROOTS 下的仓库（默认为工作目录）。KARST_MCP_HOST=0.0.0.0（或 --host）会将其开放给你的网络。	运行期间。

ask 和 review 使用哪个大模型：如果设置了 --llm（仅限 ask）或 KARST_LLM_PROVIDER，则使用该设置；否则，如果设置了 KARST_LLM_BASE_URL，则使用本地服务；否则，如果设置了 ANTHROPIC_API_KEY，则使用 Anthropic；否则，如果设置了 OPENAI_API_KEY，则使用 OpenAI。如果你的 shell 中已有供其他工具使用的 API 密钥，karst ask 就会将代码块发送给对应的提供商。 使用 --no-llm 获取带引用的代码块且不调用模型，或者使用 --llm local / KARST_LLM_PROVIDER=local 使用本地模型；本地服务 URL 默认为 http://localhost:11434/v1（Ollama），如果将 KARST_LLM_BASE_URL 指向远程主机，提示词就会发送到那里。Anthropic 和 OpenAI SDK 是可选扩展（karst[anthropic]、karst[openai]、karst[llm]）；仅执行 pip install karst 无法调用两者，而本地选项使用 openai 扩展。 向量存储（Qdrant）以嵌入式本地文件模式运行于 ~/.karst/indexes/；不支持远程 Qdrant 选项。嵌入模型缓存后，FastEmbed 会直接从磁盘加载，无需发起请求；设置 KARST_OFFLINE=1 后，模型缺失时会报错，而不会下载。模型下载通过 Hugging Face 的客户端库进行，该库有自己的使用遥测开关（HF_HUB_DISABLE_TELEMETRY=1）；此设置属于该库，而非 karst。

状态

已上线：AST 分块（支持 6 种语言）、调用/导入图谱与影响分析、按 pack 范围检索、Token 与成本计量、增量索引与嵌入缓存、带内联 PR 发布功能的差异代码审查（review --pr --post-to-pr），以及同时支持 stdio 和远程 Streamable-HTTP 的 MCP 服务（karst-mcp --http）。 即将推出：托管索引、团队共享 pack 库、自动化 GitHub PR 审查机器人，以及浏览器连接器（claude.ai / ChatGPT）的 OAuth。

许可证

Apache-2.0。参见 LICENSE。