reposkein/reposkein

## 简介 **RepoSkein 为你的 AI 编程代理提供了一份代码库地图——让它能够直接导航结构，而不是依赖 grep 和盲目猜测。** 它使用 [Tree-sitter](https://tree-sitter.github.io/) 为你的代码库构建一个**确定性的代码属性图**——包含文件、类、函数、import 和调用边——并将其提供给任何支持 [MCP](https://modelcontextprotocol.io) 的代理（Claude Code、Cursor、Codex 等）。在工作时，代理会将简短的自然语言摘要写入图节点；这些摘要**与代码一起在 git 中进行版本控制**，从而让代理的理解转化为**共享的团队记忆**，供下一个代理或团队成员作为起点。 **适用人群：** 在真实的、庞大的或**嵌套/多语言**代码库中使用 AI 编程代理的开发者，且已经厌倦了代理为了 grep 而耗尽其上下文窗口；以及希望那些来之不易的理解能够持久化并共享、而不是每次会话都重新推导的团队。 - ⚡ **零基础设施** — 无需数据库，无需 Docker。该图存储在已提交的 `.reposkein/*.jsonl` 文件中。 - 🔒 **确定性** — 相同的代码 → 字节完全相同的图。构建路径中没有 LLM 参与。 - 🌐 **7 种语言** — Python、TypeScript、JavaScript、Rust、Go、Java、C#。 - 🧩 **本地优先且 git 原生** — 图及其摘要随你的代码一起传输。 | 你的代理询问 | RepoSkein 回答 — 直接来自图 | | --- | --- | | “谁调用了 `charge()`？” | 确切的调用者，附带一行摘要 | | “如果我修改这里会破坏什么？” | 受影响的调用者 + 覆盖它们的测试 | | “我到底该从哪里开始？” | 按含义（而非文件名）排序的入口函数 | | “通常哪些文件会与此文件一起修改？” | 来自 git 的共同修改历史 | ## 目录 - [前置条件](#prerequisites) - [安装说明](#installation) - [使用方法 — 与你的代理协同工作](#usage--working-with-your-agent) - [支持的语言](#supported-languages) - [工作原理](#how-it-works) - [MCP 工具](#mcp-tools) - [可选功能：语义 embedding](#optional-semantic-embeddings) - [可选功能：Neo4j 后端](#optional-neo4j-backend) - [基准测试](#benchmarks) - [从源码构建](#build-from-source) - [文档](#documentation) - [贡献指南](#contributing) - [致谢](#acknowledgements) - [联系方式](#contact) - [许可证](#license) ## 前置条件 - **Node.js 18+** — 用于运行 `npx @reposkein/mcp`（indexer 二进制文件会自动获取）。 - **支持 MCP 的代理** — [Claude Code](https://claude.com/claude-code)、Cursor、Codex、Zed 等。 - 一个需要被索引的 **git 仓库**（RepoSkein 会安装 git hook 并提交该图）。 - *可选：* **Docker**（仅用于 [embedding 服务](#optional-semantic-embeddings)或 [Neo4j 后端](#optional-neo4j-backend)）；**Rust**（仅用于[从源码构建](#build-from-source)）。 ## 安装说明 在你希望代理理解的代码仓库中： ``` npx @reposkein/mcp init ``` 这会下载适用于你平台的 indexer，安装 git hook + 导航技能，**构建初始代码图**，并打印出 MCP 配置块。然后： 1. **将打印出的配置添加到你的代理中**（例如 Claude Code 的 `.mcp.json`）： { "mcpServers": { "reposkein": { "command": "reposkein-mcp", "env": { "REPOSKEIN_REPO_PATH": "/path/to/your/repo" } } } } 2. **验证并提交图**（`init` 已经构建了它）： reposkein-mcp doctor . # ✓ 二进制文件 ✓ 已索引 (N 个节点) ✓ 准备就绪 git add .reposkein && git commit -m "add RepoSkein code graph" 在进行重大更改后，使用 `reposkein-mcp index .`（或代理的 `reindex_file` 工具）重新索引。 3. **询问你的代理** *“谁调用了这个函数？”* 或 *“如果我修改 X 会破坏什么？”* — 它会直接从图中给出答案。 **平台支持：** 提供适用于 macOS (Apple Silicon)、Linux (x64/arm64) 和 Windows (x64) 的预构建二进制文件。在其他平台上，请将 `REPOSKEIN_INDEXER_BIN` 指向[从源码构建](#build-from-source)的版本。 ## 使用方法 — 与你的代理协同工作 你只需用自然语言提问；内置的 **`reposkein-graph-rag`** 技能会驱动这些工具。自然的循环如下： 1. **寻找起点** — `semantic_find("jwt auth validation")` 会按含义对正确的函数进行排序，无需知道符号名。→ *“限流器在哪里？”* 2. **理解它** — `get_context_profile` 将节点的调用者和被调用者作为易于阅读的文本返回（`hops: 2` 扩大范围，`federated: true` 跨越嵌套仓库）。 3. **在修改之前** — `impact` 列出传递调用者（可能会破坏的部分），并将其与覆盖它的测试（需要运行的部分）区分开来。→ *“如果我修改 `charge()` 会破坏什么？”* 4. **什么会随之变动** — `get_temporal_context` 呈现历史上经常一起更改的文件，以及变动率和所有权。→ *“什么通常会与 auth 配置一起更改？”* 5. **记录你学到的内容** — `write_semantic_summary` 将 1-3 句的笔记附加到节点上，并提交到 git 中供下一个代理/团队成员使用。 6. **编辑之后** — `reindex_file` 刷新已更改文件的图。

