gitnexus-exploring

使用 GitNexus 探索代码库

适用场景

• “身份验证是如何工作的？”
• “项目结构是什么样的？”
• “展示主要组件”
• “数据库逻辑在哪里？”
• 理解之前未接触过的代码

先绑定代码库

每个会话绑定一次，使用已确认的注册名称/路径或已配置的 MCP 默认值；之后重复使用。仅当尚不清楚目标代码库时才调用 list_repos {}，不要在每个问题之前都调用。切勿根据检出目录猜测注册名称。只有一个已索引代码库时，按下方示例原样使用。有多个代码库时，每次调用都要传入 repo：通常省略 repo 会报错， 但如果 MCP 策略配置了默认值，则会静默解析为该默认值。如果无法判断指的是哪个代码库，请停止并询问。说明时同时报告 已绑定的代码库和索引新鲜度。

list_repos 会分页；请使用 offset: pagination.nextOffset 翻页，直到 hasMore 为 false，再判断某个代码库是否不存在。

工作流

1. Bind the repository once; use hot-tool staleness on subsequent calls
2. If no symbol is known: query({search_query: "<concept>", limit: 3, max_symbols: 3})
3. context({uid: "<returned id>"})                → Inspect the selected symbol
4. Read a process resource only when its full trace answers an unresolved question

如果索引已过时 → 在终端运行 node .gitnexus/run.cjs analyze。 热工具 staleness 会标明哪个索引提供了回答（branch/lastCommit）以及新鲜程度（status）。仅当状态为 behind 或 diverged 时才重新分析——current 表示身份一致，unknown 表示无法测量。

仅请求所需的证据

使用已连接服务端公布的选项。response_sections 和上下文 relationTypes 是针对单个代码库的可选视图，不用于 @group 路由。 在较旧的服务端上，请改用现有的限制参数和内容/调用链选项。 不需要的部分内容过多时可使用过滤器；其省略元数据可能会让 原本较小的响应略微变大。 绑定代码库后，尽量只进行 2–3 次有针对性的调用；回答问题后就停止，但如果证据或必要的安全检查仍不完整，则继续扩展。

query({search_query: "payment retry", repo: "my-app", limit: 3, max_symbols: 3,
       include_content: false, chain_depth: 0,
       response_sections: ["process_symbols", "definitions"]})
context({uid: "<id from query>", repo: "my-app", include_content: true,
         response_sections: ["incoming", "outgoing"], relationTypes: ["CALLS"]})
// Before editing, assess impact using the normal traversal and risk calculation:
impact({target: "<same id>", repo: "my-app", direction: "upstream", summaryOnly: true})

如果已知符号，先从 context 开始；使用 uid，或使用 name 加上 file_path/kind，以避免结果不明确。如果只想回答“谁调用了它？”， 请求 response_sections: ["incoming"]、relationTypes: ["CALLS"]，并将 include_content 设为 false。如果问题涉及流程，请在查询中保留 processes，而不是请求仅包含符号的视图。

不要对每个搜索命中都请求源代码和多跳调用链。仅获取所选符号的源代码；对于较大的类/文件，如果工具可用，优先使用带有较小 0 起始 startLine/endLine 窗口的 read_file（图中的行号需减 1）， 或使用 maxLines 读取整个文件。对于已知的 A→B 路径，使用 trace，而不是反复扩展 context。

过滤器会保留所请求的部分/类别并隐藏其他内容；它们不能证明其他引用不存在，也不能使现有的有界搜索变得完整。请查看 response_filter、warning、partial、truncated、epistemic 和 staleness。需要更广泛的证据时，请移除过滤器。maxTokens 是最后手段，用于截断字节数，可能会截断 JSON：请缩小请求范围，不要把被截断的响应当作完整结果。绝不要使用经过过滤的调用者视图来跳过必要的影响检查或忽略 UNKNOWN 风险。

检查清单

- [ ] Once per session: bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Check hot-tool staleness; read the overview only if needed
- [ ] Query for the concept only if the relevant symbol is not already known
- [ ] Review returned symbols; include processes when execution flow matters
- [ ] context on selected symbols; request only relevant sections/relations
- [ ] Read a process resource only if its full trace is needed
- [ ] Read targeted source only when implementation details are needed
- [ ] State the repository and index freshness with the explanation

资源

资源	内容
gitnexus://repo/{name}/context	统计信息、过时警告（约 150 个 token）
gitnexus://repo/{name}/clusters	所有功能区域及其内聚度评分（约 300 个 token）
gitnexus://repo/{name}/cluster/{name}	区域成员及文件路径（约 500 个 token）
gitnexus://repo/{name}/process/{name}	分步骤执行跟踪（约 200 个 token）

工具

query — 查找与某个概念相关的执行流程：

query({search_query: "payment processing", repo: "my-app"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations

context — 查看某个符号的全方位信息：

context({name: "validateUser", repo: "my-app"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)

索引了多个代码库后，必须指定 repo；只有一个代码库时可以省略。

示例：“支付处理是如何工作的？”

在已绑定 my-app 且索引为最新的情况下：

1. query({search_query: "payment processing", repo: "my-app", limit: 3, max_symbols: 3})
   → CheckoutFlow and RefundFlow, with symbol IDs and locations
2. context({uid: "<processPayment id>", repo: "my-app", include_content: true,
            response_sections: ["outgoing", "processes"]})
   → Selected source, callees, process participation and completeness diagnostics
3. Answer from that evidence; read one process resource only if its trace is still needed

在说明中报告代码库和索引的新鲜度。如果尚未绑定 my-app，请先使用 list_repos 发现一次。