内容
<p align="center">
<img src="https://raw.githubusercontent.com/beingmartinbmc/jambavan/main/assets/jambavan.png" alt="Jambavan — the wise elder awakening latent power" width="640">
</p>
<h1 align="center">Jambavan</h1>
<p align="center"><em>提醒模型发挥其已有的能力。</em></p>
<p align="center">
<a href="https://www.npmjs.com/package/jambavan"><img src="https://img.shields.io/npm/v/jambavan.svg" alt="npm 版本"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/jambavan.svg" alt="node 版本"></a>
<a href="https://github.com/beingmartinbmc/jambavan/commits/main"><img src="https://img.shields.io/github/last-commit/beingmartinbmc/jambavan.svg" alt="最近的提交"></a>
<a href="https://github.com/beingmartinbmc/jambavan/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/beingmartinbmc/jambavan/ci.yml?branch=main" alt="CI 状态"></a>
<a href="https://bundlephobia.com/package/jambavan"><img src="https://img.shields.io/bundlephobia/minzip/jambavan" alt="bundle 大小"></a>
<a href="https://www.npmjs.com/package/jambavan"><img src="https://img.shields.io/npm/dm/jambavan.svg" alt="下载量"></a>
<a href="./LICENSE"><img src="https://img.shields.io/npm/l/jambavan.svg" alt="许可证"></a>
</p>
---
在《罗摩衍那》中，当军队在海洋边缘绝望时，是 **Jambavan** —— 古老而睿智的熊王 —— 转身对哈努曼说，提醒他自己已经拥有的、无法估量的力量。哈努曼一直拥有这种力量，他只需要被提醒。然后他一步跨过海洋。
大型语言模型是哈努曼。它已经能够推理、计划和编写代码。它缺乏的不是智力 —— 而是 *对自己所处的环境的认识*：存在哪些文件，什么调用什么，决定了什么，上周做了什么，已经尝试了什么。
**Jambavan 是海洋边缘的声音。** 它是一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为任何编码模型提供实时代码库地图、持久内存和一套外科手术工具 —— 以便模型的现有能力真正落地。
Jambavan 不调用 LLM，也不是代理。**宿主模型思考，Jambavan 给它提供立足点。**
## 它赋予的能力
| 能力 | 工具 | 功能 |
|---|---|---|
| **视野** | `jambavan_index`, `jambavan_context`, `jambavan_watch`, `jambavan_diagnostics` | AST 感知的代码索引（tree-sitter，增量，实时监控）。检索排名、按 token 预算的上下文，而不是重新读取整个文件。`jambavan_context` 还接受 `compress_prose`、`include_diff`（最近的 git 更改）和 `include_tests`（关联的测试文件）—— 增强功能共享相同的 token 预算，不会额外增加。 |
| **桥梁** | `jambavan_graph_report`, `jambavan_graph_query`, `jambavan_graph_path` | **轻量级推断代码图** —— 调用者、被调用者、导入、提及 —— 从 AST 提取的引用按 **符号名称** 匹配（不是作用域解析）。直接 `import` 语句解析为其实际源文件，因此两个同名符号之间的模糊调用链接到实际导入的符号；未解析的调用仍然按名称扩展。边框标记为 `EXTRACTED`（来自 AST）或 `INFERRED`（名称提及）；在大型重构前请验证。 |
| **记忆** | `jambavan_memory_store`, `_search`, `_recall`, `_mine_session`, `_invalidate`, `_delete`, `_status` | 持久的、人类可读的内存，以 markdown 文件存储在 `.jambavan/memory/` 下。BM25 搜索，无数据库，无嵌入，无外部服务。决策在会话和模型之间持续。 |
| **会话连续性** | `jambavan_failure_store`, `jambavan_failure_search`, `jambavan_session_export`, `jambavan_session_import` | 结构化的失败记录（命令、症状、根本原因、不重试建议），因此新的会话不会重复失败的尝试。`jambavan_session_export` 生成一个便携式交接文档（最近的记忆、未完成的债务、git 状态），以便在新会话、主机或与同事继续工作。 |
| **简洁** *(简写)* | `jambavan_sankshipta` | 确定性地将散文和提示压缩为更少的 token，同时保留代码、路径、版本和事实。 |
| **维比沙那·尼提** *(明智的建议)* | `jambavan_vibhishana_niti`, `jambavan_rin_mochan` | 在会话中激活高效开发规范，并审计临时快捷方式（`// rin:` 标记）到跟踪债务账簿。 |
| **手** | `read_file`, `search`, `list_files`（默认）· `write_file`, `patch_file`, `bash`（需启用） | 受保护的文件、搜索和 shell 工具 —— 仅限于项目根目录。只读工具默认启用；**变异和 shell 工具关闭，除非您启用它们**（参见 [安全性](#安全性)）。`bash` 具有尽力而为的防误伤过滤器（不是安全边界）。 |
| **提醒** | `jambavan_awaken` | 提醒模型上述所有能力，以及会话协议和最近的项目记忆。先调用它。 |
## 安装
一条命令。查找机器上的所有编码代理（Claude Code、Codex CLI、Cursor、Continue）。为找到的每个代理注册 Jambavan 为 MCP 服务器。
```bash
# macOS · Linux · WSL · Git Bash
curl -fsSL https://raw.githubusercontent.com/beingmartinbmc/jambavan/main/install.sh | bash
```
```powershell
# Windows · PowerShell 5.1+
irm https://raw.githubusercontent.com/beingmartinbmc/jambavan/main/install.ps1 | iex
```
~30 秒。需要 Node ≥20。跳过您没有的代理。安全地重新运行。它从不影响您配置中已经存在的其他 MCP 服务器 —— 在将脚本传输到 shell 之前请阅读它，就像对待互联网上的任何内容一样。
## 手动注册
如果您更喜欢自己配置，或者使用安装程序不知道的代理？每个地方都使用相同的命令：`npx -y jambavan`.
**Claude Code**
```bash
claude mcp add jambavan -- npx -y jambavan
```
**Codex CLI**
```bash
codex mcp add jambavan -- npx -y jambavan
```
**Cursor** (`~/.cursor/mcp.json` 全局或 `.cursor/mcp.json` 按项目)
```json
{
"mcpServers": {
"jambavan": { "command": "npx", "args": ["-y", "jambavan"] }
}
}
```
**Continue** —— 将 JSON 文件放入 `~/.continue/mcpServers/jambavan.json`:
```json
{ "command": "npx", "args": ["-y", "jambavan"] }
```
### 故障排除（NVM、GUI 应用、企业 npm）
`npx -y jambavan` 在 MCP 主机继承包含 `node`/`npx` 的 shell PATH 且 npm 可以访问公共注册表时有效。两个设置会破坏它：
**1. GUI 启动的主机（Cursor 等）看不到 NVM。** 您将看到 `spawn npx ENOENT`，或者 —— 在使用绝对 `npx` 之后 —— `env: node: No such file or directory`（因为 `npx` 是一个带有 `#!/usr/bin/env node` 的脚本）。GUI 应用在 shell 外启动，不会继承 NVM 的 PATH。解决方法：运行绝对的 `node` 以对抗 npm 的 `npx-cli.js` 并显式设置 PATH。
**2. 企业 npm 注册表 / 发布年龄策略。** 您将看到 `No versions available for jambavan`（npm 指向内部镜像，该镜像不代理它）或 `No matching version found ... with a date before <date>`（ `--before` / 发布年龄策略拒绝新发布的版本）。解决方法：强制使用公共注册表，清除 `--before` 并固定版本。
查找路径：
```bash
command -v node # → /abs/path/to/node
echo "$(npm prefix -g)/lib/node_modules/npm/bin/npx-cli.js" # → npx-cli.js
```
Cursor 配置应用了所有解决方法：
```json
{
"mcpServers": {
"jambavan": {
"command": "/abs/path/to/node",
"args": [
"/abs/path/to/npm/bin/npx-cli.js",
"-y",
"--registry=https://registry.npmjs.org",
"--before=",
"jambavan@0.4.0"
],
"env": { "PATH": "/abs/path/to/node/dir:/usr/bin:/bin" }
}
}
}
```
仅应用需要的部分：绝对 `node` + `npx-cli.js` + `PATH` 修复 NVM/GUI PATH；而 `--registry`/`--before`/固定版本修复企业 npm 策略。
## Claude Code 插件
此仓库也是 Claude Code [插件市场](https://code.claude.com/docs/en/plugin-marketplaces)。添加它并安装两个命令 —— 无需手动 MCP 配置：
```shell
/plugin marketplace add beingmartinbmc/jambavan
/plugin install jambavan@jambavan
```
插件注册相同的 `npx -y jambavan` MCP 服务器（默认情况下为只读工具）并捆绑一个 **Vibhishana Niti 技能** —— 在任何 Claude Code 会话中运行 `/jambavan:vibhishana-niti` 以激活高效开发规范。稍后刷新 `/plugin marketplace update jambavan`。目录存储在 [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)；插件清单存储在 [`plugins/jambavan/.claude-plugin/plugin.json`](plugins/jambavan/.claude-plugin/plugin.json)。
## 直接运行
```bash
npm install
npm run build
node dist/index.js --help
node dist/index.js
```
在目标仓库外部启动时设置 `JAMBAVAN_ROOT=/path/to/project`.
## 跳跃（推荐工作流）
1. `jambavan_awaken` —— 读取协议和最近的项目记忆。
2. `jambavan_index` —— 构建本地 SQLite 代码索引。
3. `jambavan_watch start` —— 在编辑时保持索引实时更新。
4. `jambavan_context` —— 在处理不熟悉的代码之前拉取排名、按 token 预算的上下文。
5. `patch_file` 而不是 `write_file` —— 外科手术编辑，更便宜的 token。（需要 `JAMBAVAN_ALLOW_WRITE=1`）
6. 保持工具输出 Sankshipta：行范围、`max_results`、`git --stat` / `--name-only`、`jq`/`yq`/`awk`/`cut`/`head`，以及哈希/mtime 轮询，然后进行完整读取。
7. `bash` —— 运行最小的相关检查。（需要 `JAMBAVAN_ALLOW_BASH=1`）
8. `jambavan_memory_store` / `jambavan_memory_mine_session` —— 坚持已做出的决定，以便下一个会话开始时保持清醒。
9. 遇到瓶颈？`jambavan_failure_store` 它（症状、根本原因、不重试的建议）—— 然后在重复失败的方法之前进行 `jambavan_failure_search`。
10. 结束会话？`jambavan_session_export` —— 将交接文档粘贴到下一个会话、不同的主机或同事。
## 安全性
**默认情况下为只读。** `read_file`、`search` 和 `list_files` 始终可用。变异和 shell 工具 **关闭，除非您显式启用它们**，因为自治主机模型不应意外获得写入/执行访问：
| 工具 | 启用方式 |
|---|---|
| `write_file`, `patch_file`, `jambavan_sankshipta` | `JAMBAVAN_ALLOW_WRITE=1` |
| `bash` | `JAMBAVAN_ALLOW_BASH=1` |
当禁用时，这些工具根本不会注册到主机上 —— 主机永远不会看到它们。（`jambavan_sankshipta` 会原地重写文件，因此算作写入工具。）
文件、搜索、列表和 `bash` 工作目录仅限于 `JAMBAVAN_ROOT`（或检测到的项目根目录）。设置 `JAMBAVAN_ALLOW_OUTSIDE_ROOT=1` 仅用于受信任的本地使用。看起来像秘密的文件（`.env*`、`*.pem`/`*.key`、`id_rsa`、`.npmrc`、`.aws/credentials`、`.git-credentials`、`service-account*.json`，以及 `.aws/`、`.docker/` 或 `.ssh/` ...）被所有文件工具拒绝，除非 `JAMBAVAN_ALLOW_SECRETS=1`。此列表故意不详尽 —— 它不是真正的秘密保护替代品。
`bash` 运行具有最小的无色环境（不继承主机秘密，除非 `JAMBAVAN_BASH_INHERIT_ENV=1`）并捕获几个明显的失误（`rm -rf /`、`rm -rf /*`、主目录/项目清除、`git reset --hard`、`git clean -fx`、盲 `curl | sh` 等）。这 **不是** 安全边界 —— 它可以被编码、别名、脚本、shell 扩展或未列出的命令（如 `find . -delete`）轻松绕过。将 `bash` 视为本地 shell：查看工具调用后再批准它们，并在需要真正的隔离时在沙盒工作空间（容器/微VM）中运行服务器。
## 配置
| 环境变量 | 默认值 | 描述 |
|---|---|---|
| `JAMBAVAN_ROOT` | 自动检测 | 要索引和服务的项目根目录 |
| `JAMBAVAN_MEMORY_HOME` | `<indexDir>/memory` | OKF 内存文档存储位置；指向共享的宫殿以跨项目重用内存 |
| `JAMBAVAN_TOKEN_BUDGET` | `8000` | `jambavan_context` 输出的最大 token 数 |
| `JAMBAVAN_DEV_MODE` | `full` | 默认 Vibhishana Niti 级别（`lite` / `full` / `ultra`） |
| `JAMBAVAN_ALLOW_WRITE` | 关闭 | `1` 注册 `write_file` + `patch_file` + `jambavan_sankshipta` |
| `JAMBAVAN_ALLOW_BASH` | 关闭 | `1` 注册 `bash` |
| `JAMBAVAN_ALLOW_OUTSIDE_ROOT` | 关闭 | `1` 允许工具逃离项目根目录（仅限受信任的本地使用） |
| `JAMBAVAN_ALLOW_SECRETS` | 关闭 | `1` 允许文件工具触摸类似秘密的文件 |
| `JAMBAVAN_BASH_INHERIT_ENV` | 关闭 | `1` 将完整的主机环境传递给 `bash`（默认：最小环境） |
| `JAMBAVAN_MAX_OUTPUT_CHARS` | `100000` | 任何工具返回的输出的全局上限 |
| `JAMBAVAN_MAX_READ_BYTES` | `5242880` | `read_file` 将加载的最大文件大小 |
## 基准测试
`npm run bench` 对实时管道进行狗粮测试 —— 没有 LLM 调用，没有外部服务，完全确定性。它从仓库自己的最常见符号自动派生查询，因此在任何代码库上都有意义。它测量 **五个** 维度，而不仅仅是 token 收益，并且下面每个数字都是针对此仓库进行的全新运行（38 个文件，177 个符号）：
**1. 索引** —— 构建速度和吞吐量。
| 指标 | 值 |
|---|---|
| 冷构建 | ~164 毫秒（38 个文件，177 个符号） |
| 暖重建 | ~29 毫秒（~5.7× 速度快，仅解析更改，仅更改的文件重新解析）
**2. 索引** — 构建速度和吞吐量。
| 指标 | 值 |
|---|---|
| 吞吐量 | ~232 文件/s · ~1,079 符号/s |
**3. 上下文** — 不仅是 token，还有 *智能体必须打开的内容*。基线 = 智能体读取查询匹配的所有文件的完整内容；Jambavan 提供排名、预算化的片段。
| 指标 | 基线 | Jambavan | 增益 |
|---|---|---|---|
| 文件/片段读取 | 6 个整文件 | 14 个聚焦块 | 有针对性的范围，而不是整文件 |
| token（5 个查询） | ~21,500 | ~12,000 | **~44% 更少** |
| 装配延迟 | （磁盘读取） | ~2 毫秒 | 小于一检查的运行时间 |
**4. 图** — 从 AST 中提取的关系（一种覆盖率指标，而不是 token）。
| 指标 | 值 |
|---|---|
| 节点/边 | 209 / 564 |
| 边源 | 314 `EXTRACTED`（来自 AST）· 250 `INFERRED`（名称提及） |
| 构建/查询/路径 | ~2.9 毫秒 / ~7.3 毫秒 / ~0.08 毫秒 |
**4. 简洁** *(简写)* — 散文压缩稳定在 **24%** 左右。
**5. 工具延迟** — **MCP 服务器提供的 28 种工具**，通过实际 stdio 传输计时（主机模型使用的相同请求/响应路径）：min/median/max 超过 10 次调用，对于只读工具，单次调用用于变异工具。代表性中位数：
| 工具 | 中位数 | 工具 | 中位数 |
|---|----|---|----|
| `jambavan_context` | 0.3 毫秒 | `jambavan_memory_search` | 0.2 毫秒 |
| `jambavan_graph_query` | 0.3 毫秒 | `jambavan_awaken` | 1.6 毫秒 |
| `jambavan_graph_path` | 0.2 毫秒 | `jambavan_index`（1 文件） | 13.4 毫秒 |
| `read_file` | 0.1 毫秒 | `search`（ripgrep） | 10.3 毫秒 |
| `list_files` | 0.3 毫秒 | `bash`（子进程） | 11.9 毫秒 |
| `jambavan_failure_search` | 0.2 毫秒 | `jambavan_session_export`（2 次 git 调用） | 40.6 毫秒 |
所有内容都驱动纯粹在进程内；异常值（`index`、`search`、`bash`、`session_export`）是 shell 调用或磁盘交互的，正如预期的那样。每个调用都成功；基准测试在任何工具出错时退出，基准测试退出码为非零，因此它兼作端到端烟雾测试。
**更大的代码库，收益越大。** 在一个中等大小的 Java 服务端（166 个文件，~1,000 个符号）上运行相同的基准测试 — 每个维度都按 Jambavan 的方式扩展：
| 维度 | 这个仓库（38 个文件，177 个符号） | 中等大小的 Java 服务端（166 个文件，~1,000 个符号） |
|---|---|---|
| 冷索引 | ~164 毫秒 | ~577 毫秒 |
| 增量重建索引 | ~5.7× 更快 | ~8.4× 更快 |
| 上下文 token 节省 | ~44% | **~87%** |
| 文件 → 块（5 个查询） | 6 个文件 → 14 个块 | 80 个文件 → 133 个块 |
| 图提取的边 | 564 | ~10,400 |
增量重建索引和每个查询的上下文保持大致不变，而从头开始读取随仓库增长而增加，因此 token 节省随着代码库增长而加剧。基线是一个保守的比较；按查询划分的结果各不相同，偶尔某个查询的匹配项位于小文件中，以整个文件的形式读取更便宜。运行它：
```bash
JAMBAVAN_ROOT=/path/to/your/repo npm run bench
```
## 检查
```bash
npm run lint
npm run build
npm run unit # node:test 单元测试套件（test/*.test.ts）
npm run self-check
npm run bench
```
参阅 [ARCHITECTURE.md](ARCHITECTURE.md) 了解内部实现。
---
<p align="center"><sub>你已经拥有了力量。Jambavan 只会提醒你。</sub></p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器