GitNexus CLI 实战指南：run.cjs 本地运行器与 analyze/status/clean/wiki/list 五大核心命令

本文基于 GitNexus 仓库中的 CLI 技能文档 SKILL.md 撰写，系统讲解 GitNexus 命令行工具的项目级运行器 run.cjs 机制与 analyze、status、clean、wiki、list 五个核心命令的用法、参数与适用时机，并结合 gitnexus/src/cli 目录下的命令实现源码，解释新鲜度判定、索引清理、LLM 配置等底层原理，读完后可独立完成仓库索引构建、索引状态检查、索引清理与 Wiki 文档生成。

项目本地运行器：node .gitnexus/run.cjs

GitNexus 的 CLI 命令统一通过项目本地运行器调用：

node .gitnexus/run.cjs <command>

这个 run.cjs 是 gitnexus analyze 生成索引时放在 .gitnexus/ 目录旁的"项目级运行器"（被 gitignore，不随仓库提交）。它在每次调用时自动探测当前机器上可用的运行环境，按如下优先级选择：全局安装的 gitnexus → pnpm dlx → bunx → npx。这意味着：

• 不假设任何包管理器，无需全局安装即可运行；
• 纯 bun 机器也能工作——这类机器上可能完全没有 npm、npx 或 pnpm，而运行器仍可通过 bunx 兜底；
• 文档中所有命令都是"CLI 中立"的，同一个 node .gitnexus/run.cjs 写法在不同开发者的机器上解析到各自的运行器，避免了提交文件中出现机器特定命令（源码注释中称为 per-machine churn 问题）。

这一机制在源码中可以直接印证：gitnexus/src/cli/ai-context.ts 中 generateGitNexusContent 的默认 runnerPath 即 .gitnexus/run.cjs，注释明确说明"在调用时解析可用运行器（global gitnexus → pnpm dlx → bunx → npx）"；gitnexus/src/cli/ai-context.ts 还展示了 analyze 完成后将 run.cjs 从 CLI 包内复制到 .gitnexus/ 存储目录的动作。也就是说，你仓库中 CLAUDE.md / AGENTS.md 里出现的那段 node .gitnexus/run.cjs ... 提示，正是 GitNexus 每次索引时注入的。

运行器缺失时的引导（Bootstrap）

如果你在一个全新 clone 的仓库里、或执行过 git clean 之后运行 node .gitnexus/run.cjs，会看到 Cannot find module 报错——因为运行器本身被 gitignore 掉了。此时需要在项目根目录重新生成索引：

# 常规机器
npx gitnexus analyze

# 纯 bun 机器（无 npm/npx/pnpm）
bunx gitnexus@latest analyze

针对 npm 11.x 的一个已知问题：npx 在安装阶段崩溃（报 node.target is null）时，有三种替代方案：

1. 一次性全局安装：npm i -g gitnexus，之后直接用 gitnexus analyze；
2. 改用 bun：bunx gitnexus@latest analyze；
3. 使用 pnpm 并显式允许原生依赖构建：

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

analyze — 构建或刷新索引

node .gitnexus/run.cjs analyze

必须在项目根目录运行。analyze 会解析所有源码文件、构建知识图谱、把结果写入 .gitnexus/ 目录，并顺带生成/更新 CLAUDE.md 与 AGENTS.md 中的 GitNexus 上下文区块。

核心参数

参数	作用
--force	即使索引已是最新也强制全量重建
--embeddings	启用 embedding 生成以支持语义搜索（默认关闭）
--drop-embeddings	重建时丢弃已有 embedding。默认情况下，不带 --embeddings 的 analyze 会保留索引中已存在的 embedding
--pdg	构建程序依赖层（污点分析、CDG、REACHING_DEF），供 explain 与 pdg_query 使用

何时运行 analyze

• 第一次在项目里使用时；
• 代码发生重大变更之后；
• 当 MCP 资源 gitnexus://repo/{name}/context 报告索引已过期时。

