mengshi02/codetrip

# codetrip [](https://github.com/mengshi02/codetrip/actions/workflows/go.yml) [](https://github.com/mengshi02/codetrip/releases) [](https://go.dev/) [](LICENSE) **为您的代码智能体提供代码库的结构地图。** Codetrip 将代码仓库转换为本地强类型的代码图，以便 Codex、Claude Code、Cursor、VS Code/Copilot 和 GitHub Copilot CLI 能够回答纯文本搜索无法解决的问题： ``` What calls this method? What could this change affect? How does this request flow? Can I safely rename this symbol? ``` 它将图遍历、源码搜索和可选的语义检索结合在一个 CLI、MCP server 和 Go 库中。索引数据始终保留在您的本地机器上。当 MCP 客户端调用工具时，选定的结果将返回给该客户端，并可能根据客户端的数据策略进入其模型上下文。配置外部 embedding endpoint 还会将已索引的 chunk 发送到该端点；而词法和图索引不需要此类服务。 ## 在 Codex 中查看实际效果 在一次真实的只读 Codex 运行中，Codetrip 将当前工作树的 diff 映射到五个已更改的 CLI 符号，遍历了它们的反向依赖项，分离出仅涉及文档的更改，并识别出共享的运行时风险路径：  提示词为： Codex 调用了 Codetrip 的 `diff` 和 `impact` MCP 工具。索引保留在本地，选定的图查询结果返回给了 Codex，并且没有编辑任何文件。同样的图也直接通过 CLI 提供给用户使用： ``` $ codetrip impact IndexRepo --repo codetrip --depth 2 --format tree IndexRepo engine.go:318 └── CALLS ← newIndexCmd cmd/codetrip/cli.go:469 └── CALLS ← newRootCmd cmd/codetrip/cli.go:39 2 affected symbols across 2 files ``` 与文本匹配不同，该结果记录了关系的方向、距离以及用于解析每次调用的证据。省略 `--format tree` 可以获取完整的 JSON 结果，包括置信度和解析证据。 ## 适用人群 Codetrip 主要面向希望让代码智能体理解代码仓库结构，但不想部署代码智能服务的开发人员和小型团队。它也可以直接在终端中用于变更前的影响分析、架构探索和安全的重命名规划。对于需要嵌入式、仓库级代码图的工具，Go 库是其辅助集成接口。目前，Codetrip 并不打算取代企业级代码搜索平台、IDE 重构引擎或跨组织的代码托管服务。 ## 快速开始 ### 1. 安装 从 [GitHub Releases](https://github.com/mengshi02/codetrip/releases) 下载适用于 Linux、macOS 或 Windows 的预编译二进制文件，或者使用 Go 进行安装： ``` go install github.com/mengshi02/codetrip/cmd/codetrip@latest ``` 使用 `go install` 构建需要 Go 1.26+ 和 C 工具链。发布的压缩包仅包含一个可执行文件，不需要任何语言运行时。 ### 2. 索引仓库 ``` cd /path/to/project codetrip index . --repo project ``` 该命令会打印出文件数、图节点、图边和索引耗时。后续可以使用 `--replace` 重新索引。 ### 3. 尝试查询 ``` # 精确的 symbol 名称可直接使用。 codetrip search "ParseConfig" --repo project codetrip context ParseConfig --repo project codetrip impact ParseConfig --repo project --depth 3 --format tree codetrip diff HEAD~1 --target HEAD --repo project ``` 如果名称存在歧义，Codetrip 会列出匹配的位置及其节点 ID，而不是随意猜测。传入其中一个 ID 即可精确选定它。CLI 查询结果默认为 JSON 格式，可以安全地通过管道传递给 `jq` 或其他程序。 ### 4. 连接您的代码智能体 ``` codetrip mcp setup --dry-run codetrip mcp setup ``` 安装命令会检测受支持的客户端，并保留不相关的 MCP server。如果您的客户端已经在运行，请重启客户端，然后尝试： 使用 `codetrip mcp setup codex` 可以定向安装特定客户端（或者 `claude`、`cursor`、`vscode` 或 `copilot`）。仅在替换现有的 Codetrip 条目时才使用 `--force`。 ## 为什么需要代码图？ | 纯文本或向量搜索 | Codetrip | |---|---| | 查找相似或匹配的文本 | 解析符号以及带类型的依赖关系 | | 显示孤立的匹配项 | 连接调用、导入、继承和重写 | | 不清楚依赖方向 | 遍历正向或反向依赖 | | 将变更影响留给读者判断 | 将 Git 变更映射到符号和受影响的代码 | | 将重命名的匹配结果一视同仁 | 将语义引用与待审查候选项区分开来 | Codetrip 仍然包含快速的源码和符号搜索。代码图在单纯搜索不够用时，提供了额外的结构上下文。 ## 对比分析 这些项目有重叠之处，但针对不同的使用模式进行了优化： | 项目 | 最适合 | 部署模式 | 当前优势 | |---|---|---|---| | **Codetrip** | 为代码智能体和 CLI 用户提供本地结构上下文 | 单一原生可执行文件；嵌入式 Go 库；本地 MCP | 原子级仓库快照、Git diff 到符号的影响分析、带类型的图查询、五个发布目标、无需依赖模型服务 | | [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | 丰富的智能体工作流和图探索 | Node/npm CLI、MCP、skills/hooks 和 Web UI | 增量更新、执行流、集群、Cypher、仓库组、PDG/taint 工具、广泛的智能体自动化 | | [Serena](https://github.com/oraios/serena) | 类 IDE 的语义检索和源码编辑 | 由 language servers 或其 JetBrains 插件支持的 MCP | 40 多种 language-server 集成、符号化编辑、重构、诊断以及可选的 IDE 级分析 | | [Sourcegraph](https://sourcegraph.com/docs) | 组织级别的搜索和导航 | 托管的单租户/企业级平台以及 IDE/Web 集成 | 多仓库和多代码托管平台搜索、分支/历史搜索、基于 SCIP 的精确导航、企业级规模 | 当本地部署的简便性、原生二进制文件、确定性的仓库快照和可嵌入式比 Web UI 或智能体工作流套件更重要时，请选择 Codetrip。如果您现在想要一个更广泛的图智能体环境，请选择 GitNexus；如果智能体需要执行 IDE 支持的编辑和重构，请选择 Serena；如果面临的是组织级别的代码发现和治理问题，请选择 Sourcegraph。 本表比较的是已公开的产品形态，而非相对的速度或准确性。Codetrip 尚未发布一对一的竞品基准测试。 ## 您可以做什么 | 目标 | 命令 | |---|---| | 查找符号 | `codetrip search "ParseConfig" --repo project` | | 搜索源码或文档 | `codetrip source 'lang:go ParseConfig' --repo project` | | 解释符号及其相邻项 | `codetrip context ParseConfig --repo project` | | 查找反向变更影响 | `codetrip impact ParseConfig --repo project --format tree` | | 分析 Git diff | `codetrip diff HEAD~1 --target HEAD --repo project` | | 追踪有向路径 | `codetrip path LoadConfig ParseConfig --repo project` | | 检查循环和图完整性 | `codetrip check --repo project` | | 在不编辑文件的情况下规划重命名 | `codetrip rename ParseConfig NewName --repo project` | MCP server 暴露了相同的核心操作： ``` list search source context impact check diff rename traverse path ``` ## 支持的语言 Codetrip 可以解析 Go、TypeScript/TSX、JavaScript/JSX、Python、Java、C、C++、C#、Rust、PHP、Swift 和 Kotlin。具有语言感知能力的解析已包含在仓库的语义测试套件中，但关系精度因语言以及动态或反射代码而异。当引用无法在语义上进行解析时，文本候选项仍然可用。所有 12 种语言均通过了精心挑选的语义测试关卡；对于真实仓库的精度测试和基于源码的召回率审查，C++ 已完成，Kotlin 正在进行中，其余语言已规划。请参阅[语义质量报告](docs/QUALITY.md)。 ## 真实代码库上的实测数据 在配备 16 GB RAM 的 Apple M2 Pro 上进行冷全量快照索引（禁用 embedding）的性能表现： | 代码库 | 语言 | 文件数 | 节点数 | 边数 | 耗时 | 索引大小 | |---|---|---:|---:|---:|---:|---:| | Kubernetes | Go | 17,389 | 107,385 | 277,588 | 121.11 s | 713.5 MiB | | RocksDB | C++ | 2,006 | 52,507 | 198,900 | 204.62 s | 434.5 MiB | | RocketMQ | Java | 2,552 | 29,535 | 141,874 | 29.16 s | 342.7 MiB | | FastAPI | Python | 2,714 | 8,913 | 15,474 | 7.53 s | 68.4 MiB | | Exposed | Kotlin | 5,173 | 25,763 | 70,030 | 26.65 s | 443.9 MiB | 所有 12 种支持的语言均完成了相同的冷索引过程。请参阅[完整结果、提交记录和方法论](docs/BENCHMARKS.md)。这些是 Codetrip 的测量数据，而非跨工具对比；时间和大小会因硬件、检出内容、操作系统和版本的不同而有所差异。 ## 可选的语义搜索 词法搜索和图分析不需要 embedding 模型。要添加语义检索功能，请将 Codetrip 指向兼容 OpenAI 的 embeddings endpoint： ``` codetrip embed --repo project \ --endpoint http://localhost:11434/v1/embeddings \ --model nomic-embed-text codetrip hybrid "configuration loading" --repo project \ --endpoint http://localhost:11434/v1/embeddings \ --model nomic-embed-text ``` 向量会针对每个代码库分别进行持久化存储。此外还提供可选的 int8 量化功能，以生成更小的索引。 ## 工作原理 ``` +-------------------+ +---------------------------+ | Repository | | Typed Code Graph | | .go .ts .py ... | ----> | symbols, calls, imports, | | source + Git | | inheritance, processes | +-------------------+ +-------------+-------------+ | +---------------------+---------------------+ | | | Symbol/source Graph traversal Optional vectors search and change impact + hybrid ranking | | | +---------------------+---------------------+ | Go library / CLI / MCP ``` 每个仓库都有独立的存储，并作为原子快照发布。持久化图是权威数据源；搜索索引和向量是仓库范围内的派生数据。构建替换快照永远不会暴露处于部分更新状态的活跃快照。 ## Go 库 ``` engine, err := codetrip.Open("./.codetrip") if err != nil { log.Fatal(err) } defer engine.Close() _, err = engine.IndexRepo(ctx, "/path/to/project", codetrip.WithRepoName("project"), codetrip.WithReplaceExisting(true), ) result, err := engine.Search(ctx, &codetrip.SearchRequest{ Repo: "project", Query: "ParseConfig", Limit: 20, }) impact, err := engine.Impact(ctx, &codetrip.ImpactRequest{ Repo: "project", NodeID: result.Results[0].NodeID, MaxDepth: 3, }) ``` 公共 API 还提供了源码搜索和混合搜索、上下文分析、结构检查、Git 变更分析、重命名规划、图遍历、最短路径、仓库管理、CSV 导出、指标统计和配置选项。 ## 导出和检查 将完整的活跃图导出为确定性的 CSV，以及包含行数和 SHA-256 校验和的清单文件： ``` codetrip export --repo project --output ./exports/project ``` 为了方便解析器和语言调优，`index --export` 也可以在持久化之前捕获验证 CSV。详情请参阅用户指南。 ## 已知限制 发布的二进制文件适用于 Linux 和 macOS（amd64/arm64 架构）以及 Windows（amd64 架构）。Linux 产物采用静态链接；macOS 产物仅使用系统库；Windows 产物不依赖编译器运行时。 Linux 和 macOS 使用原生的高吞吐量源码搜索后端。Windows 使用具有相同查询功能的可移植后端，但在处理大型仓库时可能较慢。重命名功能仅用于分析，绝不编辑源码。Git diff 分析不包含未跟踪的文件，除非将它们添加并建立索引。 - 目前重新索引会构建一个完整的替换快照。这种做法一致且对读者安全，但对于频繁更改的大型仓库来说，消耗的资源较大。 - 尚未支持解析跨仓库的依赖关系。 - 动态分发、反射、生成代码、宏和运行时模块加载可能会降低关系解析的精度。系统会显示置信度和文本兜底候选项，而不是将其作为确切结果呈现。 - 对各语言的支持精度并不均等。所有支持的语言均已发布测试夹具结果，但对真实仓库的精度和召回率审查仅涵盖了部分语言矩阵。 - CLI 正逐步提供更丰富的人类可读视图；目前大多数命令仍返回 JSON，而 `impact` 额外支持 `--format tree`。 - Codetrip 没有 Web UI，也不执行源码编辑。 ## 路线图 当前优先事项： - 实现增量索引而不削弱原子发布特性 - 跨仓库分析和契约感知的影响分析 - 增强对动态语言的解析能力 - 提供更易读的 CLI 输出 - 自动发现仓库并简化仓库选择过程 - 针对提交前分析、调试和代码审查提供更多 MCP 工作流 长期的发展方向是构建一个分布式、云/本地混合的代码智能引擎，同时保留当前的嵌入式和本地优先路径。发现了重要的缺失功能或工作流？欢迎提交 [issue](https://github.com/mengshi02/codetrip/issues)——或者给仓库加星 以跟进路线图。 ## 文档 - [English user guide](docs/USER_GUIDE.md) - [中文用户手册](docs/USER_GUIDE_ZH.md) - [语义质量报告](docs/QUALITY.md) - [索引基准测试](docs/BENCHMARKS.md) - [更新日志](CHANGELOG.md) - [贡献指南](CONTRIBUTING.md) - [安全策略](SECURITY.md) ## 开发 ``` go test ./... go vet ./... ``` ## 许可证 [MIT](LICENSE)

标签：EVTX分析, 文档结构分析, 日志审计, 网络安全研究