内容
# wordkeep
本地MCP服务器，为编码代理提供结构化的、按token预算的上下文，而不是完整的代码转储。通过 `--root` 参数指向任何存储库，并通过stdio（JSON-RPC）调用工具。
与Cursor、VS Code Copilot、Claude Desktop、Zed等MCP客户端兼容。
参见 [blog.md](./blog.md) 了解项目原理、架构决策以及开发过程中解决的问题。
*每个工具的token位移、最近活动和健康信号的实时仪表盘。*
## 安装
### 预编译二进制文件（推荐）
从 [GitHub Releases](https://github.com/inatos/wordkeep/releases) 下载您平台的存档。验证 `SHA256SUMS.txt` 中的校验和，解压并将 `wordkeep` 放入您的 `PATH` 中。
### 从源代码构建
```sh
git clone https://github.com/inatos/wordkeep.git
cd wordkeep
cargo build --release
```
二进制文件：`target/release/wordkeep`
需要Rust 1.74+ 和 C 工具链，仅当您启用可选的 `daslang` 功能时。
## 快速入门
1. 构建或下载 `wordkeep`。
2. 添加一个MCP服务器条目，运行带有 `--root` 参数的二进制文件，设置为您的 工作空间。
3. 重载编辑器，以便客户端重新启动服务器。
4. 在打开整个文件之前，要求您的代理调用 `repo_map` 或 `symbol_refs`。
示例（Cursor）：复制 [examples/mcp.cursor.json](examples/mcp.cursor.json) 到 `.cursor/mcp.json` 并替换 `/absolute/path/to/wordkeep`。
示例（VS Code Copilot）：复制 [examples/mcp.vscode.json](examples/mcp.vscode.json) 到 `.vscode/mcp.json`。
此存储库的可选启动脚本：[mcp.sh](mcp.sh) 运行 `target/release/wordkeep`，带有固定的 `CARGO_TARGET_DIR`。
## 配置
将 [`.wordkeep/config.example.json`](.wordkeep/config.example.json) 复制到您的 **目标存储库**，作为 `.wordkeep/config.json`：
```json
{
"default_paths": ["src", "pkg/lib"],
"test_command": "ctest -R"
}
```
- `default_paths`：在工具省略 `paths` 时搜索（默认：`["src"]`）。
- `test_command`：`test_map` 过滤器提示和陷阱验证行打印的前缀。
环境变量：
| 变量 | 目的 |
| --- | --- |
| `WORDKEEP_ROOT` | 省略 `--root` 时的备用工作空间根目录 |
| `XDG_CACHE_HOME` / `%LOCALAPPDATA%` | 平台缓存基；wordkeep 使用 `<base>/wordkeep/` |
| `WORDKEEP_TRACY_CSVEXPORT` | 覆盖 `.tracy` 捕获的 `tracy-csvexport` 二进制文件 |
| `WORDKEEP_MAS_ENTRY_TOKENS` | MAS 黑板帖子的每个条目上限（默认 ~400） |
## 您获得的内容
28种MCP工具，包括：
| 工具 | 用途 |
| --- | --- |
| `repo_map` | 源树结构 |
| `outline` | 单个文件中符号和行号 |
| `symbol_refs` | 符号的定义、调用、引用位置 |
| `call_graph` / `call_path` | 调用者/被调用者的爆炸半径或最短链 |
| `symbol_context` | 调用图的主体 + 一跳 + 布局 |
| `knowledge_search` | 问题的相关文档/规则 |
| `test_map` | 更改后的最窄测试 |
| `stats` | 每个工具测量的token位移 |
完整目录：[docs/tools.md](docs/tools.md)。设计说明：[docs/onboarding.md](docs/onboarding.md)。
语言（通过tree-sitter）：C/C++、GLSL、Rust、Python、C#、TypeScript/TSX/Svelte。
Daslang（`.das`）默认使用轻量级扫描器；精确解析是可选的（ `--features daslang` ）。
## 可选功能
```sh
cargo build --release --features embeddings # knowledge_search 的语义重新排序
cargo build --release --features daslang # 捆绑的 Daslang 语法
cargo run --features dashboard -- dashboard # 实时统计终端UI
```
默认构建是离线且确定性的（仅BM25，无ONNX）。
## 测试
```sh
cargo test
cargo test --test mcp_stdio # 完整的MCP协议测试
cargo test --test external_repo # 隔离的消费者存储库
```
集成测试将固定数据复制到临时git存储库中，因此工具不会意外读取父多模块存储库的`.git`。
## 手动烟雾测试
从wordkeep存储库根目录，在 `cargo build --release` 之后：
```sh
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"repo_map","arguments":{"paths":["src"]}}}' \
| ./target/release/wordkeep --root .
```
参见 [docs/getting-started.md](docs/getting-started.md) 了解更长的演练。
## 遥测
每个工具记录 **精炼** （估计读取原始材料的token）与 **返回** （实际发出的数据）。调用 `stats` 检查节省情况。
数据使用约4个字符每token的启发式算法。
在一个大型私有多语言代码库（627次调用）上进行为期29天的试验，wordkeep估计 **240M精炼 vs 315K返回** （~99.9%减少）。方法论和注意事项：[blog.md](blog.md#measured-results-anonymized-july-2026).
## 文档地图
- [docs/getting-started.md](docs/getting-started.md) - 首次运行和MCP连接
- [docs/configuration.md](docs/configuration.md) - 配置文件、环境变量、缓存
- [docs/tools.md](docs/tools.md) - 工具参考
- [docs/onboarding.md](docs/onboarding.md) - MCP入门和设计原理
- [docs/designs/recursive_mas.md](docs/designs/recursive_mas.md) - MAS 黑板
- [blog.md](blog.md) - 项目存在的原因
- [CHANGELOG.md](CHANGELOG.md) - 发布说明
- [CONTRIBUTING.md](CONTRIBUTING.md) / [SECURITY.md](SECURITY.md)
## 许可证
MIT。参见 [LICENSE](LICENSE) 和 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
