gitnexus-guide

GitNexus 指南

GitNexus MCP 工具、资源和知识图谱架构的快速参考。

始终从这里开始

对于涉及代码理解、调试、影响分析或重构的任何任务：

1. 绑定一次仓库——使用已确认的注册表名称/路径或已配置的默认值；如果不确定，请调用 list_repos。读取工具提供的 staleness；需要概览时使用 gitnexus://repo/{name}/context。
2. 将任务与下方的某项技能匹配，并阅读该技能文件
3. 遵循技能的工作流和检查清单

如果第 1 步提示索引已过期，请先在终端中运行 node .gitnexus/run.cjs analyze。 在使用 query / context / impact / cypher 的结果前，读取 staleness.status 和 staleness.branch/lastCommit。仅当状态为 behind 或 diverged 时才重新分析。

技能

任务	要阅读的技能
理解架构 /“X 是如何工作的？”	gitnexus-exploring
影响范围 /“如果我更改 X，哪些内容会出问题？”	gitnexus-impact-analysis
追踪 Bug /“X 为什么失败？”	gitnexus-debugging
重命名 / 提取 / 拆分 / 重构	gitnexus-refactoring
工具、资源、架构参考	gitnexus-guide（本文档）
索引、状态、清理、wiki CLI 命令	gitnexus-cli

工具参考

工具	提供的内容
query	按处理组整理的代码智能信息——与某个概念相关的执行流
context	符号的全方位视图——分类引用及其参与的流程
impact	符号的影响范围——深度为 1/2/3 时可能造成的影响及置信度
trace	两个符号之间的最短路径——一次调用即可回答“ A 如何到达 B？”
detect_changes	Git 差异影响——当前更改会影响哪些内容
rename	语义重命名：默认预览（省略 dry_run 或设为 true）；设置 dry_run: false 并提供预览返回的 plan_token 即可应用；检查应用状态和失败项
cypher	原始图查询（请先读取 gitnexus://repo/{name}/schema）
explain	已持久化的污点分析结果——源→汇的数据流（需要 analyze --pdg）
pdg_query	控制/数据依赖——是什么控制了 X（CDG）/Y 的流向（REACHING_DEF）；需要 analyze --pdg
check	检查图不变量，例如循环导入
route_map	API 路由图——哪些组件/钩子会请求哪些端点，以及提供这些端点的处理程序文件
shape_check	响应结构漂移——各路由返回的键与其调用方访问的键；发现不匹配时标记 MISMATCH
api_impact	API 路由变更前报告——调用方、中间件、结构不匹配、风险等级
tool_map	MCP/RPC 工具定义及其处理程序所在的文件
group_list	列出已配置的多仓库组，或某个组的配置
group_sync	重建组的 Contract Registry（跨仓库 HTTP 契约链接）；在 group.yaml 更改或成员重新编制索引后运行
list_repos	发现已编制索引的仓库（分页——limit/offset）

选择有针对性的响应

请使用已连接服务的架构；较旧的服务可能不会公布新的筛选器。以下选项均为显式设置：省略它们会保留现有输出。对于臃肿的响应，请使用筛选器排除不需要的部分；对于本已很小的响应，省略信息的开销可能超过节省的字节数。

问题	选项
哪些符号实现了此功能？	query：limit: 3、max_symbols: 3、include_content: false、chain_depth: 0、response_sections: ["process_symbols", "definitions"]
哪些执行流符合条件？	query：在 response_sections 中保留 processes；将其 id 与 process_symbols[].process_id 关联
谁调用了这个确切的符号？	context：uid、response_sections: ["incoming"]、relationTypes: ["CALLS"]
它调用了什么，并附带源代码？	context：uid、include_content: true、response_sections: ["outgoing"]、relationTypes: ["CALLS"]
影响摘要是什么？	impact：direction: "upstream"、summaryOnly: true；保留风险计算和总数
哪些受影响的符号需要检查？	impact：limit: 10、offset: 0；按响应指示分页
A 如何到达 B？	trace：from_uid、to_uid

response_sections 用于选择单个仓库 MCP query 或 context 的数据部分（不适用于 @group 路由）。query 可选项：processes、process_symbols、definitions。context 可选项：incoming、outgoing、processes、chain、routes、typed_properties；所选符号始终保留。context 的 relationTypes 接受其架构公布的大写关系名称，并且只筛选现有的 incoming/outgoing 类别。它不会改变排序、遍历、源代码保留或受限的候选项/引用窗口。

筛选器会添加 response_filter，其中包含所选内容以及省略的字段/类别。警告、歧义、过时状态和完整性元数据始终保留。筛选后的视图为空，并不能证明内容不存在。省略筛选器即可展开内容；即使某个所选类别为空，也绝不能跳过影响检查。maxTokens 是字节截断值，不是分页参数：它可能会截断 JSON。优先使用这些筛选器、较小的结果数量，以及针对所选符号展开源代码/调用链，而不是获取大型搜索结果。证据足以回答问题后就停止；不要默认运行每个工具。

对 list_repos 分页

list_repos 采用分页，以避免大型注册表被 MCP/LLM 令牌限制截断。它接受可选参数 limit（默认值为 50，最大值为 200）和 offset，并返回：

