gitnexus-cli

GitNexus CLI 命令

以下命令使用 node .gitnexus/run.cjs <command> — 该项目本地的运行器由 gitnexus analyze 放在索引旁边。它会在调用时自动选择一个可用的运行器（全局 gitnexus，否则 pnpm dlx，否则 bunx，否则 npx），因此无需假定包管理器，也无需全局安装 — 包括在仅有 bun 的机器上，这类机器完全没有 npm、npx 或 pnpm。

尚未分析，或 node .gitnexus/run.cjs 报告 Cannot find module（被 gitignore 的运行器不存在 — 例如全新克隆或执行过 git clean）？请在项目根目录下用 npx gitnexus analyze 重新生成它，或在仅有 bun 的机器上使用 bunx gitnexus@latest analyze。在 npm 11.x 上，如果 npx 在安装期间崩溃（node.target is null），请先用 npm i -g gitnexus 安装一次（然后运行 gitnexus analyze），或使用 bunx gitnexus@latest analyze，或 pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze。参见 #1939。

命令

analyze — 构建或刷新索引

node .gitnexus/run.cjs analyze

在项目根目录下运行。它会解析所有源文件，构建知识图谱，将其写入 .gitnexus/，并生成 CLAUDE.md / AGENTS.md 上下文文件。

Flag	Effect
--watch	通过串行刷新保持 Git 仓库索引为最新
--debounce <ms>	刷新前的监视静默期（默认：300 ms）
--force	即使已是最新也强制进行完整重新索引
--embeddings	为语义搜索启用嵌入生成（默认关闭）
--drop-embeddings	在重建时丢弃现有嵌入。默认情况下，不带 --embeddings 的 analyze 会保留它们。
--pdg	构建 explain 和 pdg_query 所用的程序依赖层（taint、CDG 和 REACHING_DEF）。
--spring-actuator <path>	导入可选启用的 Spring Boot Actuator 映射、bean、条件、configprops 和环境快照。强制完整重建；不支持与 --watch 一起使用。
--asyncapi-spec <path>	读取可选启用的 AsyncAPI 3.x 文档（目录或单个文件），并根据其操作生成 Destination 节点。2.x 会被拒绝，不会进行映射。不支持与 --watch 一起使用。

何时运行： 在项目中首次运行时、重大代码变更后，或当 gitnexus://repo/{name}/context 报告索引已过期时。在 Claude Code 中，PostToolUse 钩子会在 git commit 和 git merge 后检测到过期，并通知 Agent 运行 analyze — 该钩子本身不运行 analyze，以避免阻塞 Agent 长达 120 秒，并避免超时时导致 KuzuDB 损坏的风险。

对于 Spring 运行时增强，请传入一个 JSON 捆绑包、一个端点 JSON 文件，或一个包含端点文件的目录。仅当 runtimeConfirmed === true 时，路由证据才具有权威性；runtimeSource 记录来源，也可能同时伴随 handler-conflict。环境/configprops 值绝不会被持久化。

索引存储与保留

默认位置为 <repo>/.gitnexus/。可通过环境变量覆盖（README 中也有说明）：

环境变量	作用
GITNEXUS_STORAGE_PATH	一个完整的外部索引目录。若两个存储变量都设置，则以该变量为准。
GITNEXUS_STORAGE_ROOT	绝对根路径；GitNexus 会为每个仓库创建独立的 <repo-basename>-<12-hex>/ 槽位。
GITNEXUS_CONTENT_RETENTION	full（默认）保留文件文本；symbol 保留代码片段；none 仅保留图。

list_repos、gitnexus://repo/{name}/context 以及 HTTP GET /api/repos / GET /api/repo 会暴露 storagePath、contentRetention 和 sourceAvailable。除非保留策略为 full，否则 HTTP /api/file 和 /api/grep 会返回 410。当保留策略为 symbol 时，MCP include_content 仍可能返回符号范围。

对长期运行的本地 Git 仓库，请使用 node .gitnexus/run.cjs analyze --watch。它会执行一次初始分析，将扫描器认可的文件变更加入队列，并以有界退避重试完整的失败批次。Watch 刷新仅更新图：它会跳过 AGENTS.md / CLAUDE.md 注入和标准 skill 安装，因此当这些生成文件需要更新时，请运行一次性的 analyze。Watch 会拒绝一次性或上下文输出相关标志，包括 --force、嵌入相关标志、--skills、--default-branch、--skip-agents-md、--skip-skills、--no-stats、--self-commit、--index-only 和 --skip-git。它绝不会拉取远程。定时的远程 clone/pull 是另一个命令：gitnexus auto-sync。裸 gitnexus watch 已被保留，不会启动这两个任务中的任何一个。运行中的 MCP 和 serve 进程会定期检查是否发布了替代版本，并在无需重启的情况下重新打开它。MCP 检查被限流为每五秒一次，因此在下次检查前的一次工具调用可能会短暂使用先前的索引。

status — 检查索引新鲜度

node .gitnexus/run.cjs status

显示当前仓库是否有 GitNexus 索引、上次更新时间以及符号/关系数量。可用它检查是否需要重新索引。

clean — 删除索引

node .gitnexus/run.cjs clean

删除 .gitnexus/ 目录，并从全局注册表中注销该仓库。如果索引已损坏，或从项目中移除 GitNexus 之后，可在重新索引前使用。

标志	作用
--force	跳过确认提示
--all	清理所有已索引仓库，而不只是当前仓库

wiki — 从图生成文档

node .gitnexus/run.cjs wiki

使用大模型从知识图谱生成仓库文档。HTTP 提供方需要 API key（首次使用时保存到 ~/.gitnexus/config.json）。本地 CLI 提供方（--provider cursor|claude|codex|opencode|grok）使用你现有的 CLI 登录。

标志	作用
--force	强制完整重新生成，若要用不同语言重新生成现有 wiki 也需要该标志
--provider <name>	大模型提供方：minimax、openai、openrouter、azure、custom、cursor、claude、codex、opencode 或 grok（默认：minimax）。本地 CLI（cursor、claude、codex、opencode、grok）使用你现有的 CLI 登录并跳过 --api-key。
--model <model>	大模型（默认：MiniMax-M3）
--base-url <url>	大模型 API base URL
--api-key <key>	大模型 API key
--concurrency <n>	并行大模型调用数（默认：3）
--timeout <seconds>	大模型请求超时时间（秒，默认：禁用）
--retries <n>	每个请求的最大大模型重试次数（默认：3）
--lang <lang>	生成文档的输出语言（例如 english、chinese、spanish、japanese）
--gist	将 wiki 发布为公开的 GitHub Gist

list — 显示所有已索引的仓库

node .gitnexus/run.cjs list

列出在 ~/.gitnexus/registry.json 中注册的所有仓库。MCP list_repos 工具提供相同的信息。

索引之后

1. 读取 gitnexus://repo/{name}/context 以验证索引已加载
2. 使用其他 GitNexus 技能（exploring、debugging、impact-analysis、refactoring）来完成你的任务

故障排除

• "Not inside a git repository"：从 git 仓库内的目录运行
• 重新分析后索引陈旧：等待下一次 MCP 工具调用重新打开已发布的索引；这通常不超过五秒
• 嵌入速度慢：省略 --embeddings（默认关闭）或设置 OPENAI_API_KEY 以使用基于 API 的更快嵌入