Travsr-com/travsr

# travsr **与 git 并存的代码图。** [](https://github.com/Travsr-com/travsr/actions/workflows/ci.yml) [](https://github.com/Travsr-com/travsr/actions/workflows/bench.yml) [](https://github.com/Travsr-com/travsr/actions/workflows/phase2-exit.yml) [](https://www.npmjs.com/package/@travsr.com/travsr) [](LICENSE) ## 快速开始 ``` # 1. 安装 npm install -g @travsr.com/travsr # 2. 初始化你的 repo（需要 git） cd your-project git init # skip if already a git repo travsr init # indexes TypeScript files → .travsr/graph.db # auto-registers in ~/.travsr/registry.json # 3. 连接到 Claude Desktop（设置一次，适用于所有 repo） ``` 添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ``` { "mcpServers": { "travsr": { "command": "travsr", "args": ["mcp", "--stdio", "--global"] } } } ``` 重启 Claude Desktop。提问：*"谁调用了 PaymentService.charge？"* ## 发布渠道 每次发布都会推送到三个 npm dist-tag。使用 `^` 范围安装时永远不会解析到预发布版本，因此除非您明确选择加入，否则您总是获得 `latest` 版本： ``` npm i -g @travsr.com/travsr@latest # stable (default if you omit the tag) npm i -g @travsr.com/travsr@rc # release candidate — final gates in flight npm i -g @travsr.com/travsr@beta # earliest builds, opt-in testing only ``` `beta` 版本及其后来升级的 `rc`/`latest` 版本是字节完全相同的二进制文件 —— 升级操作是在新标签下重新发布相同的已签名构件，而不是重新构建，因此您在 `beta` 上测试的内容正是发布到 `latest` 的内容。无论通过哪个渠道，每个 tarball 都经过 cosign 签名和 SLSA 认证；验证步骤请参见 [SECURITY.md](SECURITY.md)。 ## 多仓库支持 Travsr 在 `~/.travsr/registry.json` 中维护一个全局注册表。每次调用 `travsr init` 都会自动注册该仓库。 ``` # 每个 repo 初始化一次 cd ~/projects/repo-a && travsr init cd ~/projects/repo-b && travsr init cd ~/projects/task-manager && travsr init # 查看所有已注册的 repo travsr repos ``` ``` | Name | DB Path | Exists | | repo-a | /Users/you/projects/repo-a/.travsr/graph.db | yes | | repo-b | /Users/you/projects/repo-b/.travsr/graph.db | yes | | task-manager | /Users/you/projects/task-manager/.travsr/graph.db | yes | ``` 单个 `--global` MCP 服务器即可服务于所有这些仓库。当您询问某个符号时，它会在所有已注册的仓库中进行搜索，并在结果前添加 `[repo-name]` 前缀，以便您随时了解答案来自哪个代码库。 ## 兼容所有支持 MCP 的 AI 工具 Travsr 支持 [MCP](https://modelcontextprotocol.io)，这是连接 AI 智能体与工具的开放标准。 ### Claude Desktop / 全局模式（推荐） ``` { "mcpServers": { "travsr": { "command": "travsr", "args": ["mcp", "--stdio", "--global"] } } } ``` ### Cursor 添加到 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（单个项目）： ``` { "mcpServers": { "travsr": { "command": "travsr", "args": ["mcp", "--stdio", "--global"] } } } ``` ### GitHub Copilot (VS Code) 需要 VS Code 1.99+。添加到您项目中的 `.vscode/mcp.json`： ``` { "servers": { "travsr": { "type": "stdio", "command": "travsr", "args": ["mcp", "--stdio", "--global"] } } } ``` ### Cline (VS Code 扩展) 在 Cline 扩展设置中 → **MCP Servers** → 添加服务器： ``` { "travsr": { "command": "travsr", "args": ["mcp", "--stdio", "--global"], "disabled": false } } ``` ### Continue.dev 添加到 `~/.continue/config.json` 的 `mcpServers` 下： ``` { "mcpServers": [ { "name": "travsr", "command": "travsr", "args": ["mcp", "--stdio", "--global"] } ] } ``` ### 单仓库模式 如果您更倾向于指向某个特定的仓库，请使用 `--db`： ``` travsr mcp --stdio --db /path/to/repo/.travsr/graph.db ``` 或者省略这两个标志并从仓库内部运行；travsr 会从当前的 git 根目录自动发现 db。 ## MCP 工具 所有工具响应都被封装在 `` 信封中，并在返回前进行了净化处理，因此返回的内容可以安全地直接传递到 LLM 上下文中（去除了控制字符，中和了提示词注入向量）。 在全局模式下，接受 `file` 或 `symbol` 参数的工具也接受可选的 `repo` 参数，以针对特定已注册的仓库。省略 `repo` 则搜索所有已注册的仓库。 **查询工具**（在单仓库和全局模式下均可用）： | 工具 | 描述 | |---|---| | `get_dependencies(file)` | 文件的所有导入/依赖项 | | `get_callers(symbol)` | 所有存在指向某符号入边的节点 | | `get_blast_radius(file)` | 如果给定文件发生更改，受传递影响的文件 | | `search_symbol(name)` | 图中匹配某个名称的符号定义 | | `get_repo_map` | 已索引仓库的结构化概览 | | `get_execution_path(source, sink)` | 两个符号之间 PCST 最优的执行路径 | | `get_context(query, token_budget)` | 通过 PPR 遍历并按相关性排序，受 knapsack 预算限制 | | `get_graph_stats` | 节点/边计数、schema 版本、最后索引的 SHA | | `get_graph_json(query, direction, depth)` | 作为结构化 JSON 的子图，供图形渲染器使用 | | `get_snippets(symbol)` | 符号的源码片段，包含文件和行上下文 | | `get_lang_status` | 仓库中每种语言的 Phase B 索引器状态 | | `repo_languages` | 在已索引仓库中检测到的语言 | **仓库管理工具**（全局模式）： | 工具 | 描述 | |---|---| | `repos_list` | 列出所有全局已注册的仓库 | | `repos_remove(repo)` | 从全局注册表中移除一个仓库 | | `repos_prune` | 移除其 db 路径不再存在的注册表条目 | **同义词工具**（查询扩展）： | 工具 | 描述 | |---|---| | `synonym_add(term, alias)` | 添加单个术语/别名对 | | `synonym_set(term, aliases)` | 原子性地替换某个术语的所有别名 | | `synonym_remove(term, alias)` | 移除单个术语/别名对 | | `synonym_remove_term(term)` | 移除某个术语的所有别名 | | `synonym_list` | 列出所有已配置的同义词 | | `synonym_reset` | 清除所有同义词 | 在全局模式下，接受 `file` 或 `symbol` 参数的工具也接受可选的 `repo` 参数，以针对特定已注册的仓库。省略 `repo` 则搜索所有已注册的仓库。 ## CLI 命令 ``` travsr init Index the repo, install git hook, register globally travsr daemon start/stop/status Start, stop, or check the background daemon travsr repos List all globally registered repos travsr status Show node/edge counts, schema version, last-indexed SHA travsr ask PPR + knapsack symbol lookup from the terminal travsr graph Show dependency graph for a symbol or file travsr graph --all Show graph for the entire indexed repository travsr mcp --stdio Start the MCP stdio server (single-repo, cwd-based) travsr mcp --stdio --global Start the MCP stdio server (all registered repos) travsr mcp --stdio --db Start the MCP stdio server (explicit db path) travsr lang list List all known Phase B language indexers and their status travsr lang install Download and register a Phase B language indexer travsr lang detect Scan the repo, detect supported languages, auto-install travsr lang remove Unregister a Phase B language indexer travsr lang approve Pre-approve a language that needs network access travsr synonym add Add a query synonym travsr synonym list List all configured synonyms travsr synonym remove Remove a synonym term travsr embed list List available embedding models travsr embed init Initialize the embedding index for this repo travsr embed status Show embedding index status travsr embed reindex Rebuild the embedding index travsr embed switch Switch to a different embedding model ``` ### travsr graph 以 ASCII 树、Graphviz DOT 或结构化 JSON 格式，可视化来自任何符号或文件的依赖图。 ``` # ASCII tree（默认）：extension.ts 导入和定义了什么？ travsr graph extension.ts # 谁调用了 PaymentService.charge？ travsr graph PaymentService.charge --direction callers # 双向，深度 2 travsr graph service.ts --direction both --depth 2 # 渲染为 SVG（需要 graphviz：brew install graphviz） travsr graph extension.ts --format dot | dot -Tsvg -o graph.svg && open graph.svg # 用于 AI 工具的机器可读 JSON travsr graph extension.ts --format json # 全仓库图 travsr graph --all --format dot | dot -Tsvg -o repo.svg && open repo.svg travsr graph --all --format json ``` **标志：** | 标志 | 默认值 | 描述 | |---|---|---| | `--direction` | `deps` | `deps` · `callers` · `both` | | `--depth` | `3` | 最大遍历深度 | | `--format` | `tree` | `tree` · `dot` · `json` | | `--all` | (无) | 导出整个已索引的图（与 `` 互斥） | **JSON 输出 schema** (`--format json`)： ``` { "schema_version": 1, "summary": { "mode": "query", "root": "file", "root_path": "src/index.ts", "total_nodes": 6, "total_edges": 5, "kinds": { "file": 1, "function": 2, "import": 2, "variable": 1 } }, "nodes": [ { "id": "...", "signature": "fn:activate", "kind": "function", "path": "src/index.ts", "language": "typescript", "depth_from_seed": 1 } ], "edges": [ { "from": "file", "to": "fn:activate", "kind": "defines/binding" } ] } ``` ## VS Code 扩展 从 VS Code Marketplace (`travsr.travsr-vscode`) 安装 **Travsr** 扩展。 该扩展通过 MCP 连接到您本地的 Travsr daemon，并添加以下功能： - **状态栏**：daemon 连接状态和已索引节点计数 - **Code lens**：函数定义上的内联“N 个调用者”注解 - **悬停提示**：导入语句上的依赖列表 - **图表面板**：使用 Cytoscape.js 渲染的交互式依赖图；支持按类型过滤和两跳导入遍历；通过 Travsr 侧边栏或命令面板 (`Travsr: Show Graph`) 打开 该扩展使用您已安装的 `travsr` 二进制文件。在 VS Code 设置中设置 `travsr.binaryPath` 可覆盖二进制文件的位置。 ## 存储后端 | 后端 | 标志 | 备注 | 状态 | |---|---|---|---| | SQLite + WAL | _(默认)_ | 零配置，随处可用 | 可用 | SQLite + WAL 是存储后端，不需要额外的依赖。 Kùzu 以前作为可选后端提供，但现已被弃用 （参见 `docs/adrs/ADR-018-drop-kuzu-backend.md`）。RocksDB 仍然是未来可能用于超大规模的后端。 ## 工作原理 ``` git init && travsr init └─▶ walks .ts / .tsx files (respects .gitignore) └─▶ Tree-sitter parses each file └─▶ Nodes + edges → .travsr/graph.db (SQLite WAL) └─▶ post-commit hook installed └─▶ repo registered in ~/.travsr/registry.json git commit └─▶ post-commit hook fires └─▶ travsr hook-run └─▶ SHA-256 delta: only re-indexes changed files └─▶ graph.db updated, last_commit SHA recorded ``` **图通过 post-commit 钩子保持最新。** 每次提交的更改都会 自动重新索引。该图在 `travsr init` 之后，即在任何提交之前，也完全可以立即进行查询。 语言支持：**TypeScript / TSX、Rust、Python、Go**（内置，零配置）。其他语言（Java、Kotlin、C#、Scala、PHP、Ruby、Swift）可通过 `travsr lang install` 作为 Phase B 索引器使用。 ### 检索算法 | 算法 | 使用场景 | 状态 | |---|---|---| | BFS depth-3 | `get_dependencies` / `get_callers` 查询 | 可用 | | Personalized PageRank (PPR) | `get_context` 和深度遍历 | 可用 | | PPR weighted | 感知分数的 PPR 变体 | 可用 | | 0-1 背包问题 (0-1 Knapsack) | 对 `get_context` 结果进行 Token 预算限制 | 可用 | | 奖励收集斯坦纳树 (PCST) | `get_execution_path`：两个符号之间的最优路径 | 可用 | | k-core 分解 | 挖掘隐藏的中间部分 | 可用 | | BM25 | 全文排名检索 | 可用 | | RBAC | 图查询上基于角色的访问过滤 | 可用 | ### 边类型 | 类型 | 含义 | |---|---| | `depends` | 文件导入另一个模块 | | `defines/binding` | 文件或类定义了一个符号（函数、方法、变量） | | `ref/call` | 调用点引用 | | `exports` | 符号从模块导出 | ### 安全性 所有 MCP 工具的输出在返回给客户端之前，都会经过一个净化流水线： 1. 截断为安全的最大长度 2. 剥离 C0/C1 控制字符 3. 转义 `<` 和 `>` 以防止工具描述中出现 XML/HTML 注入 4. 封装在 `` 结构化信封中 路径遍历和参数注入会在工具调度层被拒绝 （`../`、`..\\`、绝对路径、空字节、`%` 编码的遍历序列）。 **发布构件签名：** 每个发布 tarball 都使用 [cosign 无密钥签名](https://docs.sigstore.dev) 和 GitHub Actions OIDC token 进行签名。SLSA v1.0 来源通过 GitHub 证明附加到每个版本中。验证说明请参见 [SECURITY.md](SECURITY.md)。 **供应链审计：** 所有 Rust 依赖项在每次 CI 运行时都会使用 [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) 进行审计（CVE 公告、 许可协议策略、被封禁的 crate）。每晚的 OSV 扫描会针对 `Cargo.lock` 和 `package-lock.json` 检查新的 CVE。 ## 从源码构建 ``` git clone https://github.com/Travsr-com/travsr cd travsr # 构建（SQLite backend） cargo build --release # requires Rust 1.75+ # 使用本地构建覆盖 npm 安装的 binary cp target/release/travsr $(which travsr) # 或 export TRAVSR_BINARY=/path/to/travsr/target/release/travsr ``` **平台支持：** macOS (x86\_64 + arm64)、Linux (x86\_64 + aarch64)、Windows (x86\_64)。 预构建的二进制文件可在 [Releases](https://github.com/Travsr-com/travsr/releases) 页面获取。 **MSRV：** Rust 1.75（每次提交时在 CI 中验证）。 ## 故障排除 - **`not inside a git repository`** 在 `travsr init` 之前运行 `git init`。 - **`not initialized: run travsr init`** 在使用 `graph`、`ask`、`status` 或 `mcp` 之前，在仓库根目录下运行 `travsr init`。 - **MCP server returns empty results in `--global` mode`** 运行 `travsr repos` 以验证仓库已注册且 `Exists` 显示为 `yes`。 如果缺失，请在该仓库中重新运行 `travsr init`。 - **Stale entries in `travsr repos` (Exists = no)** 可以安全忽略；它们会被自动跳过。这些条目的出现是因为某个仓库在被索引后被删除或移动了。 - **Binary not found after npm install?** 设置 `TRAVSR_BINARY=/path/to/travsr` 以使用本地构建。 - **Corporate proxy blocks the postinstall download?** 同上：设置 `TRAVSR_BINARY` 以跳过远程获取。 ## 更新日志 完整的发布历史请参见 [CHANGELOG.md](CHANGELOG.md)。 ## 贡献 请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。欢迎提交 Issues 和 PR。采用 Apache 2.0 授权。

标签：MCP, MITM代理, SOC Prime, 云安全监控, 人工智能, 代码图谱, 代码智能, 代码索引, 开发工具, 用户模式Hook绕过, 通知系统, 静态分析