示例交互

``` You: Refactor how we validate auth tokens — what's involved? Agent: → semantic_find("validate auth token") → resolves auth.validate_jwt → get_context_profile(auth.validate_jwt) → 3 callers, 2 callees (+ summaries) → impact(auth.validate_jwt) → 6 impacted functions, 4 covering tests → get_temporal_context("src/auth/jwt.py") → co-changes with config/keys.py (conf 0.8) Agent: "validate_jwt is called by the login, refresh, and middleware paths; changing its signature touches 6 functions and 4 tests (test_jwt.py, test_middleware.py, …). Heads up: jwt.py historically changes together with config/keys.py — you'll likely need to update both." ```

### 代理技能 RepoSkein 提供了两个跨代理的 [Agent Skills](https://skills.sh) — `npx skills add reposkein/reposkein --all` 可将两者都安装到 Claude Code、Cursor、Codex 和其他 70 多种代理中： - **`reposkein-setup`** — 在代码库中安装 RepoSkein 并验证其是否正在运行（二进制文件 → 索引 → MCP 可达性）。可以让你的代理执行它。 - **`reposkein-graph-rag`** — 教导你的代理在*何时*使用哪种工具（即上述循环）。`reposkein-mcp init` 会自动将其安装到 Claude Code 中。 ## 支持的语言 | 语言 | 定义 | Imports → 边 | 跨文件调用 | | --- | --- | --- | --- | | Python | 函数、类、方法、嵌套定义、变量 | ✅ 相对 / 绝对 / 别名 | import 解析 (`exact`) | | TypeScript / TSX | 类、接口、枚举、方法、箭头函数 | ✅ 命名 / 默认 / 别名 / `* as ns` | import 解析 (`exact`) | | JavaScript / JSX | *（通过 TS 语法）* | ✅ ES imports *（暂不支持 CommonJS）* | import 解析 (`exact`) | | Rust | fns、structs、traits、enums、`impl` 方法 | ✅ `use`（分组、别名、通配符、`pub use` 链；感知 workspace） | import 解析 (`exact`) | | Go | funcs、方法 (`Type.method`)、structs、interfaces | *暂不支持（已规划跨 package）* | 同 package（同目录）；跨 package 按名称 | | Java | 类、records、interfaces、enums、方法、构造函数、字段 | ✅ package 路径 *(暂不支持通配符/static)* | import 解析 (`exact`) | | C# | 类、structs、records、interfaces、enums、方法、属性 | *暂不支持（已规划跨 namespace）* | 同目录；跨 namespace 按名称 | **诚实地说明解析能力。** 每条边都带有 `resolution`（`exact` / `name_match` / `ambiguous`）+ 置信度，因此你的代理知道该信任什么。同文件调用、`self`/`this` 方法以及**遵循 import 的自由函数调用解析为 `exact`**。Python 的 **module-alias 调用**（`import foo as f; f.bar()`）会 `exact` 解析到目标模块的函数。**跨文件的 INHERITS/IMPLEMENTS 边**在整个代码库范围内解析：遵循 import 的基类解析为 `exact`（置信度 1.0）；唯一的同目录或全库基类解析为 `name_match`（0.8/0.7）；为避免产生虚假的层级关系边，模糊的基类将被跳过——而位于**联邦子仓库**中的基类会在加载时缝合到跨仓库的继承边中。Go 的 **struct/interface embedding**（`type Dog struct { Animal }`）被捕获为 INHERITS。构造函数会发出独特的 **`INSTANTIATES`** 边（TS/Java/C# 中的 `new Foo()`，Rust 中的 struct 字面量，以及名称解析为类的 Python `Foo()`），这样代理就可以询问*谁创建了这个类型的实例*——它会针对类型索引进行解析，并在模糊时被跳过。由于该图**在设计上是无类型系统**的（确定性，流程中没有编译器），**实例方法调用（`obj.method()`）按名称解析**（≤ `name_match`），并且重载调用会被标记为 `ambiguous`。Go 和 C# 尚未发出 import 边，因此它们的跨 package/namespace 调用按名称解析（同 package/-目录下的调用*确实*可以解析）。这些限制是零基础设施、无类型系统设计所固有的；一个可选的类型感知层（SCIP/LSP）已在路线图上。[添加一种语言](CONTRIBUTING.md)是一条成熟的道路——欢迎贡献。 ## 工作原理 ``` Your agent (Claude Code / Cursor / …) ── guided by the reposkein skill │ MCP ▼ @reposkein/mcp semantic_find · get_context_profile · impact · get_temporal_context (TypeScript) read_cypher · write_semantic_summary · init_cpg_skeleton · reindex_file CLI: init · doctor │ reads ▼ .reposkein/*.jsonl ← the code graph, committed to git (zero-infra, in-memory store) ▲ writes │ reposkein-indexer Tree-sitter parse → stable IDs → canonical JSONL (Rust) + git hooks & a 3-way merge driver for conflict-free summaries ``` - **结构是静态的。** 骨架完全来自解析——相同的代码会生成字节完全相同的图（这是一个经过 CI 测试的不变量），与运行者无关。 - **含义是即时的。** 摘要在代理访问节点时写入；它们被标记上内容哈希（因此当代码更改时它们会标记为陈旧）并提交到 git。 - **本地优先。** 提交的 JSONL 是事实来源；可选的 [Neo4j 后端](#optional-neo4j-backend)是一个可重构的投影，大多数用户都不需要。 ### 跨仓库联邦 有嵌套仓库（由多个已索引的 repo 组成的 monorepo）？RepoSkein 会发现它们，用 `FEDERATES_TO` 链接它们，并在加载时缝合**跨仓库的调用、import 和继承边**（指向子仓库中基类的 `INHERITS`/`IMPLEMENTS`）。传入 `federated: true` 即可跨越 repo 边界进行遍历。联邦边是在加载时派生的（从不提交），因此每个 repo 都保持独立且确定性。 ## MCP 工具 | 工具 | 功能 | | --- | --- | | `semantic_find` | 寻找起点 — 按含义对函数/类进行排序（词法 BM25F；可选 [embeddings]()） | | `get_context_profile` | 解析函数/类 → 将其调用者/被调用者邻域转化为易于阅读的文本 | | `impact` | 将传递调用者拆分为受影响的代码与覆盖测试 | | `get_temporal_context` | 文件的 git 衍生共同修改、变动率和所有权 | | `read_cypher` | 只读图查询（拒绝写入，结果设有上限） | | `write_semantic_summary` | 将带有哈希戳的摘要附加到节点 | | `init_cpg_skeleton` | 构建/重建图 | | `reindex_file` | 编辑文件后刷新图 | `reposkein-mcp` CLI 额外添加了 **`init`**（设置仓库）和 **`doctor`**（健康检查）。 ## 可选功能：语义 embedding 默认情况下，`semantic_find` 是**确定性和词法**的（BM25F — 零基础设施，无需密钥）。你可以选择开启 **hybrid** 级别（词法 + embedding 余弦相似度，通过 RRF 融合）以进行更模糊的查询。它是**默认关闭**的，向量缓存在 `.reposkein/local/embeddings/` 中（被 gitignore，从不提交），并且在发生任何错误时会**自动回退到词法**。在 MCP 服务器上设置环境变量并**选择其中一种**： ### A) Voyage AI — 云端，最简单，最适合代码 [获取密钥](https://dashboard.voyageai.com/)，然后： ``` REPOSKEIN_EMBED_PROVIDER=voyage VOYAGE_API_KEY=pa-... # 可选: REPOSKEIN_EMBED_MODEL=voyage-code-3 # 默认 — 代码专用 ``` ### B) Ollama — 本地，开箱即用，无需密钥 ``` ollama pull nomic-embed-text # 768-dim (or mxbai-embed-large=1024, bge-m3=1024) ``` ``` REPOSKEIN_EMBED_PROVIDER=http REPOSKEIN_EMBED_URL=http://127.0.0.1:11434/v1/embeddings REPOSKEIN_EMBED_MODEL=nomic-embed-text REPOSKEIN_EMBED_DIMS=768 # must match the model ``` ### C) Voyage 的开源模型，自托管 — 离线 + Voyage 质量 `voyage-4-nano`（Apache-2.0）是一个 Ollama 无法运行的自定义基于 Qwen3 的模型，因此 RepoSkein 提供了一个预构建的服务器。该镜像**已发布到 GHCR — 公开且支持多架构 (amd64/arm64)** — 所以无需构建任何东西： ``` docker run -p 8080:8080 -v reposkein-hf:/root/.cache/huggingface \ ghcr.io/reposkein/reposkein-embed # auto-picks your architecture; first run downloads the model ``` ``` REPOSKEIN_EMBED_PROVIDER=http REPOSKEIN_EMBED_URL=http://127.0.0.1:8080/v1/embeddings REPOSKEIN_EMBED_MODEL=voyage-4-nano REPOSKEIN_EMBED_DIMS=1024 # must equal the server's EMBED_DIMS ``` 所有数据都保留在你的机器上。该镜像**仅限 CPU，无需 NVIDIA GPU** 即可在 Apple Silicon / ARM 统一内存、x64 Linux 和 Windows 上运行（CI 会构建并对这两种架构进行冒烟测试）。Docker 无法使用 Apple 的 Metal/MPS — 为此，请使用 `EMBED_DEVICE=mps` 在本地运行服务器。完整详情（root `docker compose up`、GPU、其他模型）：[`embed-server/README.md`](embed-server/README.md)。 ## 可选功能：Neo4j 后端 零基础设施的 JSONL 存储是默认选项。Neo4j 是一个可选的投影，适用于非常大的图和大规模的原始 Cypher： ``` docker compose --profile neo4j up -d # from the repo root NEO4J_PASSWORD=reposkeintest reposkein-indexer load . ``` 然后在 MCP 服务器上设置 `REPOSKEIN_STORE=neo4j` + `NEO4J_*` 环境变量。（`REPOSKEIN_STORE=auto`（默认值）在存在时使用 JSONL，仅在配置了 Neo4j 时才回退到它。） ## 基准测试 两条测试轨道，均位于 [`mcp/bench/`](mcp/bench/) 下： - **轨道 1 — 检索效率**（确定性，无 LLM）：RepoSkein 与 grep 代理在手动标记的任务上进行对比 → 在结构化查询上**平均减少约 8.4 倍的上下文 token**，F0.5 = 1.00 而 grep 为 0.11–0.71。[详情。](mcp/bench/README.md) - **轨道 2 — 终端任务**（[SWE-bench-Verified](mcp/bench/track2/README.md)）：一个最小化的代理循环，其中*唯一*的区别是导航工具集（RepoSkein 对比 grep），根据解决率 + token + 轮次进行评分。已构建并经过单元测试；API+Docker 运行是可选的。 ## 从源码构建 要求：Rust（稳定版）、Node 24。Docker 仅用于可选的 Neo4j 后端。 ``` cd indexer && cargo build --release # → indexer/target/release/reposkein-indexer cd ../mcp && npm install && npm run build ``` 通过 `command: node`、`args: [".../mcp/dist/index.js"]`、环境变量 `REPOSKEIN_REPO_PATH` + `REPOSKEIN_INDEXER_BIN` 将其连接到你的代理。测试：`cd indexer && cargo test && cargo clippy --all-targets -- -D warnings`；`cd mcp && npm test`。 ### 仓库布局 ``` indexer/ Rust workspace: core, lang-{python,ts,rust,go,java,csharp}, lang-common, neo4j-io, cli mcp/ @reposkein/mcp — the TypeScript MCP server (tools + graph-store backends) mcp/bench/ benchmarks: retrieval efficiency (Track 1) + end-task SWE-bench harness (Track 2) skills/ reposkein-graph-rag + reposkein-setup — cross-agent skills (skills.sh) embed-server/ one-command local embedding server (voyage-4-nano) for hybrid semantic_find ``` ## 文档 | 文档 | 内容 | | --- | --- | | [`mcp/README.md`](mcp/README.md) | `@reposkein/mcp` 包 — 工具、配置、环境变量 | | [`embed-server/README.md`](embed-server/README.md) | 本地 embedding 服务器 — Docker/GHCR、平台、GPU | | [`mcp/bench/README.md`](mcp/bench/README.md) | 轨道 1 检索基准测试 — 方法与结果 | | [`mcp/bench/track2/README.md`](mcp/bench/track2/README.md) | 轨道 2 终端任务 (SWE-bench) 测试框架 | | [`CHANGELOG.md`](CHANGELOG.md) | 发布历史 (Keep a Changelog) | | [`skills/`](skills/) | 两个跨代理技能 | ## 联系方式 - 🐛 **Bug / 功能：** [提交一个 issue](https://github.com/reposkein/reposkein/issues) - 💬 **问题 / 想法：** [GitHub Discussions](https://github.com/reposkein/reposkein/discussions) ## 许可证 [Apache-2.0](./LICENSE)。

_{Built for agents that read structure, not noise.}

标签：AI编程, GraphRAG, JS文件枚举, LLM上下文, MCP协议, MITM代理, SOC Prime, 代码图谱, 可视化界面, 开发工具, 日志审计, 逆向工具, 通知系统