{
  "repositories": [
    { "name": "...", "path": "...", "indexedAt": "...", "lastCommit": "...", "stats": { } }
  ],
  "pagination": {
    "total": 437,
    "limit": 50,
    "offset": 0,
    "returned": 50,
    "hasMore": true,
    "nextOffset": 50
  }
}

要枚举所有仓库，请持续调用，并将 offset 设置为 pagination.nextOffset，直到 hasMore 为 false：

list_repos {}               → repos 1–50,    nextOffset 50,  hasMore true
list_repos { offset: 50 }   → repos 51–100,  nextOffset 100, hasMore true
…
list_repos { offset: 400 }  → repos 401–437,                 hasMore false   (done)

注意：当 offset ≥ total 时，会返回空页（但仍会报告 total）。超出范围或格式错误的 limit/offset（非整数、limit 不在 [1, 200] 范围内、offset < 0）会被拒绝，并给出明确错误；超过最大值的 limit 会被拒绝，不会静默限制到最大值。排序顺序是确定的（名称转为小写后排序，再按路径排序），因此只要注册表未发生变化，分页就不会跳过或重复条目。

内联陈旧状态信号（query / context / impact / cypher）

这 4 个常用只读工具都会在每个响应中附加一个非阻塞的 staleness 字段，格式为 { status, branch?, lastCommit, indexedAt, measuredAgainst, commitsBehind?, hint? }。它同时回答两个不同的问题：哪个索引提供了答案，以及索引有多新。即使一切正常，也会包含这个字段，正是因为它能标识索引——否则，基于固定分支索引计算出的答案与基于默认分支索引计算出的答案无法区分（#3291）：

{ /* …the tool's normal result… */
  "staleness": {
    "status": "current",
    "branch": "feature/checkout-v2",
    "lastCommit": "4f2a1c9e8b7d6a5c4e3f2a1b0c9d8e7f6a5b4c3d",
    "indexedAt": "2026-09-15T07:12:00.000Z",
    "measuredAgainst": "HEAD"
  }
}

这里的 status: "current" 表示该索引与构建它所用克隆库的 HEAD 一致，而不是与默认分支一致。measuredAgainst 指明 commitsBehind 是相对于什么计算的：该克隆库当前检出的 HEAD，而非远程仓库。branch 是该索引所代表的分支；如果 HEAD 处于分离状态、文件夹不是 git 仓库，或旧版索引未记录分支，则不会包含此字段。因此，需要始终存在的标识符时，请读取 lastCommit。

当索引落后于该 HEAD 时，响应会附带落后提交数和提示：

{ /* …the tool's normal result… */
  "staleness": {
    "status": "behind", "commitsBehind": 3, "branch": "main",
    "lastCommit": "a0c945022d06b8815f93ffd8838df9ed5c08cbc0",
    "indexedAt": "2026-09-04T20:45:47.481Z", "measuredAgainst": "HEAD",
    "hint": "⚠️ Index is 3 commits behind HEAD. Run analyze tool to update."
  }
}

只有 git 能计算出差距时才会包含 commitsBehind。如果 git 无法计算差距，但 HEAD 仍解析为不同于索引所用提交的另一个提交——通常是因为索引所用的提交已不在克隆库的历史记录中——那么可以确定索引未与 HEAD 一致，但无法计算落后数，因此不会报告数字：

{ /* …the tool's normal result… */
  "staleness": {
    "status": "diverged", "branch": "main",
    "lastCommit": "a0c945022d06b8815f93ffd8838df9ed5c08cbc0",
    "indexedAt": "2026-09-04T20:45:47.481Z", "measuredAgainst": "HEAD",
    "hint": "⚠️ Index is not at HEAD and the commit gap could not be counted — the recorded commit may no longer be in this clone's history. Run analyze tool to update."
  }
}

因此：使用 commitsBehind 前，先读取 status；假定答案所描述的引用前，先读取 branch / lastCommit。status: "unknown" 表示无法执行新鲜度检查（--skip-git 文件夹没有可供衡量的历史记录）——仍会报告引用，因为即使无法判断新鲜度，也能确定哪个索引提供了答案。此字段只会添加到对象结果中——原始数组形式的 cypher 输出和错误封装均保持不变。以 @group 为目标的调用不会携带此字段（多仓库的陈旧状态定义不明确）。只有 behind 或 diverged 才需要重新运行 analyze——这两种状态表示索引未与此克隆库的 HEAD 一致。unknown 表示无法衡量，而非陈旧；除非存在 git 历史记录，否则 analyze 无法使其变为 current。

list_repos 和 HTTP 仓库路由保持不变：对于当前索引，它们完全不包含 staleness，而是通过各自顶层的 branch / lastCommit / indexedAt 字段报告引用。

污染分析结果（explain）

explain 会返回由 gitnexus analyze --pdg 记录的污染分析结果——过程内的 TAINTED 边，以及当过程间污染分析阶段发现函数级来源→汇点链时产生的跨函数 TAINT_PATH 跳转。每条结果都包含汇点类别（command-injection、code-injection、path-traversal、sql-injection、xss）、来源行和汇点行，以及按顺序排列的跳转路径，并标明每次跳转所传递的变量。

