gitnexus-guide

GitNexus 指南

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

始终从这里开始

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

1. 读取 gitnexus://repo/{name}/context — 了解代码库概况并检查索引是否为最新
2. 将任务与下方某项技能匹配，并读取对应的技能文件
3. 按照技能中的工作流程和检查清单操作

如果第 1 步提示索引已过期，请先在终端运行 node .gitnexus/run.cjs analyze。

技能

任务	要读取的技能
理解架构 /“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	跨多个文件协调重命名，并为编辑标注置信度
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）

对 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 会被拒绝，不会静默截断。结果顺序是确定的（名称转为小写后排序，再按路径排序），因此在注册表未变化时，分页不会跳过或重复条目。

污点发现（explain）

explain 返回由 gitnexus analyze --pdg 记录的污点发现——包括过程内的 TAINTED 边，以及跨函数的 TAINT_PATH 跳转（当过程间污点阶段发现函数级的 source→sink 链时）。每条发现包含 sink 类别（命令注入、代码注入、路径穿越、SQL 注入、XSS）、source/sink 行号，以及有序的跳转路径，并标注每一跳携带的变量。

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

未使用 --pdg 索引的仓库会返回明确的 "no taint layer" 提示。注意事项：闭包/回调、属性/字段以及隐式流均未建模，过程间发现是函数级的 TAINT_PATH 跳转，而非语句级的路径证明，因此未发现污点并不代表安全。SANITIZES（sanitizer-kill）边可通过 cypher 查询。

控制与数据依赖（pdg_query）

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

• pdg_query { mode: "controls", target: "..." } — CDG："X 在什么条件下运行？"。每条边是一个控制谓词块 → 依赖块，分支方向（'T'/'F'）记录在 reason 中；指向早期 return/throw 的边会标记 guard: true（守卫子句发现——方向取决于谓词，因此不要用固定标签过滤守卫）。
• pdg_query { mode: "flows", target: "...", variable?: "..." } — 函数内的 REACHING_DEF def→use 边；传入 variable 可追踪单个绑定。

未使用 --pdg 索引的仓库会返回 "no PDG layer" 提示（当该层无法确认时返回 "status unknown"）。仅限过程内——跨函数流属于污点的范畴（explain）。原始 CDG/REACHING_DEF 边也可通过 cypher 查询。完整查询接口参见 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 个 token），用于导航：

资源	内容
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