skooch/codebase-memory-zig

# codebase-memory-zig Zig 端口移植自 [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp)，这是一个从源代码仓库构建可搜索知识图谱的 MCP 服务器。 这不是逐行翻译。Zig 端口在内部结构上进行了重构以提升性能，移除了一些功能，引入了混合服务架构（FTS5 + 图结构 + 可选的 SCIP 覆盖层），并提供了 C 语言原版所不具备的工具链。 **该项目目前尚未完成，我仍在移植过程中。请暂时不要提交错误报告！** ## 与原版的一些差异 | 领域 | 变更内容 | 影响 | |------|-------------|--------| | 冷索引 | 比所有基准测试快 3.2 倍至 8.2 倍 | 小型仓库索引约 13 毫秒（对比 48 毫秒）；中型仓库约 1.4 秒（对比 11.2 秒） | | 全文搜索 | 使用 `unicode61` 分词器的 SQLite FTS5 虚拟表 | 无需启动 grep 子进程即可支持前缀匹配和基于令牌的排名 | | 查询路由 | `query_router.zig` 将每个工具分发到最佳底层存储 | FTS5 用于 `search_code`，图结构用于 `trace_call_path`，SCIP 用于增强 | | SCIP 侧车 | 可选的 `.codebase-memory/scip.json` 导入 | 精确的类型/符号元数据来自语言服务器，而不会阻塞基础索引 | | 图查询 | CTE 预计算 + 批量 BFS 遍历 | 减少数据库往返；替代了 O(N * \|edges\|) 相关子查询 | | JSON 序列化 | 使用 `std.json` 的编译时结构反射 | 相比手动 yyjson 减少约 1000 行代码；新增字段仅需修改结构 | | 错误安全 | 使用 `try`/`errdefer` 的错误联合 | 缺失的错误检查会在编译时失败；事务性索引可防止状态损坏 | | SQLite 调优 | WAL 日志、64 MB 内存映射、`busy_timeout = 10s` | 默认提供更好的并发访问行为和读取吞吐量 | 基准测试数据：[`.benchmark_reports/benchmark_report.md`](.benchmark_reports/benchmark_report.md) —— 详细说明：[`docs/differentiators.md`](docs/differentiators.md) ## 移植进度 Zig 端口覆盖了日常使用的 MCP 表面和核心索引流水线。它还不是 C 子系统的全功能逐项替代。完整细节：[`docs/port-comparison.md`](docs/port-comparison.md) | 领域 | 状态 | 说明 | |------|--------|------| | MCP 工具（14 项中 13 项） | 接近一致 | 除 `ingest_traces`（C 版中也为存根）外均实现 | | 核心索引（结构、定义、导入、调用、引用、语义） | 接近一致 | 并行提取、增量重索引、事务性写入 | | 语言（Python、JavaScript、TypeScript、Rust、Zig） | 接近一致 | 基于 Tree-sitter；其他语言使用启发式回退 | | 相似度检测（`SIMILAR_TO`） | 接近一致 | MinHash/LSH，配合调优阈值 | | 监听器 / 自动重索引 / 运行时生命周期 | 接近一致 | 自适应轮询、持久化运行时数据库、信号驱动关闭 | | CLI 安装/卸载/更新（Codex CLI、Claude Code） | 接近一致 | 原版 10 个代理目标中的 2 个 | | 路由 / 跨服务图 | 部分 | 验证的图模型契约涵盖 HTTP/异步路由调用者、路由节点、处理器、路由关联的数据流与路由摘要；更广泛的框架扩展仍为可选 | | LSP 混合类型解析 | 推迟 | C 语言具备 Go/C/C++ LSP 辅助路径 | | Git 历史 / 配置关联通过 | 接近一致 | 已实现 Git 变更耦合和验证的配置关联片段；更广泛的配置语言/键型扩展仍为可选 | | 图 UI | 已移除 | C 语言提供可选的可视化服务 | | 基础设施扫描（Docker、K8s、Terraform） | 已移除 | 超出项目范围 | ## 要求 - Zig `0.15.2` - SQLite 已内置于仓库 - Tree-sitter 支持已内嵌并通过 `build.zig` 连接 工具版本通过 `mise` 管理： ``` mise install zig version ``` ## 构建 ``` zig build ``` ## 测试 ``` zig build test ``` ## 运行 通过 stdio 启动 MCP 服务器： ``` zig build run ``` 检查 CLI 帮助和版本： ``` zig build run -- --help zig build run -- --version ``` 直接调用单个 CLI 工具： ``` zig build run -- cli [json] ``` 交叉编译目标二进制文件： ``` zig build -Dtarget=aarch64-linux-musl ``` 设置明确的构建版本： ``` zig build -Dversion=1.0.0 ``` ## 代码风格检查 使用 `zig fmt` 强制格式化： ``` zig fmt src/ build.zig ``` 该仓库还使用 `zlint` 进行 Zig 源码检查。请安装适用于你平台的固定版本，将其加入 `PATH`，然后运行： ``` find src -name '*.zig' | zlint -S ``` 固定 `zlint` 版本：`v0.7.9` ## 项目结构 ``` src/ root.zig Module root, re-exports public API main.zig CLI entry point + MCP server startup store.zig SQLite graph store (nodes, edges, projects) graph_buffer.zig In-memory graph buffer before SQLite persistence pipeline.zig Multi-pass indexing pipeline orchestrator mcp.zig MCP JSON-RPC server cypher.zig Cypher query engine discover.zig File discovery and gitignore handling watcher.zig Auto-reindex watcher support registry.zig Symbol and call-edge resolution minhash.zig Near-clone fingerprinting testdata/ interop/ Cross-implementation interoperability fixtures scripts/ run_interop_alignment.sh Compare Zig and C implementations vendored/ sqlite3/ Vendored SQLite amalgamation tree_sitter/ Vendored tree-sitter headers grammars/ Vendored parser grammars ``` ## 文档 - [CLAUDE.md](CLAUDE.md) 用于代理相关的仓库指南 - [docs/differentiators.md](docs/differentiators.md) 说明 Zig 端口相比 C 原版的优势 - [docs/port-comparison.md](docs/port-comparison.md) 用于完整的逐项功能对进度跟踪 - [docs/zig-port-plan.md](docs/zig-port-plan.md) 用于整体移植路线图 - [docs/gap-analysis.md](docs/gap-analysis.md) 用于对进度和剩余差距的分析 ## 验证说明 针对行为或构建变更的典型本地验证： ``` zig build zig build test zig fmt --check src/ build.zig find src -name '*.zig' | zlint -S ```

标签：DoH影响, FTS5, MCP服务器, SCIP, SEO, SQLite, Zig, 代码搜索, 代码智能, 全文检索, 客户端加密, 幻觉缓解, 性能优化, 技术栈, 查询路由, 检测绕过, 混合架构, 源码分析, 索引加速, 编译时反射, 错误安全, 领域分类