内容
# CALM — 代码智能地图
[](LICENSE)
[](https://github.com/Eilodon/CALM/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@eilodon/calm-mcp)
**实时代码地图，让 AI 编程助手可以放心编辑代码**
真实的调用图，而非简单的向量相似性猜测。编译器验证的边，确保调用关系的准确性。写入路径上的安全防护，不仅仅是警告。
**新来者？** [快速开始](#quick-start) 让你在一分钟内开始使用 — 无需克隆，无需 Rust 工具链，支持 [Claude Code, VS Code, Cursor, Windsurf/Devin Desktop, Codex, Antigravity, 和 JetBrains](#quick-start)。 **比较工具？** 直接跳转到 [证明，而非承诺](#proof-not-promises)。 **想了解内部机制？** [`docs/architecture.md`](docs/architecture.md) 涵盖多层索引、SCIP/LSP 叠加系统、并发模型和卫生层等。
| | |
|---|---|
| **覆盖范围** | 24 种语言解析 · 13 种默认提供完整调用图（6 种零配置 + 7 种通过默认 `tier0-5` 捆绑包） · 12 种具有正式/编译器验证的升级路径 |
| **安全性** | 五个实时 MCP 服务器基准测试中，唯一拒绝未经确认的编辑的服务器 |
| **效率** | 在多文件任务中，比简单的读取文件基准少 29 倍至 241 倍的令牌数 ([基准](benchmarks/b4_token_efficiency/)) |
---
## 问题
AI 代理在编辑代码时，如果不知道调用函数的功能，可能会：
- 删除仍被其他文件调用的“死代码”。
- 更改签名时，忽略一半的调用站点。
- 重构一个看似次要的符号，却发现它实际上是整个模块的中心。
这不是推理失败，而是**可见性**失败：代理没有地图。
## 为什么是 CALM
大多数编程代理都像在不熟悉的代码库中使用 `grep` 一样操作：没有明确的代码结构感知，没有办法知道哪些代码与哪些代码有关。这不是自信，而是快速猜测。
CALM 代表 **代码智能地图（Coding Agent Liveness Map）**。 *实时*，因为地图永远不是一个静态快照 — 它会监视文件系统，当文件更改时增量重新索引，并在每次响应中报告其当前的新鲜度（`scanning → parsing → building_edges → ready`）。 *地图*，因为它是一个实际的图 — 调用边、导入边、中心/核心度量 — 而不是一个扁平的文本索引假装成一个。
## 您将获得
- **代理不再猜测谁依赖于什么。** `callers`/`callees`/`edit_context` 显示每个已知调用者，然后再进行更改。完整的树形调用图涵盖 **13 种语言**开箱即用：Python、TypeScript、JavaScript、Java、Rust 和 Go 零配置，另外 C、C++、C#、Ruby、PHP、Shell 和 R 通过默认的 `tier0-5` 语法捆绑包提供。十一款额外语言（Kotlin、Swift、Scala、Dart、Lua、Elixir、Haskell、OCaml、Zig、PowerShell、Groovy）通过选择加入 `--features lang-X` 构建标志解析，总共支持 24 种语言。
- **编辑不会默默地破坏。** 每次写入都会针对确切的行范围进行哈希验证，并在写入磁盘之前进行语法检查。中心和高扇入符号在代理审查调用者并明确确认之前，拒绝写入 — 只有具有实际依赖图的工具才能强制执行此策略。
- **每条边都告诉您其信任程度。** 调用边按置信度分级（`textual → inferred → resolved → formal`），当编译器可用时，CALM 会要求它检查图：SCIP 叠加层（`rust-analyzer`、`scip-go` 等）和实时 LSP 叠加层（`gopls`、`clangd`）将最佳猜测边升级为编译器验证的真实情况，涵盖 12 种语言。
- **代码库对自己进行评级。** `fitness_report` 将中心度、死代码、复杂度和架构边界违规转化为可查询、可强制执行的信号，而不是一次性审计 — `remember`/`recall` 在会话之间保存决策和经验。
## CALM 适合哪里
“AI 代理的代码智能”是一个新的类别，由开源先驱（Aider、Serena、Sourcegraph/Cody 等）构建，该类别证明了代理在具有实际代码结构支持的情况下比 grep 和良好意图表现更好。CALM 建立在该基础上，其重心不同：大多数工具在类别中**通知读取路径** — 更好的搜索、更好的导航、更好的上下文。CALM 还**保护写入路径**。相同的图回答“谁调用此？”并强制执行“您在修改之前查看”：预编辑上下文是强制性的，中心编辑需要显式确认，并且每次写入在落地之前都会经过哈希和语法验证。
权衡取舍很明确：CALM 的开箱即用完整调用图层级为 13 种语言，而不是某些纯 LSP 工具达到的 40 多种 — 但 24 种解析语言和 12 种带有编译器验证的升级路径使得差距比看起来更小。所做的交易购买的是 CALM 独有的部分：置信度分级边、硬性预编辑门控和代码库对自身健康状况进行评级 — 每个都由您可以自己复制的数字支持 ([证明，而非承诺](#proof-not-promises))。
### CALM 是适合您的选择吗？
**适合：** 直接编辑代码的代理，而不仅仅是回答问题 · 单仓库代码库，Tier-0/Tier-0.5 语言 · 运行多个 MCP 客户端（见下文支持的客户端）的项目与同一仓库 · 优先考虑本地的用户，不依赖嵌入式 API。
**目前不适合：** 多仓库/跨仓库企业搜索 — 为此规模而构建的工具（Sourcegraph/Cody 等）将更好地为您服务 · 不在 CALM 当前 24 种语言树形集合中的语言。
## 快速开始
**支持的客户端** — CALM 与任何支持 stdio 的 MCP 客户端配合使用；以下客户端已连接或有文档：
| 客户端 | 模式 | 最快安装 |
|---|---|---|
| **Claude Code** | CLI · Web · IDE | `claude mcp add --transport stdio calm -- npx -y @eilodon/calm-mcp serve` |
| **VS Code** | IDE (原生 MCP / Copilot Agent 模式) | `code --add-mcp '{"name":"calm","command":"npx","args":["-y","@eilodon/calm-mcp","serve"]}'` |
| **Cursor** | IDE · 云（后台代理） | [添加至 Cursor →](cursor://anysphere.cursor-deeplink/mcp/install?name=calm&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBlaWxvZG9uL2NhbG0tbWNwIiwic2VydmUiXX0=) |
| **Windsurf / Devin Desktop** | IDE · 云 | 编辑 `~/.codeium/windsurf/mcp_config.json` |
| **Codex** (OpenAI) | CLI · IDE | `codex mcp add calm -- npx -y @eilodon/calm-mcp serve` |
| **Antigravity** (Google) | CLI · IDE | 编辑 `~/.gemini/config/mcp_config.json` |
| **JetBrains AI 助手** | IDE | 通过 UI 设置 |
上述每个客户端的完整演练，包括需要配置文件的客户端的确切全局配置片段 — [`docs/mcp-client-setup.md`](docs/mcp-client-setup.md)。在 devcontainer/Codespace 中运行，stdio 转发无法到达？请参阅 [`docs/http-transport.md`](docs/http-transport.md)（高级，远程开发仅需选择加入，默认循环访问）。
**在您自己的项目中使用 CALM** — 无需克隆，无需 Rust 工具链：
```json
{
"mcpServers": {
"calm": {
"command": "npx",
"args": ["-y", "@eilodon/calm-mcp", "serve"]
}
}
}
```
将其放入 `.mcp.json`（Claude Code/Cursor）或 `.vscode/mcp.json`（VS Code 使用顶级 `"servers"` 键而不是 `"mcpServers"`，形状相同）到项目根目录。Claude Code 插件：`/plugin marketplace add Eilodon/CALM` 然后 `/plugin install calm@CALM`。
更喜欢原生二进制文件而不是 npx？ `curl -fsSL https://raw.githubusercontent.com/Eilodon/CALM/main/scripts/install.sh | sh`，然后在项目内运行 `calm setup` — 它会自动写入相同的 MCP 配置，指向您刚刚安装的二进制文件。添加 `calm setup --npx` 以写入便携式 `npx` 条目（可共享/提交 — 团队成员和 CI 不需要二进制文件，并且它跟踪已发布的版本）。
**在 CALM 本身（此仓库）上开发：
```bash
# 1. 构建二进制文件
cargo build --release -p calm-cli
# 2. 为您的项目初始化配置
calm init --project-root .
# 3. 构建索引（如果启用了语义搜索，还会嵌入符号）
calm index --project-root .
# 4. 通过 stdio 运行 MCP 服务器 — 如果已经存在索引，则会自动启动增量重索引
calm serve --project-root .
```
此仓库自带适用于 Claude Code（`.mcp.json`）、Cursor（`.cursor/mcp.json`）和 VS Code（`.vscode/mcp.json`）的预制配置 — 所有三个都指向 `scripts/mcp-launcher.sh`，一个共享启动器，它查找已构建的二进制文件，如果您位于匹配的 git 标签，则下载校验和验证的预构建版本，或者如果尚未有任何可用版本，则从源代码构建。克隆仓库，它直接起作用 — 不需要手动构建步骤。
> **注意：** `calm serve` 自动将 `.calm/` 添加到 `.gitignore` 以防止索引数据库被提交。
## 示例：代理的实际工作流程
```
agent: repo_overview()
→ 233 个文件，3,488 个符号，indexing_phase=ready
agent: "我需要更改 getUserByEmail"
→ locate("getUserByEmail") # 查找文件 + 符号元数据
→ source("getUserByEmail") # 读取函数体，而非整个文件
→ edit_context("getUserByEmail") # 编辑前 MANDATORY
→ 12 个调用者，risk_assessment=high → 代理在触摸签名前查看每个调用者
→ edit_symbol("getUserByEmail", expected_hash=..., new_text=...)
→ risk_assessment=high, is_hub=true, no confirm:true → 被拒绝，并附有解释
→ edit_symbol(..., confirm=true, reason="checked getUserByToken, still returns the same shape")
# 原因必须引用 edit_context 返回的实际调用者 — 写入并立即重新索引
→ diff_impact(staged=true) # 在提交前验证影响范围
```
## 证明，而非承诺
以下每个数字都是通过将 CALM 自己的 `fitness_report`/`repo_overview` 指向其自己的代码库来测量的 — 使用相同的两个工具调用在全新克隆上可重现：
| 指标 | 测量值 |
|---|---|
| 索引代码库 | **233 个文件，3,488 个符号** — 此仓库中存在 15 种语言 |
| 中心度 (`hub_pct`) | 7.5% — 169 个中心符号（门控：≤ 20%） |
| 死代码率 (`dead_code_pct`, 覆盖率感知) | 5.0%（门控：≤ 10%） |
| 边覆盖率 (`edge_coverage_pct`) | 74.9% 的符号至少有一个调用边（门控：≥ 60%） |
| 高复杂度函数 (`high_complexity_pct`) | 2.9%（门控：≤ 15%） |
| 模糊符号边界 (`boundary_ambiguous_count`) | 0（门控：≤ 0） |
| 架构边界违规 (`boundary_violations`) | 0（门控：≤ 0） — 此前在此标记的 `watcher → tools` 导入已被修复，通过将所需的共享 `RwLockExt`/`LockExt` 特性从 `tools/common.rs` 移动到它们自己的 `sync_ext` 模块 |
| 与天真读取文件基线的令牌效率 | `source` **241x** · `edit_context` **193x** · `locate` **29x** · `callers` **1.0x** — 中位数 111x across 四个基准任务 ([方法论](benchmarks/b4_token_efficiency/)) |
| 完整测试套件（默认功能） | 请参阅下面的 [测试](#testing)
<details>
<summary><strong>竞争者基准方法论和每种语言的注意事项</summary>
### 与其他 4 个实时 MCP 服务器基准
`benchmarks/b11_extended_competitor_ab/` 安装并调用四个已建立的开源代码智能 MCP 服务器 — CodeGraph、Semble、grepai 和 Serena — 进入此仓库的隔离 git 工作树，任务重复 5 次，每个任务都有正确性预言。目标不是排行榜；而是检查 CALM 的声明与实际运行的先前艺术相比，而不是营销页面。
运行结果显示：CALM 在调用者召回和爆炸半径任务上与最佳结果相符，并且是五个服务器中唯一一个实际上**拒绝**高风险的未经确认的编辑，而不是仅仅能够在事后描述风险。并非所有数字都对 CALM 有利：在一个令牌效率任务中，CALM 的压缩比是五个中的最低 — 准确性仍然达到上限，并且数字作为测量值被发布。那是这个项目的基准测试政策：不利结果与好的结果一起发布 ([benchmarks/README.md](benchmarks/README.md))。完整的方针、每个任务和原始的每工具数字都存放在基准测试的 README 中。
### 语言覆盖率，测量而非断言
`benchmarks/resolution/` 在 19 个新添加或 Tier-0.5 语言上运行分层分布基线（解析 / 推断 / 文本 / 模糊分割 — 无预言，一种语言一个真实的 OSS 仓库），并按原样报告：Kotlin（89.6%）和 OCaml（86.3%）主要停留在`ambiguous` 层，因常见的短方法名冲突；Dart 生成符号但零调用边 — 文档记录的该树形语法限制，而不是错误；Tier-2 类型推理仅适用于原始 Tier-0 语言。完整的每种语言表格在基准测试的 README 中。 </details>
## CALM 的工作原理
完整的技术细节位于 [`docs/architecture.md`](docs/architecture.md) — 包括设计理念，为什么每个响应都带有 `suggested_next`，以及为什么风险步骤是硬门控而不是仅仅推荐。章节总结：
- **[多层索引](docs/architecture.md#multi-tier-indexing)** — 默认情况下 13 种语言具有完整的调用图，11 种语言需要选择加入语法功能，总共 24 种。
- **[可信任的调用图](docs/architecture.md#a-call-graph-you-can-actually-trust)** — 每条边都标有置信度（`resolved`/`inferred`/`formal`/`textual`）；SCIP 和 LSP 叠加层将边升级为 12 种语言的编译器级真理。
- **[实际查找](docs/architecture.md#search-that-actually-finds-things)** — FTS5 + 语义嵌入通过相互引用排名融合，加上文件索引器永远不会解析的直接磁盘 grep/glob。
- **[具有实际安全网的编辑](docs/architecture.md#editing-with-an-actual-safety-net)** — 哈希验证的写入，写入磁盘前的语法验证，以及三部分门控（新鲜 `edit_context`、`confirm:true`，以及 `reason`） — 风险评估基于真实的调用图。
- **[并发性和可靠性](docs/architecture.md#concurrency--reliability)** — 共享守护进程、跨进程编辑锁和单实例索引锁确保单个仓库上的多个编辑会话不会损坏或复制工作。
- **[代码库自我评级](docs/architecture.md#the-codebase-grading-itself)** — 10 个健康指标、覆盖率感知死代码检测、声明的架构边界、文档漂移检测。
- **[记住并知道何时卡住的代理](docs/architecture.md#an-agent-that-remembers-and-knows-when-its-stuck)** — 持久的跨会话笔记、git 协同变更挖掘、卡住循环信号。
- **[默认安全](docs/architecture.md#safe-by-default)** — 每个工具响应中的凭证/提示注入删除，本地默认情况下仅限使用。
## CLI 参考
```bash
calm init --project-root . # 在当前目录写入 .calm/config.json，包含默认配置
calm index --project-root . # 一次完整的索引过程（扫描 → 解析 → 构建边 → 完成）
# 如果 semantic_search.enabled=true，则嵌入符号和区块
calm serve --project-root . # 通过标准输入/输出运行 MCP 服务器 + 增量重新索引 + 文件监视器
calm serve --project-root . --listen unix:/path/to/daemon.sock # 作为共享守护进程运行（可选）
calm connect --project-root . # 连接到已经运行的守护进程的轻量级转发器（可选，Unix）
calm serve --project-root /project --db-path /data/index.db # 单独的数据库路径（容器部署）
calm serve --project-root . --preset orient # 仅注册 "orient" 阶段的工具
calm doctor --project-root . # 验证配置、数据库（符号/文件/指标历史）、Git
calm setup --project-root . # 写入/合并 MCP 配置（.mcp.json/.cursor/.vscode）指向此二进制文件
calm fitness-check --project-root . # CI 门控，失败时退出 1
calm fitness-check --project-root . --json # JSON 输出
calm fitness-check --project-root . --config thresholds.toml # 自定义阈值
calm scip-run --project-root . --lang go # 强制运行一个 SCIP 提供程序，跳过刷新策略
calm scip-run --project-root . # 省略 --lang = 运行所有提供程序（"rust,go,python,javascript,java,csharp,php,ruby,c"）
calm index --project-root . --scip-file build/index.scip --sub-root services/api # 导入预建的 SCIP 索引（CI/沙盒，无需外部索引器安装）
```
## 29 个 MCP 工具用于 AI 代理
CLI 预设通过工作流阶段过滤工具：`orient`、`trace`、`edit`、`compound`、`full`（默认）通过 `calm serve --preset` 或 `config.json` 中的 `preset` 字段 - 或从工具集（模块）名称中组成自定义集，例如 `--preset "trace,security"` 或 `--preset "full,-edit"`（参见 AGENTS.md 获取完整的工具集列表）。每个响应都带有 `suggested_next` 以指向下一步 - 每个工具的完整详细信息和完整工作流位于 [AGENTS.md](AGENTS.md)。
| 分组 | 工具 |
|---|---|
| Orient | `repo_overview`、`hotspots`、`fitness_report`（健康快照 - 与 `calm fitness-check` 相同的指标，可在会话中查询）、`indexing_status`、`test_gap_hotspots`（按核心性 × 死代码/测试覆盖率置信度对符号进行排名 - 测试编写工作最有成效的地方） |
| Locate | `locate`、`search`、`file_overview` |
| Inspect | `source`、`symbol_info`、`understand`、`symbols_batch`（源 + 调用者/被调用者，适用于多个精确 `qualified_name`，一次往返） |
| Trace | `callers`、`callees`（有序，限额，带有 etag 缓存，适用于中心符号）、`path`、`dependencies` |
| Edit | `edit_context`（任何编辑前的必填项）、`edit_lines`/`edit_symbol`（任意内容的一个写入工具 - 哈希验证；不允许中心/高风险触摸，除非 `edit_context` 为该确切符号运行在此会话中，传递 `confirm:true`，并且 `reason` 引用的真实调用者 `edit_context` 返回）、`format_files`（仅通过标准输入的 rustfmt - 绝不带有位置文件参数，因此它不能触发 rustfmt 自己的 crate 范围 `mod` 树发现和重新格式化其自己的 `paths` 列表之外的文件；无需确认/编辑上下文门控，因为格式化不能更改语义）、`pattern_debt_register`/`pattern_debt_status`（通过 `search(kind="similar")` 按限定名称锚定重复的错误模式，稍后重新检查 `open`/`resolved`/`anchor_lost`）、`diff_impact`（提交前必填）- `edit_context` 和 `diff_impact` 在 Claude Code 下强制执行钩子（参见 `.claude/hooks/calm-nudge.sh`）；`session_context` 的 `pending_diff_impact` 是在任何其他 MCP 客户端上的等效信号 |
| Recover | `session_context`、`remember`、`recall` |
| Advanced | `scip_refresh`、`lsp_refresh` - 强制一个或多个 SCIP/LSP 提供程序现在运行，跳过自动刷新策略。`scan_text` - 对您提供的任何文本运行相同的提示注入/凭证启发式 `source`/`understand` 使用 - 本地和离线，与任何托管 LLM 安全分类器无关。所有三个：仅 `full` 预设，不在上述四个工作流阶段预设中 - 故意的手动/罕见使用逃生阀，而不是默认流程中的步骤 |
### MCP 提示 - 作为斜杠命令打包的工作流
与上述 `tools` 不同 - MCP Prompts（`prompts/list`、`prompts/get`）为经常重复的工作流返回单个现成的指令消息；MCP 客户端将它们显示为斜杠命令：
| 提示 | 参数 | 打包工作流 |
|---|---|---|
| `review_symbol` | `symbol` | `locate` → `source` → `edit_context`（必填）→ 触摸任何内容前的风险摘要 |
| `debug_symbol` | `symbol` | `understand` → `callers(max_depth=3)` → 检查 `test_files`/`dead_code_confidence` |
| `onboard_area` | `path` | `repo_overview` → `file_overview`/`dependencies` → 限定在该路径的 `hotspots` |
| `review_pr` | `range` | `diff_impact(commits=range)` → `hotspots`（重叠检查）→ `fitness_report` → 合并前聚合风险摘要 |
| `calm_workflow` | *（无）* | 无参数定向到完整的第 1-8 阶段工具工作流 - 适用于从未自动加载 AGENTS.md 的客户端，或会话中间刷新器 |
## 适应性检查 - CI 门控
在每次推送/拉取请求上，在 `.github/workflows/ci.yml` 的 `fitness-check` 作业中实际运行 - 首先运行 `calm index`（新的 checkout 尚没有 `.calm/index.db`），然后运行 `calm fitness-check --project-root . --config thresholds.toml`。该 `--config` 标志不是可选的；如果没有它，`[[boundaries]]` 和 `[config_drift]` 被静默视为“未声明规则”，而不是出错 - 只有数字阈值有真正的默认值。
`calm fitness-check` 衡量针对 `thresholds.toml` 中声明的阈值的 10 个指标：
| 指标 | 衡量内容 | 默认阈值 |
|---|---|---|
| `hub_count` | 分类为中心的符号数量 | ≤ 1000 |
| `hub_pct` | 作为中心的符号百分比（尺度不变） | ≤ 20.0% |
| `avg_coreness` | 图的平均 k 核核心性 | ≤ 15.0 |
| `dead_code_pct` | 具有“高”死代码置信度的符号百分比 | ≤ 10% |
| `hotspot_risk` | 代码库中最高的热点分数 | ≤ 0.75 |
| `edge_coverage_pct` | 具有至少一个调用边的符号百分比 | ≥ 60% |
| `high_complexity_pct` | 具有 McCabe 圈复杂度 > 10 的函数/方法百分比（基于 AST；0.5 级语言始终报告复杂度 1） | ≤ 15.0% |
| `boundary_violations` | 违反声明的 `[[boundaries]]` 规则的 `import_edges` 数量 | ≤ 0 |
| `boundary_ambiguous_count` | 具有模糊行边界的符号数量（与邻居共享）- 拒绝在其上进行 `edit_symbol` 替换，直到解决 | ≤ 0 |
| `config_drift_count` | 指向不存在的实际文档文件路径引用的数量（通过 `[config_drift].doc_paths` 声明） | ≤ 0 |
每次 `calm fitness-check` 运行还会将指标快照到数据库中，以便 `edit_context` 可以显示趋势（与前一天的增量）。
### 架构边界 - `[[boundaries]]`
在 `thresholds.toml` 中直接声明“模块 A 绝不能导入模块 B”（与 Rust 自己的 crate/module 边界不重复）- 按路径前缀匹配（不是 glob/regex）。注意，这适用于 Rust 自己的 crate 模块边界 *不* 已经强制执行的分层 - 声明“calm-core 不能导入 calm-server”将是无效的，因为 Cargo 的依赖图已经在结构上阻止了这种情况：
```toml
[[boundaries]]
from = "crates/calm-core/src/indexer/"
to = "crates/calm-core/src/analysis/"
reason = "索引器（提取）必须位于分析（死代码，热点，适应性）之上 - 不能反过来"
```
`calm fitness-check` 在 `--json` 模式之外具体报告每个违规（实际的 from/to 路径，规则和原因）；默认的 `max_boundary_violations = 0` 意味着您声明的规则是一条您实际执行的规则。
## 部署
- `cargo build --release` → 静态（Linux 上的 musl）二进制文件，通过 `.github/workflows/release.yml`，带有 SHA256SUMS 和构建来源证明的 5 个目标矩阵的资产：`x86_64-unknown-linux-musl`、`aarch64-unknown-linux-musl`、`aarch64-apple-darwin`、`x86_64-apple-darwin`、`x86_64-pc-windows-msvc`。`scripts/mcp-launcher.sh`/`scripts/install.sh` 在检出时（或您安装时）自动下载并校验和验证正确的平台构建。
- `Containerfile`，多阶段（`rust:alpine` → `scratch`）- 单个静态二进制文件，无需运行时镜像，已发布到 `ghcr.io/eilodon/calm-mcp`（按版本 + `latest` 标记）每次 git 标签推送。
- `compose.yaml` 提供一个加固的示例（`read_only`、`cap_drop: ALL`、`no-new-privileges`、`pids_limit: 64`、`mem_limit: 256m`）。
- 默认嵌入模型的权重通过 `include_bytes!` 组合到二进制文件中 - `build.rs::ensure_embedding_weights` 在编译时获取 `crates/calm-core/assets/potion-code-16m/*.safetensors` 到 Hugging Face Hub 并校验和验证它，因此正常的 `cargo build`/release 二进制文件在运行时加载它而无需任何网络 I/O。无需 Git LFS（存储库携带零 LFS 内容）。
<details>
<summary>如果构建时获取失败（离线构建等）会发生什么</summary>
`cargo build` 仍然 **编译成功** - `build.rs` 编写一个小的占位符存根，而不是使构建失败。加载该存根 **在运行时** 失败（“无法解析 safetensors”），因此 `Embedder::load` 自动回退到一次性的 Hugging Face Hub 下载（随后在本地缓存，通过 `semantic_search.allow_network_fallback` 门控）。如果禁用该回退或也不可用，则 `indexing_status` 报告 `embeddings_status: "failed"` 和 `search(kind="semantic"/"hybrid")` 降级为仅限 FTS - 没有崩溃，只是没有语义搜索，直到模型可用并且您重新构建或重新运行。
</details>
## 测试
```bash
cargo test --workspace # 单元测试 + 集成测试（嵌入式是一个默认功能，已包含）
cargo test --test parity_test test_formal_edges # Stack Graphs 回归测试
```
每次拉取请求都会运行 5 个 CI 作业：`verify`（fmt/clippy/test/audit）、`stack-graphs-corpus`（正式解析器一致性）、`embeddings`（clippy + 带有 `embeddings` 功能的测试）、`all-languages`（跨所有 24 种解析语言的固定仓库索引）、`js-client-interop`（与真正的 JavaScript MCP SDK 客户端交叉检查工具模式，而不是 Rust 自有的客户端）。
完整的 workspace 套件 - 1,000+ 测试 - 全部通过，带有少数 `#[ignore]` 的实时二进制集成测试（例如 `rust-analyzer`/`scip-go`/`scip-java`），这些测试在每个环境中都未安装。
## 进一步阅读
- [`docs/architecture.md`](docs/architecture.md) - 完整的 技术深入探讨：多层索引、SCIP/LSP 叠加层、搜索内部、编辑安全网、并发性、自评、内存、净化、以及背后的设计理念。
- [`docs/comparison.md`](docs/comparison.md) - 方法论优先的定位写法，与本类别中的其他工具进行比较。
- [`docs/what-external-users-get.md`](docs/what-external-users-get.md) - 正如 `npx`/npm/MCP-Registry 安装所提供的，与此存储库自己的开发检出不同的内容：安装/分发机制、完整的工具和工具集分解、编辑安全层、语言覆盖率、以及从未外部发布的內容。
- [`docs/`](docs/) - 解析器内部、迁移计划和其他设计笔记，不在上面的 `docs/architecture.md` 中涵盖。
- [`docs/adr/`](docs/adr/) - 个别架构决策记录（Stack Graphs 范围、正式解析器方法、LSP-可选置信度升级、守护进程+转发器并发模型）。
- [`docs/mcp-client-setup.md`](docs/mcp-client-setup.md) - 每个 MCP 客户端安装路径的详细说明，包括 Windsurf/Devin Desktop 和 Codex 全局配置。
- [`docs/http-transport.md`](docs/http-transport.md) - 可选的远程/HTTP 传输（`calm serve --http`）：默认环回，失败关闭的 `--allow-remote` + 令牌要求，远程暴露为什么强制只读预设，以及 TLS/反向代理预期。
- [`AGENTS.md`](AGENTS.md) - 本项目自己的代理遵循的完整工具按工具工作流指南。
- [`benchmarks/`](benchmarks/) - README 中每个数字背后的测量套件：`b2_call_graph_quality/`（精度/召回率 vs. SCIP 神谕）、`b4_token_efficiency/`（令牌成本 vs. 天真基线，每个任务）、`b11_extended_competitor_ab/`（与 4 个其他实时 MCP 服务器的真实调用对比，而不是自我报告的数字）、`resolution/`（跨 19 个真实 OSS 仓库的层分布基线，每个语言一个）。不吸引人的结果也被发布以与好的结果对比 - `benchmarks/README.md` 声明了该策略。
## License
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器