代码索引层 phuongddx/jarvis

jarvis

CI
Platforms
License: MIT
MCP

你的编码代理不应该把上下文窗口浪费在 grep 上。

当你的代理问“AuthService 在哪里被使用？”时，grep 会把注释、 markdown、测试夹具以及名称相似的符号混成一堆噪声返回。代理为了从噪声中过滤出信号而反复读取文件，消耗上下文——而且仍然会漏掉调用点。

jarvis 预先计算出一个本地代码智能层，让你的代理可以调用 findReferences 获取精确出现位置，调用 goToDefinition 获取定义范围，调用 callHierarchy 获取调用路径，调用 searchCode 进行精确的词法搜索——十个 MCP 工具，适用于 Claude Code、Cursor 或任何 MCP 客户端。你的代码和索引永远不会离开你的机器。

| 没有 jarvis | Grep → 注释、测试、导入与真实命中混在一起 → 打开文件进行过滤 → 猜测调用点 → 把上下文浪费在搜索上而不是推理上 |
| 使用 jarvis | findReferences("AuthService") → 精确的文件和范围出现位置 → 用 callHierarchy 获取调用图 → searchCode("token refresh") → 无需打开每个匹配项即可回答 |

快速开始 · MCP 工具 · 仪表盘 · 限制 · 详情 · 文档

快速开始

1. 安装独立二进制文件：

brew install jarvis-intelligence/jarvis/jarvis

Linux 用户需要先安装 Homebrew/Linuxbrew。
该 formula 支持 macOS arm64/x86_64 和 Linux arm64/x86_64，会同时安装 jarvis 和 jarvis-server，并内嵌 Python 3.12、仪表盘资源、 tree-sitter 库、watch、scip、zoekt-git-index 和 zoekt-webserver。Homebrew 提供 universal-ctags。无需安装 Python、 uv、pip 或 PyPI。

使用 brew upgrade jarvis 升级；使用 brew reinstall jarvis 修复损坏的安装。

2. 索引一个仓库（slug 默认使用目录名）：

jarvis index /path/to/your/repo

3. 注册 MCP 服务器：

claude mcp add jarvis --scope user -- jarvis-server

让你的代理“查找对 AuthService 的所有引用”——它会调用 findReferences 而不是 grep。

其他 MCP 客户端（Cursor、Claude Desktop、任何 stdio 客户端）

{
"mcpServers": {
"jarvis": {
"command": "jarvis-server"
}
}
}
如果你的客户端在 PATH 上找不到 jarvis-server（GUI 应用通常不会继承你 shell 的环境变量），请使用 which jarvis-server 得到的绝对路径。

Claude Code 插件（注册 MCP + 附带 agent 技能）

先安装 Homebrew 二进制文件。该插件会添加 jarvis 技能，并可以注册已安装的 jarvis-server。

/plugin marketplace add jarvis-intelligence/jarvis-index
/plugin install jarvis@jarvis

可选的语言索引器

独立包包含 SCIP 转换器和两个 Zoekt 二进制文件。
Homebrew formula 不会安装 setup.sh；请从 jarvis 源码检出目录中，为你的仓库安装可选的按语言索引器：

| 语言 | 安装器 | 工具链 |
| TypeScript/TSX | sh setup.sh --only scip-typescript | Node.js/npm |
| Python | sh setup.sh --only scip-python | Node.js/npm |
| Java/Kotlin | sh setup.sh --only scip-java | JDK；Kotlin 仓库需要精确的 Kotlin 2.2.0 |
| Swift | sh setup.sh --only scip-swift | macOS arm64 上的 Xcode |

对于 macOS 上使用 Maven 构建的 Java 仓库，还需安装现代版 Bash：
brew install bash，然后从同一个源码检出目录运行 sh setup.sh --only bash-shim。
添加索引器后请重新索引。如果没有匹配的索引器，在 Tree-sitter 覆盖的范围内，documentSymbols 和 goToDefinition 仍然可用； findReferences、callHierarchy 和 typeHierarchy 会返回恢复指引。

不包含的内容

semanticSearch 为兼容 MCP 而注册，但被排除在独立发行版之外。它会返回一个 Homebrew 特有的不可用错误，并指向下方的源码构建步骤；词法搜索和符号搜索仍然可用。

源码构建的语义搜索

独立 Homebrew 包不包含语义依赖。在源码检出目录中，使用以下命令安装它们：

uv run jarvis install-semantic

然后显式索引：

