ghcr.io/abhigyanpatwari/gitnexus:1.6.6-rc.149

GitNexus

[!IMPORTANT] GitNexus没有官方加密货币、或硬币。任何在Pump.fun或其他平台上使用GitNexus名称的/硬币均与本项目或其维护者无关联、未获认可且非本项目创建。请勿购买任何声称与GitNexus相关的加密货币。

加入官方***讨论想法、问题等！

企业版（SaaS 和自托管） - akonlabs.com

为智能体上下文构建神经系统。

将任何代码库索引到知识图谱中——包括所有依赖项、调用链、集群和执行流程——然后通过智能工具公开，确保AI智能体不会遗漏任何代码。

类似于DeepWiki，但更深入。 DeepWiki帮助你_理解_代码。GitNexus让你_分析_代码——因为知识图谱会跟踪每一种关系，而不仅仅是描述。

概要： Web UI 是与任何仓库快速交互的方式。CLI + MCP 则是让你的AI智能体真正可靠的方法——它为Cursor、Claude Code、Antigravity、Codex等工具提供代码库的深度架构视图，防止它们遗漏依赖项、破坏调用链和进行盲目编辑。即使是较小的模型也能获得完整的架构清晰度，使其能够与大型模型竞争。

---

星级历史

使用GitNexus的两种方式

桥接模式： gitnexus serve 可连接两者——Web UI会自动检测本地服务器，并能浏览所有通过CLI索引的仓库，无需重新上传或重新索引。

---

企业版

GitNexus提供企业版——既可以是完全托管的SaaS，也可以是自托管部署。OSS版本也可通过适当许可进行商业使用。

企业版包括：

• PR Review - 拉取请求的自动影响范围分析
• Auto-updating Code Wiki - 始终保持最新的文档（Code Wiki在OSS版本中也可用）
• Auto-reindexing - 知识图谱自动保持更新
• Multi-repo support - 跨仓库的统一图谱
• OCaml support - 额外的语言支持
• Priority feature/language support - 请求新语言或功能的优先级支持

即将推出：

• 自动回归分析
• 端到端测试生成

👉 了解更多：akonlabs.com

💬 商业许可或企业咨询，请通过联系我们，或发送邮件至

---

开发

• ARCHITECTURE.md — 包结构、索引→图谱→MCP流程、代码修改位置
• RUNBOOK.md — 分析、嵌入、过时索引、MCP恢复、CI代码片段
• GUARDRAILS.md — 贡献者和智能体的安全规则与操作“信号”
• CONTRIBUTING.md — 许可、设置、提交和拉取请求
• TESTING.md — gitnexus 和 gitnexus-web 的测试命令

CLI + MCP（推荐）

CLI会索引你的仓库并运行MCP服务器，为AI智能体提供深度代码库感知能力。

快速开始

# 索引你的仓库（从仓库根目录运行）
npx gitnexus analyze

就是这样。此命令会索引代码库、安装智能体技能、注册Claude Code钩子，并创建AGENTS.md/CLAUDE.md上下文文件——一步完成。

[!NOTE] 使用npm 11.x？安装过程中npx可能会崩溃并显示Cannot destructure property 'package' of 'node.target'（这是npm/arborist的bug，在GitNexus运行前发生）。请改用pnpm——它会显式构建原生依赖：

> pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze
>

或者全局安装（npm install -g gitnexus@latest）并运行gitnexus analyze。参见https://github.com/abhigyanpatwari/GitNexus/issues/1939%E3%80%82

要为编辑器配置MCP，运行一次npx gitnexus setup——或按以下步骤手动设置。

[!NOTE] 更快安装（无需C++工具链）：在npm install -g gitnexus前设置GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1，可跳过预编译语法的构建（tree-sitter-dart、tree-sitter-proto、tree-sitter-swift）。Dart/Proto/Swift文件将不会被解析，但安装可在几秒钟内完成，无需python3/make/g++。仅严格支持=1——任何其他值都会触发重新构建。

MCP设置

gitnexus setup会自动检测你的编辑器并写入正确的全局MCP配置。只需运行一次。

编辑器支持

[!NOTE] Claude Code 集成最深入：MCP工具 + 智能体技能 + PreToolUse钩子（通过图谱上下文丰富搜索） + PostToolUse钩子（提交后检测过时索引并提示智能体重索引）。

