GitNexus CLI 命令
以下命令使用 node .gitnexus/run.cjs <command> 运行，其中 run.cjs 是 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。
命令
analyze —— 构建或刷新索引
命令：node .gitnexus/run.cjs analyze
需在项目根目录运行。它会解析所有源文件，构建知识图谱，写入 .gitnexus/，并生成 CLAUDE.md / AGENTS.md 上下文文件。
相关标志：
- --watch：保持 Git 仓库索引最新，采用串行刷新。
- --debounce <ms>：刷新前的观察静默期（默认 300 毫秒）。
- --force：即使已是最新也强制完整重建索引。
- --embeddings：启用嵌入生成以支持语义搜索（默认关闭）。
- --drop-embeddings：重建时丢弃现有嵌入。默认情况下，不带 --embeddings 的 analyze 会保留嵌入。
- --pdg：构建 explain 和 pdg_query 使用的程序依赖层（taint、CDG 和 REACHING_DEF）。
- --spring-actuator <path>：导入可选的 Spring Boot Actuator 映射、beans、conditions、configprops 和 env 快照。会强制完整重建；不支持与 --watch 同时使用。
- --asyncapi-spec <path>：读取可选的 AsyncAPI 3.x 文档（目录或单个文件），并依据其操作生成 Destination 节点。2.x 会被拒绝而非映射。不支持与 --watch 同时使用。
何时运行：首次在项目中使用时、代码发生重大变更后，或当 gitnexus://repo/{name}/context 报告索引已过期时。在 Claude Code 中，PostToolUse 钩子会在 git commit 和 git merge 后检测索引是否过期，并通知代理运行 analyze——该钩子本身不运行 analyze，以避免阻塞代理最长 120 秒，并防止超时导致 KuzuDB 损坏。
对于 Spring 运行时增强，可传入 JSON 包、单个端点 JSON 文件或包含端点文件的目录。只有当 runtimeConfirmed === true 时，路由证据才是权威的；runtimeSource 记录来源，也可能伴随 handler-conflict。env/configprops 的值从不持久化。
索引存储与保留
默认位置为 <repo>/.gitnexus/。可通过环境变量覆盖：
- 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 注入和标准技能安装，因此当这些生成文件需要更新时，请运行一次一次性 analyze。watch 会拒绝一次性或上下文输出标志，包括 --force、嵌入相关标志、--skills、--default-branch、--skip-agents-md、--skip-skills、--no-stats、--self-commit、--index-only 和 --skip-git。它从不拉取远程。定时远程克隆/拉取是另一个命令：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
使用 LLM 从知识图谱生成仓库文档。HTTP 提供者需要 API 密钥（首次使用时保存到 ~/.gitnexus/config.json）。本地 CLI 提供者（--provider cursor|claude|codex|opencode|grok）使用你现有的 CLI 登录。
相关标志：
- --force：强制完整重新生成，也可以用于以不同语言重新生成现有 wiki。
- --provider <name>：LLM 提供者，可选 minimax、openai、openrouter、azure、custom、cursor、claude、codex、opencode 或 grok（默认 minimax）。本地 CLI（cursor、claude、codex、opencode、grok）使用你现有 CLI 登录，可跳过 --api-key。
- --model <model>：LLM 模型（默认 MiniMax-M3）。
- --base-url <url>：LLM API 基础 URL。
- --api-key <key>：LLM API 密钥。
- --concurrency <n>：并行 LLM 调用数（默认 3）。
- --timeout <seconds>：LLM 请求超时秒数（默认禁用）。
- --retries <n>：每个请求的最大 LLM 重试次数（默认 3）。
- --lang <lang>：生成的文档输出语言（如 english、chinese、spanish、japanese）。
- --gist：将 wiki 发布为公开 GitHub Gist。
list —— 显示所有已索引仓库
命令：node .gitnexus/run.cjs list
列出注册在 ~/.gitnexus/registry.json 中的所有仓库。MCP 的 list_repos 工具提供相同信息。
索引之后
- 读取 gitnexus://repo/{name}/context 以验证索引已加载。
- 根据任务使用其他 GitNexus 技能（exploring、debugging、impact-analysis、refactoring）。
故障排除
- “Not inside a git repository”：请在 git 仓库内的目录中运行。
- 重新分析后索引仍过期：等待下一次 MCP 工具调用重新打开已发布索引，通常不超过五秒。
- 嵌入速度慢：省略 --embeddings（默认关闭），或设置 OPENAI_API_KEY 以使用更快的基于 API 的嵌入。