• explain {} — 枚举仓库中的所有结果（受 limit 限制，顺序确定）
• explain { target: "src/vuln.ts" } — 文件中的结果（接受后缀路径匹配）
• explain { target: "runUserCommand" } — 函数中的结果（按 context 的方式解析；名称有歧义时返回按排名排序的候选项）

未使用 --pdg 建立索引的仓库会返回明确的“无污染层”提示。注意：闭包/回调、属性/字段和隐式流均未建模；过程间结果是函数级的 TAINT_PATH 跳转，而非语句级路径证明，因此没有发现结果并不能证明安全。可通过 cypher 查询 SANITIZES（清理器消除污染）边。

控制与数据依赖（pdg_query）

pdg_query 读取 gitnexus analyze --pdg 记录的控制／数据依赖层（CDG + REACHING_DEF，粒度为基本块），是 explain 的控制／数据类比工具。它始终需要锚点（文件路径或符号 target，解析方式与 context 相同），并有两种模式：

• pdg_query { mode: "controls", target: "..." } — CDG：“X 在什么条件下运行？”每条边表示一个控制谓词块 → 依赖块，并在 reason 中标明分支方向（'T'／'F'）；指向提前 return／throw 的边会标记为 guard: true（用于发现守卫子句——方向取决于谓词，因此不要按固定标签筛选守卫）。
• pdg_query { mode: "flows", target: "...", variable?: "..." } — 函数内的 REACHING_DEF 定义→使用边；传入 variable 可追踪单个绑定。

未使用 --pdg 建立索引的代码库会返回“无 PDG 层”提示（若无法确认该层，则返回“状态未知”）。仅限过程内分析——跨函数数据流属于污点分析（explain）的范畴。也可以通过 cypher 查询原始 CDG／REACHING_DEF 边。完整查询范围请参阅 gitnexus-pdg-query 技能。

两个符号之间的最短路径（trace）

trace 只需一次调用即可回答“A 如何到达 B？”——它会搜索 CALLS 上的最短有向路径（以及 HAS_METHOD，因此以类为根的追踪会深入其方法），而无需手动串联 3–8 次 context／impact 调用。

• trace { from: "validateUser", to: "executeQuery" } — 两个符号之间的最短路径。
• 使用 from_uid／to_uid（无歧义）或 from_file／to_file 消除常见名称的歧义；若名称存在歧义，则会返回按相关度排序的候选项。
• maxDepth（默认值为 10，最大值为 30）限制搜索范围；includeTests（默认值为 false）允许遍历经过测试文件中的符号。

结果包含有序的 hops（每项为 { name, filePath, startLine }）以及与之对应的 edges[]（{ relType, confidence }），因此可以区分调用跳转和包含关系（HAS_METHOD）跳转。若不存在路径，结果会报告可到达的最远节点（即链路中断处）；若先达到遍历上限，则会设置 truncated: true。每个结果都包含一个 status：ok／no_path／ambiguous／not_found／error。

跨代码库（实验性）：传入 repo: "@groupName"，即可跨组内成员代码库进行追踪——路径可能跨越一个 ContractLink 边界（该边界会作为 CONTRACT_LINK 跳转报告，桥接的契约会列在 crossings[] 中）。完全省略 to，即可追踪 from 发出的 HTTP 调用，并查看其最终到达的提供方端点。可通过 group_list／group_sync 配置组。

资源参考

用于导航的轻量级读取（约 100–500 个令牌）：

资源	内容
gitnexus://repo/{name}/context	统计信息、过期检查
gitnexus://repo/{name}/clusters	所有功能区域及其内聚度分数
gitnexus://repo/{name}/cluster/{clusterName}	区域成员
gitnexus://repo/{name}/processes	所有执行流
gitnexus://repo/{name}/process/{processName}	逐步追踪
gitnexus://repo/{name}/schema	Cypher 图架构

图谱架构

节点： File、Folder、Function、Class、Interface、Method、CodeElement、Community、Process、Route、Tool，以及特定语言的类型（Struct、Enum、Trait、Impl、Namespace、Module、……）和 BasicBlock（仅 --pdg 索引）。完整节点列表位于 gitnexus://repo/{name}/schema。 边（通过 CodeRelation.type）： CALLS、IMPORTS、EXTENDS、IMPLEMENTS、DEFINES、CONTAINS、MEMBER_OF、HAS_METHOD、HAS_PROPERTY、ACCESSES、METHOD_OVERRIDES、METHOD_IMPLEMENTS、STEP_IN_PROCESS、HANDLES_ROUTE、FETCHES、HANDLES_TOOL、ENTRY_POINT_OF、WRAPS、QUERIES、INJECTS，以及仅供 --pdg 使用的类型（CFG、REACHING_DEF、TAINTED、SANITIZES、TAINT_PATH、CDG——默认索引中没有记录）。

编写 Cypher 前，请先读取 gitnexus://repo/{name}/schema；它是已索引仓库的权威架构。

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
RETURN caller.name, caller.filePath