[!NOTE] ¹ Antigravity钩子遵循*** CLI钩子参考（Antigravity 2.0是*** CLI的官方继任者）。增强在AfterTool中运行，因为协议中BeforeTool没有上下文注入通道——智能体通过hookSpecificOutput.additionalContext看到附加到工具结果的图谱上下文。成功执行git commit/merge/rebase/cherry-pick/pull后，过时索引提示会进入同一通道。如果Antigravity特定的钩子文档与 CLI的文档出现差异，架构可能会演变；实现将跟踪这些变化。

社区集成

由社区构建——非官方维护，但值得一试。

在 GitNexus 上构建了项目？提交 PR 将其添加到这里！

如果您倾向于手动配置：

推荐最快启动方式： 全局安装 gitnexus（npm i -g gitnexus）并运行 gitnexus setup——这会写入绝对路径的 MCP 配置，完全绕过 npx。下面的固定 npx 代码片段是快速启动的备选方案；在缓存未命中时，npx 安装可能会超过 Claude Code 的默认 MCP_TIMEOUT（约 30 秒）。

Claude Code（完全支持 — MCP + 技能 + 钩子）：

# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

Codex（完全支持 — MCP + 技能）：

codex mcp add gitnexus -- npx -y gitnexus@latest mcp

Cursor（~/.cursor/mcp.json — 全局配置，适用于所有项目）：

{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}

Antigravity (Google) — ~/.gemini/antigravity/mcp_config.json：

{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}

gitnexus setup 还会将 AfterTool 条目合并到 ~/.gemini/settings.json（遵循标准 *** CLI 钩子 schema），并将技能安装到 ~/.gemini/antigravity/skills/。现有用户钩子会被保留。钩子适配器路径会在安装时重写，因此请运行 gitnexus setup 而非手动编辑。

OpenCode（~/.config/opencode/config.json）：

{
"mcp": {
"gitnexus": {
"type": "local",
"command": ["gitnexus", "mcp"]
}
}
}

Codex（系统范围：~/.codex/config.toml；项目范围：.codex/config.toml）：

[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]

CLI 命令

gitnexus setup # 为编辑器配置 MCP（一次性操作）
gitnexus analyze [path] # 索引仓库（或更新过期索引）
gitnexus analyze --repair-fts # 快速路径：仅在现有索引数据上重建/验证 FTS 索引
gitnexus analyze --force # 完全重建：重新解析 + 图重建 + FTS 重建
gitnexus analyze --skills # 从检测到的社区生成仓库特定技能文件
gitnexus analyze --skip-embeddings # 跳过嵌入生成（更快）
gitnexus analyze --skip-agents-md # 保留自定义 AGENTS.md/CLAUDE.md 中 gitnexus 部分的编辑
gitnexus analyze --skip-skills # 跳过安装 .claude/skills/gitnexus/ 技能文件
gitnexus analyze --default-branch develop # 生成回归比较示例时使用的分支（base_ref）
gitnexus analyze --skip-git # 索引非 Git 仓库的文件夹
gitnexus analyze --embeddings [limit] # 启用嵌入生成（较慢，搜索效果更好）
gitnexus analyze --verbose # 当解析器不可用时记录跳过的文件
gitnexus analyze --worker-timeout 60 # 增加工作进程空闲超时以处理缓慢解析
gitnexus analyze --wal-checkpoint-threshold 67108864 # 64 MiB。控制 LadybugDB WAL 自动检查点阈值（默认：67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）
gitnexus analyze --workers # 解析工作进程池大小（默认：核心数-1，上限 16；0 = 顺序执行）
gitnexus mcp # 启动 MCP 服务器（标准输入输出）—— 服务所有已索引仓库
gitnexus serve # 启动本地 HTTP 服务器（多仓库）以连接 Web UI
gitnexus list # 列出所有已索引仓库
gitnexus status # 显示当前仓库的索引状态
gitnexus clean # 删除当前仓库的索引
gitnexus clean --all --force # 删除所有索引
gitnexus wiki [path] # 从知识图谱生成仓库 Wiki
gitnexus wiki --model # 使用自定义 LLM 模型生成 Wiki（默认：gpt-4o-mini）
gitnexus wiki --base-url # 使用自定义 LLM API 基础 URL 生成 Wiki
gitnexus publish # 通知 understand-quickly 注册表（可选加入，见下文）