在 Claude Code 中，PostToolUse hook 会在 git commit 和 git merge 之后检测索引新鲜度并通知 Agent 运行 analyze。值得注意的是，hook 只负责通知，不自己执行 analyze——原因是 analyze 可能耗时最长约 120 秒，由 hook 同步执行会阻塞 Agent，且超时存在损坏底层图数据库的风险。

源码中的完整参数面

技能文档列出的 4 个参数是最常用的子集。从 CLI 入口 gitnexus/src/cli/index.ts 可以看到 analyze 命令的完整定义，还包括：

参数	作用
--index-only	纯索引模式：跳过 AGENTS.md、CLAUDE.md 与技能文件等一切注入
--skip-agents-md	跳过更新 AGENTS.md / CLAUDE.md 中的 gitnexus 区块
--skip-skills	跳过向 .claude/skills/、.agents/skills/ 安装标准技能文件
--branch <name>	把工作区索引固定到独立的按分支索引槽位（多分支索引）
--name <alias>	以自定义名称注册到 ~/.gitnexus/registry.json，区分基名相同的多个仓库
--workers <n>	解析 worker 池大小，默认 cores-1 且上限 16
--max-file-size <kb>	跳过超过该大小（KB）的文件，默认 512，硬上限 32768
--repair-fts	不重新分析，仅修复/重建搜索 FTS 索引
--self-commit	analyze 后自动提交 AGENTS.md / CLAUDE.md 变更（默认关闭）

其中 --pdg 在源码中的描述比文档更具体：构建"控制流图 / PDG 基底（BasicBlock 节点 + CFG 边）"，仅对支持的语言生效，属于显式开启的优化项（off by default）。而 --embeddings 还接受一个可选的 [limit] 参数覆盖 50,000 节点的安全上限，传 0 可完全取消上限。

status — 检查索引新鲜度

node .gitnexus/run.cjs status

显示当前仓库是否有 GitNexus 索引、上次更新时间，以及符号/关系数量。支持 --json 输出机器可读结果（含 schemaVersion、索引 commit、运行器身份等字段）。

从实现 gitnexus/src/cli/status.ts 可以看清"索引是否最新"（up-to-date）的完整判定条件，它比"commit 相同"更严格，需要同时满足四点：

1. 当前 HEAD commit 与索引记录的 lastCommit 一致；
2. 运行器身份（analyzer runner identity）一致——索引由哪个版本的 GitNexus 生成会被记录在元数据中，换版本后旧索引视为 stale-or-unknown；
3. 索引元数据中没有"不完整原因"（如分析中途失败）；
4. 工作区必须干净——因为 analyze 会索引包含未提交修改的工作区，所以同一个 commit 下只要 git status 有未提交变更，索引同样判定为过期。

此外，status 在多分支索引场景下会优先报告与当前 checkout 分支匹配的分支索引；若分支索引缺失，会标注 workspace 索引滞后于当前分支（gitnexus/src/cli/status.ts）。

clean — 删除索引

node .gitnexus/run.cjs clean

删除当前仓库的 .gitnexus/ 目录，并把它从全局注册表（~/.gitnexus/registry.json）中注销。典型使用场景：索引损坏需要重建之前，或彻底把 GitNexus 移出某个项目之后。

参数	作用
--force	跳过确认提示（默认会先展示将要删除的路径并要求确认）
--all	清理所有已注册仓库的索引，而非仅当前仓库

实现 gitnexus/src/cli/clean.ts 中有几个值得注意的安全设计：

• 两段式确认：不带 --force 时，clean（包括 --all）只打印待删清单并提示追加 --force，不实际删除磁盘内容；
• 防投毒路径校验：--all 会遍历 ~/.gitnexus/registry.json 中所有条目，而该文件用户可写，损坏或被手工编辑的条目可能把 storagePath 指向仓库根目录甚至空字符串。源码在删除前对每条记录调用 assertSafeStoragePath 校验，非法条目直接跳过并继续处理其余条目（gitnexus/src/cli/clean.ts）；
• 源码中还提供文档未展开的 --branch <name>（只删除指定分支索引，且强校验目标必须位于 .gitnexus/branches/ 之下）与 --lbug-sidecars（清理图数据库的隔离恢复旁路文件）两个运维参数。