uv run jarvis index /path/to/repo --semantic
install-semantic 还会预先下载嵌入模型（BAAI/bge-m3，约 4.3 GB，一次性）到共享的 Hugging Face 缓存（~/.cache/huggingface/）；每个被索引的仓库都会复用它。如果下载中断，下一次 jarvis index 会自动重试。

MCP 工具

| 工具 | 功能 |
| goToDefinition | 将符号解析到其定义文件和范围 |
| findReferences | 符号在被索引仓库中的每一次出现 |
| callHierarchy | 符号的传入/传出调用 |
| typeHierarchy | 超类型/子类型 |
| documentSymbols | 一个文件中定义的所有符号的大纲 |
| searchCode | Zoekt 词法/正则搜索，可选过滤到单个仓库 |
| semanticSearch | 返回 Homebrew 发行版的语义不可用错误 |
| blastRadius | 哪些其他已索引的仓库依赖于某个包，最多 2 跳 |
| getIndexStatus | 已发布的提交、新鲜度、相对于工作树的陈旧程度 |
| indexRepo | 为位于 path 的 git 仓库构建索引 |

仪表盘

jarvis dashboard # 提供 http://127.0.0.1:6080 并打开浏览器

一个 localhost Web 控制台，读取与 CLI 和 MCP 服务器相同的 ~/.jarvis 数据：

要求和限制

- 仅支持 macOS arm64/x86_64 和 Linux arm64/x86_64。 不支持 Windows。
- Homebrew 发行版中不可用语义搜索。
- 每个仓库一种语言 —— 通过 git 跟踪文件的扩展名多数来检测；使用 --language 覆盖。
- jarvis 从不编辑代码。 它是检索的那一半 —— Serena 在重命名/重构方面与之互补。
- 索引是显式的 —— 在查询之前运行 jarvis index（或 jarvis watch）。

详情

工作原理

一个索引 CLI 将预计算的索引写入 ~/.jarvis；一个 stdio 运行时读取它们。两者之间没有其他契约。

- 发布是原子的 —— 重新索引会写入新快照，然后通过 os.replace 翻转 current 指针。读取旧快照的查询会继续工作；没有停机窗口。
- 运行时路径从不写入 —— 每个查询都以只读方式打开已发布的快照（mode=ro&immutable=1）。
- 包图是重建的，而非累积的 —— 每次重新索引都会在重新计算之前清除该仓库的出边。

完整细节：docs/system-architecture.md

索引 CLI 参考

jarvis index /path/to/your/repo # slug 默认为目录名 jarvis index /path/to/your/repo --slug foo # 或显式选择一个 jarvis index /path/to/your/repo --scheme MyScheme # 具有不明确 Xcode scheme 的 Swift 仓库 jarvis index /path/to/your/repo --language python # 强制指定语言而不是检测它 jarvis index /path/to/your/repo --no-scip # 跳过可选的 SCIP 增强；语法基线 + Zoekt 仍会发布 jarvis index /path/to/your/repo --scip # 重新启用 SCIP 增强（两个标志按仓库持久化） jarvis list jarvis status foo jarvis reindex foo jarvis forget foo jarvis watch /path/to/your/repo [--debounce 5.0] # 在文件更改时进行防抖自动重新索引（前台）

已知的上游限制
- scip-java 无法索引 Android/Gradle 仓库 — 其 Gradle 插件依赖于标准源集，而 AGP 会替换这些源集（scip-java#177）。会自动检测；降级为仅搜索模式。
- Kotlin 索引需要精确匹配 Kotlin 版本 — scip-kotlinc 是针对某一个固定版本（当前为 2.2.0）编译的。会自动检测。
- Maven 构建的 Java 仓库在 macOS 上需要 bash ≥ 4.4 — brew install bash 可解决此问题。
- Swift 索引需要 scip >= v0.9.0 — 较旧的转换器会静默丢弃出现范围。jarvis index 会拒绝较旧的 scip，而不是发布损坏的索引。

配置

| 变量 | 用途 |
| JARVIS_DATA_DIR | 覆盖所有索引和注册表的默认 ~/.jarvis |

源代码开发的语义路径有额外的模型前缀覆盖项；它们在独立发行版中不起作用。

文档

- docs/project-overview-pdr.md — 范围、价值主张、超出范围的事项
- docs/system-architecture.md — 架构保证、存储布局、查询路径
- docs/codebase-summary.md — 模块映射、测试覆盖率
- docs/code-standards.md — 代码模式和约定
- docs/dashboard.md — 仪表板视图、操作、安全模型

许可证

MIT