# 仓库组（多仓库/单体仓库服务跟踪）
gitnexus group create <name> # 创建仓库组
gitnexus group add <name> <hierarchy-path> <repo-name> # 将仓库添加到组。<hierarchy-path> 是层级路径（例如 hr/hiring/backend）；<repo-name> 是注册表中的仓库名称（见 `gitnexus list`）
gitnexus group remove <name> <hierarchy-path> # 按层级路径从组中移除仓库
gitnexus group list [name] # 列出所有组，或显示某个组的配置
gitnexus group sync <name> # 提取契约并跨仓库/服务匹配
gitnexus group contracts <name> # 检查提取的契约和交叉链接
gitnexus group query <name> <search-term> # 搜索组内所有仓库的执行流
gitnexus group status <name> # 检查组内仓库的过期状态

如果 analyze 在大型或特殊仓库上报告工作进程解析超时，它会继续运行并安全回退。要为缓慢的工作进程任务提供更多时间，请使用 gitnexus analyze --worker-timeout 60 或设置 GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000。对于非常大的文件，GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES 控制工作进程任务的字节预算。

嵌入节点限制

gitnexus analyze --embeddings 生成语义搜索向量时默认有 50,000 节点的安全上限，以保护大型仓库上的内存。当确认主机有足够内存处理更大图谱时，可覆盖此上限，或为一次性完整嵌入运行完全禁用上限。

# 使用默认 50,000 节点安全上限生成嵌入
gitnexus analyze --embeddings

# 完全禁用安全上限
gitnexus analyze --embeddings 0

# 使用自定义上限
gitnexus analyze --embeddings 100000

如果在大型仓库上跳过了嵌入，可能是索引图谱超出了默认安全上限。使用 gitnexus analyze --embeddings 0 重新运行以移除上限，或使用 gitnexus analyze --embeddings <number> 选择更高限制同时仍保持内存受限。

项目配置（.gitnexusrc）

在仓库根目录提交 .gitnexusrc JSON 文件，可为项目预配置重复的 analyze 选项，无需每次运行都重复传递相同标志。该文件从解析的仓库根目录读取（而非 .gitnexus/，后者是被 git 忽略的索引存储目录）。CLI 标志始终覆盖 .gitnexusrc。

{
// 生成回归比较示例时使用的默认分支（base_ref）。
// 使用此配置可避免 `develop`/`master` 分支的项目在每次分析时被重写为 "main"。（别名："branch"。）
"defaultBranch": "develop",
"skipContextFiles": true, // skipAgentsMd 的别名：保留您自己的 AGENTS.md/CLAUDE.md
"skipSkills": true, // 不安装 .claude/skills/gitnexus/
"embeddings": true, // 默认生成嵌入
"workerTimeout": 60
}

也接受嵌套的 analyze 块（并覆盖同一选项的扁平键）：

{ "analyze": { "defaultBranch": "develop", "skipSkills": true } }

注意：

• 默认分支的解析顺序为：--default-branch

.gitnexusrc 中的 defaultBranch/branch 自动检测的 origin/HEAD main。

• skipContextFiles / skipAiContext 是 skipAgentsMd 的别名——它们仅跳过 AGENTS.md / CLAUDE.md 块。它们不意味着 skipSkills。indexOnly 是更强的选项，会跳过所有文件注入。
• 支持的键：defaultBranch（branch）、skipAgentsMd（skipContextFiles、skipAiContext）、skipSkills、indexOnly、stats/noStats、embeddings、dropEmbeddings、name、allowDuplicateName、maxFileSize、workerTimeout、walCheckpointThreshold、workers、embeddingThreads、embeddingBatchSize、embeddingSubBatchSize、embeddingDevice。
• 该文件仅支持JSON格式。未知键和无效值会在分析开始前快速失败，并返回可操作的错误。

环境变量

大多数 analyze 控制项也可作为 CLI 标志（--workers、--worker-timeout、--max-file-size、--verbose）。当需要在每次运行时重复相同的标志，或者从已管理自身环境的长期运行主机（MCP 服务器、评估服务器、CI shell）调用 GitNexus 时，使用环境变量形式。CLI 标志优先于环境变量；环境变量优先于内置默认值。

发布到 understand-quickly（可选）

多仓库MCP架构

GitNexus 使用全局注册表，因此一个 MCP 服务器可以服务多个已索引仓库。无需每个项目单独配置 MCP——只需设置一次，即可在所有地方使用。

flowchart TD
subgraph CLI [CLI 命令]
Setup["gitnexus setup"]
Analyze["gitnexus analyze"]
Clean["gitnexus clean"]
List["gitnexus list"]
end

