voyager-repo

Name: voyager-repo
Author: dir-ai

本地服务

github.com/dir-ai开发工具014 周前更新

代码仓库

关于 voyager-repo

voyager-repo 是供 Agent 和开发者了解陌生代码库的只读侦察工具。它生成涵盖结构、构建命令、Git 状况和风险的导览简报，并给出有序的探索计划，不运行仓库代码。

主要功能

01仓库结构与语言概览
02识别构建和测试命令
03Git 活跃度与健康信号
04安装钩子和密钥风险检查
05可选依赖审查
06有序的行动计划

适用场景

01帮助 Agent 熟悉陌生仓库
02编辑前查看项目结构
03识别安装钩子或密钥风险
04不执行代码地规划仓库探索

MCP 相关

向 MCP 客户端提供 `scout_repo` 工具，以默认安全的方式导览仓库；默认关闭侵入性选项。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dir-ai-voyager-repo": {
      "command": "npx",
      "args": [
        "-y",
        "@dir-ai/voyager-repo"
      ]
    }
  }
}

启动命令npx -y @dir-ai/voyager-repo

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@dir-ai/voyager-repo0.7.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
path	string	否	本地仓库路径（默认：cwd）。远程 URL 需要 allowClone。
maxFiles	integer	否
allowExec	boolean	否	同意执行——仅限沙盒内。
checkDeps	integer	否	通过 Voyager 验证最多 N 个直接依赖项（0 = 跳过）。
allowClone	boolean	否	同意克隆远程 git URL。
allowInstall	boolean	否	同意安装依赖项（仍绝不在主机上运行代码）。

详细介绍

voyager-repo

Voyager 的仓库探测器官——AI Agent 在接触未知仓库前派出的眼睛。

Voyager 探测 Web（@dir-ai/voyager）、仓库（本项目），并将在下一步探测网络。Repotector 是仓库的守护者，负责接收和控制；Voyager Repo 则是 Agent 的对应伙伴，负责向外探索并安全地汇报。

npx @dir-ai/voyager-repo scout .          # orient in the repo you're standing in
npx @dir-ai/voyager-repo scout . --check-deps 10   # + vet 10 deps via Voyager

功能

就像 Claude 或 Codex 在新代码库中熟悉环境一样——但它是一个安全、可重复使用的工具。scout 会生成一份概览简报：

用途——根据清单文件/README 推断，并标记为不可信内容（所有者文本在传给你的模型前会经过注入剥离）
结构——编程语言、关键目录（附带角色推测）、入口点
构建——安装/构建/测试/运行命令（只检测，不执行）
健康状况——Git 信号：提交次数、巴士系数（主要作者的提交占比）、近期活跃度、变更热点
依赖项——与 Voyager 结合，为每个依赖项提供经过 OSV 检查的真实判定（--check-deps N）
风险——安装钩子（在 npm install 时可能触发 RCE）、已提交的密钥、缺少锁文件、大型不透明二进制文件
处理计划——见下文

处理协议（重点）

像谨慎的新手，而非横冲直撞的拆迁队：

如果仓库中有 Repotector（.repotector/），先与它握手——读取其活动区域/租约，并在编辑前遵守相关规定。
权限默认失败关闭。默认情况下，所有操作均为只读。在你同意之前，不会安装依赖项、执行代码或克隆远程仓库（--allow-install / --allow-exec / --allow-clone）；即使获准执行，也必须在沙箱中进行。
有序探索——简报会以一系列有序的后续步骤结尾，指导行为良好的 Agent 有目的地探索，而不是随机尝试。

保证

不会在主机上执行目标仓库中的任何内容。scout 会读取文件和 Git 数据，但绝不会运行仓库代码。（经你同意后执行时，会在 Voyager 的强化容器中运行。）
所有由仓库所有者控制的字节均不可信——README、描述、提交消息、Repotector 账本等内容，在模型看到之前都会经过注入剥离并加以标记。
退出代码：0 已完成概览 · 1 已完成概览并发现 HIGH 风险 · 2 工具错误。

MCP

voyager-repo mcp

工具：scout_repo——提供相同的概览，默认安全（关闭侵入性标志）。

库

import { scout } from '@dir-ai/voyager-repo'
const brief = await scout('/path/to/repo', { checkDeps: 10 })
if (brief.risks.some((r) => r.level === 'high')) { /* caution */ }