wiki — 基于知识图谱生成仓库文档

node .gitnexus/run.cjs wiki

wiki 命令从知识图谱出发，调用 LLM 生成仓库级文档。首次使用需要 API key，会保存到 ~/.gitnexus/config.json。

参数	作用
--force	即使已是最新也强制完整重新生成
--model <model>	指定 LLM 模型（默认：MiniMax-M3）
--base-url <url>	LLM API base URL
--api-key <key>	LLM API key
--concurrency <n>	并行 LLM 调用数（默认：3）
--gist	生成后发布为公开 GitHub Gist

源码 gitnexus/src/cli/index.ts 显示该命令的参数面比技能文档更全：--provider <provider> 支持 minimax、openai、openrouter、azure、custom、cursor、claude、codex、opencode 八种（默认 minimax），另有 --timeout（默认不限时）、--retries（默认 3 次）、--review（在分组完成后暂停，人工确认模块结构再生成页面）、--lang <lang>（指定输出文档语言，如 english、chinese）、--allow-insecure-connection（放行指定主机的 http:// LLM 地址）等。API key 的解析优先级在 gitnexus/src/core/wiki/llm-client.ts 中定义为：CLI 参数 > 环境变量（MINIMAX_API_KEY / GITNEXUS_API_KEY / OPENAI_API_KEY）> ~/.gitnexus/config.json 已保存配置，默认模型 ID 列表（MiniMax-M3、MiniMax-M2.7）也在该文件 MINIMAX_MODEL_IDS 中定义。

list — 列出所有已索引仓库

node .gitnexus/run.cjs list

列出注册在 ~/.gitnexus/registry.json 中的全部仓库。MCP 侧的 list_repos 工具提供相同信息，供 Agent 查询。

从 gitnexus/src/cli/list.ts 的实现看，输出比"仓库名列表"更丰富：每个条目展示路径、索引时间、索引时的 commit（短哈希）、文件/符号/关系统计、社区数与执行流数；同名仓库（基名冲突）会自动附加路径后缀以区分；配置过 --branch 多分支索引的仓库还会逐行列出各分支索引的 commit 与时间。

索引完成后的验证步骤

完成 analyze 后，按以下顺序确认：

1. 读取 MCP 资源 gitnexus://repo/{name}/context，验证索引已加载且不过期；
2. 结合任务选用其他 GitNexus 技能（exploring、debugging、impact-analysis、refactoring）——这些技能文件随 analyze 一并安装到 .claude/skills/ 下，AGENTS.md / CLAUDE.md 中的技能表会指明每个任务应读取哪个技能文件（对应 gitnexus/src/cli/ai-context.ts 中生成的技能表逻辑）。

常见问题排查

症状	原因与处理
"Not inside a git repository"	必须在 git 仓库内的目录运行；status 源码同样以 isGitRepo(cwd) 作为第一道检查（gitnexus/src/cli/status.ts）
重新分析后索引仍显示过期	重启 Claude Code 以重新加载 MCP 服务器——旧进程持有的图数据库连接不会感知磁盘上的新索引
Embedding 生成太慢	省略 --embeddings（默认本来就关闭）；或设置 OPENAI_API_KEY 走 API 端 embedding 替代本地推理提速
node .gitnexus/run.cjs 报 Cannot find module	运行器缺失（新 clone / git clean 后），按前文 Bootstrap 一节用 npx / bunx / pnpm dlx 重新生成

小结

GitNexus 的 CLI 围绕一条主线设计：analyze 生产 .gitnexus/ 索引并顺带维护 Agent 上下文文件，status 用"commit + 运行器身份 + 不完整原因 + 工作区脏检查"四重条件回答索引是否可信，list 提供全局注册表视角，wiki 把图谱转化为 LLM 生成的文档，clean 负责安全地拆除这一切。而 node .gitnexus/run.cjs 这一层运行器把"如何在不同包管理器环境启动 CLI"的问题收敛为一个统一的、可写入提交文档的命令形式，是让同一份项目文档在所有开发者机器上都能直接复制运行的关键设计。