subgraph Registry ["~/.gitnexus/"]
RegFile["registry.json"]
end

subgraph Repos [项目仓库]
RepoA[仓库 A 中的 .gitnexus/]
RepoB[仓库 B 中的 .gitnexus/]
end

subgraph MCP [MCP 服务器]
Server["server.ts"]
Backend["LocalBackend"]
Pool["连接池"]
ConnA["LadybugDB 连接 A"]
ConnB["LadybugDB 连接 B"]
end

Setup -->|"写入全局 MCP 配置"| CursorConfig["~/.cursor/mcp.json"]
Analyze -->|"注册仓库"| RegFile
Analyze -->|"存储索引"| RepoA
Clean -->|"注销仓库"| RegFile
List -->|"读取"| RegFile
Server -->|"读取注册表"| RegFile
Server --> Backend
Backend --> Pool
Pool -->|"延迟打开"| ConnA
Pool -->|"延迟打开"| ConnB
ConnA -->|"查询"| RepoA
ConnB -->|"查询"| RepoB

工作原理： 每次执行 gitnexus analyze 时，索引会存储在仓库内的 .gitnexus/ 目录中（可移植，已加入 gitignore），并在 ~/.gitnexus/registry.json 中注册一个指针。当 AI 智能体启动时，MCP 服务器读取注册表并可服务任何已索引仓库。LadybugDB 连接在首次查询时延迟打开，闲置 5 分钟后关闭（最大 5 个并发连接）。如果仅索引了一个仓库，则所有工具的 repo 参数为可选——智能体无需进行任何更改。

版本控制与供应链保护

Docker 镜像与 npm 包版本锁定：

• 稳定版镜像仅从 vX.Y.Z git 标签发布（通过标签推送直接触发 docker.yml 工作流），且工作流会拒绝构建，除非标签与 gitnexus/package.json 中的版本完全匹配。因此，ghcr.io/abhigyanpatwari/gitnexus:1.6.2（及其 Docker Hub 镜像 akonlabs/gitnexus:1.6.2）与 npm install gitnexus@1.6.2 的发布版本完全一致——无版本偏移，无来自 main 分支的浮动构建。两个 registry 均从同一构建步骤获得相同的摘要，因此可从任一 registry 拉取镜像，签名验证结果完全一致。
• 候选发布版镜像（例如 :1.7.0-rc.1）与每个 RC 版本的 npm 发布同步发布。它们由 publish.yml 在 RC 标签创建并推送后，调用 docker.yml 作为可重用工作流构建。
• :latest 标签仅通过 Docker 元数据操作从非预发布标签自动提升，因此它始终指向真实的、已发布到 npm 的版本。

两个镜像均使用工作流的 GitHub OIDC 身份通过 https://docs.sigstore.dev/cosign/signing/overview/ 进行签名，并附带构建来源和 SBOM 证明。这是您抵御供应链的保护措施**：即使**者在其他地方重新发布同名镜像（或通过某种方式推送到拼写相似的 registry），他们也无法伪造与 abhigyanpatwari/GitNexus 的 docker.yml 绑定的 Cosign 签名。在拉取到敏感环境前务必进行验证：

稳定版发布 — 从 v* 标签引用签名：

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
--certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?

该正则表达式将证书身份固定到本仓库中**从 `v*` 标签运行**的 `docker.yml` 工作流——拒绝未签名镜像、由其他工作流签名的镜像以及从未受保护引用签名的镜像。两个 registry 的正则表达式相同，因为两组标签在同一工作流运行中以相同摘要进行了签名。

**候选发布版** — 从 `refs/heads/main` 签名（当 `publish.yml` 将 `docker.yml` 作为可重用工作流调用时的调用者引用）：
```bash
cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
--certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
--certificate-oidc-issuer [***]

您还可以检查构建来源和 SBOM：

cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
--predicate-type https://slsa.dev/provenance/v1

Kubernetes：在准入阶段强制签名验证

对于 Kubernetes 部署，部署捆绑的 ClusterImagePolicy，以便 https://docs.sigstore.dev/policy-controller/overview/ 拒绝任何 GitNexus pod，其镜像未由本仓库中从 vX.Y.Z 标签运行的 docker.yml 签名——与上述 cosign verify 代码片段固定的身份相同。

# 1. 安装控制器（一次性，集群范围）
helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
helm install policy-controller -n cosign-system --create-namespace \
sigstore/policy-controller

# 2. 启用命名空间
kubectl label namespace policy.sigstore.dev/include=true

# 3. 应用策略
kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml

此后，尝试部署未签名镜像——或由 abhigyanpatwari/GitNexus 的 docker.yml 以外的任何实体在 v* 标签签名的镜像——将在 pod 创建前被准入 webhook 拒绝。这将可验证的签名转化为强制策略，这是大多数集群实际需要的供应链控制。

Wiki 生成

从知识图谱生成由 LLM 驱动的文档：

# 需要 LLM API 密钥（OPENAI_API_KEY 等）
gitnexus wiki

# 使用自定义模型或提供商
gitnexus wiki --model gpt-4o
gitnexus wiki --base-url https://api.***.com/v1

# 强制完全重新生成
gitnexus wiki --force

--certificate-oidc-issuer https://token.actions.githubusercontent.com

相同签名可验证 Docker Hub 镜像（摘要一致）：

cosign verify docker.io/akonlabs/gitnexus:1.6.2
--certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?

该正则表达式将证书身份固定到本仓库中从 CODE_TOKEN_186 标签运行的 CODE_TOKEN_187 工作流——拒绝未签名镜像、由其他工作流签名的镜像以及从未受保护引用签名的镜像。两个 registry 的正则表达式相同，因为两组标签在同一工作流运行中以相同摘要进行了签名。

候选发布版 — 从 CODE_TOKEN_188 签名（当 CODE_TOKEN_189 将 CODE_TOKEN_190 作为可重用工作流调用时的调用者引用）：

CODE_TOKEN_14

您还可以检查构建来源和 SBOM：

CODE_TOKEN_15

Kubernetes：在准入阶段强制签名验证

对于 Kubernetes 部署，部署捆绑的 CODE_TOKEN_191，以便 https://docs.sigstore.dev/policy-controller/overview/ 拒绝任何 GitNexus pod，其镜像未由本仓库中从 CODE_TOKEN_192 标签运行的 CODE_TOKEN_193 签名——与上述 CODE_TOKEN_194 代码片段固定的身份相同。

CODE_TOKEN_16

此后，尝试部署未签名镜像——或由 CODE_TOKEN_195 的 CODE_TOKEN_196 以外的任何实体在 CODE_TOKEN_197 标签签名的镜像——将在 pod 创建前被准入 webhook 拒绝。这将可验证的签名转化为强制策略，这是大多数集群实际需要的供应链控制。

Wiki 生成

从知识图谱生成由 LLM 驱动的文档：

CODE_TOKEN_17
--certificate-oidc-issuer https://token.actions.githubusercontent.com

该正则表达式将证书身份固定到本仓库中**从 __CODE_TOKEN_186__ 标签运行**的 __CODE_TOKEN_187__ 工作流——拒绝未签名镜像、由其他工作流签名的镜像以及从未受保护引用签名的镜像。两个 registry 的正则表达式相同，因为两组标签在同一工作流运行中以相同摘要进行了签名。

**候选发布版** — 从 __CODE_TOKEN_188__ 签名（当 __CODE_TOKEN_189__ 将 __CODE_TOKEN_190__ 作为可重用工作流调用时的调用者引用）：

__CODE_TOKEN_14__

您还可以检查构建来源和 SBOM：

__CODE_TOKEN_15__

#### Kubernetes：在准入阶段强制签名验证

对于 Kubernetes 部署，部署捆绑的 __CODE_TOKEN_191__，以便 [Sigstore policy-controller][policy-controller] 拒绝任何 GitNexus pod，其镜像未由本仓库中从 __CODE_TOKEN_192__ 标签运行的 __CODE_TOKEN_193__ 签名——与上述 __CODE_TOKEN_194__ 代码片段固定的身份相同。

__CODE_TOKEN_16__

此后，尝试部署未签名镜像——或由 __CODE_TOKEN_195__ 的 __CODE_TOKEN_196__ 以外的任何实体在 __CODE_TOKEN_197__ 标签签名的镜像——将在 pod 创建前被准入 webhook 拒绝。这将可验证的签名转化为强制策略，这是大多数集群实际需要的供应链控制。

[cosign-keyless]: https://docs.sigstore.dev/cosign/signing/overview/
[policy-controller]: https://docs.sigstore.dev/policy-controller/overview/

## Wiki 生成

从知识图谱生成由 LLM 驱动的文档：

__CODE_TOKEN_17__