repofind

repofind

在从未打开过的代码仓库中查找代码，通常要从猜测开始：grep 一个词，试一个文件名。repofind 用索引取代猜测。将它指向本地目录，它就会遍历目录树——跳过 .git、node_modules、超过 1 MB 的文件，以及不在源码和文本扩展名允许列表中的文件——将每个文件拆分为连续的 40 行区块，并根据你的问题为这些区块排序。一次调用会返回最值得查看的五处位置，每处都包含文件、行范围、区块文本和分数。

排序采用混合方式。系统始终会对区块文本运行固定的 BM25 评分器（k1 = 1.2，b = 0.75）。如果环境中存在 TAKARA_API_KEY，还会加入嵌入步骤：通过兼容 OpenAI 的端点对查询和区块进行嵌入，每个区块的最终分数为 bm25 + 10 * max(0, cosine)。如果没有密钥，或者嵌入器运行失败，结果会在其 notes 中明确说明，并仅按关键词排序。默认情况下，每个文件只保留得分最高的结果，因此五个结果意味着有五个不同的文件可供查看。

其他工具涵盖探索流程的其余部分。locate 查找精确子字符串——环境变量、符号、错误代码等——并以计数、文件列表、简要位置或完整行的形式报告。expand 接收已有结果，并返回其所在区块以及同一文件中相邻的区块。find_related 接收相同的锚点，并据此为所有其他文件中的区块排序。read_benchmark 汇总已保存的基准测试模式查询，计算节省的令牌总数。原产品的 auth 工具不属于本次重建内容：由于已发布的规范未包含交互式设备登录和 AWS 配置文件验证所需的信息，无法复现，因此这里提供的是六个工具中的五个。

CLI

npx @reneturcios/repofind search '{"query": "retry backoff logic", "repo": "."}'
npx @reneturcios/repofind locate '{"literal": "DATABASE_URL", "mode": "locations"}'
npx @reneturcios/repofind expand '{"file_path": "src/client.ts", "anchor_line": 83}'
npx @reneturcios/repofind find_related '{"file_path": "src/client.ts", "anchor_line": 83}'
npx @reneturcios/repofind read_benchmark '{}'
npx @reneturcios/repofind --version

每个工具子命令都将工具参数作为一个 JSON 字符串接收，并以 JSON 格式输出结果。退出代码：成功时为 0，运行时错误时为 1，用法错误时为 2。

环境变量：TAKARA_API_KEY 用于启用语义检索部分；MIRU_OPENAI_BASE_URL（默认值为 https://infer.takara.ai/v1）和 MIRU_OPENAI_EMBEDDING_MODEL（默认值为 ds1-miru-int8）用于配置嵌入端点；MIRU_MAX_INDEX_FILES 用于限制索引文件数（默认值为 10000）；MIRU_BENCHMARK_HISTORY_PATH 用于覆盖基准测试历史记录的位置。

MCP 服务

npx -y @reneturcios/repofind mcp

MCP 客户端配置：

{
  "mcpServers": {
    "repofind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/repofind", "mcp"]
    }
  }
}

工具

• search — 对已索引的本地代码库进行语义与关键词混合搜索。代码探索的默认工具——每个问题调用一次。

  • query（字符串，必填）— 自然语言或代码查询
  • repo（字符串，可选）— 要索引的本地目录；默认使用工作目录
  • include / exclude（字符串数组，可选）— 针对相对仓库路径的 gitignore 风格 glob 模式
  • dedupe_by_file（布尔值，默认 true）— 每个文件仅保留最佳匹配

  返回 {hits, ranking, notes}，最多包含 5 条匹配；每条匹配的格式为 {file_path, absolute_path, start_line, end_line, anchor_line, truncated, snippet, score}，其中 score 四舍五入到小数点后 4 位。

• locate — 在已索引的本地代码库中查找精确子字符串（环境变量、符号、错误代码）。

  • literal（字符串，必填）；mode 为 count、files、locations、lines 之一（默认 lines）；limit 限制位置/行数；ignore_case（默认 false）；repo、include、exclude 与 search 相同。

• expand — 返回搜索匹配所在文件中的更多上下文：锚点块及其相邻块。

  • file_path 和 anchor_line（必填）；before / after 块数（默认各为 1）。

• find_related — 根据匹配项的 file_path 和 anchor_line，在其他文件中查找相似代码。返回与 search 相同格式的 {hits, ranking, notes}，并排除源文件。

• read_benchmark — 汇总已保存的基准模式查询所节省的累计 Token。返回 {queries, total_tokens_saved, average_tokens_saved}；历史文件缺失时会返回零值汇总，而非报错。

Docker

docker run -i ghcr.io/cloudcorprecords/repofind
docker run --rm ghcr.io/cloudcorprecords/repofind locate '{"literal": "TODO"}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (temp fixture repos, fake embedder, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios