codenexus 0.4.0-rc.1

中文 | English

基于 LadybugDB 与 tree-sitter 的多语言代码知识图谱工具

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

🎯 索引一次，问遍全仓

跑一遍 codenexus index，符号关系即入图，剩下的追问交给图完成：

📋 目录

• ✨ 功能特性
• 🚀 快速开始
• 🛠️ CLI 命令
• 🔌 MCP 集成
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

✨ 功能特性

除上述核心能力外，CodeNexus 还提供 context 上下文组装（--budget token 预算器）、detect_changes 变更检测、rename 重命名影响预检、ask 自然语言入口、ci/lint 架构门禁、taint 污点审计、supply 供应链视图、evolve 演化回放、hub 制品客户端、skill 技能同步、基于 oxcache 的查询结果缓存与 inklog 结构化日志等能力；全部 37 个子命令（外加 mcp 服务模式）的分组清单见 🛠️ CLI 命令 一节，逐命令参数语义与可运行示例见 📖 用户指南 · 命令详解。

🚀 快速开始

📦 安装

# 从 crates.io 安装（默认 full 预设，含全部 21 语言 + 所有功能）
cargo install codenexus

# 从源码构建
git clone https://github.com/Kirky-X/codenexus.git
cd codenexus
cargo install --path .

# 或直接编译
cargo build --release

链接失败排查（openEuler / CentOS 等 GCC ≤ 12 系统）：默认安装会下载预编译的 LadybugDB 二进制，它依赖较新的 libstdc++。若链接报 undefined symbol: std::to_chars(..., _Float128, ...)，用环境变量强制从源码编译即可（需安装 cmake）：

LBUG_BUILD_FROM_SOURCE=1 cargo install codenexus

要求 Rust 1.97.1 及以上（MSRV，Cargo.toml rust-version 与 clippy.toml msrv 一致；CI 工具链当前锁定 1.95，见 .github/workflows/ci.yml）。

🔧 构建预设与 Feature 开关

预设：default = ["full"]

日志系统：inklog 是唯一日志后端（console + file rotation + daily 滚动 + LZ4 压缩），不再提供 tracing-subscriber 可选后端。

# 最小构建（仅 Rust，不含 daemon/analysis）
cargo build --release --no-default-features --features minimal

# 核心构建（C + Rust + Python）
cargo build --release --no-default-features --features core

# 单语言精简构建（例如仅 C）
cargo build --release --no-default-features --features lang-c

# 完整构建（默认，含所有语言 + 全部功能）
cargo build --release

# 含向量嵌入的构建
cargo build --release --features embeddings

💡 最小示例

以下命令改编自 examples/src/bin/basic_indexing.rs 等示例与 📖 用户指南，均可直接运行：

# 1. 索引一个代码仓库（数据库默认写入 .codenexus/<项目名>.lbug）
codenexus index --path /path/to/project --name myproject

# 1b. RAM 优先索引（LZ4 内存压缩，适合中小仓库，更快）
codenexus index --path /path/to/project --name myproject --ram_first true

# 2. 查询函数（Cypher 子集）
codenexus query --cypher "MATCH (f:Function) RETURN f.name LIMIT 10"

# 3. 追踪调用链（可选参数已有内置默认值：depth=5、无路径过滤）
codenexus trace --symbol main --trace_type calls

# 4. 搜索符号（exact / regex / fuzzy + BM25 全文；limit 默认 50）
codenexus search --text "parse" --mode exact
codenexus search --text "authentication logic" --fulltext true

💡 建议：把 .codenexus/ 加入项目的 .gitignore（索引库与日志都在这个目录里，不应入库）。也可以创建 .codenexus/config.json 固化每项目的常用参数（如 ram_first、复杂度阈值），详见 📖 用户指南 · 配置文件。

🧭 核心概念

• 知识图谱模型：源码被解析为 44 种节点与 30 种边构成的属性图，存入 LadybugDB，可用 Cypher 子集查询。
• 严格 flag 风格 CLI：无位置参数，参数为 snake_case 长选项（如 --symbol、--trace_type），布尔选项显式传值（true/false）。可选参数自带内置默认值（如 trace --depth 5、search --limit 50，完整清单见各命令 --help），并可用 .codenexus/config.json 按项目固化。
• 全局 --db 选项：数据库路径默认 .codenexus/<项目名称>.lbug，需置于子命令之前；仅有一个索引时可自动发现。
• 退出码契约：0 成功、1 内部错误、2 无效输入 / 项目不存在 / 查询错误、4 NotFound / 数据库损坏（见 src/service/error.rs）。

增量索引、置信度分层等完整核心约定见 📖 用户指南 · 核心约定。

🛠️ CLI 命令

CodeNexus 提供 37 个子命令（外加 codenexus mcp 服务模式），按功能分组：

• 索引与项目管理：index / daemon / status / list / clean / export / import
• 查询与搜索：query / search / context
• 追踪与影响分析：trace / impact / detect_changes / rename
• 分析工具包：dead_code / architecture / complexity / community / cross_service
• API 审查与架构图：route_map / shape_check / api_impact / tool_map / diagram / arch_diff
• 多智能体与 LSP：setup / hook / mcp / lsp_goto_def / lsp_hover

每个命令的全部参数语义与可运行示例见 📖 用户指南 · 命令详解；复杂度指标与阈值表见 📖 用户指南 · 复杂度分析，死代码检测配置见 📖 用户指南 · 死代码检测。

🔌 MCP 集成

CodeNexus 使用 sdforge 提供 MCP（Model Context Protocol）服务器，经 sdforge mcp stdio 传输暴露 10 个工具（query / trace / impact / search / context / architecture / diagram / arch_diff / dead_code / detect_changes），与同名 CLI 命令共用同一套 #[forge] 定义；每个工具的描述包含参数语义与默认值，服务器以只读方式打开数据库，可与写入进程并存。

# 启动 MCP 服务（stdio）
codenexus mcp [--db <DB_PATH>]

# 自动检测已安装的 Claude Code / Cursor / Codex 并写入 MCP 配置（--force 跳过确认）
codenexus setup

# 输出 PreToolUse/PostToolUse JSON（exit 0，永不阻塞，适合作为智能体钩子）
codenexus hook

各工具的能力说明见 📖 用户指南 · 多智能体集成。

📚 文档

💻 示例

全部 14 个可运行示例位于 examples/ 目录，每个示例对应一个 cargo run --bin 目标（经 examples/Cargo.toml 注册）：

# 运行单个示例
cargo run --manifest-path examples/Cargo.toml --bin basic_indexing

# 运行所有示例
for bin in basic_indexing cypher_query symbol_search call_tracing impact_analysis symbol_context export_import project_lifecycle code_analysis api_surface architecture_diagram daemon_watch git_integration setup_mcp; do
  cargo run --manifest-path examples/Cargo.toml --bin $bin
done

示例通过 IndexFacade 索引源码、QueryFacade 执行查询、TraceFacade 追踪调用，退出时临时目录自动清理。库 API 的完整说明见 📘 API 参考。

🏗️ 架构

CodeNexus 采用「库 + 二进制」双目标 crate：src/lib.rs 暴露公共 API（模型 / 解析 / 存储 / 索引 / 查询 / 追踪 / service 模块），src/main.rs 是 sdforge 驱动的 CLI 二进制；v0.3.2 起 CLI 与 MCP 接口经 sdforge #[forge] 宏统一封装在 src/service/，每个命令定义 core 函数 + CLI wrapper + MCP wrapper。索引方向为「文件发现 → 增量哈希 → 并行解析 → 符号解析 → 批量入库」。

三层源码结构、索引管线流程图、图模型（44 种节点 / 30 种边与置信度分层）、核心语言提取表与 architecture / diagram / arch_diff 命令输出语义，详见 🏗️ 架构文档。

🧪 测试

🎯 测试策略

分层测试策略：src/ 内联 #[cfg(test)] 单元测试 → tests/ 集成测试（CLI 子进程 E2E、全功能套件、MCP/图集成、非 ASCII 路径）→ tests/acceptance/ 8 语言真实开源项目验收（与 gitnexus 交叉验证）→ benches/ 7 组 Criterion 基准回归。测试分层总览与逐条场景矩阵见 🧪 测试场景矩阵。

▶️ 运行命令（与 CI 一致）

# 格式检查（nightly rustfmt，rustfmt.toml 使用 nightly-only 选项）
cargo +nightly fmt --all -- --check

# Clippy 门禁（CI 按 full 与 minimal 双档执行，警告即错误）
cargo +1.95 clippy -- -D warnings
cargo +1.95 clippy --lib --no-default-features --features minimal -- -D warnings

# 测试（CI 矩阵按 minimal / core / full / core,daemon,analysis,complexity / core,lsp,cache / full,embeddings 六档运行）
cargo test --lib --verbose
cargo test --lib --no-default-features --features "core" --verbose

# 覆盖率门禁：行覆盖率不低于 95%（CI coverage job 与 pre-push 钩子执行）
cargo llvm-cov --lib --fail-under-lines 95 --lcov --output-path lcov.info

# 基准测试（--quick 达到统计显著性即停止）
cargo bench -- --quick
cargo bench --bench daemon_bench --features daemon -- --quick

# 安全审计（CI security job：RustSec 公告 + 许可证/禁用依赖）
cargo audit
cargo deny check

CI 还会在每次 push/PR 上运行 CodeQL 静态分析（.github/workflows/codeql.yml），并在 v* tag 推送时触发 Release 工作流（GitHub Release + crates.io 发布）。

📊 测试规模

截至 v0.3.12（#[test] / #[tokio::test] 函数 grep 统计）：约 4600+ 条单元测试（147 个源文件含 #[cfg(test)]）+ 118 条集成测试（8 个文件）+ 8 个验收项目 + 7 组 Criterion 基准；覆盖率门禁为行覆盖 ≥ 95%（CI coverage job 与 pre-push 钩子双重执行）。逐文件分解与完整统计见 🧪 测试场景矩阵 · 统计汇总。

📊 性能

基准套件为 benches/ 下 7 组 Criterion 基准（SLO 阈值来自 docs/PRD.md §5.1）：实测 1000 文件冷启动索引约 3929 files/s（SLO ≥ 100）、单文件增量约 4987 files/s（SLO ≥ 500）、daemon 去抖响应约 2.76 s（SLO ≤ 3 s）；incremental_500_of_1000 为已知未达标项。v0.3.10–v0.3.12 落地的 L1–L7 内存防线（MemoryBudget 三级内存压力、流式 CSV、管线流式化、buffer_pool 封顶等）将 70 GB 主机上的索引峰值内存从约 60 GB 降至约 4 GB。完整实测基线、SLO 表与调优方法见 ⚡ 性能指南，SLO 阈值表见 benches/README.md。

🔒 安全

🛡️ 安全设计

攻击面集中在索引文件（LadybugDB 数据库、.graph.zst 导入制品、tree-sitter 解析输入）与进入 Cypher 子集查询的 query / trace / impact / search 用户输入；代码层面配套 Cypher / 标识符转义、图编辑 dry-run 默认与诊断回执的失败显性化。设计细节与范围界定见 🔒 安全文档。

⛓️ 供应链与门禁

CI 内置四道门禁：cargo-audit（RustSec 公告扫描）、cargo-deny（许可证 / 禁用依赖校验）、CodeQL 静态分析与 pre-commit 密钥扫描。完整清单与忽略项说明见 🔒 安全文档。

🚨 报告安全漏洞

请勿通过公开 issue 报告安全漏洞。请发送邮件至 security@kirky-x.dev，附漏洞描述与影响、复现步骤（最小代码库或 codenexus 命令序列）、版本信息（codenexus --version、Rust 工具链、操作系统）与已知缓解措施。项目承诺 48 小时内确认、5 个工作日内给出初步评估。完整政策（支持版本、披露流程、范围界定）见 🔒 安全文档。

🗺️ 开发路线图

🤝 参与贡献

详细的贡献流程与代码规范请参阅 🤝 贡献指南。

🛠️ 开发环境

工具链为 Rust stable 1.95+（CI 锁定 1.95；Cargo.toml MSRV 1.97.1）+ nightly（cargo fmt 使用 nightly-only 选项），系统依赖包括 C/C++ 编译器（tree-sitter grammar 构建）、libssl-dev、pkg-config 与 protobuf-compiler；提交前运行 cargo +nightly fmt --all -- --check 与 cargo clippy -- -D warnings；pre-commit Git 钩子在 pre-commit 执行文件检查、私钥/密钥扫描、fmt 与 clippy，pre-push 执行 cargo test --lib、覆盖率门禁（≥95%）、cargo audit 与 cargo deny check；提交信息遵循 Conventional Commits（feat、fix、perf、refactor、docs、test、chore、revert）。完整环境搭建步骤见 🤝 贡献指南 · 开发环境。

💖 贡献方式

🐛 报告 Bug

发现问题？ 创建 Issue

💡 功能建议

有好想法？ 提交功能建议

🔧 提交 PR

想贡献代码？ Fork 并提交 PR

报告 Issue 时请附上：CodeNexus 版本（codenexus --version）、Rust 版本、操作系统、完整命令与错误输出、最小复现。安全漏洞请勿公开提交，见 🔒 安全文档。

📋 更新日志

完整版本历史见 📋 更新日志（遵循 Keep a Changelog 格式，语义化版本）。

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

🌟 核心依赖

CodeNexus 站在以下优秀开源项目的肩膀上：

💝 特别感谢

感谢 Rust 社区与所有贡献者。

📞 联系与支持

⭐ Star 历史

如果这个项目对您有帮助，请考虑给它一个 ⭐️！

由 Kirky.X 构建

© 2026 Kirky.X. 保留所有权利。